entity/skill/SKILL.md

name	description
entity	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）。