73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
---
|
||
name: scene
|
||
description: scene 模块技能文档——场景管理（场景表 CRUD + 场景导入）。提供 scene/scene_import 两张表、CRUD、列表查询接口、文件导入（api/scene_import.dspy），通过 load_scene() 挂载。枚举字段用 appcodes 字典（cond parentid=）。
|
||
---
|
||
|
||
# scene 模块
|
||
|
||
## 概述
|
||
场景管理，含场景导入。依赖 world（world_id 外键）、appbase（appcodes 字典）、rbac（权限）。
|
||
|
||
## 数据模型
|
||
|
||
### 表 `scene`（models/scene.json）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | str(32) | 主键 |
|
||
| world_id | str(32) | 所属世界（→world.id） |
|
||
| name | str(255) | 场景名称 |
|
||
| code | str(64) | 场景编码（唯一） |
|
||
| description | text | 描述 |
|
||
| scene_type | str(16) | 场景类型（appcodes scene_type，默认 '0'） |
|
||
| status | str(16) | 状态（appcodes scene_status，默认 '0'） |
|
||
| config_json | text | 场景配置 JSON |
|
||
| created_at | timestamp | 创建时间 |
|
||
| updated_at | timestamp | 更新时间 |
|
||
|
||
- 主键 `["id"]`；唯一索引 `idx_scene_code(code)`；索引 `idx_scene_world(world_id)`
|
||
- 字典：world_id → world(id/name)、scene_type → appcodes_kv(parentid='scene_type')、status → appcodes_kv(parentid='scene_status')
|
||
|
||
### 表 `scene_import`（models/scene_import.json）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | str(32) | 主键 |
|
||
| world_id | str(32) | 目标世界 |
|
||
| file_name | str(255) | 导入文件名 |
|
||
| total | int | 总条数（默认 0） |
|
||
| success | int | 成功条数（默认 0） |
|
||
| fail | int | 失败条数（默认 0） |
|
||
| status | str(16) | 导入状态（appcodes import_status，默认 '0'） |
|
||
| created_at | timestamp | 导入时间 |
|
||
|
||
- 主键 `["id"]`；索引 `idx_scene_import_world(world_id)`
|
||
- 字典：world_id → world、status → appcodes_kv(parentid='import_status')
|
||
|
||
## 关键接口
|
||
|
||
### ServerEnv 注册函数（load_scene() 挂载）
|
||
- `list_scenes(params)` → `[{value:id, text:name}]`
|
||
- `get_scene({id})` → 单条
|
||
- `create_scene(ns)` → 自动生成 id/code、写 created_at
|
||
- `update_scene(ns)` → 写 updated_at、剔除 `_text` 后缀
|
||
- `delete_scene({id})`
|
||
- `import_scenes({world_id, file_name, rows})` → `{success, total, success_count, fail}`
|
||
- `parse_scene_file(content, filename)` → `[{...}]`（JSON 数组 / JSON Lines / CSV）
|
||
- `get_world_options()` / `get_scene_type_options()` / `get_scene_status_options()` → `[{value, text}]`
|
||
|
||
### wwwroot/api/*.dspy
|
||
- `list_scenes.dspy`、`create_scene.dspy`、`scene_update.dspy`、`scene_delete.dspy`
|
||
- `get_search_world_id.dspy` / `get_search_scene_type.dspy` / `get_search_status.dspy`：字典下拉
|
||
- `scene_import.dspy`：场景导入（world_id + file → parse_scene_file → import_scenes）
|
||
|
||
## 陷阱
|
||
- 库名禁止硬编码：.py 用 `ServerEnv().get_module_dbname("scene")`，.dspy 用 `get_module_dbname("scene")`（全局）
|
||
- world 下拉用 `ServerEnv().get_module_dbname("world")`（world 表在 world 模块库）
|
||
- dspy 无 import（json/get_sor_context/debug/params_kw 均为预加载全局）
|
||
- `create_scene` 必须设置 `created_at = curDateString()`，否则 sor.C 静默丢记录
|
||
- 导入时 `scene_import` 记录必须设置 `created_at`，字段 total/success/fail 为 int
|
||
- `import_scenes` 返回用 `success_count` 表示成功条数（避免与布尔 `success` 键冲突）
|
||
- CRUD json `new_data_url` 指向自定义 `api/create_scene.dspy`；scene_import 为只读列表，无 editable
|
||
|
||
## 依赖
|
||
- world（world_id 外键 + 世界下拉）、appbase（appcodes 字典）、rbac（权限）
|