67 lines
4.5 KiB
Markdown
67 lines
4.5 KiB
Markdown
---
|
||
name: world_sync
|
||
description: 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 | 编码字典 [{value,text}] |
|
||
|
||
成功：`{"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()
|