WMS_MAIN/docs/api-doc-update-workflow.md
liufumingren d725e7e457 feat(openapi): 出站回调命名与报文改奇门同层级
- 回调 method 由 snake_case 事件名改为 模块.动作:entryorder.confirm / entryorder.match / deliveryorder.confirm / stockout.confirm / deliveryorder.cancel(原 order.cancel 与入站方法同名,改名避免 callback_url 误指向 /openapi 时被路由到取消单据接口)。

- 时间戳统一为秒级(String(Math.floor(Date.now()/1000))),与 /openapi 入站 ±600 秒时效校验及回调调试页一致。

- 报文体由 { event, data, metadata } 改为奇门同层级 { request: {...} }(移除 metadata,事件标识只靠 query 的 method);入库类回调与奇门侧共用同一份报文组装。

- deliveryorder.confirm 改为逐单发送(仅同步成功的订单);stockout.confirm 直接复用 buildStockoutConfirmDataInternal 结果。

- 修复 entryorder.match 死代码:绑定成功且本次新建绑定时回传,重复触发不重复通知,回传失败不影响绑定。

- 调试页 /docs/api/openapi/callback-test 按真实报文预填;新增出站回调文档页 /docs/api/openapi_callback 及入口链接。

- script/update-api-doc.cjs 支持 spec.newDoc 新建文档与 docMeta.description(附单测)。

- 文档:methods/openapi_callback.json、AI_METHOD_ROUTING.md 5.6 节、docs/openapi-callback-events.md、docs/api-doc-update-workflow.md 等。
2026-09-13 02:24:37 +08:00

11 KiB
Raw Permalink Blame History

API 文档更新工作流(script/update-api-doc.cjs)

