9e8984168f
- 根 __init__.py 的删除已在 e118efe 落地并推送 origin/main（本提交补齐可追溯的 Q6 专项说明：README.md / skill/SKILL.md 增补「命名空间铁律」段，留档根因与核验命令） - 根因：modules/entity 根同时存在包目录 entity/ 与种子目录 init/，根再放 __init__.py 会使根成为包，entity.init 解析到根下命名空间目录，遮蔽 entity/entity/init.py → 部署侧 cannot import name 'load_entity' from 'entity.init' - 核验：python3 apps/pbls/scripts/verify_import_closure.py → entity 无 NS_AMBIGUITY 告警
42 lines
1.9 KiB
Markdown
42 lines
1.9 KiB
Markdown
# entity 模块
|
||
|
||
实体管理模块，含实体导入。依赖 `world`、`scene` 模块。
|
||
|
||
## 功能
|
||
- 实体表（entity）CRUD：实体名称/编码/所属世界/所属场景/实体类型/状态/属性 JSON
|
||
- 实体导入：上传 CSV/JSON 文件 → 解析 → 逐条校验 → 批量落库 → 写导入记录（entity_import）
|
||
|
||
## 数据表
|
||
| 表 | 说明 |
|
||
|----|------|
|
||
| entity | 实体表 |
|
||
| entity_import | 实体导入记录表 |
|
||
|
||
## 目录结构
|
||
```
|
||
entity/
|
||
├── entity/ # Python 包（init.py 定义 load_entity 及业务函数）
|
||
├── models/ # 表定义（entity.json / entity_import.json）
|
||
├── json/ # CRUD 定义（entity.json / entity_import.json）
|
||
├── wwwroot/ # 前端（index.ui / import_page.ui / api/*.dspy）
|
||
├── init/data.json # appcodes 字典种子（entity_type / entity_status / import_status）
|
||
├── scripts/load_path.py # RBAC 权限注册
|
||
└── skill/SKILL.md # 模块技能文档
|
||
```
|
||
|
||
## 集成方式
|
||
应用入口 `app/{应用名}.py` 中 `from entity.init import load_entity`，并在 `init()` 里调用
|
||
`load_entity()`。库名由宿主应用的 `get_module_dbname('entity')` 决定，模块内不硬编码。
|
||
|
||
## 关键接口
|
||
- `load_entity()`：挂载模块函数到 ServerEnv
|
||
- `wwwroot/api/entity_import.dspy`：实体导入（world_id + scene_id + file）
|
||
- `wwwroot/api/entity_create.dspy` / `entity_update.dspy` / `entity_delete.dspy`：实体 CRUD
|
||
- `wwwroot/api/get_search_*.dspy`：下拉数据源
|
||
|
||
## 命名空间约束（Q6）
|
||
仓库根**不得**存在 `__init__.py`（会使根成为包，令 `entity.init` 遮蔽 `entity/entity/init.py`，
|
||
部署时报 `cannot import name 'load_entity' from 'entity.init'`）。根 `__init__.py` 已在提交
|
||
`e118efe` 删除并推送 `origin/main`；核验命令：
|
||
`python3 apps/pbls/scripts/verify_import_closure.py`（entity 应无 NS_AMBIGUITY 告警）。
|