52 lines
3.1 KiB
Markdown
52 lines
3.1 KiB
Markdown
---
|
||
name: world
|
||
description: 世界定义与管理模块（W-01 世界管理）——world 表 CRUD、列表查询(sqlPaging+复合索引)、创建自动编码、mode 白名单硬校验与流转规则校验、world_mode 编码字典幂等落库。通过 load_world() 挂载。
|
||
---
|
||
|
||
# world 模块技能文档
|
||
|
||
## 概述
|
||
世界定义与管理（平台入口域根模块）。提供 world 表 CRUD、分页列表查询、创建自动编码、
|
||
世界模式（mode）白名单硬校验与流转规则校验。依赖 sqlor / ahserver / appbase（编码字典 appcodes/appcodes_kv）。
|
||
|
||
## 数据模型
|
||
表 `world`（models/world.json 四段式 summary/fields/indexes/codes）：
|
||
- id VARCHAR(32) PK（str 32，getID() 生成，禁 uuid）
|
||
- code VARCHAR(64) 唯一（唯一索引 idx_world_code + 应用层前置校验 + 冲突重试）
|
||
- name VARCHAR(255) NOT NULL
|
||
- description TEXT
|
||
- mode VARCHAR(32) NOT NULL DEFAULT 'draft'（白名单 draft/active/paused/archived）
|
||
- world_type VARCHAR(32)（world_type 编码字典）
|
||
- owner_id / org_id VARCHAR(32)
|
||
- created_at / updated_at TIMESTAMP
|
||
- 复合索引 idx_world_list(org_id, mode, created_at) 支撑列表查询
|
||
|
||
编码字典：init/data.json 幂等落库 `world_mode`（draft=草稿/active=运行中/paused=已暂停/archived=已归档）
|
||
与 `world_type`（game/simulation/education/business/social），appcodes + appcodes_kv 两表同插。
|
||
|
||
## 关键接口（经 load_world() 注册到 ServerEnv）
|
||
- `create_world(params)` → 自动编码 W+时间戳+随机4位；mode 默认 draft；非法 mode/流转 100% 拦截不落库；编码唯一冲突重试 3 次
|
||
- `update_world(params)` → 部分更新；mode 变更走流转校验；code 变更走全局唯一校验
|
||
- `delete_world(params)` / `get_world(params)`
|
||
- `list_worlds(params)` → 分页 {list, total, page, page_size}；count 与数据查询分离 + 显式列清单（排除 TEXT），P95 达标
|
||
- `set_world_mode(params)` → 模式切换严格校验（draft→active⇄paused、active/paused→archived、archived→active）
|
||
|
||
REST 前缀 `/api/*`（wwwroot/api/*.dspy）：
|
||
- create_world.dspy / world_update.dspy / world_delete.dspy / get_world.dspy / list_worlds.dspy / set_world_mode.dspy
|
||
- get_search_status.dspy / get_search_world_type.dspy（下拉数据源，返回 [{value,text}]，首项"全部"）
|
||
|
||
统一错误结构：`{code, message, field, detail}`；分页结构：`{list, total}`。
|
||
|
||
## 陷阱
|
||
- mode 硬校验：非法枚举一律返回 INVALID_MODE，绝不落库；流转规则见 MODE_TRANSITIONS
|
||
- 编码唯一：唯一索引兜底 + 前置校验 + Duplicate key 冲突重试（自动编码场景）
|
||
- 列表查询 LIMIT/OFFSET 用整数内联（sqlPaging ns.page/ns.rows），禁止 `${param}$` 生成引号字符串
|
||
- 所有 .dspy 无 import（json/exception/format_exc/get_module_dbname/DBPools 为预载全局）
|
||
- 取库名用 get_module_dbname('world')，禁止硬编码 DBNAME
|
||
- 根目录不放 __init__.py；包目录为 world/world/；三处同步注册（world.py / __init__.py / init.py）
|
||
|
||
## 依赖
|
||
- sqlor（DBPools/sqlExe/sor.C/U/D/R/sqlPaging）
|
||
- ahserver（ServerEnv、get_module_dbname）
|
||
- appbase（appcodes/appcodes_kv 编码字典）
|