# scene 模块开发工作日志

日期：2026-07-19
模块：scene（W-02 场景管理）
任务：new_dev（新开发），迭代「元景项目-初始迭代」

## 范围 / 背景
按 design 交付 modules/scene.md 与 design/scene.md 实现 W-02 场景管理：
- scene.scene / scene_import 表 CRUD、列表查询（分页 {list,total}）
- 场景导入（api/scene_import.dspy 文件导入）
- scene.world_id → world.id 逻辑关联（codes 段，不加外键）
- 导入事务批量 + 失败回滚无脏数据
- REST 统一前缀 /api/*，错误结构 {code,message,field,detail}
- 非法输入 100% 拦截不落库

## 交付清单
| 文件 | 说明 |
|---|---|
| models/scene.json | scene 表定义（id PK、idx_scene_code 唯一、idx_scene_world；codes 段 world/appcodes） |
| models/scene_import.json | scene_import 表定义（只读导入记录） |
| json/scene.json | scene CRUD 定义（editable 顶部 new/update/delete_data_url → 自定义 api/*.dspy） |
| json/scene_import.json | scene_import 只读列表定义 |
| init/data.json | appcodes 种子：scene_type / scene_status / import_status |
| scene/init.py | 全部业务函数：list/get/create/update/delete/import_scenes/parse_scene_file/下拉 |
| scene/__init__.py | 包导出（与 init.py、load_scene 三处同步注册） |
| wwwroot/api/*.dspy | 9 个 REST 接口（/scene/api/*.dspy） |
| wwwroot/index.ui | 场景管理入口（列表/导入/导入记录三卡片） |
| wwwroot/import_page.ui | 导入页（Form：world_id + file） |
| scripts/load_path.py | RBAC 显式路径注册（无通配符） |
| pyproject.toml / README.md / .gitignore / skill/SKILL.md | 工程化配套 |

## 关键技术决策
1. **world_id 逻辑关联**：models codes 段声明 world_id→world(id/name) 渲染下拉，不加物理外键；create/update/import 在 Python 层显式校验 world 存在（`_world_exists`），非法 world_id 100% 拦截。
2. **导入事务回滚**：import_scenes 先对全部行做字段校验（name/code/world_id 必填、长度上限、文件内 code 去重），再在一个 `async with sqlorContext` 内逐条 sor.C；任一条异常 → 整个 context 回滚，仅写一条 status=2 的 scene_import 失败记录。无脏数据。
3. **分页 {list,total}**：用 `sor.sqlPaging(sql, {page, rows, ...})`，支持白名单 sort/order（防注入），rows 上限 200。
4. **错误结构统一**：`{code, message, field, detail}`；code 枚举见 SKILL.md。
5. **REST 统一前缀**：所有接口放 wwwroot/api/*.dspy，宿主挂载后路径为 `/scene/api/*.dspy`；返回 `{status:'ok'|'error', data}`。
6. **三处同步注册**：scene/__init__.py 导出 ← scene/init.py 实现 ← load_scene() env.xxx=xxx；.dspy 无 import 直接调用全局函数。

## 验证情况（环境受限）
- 本工作空间无运行时环境（无 MySQL/ahserver/宿主应用），无法启动服务 curl 实测。
- 已做静态自检：模型 JSON 四段式（summary/fields/indexes/codes）；CRUD JSON 有 tblname + params.editable + 顶部 new/update/delete_data_url；dspy 无 import/print/uuid，均显式 return；init.py 用 sor.C/U/R/D/sqlPaging 标准 API（无编造 save/list/insert）；未硬编码 DBNAME（全部 get_module_dbname）。
- 待部署环境验证项：`pip install .`、json2ddl 建表、xls2ui 生成 CRUD UI、RBAC 注册、curl 各 /scene/api/*.dspy。

## 当前状态
- 模块仓库 modules/scene/，未提交（交付后由 PM 审核通过统一 git 提交）。