同步文档与系统接口变更

This commit is contained in:
liufumingren 2026-04-17 20:02:39 +08:00
parent fec1dd9f55
commit 37a8e152a6
5 changed files with 808 additions and 27 deletions

View File

@ -38,9 +38,10 @@ model: GPT-5 mini (copilot)
- 公共请求头变化
- 鉴权方式变化
- 每次 API 接口变更(新增 / 修改 / 删除 method、参数、响应、错误码、header、鉴权等)后,除了更新 `methods/*.json` / `docs/*.md`,**还必须追加一条变更记录到对应的 `methods/changes/<docName>.json` 数组**
- 默认禁止直接手写 `methods/*.json` / `methods/changes/*.json`,必须先按 `docs/api-doc-update-workflow.md` 生成固定 spec,再执行 `npm run doc:api:update -- --spec=<path>`
- 正式写入前必须先执行 `npm run doc:api:update -- --spec=<path> --dry-run`
- 修补 JSON 文件时必须强校验 JSON 格式正确性,确保不会引入无法解析的问题
- 明确禁止直接手动编辑或提交 `methods/*.json` 与 `methods/changes/*.json` 文件。
- 任何 PR 中直接修改这类文件的变更将被视为违规并可能被退回。所有对 methods JSON 的写入必须通过脚本完成,命令为 `npm run doc:api:update -- --spec=<path>`(不可绕过)。
- 正式写入前**必须**先执行 `npm run doc:api:update -- --spec=<path> --dry-run` 进行验证;dry-run 不做写入,仅输出差异和校验结果。
- 修补 JSON 文件时必须强校验 JSON 格式正确性,确保不会引入无法解析或破坏结构的问题
- `methods/*.json` 仍是 SSOT,`methods/changes/*.json` 仅记录差异历史
- 变更记录建议字段至少包含:`version`、`date`、`summary`、`methods`、`notes`
5. 如 system 入参有变化,可执行:
@ -97,6 +98,33 @@ Select-String -Path "methods/system.json" -Pattern "storage.receiving.bindDetail
3) 同步 docs/*.md / README,并校验文档与实现一致
```
## 脚本使用示例
推荐的最小操作序列(PowerShell 示例):
```powershell
# 1) 从示例复制 spec 到 temp 并编辑
Copy-Item docs/api-doc-update-spec.example.json temp/api-doc-update.json
# 2) 先 dry-run(仅校验并打印差异)
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
# 3) 检查 dry-run 输出并修正 spec;确认无误后正式写入
npm run doc:api:update -- --spec=temp/api-doc-update.json
# 4) 仅修补主文档且不追加 changes(慎用)
npm run doc:api:update -- --spec=temp/api-doc-update.json --doc-only
```
脚本职责(由 `script/update-api-doc.cjs` 实现):
- 校验 spec JSON 结构与必填字段
- 在 dry-run 模式下不写入,仅打印将要变更的差异并返回校验结果
- 校验目标 `methods/*.json` 与 `methods/changes/*.json` 的可解析性
- 按 `group` + `method` 执行 upsert,避免覆盖或破坏其它分组/方法
- 保留目标文件原有缩进与换行风格,尽量减少无关 diff
- 校验 change 版本不重复并拒绝重复写入
## 输出要求
- 所有回复建议以 `[Doc]` 开头

View File

@ -184,4 +184,4 @@ const parsed = await ctx.service.systems.excel.parseFile('D:/tmp/demo.xlsx');
## 参考
- Egg.js 官方文档:https://eggjs.org
- Egg.js 官方文档:https://v3.eggjs.org/

View File

@ -64,21 +64,25 @@
- `methods` 为要写入的完整 method 文档对象数组,脚本按 `method` 字段 upsert
- `change` 默认必填;仅当明确是纯格式修复且不需要追加历史时,才允许加 `--doc-only`
注意:所有对 `methods/*.json` 与 `methods/changes/*.json` 的变更必须通过 spec + 脚本完成。spec 是唯一输入来源,不接受直接手写或直接提交目标 JSON 的改动。
## 固定命令
先做 dry-run:
务必按顺序执行:复制 example -> 编辑 spec -> dry-run -> 修正 -> 正式写入。示例命令(PowerShell):
先做 dry-run(验证和查看差异):
```powershell
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
```
确认无误后执行写入:
确认 dry-run 输出无误后执行正式写入:
```powershell
npm run doc:api:update -- --spec=temp/api-doc-update.json
```
纯文档主文件修补且不追加 changes 时:
仅修补主文档且不追加 changes 时(慎用):
```powershell
npm run doc:api:update -- --spec=temp/api-doc-update.json --doc-only
@ -86,18 +90,35 @@ npm run doc:api:update -- --spec=temp/api-doc-update.json --doc-only
## 脚本保证
`script/update-api-doc.cjs` 会执行以下动作:
`script/update-api-doc.cjs` 会执行以下动作(脚本为写入守门人):
- 校验 spec JSON 是否符合固定结构
- 校验 spec JSON 是否符合固定结构与必填字段
- 校验目标 `methods/*.json` 与 `methods/changes/*.json` 是否可解析
- 按 group + method 做 upsert,避免手写 JSON 时把括号、逗号、层级写坏
- 检查 change version 是否重复
- 保留目标 JSON 原有缩进与换行风格
- 在 dry-run 模式下不写入,仅打印将要变更的差异并返回校验结果
- 按 `group` + `method` 做 upsert,避免覆盖或破坏其他分组/方法
- 检查 change version 是否重复并拒绝冲突写入
- 尽量保留目标 JSON 原有缩进与换行风格,减少无关 diff
脚本是对 methods JSON 的唯一写入通道;任何绕过脚本的改动都不被接受。
## 推荐流程
1. 先核对代码与测试,确认真实接口契约
2. 如果是 system 参数结构变化,可先执行 `node .\script\tmp-struct-system-params.cjs`
3. 按 [docs/api-doc-update-spec.example.json](docs/api-doc-update-spec.example.json) 复制一份 spec 到 `temp/`
4. 先执行 dry-run,再执行正式写入
5. 最后补充必要的 `docs/*.md` 或 `README.md`
3. 按 [docs/api-doc-update-spec.example.json](docs/api-doc-update-spec.example.json) 复制一份 spec 到 `temp/` 并在该文件上编辑
4. 先执行 dry-run(`--dry-run`),阅读输出并修正 spec
5. 确认无误后执行正式写入(不带 `--dry-run`)
6. 最后补充必要的 `docs/*.md` 或 `README.md`
最小示例流程(PowerShell):
```powershell
# 复制示例到 temp 并编辑
Copy-Item docs/api-doc-update-spec.example.json temp/api-doc-update.json
# dry-run
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
# 正式写入
npm run doc:api:update -- --spec=temp/api-doc-update.json
```

View File

@ -552,15 +552,6 @@
"isNeedAuth": false,
"isNeedLogin": true,
"params": []
},
{
"method": "index.getExpressList",
"description": "index.getExpressList 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [],
"response": [],
"errors": []
}
]
},
@ -2436,6 +2427,747 @@
}
]
},
{
"groupName": "快递编码管理模块",
"module": "setting.express",
"list": [
{
"method": "index.getExpressList",
"description": "合并后的快递列表",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [],
"response": [],
"errors": []
},
{
"method": "setting.express.list",
"description": "查询当前仓库范围的快递映射列表,支持 where + pagination",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize,兼容 currentPage / page_size / size"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构"
}
],
"response": [],
"errors": []
},
{
"method": "setting.express.listBase",
"description": "返回系统快递基础列表(系统级别基础快递,不含仓库自定义)",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [],
"response": [],
"errors": []
},
{
"method": "setting.express.create",
"description": "创建快递映射,仅写入已实现字段(code、name、platform 等)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "code",
"type": "string",
"required": true,
"source": "body",
"description": "快递编码"
},
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "快递名称"
},
{
"name": "platform",
"type": "string",
"required": false,
"source": "body",
"description": "平台标识(可选)"
}
],
"response": [],
"errors": []
},
{
"method": "setting.express.checkCodeUnique",
"description": "校验快递编码在当前仓库/主体维度唯一性,仅支持 code 与可选 id 排除自身",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "code",
"type": "string",
"required": true,
"source": "body",
"description": "待校验的快递编码"
},
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "排除自身 id(更新时使用)"
}
],
"response": [],
"errors": []
},
{
"method": "setting.express.update",
"description": "更新快递映射,仅更新已实现字段(例如 name、platform)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "快递记录ID"
},
{
"name": "name",
"type": "string",
"required": false,
"source": "body",
"description": "快递名称"
},
{
"name": "platform",
"type": "string",
"required": false,
"source": "body",
"description": "平台标识(可选)"
}
],
"response": [],
"errors": []
}
]
},
{
"groupName": "快递接口管理模块",
"module": "setting.expressInterface",
"list": [
{
"method": "setting.expressInterface.list",
"description": "查询当前仓库范围的快递接口列表,支持 where + pagination;返回 data:{ list, total, page, page_size }。每条记录字段见 children。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize,兼容 currentPage / page_size / size"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;支持字段:id、name、express_code、platform_code、express_platform_id、sender_name、sender_tel、viewer、client_id、share_id、site_code、product_type、shop_name。支持 quickWhere 快速关键词。"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "快递接口记录数组(每项字段如下)",
"children": [
{
"name": "id",
"type": "number",
"description": "记录ID"
},
{
"name": "name",
"type": "string",
"description": "接口名称"
},
{
"name": "express_code",
"type": "string",
"description": "快递编码"
},
{
"name": "warehouse_id",
"type": "number",
"description": "所属仓库ID(文档中的仓库范围由系统强制校验)"
},
{
"name": "platform_code",
"type": "string",
"description": "平台代码"
},
{
"name": "express_platform_id",
"type": "number",
"description": "平台接口ID"
},
{
"name": "sender_name",
"type": "string",
"description": "发件人姓名"
},
{
"name": "sender_tel",
"type": "string",
"description": "发件人电话"
},
{
"name": "weight",
"type": "number",
"description": "默认重量"
},
{
"name": "token",
"type": "string",
"description": "接口密钥或 token(部分记录可能为空)"
},
{
"name": "viewer",
"type": "string",
"description": "查看者标识"
},
{
"name": "client_id",
"type": "string",
"description": "客户端 ID"
},
{
"name": "is_share",
"type": "number",
"description": "是否共享(0/1)"
},
{
"name": "share_id",
"type": "number",
"description": "共享记录ID"
},
{
"name": "can_use_count",
"type": "number",
"description": "可用次数或配额"
},
{
"name": "province_name",
"type": "string",
"description": "省"
},
{
"name": "city_name",
"type": "string",
"description": "市"
},
{
"name": "district_name",
"type": "string",
"description": "区/县"
},
{
"name": "site_code",
"type": "string",
"description": "站点编码"
},
{
"name": "product_type",
"type": "string",
"description": "快递产品类型"
},
{
"name": "shop_name",
"type": "string",
"description": "店铺名称/分组标识"
}
]
},
{
"name": "total",
"type": "number",
"description": "匹配的总记录数"
},
{
"name": "page",
"type": "number",
"description": "当前页"
},
{
"name": "page_size",
"type": "number",
"description": "每页数量"
}
],
"errors": [
{
"code": "400",
"description": "缺少仓库上下文或 where 参数解析失败"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "setting.expressInterface.create",
"description": "在当前仓库范围内创建快递接口,仅写入已实现字段(见 params),仓库由系统自动填充,禁止传入 warehouse_id/warehouseId。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "接口名称"
},
{
"name": "express_code",
"type": "string",
"required": true,
"source": "body",
"description": "快递编码(不区分大小写,会在服务端转为大写)"
},
{
"name": "platform_code",
"type": "string",
"required": true,
"source": "body",
"description": "平台代码(不区分大小写,会在服务端转为大写)"
},
{
"name": "express_platform_id",
"type": "number",
"required": true,
"source": "body",
"description": "平台接口 ID"
},
{
"name": "sender_name",
"type": "string",
"required": false,
"source": "body",
"description": "发件人姓名"
},
{
"name": "sender_tel",
"type": "string",
"required": false,
"source": "body",
"description": "发件人电话"
},
{
"name": "weight",
"type": "number",
"required": false,
"source": "body",
"description": "默认重量(可选)"
},
{
"name": "token",
"type": "string",
"required": false,
"source": "body",
"description": "接口密钥或 token"
},
{
"name": "viewer",
"type": "string",
"required": false,
"source": "body",
"description": "查看者标识"
},
{
"name": "client_id",
"type": "string",
"required": false,
"source": "body",
"description": "客户端 ID"
},
{
"name": "is_share",
"type": "number",
"required": false,
"source": "body",
"description": "是否共享(0/1)"
},
{
"name": "share_id",
"type": "number",
"required": false,
"source": "body",
"description": "共享记录 ID"
},
{
"name": "can_use_count",
"type": "number",
"required": false,
"source": "body",
"description": "可用次数/配额"
},
{
"name": "province_name",
"type": "string",
"required": false,
"source": "body",
"description": "省"
},
{
"name": "city_name",
"type": "string",
"required": false,
"source": "body",
"description": "市"
},
{
"name": "district_name",
"type": "string",
"required": false,
"source": "body",
"description": "区/县"
},
{
"name": "site_code",
"type": "string",
"required": false,
"source": "body",
"description": "站点编码"
},
{
"name": "product_type",
"type": "string",
"required": false,
"source": "body",
"description": "快递产品类型"
},
{
"name": "shop_name",
"type": "string",
"required": false,
"source": "body",
"description": "店铺名称/分组标识"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "新建记录 ID"
}
],
"errors": [
{
"code": "400",
"description": "必填参数缺失或参数格式错误"
},
{
"code": "409",
"description": "快递编码或平台接口组合已存在(冲突)"
}
]
},
{
"method": "setting.expressInterface.update",
"description": "更新快递接口,支持局部字段更新;支持 id 别名 interface_id / interfaceId;禁止通过接口修改 warehouse_id。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "快递接口ID;兼容 interface_id / interfaceId"
},
{
"name": "name",
"type": "string",
"required": false,
"source": "body",
"description": "接口名称"
},
{
"name": "express_code",
"type": "string",
"required": false,
"source": "body",
"description": "快递编码(更新时会被转为大写)"
},
{
"name": "platform_code",
"type": "string",
"required": false,
"source": "body",
"description": "平台代码(更新时会被转为大写)"
},
{
"name": "express_platform_id",
"type": "number",
"required": false,
"source": "body",
"description": "平台接口 ID"
},
{
"name": "sender_name",
"type": "string",
"required": false,
"source": "body",
"description": "发件人姓名"
},
{
"name": "sender_tel",
"type": "string",
"required": false,
"source": "body",
"description": "发件人电话"
},
{
"name": "weight",
"type": "number",
"required": false,
"source": "body",
"description": "默认重量"
},
{
"name": "token",
"type": "string",
"required": false,
"source": "body",
"description": "接口密钥或 token"
},
{
"name": "viewer",
"type": "string",
"required": false,
"source": "body",
"description": "查看者标识"
},
{
"name": "client_id",
"type": "string",
"required": false,
"source": "body",
"description": "客户端 ID"
},
{
"name": "is_share",
"type": "number",
"required": false,
"source": "body",
"description": "是否共享(0/1)"
},
{
"name": "share_id",
"type": "number",
"required": false,
"source": "body",
"description": "共享记录 ID"
},
{
"name": "can_use_count",
"type": "number",
"required": false,
"source": "body",
"description": "可用次数/配额"
},
{
"name": "province_name",
"type": "string",
"required": false,
"source": "body",
"description": "省"
},
{
"name": "city_name",
"type": "string",
"required": false,
"source": "body",
"description": "市"
},
{
"name": "district_name",
"type": "string",
"required": false,
"source": "body",
"description": "区/县"
},
{
"name": "site_code",
"type": "string",
"required": false,
"source": "body",
"description": "站点编码"
},
{
"name": "product_type",
"type": "string",
"required": false,
"source": "body",
"description": "快递产品类型"
},
{
"name": "shop_name",
"type": "string",
"required": false,
"source": "body",
"description": "店铺名称/分组标识"
}
],
"response": [
{
"name": "id",
"type": "number",
"description": "首条更新记录 ID"
},
{
"name": "name",
"type": "string",
"description": "更新后的接口名称"
}
],
"errors": [
{
"code": "400",
"description": "id 为空或无可更新字段"
},
{
"code": "404",
"description": "快递接口不存在或无权限操作"
},
{
"code": "409",
"description": "快递编码或平台接口组合冲突"
}
]
},
{
"method": "setting.expressInterface.delete",
"description": "删除快递接口,支持 id 别名 interface_id / interfaceId;返回被删除记录 id 与所属 warehouse_id。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "快递接口ID;兼容 interface_id / interfaceId"
}
],
"response": [
{
"name": "id",
"type": "number",
"description": "已删除记录 ID"
},
{
"name": "warehouse_id",
"type": "number",
"description": "记录所属仓库 ID"
},
{
"name": "deleted",
"type": "boolean",
"description": "是否已删除,成功时为 true"
}
],
"errors": [
{
"code": "400",
"description": "id 为空或格式错误"
},
{
"code": "404",
"description": "快递接口不存在或无权限操作"
}
]
}
]
},
{
"groupName": "账号管理模块",
"module": "setting.account",

View File

@ -1,7 +1,7 @@
{
"filePath": "D:\\wms\\runtime\\file-writer\\qimen-logs\\2026\\04\\12\\qimen-logs-MINGREN-worker-p42648-0001.log",
"filePath": "D:\\wms\\runtime\\file-writer\\qimen-logs\\2026\\04\\12\\qimen-logs-MINGREN-worker-p38224-0001.log",
"offset": 1713,
"processedCount": 1,
"completedAt": "2026-04-12T14:54:22.636Z",
"updatedAt": "2026-04-17T11:23:32.286Z"
"completedAt": "2026-04-12T14:46:52.525Z",
"updatedAt": "2026-04-27T08:09:00.255Z"
}