---
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 用整数内联，禁止 `${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）
- ahserver（ServerEnv、get_module_dbname）
- appbase（appcodes/appcodes_kv 编码字典）