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

191 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 等。