world_sync/skill/SKILL.md

name	description
world_sync	W-05 同步管理模块——同步配置(world_sync)、同步任务(world_sync_task)、同步日志(world_sync_log)管理; 同步任务批量事务执行、失败回滚无脏数据; 编码字典 sync_status/sync_type 幂等落库。

world_sync 模块技能文档

模块概述

world_sync 是元景项目 W-05 同步管理模块，提供：

• 同步配置维护（world_sync 表 CRUD，同步编码唯一、类型/模式/状态白名单校验）
• 同步任务执行（create_sync_task + execute_sync_task，批量事务 + 失败回滚无脏数据）
• 同步日志查询（get_sync_log 分页 {list,total}）
• 编码字典（sync_status / sync_type 经 init/data.json 幂等落库 appcodes/appcodes_kv）

架构与集成

• Python 包 world_sync/，通过 load_world_sync() 注册到 ServerEnv（宿主应用调用）。
• 宿主应用 app/{app}.py 定义 get_module_dbname('world_sync') 并挂 ServerEnv；模块内禁止硬编码库名。
• 前端 wwwroot/ 自动路由 /world_sync/{file}；api/ 下 .dspy 为薄封装，业务在 init.py 注册函数。
• 宿主应用 spec.json 的 generated_modules 必须包含 "world_sync"，并在 init() 中 load_world_sync() 挂载。

数据模型（models/*.json 四段式）

表	说明	主键	关键字段
world_sync	同步配置	id str(32)	sync_code(唯一 str64)、sync_name、sync_type(str32)、mode(str16)、status(str32)、org_id
world_sync_task	同步任务	id str(32)	sync_id、sync_code、sync_type、status、batch_no、total/success/fail_count、start/end_time、error_msg
world_sync_log	同步日志	id str(32)	task_id、sync_id、sync_type、status、direction、target_table、target_key、batch_no、payload、result、error_msg

• 主键 id 一律 str(32)，由 appPublic.uniqueID.getID() 生成（禁止 uuid4）。
• status 字段引用 appcodes_kv，cond 用 parentid='sync_status' / parentid='sync_type'（禁止 id=）。

关键接口（REST 前缀 /api/*，错误结构 {code,message,field,detail}，分页 {list,total}）

方法/路径	说明
POST /world_sync/api/world_sync_create.dspy	新增同步配置（前置校验，非法输入不落库）
POST /world_sync/api/world_sync_update.dspy	更新同步配置
POST /world_sync/api/world_sync_delete.dspy	删除同步配置（级联任务/日志）
GET /world_sync/api/world_sync_list.dspy	配置分页列表 {list,total}
POST /world_sync/api/world_sync_task_create.dspy	创建同步任务
POST /world_sync/api/world_sync_task_execute.dspy	执行同步任务（batch 批量事务，失败回滚）
GET /world_sync/api/world_sync_task_list.dspy	任务分页列表 {list,total}
GET /world_sync/api/world_sync_log_list.dspy	日志分页查询 {list,total}
GET /world_sync/api/world_sync_dict.dspy?type=sync_status	sync_type

成功：{"success":true,"code":0,"message":"ok","data":{...}} 失败：{"success":false,"code":400|404|409|500,"message":"...","field":"...","detail":"..."}

模块陷阱

1. 三处同步注册：增删函数需同步修改 world_sync/world_sync.py、__init__.py 导入、init.py 的 env.xxx = xxx。
2. dspy 禁 import：.dspy 无 import（json/debug/format_exc 预置），业务全部走 await xxx(request, params_kw) 委托。
3. sor 接口：只用 sor.C/U/R/D/I/sqlExe；sor.U('t', data) 只收 2 参，id 在 data 内；sor.I 只收 1 参（元数据）。
4. 事务回滚：execute_sync_task 中批量写入任一条失败 → sor.rollback() 整体回滚，任务标记 failed，无脏数据；校验失败（batch 非数组/超 5000/任务已结束/配置停用）直接拦截不写库。
5. 时间戳：sqlor 不自动填充 created_at，必须 curDateString() 显式赋值，否则 sor.C 静默丢记录。
6. 用户上下文：.py 内取用户用 request._run_ns（env = request._run_ns; await env.get_user()），ServerEnv() 单例无 per-request 用户。
7. 库名：取库名一律 ServerEnv().get_module_dbname('world_sync')，禁止 DBNAME = 'xxx'。
8. task/log 只读：json/ 中 task、log 的 editable 指向 world_sync_write_guard.dspy，拒绝直接增删改，数据只能由 execute_sync_task 生成。

依赖

• 基础包：sqlor、ahserver(ServerEnv)、appPublic(uniqueID/log/timeUtils)
• 编码字典依赖宿主应用 appbase 的 appcodes/appcodes_kv 表
• 宿主应用必须定义 get_module_dbname 并 load_world_sync()