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 告警
43 lines
2.9 KiB
Markdown
43 lines
2.9 KiB
Markdown
---
|
||
name: entity
|
||
description: entity 模块技能文档——实体管理（实体表 CRUD + 实体导入 entity_import + api/entity_import.dspy），通过 load_entity() 挂载。
|
||
---
|
||
|
||
# entity 模块
|
||
|
||
## 概述
|
||
实体管理模块，提供实体表（entity）增删改查与文件导入（entity_import 记录表）。依赖 world、scene 模块。
|
||
|
||
## 数据模型
|
||
- `entity`：id / world_id（→world.id）/ scene_id（→scene.id）/ name / code / entity_type（appcodes entity_type）/ status（appcodes entity_status）/ attributes_json(text) / created_at / updated_at。唯一索引 code。
|
||
- `entity_import`：id / world_id / scene_id / file_name / total / success / fail / status（appcodes import_status）/ created_at。只读记录。
|
||
|
||
## 关键接口
|
||
- `load_entity()`：注册 create_entity/update_entity/delete_entity/entity_import 到 ServerEnv（含复数别名）。
|
||
- `wwwroot/api/entity_import.dspy`：文件导入 → 解析（JSON 数组或 CSV 表头）→ 逐条校验 name/code → sor.C('entity') → 统计 → sor.C('entity_import')。返回 `{success,total,success_count,fail,file_name}`。
|
||
- `wwwroot/api/entity_{create,update,delete}.dspy`：实体 CRUD（委托 init.py 函数）。
|
||
- `wwwroot/api/get_search_{world_id,scene_id,entity_type,status}.dspy`：下拉数据源。
|
||
|
||
## 陷阱
|
||
- 库名禁止硬编码：.py 用 `ServerEnv().get_module_dbname('entity')`，.dspy 用 `get_module_dbname('entity')` / `get_sor_context(request._run_ns, 'entity')`。
|
||
- dspy 内禁止 import（仅 `from sqlor.filter import DBFilter` 例外），业务逻辑放 `entity/init.py` 并通过 `load_entity()` 导出。
|
||
- `sor.C()` 不会自动填 created_at，必须显式 `ns['created_at'] = curDateString()`。
|
||
- 实体导入记录（entity_import）只读，不可手工增删改。
|
||
|
||
## 依赖
|
||
- world、scene（下拉数据源 world / scene 表）
|
||
- 基础：sqlor、ahserver、bricks、appbase（appcodes）
|
||
|
||
## 命名空间铁律（pbls-deploy-Q6 缺陷 2 修复留档）
|
||
|
||
- **仓库根禁止存在 `__init__.py`**：`modules/entity/` 根下同时有包目录 `entity/` 与种子数据目录
|
||
`init/`，若根再放 `__init__.py`，根目录自身成为包，`entity.init` 会被解析成「根下的 init/
|
||
命名空间目录」而遮蔽真实实现 `entity/entity/init.py` → 部署侧报
|
||
`cannot import name 'load_entity' from 'entity.init'`（deploy_test 第 3 轮实测）。
|
||
- 根 `__init__.py` 已于提交 `e118efe` 删除（`git rm`），本地 main 与 `origin/main` 同 SHA，
|
||
`git ls-remote origin main` 已含该提交；`apps/pbls/scripts/verify_import_closure.py` 复跑
|
||
entity 无 `NS_AMBIGUITY` 告警。
|
||
- 唯一入口：`from entity.init import load_entity`（实现文件 `entity/init.py`，包导出
|
||
`entity/__init__.py`）。新增函数仍须遵守三处同步注册（实现 def / 包 `__init__.py` 导出 /
|
||
`init.py` 的 `load_entity()` 内 `env.xxx = xxx`）。
|