scene/README.md

scene 模块

场景管理（W-02）：场景表 CRUD、列表查询、场景文件导入（JSON/JSON Lines/CSV）。

功能

• scene 表 CRUD（list/get/create/update/delete），分页 {list, total}
• scene_import 表只读列表（导入记录）
• 场景导入 api/scene_import.dspy：world_id + file → 解析 → 事务批量落库 → 写导入记录
• 枚举字段 appcodes 字典（scene_type / scene_status / import_status）
• 世界下拉（依赖 world 模块，world_id 逻辑关联，不加物理外键）

数据表

• scene：id(str32 PK)、world_id(str32→world.id 逻辑关联)、name(255)、code(64 唯一)、 description(text)、scene_type(16)、status(16)、config_json(text)、created_at、updated_at
• scene_import：id(str32 PK)、world_id、file_name(255)、total/success/fail(int)、status(16)、created_at

接口（REST 统一前缀 /api/，宿主应用挂载后路径为 /scene/api/.dspy）

• GET/POST list_scenes.dspy → {status, data:{list, total}}（支持 page/rows/sort/order/world_id/name/code/scene_type/status 过滤）
• GET get_scene.dspy?id= → 单条
• POST create_scene.dspy / scene_update.dspy / scene_delete.dspy
• POST scene_import.dspy（multipart: world_id + file）→ {status, data:{success,total,success_count,fail}}
• GET get_search_world_id.dspy / get_search_scene_type.dspy / get_search_status.dspy → [{value,text}]

错误结构（统一）

{code, message, field, detail}，code 取值：PARAM_REQUIRED / FIELD_REQUIRED / FIELD_TOO_LONG / WORLD_NOT_FOUND / DUPLICATE_CODE / PARSE_ERROR / DB_ERROR / NOT_FOUND。

集成

宿主应用入口 init() 调用 load_scene()（from scene.init import load_scene）。 库名统一 ServerEnv().get_module_dbname("scene")，world 表用 get_module_dbname("world")，禁止硬编码。

开发顺序

2（依赖 world）。