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

实体管理模块：实体表（entity）增删改查、分页列表查询、实体文件导入（entity_import 记录表）。依赖 world、scene（逻辑关联，不加物理外键）。

功能

• 实体 CRUD：create_entity / update_entity / delete_entity / get_entity / list_entities
• 列表查询：sqlPaging 分页 {list, total}，支持 world_id / scene_id / entity_type / status / name / code 过滤 + sort / order
• 文件导入：api/entity_import.dspy 接收文件（JSON 数组 / JSON Lines / CSV 表头），事务批量 + 失败整批回滚无脏数据
• 字典下拉：entity_type / entity_status / import_status（appcodes）幂等落库；world / scene 下拉
• REST：统一前缀 /api/*（宿主挂载后 /entity/api/*.dspy），错误结构 {code,message,field,detail}，分页 {list,total}，非法输入 100% 拦截不落库

数据表

表	说明
entity	实体表：id / world_id / scene_id / name / code(唯一) / entity_type / status / attributes_json / created_at / updated_at
entity_import	导入记录表（只读）：id / world_id / scene_id / file_name / total / success / fail / status / created_at

• entity.scene_id → scene.id、entity.world_id → world.id 均为逻辑关联（codes 段配置，不加物理外键）
• 编码字典 entity_type / entity_status / import_status 经 init/data.json 幂等落库到 appbase

集成

1. load_entity() 挂载：在宿主应用 init() 中调用（函数注册到 ServerEnv，含复数别名）
2. wwwroot 符号链接到宿主 wwwroot/entity/
3. 运行 scripts/load_path.py 注册 RBAC（或同步中央 load_path.py）
4. 构建：json2ddl mysql . > mysql.ddl.sql（models/）、xls2ui -m ../models -o ../wwwroot entity *.json（json/）

关键接口（经 load_entity() 注册）

• list_entities(params) → {list, total}
• create_entity(ns) / update_entity(ns) / delete_entity(ns) / get_entity(ns)
• import_entities({world_id, scene_id, file_name, rows}) → {success, total, success_count, fail}
• parse_entity_file(content, filename) → {rows: [...]}
• get_world_options() / get_scene_options() / get_entity_type_options() / get_entity_status_options() / get_import_status_options() → [{value, text}]

安装

cd modules/entity && pip install .

详见 skill/SKILL.md。