diff --git a/.github/agents/文档.agent.md b/.github/agents/文档.agent.md index be3c5df..7ca1a5e 100644 --- a/.github/agents/文档.agent.md +++ b/.github/agents/文档.agent.md @@ -38,9 +38,10 @@ model: GPT-5 mini (copilot) - 公共请求头变化 - 鉴权方式变化 - 每次 API 接口变更(新增 / 修改 / 删除 method、参数、响应、错误码、header、鉴权等)后,除了更新 `methods/*.json` / `docs/*.md`,**还必须追加一条变更记录到对应的 `methods/changes/.json` 数组** - - 默认禁止直接手写 `methods/*.json` / `methods/changes/*.json`,必须先按 `docs/api-doc-update-workflow.md` 生成固定 spec,再执行 `npm run doc:api:update -- --spec=` - - 正式写入前必须先执行 `npm run doc:api:update -- --spec= --dry-run` - - 修补 JSON 文件时必须强校验 JSON 格式正确性,确保不会引入无法解析的问题 + - 明确禁止直接手动编辑或提交 `methods/*.json` 与 `methods/changes/*.json` 文件。 + - 任何 PR 中直接修改这类文件的变更将被视为违规并可能被退回。所有对 methods JSON 的写入必须通过脚本完成,命令为 `npm run doc:api:update -- --spec=`(不可绕过)。 + - 正式写入前**必须**先执行 `npm run doc:api:update -- --spec= --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]` 开头 diff --git a/README.md b/README.md index 09584fc..d237237 100644 --- a/README.md +++ b/README.md @@ -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/ diff --git a/docs/api-doc-update-workflow.md b/docs/api-doc-update-workflow.md index eccf22b..c5e8343 100644 --- a/docs/api-doc-update-workflow.md +++ b/docs/api-doc-update-workflow.md @@ -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` \ No newline at end of file +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 +``` \ No newline at end of file diff --git a/methods/system.json b/methods/system.json index ee2ad0d..edbee82 100644 --- a/methods/system.json +++ b/methods/system.json @@ -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", diff --git a/runtime/file-writer/qimen-logs/.consume-progress b/runtime/file-writer/qimen-logs/.consume-progress index 076fe43..8ba54cd 100644 --- a/runtime/file-writer/qimen-logs/.consume-progress +++ b/runtime/file-writer/qimen-logs/.consume-progress @@ -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" }