# 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     # 模块技能文档
```