45 lines
2.4 KiB
Markdown
45 lines
2.4 KiB
Markdown
# 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}]`
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
cd modules/entity && pip install .
|
||
```
|
||
|
||
详见 skill/SKILL.md。
|