45 lines
2.6 KiB
Markdown
45 lines
2.6 KiB
Markdown
# 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 # 模块技能文档
|
||
```
|