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