# entity 模块工作日志（W-03 实体管理）

- 日期：2026-07-19（元景项目-初始迭代）
- 范围：W-03 实体管理功能点——entity.entity / entity_import 表 CRUD、列表查询、实体文件导入；scene_id→scene.id 逻辑关联（codes 段）；entity_type 字典幂等落库；导入事务批量+失败回滚；REST 统一前缀 /api/*；错误结构 {code,message,field,detail}；分页 {list,total}；非法输入 100% 拦截。

## 交付内容

- `modules/entity/entity/init.py` + `entity/__init__.py`：后端全部 async 函数（create/update/delete/get/list/import/guard/reject）与 `load_entity()` 注册。
- `modules/entity/models/`：entity / entity_import / entity_import_log 三张表定义（四段式 summary/fields/indexes/codes）。
- `modules/entity/json/`：entity / entity_import 两个 CRUD 定义。
- `modules/entity/wwwroot/`：index.ui（入口导航）、import_page.ui（导入页）、api/*.dspy（11 个接口）、i18n/zh-CN.json + en-US.json。
- `modules/entity/init/data.json`：entity_type / common_status / import_status 三组字典（Format B appcodes 幂等落库）。
- `modules/entity/scripts/load_path.py`：RBAC 显式路径注册（无通配符）。
- `modules/entity/skill/SKILL.md`：模块技能文档。
- `modules/entity/docs/i18n.md`：i18n 提取说明。

## 关键决策

1. **包目录双层结构**：`modules/entity/entity/`（Python 包），根 `__init__.py` 仅为仓库标记。符合「包目录=模块名」规范。
2. **导入两阶段**：先全量校验（只读，不写任何数据）→ 再批量插入（同批 import_id 标记）；插入异常按 import_id 补偿 DELETE 回滚，保证失败无脏数据。校验失败只写失败批次 + 逐行日志。
3. **entity_import 只读**：批次/明细表系统生成，new/update/delete 指向 `entity_import_reject.dspy` 统一拒绝。
4. **逻辑关联不加外键**：scene_id/world_id 在 models/entity.json codes 段声明（table=scene/world），不建物理外键。
5. **非法输入 100% 拦截**：编码必填/唯一/长度、类型字典白名单、状态白名单、场景/世界存在性均在校验层拦截，不落库。
6. **i18n**：全部新文案提取到 wwwroot/i18n/{zh-CN,en-US}.json，key 前缀 `entity.`，错误码 `entity.code.*` 对应后端 {code,...}。

## 验证情况

- 环境受限（本地无 Sage/数据库服务），无法起服务做端到端 curl。已做静态验证（见交付说明中 py_compile 与禁项审计输出）。
- 部署后需在宿主应用：`load_entity()` 挂载、`get_module_dbname('entity')` 注册、执行 scripts/load_path.py 注册 RBAC、build.sh 链接 wwwroot 并生成 CRUD 页面、init/data.json 落库字典。

## 当前状态

- 分支/提交：见 git 本地提交记录（交付说明）。
- 遗留：运行期集成验证由 deploy_test 在测试环境执行。