本文档说明 methods/*.json(接口文档 SSOT)与 methods/changes/*.json(变更记录)的唯一合规写入方式: 通过 npm run doc:api:update -- --spec=<path> 执行,禁止直接手写这两个目录下的 JSON。 内容以 script/update-api-doc.cjs 实际实现为准;回归测试见 test/scripts/update_api_doc.test.cjs(13 用例)。

1. 命令用法

npm run doc:api:update -- --spec=<path>            # 正式写入(主文档 + 变更记录)
npm run doc:api:update -- --spec=<path> --dry-run  # 只校验并打印计划,不写任何文件
npm run doc:api:update -- --spec=<path> --doc-only # 只写 methods/<docName>.json,跳过变更记录
npm run doc:api:update -- --help                   # 打印用法、选项与 spec.newDoc 说明(-h 等价)
  • --spec=<path>:必填;相对路径按项目根目录(process.cwd())解析。缺省报 Missing required --spec=<path> argument.;文件不存在报 Spec file not found: <path>。
  • 脚本底层等价于 node ./script/update-api-doc.cjs --spec=<path>,npm 层需要 -- 分隔符传递参数。

2. spec 结构(固定 spec JSON)

{
  "docName": "system",
  "docMeta": { "version": "1.2.0", "updatedAt": "2026-09-12" },
  "group": { "groupName": "分组展示名", "module": "分组 module" },
  "methods": [ { "method": "...", "description": "...", "isNeedAuth": true, "isNeedLogin": false, "headers": [], "params": [], "response": [], "errors": [], "notes": [] } ],
  "deleteMethods": [ "要删除的.method" ],
  "change": { "version": "唯一版本号", "date": "2026-09-12", "type": "updated", "summary": "...", "methods": [ "..." ], "notes": [ "..." ] }
}
字段 必填 说明
docName 是 目标文档名;仅允许字母、数字、下划线、横线(^[a-z0-9_-]+$)。对应 methods/<docName>.json 与 methods/changes/<docName>.json
docMeta 否 { version, updatedAt, description } 均可选;写入后覆盖主文档根部的 version / updatedAt / description(description 为字符串时生效,可用于更正根说明文案)
group 是 { groupName, module } 均为非空字符串。定位已有分组时先按 module 匹配,再按 groupName;找不到则新建分组
methods 是 至少 1 条 method 文档;按 group + method 做 upsert,不覆盖其它分组/方法
deleteMethods 否 要删除的 method 名数组;不能与 methods 中的 method 重名,否则报 Method conflict
change 否 变更记录对象(--doc-only 模式下可省略)。详见第 5 节

2.1 method 文档条目(methods[] 每一条)

  • 必填键:method / description / isNeedAuth(boolean)/ isNeedLogin(boolean)/ headers(数组)/ params(数组)/ response(数组)/ errors(数组)。
  • notes 可选(字符串数组,写入后保留在 method 文档内)。

2.2 upsert 语义

  • method 不存在 → inserted(追加到目标分组 list 尾部)。
  • method 已存在且在同一分组 → updated(整条覆盖)。
  • method 已存在但在其它分组 → moved(从原分组移除后写入目标分组)。
  • deleteMethods 命中 → deleted;未命中 → delete-not-found(不报错,仅提示)。
  • 脚本逐条打印 inserted: / updated: / moved: / deleted: / delete-not-found: 行。

3. 字段级硬性校验(报错即拒绝写入)

校验点 规则
docName 非空字符串,仅字母/数字/下划线/横线
docMeta.description(可选) 若提供必须为字符串(可为空串,表示清空根说明);非字符串报 spec.docMeta.description must be a string.
group.groupName / group.module 非空字符串
methods[].method / description 非空字符串;spec 内 method 名不允许重复(Duplicate method in spec.methods)
methods[].isNeedAuth / isNeedLogin 必须为 boolean
methods[].headers / params / response / errors 必须为数组
headers[] / params[] / response[] 每一项 name / type / description 非空字符串;required 必须为 boolean(非布尔报 xxx.required must be a boolean)
source 字段 仅 params[] 允许(allowSource=true,如 query / body);headers[] / response[] 不校验 source,因此不要在这两处写 source
可选 list 字段 必须是数组,且每一项必须含 value 键
errors[] 每一项 必须含 code 键(数字或字符串均可,如 400 / 5xx)+ 非空字符串 message
deleteMethods[] 字符串数组;与 methods[] 中的 method 重名时报 Method conflict
change 见第 5 节

4. 新增文档能力(spec.newDoc,2026-09-12 新增)

目标 methods/<docName>.json 不存在时,spec 必须提供 newDoc,脚本自动生成文档骨架后再应用 group / methods;否则报:

Target doc file not found: <path> (provide spec.newDoc to create it)

4.1 newDoc 字段与规则

字段 规则
module 必填,非空字符串 → 新文档根 module
description 可选,string;缺省 ""
http 可选,object;缺省 { "path": "", "method": "POST" }
headers 可选,array;缺省 []
version / updatedAt / methods 保留键:由骨架统一管理(version/updatedAt 取自 docMeta,methods 固定为 { groups: [] }),写在 newDoc 里不生效、不参与透传,也不报错
其它未知字段 仅接受 plain JSON 值(null/字符串/数字/布尔/对象/数组,递归校验),原样透传到新文档根(供未来扩展)

4.2 骨架与落盘行为

  • 新文档骨架:{ module, description, version, updatedAt, http, headers, methods: { groups: [] } };version 取 docMeta.version(缺省 0.0.0),updatedAt 取 docMeta.updatedAt(缺省本地今天 YYYY-MM-DD)。
  • methods/changes/<docName>.json 不存在时视为空数组,正式写入时自动创建(目录递归创建),内容为仅含本次 change 的数组。
  • 新建文件统一为 2 空格缩进 + LF;已存在的文件保留原缩进与 EOL 风格(最小 diff)。
  • doc 已存在时 spec.newDoc 被忽略(与不传 newDoc 落盘结果逐字节一致,有测试覆盖)。
  • dry-run 对将要新建的文件打印 created: <相对路径> 计划行,但不写盘。

4.3 示例(一次完成新建 + 写入)

npm run doc:api:update -- --spec=temp/api-doc-create.json --dry-run
npm run doc:api:update -- --spec=temp/api-doc-create.json

5. 变更记录(methods/changes/<docName>.json)

  • change 必填键:version(非空字符串,不得与既有记录重复,重复报 Duplicate change version detected)/ date / summary / methods(字符串数组)/ notes(字符串数组)。
  • type 可选(如 added / updated)。
  • 新记录插入数组头部(unshift),与现有约定一致;历史记录不回改。
  • 建议记录至少包含:version、date、summary、methods、notes。

6. 推荐流程

  1. 核对代码与调用链(controller / systemMethods / systems / model / test),确定 method、参数、响应、错误码的真实口径。
  2. 在 temp/apiDoc/ 下先备份对应时间点的 methods/<docName>.json 与 methods/changes/<docName>.json(自动归档与人工回档都在该目录)。
  3. 组织固定 spec JSON(可从已有 spec 或 docs/api-doc-update-spec.example.json 复制后编辑)。
  4. 先执行 dry-run 校验并查看 inserted: / updated: / deleted: / created: 计划行。
  5. 确认无误后正式执行写入。
  6. 校验落盘文件:JSON.parse 可解析、缩进/EOL 与写入前一致(新建文件为 2 空格 + LF)。
  7. 再同步 docs/*.md / README.md 等解释性文档。

7. --doc-only 的适用场景

  • 仅修补 methods/<docName>.json 本身、不追加变更记录时使用(例如变更记录 version 与既有记录重复且只想修正主文档,慎用)。
  • --doc-only 下 spec 可省略 change;若提供了 change 仍会做字段校验(不写 changes 文件)。
  • 注意:--doc-only 属于旁路,正式接口变更仍应走完整流程(主文档 + 变更记录)。

8. 环境变量钩子(仅测试用)

  • WMS_API_DOC_METHODS_DIR:覆盖主文档目录(默认 methods/)。
  • WMS_API_DOC_CHANGES_DIR:覆盖变更记录目录(默认 methods/changes/)。
  • 脚本在模块加载时读取这两个变量(path.resolve 解析)。仅用于测试目录隔离(如 test/scripts/update_api_doc.test.cjs 注入临时目录),业务运行不要设置。

9. 输出样例

dry-run(新建场景):

docName: sample
group: sample (示例分组)
inserted: sample.echo
updated: -
moved: -
deleted: -
delete-not-found: -
change version: 2026.09.12-sample
created: methods/sample.json
created: methods/changes/sample.json
dry-run: validated successfully, no files were written.

正式写入(既有文档):

docName: openapi_callback
group: callback (出站回调事件)
inserted: deliveryorder.cancel
updated: entryorder.confirm, entryorder.match, deliveryorder.confirm, stockout.confirm
moved: -
deleted: order.cancel
delete-not-found: -
change version: 2026.09.12-openapi-callback-protocol-align
wrote: methods/openapi_callback.json
wrote: methods/changes/openapi_callback.json

10. 常见坑(校验报错对照)

报错 / 现象 原因与处理
Missing required --spec=<path> argument. 未传 --spec=(npm 调用需加 -- 分隔符)
Spec file not found: <path> spec 路径不存在或相对路径解析基准不对(按项目根解析)
spec.docName must contain only letters, numbers, underscore, or dash. docName 含非法字符
spec.methods must contain at least one method doc. methods 为空数组
spec.methods[0].response[0].required must be a boolean. required 不是布尔(写了字符串 "true" 等)
Duplicate method in spec.methods: xxx spec 内 method 名重复
Method conflict: xxx appears in both spec.methods and spec.deleteMethods. 同一 method 同时出现在增改与删除列表
Target doc file not found: <path> (provide spec.newDoc to create it) 目标文档不存在且未提供 spec.newDoc
spec.newDoc.module must be a non-empty string. newDoc 缺 module 或为空白字符串
spec.newDoc.custom must be a plain JSON value. newDoc 未知透传字段不是 plain JSON 值(如函数)
Duplicate change version detected: xxx changes 中已有同 version 记录;更换 version,或确认只想补主文档时用 --doc-only
变更记录里方法名带 spec. 前缀报错 字段路径为 spec 内路径提示,指向的仍是 method 文档字段本身

11. 回归测试

node test/scripts/update_api_doc.test.cjs

覆盖 13 用例:spec.newDoc 新建骨架、保留键不透传、doc 已存在时 newDoc 被忽略、changes 自动创建、--doc-only 不建 changes、dry-run 不写盘、--help 输出、新建文件 2 空格 + LF 等。