- 回调 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 等。
191 lines
11 KiB
Markdown
191 lines
11 KiB
Markdown
# 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. 命令用法
|
||
|
||
```powershell
|
||
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)
|
||
|
||
```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 示例(一次完成新建 + 写入)
|
||
|
||
```powershell
|
||
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. 回归测试
|
||
|
||
```powershell
|
||
node test/scripts/update_api_doc.test.cjs
|
||
```
|
||
|
||
覆盖 13 用例:`spec.newDoc` 新建骨架、保留键不透传、doc 已存在时 `newDoc` 被忽略、changes 自动创建、`--doc-only` 不建 changes、dry-run 不写盘、`--help` 输出、新建文件 2 空格 + LF 等。
|