entity/README.md

entity 实体管理模块（W-03）

实体管理模块：管理元景项目的实体（entity）数据，提供实体表 CRUD、分页列表查询与实体文件导入。

功能

• 实体表 CRUD：entity 表新增/编辑/删除/详情/分页列表（{list, total}）。
• 列表查询：按关键字、实体类型、状态、场景过滤，分页返回 {list, total, page, rows}。
• 实体导入：api/entity_import.dspy 文件导入（CSV 首行表头 / JSON 数组），两阶段处理：
  1. 全量校验（编码必填/唯一、类型/状态字典白名单、场景/世界存在性）——任一行非法整批拦截，不落库；
  2. 批量插入（同批以 import_id 标记），插入异常按 import_id 补偿回滚，保证无脏数据。
• 导入记录：entity_import（批次）+ entity_import_log（逐行明细）系统生成，只读，禁止手工增删改。
• 编码字典：entity_type（实体类型）、common_status（通用状态）、import_status（导入状态）经 init/data.json 幂等落库到 appcodes/appcodes_kv。

数据表

表	说明
entity	实体表（entity_code 唯一，entity_type 字典，scene_id/world_id 逻辑关联 codes 段，不加外键）
entity_import	实体导入批次记录（import_no 唯一，status 字典）
entity_import_log	实体导入逐行明细日志（import_id 关联批次）

接口约定

• REST 统一前缀 /api/*：/entity/api/entity_list.dspy、entity_create.dspy、entity_update.dspy、entity_delete.dspy、entity_get.dspy、entity_import.dspy、entity_import_guard.dspy、entity_import_list.dspy。
• 错误结构统一：{code, message, field, detail}；分页结构统一：{list, total}。
• 非法输入 100% 拦截，不落库。

集成

通过 load_entity() 挂载到宿主应用（app/{应用名}.py 的 init() 中调用并注册 get_module_dbname('entity')），库名禁止硬编码。前端页面：wwwroot/index.ui（入口导航）、wwwroot/import_page.ui（导入页）。

目录结构

modules/entity/
├── entity/            # Python 包（entity/__init__.py + entity/init.py）
├── wwwroot/           # index.ui / import_page.ui / api/*.dspy / i18n/
├── models/            # entity / entity_import / entity_import_log 表定义
├── json/              # entity / entity_import CRUD 定义
├── init/data.json     # 编码字典种子（appcodes）
├── scripts/load_path.py  # RBAC 路径注册
└── skill/SKILL.md     # 模块技能文档