[ { "version": "2026.09.25-index-upload-client-error-log", "date": "2026-09-25", "type": "added", "summary": "新增客户端错误日志上报接口 index.uploadClientErrorLog(免登录、免权限、免鉴权,保留系统日志):设备端运行时错误批量上报暂存到新表 wms_client_error_log。入参支持单条对象/数组/{ logs: [...] } 三种形态、单次最多 50 条;snake_case 为主并兼容 camelCase 别名;error_message/error_stack 至少一项有值(超长截断 5000/65535),extra 截断 65535;report_uuid 唯一索引幂等去重(重复静默成功,duplicated +1),缺失时服务端生成 srv-{uuid};client_time 仅参考(非法存 null)。成功返回 code=200 + total/accepted/duplicated/rejected/rejected_reasons(≤10) 统计;方法级错误 HTTP 200 + flag=failure(code=400/500)。配套迁移 database/migrations/20260925100000-create-wms-client-error-log.js、模型 app/model/client_error_log.js、服务 app/service/systems/client_error_log.js。", "methods": [ "index.uploadClientErrorLog" ], "notes": [ "变更类型:added(新增 method + 新增表);影响范围:methods/system.json 的 index(基础模块)分组 28 → 29 条,根版本 0.3.189 → 0.3.190、updatedAt 2026-09-24 → 2026-09-25;methods/changes/system.json 新增本条(插入数组首位)。", "入口与鉴权:POST /system?method=index.uploadClientErrorLog&v=1×tamp=<数字时间戳>(controller.home.system 统一入口);请求头需 platform、project(根 headers 已声明枚举),无 Authorization/token;方法已登记 _noNeedLogin/_noNeedRight/_noNeedAuth,且不在 INDEX_NO_NEED_LOG_METHODS 清单 → 保留系统日志(index 模块日志口径已由通配改为显式清单)。", "入参归一化口径(代码为准):三种形态三选一(单条对象 / 数组 / { logs: [...] },单次最多 50 条,超限 code=400);字段按 snake_case 读取并兼容 camelCase 别名(clientType/appVersion/deviceId/osVersion/deviceModel/errorType/errorMessage/errorStack/reportUuid/clientTime);字符串字段超宽截断:client_type 32、app_version 64、device_id 128、os_version 64、device_model 128、error_type 64、report_uuid 64;error_message 截断 5000、error_stack 截断 65535(两者至少一项有值,否则该条 rejected);extra 支持对象(JSON.stringify 后截断 65535);client_time 支持毫秒/秒时间戳(≥1e12 视为毫秒)与日期字符串,非法解析存 null。", "幂等语义:report_uuid 唯一索引 uk_report_uuid —— 写入前先查已有 uuid,重复项 duplicated +1 且不再写入(静默成功);客户端未传 report_uuid 时服务端生成 srv-{uuid},此时不做幂等去重、不保证幂等;created_at/updated_at 由 Sequelize 统一取服务器时间,不采信 client_time。", "表结构:wms_client_error_log —— id BIGINT(20) UNSIGNED 自增主键;client_type/app_version/device_id/os_version/device_model/error_type/report_uuid 为 STRING(32/64/128/64/128/64/64,NOT NULL DEFAULT '');error_message TEXT、error_stack MEDIUMTEXT、extra TEXT 可空;client_time/created_at/updated_at DATE(created_at/updated_at NOT NULL);索引 uk_report_uuid(唯一)、idx_created_at、idx_client_type_app_version、idx_device_id。", "出参(成功):{ flag:'success', code:200, message:'上报成功', success:true, total, accepted, duplicated, rejected, rejected_reasons(≤10 条,每条 { index, reason }), timestamp };失败(400/500):HTTP 200 + { flag:'failure', code, message, timestamp }。", "客户端接入示例(无需 token,仅需公共头 platform/project 与 query method/v/timestamp):curl -X POST 'https:///system?method=index.uploadClientErrorLog&v=1×tamp=1764000000' -H 'platform: app' -H 'project: wms' -H 'Content-Type: application/json' -d '{\"client_type\":\"android\",\"app_version\":\"1.2.3\",\"device_id\":\"dev-001\",\"os_version\":\"Android 14\",\"device_model\":\"Pixel 8\",\"error_type\":\"crash\",\"error_message\":\"NullPointerException\",\"error_stack\":\"...\",\"report_uuid\":\"uuid-2026-001\",\"client_time\":1763999999000}';Kotlin(OkHttp) 伪代码:RequestBody.create(MediaType.parse(\"application/json\"), JSONObject().apply{put(\"client_type\",\"android\");put(\"error_message\",\"...\");put(\"report_uuid\", UUID.randomUUID().toString())}.toString()),Request.Builder().url(\"$base/system?method=index.uploadClientErrorLog&v=1×tamp=${System.currentTimeMillis()/1000}\").header(\"platform\",\"app\").header(\"project\",\"wms\").post(body).build() —— 客户端应在本地生成 report_uuid 以保证重试幂等。", "前端/客户端是否需适配:是(仅客户端接入层)。既有 /system 前端无改动;android/ios/web 端需按上述示例补齐 platform/project 头与 method/v/timestamp query,并自行生成并持久化 report_uuid 以利用幂等;无 token 校验,无需改造登录态链路。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta,导出脚本 script/method-doc-export.cjs)。本次仅按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(遵循「只修改文档」红线,与 2026-09-24 变更记录口径一致)。后续需由维护者决定是否以 method-doc-create 将该方法入库并重新导出,否则下次执行 method-doc-export.cjs 会用库表重建 system.json 而丢失本条。", "发布顺序:迁移(20260925100000-create-wms-client-error-log)先于代码发布;迁移为纯建表、无回填,先迁移无风险。" ] }, { "version": "2026.09.24-return-unpack-notify-by-source", "date": "2026-09-24", "type": "updated", "summary": "拆包完成通知改为按原查询登记来源定向回信:_notifyUnpacked 不再按货主泛推售后群,改为按 wms_return_query_log 登记时记录的 group_id+user_id 聚合回信原查询群/用户(有用户信息时 writeOutboundReply 定向回原查询用户,否则退化为来源群系统通知);登记无来源群的记录不通知;仅推送成功的登记标记 is_notified=1。", "methods": [ "returnUnpack.submit" ], "notes": [ "代码位置:app/service/systems/return_unpack.js _notifyUnpacked(依赖此前新增的登记来源字段 group_id/group_name/user_id/user_name)", "回信链路与 video_record_request._replyResult 口径一致:批量反查 wms_inbox_group 补全 group_name/ext_data/store_id,缺失时用登记快照兜底;定向回信 source=ai_reply(wms_inbox_message 记录 user_id/user_name)" ] }, { "version": "2026.09.24-return-query-log-source-ids", "date": "2026-09-24", "type": "updated", "summary": "退回查询登记表 wms_return_query_log 新增登记来源字段 group_id/group_name/user_id/user_name(迁移 20260924160000-add-source-ids-to-wms-return-query-log):站内信「查退回」触发登记时写入查询来源群/用户信息,用于登记追溯与后续定向通知;returnWaybill.create/list/detail 响应记录同步包含新字段(后台登记路径为 null)。", "methods": [ "returnWaybill.create", "returnWaybill.list", "returnWaybill.detail" ], "notes": [ "代码位置:app/model/return_query_log.js 新增 4 字段;app/service/systems/return_unpack.js queryByWaybill 增加可选入参并在 received/not_returned 两处自动登记时写入来源;app/service/inbox/functions.js queryReturn 透传 ctx.inboxContext 的 group_id/group_name/user_id/user_name", "迁移执行:npx sequelize-cli db:migrate(生产:$env:NODE_ENV='production'; npx sequelize-cli db:migrate --migrations-path database/migrations --env production)", "库表化维护:method-doc-update.cjs 更新 3 个方法 response 说明并 --bump 至 0.3.184,method-doc-export.cjs 回写 methods/system.json" ] }, { "version": "2026.09.24-big-group-pack-coefficient-desc", "date": "2026-09-24", "type": "updated", "summary": "大团购打包系数字段描述统一:subject_config.big_group_pack_coefficient 描述更新为「大团购波次(wave_scope=1)打包中,扫描其他波次订单至少需等待「当前波次打包数 × 系数」秒,单位:秒/单,默认 3,必须大于 0」", "methods": [ "setting.warehouse.getSettings" ], "notes": [ "字段元信息 app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS)中 big_group_pack_coefficient 的 description 已与该口径一致,无代码变更" ] }, { "version": "2026.09.24-workbench-big-group-pack-member-divide", "date": "2026-09-24", "type": "updated", "summary": "大团购打包时长按人数分摊:workbench.packOrder 倒计时字段 pack_wait_seconds 与 workbench.queryOrder 闸门等待秒数改为「大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数」;拉取当前打包任务时仅统计进行中任务(status<2,任务已结束则不计);人数为 0 时任务已被成员全部登出流程自动结束,不会出现,仍按 1 兜底防除零", "methods": [ "workbench.packOrder", "workbench.queryOrder" ], "notes": [ "代码位置:app/service/systems/workbench.js(_packOrder 倒计时按 users 成员数分摊、_queryOrder 闸门按 _countCurrentPackMembers 统计 wms_workbench_member 人数分摊)", "回归测试:test/app/service/systems/workbench.bigGroupTimeGate.regression.test.js 新增人数分摊用例(打包 2 人 1×3/2=1.5 秒、闸门 3 人 10×3/3=10 秒),共 13 用例全绿" ] }, { "version": "2026.09.24-setting-big-group-pack-coefficient", "date": "2026-09-24", "type": "updated", "summary": "仓库设置新增大团购打包系数:subject_config 新增 big_group_pack_coefficient(数字,默认 3,单位秒/单,必须大于 0),用于 workbench 大团购波次打包时长闸门与倒计时;setting.warehouse.getSettings 响应新增该字段说明,getFieldMeta 字段元信息列表同步新增该项", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta" ], "notes": [ "代码位置:app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS 新增字段元信息:type=number、default=3、min=0.1);app/model/store.js(DEFAULT_SUBJECT_CONFIG 与 normalizeSubjectConfig 校验:空值回填 3,非法值抛错)", "读取链路:app/service/systems/delivery_order.js getStoreSubjectConfig(带缓存),workbench 侧经 _getBigGroupPackCoefficient 读取,异常/非法降级默认 3", "无需数据库迁移:配置存于 wms_store.subject_config(JSON 字段),仅需代码发布" ] }, { "version": "2026.09.24-workbench-big-group-pack-gate", "date": "2026-09-24", "type": "updated", "summary": "工作台大团购打包系数与打包时长闸门:workbench.packOrder 打包任务落库 wave_scope,大团购波次(wave_scope=1)响应新增倒计时字段 pack_wait_seconds(当前波次打包数 × 大团购打包系数,单位秒)与 pack_start_time(开始打包时间,毫秒时间戳),其他波次均为 0;workbench.queryOrder 响应 order 新增 wave_scope,并新增大团购打包时长闸门(当前工作台 wave_scope=1 任务未到时仅允许查询本波次订单,其他波次返回「打包时长不足」错误)", "methods": [ "workbench.packOrder", "workbench.queryOrder" ], "notes": [ "数据库迁移:wms_pack_task 新增 wave_scope 列(database/migrations/20260924150000-add-wave-scope-to-pack-task.js,幂等),开发库与生产库均已执行(生产库因存在更早 pending 迁移改为等价 DDL + SequelizeMeta 记录)", "代码位置:app/service/systems/workbench.js(_queryOrder 步骤3.5 闸门、_packOrder 落库与倒计时下发、_getBigGroupPackCoefficient 配置读取);app/model/pack_task.js 新增 wave_scope 字段定义", "回归测试:test/app/service/systems/workbench.bigGroupTimeGate.regression.test.js(11 用例全绿:响应 wave_scope / packOrder 落库与倒计时 / 闸门未到时同波次放行、不同波次拦截、已到时放行、其他 wave_scope 不限制)" ] }, { "version": "2026.09.24-front-config-domain-verify", "date": "2026-09-24", "type": "updated", "summary": "前端独立部署新增「域名归属验证」能力:新增设置/查询/校验域名的 3 个接口(frontConfig.setDomain/getDomain/checkDomain,均需登录、免权限、免鉴权、仅仓库主体可用);两个保存接口不再负责设置域名(saveCert 移除 domain 入参);新增域名验证闸门(getByDomain 仅放行 domain_status=1 的已验证域名、nginx 侧仅对已验证域名生成 server 块);getCert/saveCert 响应新增证书可设置性字段(10 → 13 字段:can_set_cert/can_set_cert_reason/domain_status)。", "methods": [ "frontConfig.setDomain", "frontConfig.getDomain", "frontConfig.checkDomain", "frontConfig.getByDomain", "frontConfig.getCert", "frontConfig.saveCert" ], "notes": [ "数据表与迁移:wms_warehouse_front_config 新增列 domain_status(tinyint 默认 0)/domain_verify_host/domain_verify_token/domain_verified_at/domain_verify_attempts/domain_last_error 与索引 idx_domain_status;迁移文件 database/migrations/20260924120000-add-domain-verify-to-wms-warehouse-front-config.js(幂等:列/索引已存在则跳过)。迁移会把历史非空 domain 的行回填 domain_status=1:存量域名在线上已生效(nginx 已在按域名提供服务),不回填会被新闸门在升级瞬间全部断流(证书上传被拒、公共拉取 404);回填只在真正新增该列的那一次执行,避免把升级后新设但未验证的域名误标为已验证;domain_verified_at 保持 NULL(历史生效时间不可考,不写虚假时间)", "定时任务:新增 app/schedule/domain_verify_scan.js,按 config.frontConfig.domainVerify.interval(默认 10m)扫描待验证行;配置项 enable(true)/interval(10m)/lockTtlSeconds(600)/batchSize(50)/dohUrl(https://doh.pub/dns-query)/timeoutMs(5000)/maxAttempts(20);并发控制为进程内重入标志(ctx.app._domainVerifyScanRunning)+ Redis SET NX EX 跨进程互斥锁(Redis 不可用/抛错时降级为仅进程内防重入并 WARN);业务逻辑全部委托 service.systems.frontConfig.verifyPendingDomains(schedule 内不写 SQL);单行解析/落库失败只计入 errors 不中断整轮;已达 maxAttempts 的行不再自动重试(计入 skipped,仍可由 checkDomain 手动触发)", "DNS 解析:DoH 为主(config.frontConfig.domainVerify.dohUrl,默认 https://doh.pub/dns-query;Status=3 或无 Answer 视为未解析到记录,不重复走系统 DNS),失败降级系统 DNS(node:dns,本仓首次引入,仅服务域名验证链路);校验目标一律为一次性子域 wmsv-<10 位 hex>.<域名>,避免与用户主域已有 TXT 记录(SPF/DKIM/站点校验等)冲突", "配置新增 config.frontConfig.cname(默认空字符串):域名未通过验证时随 getDomain/setDomain/checkDomain 响应返回给前端,提示用户把域名 CNAME 指向该目标", "nginx 侧联动(未改动本次文档范围,仅记录):script/warehouse-cert-sync.cjs 扫描待同步记录时新增 domain_status = 1 过滤(无该列时降级为不过滤并 WARN);script/deploy-cert-sync.cjs 探针新增 domain_status 列探测与取值分布/计数输出(0_unverified/1_verified/2_failed 与 gated-out 行数)", "前端必须改造(不兼容变更):域名设置从 saveCert 迁移到 setDomain —— saveCert 已删除 domain 入参,前端若继续传 domain 会被静默忽略且不再变更域名;正确顺序为 setDomain → 按 verify_host/verify_value 配置 TXT 记录(并按 cname 配置 CNAME)→ checkDomain 手动校验或等待定时任务 → domain_status=1 后才可 saveCert 上传证书;getCert/saveCert 响应新增 can_set_cert/can_set_cert_reason/domain_status,供上传入口置灰与提示文案", "风险提示:config.frontConfig.domainVerify.enable = false 时 app/schedule/domain_verify_scan.js 标记 disable、Egg 不注册该任务,新域名只能靠前端调用 checkDomain 手动触发才会放行;迁移尚未执行时 getByDomain 闸门降级为仅按 domain 查询(一次性 WARN),需迁移完成并重启实例后闸门才真正生效;getByDomain 命中配置缓存最长 600s 内仍可能放行刚被置为未验证的域名(setDomain/saveCert/校验成功均已主动清缓存,实际窗口极短,接受该取舍)", "文档变更:methods/system.json 的 frontConfig 分组新增 3 条(setDomain/getDomain/checkDomain,均 isNeedLogin=true、isNeedAuth=false、带 Authorization 头)+ 更新 3 条(getByDomain 描述补充闸门语义与迁移降级说明,params/response/errors 未变;getCert 响应 10 → 13 字段;saveCert 删除 domain 入参、新增前置闸门、response 10 → 13 字段、errors 同步收敛);spec.methods 只放上述 6 条,未放入 getInfo/saveInfo(避免整条覆盖造成语义漂移);未使用 deleteMethods;根版本 0.3.178 → 0.3.179,updatedAt 保持 2026-09-24", "已知遗留(本次未处理,建议下一批单独修正):frontConfig.getInfo 与 frontConfig.saveInfo 的描述仍写「domain 只能通过 frontConfig.saveCert 变更」,实际域名变更已收敛到 frontConfig.setDomain;这两条不在本批 spec.methods 内(避免整条覆盖),故未同步", "变更记录条目数 640 → 641(新记录插入数组首位,既有 640 条 version 未改动、未删除)", "维护源口径冲突(仅记录,未处理):与上一轮维持一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库", "自动清单刷新:node temp/tmp-gen-service-method-inventory.cjs 与 node temp/tmp-update-ai-method-routing.cjs(AI_METHOD_ROUTING.md 第 6 节 SERVICE_METHOD_INVENTORY 标记区与 temp/tmp-service-method-inventory.md 同步刷新)", "docs/*.md 无需同步:检索 frontConfig/setDomain/checkDomain/域名验证 未命中解释性文档(仅 AI_METHOD_ROUTING.md 与 temp/tmp-service-method-inventory.md 含自动清单命中,已由刷新脚本处理)" ], "module": "frontConfig" }, { "version": "2026.09.24-front-config-saveCert-response-fix", "date": "2026-09-24", "type": "updated", "summary": "修正 frontConfig.saveCert 的响应契约:由错误的 8 字段品牌口径(buildInfoOutput:warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/updated_at)更正为 10 字段证书口径(buildCertOutput,与 frontConfig.getCert 一致:warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at);入参 domain/pem/key 与错误码 400/403/409/500 口径不变,其余 frontConfig 条目(getInfo/getCert/saveInfo/getByDomain)未改动。本记录闭环 2026.09.24-front-config-migrate-to-frontConfig 中标注的「saveCert 响应口径待确认」一项。", "methods": [ "frontConfig.saveCert" ], "notes": [ "闭环说明:本记录闭环 2026.09.24-front-config-migrate-to-frontConfig 中标注的「saveCert 响应口径待确认」一项(该记录 notes 第 6 条:JSDoc 声明返回 10 字段证书输出,但实现实际 return this.buildInfoOutput(...) 返回 8 字段品牌信息);按工作流「新记录插入数组头部、历史记录不回改」,原记录保持原样,修正以本记录承接", "代码证据:app/service/systems/frontConfig.js:782 saveCert 出口 return this.buildCertOutput(savedRecord, warehouseId);buildCertOutput 定义于同文件 :202,输出 10 字段 warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at(其中 key_pem 读 cert_key 列)", "由 wms-dev-agent 修正实现(saveCert 返回由 buildInfoOutput 改为 buildCertOutput),本次仅同步文档口径,未改动任何代码", "文档变更:methods/system.json 的 frontConfig 分组仅更新 saveCert 一条(spec.methods 只放这一条,未放入 getInfo/getCert/saveInfo/getByDomain,避免整条覆盖造成语义漂移;未使用 deleteMethods);响应字段 8 -> 10,method 级 notes 中「响应口径待确认」一条被替换为「响应契约修正」;headers/params/errors 沿用既有条目不变;根版本 0.3.177 -> 0.3.178,updatedAt 保持 2026-09-24", "通配语义同步写准:certCoversDomain 的 *.example.com 分支(app/service/systems/frontConfig.js:512)要求通配前缀非空且不含「.」,即仅覆盖恰好一级标签;*.a.com 覆盖 b.a.com,不覆盖 x.y.a.com(报 400「证书不合法」)", "变更记录条目数 639 -> 640(新记录插入数组首位,既有 639 条 version 未改动、未删除);script/update-api-doc.cjs 的 appendChange 仅支持 unshift + 重复 version 拦截,无整条替换既有 change 的能力,故未回改上一条记录的 note", "无代码结构变化,未重新生成 AI_METHOD_ROUTING.md 与 temp/tmp-service-method-inventory.md(上一轮已刷新,本次仅文档响应口径修正)", "维护源口径冲突(仅记录,未处理):与上一轮维持一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库" ], "module": "frontConfig" }, { "version": "2026.09.24-front-config-migrate-to-frontConfig", "date": "2026-09-24", "type": "updated", "summary": "前端独立部署接口从 setting.warehouse 迁移到 frontConfig 模块:删除 setting.warehouse.getFrontConfig / saveFrontConfig / saveFrontCert 三个旧方法(出口、服务实现与鉴权白名单同步移除,实测调用返回「方法 xxx 不存在」),新增 frontConfig.getInfo / getCert / saveInfo / saveCert 四个需登录、免权限、免鉴权的配置接口(权限由业务层 isWarehouse 判定,仅仓库主体可用);公共按域名拉取接口 frontConfig.getByDomain 保持不变(仍 6 字段公开白名单,免登录免权限免鉴权)。", "methods": [ "frontConfig.getInfo", "frontConfig.getCert", "frontConfig.saveInfo", "frontConfig.saveCert", "setting.warehouse.getFrontConfig", "setting.warehouse.saveFrontConfig", "setting.warehouse.saveFrontCert" ], "notes": [ "代码变更:新增出口 app/service/systemMethods/frontConfig.js 的 getInfo/getCert/saveInfo/saveCert(_noNeedRight/_noNeedAuth/_noNeedLog 均含这 4 个方法;_noNeedLogin 仍仅 getByDomain),实现见新增服务 app/service/systems/frontConfig.js(TEXT_FIELDS/PUBLIC_FIELDS 白名单、buildInfoOutput/buildCertOutput/buildPublicOutput)", "代码变更:app/service/systemMethods/setting/warehouse.js 与 app/service/systems/setting/warehouse.js 中 getFrontConfig/saveFrontConfig/saveFrontCert 的出口与实现已删除,_noNeedRight 收敛为 getSettings,getFieldMeta,saveSettings,getweChatApp;methods/system.json 中 setting.warehouse 分组仅删除这 3 条条目,分组与 getSettings/getFieldMeta/saveSettings 保留", "文档变更:methods/system.json 删除 setting.warehouse 分组下 3 条旧条目(原 L15632 saveFrontConfig / L15797 getFrontConfig / L15914 saveFrontCert),frontConfig 分组(groupName 前端独立部署模块)新增 4 条条目(isNeedLogin=true、isNeedAuth=false、Authorization 头);frontConfig.getByDomain 条目未改动(未放入本次 spec.methods,避免整条覆盖造成语义漂移);根版本 0.3.176 -> 0.3.177,updatedAt 2026-09-23 -> 2026-09-24", "saveInfo 口径:upsert 一仓一行;仅受理 title(≤100)/logo_url、favicon_url、login_bg_url(≤255)/theme(合法 JSON 对象或 JSON 字符串),domain 与证书字段由方法层白名单静默忽略;保存即重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at);写库成功后清当前 domain 公共拉取缓存(清缓存失败仅记日志)", "saveCert 口径:校验链 证书可解析 → 未生效拒绝 → 已过期拒绝 → 私钥与证书 SPKI 配对 → 证书 SAN/CN 覆盖 domain(支持 *.example.com 通配,仅匹配一级标签) → domain 全局唯一;校验链任一失败统一 400「证书不合法」不吐细节;cert_expire_at 以证书 validTo 权威写入;cert_pem/cert_key 直接入库、cert_path/key_path 置 null(等待 script/warehouse-cert-sync.cjs 部署后回填);写库后同时清旧 domain 与新 domain 两个公共缓存 key", "响应口径待确认:app/service/systems/frontConfig.js saveCert 的 JSDoc(及方法层注释)声明返回证书输出(10 字段含 cert_pem/key_pem),但实现实际 return this.buildInfoOutput(...) 返回 8 字段品牌信息、不含证书字段;本文档按当前实现(8 字段)编写,若确认应返回证书输出需先修正实现再同步文档", "维护源口径冲突(仅记录,未处理):methods/changes/system.json 既有记录备注「维护源是数据库表 wms_method_doc_meta,methods/*.json 只是导出产物」,仓库内已存在 script/method-doc-*.cjs 工具链与迁移 database/migrations/20260923150000-create-method-doc-tables.js;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,待用户决策是否需要回灌数据库维护源", "自动清单刷新:node temp/tmp-gen-service-method-inventory.cjs 与 node temp/tmp-update-ai-method-routing.cjs(AI_METHOD_ROUTING.md 第 6 节 SERVICE_METHOD_INVENTORY 标记区与 temp/tmp-service-method-inventory.md 同步刷新,会顺带更新扫描时间与文件/方法计数,属脚本预期行为)", "docs/*.md 与 README.md 无需同步:检索 getFrontConfig/saveFrontConfig/saveFrontCert/前端独立部署/frontConfig/getByDomain 未命中任何解释性文档(仅 AI_METHOD_ROUTING.md 与 temp/tmp-service-method-inventory.md 含自动清单命中,已由刷新脚本处理)" ], "module": "frontConfig" }, { "version": "2026.09.23-returnReceived-create-is-urgent", "date": "2026-09-23", "type": "updated", "summary": "returnReceived.create 响应新增 is_urgent 加急标记(boolean):wms_return_query_log(退回查询记录表)按 仓库+运单号 精确匹配,命中即 true,未命中或查询失败降级为 false;幂等命中(duplicated=true)与新创建(duplicated=false)两个分支均返回该字段", "methods": [ "returnReceived.create" ], "notes": [ "代码变更:app/service/systems/return_received.js 的 create 在幂等命中与新登记两个返回分支均新增顶层 is_urgent 字段,并新增私有辅助方法 _isUrgentReturnQuery(waybillCode, warehouseId)(含 JSDoc)", "判定口径:wms_return_query_log(退回查询记录表)中存在 warehouse_id=当前仓库且 waybill_code=登记运单号(精确匹配)的记录时为 true,否则 false;查询失败降级为 false,不影响登记主流程", "方法层 app/service/systemMethods/returnReceived.js 无需改动;文档变更:response 新增 is_urgent(boolean,required=true);维护源 wms_method_doc_meta 与导出产物 methods/system.json 版本同步至 0.3.176(dashboard.hot_order_rank mask 变更同步入库 0.3.175,本次变更升至 0.3.176)" ], "module": "returnReceived" }, { "version": "2026.09.23-dashboard.hot_order_rank.mask", "date": "2026-09-23", "type": "updated", "summary": "dashboard.hot_order_rank 响应口径调整:data[].sku 由商品编码改为库存商品ID(stock_warehouse.id);data[].name 做脱敏处理(前2字符+***+后2字符,长度不足 4 字符时返回 ***)", "methods": [ "dashboard.hot_order_rank" ], "notes": [ "代码变更:app/service/systemMethods/dashboard.js 中 buildHotOrderRankMap/mergeHotOrderRank 的聚合条目新增 stockId(订单明细 stock_id),并在货主端跨仓合并时保留首个非 0 值", "代码变更:resolveHotOrderRankProduct 的 sku 改为返回库存商品ID(number,stock_warehouse.id),仅当 stock_id 缺失时回退商品编码字符串;新增 maskHotOrderRankName 对最终展示名称统一脱敏(长度>=4 时前2字符+***+后2字符,否则返回 ***)", "文档变更:data[].sku 类型改为 number 并更新描述;data[].name 描述补充脱敏规则;根版本 0.3.174 -> 0.3.175" ], "module": "dashboard" }, { "version": "2026.09.23-returnReceived-list-created-at-filter", "date": "2026-09-23", "type": "updated", "summary": "修复 returnReceived.list 登记时间(created_at)筛选不生效问题:_buildListWhere 白名单补充 created_at/updated_at,并补齐文档此前缺失但代码已支持的 where 字段(scanner_name/order_express_id/order_id);returnReceived.export 的 where 语义描述同步更新(与 list 一致)。配套新增 wms_return_received 索引 idx_warehouse_created_at(warehouse_id, created_at)(迁移 20260923180000),优化登记时间范围过滤与默认 created_at desc 排序。", "methods": [ "returnReceived.list", "returnReceived.export" ], "notes": [ "代码变更:app/service/systems/return_received.js _buildListWhere 的 directFields 白名单补充 created_at、updated_at(list 与 exportList 同时生效)", "数据库变更:database/migrations/20260923180000-add-created-at-index-to-wms-return-received.js 新增 idx_warehouse_created_at(warehouse_id, created_at),已在开发库执行", "文档变更:returnReceived.list 新增 where.created_at / where.updated_at / where.scanner_name / where.order_express_id / where.order_id 参数说明,description 更新;returnReceived.export 的 where 参数描述补充 created_at/updated_at 范围", "文档库版本 0.3.173 -> 0.3.174(wms_method_doc_meta.version),methods/system.json 为导出产物" ] }, { "version": "2026.09.23-dashboard.hot_order_rank.realtime", "date": "2026-09-23", "type": "updated", "summary": "dashboard.hot_order_rank 由演示数据改为真实数据库查询:统计今日(00:00 至当前时刻)销量 Top10 商品及环比昨日趋势;仓库端单仓统计,货主端跨已签约仓库聚合", "methods": [ "dashboard.hot_order_rank" ], "notes": [ "核实 app/service/systemMethods/dashboard.js 实现后更新:废弃旧版 mock 数据,改为查询订单常用表/配送分表(OrderDeliveryFactory/OrderItemsFactory 的 current 与 dispatch)聚合", "口径:今日窗口 [今日 00:00, 当前时刻),昨日窗口 [昨日 00:00, 今日 00:00);value 为窗口内非取消、非异常、未删除订单的商品计划数量(plan_qty)合计;trend 为环比昨日百分比(保留 1 位小数,昨日为 0 且今日 >0 时按 100)", "仓库端使用 ctx.user.store_id 单仓统计;货主端(store_type=store)跨已签约仓库(auth_status=2)并行统计并按商品聚合;按今日销量降序取前 10 条,无数据时返回空数组", "响应更新:data[].name 无名称回退商品编码/商品+库存ID、data[].sku 无编码回退 SKU+库存ID;错误码补充 code=0(缺少仓库/货主上下文),500 改为订单数据查询失败", "文档库表同步:method-doc-update.cjs 更新 description/response/errors 并 --bump,method-doc-export.cjs 回写 methods/system.json" ], "module": "dashboard" }, { "version": "2026.09.23-dashboard.charts.doc", "date": "2026-09-23", "type": "updated", "summary": "补齐看板模块其余 5 个接口文档:express_ratio/platform_distribution/order_trend 为实时统计接口,warehouseStats/hot_order_rank 为演示数据接口(描述已标注);均无业务入参", "methods": [ "dashboard.express_ratio", "dashboard.platform_distribution", "dashboard.order_trend", "dashboard.warehouseStats", "dashboard.hot_order_rank" ], "notes": [ "核实 app/service/systemMethods/dashboard.js 实现后补齐", "express_ratio/platform_distribution 货主端跨已签约仓库(auth_status=2)汇总,返回 name/value/itemStyle.color 结构", "order_trend 按小时统计 08:00 至当前小时,返回 summary/categories/orders/shipments", "warehouseStats/hot_order_rank 当前为固定演示数据,待业务接入真实统计后需同步更新文档" ] }, { "version": "2026.09.23-dashboard.storeStats.doc", "date": "2026-09-23", "type": "updated", "summary": "补齐 dashboard.storeStats 接口文档:补充描述、13 个响应统计字段与错误码(无业务入参,依据登录用户上下文区分仓库端/货主端)", "methods": [ "dashboard.storeStats" ], "notes": [ "核实 app/service/systemMethods/dashboard.js 实现后补齐", "仓库端按当前用户 store_id 单仓统计;货主端跨已签约仓库(auth_status=2)汇总" ] }, { "version": "2026.09.23-index.tryAutoTranslateNewKeys.doc", "date": "2026-09-23", "type": "updated", "summary": "补全 index.tryAutoTranslateNewKeys 文档:明确其为 putI18nCollect 的内部辅助方法,补充 project/targetLanguage 参数说明,注明无对外返回值、异常仅记日志、不建议作为 HTTP API 直接调用", "methods": [ "index.tryAutoTranslateNewKeys" ], "notes": [ "代码事实:app/service/systemMethods/index.js:1512 async tryAutoTranslateNewKeys(project, targetLanguage),仅被 putI18nCollect(1451 行)内部调用;目标语言为 zh-CN 直接返回;为 zh-CN 已有翻译的键批量创建目标语言占位(translation=null、translation_status=0、auto_generated=1、translator=auto-translate);无返回值,异常被内部 try/catch 吞掉仅记日志。", "文档库表同步:method-doc-update.cjs 更新 description/params 并 --bump(版本 0.3.169 -> 0.3.170),method-doc-export.cjs 回写 methods/system.json(562 个方法)。", "说明:/system 通用分发不区分 public 与内部函数,该方法理论上可被直接调用,文档已注明不建议直接调用。" ], "module": "index" }, { "version": "2026.09.23-wechat.dropAgreementVersionNumber", "date": "2026-09-23", "type": "updated", "summary": "用户须知版本表去掉 version 数字版本号,直接使用 id 自增:最新版判定改 ORDER BY id DESC,提交即插入新行(去掉 max+1 与并发重试),接口响应只保留 version_id", "methods": [ "wechat.getUserAgreementText", "wechat.getUserAgreement", "wechat.setUserAgreement", "wechat.getAgreementVersion", "wechat.loginByCode" ], "notes": [ "迁移 20260923140000-drop-version-from-wechat-agreement-version(开发+生产均执行):removeIndex uk_appid_version + removeColumn version;down 为加回列与唯一索引。同步 app/model/wechat_agreement_version.js 删 version 字段与唯一索引(仅保留 idx_appid)。", "最新版判定统一为 ORDER BY id DESC(loginByCode/getUserAgreementText/getUserAgreement/findLatestAgreementVersion/cleanupUnusedAgreementVersions 的最终版=max(id));setUserAgreement 改为直接 create(appid+content),无并发重试;getUserAgreementText 缓存 JSON 仅 {version_id,text}。", "接口响应精简:getUserAgreementText/getUserAgreement/setUserAgreement 去掉 version 字段、getAgreementVersion 去掉 version 字段,均保留 version_id(=记录 id)。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.getAgreementVersion", "date": "2026-09-23", "type": "added", "summary": "新增 wechat.getAgreementVersion(按协议版本 id 获取协议内容,需登录免权限+校验仓库);wechat.userList 响应新增 agreement_version_id(协议id)", "methods": [ "wechat.getAgreementVersion", "wechat.userList" ], "notes": [ "wechat.getAgreementVersion:入参 id(wms_wechat_agreement_version.id,来源 userList 的 agreement_version_id),按 id 查版本 → 校验该版本 appid 属于当前仓库启用小程序(warehouse_id=ctx.user.store_id, is_enabled=1),不属于则提示「该协议版本不属于当前仓库的小程序」;返回 id/appid/nickname/version/text/created_at。需登录免权限(systemInit 第2/4参)。", "wechat.userList:响应行新增 agreement_version_id(数值化,null 保持 null),sortField 白名单新增 agreement_version_id;该字段由 loginByCode 自动回写,供前端按版本 id 拉取协议内容。", "代码变更:app/service/systems/wechat.js 新增 getAgreementVersion + userList 响应数值化/排序白名单;app/service/systemMethods/wechat.js 白名单与出口同步。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.agreementVersionCleanup", "date": "2026-09-23", "type": "updated", "summary": "新增定时任务:每 1 小时扫描 wms_wechat_agreement_version,真实删除未使用且非对应 appid 最终版的历史版本,释放 MySQL 磁盘", "methods": [], "notes": [ "保留规则:① 各 appid 的最终版(version 最大)永久保留;② 被 wms_user_oauth.agreement_version_id 引用的版本保留(老用户仍停留在旧协议);其余版本真实删除(模型 paranoid=false)。", "触发:app/schedule/wechat_agreement_cleanup.js,cron 从 config.wechatAgreementCleanup.cron 读取(默认 0 0 * * * * = 每 1 小时整点,type=worker 单 worker 防重入,enable=false 不注册);清理逻辑收敛在 service.systems.wechat.cleanupUnusedAgreementVersions(batchSize 默认 500,按 id 分批删走主键索引)。", "每次任务完成后输出日志:deleted/kept_latest/kept_in_use/total;失败仅记 error 日志不抛出。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.userAgreement.versioning", "date": "2026-09-23", "type": "updated", "summary": "用户须知改为副表版本管理:移除 wms_wechat_app.user_agreement;新增 wms_wechat_agreement_version(appid+数字版本号+富文本,提交一次自动新增版本,拉取只取最新);wms_user_oauth 加 agreement_version_id,loginByCode 自动更新到最新协议版本", "methods": [ "wechat.getUserAgreementText", "wechat.getUserAgreement", "wechat.setUserAgreement", "wechat.loginByCode" ], "notes": [ "迁移 20260923130000-user-agreement-versioning(开发+生产均执行):① removeColumn wms_wechat_app.user_agreement;② createTable wms_wechat_agreement_version(id/appid/version INT/content LONGTEXT/时间戳,uk_appid_version(appid,version) 唯一 + idx_appid);③ addColumn wms_user_oauth.agreement_version_id(BIGINT UNSIGNED 可空,关联版本表 id)。同步 app/model/wechat_agreement_version.js 新增、wechat_app.js/user_oauth.js 字段同步。", "wechat.setUserAgreement:提交一次自动新增版本——查该 appid 最大 version 后 +1 插入(并发撞唯一键时重算重试最多 3 次),成功后 cacheDel 清 24h 缓存;返回 version_id/version/text。", "wechat.getUserAgreementText/getUserAgreement:拉取只拉最新版本(ORDER BY version DESC);getUserAgreementText 缓存 24h 存 JSON {version_id,version,text},命中 from_cache=true;无版本分别提示「未找到对应小程序或该小程序暂无用户须知」/「该小程序暂无用户须知」。", "wechat.loginByCode:查该小程序 appid 最新协议版本 id,oauth 新增/更新时自动写入 agreement_version_id(无需前端传入,为空版本表时为 null)。", "代码变更:app/service/systems/wechat.js loginByCode/getUserAgreementText/getUserAgreement/setUserAgreement 改版并新增 findLatestAgreementVersion;systemMethods 无签名变化。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.userAgreement", "date": "2026-09-23", "type": "added", "summary": "新增用户须知三接口:wms_wechat_app 加 user_agreement(LONGTEXT)字段;wechat.getUserAgreementText(免登录,appId 查询 + 24h Redis 缓存)、wechat.getUserAgreement(需登录,当前仓库)、wechat.setUserAgreement(需登录,更新并清缓存)", "methods": [ "wechat.getUserAgreementText", "wechat.getUserAgreement", "wechat.setUserAgreement" ], "notes": [ "迁移 20260923120000-add-user-agreement-to-wms-wechat-app:wms_wechat_app 仅加 user_agreement 字段(Sequelize TEXT('long') = LONGTEXT,allowNull,comment 用户须知富文本),同步 app/model/wechat_app.js。开发+生产均需执行(生产:$env:NODE_ENV='production'; npx sequelize-cli db:migrate --migrations-path database/migrations --env production)。", "wechat.getUserAgreementText:免登录(systemInit 第1参),入参 appId;Redis key wechat:userAgreement:{appid},TTL 24h,命中直接返回 from_cache=true;未命中查 wms_wechat_app.user_agreement 并回写缓存;无该 appid 返回「未找到对应小程序」。", "wechat.getUserAgreement/setUserAgreement:需登录免权限(systemInit 第2/4参),按 ctx.user.store_id 取启用小程序(is_enabled=1),无则提示「无小程序,需要先绑定」;set 校验 text 为字符串(可空串清空)→ update 后 cacheDel 清除 24h 缓存。", "代码变更:app/service/systems/wechat.js 新增 getUserAgreementText/getUserAgreement/setUserAgreement/findWarehouseWechatApp;app/service/systemMethods/wechat.js 白名单与出口同步。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.bindByEmployee", "date": "2026-09-23", "type": "added", "summary": "新增 wechat.bindByEmployee:管理员按工号绑定微信(需登录需权限),传工号 id + 微信绑定记录 id,查工号账号 id 写入 wms_user_oauth.user_id", "methods": [ "wechat.bindByEmployee" ], "notes": [ "新增接口 wechat.bindByEmployee(需登录需权限,区别于中间层 wechat.bindUser 的用户名密码自绑定):入参 id(工号 id=wms_account_store_employee.id,必填正整数)与 oauth_id(微信绑定记录 id=wms_user_oauth.id,必填正整数,来自 wechat.userList 结果)。", "业务:工号存在且 status=1 → account_id;工号须属于当前仓库(store_id=ctx.user.store_id);oauth 须存在、provider=wechat、未绑定或已绑定同一账号(已绑其他账号拒绝换绑);oauth.app_id 存在时校验对应 wms_wechat_app 属于当前仓库;账号存在且 status=1。校验通过后 wms_user_oauth.user_id=account_id,幂等返回 already_bound。不签发 token。", "鉴权:不加入 systemInit 任何白名单 → 需正常登录 token 且需 wms_permission 接口权限(path=wechat.bindByEmployee,type=api,需在开发库插入该权限记录并由管理员在角色中勾选后生效)。", "代码变更:app/service/systems/wechat.js 新增 bindByEmployee;app/service/systemMethods/wechat.js 新增 bindByEmployee 出口。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.wxaauth-new-api", "date": "2026-09-23", "type": "updated", "summary": "wechat.wxaauth 迁移到微信新版认证接口:旧接口 /wxa/sec/wxaapi/wxaauth、/wxa/sec/wxaapi/uploadmedia 已下线(40066 invalid url),改为 POST /wxa/sec/wxaauth(auth_data 包裹)+ POST /wxa/sec/uploadauthmaterial(mediaid)", "methods": [ "wechat.wxaauth" ], "notes": [ "根因:微信下线旧版小程序认证接口,调用 /wxa/sec/wxaapi/wxaauth 与 /wxa/sec/wxaapi/uploadmedia 返回 40066 invalid url(与 queryauth 当年同因:路径不存在,详见 2026.09.22-wechat.queryauth-fix 记录)。", "发起认证改为 POST /wxa/sec/wxaauth,请求体 { auth_data }:customer_type(1 企业/12 个体户/15 个人)、account_name、account_name_type(1 自选词汇/2 商标)、pay_type(1 服务商预购包/2 自行支付)、third_party_phone、contact_info{name,email,mobile?} 必填;invoice_info/qualification/qualification_other(≤10)/account_supplemental/auth_identification/auth_ident_material/service_appid(代缴必填)/taskid 可选。", "上传材料改为 POST /wxa/sec/uploadauthmaterial(multipart media=文件,图片 ≤2M,PNG/JPEG/JPG/GIF),返回 mediaid(lib 层归一化为 media_id)。自动换 mediaid 的图片字段:qualification(单张)、qualification_other[]/account_supplemental[]/auth_ident_material[](数组),支持传 COS URL。", "破坏性变更:入参由旧扁平字段(contact_type/contact_name/contact_cert_photo/business_license_*/legal_persona_*/pic_list/qualification_list/statement_list 等 33 字段白名单)改为新版 auth_data 字段,前端需同步切换。打回重填走新接口 POST /wxa/sec/reauth(同 auth_data + taskid,暂未接入,可后续补 wechat.reauth)。", "代码变更:app/lib/wechat_open_client.js wxaauth/uploadAuthMedia 路径与 mediaid 归一化;app/service/systems/wechat.js wxaauth/resolveBodyMedia/resolveMediaValue 换新字段;app/service/systemMethods/wechat.js 注释同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.wxaauth-cos-url", "date": "2026-09-22", "type": "updated", "summary": "wechat.wxaauth 改为后端分步:图片字段传 COS 文件 URL,后端下载 → uploadmedia 换 media_id → wxaauth 提交", "methods": [ "wechat.wxaauth" ], "notes": [ "后端分步:① 图片字段值为 http/https(COS URL)时,后端 GET 下载 Buffer → POST /wxa/sec/wxaapi/uploadmedia(multipart/form-data,media_type=image,media=临时文件)换 media_id;② 替换请求体后调 /wxa/sec/wxaapi/wxaauth 提交。非 URL 值视为已传 media_id 原样透传。", "支持自动换 media_id 的图片字段:顶层 contact_cert_photo/business_license_copy/legal_persona_idcard_copy/legal_persona_media;pic_list 项的 pic_url;qualification_list 项 licence_list/certificate_list 的 value;statement_list 项的 value。", "uploadmedia 实现细节:Buffer 写临时文件(文件名带 jpg/jpeg/png 扩展名,从 URL path 提取,默认 image.jpg)后按路径传 files:{media}(urllib 2.44 files 支持 Buffer 但文件名固定 bufferfileN 无扩展名,故落临时文件保证扩展名),finally 删除临时文件;40001/40014 清 authorizer token 重试一次。media_id 3 天内有效。", "代码变更:app/lib/wechat_open_client.js 新增 uploadAuthMedia;app/service/systems/wechat.js 新增 resolveBodyMedia/resolveMediaValue/downloadFromUrl/resolveMediaFilename 并在 wxaauth 中调用。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.wxaauth", "date": "2026-09-22", "type": "added", "summary": "新增 wechat.wxaauth 发起小程序认证(一步提交):前端上传材料换 media_id 后传入,后端调 wxa/sec/wxaapi/wxaauth,成功回写 auth_task_id/auth_apply_status", "methods": [ "wechat.wxaauth" ], "notes": [ "新增接口 wechat.wxaauth(需登录免权限,权限集 18):前端负责上传材料换取 media_id 后一步提交;入参白名单透传(contact_type/contact_name 必填,其余 contact_*/business_license_*/legal_persona_*/pic_list 等 33 字段白名单)。", "成功回写 wms_wechat_app.auth_task_id=taskid、auth_apply_status(auth_task_status 置空),返回 taskid/auth_url/apply_status;taskid 供 wechat.queryauth 查询进度(taskid 可选,库中 auth_task_id 兜底)。", "已认证(verify_type_id>=0)拒绝重复发起;未授权权限集 18 拒绝。lib#wxaauth 40001/40014 清 authorizer token 重试一次。不拆表:认证状态继续复用 wms_wechat_app 现有字段,无迁移。", "代码变更:app/lib/wechat_open_client.js 新增 wxaauth;app/service/systems/wechat.js 新增 wxaauth;systemMethods/wechat.js 白名单与出口同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.queryauth-verified-first", "date": "2026-09-22", "type": "updated", "summary": "wechat.queryauth 改为先判已认证再查进度:已认证直接返回认证信息;未认证且有 taskid 才调微信查进度;taskid 可选(库中 auth_task_id 兜底);认证通过回写 verify_type_id=0", "methods": [ "wechat.queryauth" ], "notes": [ "判定顺序:① 本地 wms_wechat_app.verify_type_id>=0(已认证)→ 直接返回本地认证信息(is_verified=true/verify_type_id/principal_name/signature/service_type_id/account_status),不调微信;② 未认证(null/-1)→ taskid(入参优先,其次库中 auth_task_id)调 wxa/sec/queryauth 查进度;③ 未认证且无 taskid → 返回 code 200「尚未认证且无认证任务」(is_verified=false)。", "落库:查询成功回写 auth_task_id/auth_task_status/auth_apply_status;apply_status=4(认证通过)时同时回写 verify_type_id=0(微信认证),后续 queryauth 直接走已认证分支。", "文档:system.json wechat.queryauth 条目 params(taskid 改可选)/response(新增 is_verified/verify_type_id/principal_name 等)同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getAuthorizerInfo-db-fields", "date": "2026-09-22", "type": "added", "summary": "新增 wechat.getAuthorizerInfo 基础信息接口;wms_wechat_app 补充授权账号基础信息与认证状态字段(13列);认证 taskid/状态随 queryauth 成功落库", "methods": [ "wechat.getAuthorizerInfo", "wechat.queryauth" ], "notes": [ "新增接口 wechat.getAuthorizerInfo(需登录免权限):调微信 POST /cgi-bin/component/api_get_authorizer_info(component_access_token)拉取 authorizer_info + authorization_info,将基础信息/认证类型/权限集落库 wms_wechat_app 后返回完整数据。", "迁移 20260922180000-add-authorizer-info-fields-to-wms-wechat-app:wms_wechat_app 新增 principal_name/signature/alias/qrcode_url/service_type_id/verify_type_id/account_status/register_type/business_info/mini_program_info/auth_task_id/auth_task_status/auth_apply_status,开发+生产均已执行。", "verify_type_info.id 语义:-1 未认证、0 微信认证、1 新浪微博认证、3 资质通过未名称认证、4 同3+微博;account_status:1 正常、14 已注销、16 已封禁、18 已告警、19 已冻结。", "认证任务落库口径:taskid 由发起认证接口(wxa/sec/wxaapi/wxaauth,暂未接入)返回,queryauth 查询成功后回写 auth_task_id/auth_task_status/auth_apply_status。", "代码变更:app/lib/wechat_open_client.js 新增 getAuthorizerDetail(完整返回);app/service/systems/wechat.js 新增 buildAuthorizerPatch/getAuthorizerInfo、queryauth 增加状态落库;app/controller/wechatOpen.js 授权回调/authorized/updateauthorized 事件改用 getAuthorizerDetail 全量字段落库;app/model/wechat_app.js、systemMethods/wechat.js 同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getAuthUrl-scope", "date": "2026-09-22", "type": "updated", "summary": "wechat.getAuthUrl 授权链接限定授权范围:auth_type=2(仅小程序)+ category_id_list=18|86(代码管理、体验版二维码)", "methods": [ "wechat.getAuthUrl" ], "notes": [ "修正认知:auth_type 是授权账号类型(1公众号/2小程序/3公众号+小程序),不是权限范围;权限范围由 category_id_list(权限集 id 列表,竖线分隔)或商家在授权页自定义勾选控制。业务所需权限集:18=小程序代码管理(commit/submit_audit/queryauth/get_qrcode)、86=体验版二维码;getTemplateList/jscode2session/快速注册不需要商家权限集。", "代码变更:app/service/systems/wechat.js#getAuthUrl 授权链接增加 category_id_list=18|86、auth_type 改为 2。前提:18/86 需在微信开放平台后台「权限集」配置并全网发布,否则商家授权页看不到;已授权商家需重新扫码授权才能获得 18/86。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.commit-ext-json-default", "date": "2026-09-22", "type": "updated", "summary": "wechat.commit 的 ext_json 改为后端默认生成(仅 extEnable+extAppid),不再由前端传入", "methods": [ "wechat.commit" ], "notes": [ "入参仅剩 template_id;ext_json 由后端生成 JSON.stringify({extEnable:true, extAppid: 当前小程序appid}),前端传值被忽略;响应新增 ext_json 回显。", "代码变更:app/service/systems/wechat.js#commit;文档 system.json wechat.commit 条目 params/response 同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.commit-desc-from-template", "date": "2026-09-22", "type": "updated", "summary": "wechat.commit 代码描述也改为从模板取:user_version 与 user_desc 均不再由外部传入", "methods": [ "wechat.commit" ], "notes": [ "入参进一步瘦身:user_desc 也移除(外部传入被忽略);commit 流程:getTemplateList(0) → 按 template_id 找模板 → 取模板 user_version(≤64)与 user_desc 作为上传版本号/代码描述(缺失分别报「模板缺少合法版本号/缺少代码描述」)→ wxa/commit 成功后回写 wms_wechat_app.template_id/user_version;响应新增 user_desc。", "代码变更:app/service/systems/wechat.js#commit;文档 system.json wechat.commit 条目 params/response 同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.userList", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.userList(需登录):拉取当前仓库小程序的用户列表(wms_user_oauth),支持 where/pagination/sort", "methods": [ "wechat.userList" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.userList(isNeedLogin=true、isNeedAuth=false、Authorization 头):按 ctx.user.store_id 取仓库启用小程序(wms_wechat_app,is_enabled=1;可选 app_id 指定单个,须属于当前仓库),查询 wms_user_oauth(provider=wechat,app_id IN 命中应用);入参 where(字段白名单 id/user_id/app_id/openid/unionid/nickname/sex/login_time/login_count/created_at/updated_at,operator 结构,经 prepareWhereContext 解析)、pagination(page/pageSize)、sort(sortField 白名单同上,默认 updated_at DESC)。", "代码变更:app/service/systems/wechat.js#userList(findAndCountAll,attributes 排除 session_key/refresh_token/access_token/expire_in/expire_time/login_code 敏感字段,raw+is_bound);app/service/systemMethods/wechat.js 出口 + where 字段白名单过滤 + _noNeedRight/_noNeedLog/_noNeedAuth 白名单加入 userList。", "无数据库变更(纯只读查询)。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.queryauth-fix", "date": "2026-09-22", "type": "updated", "summary": "修复 wechat.queryauth:接口路径改为 wxa/sec/queryauth 并新增必填入参 taskid,响应改为 task_status/apply_status", "methods": [ "wechat.queryauth" ], "notes": [ "根因:此前实现误用 /wxa/sec/wxaapi/queryauth 且未传 taskid,微信返回 40066 invalid url;官方接口为 POST /wxa/sec/queryauth?access_token=authorizer_access_token,请求体必填 taskid(发起认证接口 wxa/sec/wxaapi/wxaauth 返回)。", "修复:lib#queryMiniProgramAuth 改路径并传 { taskid },40001/40014 清 authorizer token 重试;systems#queryauth 新增 taskid 必填校验,响应返回 task_status/apply_status/orderid/auth_url 等并附中文文案;文档 system.json queryauth 条目同步更新。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.submitAudit", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.submitAudit(需登录):提交代码审核,wms_wechat_app 新增审核状态字段(开发+生产已迁移)", "methods": [ "wechat.submitAudit" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.submitAudit(isNeedLogin=true、isNeedAuth=false、Authorization 头):入参白名单 item_list/feedback_info/feedback_stuff/preview_info/version_desc/privacy_api_not_use/order_info/ugc_declare;校验权限集 18;仅 audit_status!=1 时允许提交;POST wxa/submit_audit(authorizer_access_token,40001/40014 清缓存重试)成功后回写 audit_status=1、audit_id。", "数据库:迁移 20260922170000-add-audit-fields-to-wms-wechat-app.js(user_version/audit_status/audit_id/audit_reason),开发与生产均已执行;commit 同步回写 user_version;审核结果事件 weapp_audit_success→audit_status=2、weapp_audit_fail→audit_status=3+audit_reason(按 ToUserName=user_name 定位)。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getTrialQRCode", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.getTrialQRCode(需登录):获取体验版二维码(转存 COS 返回 URL)", "methods": [ "wechat.getTrialQRCode" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.getTrialQRCode(isNeedLogin=true、isNeedAuth=false、Authorization 头):入参 path(可选);按 ctx.user.store_id 取仓库启用小程序,hasFuncScope 校验权限集 18 或 86;GET wxa/get_qrcode(authorizer_access_token,path 自动 urlencode,40001/40014 清 authorizer token 缓存重试)返回 jpeg 图片,经 upload.uploadBuffer 转存 COS(key=qrcode/wechat/{warehouseId}/{yyyymmdd}/{ts}{rand}.jpg)后返回 URL。", "代码变更:app/lib/wechat_open_client.js#getTrialQRCode;app/service/systems/wechat.js#getTrialQRCode/#buildTrialQrCodeKey;app/service/systemMethods/wechat.js 出口 + _noNeedRight/_noNeedAuth 白名单。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.commit", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.commit(需登录):上传代码并生成体验版,wms_wechat_app 新增 template_id 字段(开发+生产已迁移)", "methods": [ "wechat.commit" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.commit(isNeedLogin=true、isNeedAuth=false、Authorization 头):入参 template_id/ext_json/user_version(≤64)/user_desc;按 ctx.user.store_id 取仓库启用小程序,hasFuncScope(func_info, 18) 校验代码管理权限集,getTemplateList(0) 校验模板存在(微信 85014 兜底),POST wxa/commit(authorizer_access_token,40001/40014 清 authorizer token 缓存重试)成功后回写 wms_wechat_app.template_id。", "数据库:迁移 20260922160000-add-template-id-to-wms-wechat-app.js(wms_wechat_app.template_id bigint unsigned nullable),已在开发(127.0.0.1:3307)与生产(112.124.21.102)执行并验证;app/model/wechat_app.js 同步 template_id 字段。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getTemplateList", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.getTemplateList(需登录):获取普通模板库列表,Redis 缓存 24h", "methods": [ "wechat.getTemplateList" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.getTemplateList(isNeedLogin=true、isNeedAuth=false、Authorization 头):只拉普通模板(template_type=0,GET wxa/gettemplatelist + component_access_token,40001 自愈);Redis key wechat:template:list:normal 缓存 24h,有缓存直接返回(from_cache=true),无缓存拉取后写缓存。", "代码变更:app/lib/wechat_open_client.js#getTemplateList(GET 请求封装);app/service/systems/wechat.js#getTemplateList;app/service/systemMethods/wechat.js 出口 + _noNeedRight/_noNeedAuth 白名单。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getMyLoginCode", "date": "2026-09-22", "type": "added", "summary": "新增 wechat.getMyLoginCode:获取当前微信登录用户的登录码(至少微信登录),无则生成写入、有则直接返回", "methods": [ "wechat.getMyLoginCode" ], "notes": [ "systemMethods/wechat.js 白名单:_noNeedBind 新增 getMyLoginCode(微信登录态中间层,未绑定真实用户也可访问,业务层校验 ctx.oauth);systems/wechat.js 新增 getMyLoginCode:ctx.oauth 定位 wms_user_oauth,login_code 为空时 buildLoginCode(id) 生成(uuid={id}_{6位随机}、form=wechat 的 JSON base64)并回写,已有直接返回;system.json 微信模块新增该 method" ], "module": "wechat" }, { "version": "2026.09.22-wechat.uploadHeadimg", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.uploadHeadimg(微信登录态中间层):上传裁剪后的 PNG 头像(<500K)并回写 headimgurl", "methods": [ "wechat.uploadHeadimg" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.uploadHeadimg(中间层鉴权,至少微信登录即可,未绑定也可):入参 image(PNG base64,支持 data URL 前缀);校验大小 <500K 与 PNG 文件头魔数后经 upload.uploadBuffer 上传 COS(key=headimg/wechat/{yyyymmdd}/{timestamp}{random}.png,不依赖仓库上下文),回写 wms_user_oauth.headimgurl 并返回 URL。", "代码变更:app/service/systems/upload.js#uploadBuffer(Buffer 直传 COS);app/service/systems/wechat.js#uploadHeadimg/#buildHeadimgKey;app/service/systemMethods/wechat.js 出口 + _noNeedBind 白名单。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.updateInfo", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.updateInfo(微信登录态中间层):未绑定用户更新自己的昵称/头像", "methods": [ "wechat.updateInfo" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.updateInfo(中间层鉴权,需有效微信登录态 token):仅未绑定真实用户(wms_user_oauth.user_id=0)可更新 nickname(≤255)/headimgurl(≤500),可部分更新,至少一个字段;已绑定账号返回「账号已绑定,不支持修改微信资料」。", "代码变更:app/service/systems/wechat.js#updateInfo;app/service/systemMethods/wechat.js 出口 + _noNeedBind 白名单加入 updateInfo。" ], "module": "wechat" }, { "version": "2026.09.22-user.info-wechat-appId-filter", "date": "2026-09-22", "type": "updated", "summary": "user.info 新增可选入参 wechat_appId:传入时按小程序归属仓库过滤工号列表(仅保留非仓库工号(货主)+ 该仓库工号)", "methods": [ "user.info" ], "notes": [ "user.info 新增可选入参 wechat_appId:按 wms_wechat_app.appid(is_enabled=1)反查归属 warehouse_id,有仓库时过滤返回的 user.employees —— 保留 role_type!=warehouse(货主工号)或 store_id=该仓库 的工号;未传或查不到仓库保持原逻辑。", "代码变更:app/service/systems/auth/user.js#info 增加 data.wechat_appId 处理(method 层 user.info 已透传 data)。" ], "module": "user" }, { "version": "2026.09.22-wechat.registerMiniprogram", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.registerMiniprogram(需登录):快速注册企业小程序", "methods": [ "wechat.registerMiniprogram" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.registerMiniprogram(isNeedLogin=true、isNeedAuth=false、Authorization 头):入参 name/code/code_type/legal_persona_wechat/legal_persona_name(必填)+ component_phone(选填),校验后调微信 fastregisterweapp?action=create(component_access_token,40001 自愈重试);注册任务创建后法人微信收到模板消息做人脸核身,审核结果通过 notify_third_fasteregister 事件推送到授权事件接收 URL(后续需在 handleEvent 中处理该事件绑定仓库)。", "代码变更:app/lib/wechat_open_client.js#fastRegisterWeapp(create/search 通用封装 + 40001 自愈);app/service/systems/wechat.js#registerMiniprogram;app/service/systemMethods/wechat.js 出口 + _noNeedRight/_noNeedAuth 白名单。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.queryauth", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.queryauth(需登录):查询当前仓库小程序的认证状态", "methods": [ "wechat.queryauth" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.queryauth(isNeedLogin=true、isNeedAuth=false、Authorization 头):按 ctx.user.store_id 取仓库启用小程序(wms_wechat_app,is_enabled=1,id ASC 取第一条),用 authorizer_access_token 调微信 wxa/sec/wxaapi/queryauth 返回 auth_state(0 未认证/1 认证中/2 认证通过/3 认证失败)并附 auth_state_text 中文文案。", "代码变更:app/lib/wechat_open_client.js#queryMiniProgramAuth(authorizer_access_token 调 wxa/sec/wxaapi/queryauth,支持 DB 落库的 authorizer_refresh_token 兜底 Redis 丢失);app/service/systems/wechat.js#queryauth;app/service/systemMethods/wechat.js 出口 + _noNeedRight/_noNeedAuth 白名单加入 queryauth。" ], "module": "wechat" }, { "version": "2026.09.21-wechat.pushLoginCode-legacy-code", "date": "2026-09-21", "type": "updated", "summary": "弃用 wechat.getLoginWechatCode,wechat.pushLoginCode 改为复用旧 user.getLoginWechatCode 生成的登录码", "methods": [ "wechat.pushLoginCode" ], "notes": [ "弃用新增的 wechat.getLoginWechatCode(移除 systems/method 层与文档);小程序端继续使用旧 user.getLoginWechatCode 生成/轮询 6 位字母+数字登录码(user:wechat:login:code:* / client key,TTL 60s)。", "wechat.pushLoginCode(需登录免权限)改造:读旧码缓存(getWechatLoginCodeCacheKey)取 client_code,经 findYe4sBindingByAccountId 反查当前账号 ye4s_user,将 ye4s_user_id 双写旧登录码缓存(code key + client key,TTL 按剩余有效期),旧轮询方读到 ye4s_user_id 即走 loginByYe4sUserId 直登返回正常 WMS token。" ], "module": "wechat" }, { "version": "2026.09.21-wechat.loginCode-flow", "date": "2026-09-21", "type": "added", "summary": "新增微信模块 wechat.getLoginWechatCode / wechat.pushLoginCode:小程序端生成 6 位登录码轮询,PC 已登录用户确认后小程序端返回登录成功并绑定账号", "methods": [ "wechat.getLoginWechatCode", "wechat.pushLoginCode" ], "notes": [ "getLoginWechatCode(微信登录态中间层 _noNeedBind):不传 code 生成 6 位数字登录码写 Redis(key wechat:login:code:{code},TTL 300s,记录 oauth_id);传 code 轮询状态 pending/expired/success;success 时校验归属 oauth_id、一次性消费登录码、绑定 wms_user_oauth.user_id=确认账号(防换绑)并签发登录 token(id=账号ID、oauth_id 保留)。", "pushLoginCode(需登录、免权限):PC/Web 已登录用户传 code,将对应缓存态置 success 并写入 account_id(TTL 120s 等待小程序领取);登录码归属校验防止他人码窃取登录。", "代码变更:app/service/systems/wechat.js#getLoginWechatCode/#pushLoginCode/#createLoginCode/#getLoginCodeCacheKey、app/service/systemMethods/wechat.js(出口 + _noNeedBind 白名单 + _noNeedRight 加入 pushLoginCode)。" ], "module": "wechat" }, { "version": "2026.09.21-wechat.loginByCode-appid-string", "date": "2026-09-21", "type": "updated", "summary": "wechat.loginByCode 应用标识兼容字符串 appid:新增 appid(微信 AppID 字符串)入参按 uk_appid 反查,app_id(整数主键)保留向后兼容", "methods": [ "wechat.loginByCode" ], "notes": [ "微信 AppID 是字符串(如 wx6e91ec813bcb7eec),小程序端应传 appid 字符串(模板小程序运行时取 wx.getAccountInfoSync().miniProgram.appId)而非数据库主键。", "代码变更:app/service/systems/wechat.js 新增 resolveWechatApp(优先 app_id 主键,其次 appid 按 uk_appid 反查并过滤 is_enabled=1);loginByCode 经 resolveWechatApp 解析应用记录,wms_user_oauth.app_id 仍存 wms_wechat_app.id(整数外键)。文档 system.json loginByCode 入参补充 appid 字段说明。" ], "module": "wechat" }, { "version": "2026.09.21-user.info-oauth-middle", "date": "2026-09-21", "type": "updated", "summary": "user.info 支持微信登录态中间层:微信登录未绑定时返回微信层信息(is_bound=false),不 401", "methods": [ "user.info" ], "notes": [ "systemMethods/user.js 构造器新增 _noNeedBind='info'(systemInit 第 5 参),微信登录态 token 可调用 user.info;auth.user.info 增加分支:未绑定真实用户(ctx.oauth 存在且无 ctx.user)时返回微信层信息(id=0/is_bound=false/oauth_id/openid/unionid/nickname/headimgurl/login_time/login_count,code 200),不 401;绑定/正常登录仍返回 findById 完整信息。", "代码变更:app/service/systems/auth/user.js#info、app/service/systemMethods/user.js;撤销前版 wechat.getUserInfo(用户要求 getUserInfo 为公用接口,不收在 wechat 模块)。" ], "module": "user" }, { "version": "2026.09.21-wechat.bindUser", "date": "2026-09-21", "type": "added", "summary": "新增微信模块 wechat.bindUser(微信登录态中间层):用户名密码一致则绑定 wms_user_oauth.user_id 并签发绑定后的新 token", "methods": [ "wechat.bindUser" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.bindUser(中间层鉴权:需有效微信登录态 token,未绑定真实用户也可调用):入参 username(用户名/手机号/邮箱)+ password;复用 auth.user 的 findUserByIdentifier/checkUserStatus/verifyPassword 校验;一致则 wms_user_oauth.user_id 绑定账号并签发新 token(payload id=账号ID、oauth_id 保留);已绑定时仅允许本人凭据幂等调用,不允许换绑。", "鉴权机制:app/service/main.js checkAuth 新增中间层白名单 _noNeedBind(systemInit 第 5 参),oauth token 有效即通过(user_id=0 也可),ctx.oauth/ctx.oauthId 注入微信身份,不查 API 权限;代码变更:app/service/systemMethods/wechat.js(bindUser 出口 + _noNeedBind 白名单)、app/service/systems/wechat.js#bindUser/#buildBindResult。" ], "module": "wechat" }, { "version": "2026.09.21-wechat.loginByCode", "date": "2026-09-21", "type": "added", "summary": "新增微信模块 wechat.loginByCode(免登录):小程序 wx.login code 换 openid/session_key 并查/建 wms_user_oauth,返回 token+user", "methods": [ "wechat.loginByCode" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.loginByCode(免登录 isNeedLogin=false):入参 code(wx.login 获取)+ app_id(wms_wechat_app.id);jscode2session(GET /sns/component/jscode2session)换 openid/session_key/unionid;wms_user_oauth 有记录则刷新 login_time/login_count/session_key,无记录则创建且 user_id=0(未绑定);JWT payload 记录 oauth_id(wms_user_oauth.id),区别于正常登录的用户 id 字段。", "代码变更:app/lib/wechat_open_client.js#jscode2session(GET 请求封装);app/service/systems/wechat.js#loginByCode;app/service/systemMethods/wechat.js 免登录白名单加入 loginByCode。" ], "module": "wechat" }, { "version": "2026.09.21-workbench.packOrder-business-users-restore", "date": "2026-09-21", "type": "updated", "summary": "workbench.business 的 packOrder 分支恢复支持传入 users 上报打包人(未上报时回填工作台成员);token+key 新链路保持剥离 users", "methods": [ "workbench.business" ], "notes": [ "业务旧链路(workbench.business 的 packOrder 分支)恢复 users 上报生效:上报时以上报为准,未上报时自动回填该工作台绑定成员(wms_workbench_member);token+key 新链路(workbench.packOrder)保持剥离 users、一律取工作台绑定成员。", "代码变更:app/service/systems/workbench.js#_packOrder 恢复 users 入参(上报优先、未报回填)、#packOrderByToken 解构剥离 users;回归测试 test/workbench_pack_waybill_dimension.test.cjs(26 用例)。" ], "module": "workbench" }, { "version": "2026.09.21-wechat.getAuthUrl", "date": "2026-09-21", "type": "added", "summary": "新增微信模块 wechat.getAuthUrl:生成微信开放平台小程序授权链接(PC版),state 缓存仓库信息用于回跳绑定", "methods": [ "wechat.getAuthUrl" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.getAuthUrl(需登录);app/service/systems/wechat.js + app/service/systemMethods/wechat.js 生成授权链接;state=随机串,缓存 key wechat_auth_state:{state}(TTL 600s)存仓库信息;GET /Authorization 回跳凭 state 绑定仓库并落库 wms_wechat_app;state 缺失/过期展示错误页 app/view/wechat_auth_callback.html;配置 wechatOpen.redirect_uri" ], "module": "wechat" }, { "version": "2026.09.21-workbench.getWorkbenchInfo-order-fields", "date": "2026-09-21", "type": "updated", "summary": "workbench.getWorkbenchInfo 的 current_orders 补齐货主备注(store_remark)与运单信息(express:物流公司/称重重量/包材名称),与 queryOrder 口径一致", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "背景:getWorkbenchInfo 返回的 current_orders 相比 queryOrder 缺货主备注与包材信息,前端无法填充。", "散单任务(pack_mode=1)按 order_id(优先任务 waybill_code)补 wms_order_express 的 logistics_name/weighing_weight/package_material_name_snapshot 与 wms_store_warehouse.store_remask;团购任务为波次维度不适用(store_remark 空、express 为 null)。查询并行执行,异常降级不阻断主信息。", "代码变更:app/service/systems/workbench.js#buildCurrentPackingInfo;回归测试 test/workbench_pack_waybill_dimension.test.cjs(24 用例)。" ], "module": "workbench" }, { "version": "2026.09.21-workbench.packOrder-key-forward-fix", "date": "2026-09-21", "type": "updated", "summary": "修复 workbench.packOrder method 层未透传 key 导致 key 模式不生效(请求带 key 仍报发货单号不能为空)", "methods": [ "workbench.packOrder" ], "notes": [ "根因:app/service/systemMethods/workbench.js#packOrder 解构白名单未包含 key,packOrderByToken 收不到 key 回退旧参数模式,新客户端只传 token+key 时报「发货单号不能为空」。", "修复:method 层透传 key;回归测试 test/workbench_pack_waybill_dimension.test.cjs 新增 method 层透传用例(22 用例)。" ], "module": "workbench" }, { "version": "2026.09.21-workbench.packOrder-legacy-compat", "date": "2026-09-21", "type": "updated", "summary": "workbench.packOrder 代码保留旧参数模式过渡兼容(不传 key 时直传参数),文档主推 token+key 新接口", "methods": [ "workbench.packOrder", "workbench.business" ], "notes": [ "设备端过渡方案:代码同时支持新 key 模式(优先)与旧参数模式(不传 key 时直传 delivery_order_code 等,后续版本移除),文档按 token+key 新接口展示。", "代码变更:app/service/systems/workbench.js#packOrderByToken 与 #business(packOrder) 分支恢复旧参数回退;回归测试 test/workbench_pack_waybill_dimension.test.cjs(21 用例,含旧参数兼容)。" ], "module": "workbench" }, { "version": "2026.09.21-workbench.packOrder-key-only", "date": "2026-09-21", "type": "updated", "summary": "workbench.packOrder 除 token、key 外不再接收任何订单相关信息:订单参数一律由后端从打包上下文缓存拉取(防篡改)", "methods": [ "workbench.packOrder", "workbench.business" ], "notes": [ "workbench.packOrder 入参收敛为 token + key,移除旧参数(delivery_order_code/waybill_code/wave_no/status/pack_time/wave_total_orders/items_count/items_total),body 传入其它字段一律忽略;缺 key 返回 400、key 过期返回 400、跨仓库/跨工作台使用返回 403。", "workbench.business 的 packOrder 分支同样只接受 key(订单信息取自缓存,仓库/工作台取缓存值)。", "代码变更:app/service/systems/workbench.js 新增 _loadPackCtx(凭 key 拉取缓存,缺 key/过期抛错);packOrderByToken 只取 token+key 并捕获 _loadPackCtx 异常转 400;business(packOrder) 分支改走 key 消费。", "回归测试 test/workbench_pack_waybill_dimension.test.cjs(21 用例,含缺 key 400、business 只接受 key、body 订单参数忽略)。" ], "module": "workbench" }, { "version": "2026.09.21-workbench.packOrder-key-mode", "date": "2026-09-21", "type": "updated", "summary": "workbench.queryOrder 返回打包上下文 key(20 分钟缓存);workbench.packOrder 精简为 token+key 消费缓存参数(旧参数模式保留兼容)", "methods": [ "workbench.queryOrder", "workbench.packOrder" ], "notes": [ "workbench.queryOrder 扫码查询成功时生成打包上下文 key(wpck 前缀 + 32 位随机段),缓存 key workbench:packctx:{key}、TTL 1200s,内容含 warehouse_id/workbench_id/order_id/delivery_order_code/wave_no/waybill_code/is_sandan,响应新增 key 字段;缓存写入失败仅告警不阻断查询。", "workbench.packOrder 推荐只传 token + key:后端按 key 拉取缓存参数执行打包(数量参数后端复查兜底),跨仓库/跨工作台消费他人 key 返回 403、key 过期返回 400(提示重新扫码);旧参数模式(不传 key 直接传 delivery_order_code 等)保留兼容。", "代码变更:app/service/systems/workbench.js 新增 WORKBENCH_PACK_CTX_CACHE_PREFIX/TTL/KEY_PREFIX 常量、generatePackCtxKey、getWorkbenchPackCtxCacheKey;_queryOrder 步骤7 写打包上下文缓存并返回 key(新增 workbench_id 入参);packOrderByToken 增加 key 消费与归属校验;queryOrderByToken 注入 workbench_id。", "回归测试 test/workbench_pack_waybill_dimension.test.cjs(19 用例,含 key 模式/过期/跨仓/跨台/旧模式兼容)。" ], "module": "workbench" }, { "version": "2026.09.21-workbench.packOrder-remove-users-param", "date": "2026-09-21", "type": "updated", "summary": "workbench.packOrder 移除 users 入参:打包人一律由服务端取该工作台绑定成员(wms_workbench_member)回填", "methods": [ "workbench.packOrder" ], "notes": [ "打包人数据源收敛为工作台绑定成员(bindMember/removeMember 登入登出链路持久化到 wms_workbench_member),packOrder 不再接收 users 入参,写入 wms_pack_task_packer 与 operator_text 的打包人一律由服务端按 workbench_id 回填;旧设备端传 users 将被忽略。", "代码变更:app/service/systems/workbench.js#_packOrder 移除 users 解构与上报优先分支,步骤7 直接回填绑定成员;回归测试 test/workbench_pack_waybill_dimension.test.cjs 更新(13 用例,含「旧设备端仍传 users:一律忽略」)。" ], "module": "workbench" }, { "version": "2026.09.21-workbench.removeMember-auto-finish-pack", "date": "2026-09-21", "type": "updated", "summary": "workbench.packOrder 打包人缺省自动回填工作台绑定成员;workbench.removeMember 成员全部登出后自动结束未结束的打包任务", "methods": [ "workbench.packOrder", "workbench.removeMember" ], "notes": [ "workbench.packOrder 的 users 入参缺省/为空时,后端自动查询该工作台绑定成员(wms_workbench_member)回填 wms_pack_task_packer 与 operator_text,打包人数据源单一,设备端无需重复上报;上报时优先使用上报值。", "workbench.removeMember 软删除成员行后统计剩余成员,剩余为 0 时自动结束该工作台所有未结束打包任务(status<2 → 2 并写 end_time),同步订单打包状态(散单按订单、团购按波次,与 _finishPack 语义一致)、写完成操作日志、复位摄像头 OSD、失效 token 缓存;响应新增 auto_finished_pack(finished/task_ids)。", "代码变更:app/service/systems/workbench.js#_packOrder(步骤7 成员回填)、#removeWorkbenchMember(登出后剩余成员检查)、新增 #_finishAllPackTasksByMemberLogout;回归测试 test/workbench_pack_waybill_dimension.test.cjs(13 用例)。" ], "module": "workbench" }, { "version": "2026.09.21-workbench.packOrder-waybill-dimension", "date": "2026-09-21", "type": "updated", "summary": "workbench.packOrder 支持运单维度打包流水(一单多号:主单号/子单号流水互不覆盖),workbench.queryOrder 的 pack_flag 改为运单维度判定", "methods": [ "workbench.packOrder", "workbench.queryOrder", "workbench.business" ], "notes": [ "背景:一单多号订单(wms_order_express 同 order_id 下 business_key=1 主单号 / >1 子单号)此前按订单维度打包,任一运单打包后订单 pack_status 非 none,导致另一运单被误判为已打包、无法写入打包流水。", "workbench.packOrder 新增可选入参 waybill_code:散单按「订单+运单号」维度写入 wms_pack_task.waybill_code 并去重(同时清理同订单历史 waybill_code 为空的旧流水),主/子单号流水互不覆盖;未传运单号(旧设备端)保持订单维度;团购为波次维度,不使用运单号。", "workbench.queryOrder 的 pack_flag 改为运单维度判定:查询该运单号是否已有打包流水(waybill_code 命中,或历史订单级流水 waybill_code 为空兜底),流水查询异常时降级为订单级 pack_status 判定。", "代码变更:app/service/systems/workbench.js#_packOrder(步骤2.5 运单归属解析、步骤5 去重、packData.waybill_code、步骤7.5 OSD 优先展示打包运单号)、#_queryOrder(步骤6 pack_flag 运单级判定);回归测试 test/workbench_pack_waybill_dimension.test.cjs(8 用例)。" ], "module": "workbench" }, { "version": "2026.09.20-workbench-pack-backfill-confirm-print", "date": "2026-09-20", "type": "updated", "summary": "打包链路(workbench.packOrder / workbench.finishPack)回写打包状态时同步补确认打印状态:扫描打包即视为面单已真实存在,confirm_print_status 未写入(none/null)时补 fin,团购按波次、散单按单,拦截订单跳过,并递增统计版本号驱动确认打印未领单长轮询。", "methods": [ "workbench.packOrder", "workbench.finishPack" ], "notes": [ "实现入口:systems/workbench.js _updateOrderPackStatus(覆盖开始打包/完成打包/关闭旧任务全部路径)", "幂等:仅 confirm_print_status 为 none/null 时补 fin" ] }, { "version": "2026.09.20-wave-confirmPrintScan-need-right", "date": "2026-09-20", "type": "updated", "summary": "order.wave.confirmPrintScan 改为需要接口权限(isNeedAuth=true),从免权限名单移除;confirmPrintUnclaimedWaveCount 保持免权限。", "methods": [ "order.wave.confirmPrintScan" ], "notes": [ "运行时:wave.js _noNeedRight/_noNeedAuth 已移除 confirmPrintScan,checkAuth 走 checkApiPermission", "权限记录由 permission:sync:system-api 从 system.json isNeedAuth=true 接口同步并授权角色 2" ] }, { "version": "2026.09.20-pendingOrder-list-confirm-print-claim-fields", "date": "2026-09-20", "type": "updated", "summary": "order.pendingOrder.list 文档补充 confirm_print_status(确认打印)与 claim_status(领料)的 where 筛选说明与响应字段说明(功能已支持,本次仅同步文档)。", "methods": [ "order.pendingOrder.list" ], "notes": [ "列表输出 ORDER_LIST_BASE_ATTRIBUTES 已包含 confirm_print_status/claim_status;where 无字段白名单,两列可直接透传筛选" ] }, { "version": "2026.09.20-wave-batchList-claim-status", "date": "2026-09-20", "type": "updated", "summary": "order.wave.batchList 波次列表新增 claim_assignment_status 领料状态显示(含 claim_time/claim_operator)与 where.claim_assignment_status 筛选(波次表 claim_time 口径)。", "methods": [ "order.wave.batchList" ], "notes": [ "领料状态以波次表 wms_wave_batch.claim_time 是否为空判定(二态:未领料/已领料),与 confirmPrintUnclaimedWaveCount 口径一致", "where 新增 claim_assignment_status 筛选字段(仅 eq,unclaimed/claimed,兼容中文)" ] }, { "version": "2026.09.20-wave-confirm-print-count-fix", "date": "2026-09-20", "type": "updated", "summary": "order.wave.confirmPrintUnclaimedWaveCount 统计口径修正:未领单由订单维度 claim_status 改为波次表维度 wms_wave_batch.claim_time IS NULL,避免历史领单(波次表加 claim_time 字段前)导致少算。", "methods": [ "order.wave.confirmPrintUnclaimedWaveCount" ], "notes": [ "根因:B2026081500088/89 等波次订单 claim_status='fin'(历史领单)但 wave_batch.claim_time=null,订单维度口径误判为已领单导致 count 少算", "新口径:wave_batch(wave_status 0/1、claim_time IS NULL)+ 波次下存在 confirm_print_status='fin' 的非取消订单" ] }, { "version": "2026.09.20-wave-confirm-print-scan-count", "date": "2026-09-20", "type": "added", "summary": "order.wave 新增两个接口:confirmPrintScan(扫面单批量确认打印并写日志,与领单操作一致)与 confirmPrintUnclaimedWaveCount(快速查询已确认打印但未领单波次数量,支持 60s 长轮询,由确认打印/领单版本号驱动)。", "methods": [ "order.wave.confirmPrintScan", "order.wave.confirmPrintUnclaimedWaveCount" ], "notes": [ "confirmPrintScan 复用 print.confirmWavePrint 实现(同入参同返回)", "confirmPrintUnclaimedWaveCount 长轮询:1s 间隔轮询 Redis 版本号(wave:confirm-print:unclaimed:version:{warehouseId}),60s 超时;Redis 不可用时降级为轮询 DB count", "确认打印(print.confirmWavePrint)与领单(pick.waveClaimScan)成功后均递增统计版本号" ] }, { "version": "2026.09.20-wave-batchList-confirm-print", "date": "2026-09-20", "type": "updated", "summary": "order.wave.batchList 波次列表新增 confirm_print_assignment_status 显示与筛选(确认打印状态:未确认打印/部分确认打印/已确认打印)。", "methods": [ "order.wave.batchList" ], "notes": [ "where 新增 confirm_print_assignment_status 筛选字段(仅 eq,英文枚举 unconfirmed/partially_confirmed/confirmed)", "list 每条新增 confirm_print_assignment_status 汇总状态字段" ] }, { "version": "2026.09.20-confirm-wave-print", "date": "2026-09-20", "type": "added", "summary": "订单表新增 confirm_print_status(确认打印状态)字段,并新增 print.confirmWavePrint 波次确认打印接口:打印完成后扫描波次内任一订单面单,批量确认波次下已打印订单。", "methods": [ "print.confirmWavePrint" ], "notes": [ "订单表 wms_order_delivery 及全部分表新增 confirm_print_status ENUM('none','fin'),默认 none;迁移 20260920100000-add-confirm-print-status-to-order-delivery", "波次下存在未打印订单(print_status != 'fin',拦截订单除外)时阻断确认", "拦截订单跳过(不确认、不阻断);全部已确认时重复扫描返回 already_confirmed" ] }, { "version": "2026.09.19-workbench-packOrder-server-side-verification", "date": "2026-09-19", "type": "enhance", "summary": "workbench.packOrder 落库数量改为服务端复查:打包数量/商品总件数/商品种类数不再取设备端上报值,散单取订单分表(orderRow),团购取波次实时统计(totalOrders + 波次商品 SKU 聚合 _fetchWaveItemsSummary),设备端 wave_total_orders/items_count/items_total 仅作交叉校验日志;修复团购波次打包数量落 0/1 的失真问题。", "methods": [ "workbench.packOrder" ], "notes": [ "代码:app/service/systems/workbench.js _packOrder 步骤6 改为服务端复查口径:packQuantity 散单固定 1、团购取 totalOrders(>0 否则 1);packItemQuantity/packSkuCount 散单取 orderRow.items_total/items_count(注:分表列名为 items_count 而非 item_count,此前兜底读 item_count 导致散单 sku_count 兜底落 0,已一并修正),团购取 _fetchWaveItemsSummary(15s 短缓存)聚合 rows.length 与 plan_qty 求和,聚合失败降级为扫描订单值", "交叉校验:设备端上报值与服务端不一致时仅 ctx.logger.info 告警(打包数量/商品总件数/商品种类数三组),落库始终以服务端为准", "开发库数据回填:temp/fix-dev-pack-task-quantities.cjs 已按新口径重算 wms_pack_task 存量 30 条并更新 19 条(保留 update_time、不删行;散单/团购各自取服务端口径,旧 6 月订单缺失的 6 条跳过)", "背景:原语义 pack_quantity=wave_total_orders(缺省 1、传 0 落 0),服务端实时波次订单数未回写,导致列表/统计口径失真", "methods/system.json:workbench.packOrder 参数 wave_total_orders/items_count/items_total 描述同步服务端复查口径;版本 0.3.140 -> 0.3.141(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-getWorkbenchCount-avg-piece-count", "date": "2026-09-19", "type": "enhance", "summary": "workbench.getWorkbenchCount 个人工作台返回调整:新增 group_order_count(团购订单数量,团购任务 pack_quantity 求和,个人/团体工作台均返回);均件数 avg_piece_count 口径改为本人打包任务按 订单数量/人数 折算求和(本人作为打包人参与的任务按任务实际打包人数均分、缺省 1,本工作台单人任务整单计入),不再只统计打包人数≥2 的任务,单人打包 500 单波次可正确得到 500。", "methods": [ "workbench.getWorkbenchCount" ], "notes": [ "代码:app/service/systems/workbench.js getWorkbenchCountByToken 个人分支:新增 groupOrderCount(groupTasks 对 pack_quantity 求和);均件数循环改为 participatedTaskIds 按 packerCount(缺省 1)均分、workbenchTaskIds 未记本人时整单计入", "methods/system.json:getWorkbenchCount response 更新 avg_piece_count/group_order_count 描述;版本 0.3.141 -> 0.3.142(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-getWorkbenchCount", "date": "2026-09-19", "type": "enhance", "summary": "新增 workbench.getWorkbenchCount 当前工作台班次打包统计(免登录/免权限/免鉴权,以工作台 token 鉴权):统计窗口为本地时间当日 08:00 至次日 08:00,早于 08:00 时为昨日 08:00 至今日 08:00;个人工作台(type=personal)统计涉及本人(工作台成员 user_id)的打包数据,返回团购波次数量/散单数量/团散(团购波次数/散单数 2 位小数)/均件数(多人打包任务按 订单数量/人数 折算求和 2 位小数);团体工作台(type=group)返回团购波次数量/团购订单数量(pack_quantity 快照求和)/散单数量。", "methods": [ "workbench.getWorkbenchCount" ], "notes": [ "代码:app/service/systems/workbench.js 新增 getWorkbenchCountByToken(resolveWorkbenchContext 统一 token 校验,无 token 401/无效 403)与辅助方法 buildWorkbenchPackCountTimeRange(8 点班次窗口)/ _round2 / _formatPackCountTime", "个人统计:窗口内本仓库任务走 idx_warehouse_create_time;本人参与任务通过 wms_pack_task_packer(account_id=成员 user_id,分批 IN 500)与 uix_pack_task_account 索引判定;统计范围 = 本工作台任务 ∪ 本人作为打包人参与的任务;均件数只折算本人参与的多人打包(打包人数≥2)任务", "团体统计:workbench_id+create_time 走新增 idx_workbench_create_time 索引", "索引:数据库迁移 20260919100000-add-workbench-create-time-index-to-wms-pack-task.js 为 wms_pack_task 新增 (workbench_id, create_time) 复合索引,避免窗口统计长跨度扫描导致慢 SQL;模型 app/model/pack_task.js indexes 同步补充", "methods/system.json:工作台模块新增 workbench.getWorkbenchCount 条目;版本 0.3.138 -> 0.3.139(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-wave-batchList-sync-assignment-status", "date": "2026-09-19", "type": "enhance", "summary": "order.wave.batchList 响应新增 sync_assignment_status(同步状态,取值:未同步/部分同步/已同步/同步异常),并支持 where.sync_assignment_status 筛选(英文枚举 unsynced/partially_synced/synced,仅 eq,error 并入未同步集合)。", "methods": [ "order.wave.batchList" ], "notes": [ "代码:app/service/systemMethods/order/wave.js BATCH_LIST_ASSIGNMENT_FILTER_SCHEMAS 新增 sync 类型(fieldName=sync_assignment_status,enumMap unsynced/partially_synced/synced → none/partial/finished,caseInsensitive=true,statsColumnPrefix=sync,withErrorStatus=true)", "聚合:wave_order_stats 子查询新增 sync_none_count/sync_fin_count/sync_error_count,按订单 sync_status(padding/fin/error)聚合;none 口径为 sync_status IS NULL 或 NOT IN ('fin','error'),与 review 统计口径一致", "输出:list[].sync_assignment_status 复用 resolveAssignmentStatus,error 优先判定为同步异常,labels 为未同步/部分同步/已同步/同步异常", "筛选:buildBatchListWhereClause allowedFields 新增 sync_assignment_status,仅支持 eq;normalizeBatchListSyncAssignmentStatusFilter/buildBatchListSyncAssignmentFilterClause 复用通用 schema 链路", "methods/system.json:batchList description/where/response 同步 sync_assignment_status 说明;版本 0.3.137 -> 0.3.138(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-getWorkbenchInfo-wave-items-summary", "date": "2026-09-19", "type": "enhance", "summary": "workbench.getWorkbenchInfo 团购任务(pack_mode=2)current_orders items 由空数组改为波次商品 SKU 聚合汇总,彻底解决工作台退出/刷新后团购打包任务无商品信息的问题:新增 _aggregateWaveItems(波次内全部未拦截订单(current+dispatch 分表)商品明细按 SKU 聚合计划数量并合并 stock 详情,聚合行另附 is_wave_summary=true)与 _fetchWaveItemsSummary(按 warehouseId+waveId 维度 15s 短缓存兜底,与 order_count/items_total 同款缓存模式),buildCurrentPackingInfo 团购任务分支调用;散单任务 items 口径不变。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "代码:app/service/systems/workbench.js 新增常量 WAVE_ITEMS_SUMMARY_CACHE_KEY_PREFIX/WAVE_ITEMS_SUMMARY_CACHE_TTL_SECONDS(15s);_aggregateWaveItems 聚合键 stock_id 优先、缺省按 item_code+item_name,stock 详情走 stockWarehouse.getStockDetails 通用缓存链路,异常降级空数组;buildCurrentPackingInfo 团购任务(wave_id>0)调用 _fetchWaveItemsSummary 填 items", "结构:聚合行与散单 items 结构同源(id/order_id 置 0、order_line_no 空串、actual_price null、plan_qty 为波次内该 SKU 合计),另附 is_wave_summary=true 供前端区分单笔明细与波次汇总", "性能:15s 短缓存保证 TTL 内重复查询零开销;缓存未命中时波次订单 ID 查询走 wave_id 索引、items 按 order_id IN 查询走索引,500 单规模波次一次聚合可接受;packOrder/finishPack 后 token 缓存失效,波次聚合缓存在 TTL 内可能与最新波次状态有最多 15s 滞后(与 order_count/items_total 同口径)", "methods/system.json:workbench.getWorkbenchInfo description 与 current_orders[].items/items[].id/items[].order_id/items[].plan_qty 描述更新为双口径,response 新增 current_orders[].items[].is_wave_summary 条目;版本 0.3.136 -> 0.3.137(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-order-items-need-recheck", "date": "2026-09-19", "type": "updated", "summary": "workbench.queryOrder 与 workbench.getWorkbenchInfo 响应商品明细 items 新增 need_recheck 字段(Y=需要复核,N=不需要复核(免验),缺省 Y):组装链路 _fetchOrderItemsDetail 从 stock 详情(getStockDetails 通用缓存链路,其 attributes 已含 need_recheck)透出,补齐工作台打包端商品列表缺少免验标识的问题。", "methods": [ "workbench.queryOrder", "workbench.getWorkbenchInfo" ], "notes": [ "代码:app/service/systems/workbench.js _fetchOrderItemsDetail items 组装新增 need_recheck: String(stock.need_recheck || 'Y').trim()(与 order.recheckOrder.scanOrder/scanTask 同口径,getStockDetails 旧缓存无该字段时兜底 Y)", "workbench.queryOrder 与 workbench.getWorkbenchInfo(current_orders[].items)共用 _fetchOrderItemsDetail,两接口 items 同步生效", "methods/system.json:workbench.queryOrder description 补充 need_recheck 说明,response 新增 items[].need_recheck 条目;workbench.getWorkbenchInfo description 补充「是否需要复核 need_recheck」,response 新增 current_orders[].items[].need_recheck 条目,并将 current_orders[].items[].image_url 类型由 string 修正为 array(实际返回数组);版本 0.3.135 -> 0.3.136(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-getWorkbenchInfo-order-items", "date": "2026-09-19", "type": "enhance", "summary": "enhance: workbench.getWorkbenchInfo 响应 data.current_orders 补全任务上下文字段,解决工作台退出/刷新后无法恢复任务信息的问题:散单任务(pack_mode=1)新增 items 商品明细数组(wms_order_items 分表按 order_id 查询并合并 stock 详情,含 item_code/item_name/plan_qty/barcodes/image_url/packing_requirements 等,与 workbench.queryOrder 返回结构同源),团购任务(pack_mode=2)波次商品明细量大,items 置空数组、以 current_wave 汇总展示;同时每项新增 wms_pack_task 已有字段 item_quantity/sku_count/waybill_code 与订单分表字段 order_type/store_id/items_count/items_total。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "实现:app/service/systems/workbench.js 从 _queryOrder 步骤4 抽取公共方法 _fetchOrderItemsDetail(orderId, warehouseId, sourceTable)(sourceTable=dispatch 查配送明细分表、其余查 current;stock 详情走 stockWarehouse.getStockDetails 自带缓存;异常降级空数组),_queryOrder 改为复用(响应结构不变);buildCurrentPackingInfo 任务遍历时记录订单所在分表 sourceTable 并多取 order_type/store_id/items_count/items_total 字段,散单任务调用 _fetchOrderItemsDetail 补 items,团购任务 items 置空数组", "口径:items 仅对 pack_mode=1 散单任务查询(团购波次逐单聚合开销大且前端以 current_wave 汇总展示);单笔商品明细查询异常仅该项 items 降级为空数组,不影响主信息与其余字段", "性能:buildCurrentPackingInfo 仅在 token 缓存(workbench:token:{token},TTL 300s)未命中或打包状态变更失效后执行,未结束任务通常单条,items 按 order_id 走索引查询,无新增高频开销", "methods/system.json:workbench.getWorkbenchInfo description 补充散单 items/团购空数组与新增字段说明,response 新增 current_orders[].item_quantity/sku_count/waybill_code/order_type/store_id/items_count/items_total 与 current_orders[].items 及 items[] 下 16 个子字段条目(沿用 current_orders[].xxx 嵌套命名惯例);版本 0.3.134 -> 0.3.135(docMeta.version),updatedAt 2026-09-17 -> 2026-09-19" ] }, { "version": "2026.09.17-inbox-group-template-reply-switch", "date": "2026-09-17", "type": "enhance", "summary": "enhance: inbox.group 系列接口接入模板消息回复开关 templateReplyEnabled/template_reply_enabled(0=关闭(普通文本回复) / 1=开启(模板消息回复)),默认 0,所有群类型均支持且独立于 aiEnabled。update 新增入参(未传不修改),reset 重置为关闭,list 返回字段与 where 筛选支持、quickList 返回字段同步补全。", "methods": [ "inbox.group.update", "inbox.group.reset", "inbox.group.list", "inbox.group.quickList" ], "notes": [ "字段落位:wms_inbox_group.template_reply_enabled(TINYINT(1) NOT NULL DEFAULT 0,迁移 database/migrations/20260917100000-add-template-reply-enabled-to-inbox-group.js,model app/model/inbox_group.js 已同步)", "语义:ai_enabled 控制是否 AI 处理;template_reply_enabled 控制命中处理后是否以模板消息形式回复(0=普通文本回复,1=模板消息回复),两开关相互独立", "update:data.templateReplyEnabled===1 时写 1,否则写 0,未传不修改;reset:清空配置时 template_reply_enabled 重置为 0;方法层 app/service/systemMethods/inbox.js#groupUpdate 透传", "list:attributes 与 where specialFieldMap 新增 template_reply_enabled(可筛选),返回行沿用 snake_case 风格(template_reply_enabled)与 ai_enabled 相邻", "quickList:轻量字段新增 template_reply_enabled,下拉选择可感知模板回信开关", "消费方:app/service/inbox/processor.js#loadGroupConfig 读取 template_reply_enabled,为 1 的群命中处理后走 inbox.v2.rules 可配置引擎(模板消息回复)", "文档版本 0.3.133 -> 0.3.134,updatedAt 2026-09-17" ] }, { "version": "2026.09.16-inbox-push-retry-warehouse-setting", "date": "2026-09-16", "type": "updated", "summary": "仓库设置新增「站内信推送失败自动重发」配置(嵌套结构 subject_config.inbox_push_retry,同「收货未入库提醒」):enabled(flag,默认 0=关闭,需显式开启)、window_minutes(重发时间范围,分钟,1-1440,默认 30)。开启后站内信回信/系统通知推送失败(如桥接离线返回 wx offline / qiwe offline 的 503)由定时任务每 3 分钟自动重发,仅重发失败时间在 window_minutes 内的消息,超出范围不再补发。", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "字段落位:wms_store.subject_config.inbox_push_retry(与 receiving_pending_inbound_notice 同表的嵌套 JSON 配置)", "默认值口径:未配置(或配置缺失/非法结构)时 enabled=false、window_minutes=30,即**默认关闭不重发**,需在仓库设置中显式开启", "代码依据:app/model/store.js#normalizeInboxPushRetry(enabled 走 normalizeBooleanFlag;window_minutes 限 1-1440 整数,越界抛「subject_config.inbox_push_retry.window_minutes 必须是 1-1440 的整数(分钟)」);app/service/systems/setting/warehouse.js#WAREHOUSE_SETTING_FIELDS(key=inbox_push_retry,type=object,item_keys 为 enabled/window_minutes)", "消费方:app/service/inbox/message.js#retryFailedByWarehouse(定时任务 app/schedule/retry_inbox_push.js,每 3 分钟;逐仓读设置 → 仅重发该仓窗口内 push_status=3 的出站消息,单仓单轮上限 config.inbox.pushRetryLimit,默认 20)", "全局应急开关:config.inbox.pushRetryEnabled(默认 true),置 false 后所有仓库都不再自动重发;config.inbox.pushRetryWindowMs 仅在仓库未配置/配置非法时兜底(默认 30 分钟)", "getFieldMeta 为通用结构(list + children,不逐字段枚举),本次未改动其文档", "文档版本 0.3.132 -> 0.3.133,updatedAt 2026-09-16" ] }, { "version": "2026.09.16-after-sale-type-subtype-crud", "date": "2026-09-16", "type": "added", "summary": "售后模块新增售后类型/子类型自定义配置 8 个接口:afterSale.typeList / typeCreate / typeUpdate / typeDelete / subTypeList / subTypeCreate / subTypeUpdate / subTypeDelete。列表返回系统级(warehouse_id=null、is_system=1)+ 当前仓库自定义(is_system=0)合并;创建仅允许仓库自定义;改/删仅命中 id + 当前仓库 + is_system=0;系统级不允许编辑/删除(未命中统一 404);编码仅允许小写字母/数字/下划线(type≤20、sub_type≤50、name≤50)且创建时校验不与系统级重复、同仓库内唯一(409);update 编码不可变;删除不做级联(类型下存在自定义子类型或子类型已被售后单引用时 409 拒绝)。", "methods": [ "afterSale.typeList", "afterSale.typeCreate", "afterSale.typeUpdate", "afterSale.typeDelete", "afterSale.subTypeList", "afterSale.subTypeCreate", "afterSale.subTypeUpdate", "afterSale.subTypeDelete" ], "notes": [ "接口口径:全部挂 afterSale 模块(POST /system?method=afterSale.xxx);方法层 app/service/systemMethods/afterSale.js(typeList/typeCreate/typeUpdate/typeDelete/subTypeList/subTypeCreate/subTypeUpdate/subTypeDelete)→ 业务层 app/service/systems/afterSale.js(getTypeList/createType/updateType/deleteType/getSubTypeList/createSubType/updateSubType/deleteSubType)", "权限口径(afterSale.js#systemInit):8 个方法全部免权限(_noNeedRight)、免仓库有效期校验(_noNeedAuth)、需登录(不在 _noNeedLogin);typeList/subTypeList 免日志(_noNeedLog),其余 6 个写系统日志", "仓库维度隔离:列表按 [warehouse_id IS NULL OR warehouse_id=当前仓库] 合并;创建/改/删均以 ctx.user.store_id 为 warehouseId(无仓库上下文报 400),改/删仅命中 id+warehouse_id+is_system=0", "系统级保护:is_system=1 记录不允许编辑/删除,未命中统一 404「不存在、无权操作或为系统预设类型」", "编码规则:type/sub_type 仅允许 /^[a-z0-9_]+$/(小写字母/数字/下划线);type≤20 字符、sub_type≤50、name≤50;创建时校验编码不与系统级重复、同仓库内唯一(409),MySQL 唯一索引 uk_type_warehouse / uk_type_subtype_warehouse 兜底", "编码不可变:typeUpdate 仅允许 name/is_enabled/sort_order,type 不可改;subTypeUpdate 仅允许 name/is_enabled/sort_order,type 与 sub_type 均不可改", "删除策略(拒绝,不做级联):typeDelete 在该类型下存在当前仓库自定义子类型时拒绝(409);subTypeDelete 在 wms_after_sale 存在该 type/sub_type 引用(deleted_at 为空)时拒绝(409「已被售后单使用」)", "错误码口径:400(参数/编码格式/无仓库上下文)、404(不存在/无权/系统预设)、409(编码重复/存在自定义子类型/已被售后单使用)", "数据模型:wms_after_sale_type / wms_after_sale_sub_type(app/model/after_sale_type.js、after_sale_sub_type.js;迁移 database/migrations/20260916100000-create-wms-after-sale-type-tables.js)", "AI_METHOD_ROUTING.md 新增 5.8 节(8 个方法的 method→文件→函数→登录→鉴权口径速查表)并刷新第 6 节自动清单(systemMethods/afterSale.js 22→30,systems/afterSale.js 29→46)", "文档版本 0.3.131 -> 0.3.132,updatedAt 2026-09-16;写入通过 script/update-api-doc.cjs(先 --dry-run)" ] }, { "version": "2026.09.15-warehouse-pending-receiving-notice-template", "date": "2026-09-15", "type": "updated", "summary": "收货未入库提醒支持自定义通知短语:subject_config.receiving_pending_inbound_notice 新增 notice_template(仓库/客服群短语)与 store_notice_template(货主群短语),支持变量替换({warehouse}/{warehouse_id}/{store}/{store_id}/{count}/{min_hours}/{max_hours}/{date}/{numbers}),消息结构固定为「短语 + 换行 + 明细(一行一条)+ 查看链接」,留空使用默认短语。", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "字段口径:wms_store.subject_config.receiving_pending_inbound_notice.notice_template / store_notice_template,均为 string、最长 500 字符、空值回退默认短语", "默认短语:仓库/客服群「【收货未入库提醒】以下 {count} 个收货单已超过 {min_hours} 小时且不足 {max_hours} 小时,仍未完成入库,请及时跟进:」;货主群「【收货未入库提醒】以下 {count} 个收货单已超过 {min_hours} 小时仍未完成入库,请尽快完成收货入库:」", "可用变量:{warehouse} 仓库名(缺名回退「仓库{id}」)/ {warehouse_id} / {store} 货主名(未绑定为「未绑定货主」)/ {store_id} / {count} 本批单数 / {min_hours} / {max_hours} / {date} 提醒日期 YYYY-MM-DD / {numbers} 本批收货单号(最多 20 个,超出以「等 N 单」结尾);未识别占位符原样保留", "校验:短语超 500 字符报 400「subject_config.receiving_pending_inbound_notice.notice_template 长度不能超过 500 字符」(store_notice_template 同);空串/null 回退默认短语(模型 app/model/store.js#normalizeReceivingPendingInboundNotice)", "消息结构:短语 + \\n + 明细行(一行一条,最多 20 行「序号.单号 货主 数量 创建时间 状态」)+ \\n + 快速查看/详情查看链接;不再在结尾追加句号", "单测:test/app/service/systems/receiving_pending_notice.test.js 新增「短语变量替换 + 明细逐行」「未识别占位符原样保留 + 货主短语缺省回退」两用例(共 11 用例)", "文档版本 0.3.130 -> 0.3.131,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run)" ] }, { "version": "2026.09.15-warehouse-pending-receiving-notice", "date": "2026-09-15", "type": "updated", "summary": "仓库设置(wms_store.subject_config)新增「收货未入库提醒」配置 receiving_pending_inbound_notice:enabled(是否通知收货未入库,flag,默认 0 关闭)/ notice_time(提醒时间 HH:mm,默认 08:30)/ min_hours(超时下限小时,默认 24)/ max_hours(超时上限小时,默认 48,须大于 min_hours)。开启后由定时任务(app/schedule/notice_receiving_pending_inbound.js,每 5 分钟检查、按仓库配置的提醒时间执行,每天一次)扫描超时未完成入库的收货单并通知:绑定货主的通知货主收货群(未配群回退仓库客服群),未绑定货主的通知仓库客服群。setting.warehouse.getSettings 响应与 setting.warehouse.saveSettings 入参补充该字段文档。", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "字段口径:wms_store.subject_config.receiving_pending_inbound_notice = { enabled, notice_time, min_hours, max_hours };默认 { enabled:false, notice_time:\"08:30\", min_hours:24, max_hours:48 }(默认不通知)", "模型默认值与校验:app/model/store.js(DEFAULT_SUBJECT_CONFIG + normalizeReceivingPendingInboundNotice);字段元信息:app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS,type=object)", "校验口径:notice_time 必须为 HH:mm(如 08:30),否则 400「subject_config.receiving_pending_inbound_notice.notice_time 格式必须为 HH:mm(如 08:30)」;min_hours/max_hours 必须为大于 0 的整数,且 min_hours 必须小于 max_hours,否则 400", "定时任务:app/schedule/notice_receiving_pending_inbound.js(interval 5m、单 worker、进程内防重入)→ app/service/systems/receiving_pending_notice.js#execute;命中口径为「创建时间超过 min_hours 且不足 max_hours」且(status=receiving 或 storage_status<>all)、is_deleted=0、status<>cancelled;货主维度聚合成一条消息(每行一个收货单,最多 20 行)", "通知事件:新增事件码 receiving_pending_inbound(app/model/notification_webhook.js 注册),固定群订阅 app/service/systems/notice/index.js#FIXED_GROUP_SUBSCRIPTIONS:store:receiving + fallbackTargets warehouse:customer_service(无货主或货主未配收货群时通知仓库客服群)", "幂等:同一仓库+货主同一自然日只推送一次(Redis 当日锁 receiving_pending_notice:lock:{warehouseId}:{YYYYMMDD},TTL 24h;执行异常释放锁,宽限窗口内下一轮重试),消息 ext_id 含 receiving-pending:{warehouseId}:{storeId}:{YYYYMMDD}", "单测:test/app/service/systems/receiving_pending_notice.test.js(9 用例:开关关闭/未命中提醒时间不执行、超时窗口查询条件、货主群通知、无货主回退、当日只提醒一次、异常释放锁重试、行数截断、非法配置回退默认)", "文档版本 0.3.129 -> 0.3.130,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run)" ] }, { "version": "2026.09.15-camera-ptz-camera-id", "date": "2026-09-15", "type": "updated", "summary": "云台(PTZ)四个接口下发给打印服务时请求体统一携带摄像头ID:camera.ptzControl / camera.ptzStop / camera.ptzPresetGoto / camera.ptzPresetSet 的请求体由 { warehouse_id, rtspUrl, … } 改为 { warehouse_id, cameraId, rtspUrl, … }(cameraId 取 wms_camera.id,数值型;warehouse_id 仍为字符串)。接口入参与响应不变。", "methods": [ "camera.ptzControl", "camera.ptzStop", "camera.ptzPresetGoto", "camera.ptzPresetSet" ], "notes": [ "变更内容:4 个 PTZ 端点(/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto、/camera/ptzPresetSet)的请求体新增 cameraId 字段,值取摄像头记录主键 wms_camera.id(Number() 归一化后以数值下发),便于打印服务侧按摄像头ID定位/校验设备与日志排查", "前端入参不变:cameraId 由 WMS 服务端从查询到的摄像头记录自动带入(前端仍只传 id,无需重复传摄像头ID;也无需传 computerId)", "实现位置:app/lib/ptz_client.js#_send 统一拼接请求体 { warehouse_id: String(warehouseId), cameraId, ...业务字段 },四个入口方法无需各自处理;同时补 camera.id 合法性校验(非正整数报「摄像头ID不合法」)", "请求体口径(warehouse_id 为字符串、cameraId 为数值):ptzControl { warehouse_id, cameraId, rtspUrl, action, speed };ptzStop { warehouse_id, cameraId, rtspUrl, action };ptzPresetGoto { warehouse_id, cameraId, rtspUrl, presetId };ptzPresetSet { warehouse_id, cameraId, rtspUrl, presetId }", "响应不变:仍为 { camera_id, rtsp_url, action, speed | preset_id, print_service_response };错误码不变(400/404/500)", "回归:node run/check-camera-ptz.cjs(68 用例,四个方法的请求体断言均已含 cameraId)全部通过;npx eslint 无告警", "文档版本 0.3.128 -> 0.3.129,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run)", "AI_METHOD_ROUTING.md 5.7 段「下发通道」条目已同步补充 cameraId" ] }, { "version": "2026.09.15-camera-ptz-preset-set", "date": "2026-09-15", "type": "added", "summary": "摄像头模块新增 camera.ptzPresetSet(云台预置点设置):把摄像头当前机位保存为指定预置点,入参 id + presetId(1-256),一次调用即可、无需配对 stop。与既有的 camera.ptzPresetGoto(跳转到预置点)构成「存点 / 跳转」一对,写入载体为打印服务端点 POST {printService.url}/camera/ptzPresetSet,请求体 { warehouse_id, rtspUrl, presetId }。", "methods": [ "camera.ptzPresetSet" ], "notes": [ "接口口径:与 camera.ptzControl / camera.ptzStop / camera.ptzPresetGoto 完全一致 —— 独立端点(不带 computerId)、扁平请求体、warehouse_id 为字符串、rtspUrl 服务端按摄像头记录组装", "入参:id(摄像头ID,必填)、presetId(预置点编号,必填,1-256 整数,字符串数字会被归一化);无 speed / action 参数", "响应:data 为 { camera_id, rtsp_url, preset_id, print_service_response }", "错误码:400(摄像头ID不能为空 / 预置点编号不能为空或不是 1-256 的整数 / 摄像头未配置IP地址)、404(摄像头不存在或无权操作)、500(打印服务调用失败,含 HTTP 非 2xx 与回包 status=fail / success=false)", "权限口径:与 camera.setOsd 一致,camera.js#systemInit 已把 ptzPresetSet 加入 _noNeedRight/_noNeedAuth,_noNeedLog 为 *(不写系统日志)", "代码依据:app/lib/ptz_client.js#PTZ_PATH.PRESET_SET 与 #presetSet(复用 normalizePresetId/_send/buildRtspUrl)、app/service/systems/camera.js#ptzPresetSet(复用 _findCameraForControl/_assertPtzSuccess)、app/service/systemMethods/camera.js#ptzPresetSet", "回归:node run/check-camera-ptz.cjs(67 用例,新增 presetSet 的端点/请求体/归一化/边界/摄像头不存在 6 项断言)全部通过;npx eslint 无告警", "文档版本 0.3.127 -> 0.3.128,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run),新增 method 由脚本追加到「摄像头模块」分组尾部", "AI_METHOD_ROUTING.md 5.7 段表格已补 camera.ptzPresetSet 行,并刷新第 6 节自动清单(systemMethods/camera.js 与 systems/camera.js 方法数 +1)" ] }, { "version": "2026.09.15-camera-ptz-wms-endpoint", "date": "2026-09-15", "type": "updated", "summary": "云台(PTZ)三接口入参口径变更:camera.ptzControl / camera.ptzStop / camera.ptzPresetGoto 去除 computerId(打印电脑ID)参数,改为打印服务独立端点下发 —— POST {printService.url}/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto,请求体 { warehouse_id, rtspUrl, action, speed | presetId },与 camera.setOsd 同风格(独立端点、不带电脑ID、warehouse_id 为字符串)。响应同步去除 computer_id 字段。", "methods": [ "camera.ptzControl", "camera.ptzStop", "camera.ptzPresetGoto" ], "notes": [ "变更原因:与 camera.setOsd 对齐 —— 打印服务按 rtspUrl 定位摄像头,无需电脑房间路由;WMS 服务端也推导不出打印电脑ID(wms_print_computer.id 由打印端 /auth/bind 按「仓库+打印台名称」创建,Web 端登录用户仅有 store_id,wms_workbench 只有 device_ids)", "入参变化:三个接口均删除 computerId(必填);camera.ptzControl 保留 id/action/speed,camera.ptzStop 保留 id/action,camera.ptzPresetGoto 保留 id/presetId", "下发报文变化:由 POST {printService.url}/sendToRoom 信封 { warehouse, computerId, method: 'camera.ptz.control'|'camera.ptz.stop'|'camera.ptz.presetGoto', data } 改为三个独立端点 + 扁平请求体 { warehouse_id, rtspUrl, action, speed | presetId }", "响应变化:data 由 { camera_id, computer_id, rtsp_url, action, speed | preset_id, print_service_response } 改为 { camera_id, rtsp_url, action, speed | preset_id, print_service_response }(删除 computer_id)", "错误码变化:不再返回「打印电脑ID不能为空/不合法」;其余 400(摄像头ID为空、方向不合法、转速越界、预置点越界、摄像头未配置IP)/404/500 口径不变", "同一日已存在本接口首次登记的变更记录 2026.09.15-camera-ptz-control(type=added,尚未发布);script/update-api-doc.cjs 的变更记录仅支持头部插入新记录、不支持原位追加,故按兜底方案新增带 -wms-endpoint 后缀的独立记录", "代码依据:app/lib/ptz_client.js#PTZ_PATH(/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto)+ _send(请求体 warehouse_id 转字符串、字段与 setOSD 对齐)、app/service/systems/camera.js(删除 _normalizeComputerId;_findCameraForControl/_assertPtzSuccess 保留;三方法返回值去掉 computer_id)", "回归:node run/check-camera-ptz.cjs(60 用例,含「请求体不带 computerId」断言)全部通过;npx eslint 无告警", "文档版本 0.3.126 -> 0.3.127,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run)", "AI_METHOD_ROUTING.md 5.7 段已同步(删除 computerId 说明、改为独立端点),并刷新第 6 节自动清单" ] }, { "version": "2026.09.15-camera-ptz-control", "date": "2026-09-15", "type": "added", "summary": "摄像头模块新增云台控制(PTZ)三个接口:camera.ptzControl(按下,按方向持续转动,action 支持 8 个位置 up/down/left/right/upleft/upright/downleft/downright,speed 1-7 默认 4)、camera.ptzStop(松手,action 必须与按下时一致)、camera.ptzPresetGoto(预置点跳转,presetId 1-256,一次调用无需 stop)。服务端按摄像头记录组装 rtspUrl,通过打印服务统一指令信封 POST {printService.url}/sendToRoom 下发 { warehouse, computerId, method, data },computerId 由前端传入。", "methods": [ "camera.ptzControl", "camera.ptzStop", "camera.ptzPresetGoto" ], "notes": [ "接口口径:method 与打印服务一一对应 —— camera.ptzControl -> camera.ptz.control(data: { rtspUrl, action, speed })、camera.ptzStop -> camera.ptz.stop(data: { rtspUrl, action })、camera.ptzPresetGoto -> camera.ptz.presetGoto(data: { rtspUrl, presetId })", "action 枚举(8 个位置,与打印服务约定,写入 params[].action.list,顺序固定):up-上、down-下、left-左、right-右、upleft-左上、upright-右上、downleft-左下、downright-右下;大小写不敏感,服务端转小写后校验,非法值报 400", "参数校验:id 必填;computerId 必填且为正整数;action 必填且属于 8 个方向;speed 可选取 1-7 整数(默认 4);presetId 必填取 1-256 整数(转速/预置点仅约束下发的打印服务指令口径,摄像头端实际生效范围以设备为准)", "rtspUrl 由服务端组装(rtsp://{username}:{password}@{ip}:554/stream{channel_id}),与 camera.setOsd 同口径,前端无需传;摄像头无 ip 时报 400「摄像头未配置IP地址,无法组装RTSP地址」", "权限口径:与 camera.setOsd 一致,camera.js#systemInit 已把 ptzControl/ptzStop/ptzPresetGoto 加入 _noNeedRight/_noNeedAuth,且 _noNeedLog 为 *(PTZ 高频调用不写系统日志)", "响应口径:成功时 data 为 { camera_id, computer_id, rtsp_url, action, speed | preset_id, print_service_response }(print_service_response 为打印服务原始回信,便于前端/排查核对);打印服务 HTTP 非 2xx、或回包 status=fail / success=false 时按 500 抛出并带打印服务 message", "代码依据:app/lib/ptz_client.js(PTZ_METHOD/PTZ_ACTION_LIST/PTZ_ACTIONS + control/stop/presetGoto + buildRtspUrl 与 osd_client 同口径)、app/service/systems/camera.js(_findCameraForControl/_normalizeComputerId/_assertPtzSuccess + ptzControl/ptzStop/ptzPresetGoto)、app/service/systemMethods/camera.js(三个入口方法 + systemInit 免权限声明)", "文档版本 0.3.125 -> 0.3.126,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run),新增 method 由脚本追加到「摄像头模块」分组尾部", "AI_METHOD_ROUTING.md 已同步刷新第 6 节自动清单(app/service/systemMethods/camera.js 由 6 个方法变为 9 个)" ] }, { "version": "2026.09.15-returnUnpack.transferByWaybills-ids", "date": "2026-09-15", "type": "updated", "summary": "returnUnpack.transferByWaybills 入参口径变更:waybill_codes(运单号字符串/数组)改为 ids(运单表主键 wms_order_express.id,单个数值或数组,Number() 归一化 + 过滤非正整数 + 去重,单次上限 200)。系统层改为按 id IN (ids) + warehouse_id 一次批量反查运单,未命中即不存在或非本仓库,记失败「运单不存在」。失败项新增 waybill_id,waybill_code 仅运单命中时有值(否则为 null)。错误码新增 400「运单号为空,无法转入退件登记」与 500「反查运单失败,请稍后重试」。业务规则不变(统一置 is_back='Y'、子单跳过、明细按订单原本明细 1:1 复制、幂等复用非 cancelled 拆包单)。", "methods": [ "returnUnpack.transferByWaybills" ], "notes": [ "本次为入参变更;同日已存在 change 记录 2026.09.15-returnUnpack.transferByWaybills(type=added,接口首次登记,尚未发布/未提交)。script/update-api-doc.cjs 的变更记录结构仅支持新记录插入数组头部、不支持对既有记录原位追加,故本次按兜底方案新增 version 带 -ids 后缀的独立记录(summary 已说明是入参变更)", "代码依据:app/service/systems/return_unpack.js#transferByWaybills({ ids })(Number() 归一化 → 过滤非正整数 → 去重 → 上限 200 → id IN (ids)+warehouse_id 批量反查;failed[] 元素为 { waybill_id, waybill_code: 命中时有值否则 null, reason });app/service/systemMethods/returnUnpack.js#transferByWaybills(data) 取 data.ids 后透传,方法层包装不变", "错误码变化:新增 400「运单号为空,无法转入退件登记」、500「反查运单失败,请稍后重试」;400「waybill_codes 不能为空」改为「ids 不能为空」;其余 400/404/401/403/500 口径不变", "响应结构变化:failed[] 元素由 { waybill_code, reason } 调整为 { waybill_id, waybill_code, reason };success[] 元素由 { waybill_code, unpack_id, unpack_no, reused, detail_count, total_quantity } 调整为含 waybill_id 的 7 字段", "回归:代码已先行修改并跑通 76/76 回归,本次仅同步文档;AI_METHOD_ROUTING.md 方法名与数量不变,无需同步", "文档版本 0.3.124 -> 0.3.125,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.15-order-list-default-where-fix", "date": "2026-09-15", "type": "updated", "summary": "修正 order.pendingOrder.list / order.outboundOrder.list 的默认筛选说明,使其与 app/service/systemMethods/order/base.js#MODULE_CONFIGS 实现一致(前者 step in [1,2,3];后者 outbound_status in [fin,padding] 且 step in [4,9])。", "methods": [ "order.pendingOrder.list", "order.outboundOrder.list" ], "notes": [ "实现口径:base.js MODULE_CONFIGS.pendingOrder.defaultWhere = { outbound_status: { operator: \"ne\", value: \"padding\" }, step: { operator: \"in\", value: [1,2,3] } };outboundOrder.defaultWhere = { outbound_status: { operator: \"in\", value: [\"fin\",\"padding\"] }, step: { operator: \"in\", value: [4,9] } };两者 list 均直接 this.listByModule(module, data),无额外覆盖", "原描述偏差:pendingOrder 写 step in [1,2](漏 3);outboundOrder 写 outbound_status in [none,padding] 且 step in [1,2](正确为 outbound_status in [fin,padding] 且 step in [4,9])", "旁证:run/check-order-list-create-channel.cjs 的期望值按 MODULE_CONFIGS 语义独立构造(pendingOrder step in [1,2,3];outboundOrder outbound_status in [fin,padding] + step in [4,9]),45/45 通过", "文档版本 0.3.123 -> 0.3.124,updatedAt 2026-09-15;通过 script/update-api-doc.cjs 写入(先 --dry-run),按分组拆 spec(首个带 change,其余 --doc-only)" ] }, { "version": "2026.09.15-order-list-create-channel-filter", "date": "2026-09-15", "type": "updated", "summary": "订单工作台各订单列表接口(order.list、order.reviewOrder.list、order.pendingOrder.list、order.outboundOrder.list、order.expectionOrder.list、order.entrustOrder.list、order.deliveryOrder.list、order.deliveryExpectionOrder.list、order.archiveOrder.list)的 where 参数补充 create_channel 订单来源渠道查询条件说明与枚举(MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单),并给出裸值/裸数组/标准 operator 结构写法。", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list" ], "notes": [ "口径来源:9 个列表均走 app/service/systemMethods/order/base.js#listByModule -> buildWhere -> lib/query_condition_parser.js(where 无字段白名单,字段直接透传为订单分表条件),故 create_channel 可作精确/多选/排除筛选", "枚举来源:app/service/systemMethods/order/base.js CREATE_CHANNEL_LABELS(MANUAL 手工单 / API 接口 / QM 奇门 / STOCKOUT 出库转单)、app/service/systems/order_async.js CREATE_CHANNEL_* 常量;列定义见 database/migrations/20260813140000-add-order-delivery-base-table-missing-columns.js(create_channel STRING(20),默认 MANUAL)", "响应口径:base.js#normalizeOrderListItem 会把 create_channel 通过 formatCreateChannelLabel 转成中文标签,故文档中明确「查询传英文枚举、响应回中文标签」", "已核实列存在性(本地库 information_schema):wms_order_delivery_{100000,1000028} 及 _dispatch/_history/_outsourced 分表均含 create_channel 列;本地数据取值分布仅 MANUAL(73715)/QM(1082)/API(18)/STOCKOUT(2)", "不支持的订单类列表(未纳入本次说明):order.recheckOrder.recheckOrderList / queryRecheckOrderSingleList(手写 SQL,仅 keyword/wave_no/recheck_status/pick_status/wave_index/stock_query)、order.packing.list(仅 status/pack_mode/waybill_code/wave_no 等)、order.wave.batchList(wave.js#buildBatchListWhereClause 字段白名单不含 create_channel)", "文档版本 0.3.122 -> 0.3.123,updatedAt 2026-09-15;写入走 script/update-api-doc.cjs(先 --dry-run),首个 spec 带 change,其余 --doc-only" ] }, { "version": "2026.09.15-returnUnpack.transferByWaybills", "date": "2026-09-15", "type": "added", "summary": "新增退回拆包接口 returnUnpack.transferByWaybills(运单批量转入退件登记):waybill_codes 单个字符串或数组批量转入(trim+去重+过滤空值,上限 200),逐单处理、单条失败不阻断;命中运单统一置 wms_order_express.is_back='Y';子单(business_key>1)跳过;幂等复用同仓库同运单号有效拆包单(reused=true,复用单明细为空按订单明细补写);明细按运单关联订单原明细 1:1 复制(items JSON 优先回退明细分表,复用 afterSale._resolveOrderDetail);命中退回收到登记回填 return_received_id;新增权限 568(API:运单批量转入退件登记,授权角色 27/26)。", "methods": [ "returnUnpack.transferByWaybills" ], "notes": [ "方法层:app/service/systemMethods/returnUnpack.js 新增 transferByWaybills(data)(位于 create 之后),统一 this.success('ok', data) 包装,未加入 _noNeedRight/_noNeedLogin/_noNeedLog/_noNeedAuth 免检清单(isNeedAuth=true、isNeedLogin=true)", "系统层:app/service/systems/return_unpack.js 新增 transferByWaybills / _insertMainWithRetry / _transferOneWaybill / _backfillDetailsFromOrder / _countDetails / _resolveReturnReceivedId / _buildTransferDetailRows(共 7 个方法)", "权限:database/migrations/20260915100000-add-return-unpack-transfer-waybills-permission.js 固定 ID 568 path=returnUnpack.transferByWaybills meta_title=API:运单批量转入退件登记,角色授权 27(仓库组-员工)→ 26(仓库组-主管),INSERT IGNORE + 权限数组追加去重排序幂等", "响应错误码:400 参数/上下文/子单跳过/无明细可复制、404 运单不存在、401/403 与其它接口一致、500 服务器内部错误;单运单失败进入 failed[] 不抛错", "AI_METHOD_ROUTING.md 同步:systemMethods/returnUnpack.js 20→21(新增 transferByWaybills)、systems/return_unpack.js 43→50(新增 7 个方法);docs/*.md 无退回拆包接口清单,无需同步", "文档版本 0.3.121 -> 0.3.122,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ], "module": "returnUnpack" }, { "version": "2026.09.15-storage-inventory-update-expiry", "date": "2026-09-15", "type": "added", "summary": "新增 storage.inventory.updateExpiry 接口:传入 storage_id 与 production_date / expiry_date,维护当前库存批次的生产日期与到期日期;两个日期至少传一个,未传字段保持原值,传 null/空串清空,合并后生产日期不得晚于到期日期。", "methods": [ "storage.inventory.updateExpiry" ], "notes": [ "app/service/systems/storage/inventory.js 新增 updateExpiry(data):校验 storage_id 为正整数、两个日期格式合法且至少传一个、当前仓库上下文(ctx.user.store_id);单事务 + 行锁(SELECT ... FOR UPDATE)按 id + warehouse_id + is_enabled=1 + delete_at IS NULL 定位库存记录,跨仓库按 404 处理", "app/service/systems/storage/inventory.js 新增模块级 helper parseStorageDateInput:undefined=未传(provided=false)、null/空串=清空、YYYY-MM-DD / YYYY/MM/DD / YYYY-MM-DD HH:mm:ss / ISO / Date 统一规范化为 YYYY-MM-DD(并校验真实存在日期,如 2026-02-30 判非法)、其它非法", "业务校验:合并后(未传字段取库内现值)生产日期不能晚于到期日期,违反返回 400「生产日期(x)不能晚于到期日期(y)」;两值均与库内一致时返回 changed=false,不写库、不记日志", "成功路径写业务操作日志(operationLog.createOperationLog,失败仅告警不影响主流程):business_type=storage、operation_code=STORAGE_UPDATE_EXPIRY、before_changes 含维护前两个日期与 storage/space/stock/batch 快照、message 为「生产日期 A → B;到期日期 C → D」摘要", "app/dict/businessDict.js OPERATION_CODE 新增 STORAGE_UPDATE_EXPIRY: '维护库存效期'", "app/service/systemMethods/storage/inventory.js 新增 updateExpiry 包装方法(this.success('ok', result) 透传 code/message/data),未加入 _noNeedRight/_noNeedAuth 豁免列表:该接口为写操作,需要 API 权限与仓库有效期校验", "权限联动:wms_permission 需新增 path=storage.inventory.updateExpiry 的接口权限并授予相关角色(校验逻辑 app/service/main.js checkApiPermission,路径比较不区分大小写);permissions='*' 的角色无需授权", "响应错误码:400 参数/业务校验失败、404 库存记录不存在或无权访问、409 库存记录被锁定请稍后重试(Lock wait timeout)", "验证:ESLint(npx eslint app/service/systems/storage/inventory.js app/service/systemMethods/storage/inventory.js app/dict/businessDict.js)0 error;parseStorageDateInput 通过临时脚本 temp/verify-update-expiry-date-parse.cjs 逐用例验证(未传/空/清空/多格式/非法日期/Date 对象);未执行任何部署/回退脚本,未改动数据库与 Redis 数据" ], "module": "storage.inventory" }, { "version": "2026.09.15-workbench-pack-osd-reset", "date": "2026-09-15", "type": "updated", "summary": "打包任务结束统一复位工作台摄像头 OSD 为「无任务」:覆盖三条结束路径 —— workbench.finishPack 手动结束、workbench.packOrder 关闭上一个未结束任务(先复位再串行下发新任务 OSD,避免复位覆盖新文字)、packTaskAutoFinish 定时任务自动结束;统一调用 workbench._resetPackOsd 回写 Redis osd_{workbenchId}=无任务 并逐台摄像头下发「无任务」,异常仅告警不阻塞打包主流程。", "methods": [ "workbench.packOrder", "workbench.finishPack" ], "notes": [ "代码:app/service/systems/workbench.js 新增 OSD_IDLE_TEXT/OSD_CACHE_KEY_PREFIX/OSD_CACHE_TTL_SECONDS 常量与 _resetPackOsd;_finishPack、_packOrder 步骤4/7.5 接入", "代码:app/service/systems/pack_task_auto_finish.js 扫描补 workbench_id,自动结束后调用 _resetPackOsd;app/schedule/auto_finish_pack_task.js 注释同步", "回归测试:test/workbench_reset_pack_osd.test.cjs(8 用例,mock ctx)全部通过" ] }, { "version": "2026.09.13-stockout-waybill-codes-single-deprecate", "date": "2026-09-13", "type": "updated", "module": "storage.stockout", "summary": "出库单运单号口径收敛为复数:storage.stockout.confirm 的确认校验与出站回传改为以 waybill_codes 为准(对齐奇门 packages.package[] 多运单模型,不使用 deliveryOrder.expressCode),错误文案由「未填写运单号(waybill_code)」改为 (waybill_codes);storage.stockout.updateExpress 以 waybill_codes 为主,单数 waybill_code 降级为镜像字段(传复数时自动镜像首个数,传空数组/null 时同步置 NULL),仅传单数的旧调用方行为不变。存量单在复数缺失时仍回退单数,避免卡单。", "methods": [ "storage.stockout.confirm", "storage.stockout.updateExpress" ], "notes": [ "代码依据:app/service/systemMethods/storage/stockout.js#confirm(校验改为 waybill_codes 优先、单数回退;报文运单号复用校验结果)、#updateExpress(waybill_codes 写入时镜像 waybill_code = 首个);app/service/systems/order_async.js#syncStockoutOrders 写回注释同步为「复数为准、单数为镜像」", "协议依据:taobao.qimen.stockout.confirm 中运单号在 packages.package[].expressCode(多包裹/多运单,每个包裹一个),deliveryOrder.expressCode 为单据级单运单号(多运单场景不使用)", "回归测试:stockout.confirm.outbound.test.js 扩到 8 条(新增「一单多运单只填复数即可确认且回传 packages.package[] 两个包裹」「存量单仅有单数仍可确认」);新增 stockout.updateExpress.test.js 7 条(复数镜像、空数组/null 清空、复数优先覆盖单数、仅单数行为不变、非数组 400、无字段 400)", "对外契约影响:确认失败文案变化(waybill_code → waybill_codes);updateExpress 响应仍同时返回两列(waybill_codes 为准,waybill_code 为镜像);仅传 waybill_codes 即可完成填写与确认,调用方可不再传单数", "存量兼容:复数缺失时 confirm 回退单数、updateExpress 仅传单数行为不变,因此旧调用方无需强制同步升级", "文档版本 0.3.118 -> 0.3.119,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.13-storage-stockout-confirm-source-routing", "date": "2026-09-13", "type": "updated", "module": "storage.stockout", "summary": "修复 storage.stockout.confirm 出站回传未按出库单来源分流的问题:confirm 改为复用 systems/order_async.js#notifyStockoutExternalInternal(QM→奇门 taobao.qimen.stockout.confirm,API→OpenAPI 回调 method=stockout.confirm,WMS 等内部来源无需通知直接成功),与出库单转订单回传同一套分流口径;API 来源 appKey 按货主合约反查。修复后 API 来源出库单不再被错误发往奇门(此前被奇门以「-1 无法匹配货主」拒绝,且跳过出站同样走失败分支,导致该来源出库单无法确认);同时确认文档同步分流语义与新增失败文案。", "methods": [ "storage.stockout.confirm" ], "notes": [ "代码依据:app/service/systemMethods/storage/stockout.js#confirm(第二步由硬编码 qimenClient.send 改为调用 ctx.service.systems.orderAsync.buildStockoutConfirmRequest / resolveOpenApiAppByStore / notifyStockoutExternal);app/service/systems/order_async.js 新增 3 个实例方法(buildStockoutConfirmRequest / notifyStockoutExternal / resolveOpenApiAppByStore)复用既有模块级实现,未改动原函数与其既有调用方", "回归测试:test/app/service/systemMethods/storage/stockout.confirm.outbound.test.js 新增 6 条用例(API 走回调不发奇门、API 无可用 ApiApp 时不回落奇门、QM 仍走奇门且不发回调、WMS 内部来源直接完成、QM 奇门失败保持 CREATED、未填 waybill_code 前置拒绝)", "对照验证:order_async.openapi.callback.test.js(5 failing)与 order_async.syncOrderIds.test.js(13 failing)为改动前既有失败(测试未跟上 2026-09-13 API 回传「不再静默跳过」的口径变更),已用「新增方法临时抛错后失败数不变」判定与本次改动无路径交集", "对外契约影响:入参、成功响应结构不变;新增可能出现的失败文案「出库单回传服务不可用」与 API 来源的「缺少 appKey,无法回传出库单」;WMS 等内部来源出库单由「出站同步失败: 未发起出站通知」变为可正常确认完成", "文档版本 0.3.117 -> 0.3.118,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.13-storage-stockout-waybill-field-align", "date": "2026-09-13", "type": "updated", "module": "storage.stockout", "summary": "修正 storage.stockout.updateExpress / storage.stockout.confirm 的运单号字段口径(仅文档,未改代码):updateExpress 的入参由「express_code=运单号、express_codes=运单号列表」纠正为真实实现口径——express_code=快递公司编码(自动解析 express_name)、waybill_code=运单号、waybill_codes=运单号列表,并补齐 express_name/waybill_code/waybill_codes 响应字段与「没有需要更新的字段」错误项;confirm 的运单号校验字段由 express_code 纠正为 waybill_code,并如实描述响应 expressCode/expressCodes 的来源与历史遗留命名。", "methods": [ "storage.stockout.confirm", "storage.stockout.updateExpress" ], "notes": [ "代码依据:app/service/systemMethods/storage/stockout.js#updateExpress(L826 起,仅识别 express_code/waybill_code/waybill_codes,无 express_codes 分支)、#confirm(L577 校验 order.waybill_code)、app/model/order_stockout.js(express_codes 标注 @deprecated)", "背景:2026-08-07 首次上线时 express_code/express_codes 即运单号口径;随后迁移 20260807140000 引入 waybill_code/waybill_codes 并改义 express_code 为快递公司编码,但 methods/system.json 与 confirm 错误文案未同步,导致调用方按旧文档传 express_codes 时静默失败。", "对外契约影响:仅描述与错误文案纠偏,接口行为、参数名、HTTP 状态码均未变更;调用方需把运单号列表参数由 express_codes 改为 waybill_codes(confirm 前还需填 waybill_code)。", "文档版本 0.3.116 -> 0.3.117,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)", "后续代码侧待办(未在本次实施):updateExpress 增加 express_codes 兼容映射或对未识别参数报错、补 warehouse_id 归属校验;confirm 成功响应 expressCode/expressCodes 收敛为 waybill_code/waybill_codes。" ] }, { "version": "2026.09.13-pendingOrder-syncOrderIds-api-confirm-before-deduct", "date": "2026-09-13", "type": "updated", "summary": "order.pendingOrder.syncOrderIds 描述同步 API 渠道同步顺序变更(代码已先行落地):API 渠道订单改为逐单「先回传 deliveryorder.confirm、回调成功才扣减库存并置 sync_status='fin'」,回调失败/异常置 sync_status='error' + 待处理异常、不扣减库存、可重新派发;单订单失败统一「写入错误状态 + 标记待处理异常」。QM/MANUAL 口径不变。文档版本 0.3.115 → 0.3.116。", "methods": [ "order.pendingOrder.syncOrderIds" ], "notes": [ "代码依据:app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal → processApiOrderInternal(回调成功才 processLocalChannelOrderInternal 扣减并置 fin)、markApiSyncFailedInternal(error + markPendingException)", "params / response / errors 未变,仅 description 同步语义", "本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.12-storage-entry-cancel-entryOrderCode-doc", "date": "2026-09-12", "type": "updated", "module": "storage.entry", "summary": "storage.entry.cancel 文档小幅补充(对外契约不变):description 末尾注明另支持按 entryOrderCode(兼容别名 entry_order_code)按单号定位、供奇门/openapi 外部渠道复用;params 新增可选 entryOrderCode(内部复用口径,优先于 id/ids)。id/ids 入参、响应结构 { code, message, data } 与全部失败文案(入库单不存在或无权访问 / 入库单已作废 / 已完成入库单不允许作废 / 入库单已完成回传,不可取消 / 作废成功)逐一不变。", "methods": [ "storage.entry.cancel" ], "notes": [ "app/service/systems/storage/entry.js cancel:新增 data.entryOrderCode(或 data.entry_order_code)按单号定位(定位条件带 is_enabled/deleted_at/warehouse_id,有 storeId 时追加货主条件),优先于 id/ids;options 为外部渠道扩展(warehouseId/storeId/operatorLabel/skipExternalSync/idempotent/notFoundMessage),系统方法入口不传时行为与文案与历史版本完全一致", "奇门 order.cancel 与 openapi order.cancel 的 RK 组经此共用作废流程(skipExternalSync=true、idempotent=true、notFoundMessage=未找到对应的入库单)", "methods/system.json:storage.entry.cancel 的 description 末尾补一句按 entryOrderCode 定位说明,params 新增可选 entryOrderCode;id/ids、response、errors 文案未动", "文档版本 0.3.114 -> 0.3.115(docMeta.version),updatedAt 保持 2026-09-12", "本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.12-storage-stockout-cancel-shared-impl", "date": "2026-09-12", "type": "updated", "module": "storage.stockout", "summary": "storage.stockout.cancel 内部实现改为委托共享 app/service/systems/stockout_order.js#cancel(奇门 / openapi 同口径:单事务 + 行锁);对外契约完全不变(缺少出库单ID / 缺少仓库上下文 / 出库单不存在 / 出库单当前状态(xxx)不允许取消 / 成功返回取消成功 + data 含 id、stockout_order_code、order_status);由「先查单再开事务」改为「单事务 + 行锁」,并发取消/确认/转单更安全。", "methods": [ "storage.stockout.cancel" ], "notes": [ "app/service/systemMethods/storage/stockout.js cancel 改为薄适配层:校验 id(缺少出库单ID)与仓库上下文(缺少仓库上下文),委托 systems.stockoutOrder.cancel({ id }, { storeId: null, warehouseId, operatorLabel }),将共享层「未找到对应的出库单」映射为「出库单不存在」,成功映射为「取消成功」并透传 id / stockout_order_code / order_status", "app/service/systems/stockout_order.js cancel:定位优先 stockoutOrderCode 其次 id;单事务 + 行锁(防止并发取消/确认/转单),仅 CREATED/PENDING 可取消(canCancel),已 CANCELLED 幂等返回成功,COMPLETED/TRANSFERRED 返回「出库单当前状态(xxx)不允许取消」", "对外契约与实现变更前一致,调用方无需改动", "methods/system.json:storage.stockout.cancel 的 description 补充共享实现说明;errors 由单条 description 文本改为逐条 code/message(与仓库统一格式),文案不变;docMeta.version 0.3.113 -> 0.3.114,updatedAt 保持 2026-09-12", "本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.12-storage.inventory.listBySpaceId", "date": "2026-09-12", "type": "added", "summary": "新增 storage.inventory.listBySpaceId 接口:传入 space_id,先判断该库位是否为当前仓库的库位(不存在返回 404、存在但不属于当前仓库返回 400),是则返回该库位下有量库存(quantity > 0)的商品列表。列表按商品(stock_id)汇总为一条(汇总 quantity/locked_quantity/intercept_locked_quantity/available_quantity,含 batch_count 与最早/最晚入库时间);商品信息统一走 stock_warehouse 通用链路(getStockDetails)返回 stock_warehouse 通用属性。", "methods": [ "storage.inventory.listBySpaceId" ], "notes": [ "app/service/systemMethods/storage/inventory.js 新增 listBySpaceId 包装方法(透传 data.space_id,返回结构沿用 this.success('ok', result)),并加入 _noNeedRight/_noNeedLog/_noNeedAuth 豁免列表(与 listByStockId 一致)", "app/service/systems/storage/inventory.js 新增 getStorageListBySpaceId:校验 space_id 为正整数与当前仓库上下文(ctx.user.store_id);先查 wms_location_space(id + warehouse_id + deleted_at=null)判断库位归属,未命中再查全局记录以区分「库位不存在」(404)与「库位不属于当前仓库」(400)", "库存查询条件:wms_storage where warehouse_id + space_id + quantity > 0 + is_enabled=1 + delete_at=null,按 id 倒序取出库位明细行(仅取汇总所需列,不返回批次/效期明细)", "商品通用属性:收集明细行 stock_id 去重后调用 ctx.service.systems.stockWarehouse.getStockDetails(stockIds, { warehouseId })(带缓存通用链路),stock 对象即 stock_warehouse 通用属性(id/item_code/item_name/sku_property/quantity/locked_quantity/is_batch_mgmt/is_shelf_life_mgmt/is_images/need_recheck/store_id/packing_requirements/stock_unit/barcodes/image_url);该链路异常时降级为 stock=null 且不中断主流程", "app/service/systems/storage/inventory.js 新增 _aggregateStorageRowsByStock:按 stock_id 在内存汇总数量与批次数、取最早/最晚入库时间(app.formatDate 格式化),并平铺 space_code/space_name(custom_name 优先,否则 space_code)与 store_name(wms_store_warehouse.store_remask,按 warehouse_id + store_id 收敛,查询异常降级为 null)", "响应结构:data.space(id/warehouse_id/space_code/custom_name/space_status)+ data.list(按商品汇总行,无有量库存时为空数组)", "错误码:400「space_id 必填且必须为正整数」、400「无法获取当前仓库信息」、400「库位 {space_id} 不属于当前仓库」、404「库位不存在: space_id={space_id}」", "methods/system.json 新增 storage.inventory.listBySpaceId 条目(追加于 storage.inventory.listByStockId 之后;isNeedAuth=false、isNeedLogin=true、isNeedRight=false),version 0.3.112 -> 0.3.113,updatedAt 2026-09-12", "AI_METHOD_ROUTING.md 第 6 节按文件内维护说明刷新(node .\\script\\tmp-gen-service-method-inventory.cjs → node .\\script\\tmp-update-ai-method-routing.cjs):systemMethods/storage/inventory.js 14 -> 15、systems/storage/inventory.js 13 -> 15(新增 getStorageListBySpaceId、_aggregateStorageRowsByStock)", "验证:ESLint(npx eslint app/service/systems/storage/inventory.js app/service/systemMethods/storage/inventory.js)0 error;未执行任何部署/回退脚本,未改动数据库与 Redis 数据" ], "module": "storage.inventory" }, { "version": "2026.09.11-shops-edit-shop-name-doc-sync", "date": "2026-09-11", "type": "updated", "summary": "同步 shops.edit 文档:补入 shop_name 入参(修改店铺名称),修正「仅允许修改 platform_code 或 custom_name」的过时描述与错误文案。", "methods": [ "shops.edit" ], "notes": [ "实现依据:app/service/systemMethods/shops.js 的 edit 已透传 shop_name/shopName(与 custom_name/platform_code 同样兼容 camelCase),app/service/systems/shops.js 的 edit 已支持 updates.shop_name。", "字段语义区分:shop_name 为平台真实店铺名(shops.add 时写入 PENDING_* 占位名,授权回调后同步真实名称);custom_name 为自定义名称,仅作标签展示。", "校验行为:三者至少传一个,否则抛 400「仅允许修改 platform_code、custom_name 或 shop_name」;shop_name 走 normalizeText(required, maxLength=100),为空抛 400「shop_name 不能为空」、超长抛 400「shop_name 长度不能超过 100」。", "唯一性:改名与改平台合并后按「当前仓库 + next platform_code + next shop_name」调用 ensureShopNameUnique(排除自身,软删除店铺名以 DELETED_SHOP_NAME_PREFIX 前缀排除),冲突抛 409「同仓同平台下 shop_name 已存在」。", "文档更新:methods/system.json 的 shops.edit description 改为 platform_code/custom_name/shop_name 三选一,params 新增 shop_name(兼容 shopName),errors 补入 shop_name 相关 400 文案、id 与仓库校验 400、店铺不存在 404,并修正 400「仅允许修改 platform_code 或 custom_name」为「仅允许修改 platform_code、custom_name 或 shop_name」;version 0.3.111 -> 0.3.112,updatedAt 2026-09-11。", "仅文档同步,未修改任何业务代码;未执行部署/回退脚本,未改动生产数据。" ], "module": "shops" }, { "version": "2026.09.11-wave-batch-list-where-operator", "date": "2026-09-11", "type": "changed", "summary": "order.wave.batchList(波次管理列表)的 where 新增操作符传参支持:白名单字段统一支持裸值与 {operator,value,type} 标准结构(eq/ne/gt/lt/ge/le/in/notin/between/notbetween/like/contains/notlike/startswith/endswith/isnull/isnotnull,按字段分组限制),value 支持数组(like/contains 多值 OR、notlike 多值 AND、in/notin 要求非空数组、eq 传数组等价 in);未显式传 operator 时保持历史默认语义(wave_no/creator/logistics_name/item_part/item_snapshot_key/item_detail_machine 默认模糊,其余默认等值),裸数组按 in。新增 total_orders / processed_orders 两个数值字段,store_id 新增 ne/notin 排除语义。修复前端通用筛选器下发 {operator,value:[...]} 时 wave_id 等整数字段报「参数不合法」、wave_no 等文本字段被 String([...]) 拼成 'A,B' 导致恒空的问题。", "methods": [ "order.wave.batchList" ], "module": "order.wave", "notes": [ "app/service/systemMethods/order/wave.js:buildBatchListWhereClause 由「逐字段手写 if 取 .value」改为通用条件构建,新增 isEmptyBatchListWhereValue(空值跳过,isnull/isnotnull 例外)、resolveBatchListFieldCondition(区分标准结构与裸值,仅标准结构读取 operator,裸值回落字段默认操作符)、buildBatchListFieldConditionSql(操作符 → SQL 片段 + 命名占位符)、normalizeBatchListDistinguishExpressValue(布尔归一 0/1)、normalizeBatchListStoreIdCondition(货主条件归一 in/notin)。", "默认语义与历史完全对齐:wave_no/creator/logistics_name/item_part/item_snapshot_key/item_detail_machine 未传 operator 时 LIKE '%值%';wave_id/wave_type/wave_status/source/distinguish_express 默认等值;total_orders_min/max、processed_orders_min/max 默认 ge/le;裸数组按 in(此前会被 String(arr) 拼成 'A,B' 恒空)。", "新增数值字段 total_orders / processed_orders(默认 eq,支持 between 等数值操作符);原有 *_min/*_max 保留范围语义,也接受标准结构覆盖默认操作符(如 {operator:'between',value:[1,20]})。", "store_id:默认 eq/in(返回包含任一筛选货主订单的波次,含混合货主波次);新增 ne/notin 排除语义——外层 WHERE 追加 wb.wave_id NOT IN (SELECT DISTINCT od.wave_id FROM <订单分表> od WHERE od.wave_id IS NOT NULL AND od.store_id IN (:whereStoreIds)),子查询显式排除 NULL 波次号,避免 NOT IN 三值逻辑把整表过滤为空。", "分配/复核状态类(storage/express/print/review_assignment_status)仍只支持等值(内部按聚合统计判定):改为先解构 {operator,value} 再校验,显式传非 eq 操作符直接报错「仅支持: eq」,不再被 String({...}) 静默拼成非法枚举值。", "根因:batchList 走原生 SQL 拼条件(列表查询路线 B),只读 .value 不读 operator——整数字段 Number({operator,value}) → NaN → 抛「参数不合法」;文本字段 String([...]) → 'A,B' → LIKE '%A,B%' 恒空(无报错难以定位)。", "验证:run/check-wave-batch-where-operator.cjs(egg-mock 起真实 service,只读、不写库、不清理数据)33/33 通过——基线 274;wave_no eq/like/裸值/startswith/notlike/数组 contains/数组 eq;wave_id 裸值/in/裸数组/gt/between/notbetween;creator 裸值/eq/ne;wave_type in;source in;distinguish_express 裸 true/in;total_orders between、total_orders_min/max 历史回归;logistics_name isnotnull;storage_assignment_status {operator:eq} 与裸值结果一致;store_id 裸值/数组/notin(= baseline - positive)/不存在货主(notin 直通基线,验证 NULL 安全);5 个错误用例(不支持操作符、store_id 不支持操作符、分配状态仅 eq、where 禁止 warehouse_id、不支持的字段)。期望值均由本地开发库现算(含货主覆盖数),不依赖硬编码总量。", "methods/system.json:order.wave.batchList 方法描述与 where 参数说明同步操作符契约、字段分组允许集合、新增 total_orders/processed_orders 与 store_id ne/notin 语义;version 0.3.110 -> 0.3.111,updatedAt 2026-09-11。", "兼容性:未显式传 operator 的既有调用语义完全不变,包括 delivery_order.findAutoGroupingWaveId 传入的 wave_status/item_part_type/item_part/item_snapshot_key/distinguish_express/logistics_name 裸值,以及分页 page/pageSize 顶层写法。", "未执行任何部署/回退脚本,未改动生产数据;ESLint(npx eslint app/service/systemMethods/order/wave.js)0 error。" ] }, { "version": "2026.09.10-packing-where-waybill-wave-contains", "date": "2026-09-10", "type": "changed", "summary": "order.packing.list / order.packing.export 的 where.waybill_code 与 where.wave_no 新增 operator 支持:operator=contains(兼容 like)时按 LIKE '%值%' 模糊匹配;两字段 value 均支持字符串数组(多值取并集)。修复前端通用筛选器下发 {operator:'contains', value:[...]} 时因数组被整体字符串化(String(['A','B']) → 'A,B')导致恒返回空列表的问题。", "methods": [ "order.packing.list", "order.packing.export" ], "module": "order.packing", "notes": [ "app/service/systems/order_packing.js:_buildListWhere 的 waybill_code 分支改为逐单号展开条件——operator=contains/like 下发 { waybill_code: { [Op.like]: '%单号%' } }(escapeLikeWildcards 转义通配符);缺省/eq 保持原「完整单号等值 + 剥离 -1-1- 分段后缀主体等值 + 主体前缀 LIKE '主体-%'」三件套,仍不落入 %短串% 模糊分支。所有条件合并为一次 OrderExpress.findAll({ [Op.or]: ... }) 解析 order_id,无命中仍走 queryWhere.id = -1 强制空结果。", "app/service/systems/order_packing.js:wave_no 分支支持 operator——eq/in 精确(单值等值、多值 Op.in)、ne 不等、contains/like/缺省为模糊 LIKE '%值%'(缺省保持历史模糊语义),多值模糊通过 queryWhere[Op.and] 追加 { [Op.or]: [...] } 合并。", "list 与 export 复用同一 _buildListWhere,导出同步生效;未改任何 SQL 结构,仅条件组装方式变化。", "验证:run/check-packing-where-contains.cjs(egg-mock 启动真实 service,只读)10/10 通过——数组+contains 命中 2 条(原上报场景原为 0 条)、单值无 operator 回归 1 条、数组+eq 2 条、不存在单号+contains 0 条、空数组等同无筛选 13 条、wave_no contains 单值 3 条/数组 4 条、wave_no in 4 条、wave_no eq 精确不模糊 0 条。" ] }, { "version": "2026.09.10-report-filename-time-placeholder", "date": "2026-09-10", "type": "changed", "summary": "报表导出文件名模板新增占位符:{time}(生成时刻 HHmmss)、{datetime}(数据日期_生成时刻)、{timestamp}(生成时刻毫秒时间戳);{date} 语义保持不变(仍为数据日期 params.bizDate,缺省服务器当天)。用于同一天多次投递/手动导出同一报表时避免 COS 同名覆盖(同名文件被后一次写覆盖且 CDN 可能仍回源旧内容,表现为「下载到的还是旧版列」)。缺省文件名模板不变,存量定义不受影响(未改 file_name 者行为完全不变)。", "methods": [ "report.generate", "report.definition.save", "report.definition.list", "report.deliveryPlan.save" ], "module": "report", "notes": [ "app/service/systems/report.js:buildFilename(definition, bizDate, now) 新增第三参 now(生成时刻,缺省 new Date(),可注入供测试);替换顺序 {datetime} -> {date} -> {time} -> {timestamp};{date} 取值逻辑(params.bizDate || 服务器当天)与既有行为完全一致;缺省模板仍为 _.xlsx。", "根因与实测:2026-09-10 同一 (store 1000000, 定义 3, biz_date 2026-09-09) 在 19:40、19:58、20:07 三次投递使用同名 interceptOrder_2026-09-09.xlsx,COS 对象被覆盖且 CDN 仍回源旧版本,导致用户看到 10 列旧表(缺「仓库商品名称」)。定义改为 interceptOrder_{date}_{time} 后手动导出产出 interceptOrder_2026-09-09_201533.xlsx,文件 13 列(含仓库商品名称/平台交易单号/两列拦截时间)与定义勾选一致。", "app/model/report_definition.js 字段注释、app/service/systemMethods/report/definition.js JSDoc、methods/system.json(report.definition.save description 与 file_name 参数/响应/定义对象说明共 4 处)、docs/report-config-guide.md 第 1 节模型表与第 4 节文件名说明同步为四种占位符;docMeta.version 0.3.108 -> 0.3.109,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "测试:test/report_systems_engine.cjs 的 buildFilename 用例扩充({date}_{time}、{datetime}、{timestamp}、不同生成时刻文件名不同、未传 now 回落当前时刻、{date} 语义不变、缺省模板与自动补 .xlsx 保持);13 个 test/report_*.cjs 全部通过,ESLint 0 error。", "数据/配置变更(仅开发库,已披露):wms_report_definition id=3 的 file_name 由 interceptOrder_{date} 改为 interceptOrder_{date}_{time},使定义重新投递/手动导出时文件名唯一。", "兼容性:占位符为新增能力,未使用新占位符的既有定义(如 7日出入库数据 7daysStockFlow_{date})输出文件名与行为完全不变;未执行部署脚本,未改动生产数据。" ] }, { "version": "2026.09.10-intercept-order-source-order-codes", "date": "2026-09-10", "type": "added", "summary": "interceptOrder(库内确定拦截订单明细)报表新增导出列「平台交易单号」(字段 key source_order_codes,取配送表 wms_order_delivery_*.source_order_codes 原值,列位置紧跟「外部单号」)。注册字段数 48 -> 49(订单导出 item 模式去掉商品图片 46 列 + 附加 3 列:平台交易单号 + 通知拦截时间 + 库内确定拦截时间);接口入参/响应契约不变,stockFlow 与 order.export 均不受影响。", "methods": [ "report.definition.typeList", "report.generate", "report.definition.save" ], "module": "report", "notes": [ "app/service/systems/report/queries/interceptOrder.js:FIELDS 在 external_order_code(外部单号)之后插入 { key: 'source_order_codes', label: '平台交易单号', type: 'string' }。", "app/service/systems/report/queries/interceptOrder.js:enrichInterceptTimes 重命名为 enrichInterceptFields(已导出),回查 attributes 由 [id, intercept_time, dispath_time] 扩为 [id, source_order_codes, intercept_time, dispath_time],同一批查询同时回填平台交易单号(null/undefined 归一化为空字符串);仍按 500 订单分片、异常只 warn 不阻断报表。", "取数原因:明细行来自 orderExport.buildOrderExportPage(mode=item) → mapOrderExportRow(item),该映射不输出 source_order_codes,故由查询器回查补充。", "测试:test/report_intercept_order_fields.cjs 同步为 49 列断言(预期列序 = 订单导出 item 去掉商品图片,在 external_order_code 后插入平台交易单号、末尾 2 列拦截时间),并补充平台交易单号取值与回查 attributes 断言;test/report_systems_engine.cjs 注册字段数断言 48 -> 49;13 个 report_*.cjs + test/intercept_time_lifecycle.cjs 全部通过,ESLint 0 error。", "端到端:script/tmp-verify-intercept-order-dev.cjs D 段增加平台交易单号与配送表 source_order_codes 的逐单交叉核对(通过);同时修正该脚本 A 段旧断言(原先假设开发库昨日 0 行,现改为校验 meta.orderCount 与明细去重订单数一致)。", "生产/开发验证:投递计划 id=2(货主 1000000 → 仓 100000,时间点 19:40)于 2026-09-10 19:40:45 投递成功(wms_report_delivery_log id=16 status=delivered,文件 exports/report/3/store-1000000/20260910/interceptOrder_2026-09-09.xlsx),文件内容核对为 1 表头 + 4 行明细(对应补测的 3 单)。", "methods/system.json:report.definition.typeList description 与 fields 说明同步为 49 列(含平台交易单号);docMeta.version 0.3.107 -> 0.3.108,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "docs/report-config-guide.md 2.2 节:字段清单新增 source_order_codes 行(紧跟 external_order_code)、列数 48 -> 49、第 10 条口径改为「附加列(3 列)」并说明平台交易单号来源;AI_METHOD_ROUTING.md report 速查同步。", "注意:报表定义的 fields 需显式勾选 source_order_codes 才会出现在导出列中(已有定义不动则不输出该列);本次未修改任何已有 wms_report_definition 配置行,未执行部署脚本。" ] }, { "version": "2026.09.10-intercept-time-lifecycle", "date": "2026-09-10", "type": "changed", "summary": "拦截时间 intercept_time 口径调整(wms_order_delivery):统一为「最近一次发起拦截的通知时刻」——发起/通知拦截仅**首次写入**(重复发起不覆盖已有值),库内拦截确认(order.recheckOrder.confirmIntercept / order.recheckOrder.interceptScan / 定时自动确认)与退回入库(returned)**不再写该字段**,取消/解除拦截(order.pendingOrder.batchUnintercept)与订单克隆重置**置空 null**;「库内确定拦截时刻」改用配送表 dispath_time(订单迁移进配送表的时间)。同步调整 interceptOrder 报表两列:通知拦截时间 intercept_notice_time = 配送表 intercept_time(为空回落 ORDER_INTERCEPT_REQUEST 操作日志最早一条),库内确定拦截时间 intercept_confirm_time = 配送表 dispath_time(原 key intercept_time 更名;该报表类型尚未落库定义行,无兼容问题)。", "methods": [ "order.pendingOrder.batchIntercept", "order.pendingOrder.batchUnintercept", "order.pendingOrder.cloneOrder", "order.recheckOrder.confirmIntercept", "order.recheckOrder.interceptScan", "report.definition.typeList", "report.generate" ], "module": "order", "notes": [ "app/lib/intercept_time.js(新增):拦截时间字段口径工具(纯函数):isEmptyInterceptTime、buildNoticeTimePatch(currentValue, now)(空值才写入,已有值返回空对象=不覆盖)、pickNoticeTimeOrderIds(rows)(批量场景筛出尚未写入通知时刻的订单ID,去重保序);文件头注释固化生命周期口径(首次写入/不覆盖/取消置空/库内确定时刻改用 dispath_time)。", "发起/通知拦截(首次写入,不覆盖):app/service/qimenMethods/order.js(intercepting/requested 两处 existingOrder.update 改为 ...buildNoticeTimePatch(existingOrder.intercept_time, noticeNow))、app/service/openapiMethods/order.js(intercepting)、app/service/inbox/functions.js(两处波次感知拦截:订单查询 attributes 增补 intercept_time,主更新只写 intercept_status,随后仅对 pickNoticeTimeOrderIds 命中的订单补写 intercept_time)、app/service/systemMethods/order/pendingOrder.js(取消订单转拦截的 syncedOrders 批量更新、batchIntercept 分批更新:同样先取空值订单子集再补写)。", "库内拦截确认不再覆盖:app/service/systems/intercept_auto_confirm.js(confirmInterceptForOrderIds 的 updateValues 移除 intercept_time)、app/service/systemMethods/order/recheckOrder.js(interceptScan 的 orderModel.update 移除 intercept_time)。app/service/systems/return_received.js(退回入库 updateFields 移除 intercept_time)。", "取消/清空:app/service/systemMethods/order/pendingOrder.js batchUnintercept 保持 intercept_time=null(解除拦截置空);cloneOrder 的 RESET_FIELDS 新增 intercept_time=null(避免克隆重置新单继承原单发起拦截时刻)。", "interceptOrder 报表(app/service/systems/report/queries/interceptOrder.js):enrichInterceptTimes 改为 attributes=[id, intercept_time, dispath_time];intercept_notice_time ← intercept_time(为空时才回落 wms_operation_log 的 ORDER_INTERCEPT_REQUEST 最早记录,同仓隔离 business_type/business_id/warehouse_id 三重过滤,主取有值时不查日志);intercept_confirm_time ← dispath_time;meta 计数更名 confirmTimeFilledCount(原 interceptTimeFilledCount)。", "测试:新增 test/intercept_time_lifecycle.cjs(纯函数 3 例 + 写入点静态守卫 4 例:确认链路不得同写 intercepted_at_warehouse 与 intercept_time、发起链路使用首次写入工具、取消与克隆重置置空、退回入库不覆盖);test/report_intercept_order_fields.cjs 同步更新(末 2 列 key、dispath_time 作为库内确定拦截时间、日志兜底用例、缺失/模型不可用降级),共 18 例;test/report_*.cjs 13 个文件 + 新测试全部通过;ESLint 0 error。", "端到端校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs D 段改为对开发库真实订单交叉核对「通知拦截时间=intercept_time(空时回落日志)」与「库内确定拦截时间=dispath_time」,与直连 SQL 一致。", "兼容性与风险:intercept_time 在本次上线前的历史数据可能仍是确认时刻(旧逻辑覆盖所致),这部分历史行的「通知拦截时间」不可靠;报表按「昨日」取数,上线次日起数据即为新口径。自动确认定时任务仍以 intercept_time 作为「发起后超时」判定依据,语义反而更准确(未被确认覆盖)。", "methods/system.json:order.pendingOrder.batchIntercept(首次写入不覆盖 + 取消清空说明)、order.pendingOrder.batchUnintercept(解除拦截清空 intercept_time)、order.recheckOrder.confirmIntercept 与 order.recheckOrder.interceptScan(确认不写 intercept_time、库内确定时刻以 dispath_time 为准)description 同步;report.definition.typeList 字段清单描述 key 更新为 intercept_confirm_time;docMeta.version 0.3.106 -> 0.3.107,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "docs/report-config-guide.md 2.2 节第 10 条与字段清单、AI_METHOD_ROUTING.md report 速查(新增拦截时间口径变更条目)同步;本次未执行任何数据库/Redis 写操作,未运行部署脚本。" ] }, { "version": "2026.09.10-intercept-order-time-columns", "date": "2026-09-10", "type": "added", "summary": "interceptOrder(库内确定拦截订单明细)报表新增导出列「通知拦截时间」与「库内确定拦截时间」:intercept_time(库内确定拦截时间)= 配送表 intercept_time(确认拦截时写入);intercept_notice_time(通知拦截时间)= wms_operation_log 中 operation_code='ORDER_INTERCEPT_REQUEST' 的最早记录时间(发起/通知拦截时刻,因为 intercept_time 在确认时会被覆盖,只能从操作日志反查,按订单ID+仓库ID同仓隔离;日志缺失时该列留空)。两列均格式化为 YYYY-MM-DD HH:mm:ss,列排在字段清单末尾,注册字段数 46 -> 48;接口入参/响应契约与 stockFlow 均不受影响。", "methods": [ "report.definition.typeList", "report.generate", "report.definition.save" ], "module": "report", "notes": [ "app/service/systems/report/queries/interceptOrder.js:FIELDS 末尾新增 intercept_notice_time(label 通知拦截时间)、intercept_time(label 库内确定拦截时间),type 均为 string(渲染层原样输出保留与订单导出 item 模式一致的零转换口径);列顺序 = 订单导出 item 模式 47 列去掉商品图片(46)+ 末 2 列拦截时间,共 48 列。", "app/service/systems/report/queries/interceptOrder.js:新增 enrichInterceptTimes(已导出供单测/脚本复核)——按订单ID分片(ENRICH_CHUNK_SIZE=500)回查:1)配送表模型 findAll(attributes: id/intercept_time) 取库内确定拦截时间;2)OperationLog.findAll(attributes: business_id + MIN(created_at) 别名 notice_time,group by business_id)取通知拦截时间,where 限定 business_type='order' + operation_code='ORDER_INTERCEPT_REQUEST' + warehouse_id=当前仓库 + business_id IN(订单ID字符串化)。两列分别格式化为 YYYY-MM-DD HH:mm:ss(空值/无效值空字符串,与订单导出 formatDateSafe 口径一致);任一回查异常只 warn 并留空,不影响报表主流程;OperationLog 模型缺失时跳过日志查询。", "同仓隔离:订单 ID 按仓库发号(wms_order_id_location_{wh}),日志查询必须带 warehouse_id,禁止仅凭订单ID跨仓串读(与 order_express 同仓隔离修复同口径)。", "app/service/systems/report/queries/interceptOrder.js:查询器返回 meta 新增 noticeTimeFilledCount / interceptTimeFilledCount(两列有值行数),便于核对日志覆盖率;rows 为同一行对象的拦截时间列赋值(同一订单的多条商品明细行同值)。", "测试:test/report_intercept_order_fields.cjs 新增 2 例(拦截时间两列取值/查询条件/分组断言;空值与 OperationLog 模型不可用降级),并同步列数断言 46 -> 48(前 46 列仍与订单导出 item 模式逐列对齐,末 2 列固定为拦截时间);test/report_systems_engine.cjs 注册表字段数断言同步为 48。test/report_*.cjs 13 个文件全部通过。", "真实数据校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs 新增 D 段——以 egg 真实上下文调用 enrichInterceptTimes 对开发库 5 个库内确定拦截订单富化,并与直连 SQL(配送表 intercept_time、wms_operation_log 的 MIN(created_at))逐单交叉核对一致(开发库这 5 单均无 ORDER_INTERCEPT_REQUEST 日志,故通知拦截时间为空,符合预期);渲染表头列数校验同步为 48 且末两列表头为拦截时间列。", "methods/system.json:report.definition.typeList 的 description 与 fields 说明同步为 48 列(前 46 列对齐订单导出 item 模式去掉商品图片,末 2 列为拦截时间);docMeta.version 0.3.105 -> 0.3.106,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "docs/report-config-guide.md 2.2 节:字段清单补 2 行拦截时间列、新增第 10 条口径(两列来源/同仓隔离/空值语义/meta 计数),注册类型表与「与订单导出 item 模式差异」说明同步更新;AI_METHOD_ROUTING.md report 速查同步(48 列 + 两个时间列来源)。", "兼容性:仅为报表列扩展(新报表类型尚未在 wms_report_definition 落库定义行,无存量定义受影响);stockFlow 与 order.export 列口径、report.generate / report.deliveryPlan 链路均未改动。" ] }, { "version": "2026.09.10-report-intercept-order-type", "date": "2026-09-10", "type": "added", "summary": "通用报表新增注册类型 interceptOrder(库内确定拦截订单明细):以配送表 dispath_time(订单迁移进配送表的时间)为时间基准,统计昨日(自然日 [昨日 00:00:00, 今日 00:00:00) 本地时区半开区间)库内确定拦截订单(intercept_status=intercepted_at_warehouse),**统计日不得晚于昨天**(params.bizDate 传今天/未来一律回落昨日,今天发出去的报表不含今天数据;比昨天更早的显式日期仍被尊重以支持补数),按商品明细展开(一个商品一行),列与订单导出含明细模式(order.export export_mode=item)完全对齐、仅去掉「商品图片」列(共 46 列)。报表定义 type 填 interceptOrder 即可使用,report.generate / report.deliveryPlan / wms_report_definition 结构均无需变更。", "methods": [ "report.definition.typeList", "report.generate", "report.definition.save" ], "module": "report", "notes": [ "app/service/systems/report/queries/interceptOrder.js(新增):查询器签名与 stockFlow 一致 async ({ctx, storeId, warehouseId, params}) => ({windows: [], rows, meta})。数据源为配送表 wms_order_delivery_{warehouseId}_dispatch(经 orderExport.getOrderModelByTableType('dispatch', warehouseId) 取模型),过滤 intercept_status='intercepted_at_warehouse' 且 dispath_time ∈ [统计日 00:00:00, 次日 00:00:00);warehouseId 必填(<=0 抛「interceptOrder 查询器缺少仓库维度 warehouseId」),storeId>0 时追加 store_id 过滤(货主维度报表/投递),否则仓库维度全量。", "明细口径复用订单导出链路:按单页 1000 单分页循环(不足一页终止)调用 orderExport.buildOrderExportPage({ mode: 'item' }),即复用 mapOrderExportRow(item) 的状态中文翻译、货主备注、仓库商品名/条码回落、运单汇总、包材、收件人脱敏等取值,逐格与订单导出 item 模式一致;行再经 pickReportRow 按注册字段裁剪(丢弃 item_image 等多余键,缺失值回落空字符串)。", "统计日解析 resolveBizDayWindow:params.bizDate(兼容 biz_date)为真实存在的 YYYY-MM-DD 时按该自然日整天统计,缺省/非法一律回落昨日自然日;区间左闭右开,用 new Date(y, m, d) 构造规避夏令时步进偏差。Sequelize 未配置 timezone(默认 UTC)+ MySQL 时区 UTC,dispath_time 写入(orderDeliveryMigration.buildDispatchRow 写 new Date())与本查询的时间过滤经同一序列化路径,口径自洽。", "字段清单 FIELDS 共 46 列,与 order.export 的 ORDER_EXPORT_ITEM_COLUMNS(47 列)逐列对齐并去掉「商品图片」列,key/label/顺序一致;type 统一为 string(渲染层 renderCell 原样输出,不做 zeroToDash/yesNo 转换,且不声明 asText),以保证单元格取值与订单导出一致;无 array 展开列,windows 恒为空数组、单行表头、无表头合并。", "app/service/systems/report/queries/index.js:QUERIES 注册 interceptOrder,DESCRIPTIONS 新增条目(title「库内确定拦截订单明细」、window {dayCount: 1, cutoverHour: 0}),report.definition.typeList 自动带出 46 列字段元数据供报表定义勾选。", "行数保护与元信息:明细行数达 MAX_EXPORT_ROWS=200000 时截断并打 warn(meta.truncated=true);meta 返回 bizDate/startTime/endTime/warehouseId/storeId/interceptStatus/timeField/orderCount/rowCount/truncated 供复核。", "波次序号(wave_index)沿用订单导出同款 attachOrderWaveIndex(仓库ID取 ctx.user.store_id),定时投递(无 ctx.user)场景该列降级为 0,仓库主体手工导出为真实序号(与 order.export 行为一致)。", "统计日硬约束(同日补充):resolveBizDayWindow 解析出统计日后统一校验 baseDate >= 今日 00:00:00 时回落昨日——params.bizDate 传今天/未来(含手工导出误传当天)时查询区间仍为 [昨日 00:00:00, 今日 00:00:00),保证「今天发出去不含今天」;比昨天更早的显式日期仍被尊重(补数场景)。测试:test/report_intercept_order_fields.cjs 新增「硬约束:统计日不得晚于昨天」与「params.bizDate 传今天:查询区间仍为昨日」两例(共 16 例)。", "测试:新增 test/report_intercept_order_fields.cjs(14 例:字段与订单导出 item 逐列对齐、pickReportRow 裁剪、统计日区间解析、查询器 mock 链路含分页/where/meta/storeId 过滤与错误分支);同步修正 test/report_systems_engine.cjs 与 test/report_stockflow_fields.cjs 中「注册表仅 1 种类型」的旧断言(改为按 key 定位并断言注册顺序 stockFlow → interceptOrder)。test/report_*.cjs 共 13 个文件全部通过。", "端到端校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs 以 egg 真实上下文在开发库跑通查询器(meta 正确、开发库历史拦截单 dispath_time 为 NULL 故昨日命中 0 行)、真实拦截订单 5 单 → 9 条商品明细行的取值映射,以及 renderSheetByType 渲染(表头 46 列、单行表头、无合并、无 textColumns)。", "methods/system.json:report.generate description 类型举例补 interceptOrder;params.bizDate 说明补充「同时是 interceptOrder 的统计日覆盖(缺省昨日自然日)」;params.dayCount/params.cutoverHour 标注仅 stockFlow 生效;report.definition.typeList 的 description、response.list、window.dayCount、window.cutoverHour、fields 说明同步为两种类型口径;docMeta.version 0.3.104 -> 0.3.105,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "docs/report-config-guide.md:新增注册类型行、46 列字段清单与 interceptOrder 口径章节;wms_report_definition 定义行由业务侧在后台配置(本次未插入定义行、未执行任何数据库写操作)。", "未修改任何既有接口入参/响应契约:新增类型为注册表扩展,stockFlow 行为不变,report.generate / report.deliveryPlan / report.exportTaskProgress 链路无需改动。", "README.md / AI_TOOLBOX.md 无需同步:检索确认无注册类型清单描述;AI_METHOD_ROUTING.md 第 6 节为函数清单,本次未新增/删除既有函数名(interceptOrder 为查询器注册 key),如需刷新可另行执行扫描脚本" ] }, { "version": "2026.09.10-cross-warehouse-order-express-warehouse-isolation", "date": "2026-09-10", "type": "fixed", "summary": "跨仓运单号串读缺陷修复文档同步:修复前所有按订单 ID 读取 wms_order_express 的查询缺少 warehouse_id 强制校验,存在跨仓串读运单号风险;修复后所有读取链路均强制校验订单所属仓库(查询条件同时限定订单ID与仓库ID),仓库归属无法确定时跳过读取或拒绝读取。order.detail 及各订单列表接口 description 补充「运单号按订单所属仓库隔离读取」说明,接口入参/出参契约不变。", "methods": [ "order.detail", "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.pendingOrder.detail", "order.pendingOrder.reverseReviewOrder", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list", "order.wave.waveStrategyFallbackOrderList", "order.recheckOrder.recheckOrderList", "order.recheckOrder.queryRecheckOrderSingleList" ], "module": "order", "notes": [ "app/service/systemMethods/order/base.js:getOrderExpressesByOrderId 强制同仓校验(仓库ID优先取订单行 order.warehouse_id,缺省回退当前上下文仓库,均缺失返回空数组);attachOrderExpressNumbers 批量回填改为按「订单ID+仓库ID」逐仓分组查询(行内 warehouse_id 优先,缺省回退上下文仓库,无法确定仓库归属的订单不参与运单查询)", "app/service/systemMethods/order/recheckOrder.js:confirmRecheck 调用 getOrderExpressesByOrderId 传入订单行;queryRecheckOrderSingleList 运单号关键词 EXISTS 搜索与 waybill_code 子查询均追加 oe.warehouse_id = o.warehouse_id 同仓条件", "app/service/systemMethods/order/pendingOrder.js:detail 传订单行给 getOrderExpressesByOrderId;assertOrdersWithoutWaybill 增加 warehouseId 入参强制同仓校验(reverseReviewOrder 反审前运单校验传入当前仓库ID,缺少仓库上下文时跳过校验读取,按无可读记录处理)", "app/service/systems/order_express.js:findValidOrderExpressRows 仓库ID缺失直接抛 400「缺少仓库上下文,禁止读取订单运单记录」;checkExpress 存在性校验、updateWeighingWeight、updateWeighingWeightByWaybill、按订单ID批量查询等读取链路全部追加 warehouse_id 条件", "app/service/systems/storage/report.js:loadReportReferenceMaps 运单查询强制 AND warehouse_id(仓库模式用当前仓库ID;货主模式按订单所属仓库 Map 分组查询);库存流水明细 SELECT 增加 t.warehouse_id 并构建订单ID→仓库ID映射传入", "app/service/systems/order_async.js:buildOrderWaybillCodeMapInternal 增加 warehouseId 入参并强制同仓校验(缺失返回空映射),syncManualOrders/syncStockoutOrders/syncQmOrders 三处调用均传入仓库ID", "app/service/systems/waybill.js:主单号 SELF JOIN 查询追加 warehouse_id 条件;app/service/systems/workbench.js:打包列表运单查询追加 warehouse_id 条件", "app/service/systems/express.js:运单状态 success 行查询追加 warehouse_id(取 options.warehouse_id 或当前仓库上下文);app/service/systems/express_platform.js:polyapi 已分配运单查询强制同仓校验,仓库ID缺失时不查询", "app/service/qimenMethods/order.js:getInterceptExpressInfo 增加 warehouseId 入参强制同仓校验(缺失返回空数组),sendCancelInterceptNotice 与取消拦截链路均传入 info.warehouseId;app/service/inbox/functions.js:已分配快递单号查询追加 warehouse_id;app/lib/intercept_guard.js:拦截守卫称重查询追加 warehouse_id", "methods/system.json:order.detail、order.pendingOrder.detail 与各订单列表接口(order.list、order.reviewOrder.list、order.pendingOrder.list、order.outboundOrder.list、order.expectionOrder.list、order.entrustOrder.list、order.deliveryOrder.list、order.deliveryExpectionOrder.list、order.archiveOrder.list、order.wave.waveStrategyFallbackOrderList、order.recheckOrder.recheckOrderList、order.recheckOrder.queryRecheckOrderSingleList)description 补充运单号按订单所属仓库隔离读取说明;params/response/errors/headers 契约均未变化;docMeta.version 0.3.103 -> 0.3.104,updatedAt 2026-09-08 -> 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位", "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 无需同步:检索确认无 wms_order_express 读取口径描述;AI_METHOD_ROUTING.md 第 6 节为函数清单,本次未新增/删除函数名(仅实现与签名参数变化),无需刷新", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-front-config-cert-pem-echo", "date": "2026-09-08", "type": "changed", "summary": "setting.warehouse.getFrontConfig 响应改为回显证书/私钥原文(cert_path/key_path 替换为 cert_pem/key_pem):cert_pem 读 cert_pem 列、key_pem 读 cert_key 列,未配置均为空字符串,响应仍 15 字段;saveFrontCert/saveFrontConfig 复用 buildFrontConfigOutput,响应口径同步返回 cert_pem/key_pem 原文;仅登录后的仓库主体(settings 页)接口回显,公共无鉴权接口 frontConfig.getByDomain 不受影响仍 6 字段白名单(domain/title/logo_url/login_bg_url/favicon_url/theme),严禁暴露证书内容。", "methods": [ "setting.warehouse.getFrontConfig", "setting.warehouse.saveFrontConfig", "setting.warehouse.saveFrontCert" ], "module": "setting.warehouse", "notes": [ "app/service/systems/setting/warehouse.js:buildFrontConfigOutput 输出字段 cert_path→cert_pem(证书 PEM 原文,读 cert_pem 列)、key_path→key_pem(私钥 PEM 原文,读 cert_key 列),未配置均为空字符串;响应仍 15 字段(warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at);方法注释明确私钥原文回显仅限仓库主体登录后的 settings 页(getFrontConfig/saveFrontConfig/saveFrontCert 三个需登录接口复用本输出),公共无鉴权接口走 buildFrontConfigPublicOutput 白名单、不经过本方法", "app/service/systems/setting/warehouse.js:getFrontConfig 响应含证书原文(cert_pem)与私钥原文(key_pem)供仓库主体 settings 页回显;buildFrontConfigPublicOutput/getFrontConfigByDomain 不变(仍仅 FRONT_CONFIG_PUBLIC_FIELDS 6 字段,严禁输出 cert_pem/cert_key 证书与私钥内容及 cert_path/key_path/sync_status 等内部字段)", "app/service/systems/setting/warehouse.js:saveFrontConfig(约 L1260)与 saveFrontCert(约 L1380)响应均复用 buildFrontConfigOutput,响应口径与 getFrontConfig 一致返回 cert_pem/key_pem 原文;saveFrontCert 保存时证书/私钥 PEM 直接写 cert_pem/cert_key 列、cert_path/key_path 置空待定时任务回填真实路径的行为不变", "methods/system.json:setting.warehouse.getFrontConfig/saveFrontConfig/saveFrontCert 三个条目 response 中 cert_path/key_path 字段替换为 cert_pem/key_pem(原文回显语义、未配置为空字符串、注明仅登录仓库主体 settings 页回显的安全口径);getFrontConfig description 补充证书/私钥原文回显与公共接口 6 字段白名单口径;saveFrontCert description 由「响应 15 字段不含证书/私钥内容」修正为「响应 15 字段含 cert_pem/key_pem 原文回显」并同步「内容供定时任务读取、禁止写入日志」口径;saveFrontCert response updated_at 字段描述移除「响应不含 cert_pem/cert_key 证书与私钥内容」旧口径;getFrontConfig response cert_expire_at 描述删除已废弃的「纯路径模式」口径;frontConfig.getByDomain 条目未改动(仍 6 字段白名单、isNeedLogin=false、isNeedAuth=false);docMeta.version 0.3.102 -> 0.3.103,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "README.md / AI_TOOLBOX.md 无需同步:检索确认无 cert_path/key_path/getFrontConfig/saveFrontCert 字段描述引用;AI_METHOD_ROUTING.md 第 6 节仅方法名清单(getFrontConfig/saveFrontConfig/saveFrontCert 方法名未变、buildFrontConfigOutput 函数名未变)无需同步", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-wave-strategy-group-buy-cross-pool-merge", "date": "2026-09-08", "type": "changed", "summary": "小团购 PDA 抓取跨池同结构合并文档同步(修复「1 单 1 波次」问题):order.wave.waveStrategyFetchPda 抓取主流程新增小团购跨池同结构合并工序(mergeWaveStrategyFirstPoolSameStructureOrders),自动分流执行结果 result 新增 merged_order_count 字段(合并进候选的跨池订单数量,无合并时为 0);触发条件为小团购 pickMode=1 + 第一池非空 + max_same_structure 为正整数且≠999,max_same_structure 为 null/999 的策略、大团购 pickMode=5 与后台抓取入口行为不变。", "methods": [ "order.wave.waveStrategyFetchPda" ], "module": "order.wave", "notes": [ "app/service/systemMethods/order/wave.js:新增私有方法 mergeWaveStrategyFirstPoolSameStructureOrders(约 L11339~L11495):按第一池候选分组出现过的 structure_key(require_same_express=1 时为「结构+快递」组合,快递口径复用候选 SQL expressExpr 的 COALESCE 优先级 sys_logistics_code > logistics_code > logistics_name)查询同结构全池过筛订单(wave_id=0、step!=0、post_status/storage_status=fin、print_status!=fin、status!=cancel、outbound_status!=padding、intercept_status=none、lock_status=none,不限策略匹配、不含池边界 create_at 条件),将两池同结构订单全部并入候选(按 id 去重)后复用既有分组建波流程;任一门控不满足返回 null 跳过合并", "app/service/systemMethods/order/wave.js:autoPopulateWaveStrategyFetchSelections 团购分支(strategy_type=2 且 pickMode=1)接入合并:仅 pickMode=1 且 candidate_pool_stage='first' 且 max_same_structure 为正整数且≠999 时执行合并,merged_order_count = 合并后候选数 - 原候选数;max_same_structure 为 null/999、pickMode=5(大团购)、第一池为空、全池查询无新增订单时 merged_order_count=0 维持现状;后台抓取入口(executeWaveStrategyDirectFetch / waveStrategyFetchAdmin)不经过本方法不受影响", "背景:订单池按今日前/今日分割 + min_same_structure 全池计数口径导致某结构第一池仅剩 1 条时仍通过门槛单独成波(生产订单 11103 案例「1 单 1 波次」)", "methods/system.json:order.wave.waveStrategyFetchPda 条目 response 数组末尾新增 merged_order_count 字段说明(合并进候选的跨池订单数量、无合并为 0、不含在原 candidate_count 内、合并后候选总量 = candidate_count + merged_order_count);description 补充小团购跨池同结构合并规则(触发条件与跳过条件);params/headers 不变;errors 条目键名由 description 规范化为 message(文案不变,满足更新脚本 schema,与 order.wave.waveStrategyList 等先例一致);docMeta.version 0.3.101 -> 0.3.102,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "兼容性:merged_order_count 为自动分流执行结果 result 新增可选字段,向后兼容;pickMode=5(大团购)、max_same_structure 为 null/999 的策略、后台抓取入口与第一池为空的场景行为与改动前一致,无接口破坏性变更", "回归验证:test/wave_first_pool_merge_regression_20260908.cjs 覆盖门控(pickMode/池阶段/max_same_structure)、快递组合口径、合并去重、merged_order_count 计数与建波结果(wms-test-agent 回归通过)", "README.md / AI_TOOLBOX.md 无需同步:检索确认无 waveStrategyFetchPda 抓取数量口径描述;AI_METHOD_ROUTING.md 第 6 节为自动扫描函数清单,如需刷新可另行执行扫描脚本", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-wave-strategy-list-info-order-count", "date": "2026-09-08", "type": "changed", "summary": "order.wave.waveStrategyList 成功响应新增 info 子对象(info.order_count):返回当前查询条件下(当前仓库 + strategy_type 过滤)全部波次策略命中的订单总数,按订单去重、不受分页影响,统计失败时安全降级为 0;错误/失败路径响应结构不变,成功路径 info 恒存在。", "methods": [ "order.wave.waveStrategyList" ], "module": "order.wave", "notes": [ "app/service/systemMethods/order/wave.js:waveStrategyList 成功响应新增 info 对象;当 total>0(当前仓库存在波次策略)时调用 getWaveStrategyMatchedOrderCountTotal(contextWarehouseId,{strategyType}) 统计全部命中订单去重总数,异常时捕获并记录 warn 日志(含 warehouse_id/strategy_type/error)后降级为 0,不影响列表主流程", "app/service/systemMethods/order/wave.js:新增 getWaveStrategyMatchedOrderCountTotal(warehouseId,{strategyType}):基于 wms_order_wave_strategy_match 关联订单表与 wms_wave_strategy,require_same_express=1(结构+快递分组)与 =0(仅结构分组)两类候选口径 UNION ALL 后 COUNT(DISTINCT order_id);strategy_type 非法或未传时为 null(不过滤);仅统计未入波次且满足同结构 min/max 上下限的候选订单", "methods/system.json:order.wave 分组 order.wave.waveStrategyList 条目 response 数组末尾新增 info 子对象及 order_count 字段说明(全部命中订单去重总数、不受分页影响、异常降级为 0),params/headers/description 保持原样;errors 条目键名由 description 规范化为 message(文案不变,满足更新脚本 schema,与 order.manualOutboundOrder 等先例一致);docMeta.version 0.3.100 -> 0.3.101,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "README.md / AI_TOOLBOX.md 无需同步:检索确认无 waveStrategyList 响应结构描述;AI_METHOD_ROUTING.md 第 6 节为自动扫描函数清单(本次新增 getWaveStrategyMatchedOrderCountTotal 已纳入代码),如需刷新清单可另行执行扫描脚本", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-front-cert-inline-content-save", "date": "2026-09-08", "type": "changed", "summary": "setting.warehouse.saveFrontCert 证书上传接口改版文档同步:入参 cert_pem/key_pem 重命名为 pem/key(必填,超长文案「pem|key 内容长度不能超过 65536 字符」);证书/私钥 PEM 内容直接写入 cert_pem/cert_key 列入库、保存时不再写暂存文件,cert_path/key_path 保存置空、等待未来定时任务部署后回填真实路径;cert_expire_at 仍由证书 validTo 权威写入,同步状态机重置(sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at)与新旧 domain 公共拉取缓存清理保持不变;删除「证书暂存目录未配置/证书文件写入失败」500 错误分支;响应 15 字段不含证书内容(cert_pem/cert_key 仅定时任务读取)。", "methods": [ "setting.warehouse.saveFrontCert" ], "module": "setting.warehouse", "notes": [ "app/service/systems/setting/warehouse.js:saveFrontCert 入参改为 domain/pem/key(domain 经 normalizeFrontConfigText(data.domain,'domain',100) 校验非空 400「domain 不能为空」与超长 400「domain 长度不能超过 100 字符」;pem/key 经 normalizeFrontConfigPem 校验非空 400「pem 不能为空」「key 不能为空」、超长 400「pem|key 内容长度不能超过 65536 字符」);移除 writeFrontConfigCertFiles 落盘链路,证书内容直接入库 patch.cert_pem=certPem/cert_key=keyPem,patch.cert_path=null/key_path=null(等待未来定时任务从库内读取内容写 nginx 证书目录后回填真实路径);校验链 parseFrontConfigCertPem → assertFrontConfigCertValid → validateFrontConfigKeyPem → collectFrontConfigCertNames/frontConfigCertCoversDomain → assertFrontConfigDomainUnique 不变,任一失败统一「证书不合法」400;cert_expire_at=new Date(cert.validTo) 权威写入不变;sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at 与新旧 domain front:config:domain:{*} 缓存清理逻辑不变;响应 buildFrontConfigOutput 15 字段不含 cert_pem/cert_key(内容仅定时任务读取)", "app/service/systemMethods/setting/warehouse.js:saveFrontCert 薄出口透传改为 domain/pem/key,_noNeedRight/_noNeedAuth 不变;错误 code 透传不变", "app/model/warehouse_front_config.js:cert_pem/cert_key TEXT 列承接证书内容(comment 注明仅定时任务读取、禁止写入日志/接口响应),cert_path/key_path 保存置空由未来定时任务回填;模型结构无变更", "config/config.default.js:frontConfig.certStagingDir 保留(注释已更新为「保存接口不再写暂存文件、证书内容直接入库,目录供未来定时任务部署使用」),无配置键变化", "methods/system.json:setting.warehouse.saveFrontCert 条目 params cert_pem→pem、key_pem→key(文案同步「pem/key 不能为空」与「pem|key 内容长度不能超过 65536 字符」);description 改为内容直接入库、cert_path/key_path 置空待定时任务回填、响应不含证书内容;errors 删除 500「证书暂存目录未配置(frontConfig.certStagingDir)或证书文件写入失败」分支,其余 400/403/409/500 文案按代码核实保留;response 15 字段结构不变;docMeta.version 0.3.99 -> 0.3.100,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "AI_METHOD_ROUTING.md:第 6 节自动扫描清单定向修正 systems/setting/warehouse.js 31→30(writeFrontConfigCertFiles 已从代码移除);systemMethods/setting/warehouse.js 6 个方法名不变,其余条目未动", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-front-cert-config-split", "date": "2026-09-08", "type": "changed", "summary": "前端独立部署「证书上传」与「配置保存」拆分文档同步:新增 setting.warehouse.saveFrontCert 接口文档(证书上传:domain+cert_pem/key_pem 成对必填,校验链任一失败统一返回「证书不合法」400,通过后自动权威写入 cert_expire_at、证书内容落盘只存路径、清新旧 domain 公共拉取缓存);saveFrontConfig 入参瘦身为仅品牌字段 title/logo_url/favicon_url/login_bg_url/theme(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at 不再受理,前端传值被方法层白名单静默忽略,domain 变更必须走 saveFrontCert)。", "methods": [ "setting.warehouse.saveFrontCert", "setting.warehouse.saveFrontConfig" ], "module": "setting.warehouse", "notes": [ "app/service/systemMethods/setting/warehouse.js:新增 saveFrontCert 薄出口(透传 domain/cert_pem/key_pem,错误 code 透传);_noNeedRight/_noNeedAuth 增加 saveFrontCert(需登录、免权限、免鉴权,权限靠业务层 isWarehouse 判定);saveFrontConfig 方法层白名单收敛为 title/logo_url/favicon_url/login_bg_url/theme(domain/cert_path/key_path/cert_pem/key_pem/cert_expire_at 一律静默忽略)", "app/service/systems/setting/warehouse.js:saveFrontCert 校验链 parseFrontConfigCertPem(crypto.X509Certificate)→ assertFrontConfigCertValid(未生效/已过期 400)→ validateFrontConfigKeyPem(SPKI 公钥指纹比对,私钥无法解析/不匹配 400)→ collectFrontConfigCertNames/frontConfigCertCoversDomain(SAN DNS/CN 精确或 *.example.com 通配,不覆盖 400),所有证书校验失败统一文案「证书不合法」;domain 经 normalizeFrontConfigText(data.domain,'domain',100) 校验非空(400「domain 不能为空」)与超长(400「domain 长度不能超过 100 字符」);cert_pem/key_pem 必填(400「cert_pem 不能为空」「key_pem 不能为空」)且 ≤65536 字符(超长 400「{字段} 内容长度不能超过 65536 字符」);通过后 patch.domain/cert_path/key_path/cert_expire_at=new Date(cert.validTo)(权威值非入参)+ sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at;writeFrontConfigCertFiles 落盘 frontConfig.certStagingDir({store_id}_{domain}.crt/.key,内容不入库只回传路径,暂存目录未配置或写入失败 500);assertFrontConfigDomainUnique 全局唯一(409「域名 {domain} 已被其他仓库使用」,并发唯一索引冲突兜底 409「仓库前端配置保存冲突,请稍后重试」);写库成功后清理旧 domain 与新 domain 的 front:config:domain:{*} 缓存(先写库后清缓存,清缓存失败仅日志)", "app/service/systems/setting/warehouse.js:saveFrontConfig 仅按 FRONT_CONFIG_TEXT_FIELDS(title/logo_url/favicon_url/login_bg_url)+ theme 组装 patch;不再受理 domain/cert_*;保存仍重置同步状态并清理当前 domain 公共拉取缓存;响应 buildFrontConfigOutput 15 字段(warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at),getFrontConfig/frontConfig.getByDomain 无变化未改动", "methods/system.json:setting.warehouse 分组 list 末尾新增 saveFrontCert 条目(isNeedLogin=true、isNeedAuth=false、Authorization 头);saveFrontConfig 条目入参瘦身(移除 domain/cert_pem/key_pem/cert_path/key_path 入参说明,description 注明前端传值静默忽略)与 errors 修订(证书校验 400 统一文案「证书不合法」移至 saveFrontCert;保留 400/403/409 并发兜底/500);docMeta.version 0.3.98 -> 0.3.99,updatedAt 2026-09-07 -> 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "AI_METHOD_ROUTING.md:按文件内维护说明执行第 6 节自动扫描清单刷新(node .\\script\\tmp-gen-service-method-inventory.cjs → node .\\script\\tmp-update-ai-method-routing.cjs),systemMethods/setting/warehouse.js 3→6、systems/setting/warehouse.js 12→31(以扫描结果为准)", "README.md / AI_TOOLBOX.md 无需同步:检索确认无 saveFrontConfig/saveFrontCert 相关描述", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.07-front-config-independent-deploy", "date": "2026-09-07", "type": "changed", "summary": "仓库前端独立部署功能文档同步:新增 setting.warehouse.saveFrontConfig / setting.warehouse.getFrontConfig 与公共无鉴权接口 frontConfig.getByDomain 三个方法文档。保存配置支持上传 cert_pem/key_pem:后端解析证书并校验(无法解析/未生效/已过期/SAN-CN 不包含 domain/私钥不匹配报 400),自动权威写入 cert_expire_at(不再是入参,前端传值被忽略),证书内容落盘暂存目录、库内只存路径;纯路径模式(未提供 cert_pem)直接保存 cert_path/key_path 且不写有效期;保存即重置同步状态(sync_status=0、sync_attempts=0)。新增 favicon_url 字段(保存/查询/公共拉取均含)。公共拉取接口免登录、免鉴权、免权限(保留系统日志),响应仅 6 个公开字段(绝不返回证书路径/同步状态等内部字段),Redis 缓存 front:config:domain:{domain}(命中 TTL 600s、未登记域名空缓存 60s 防穿透、保存配置自动失效新旧域名缓存)。关联迁移 20260907150000(建表 wms_warehouse_front_config)与 20260907170000(favicon_url 列)。", "methods": [ "setting.warehouse.saveFrontConfig", "setting.warehouse.getFrontConfig", "frontConfig.getByDomain" ], "module": "setting.warehouse", "notes": [ "app/service/systemMethods/setting/warehouse.js:saveFrontConfig 方法层白名单仅透传 domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_pem/key_pem(cert_expire_at 不入白名单,前端传值直接忽略);getFrontConfig 无入参;两方法均需登录、免权限(_noNeedRight 含 getFrontConfig,saveFrontConfig)、免鉴权(_noNeedAuth 含两方法),saveFrontConfig 权限由业务层 getCurrentSubject().isWarehouse 判定(非仓库主体 403「仅仓库主体可配置前端独立部署」)", "app/service/systemMethods/frontConfig.js:新模块 frontConfig(与 workbench/inbox 同级),getByDomain 配置 _noNeedLogin/_noNeedRight/_noNeedAuth='getByDomain'(免登录、免鉴权、免权限)、保留系统日志(_noNeedLog 为空);薄出口调用 systems.setting.warehouse.getFrontConfigByDomain,错误 code 透传(400/404/500)", "app/service/systems/setting/warehouse.js:saveFrontConfig upsert 一仓一行;domain 非空时 assertFrontConfigDomainUnique 全局唯一校验(409「域名 {domain} 已被其他仓库使用」,并发唯一索引冲突兜底转 409「仓库前端配置保存冲突,请稍后重试」);normalizeFrontConfigText 校验文本字段长度(domain/title≤100、logo_url/login_bg_url/favicon_url≤255、cert_path/key_path≤500);normalizeFrontConfigTheme 校验 theme 为合法 JSON 对象;normalizeFrontConfigPem 限制 PEM ≤65536 字符;提供 cert_pem 时 parseFrontConfigCertPem(crypto.X509Certificate)+ assertFrontConfigCertValid(未生效/已过期 400)+ collectFrontConfigCertNames/frontConfigCertCoversDomain(SAN DNS/CN 精确或 *.example.com 通配匹配,不含 domain 报 400)+ validateFrontConfigKeyPem(SPKI 公钥指纹比对),writeFrontConfigCertFiles 落盘暂存目录({store_id}_{domain}.crt/.key,只回传路径、内容不入库,旧暂存文件不主动删除);key_pem 单独提供报 400;未提供 cert_pem 时纯路径模式直接落库、cert_expire_at 允许为空;保存即 patch.sync_status=0/sync_attempts=0 并清空 last_sync_error/last_synced_at;写库成功后清理新旧 domain 公共拉取缓存(先写库后清缓存,清缓存失败仅日志不影响保存)", "app/service/systems/setting/warehouse.js:getFrontConfig 按 getCurrentWarehouseId()(ctx.user.store_id,未识别报 400「未识别到当前仓库,无法操作仓库设置」)查询 wms_warehouse_front_config,无记录返回 buildFrontConfigOutput 默认空配置(15 字段:warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at)", "app/service/systems/setting/warehouse.js:getFrontConfigByDomain 校验 domain 必填非空(400「domain 不能为空」)且 ≤100 字符(400「domain 长度不能超过 100 字符」);Redis key front:config:domain:{domain},配置命中缓存 TTL 600s(FRONT_CONFIG_PUBLIC_CACHE_TTL_SECONDS),未登记域名写 {configured:false} 空缓存 TTL 60s(FRONT_CONFIG_PUBLIC_MISS_CACHE_TTL_SECONDS)防穿透并返回 404「域名未配置」;响应仅 FRONT_CONFIG_PUBLIC_FIELDS 白名单 6 字段(domain/title/logo_url/login_bg_url/favicon_url/theme),绝不返回 cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段;Redis 读异常降级查库、写异常仅日志", "app/model/warehouse_front_config.js:wms_warehouse_front_config 单表一仓一行(uk_store_id 唯一、uk_domain 可空列唯一索引允许多 NULL,非空唯一性靠应用层校验),字段含 domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at;不启用 paranoid,无 deleted_at", "数据库迁移:database/migrations/20260907150000-create-wms-warehouse-front-config.js(建表 wms_warehouse_front_config 及索引)、database/migrations/20260907170000-add-favicon-url-to-wms-warehouse-front-config.js(新增 favicon_url 列)", "methods/system.json:setting.warehouse 分组 list 末尾新增 saveFrontConfig/getFrontConfig 条目(isNeedLogin=true、isNeedAuth=false、Authorization 头);新增 frontConfig 分组(groupName 前端独立部署模块)与 frontConfig.getByDomain 条目(isNeedLogin=false、isNeedAuth=false、headers 为空,免登录免鉴权免权限);docMeta.version 0.3.97 -> 0.3.98,updatedAt 保持 2026-09-07;本变更记录写入 methods/changes/system.json 数组首位", "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 无需同步:检索确认无前端独立部署配置相关行为描述(AI_METHOD_ROUTING.md 为函数清单由扫描脚本维护,本任务未执行扫描,如需刷新可另行执行)", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.07-ai-method-routing-service-inventory-refresh", "date": "2026-09-07", "type": "changed", "summary": "AI_METHOD_ROUTING.md 第 6 节「全量 Service Method 能力清单」按项目维护脚本重新扫描刷新:receiving_entry_match.js 由 12 个函数更新为 27 个(补齐台账/防超扣链路的 _bindReceivingsWithStorageSync、_bindOneReceivingAndSyncStorage、_syncReceivingStorageByEntryItems、_parseLedgerMap、_serializeLedgerMap、_buildLegacyBaselineLedger、_bindingAllocationByStock、_recalcReceivingStorageStatus、_reconcileEntryReceivedQuantity、recordLedgerAllocation、setLedgerAllocation、rollbackEntryOrderBindings、_rollbackOneBindingStorage 等),并同步刷新 workbench.js(52→61)、express_platform.js(16→17)、intercept_auto_confirm.js(新增)等存量漂移条目;本节内容由自动扫描脚本生成,仅函数清单、无接口行为描述。", "methods": [ "storage.entry.bindReceiving", "storage.entry.unbindReceiving", "storage.entry.cancel", "storage.entry.commit", "storage.entry.quickInbound" ], "notes": [ "本记录是对 2026.09.07-entry-receiving-binding-allocated-quantity-ledger 同任务的补充记录:该记录撰写时判定 AI_METHOD_ROUTING.md 无需同步,随后按文件内维护说明执行刷新脚本同步了第 6 节自动扫描清单(本任务涉及 receiving_entry_match.js 新增 13 个台账/防超扣相关方法)", "刷新方式:node .\\script\\tmp-gen-service-method-inventory.cjs(扫描 app/service/**/*.js 输出 temp/tmp-service-method-inventory.md)→ node .\\script\\tmp-update-ai-method-routing.cjs(注入 AI_METHOD_ROUTING.md 第 6 节 BEGIN/END 标记内),自动生成时间 2026-09-06 → 2026-09-07、文件数 203 → 204", "生成器按类方法扫描,个别内置标识符(如 max、min、Set、Date、NOW)会被一并列出为方法名,属于既有生成器口径,非手工修改", "methods/system.json 无实质变化:本次 spec 复用 storage.entry.unbindReceiving 现有条目内容,upsert 为无差异重写;接口行为、参数、响应、错误码均不变", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ], "module": "storage.entry" }, { "version": "2026.09.07-entry-receiving-binding-allocated-quantity-ledger", "date": "2026-09-07", "type": "changed", "summary": "入库单绑定收货单链路防超扣修复文档同步:wms_entry_order_receiving 新增 allocated_quantity 数量台账列(JSON,收货明细ID→分配数量,迁移 20260907160000 仅基表);storage.entry.bindReceiving COMPLETED 绑定改为台账制归一化分配(每 SKU 分配目标 = min(入库单计划数 − 其他绑定已占用, 收货单剩余可入量),多退少补、旧超分数据回收、重复绑定幂等跳过、软删恢复仅分配剩余量),并同步 entry_items.received_quantity 口径;新增 storage.entry.unbindReceiving 接口文档(解绑按台账回滚 stored_quantity、重算 storage_status、清空台账,响应新增 rolled_back_quantity);storage.entry.cancel 作废回滚改台账制逐绑定回收(不再整体清零共享收货单);storage.entry.commit / storage.entry.quickInbound 分别按覆写/累计语义同步台账。", "methods": [ "storage.entry.bindReceiving", "storage.entry.unbindReceiving", "storage.entry.cancel", "storage.entry.commit", "storage.entry.quickInbound" ], "notes": [ "app/model/entry_order_receiving.js 新增 allocated_quantity 列(JSON 可空,comment 数量台账:收货明细ID→已分配数量(JSON对象,如 {\"123\":8});null 表示旧数据未初始化);数据库迁移 database/migrations/20260907160000-add-allocated-quantity-to-wms-entry-order-receiving.js 仅基表(describeTable 幂等检测)", "app/service/systems/receiving_entry_match.js _syncReceivingStorageByEntryItems(方案A台账版):FOR UPDATE 行锁入库单主行 + 该入库单全部未删除绑定行 + 绑定收货单明细行,串行化同一入库单的分配事务;每 SKU 分配目标 target = min(max(0, 入库单计划数 − 其他绑定已分配), 当前绑定已分配 + 收货单剩余可入量),多退少补(旧数据超分回收、亏分补分配);明细级结果回写绑定行台账 allocated_quantity,重算收货单主表 storage_status,并经 _reconcileEntryReceivedQuantity 同步 entry_items.received_quantity;返回的 storage_sync.stored_total 仅计补分配量(归一化回收不计入)", "幂等/恢复语义:绑定已存在且未删除 → skipped(error_code=ALREADY_BOUND,不重复分配);已软删除 → restore 后按归一化目标仅分配剩余量(restored=true);并发唯一索引冲突按已绑定跳过。旧绑定行(台账 null)由 _buildLegacyBaselineLedger 按收货侧累计量兜底重建明细级台账,新链路绑定行台账初始化为 {}(非 null)", "新增 unbindEntryOrderReceiving(对应 storage.entry.unbindReceiving):仅 CREATED / PENDING 可解绑(COMPLETED / CANCELLED 拒绝),解绑不回退入库单状态;事务内行锁后按台账逐明细回收该收货单 stored_quantity、重算明细与主表 storage_status、台账重置为 {},软删除主表绑定与关联明细绑定(InboundDirectLog status=committed 且 receiving_detail_id 非空的记录);返回 success/failed/success_count/failed_count,success 项含 released_detail_ids / released_detail_count / rolled_back_quantity(本次回滚的 stored_quantity 总量,无可回滚量为 0);不影响同一收货单上其他入库单的占用", "app/service/systems/storage/entry.js cancel → _rollbackReceivingStorageStatus → rollbackEntryOrderBindings(receivingId=null、softDeleteBinding=false):按台账逐绑定回收、清空台账(绑定行保留)、重算 received_quantity;回滚失败仅日志不阻塞作废主流程;QM 来源入库单作废前先发送奇门取消同步,sync_status=SUCCESS 不可取消", "app/service/systems/inbound_direct_log.js commit 绑定模式 _syncReceivingStorageStatus → receivingEntryMatch.setLedgerAllocation(按 committed 汇总量覆写台账条目);app/service/systems/storage/entry.js quickInbound _applyReceivingInboundUsage → receivingEntryMatch.recordLedgerAllocation(按本次落到收货明细的分配量累计台账)。说明:receiving_entry_match._commitBinding(PDA 明细绑定)内部调用 recordLedgerAllocation,但当前无调用方(实际 addItem 绑定走 inboundDirectLog._bindReceivingDetail),本次按实际生效链路记录,addItem 文档不改动", "methods/system.json:storage.entry.bindReceiving 条目 description/storage_sync.stored_total 说明按台账归一化语义更新;新增 storage.entry.unbindReceiving 条目(按脚本规则追加到 storage.entry 组列表末尾);storage.entry.cancel / commit / quickInbound 描述补充台账行为;cancel errors 补充「入库单已完成回传,不可取消」;版本 0.3.96 -> 0.3.97(docMeta.version),updatedAt 保持 2026-09-07", "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 检索确认:无本链路行为描述(AI_METHOD_ROUTING.md 仅函数清单,无行为描述),无需同步", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ], "module": "storage.entry" }, { "version": "2026.09.07-entry-bindReceiving-completed-storage-sync", "date": "2026-09-07", "type": "changed", "summary": "storage.entry.bindReceiving 契约变更:可绑定状态由 CREATED/PENDING 调整为 CREATED/COMPLETED;COMPLETED 绑定在事务内联动同步收货单入库进度(SKU 级累加 stored_quantity、重算明细与主表 storage_status);绑定已存在时幂等跳过不重复累加、软删除恢复后执行同步;返回结构由 success/failed/success_count/failed_count 修正为实际返回的 bound/skipped/summary,并在 COMPLETED 结果中新增 restored 与 storage_sync(含 unmatched_items)。", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "app/service/systems/receiving_entry_match.js bindEntryOrderReceiving:ALLOWED_BIND_STATUSES = [CREATED, COMPLETED],其他状态抛错「入库单状态不允许绑定,当前状态: {status},仅 CREATED、COMPLETED 状态可操作」;收货单校验含 存在未删除、同仓库、同货主、未取消、已审核(is_review)", "COMPLETED 路径新增 _bindReceivingsWithStorageSync / _bindOneReceivingAndSyncStorage / _syncReceivingStorageByEntryItems:事务内逐收货单主表绑定 + 入库明细按 stock_id(≡ wms_receiving_detail.system_product_id)汇总,FOR UPDATE 行锁后逐明细累加 stored_quantity(上限 actual_quantity),按 stored vs actual 重算明细 storage_status(none/partial/all)并汇总更新收货单主表 storage_status;SKU 未匹配明细汇总进 unmatched_items;任一异常整体回滚", "幂等语义:绑定已存在且未删除 → skipped(error_code=ALREADY_BOUND,不重复累加);已软删除 → restore 并执行进度同步(restored=true);并发唯一索引冲突 → 按已绑定跳过", "methods/system.json:storage.entry.bindReceiving 条目 description/errors 按代码更新;response 由 success/failed/success_count/failed_count 修正为实际返回的 flag/code/message/bound/skipped/summary/timestamp(bound 项 CREATED 含 receiving_id/receiving_number/created,COMPLETED 新增 restored 与 storage_sync.stored_total/matched_item_count/unmatched_items;skipped 项 error_code 枚举 ALREADY_BOUND/BINDING_WRITE_FAILED;收货单校验失败不返回明细、仅 summary.skipped_count 计数);错误码同步为实际文案(抛错经 /system 全局异常处理返回 500「接口错误: ...」);版本 0.3.95 -> 0.3.96(docMeta.version),updatedAt 保持 2026-09-07", "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 检索确认:无本接口状态规则描述(AI_METHOD_ROUTING.md 仅函数清单,无行为描述),无需同步", "本次仅同步文档,未修改任何业务代码" ], "module": "storage.entry" }, { "version": "2026.09.07-store-openAccount-remove-logo-url-domain", "date": "2026-09-07", "type": "changed", "summary": "storeWarehouse.store.openAccount 入参移除 logo_url、domain 两个可选参数:wms_store 表的 logo_url、domain 字段已废弃(代码写入链路已移除、数据库已执行删列迁移 20260907140000-drop-logo-url-and-domain-from-wms-store),文档同步删除这两个可选 body 入参对象;字段无业务承载,前端若仍传参会被忽略,不破坏响应结构。", "methods": [ "storeWarehouse.store.openAccount" ], "notes": [ "database/migrations/20260907140000-drop-logo-url-and-domain-from-wms-store.js:删除 wms_store 表的 logo_url、domain 两列(开发库已执行完成)", "代码写入链路(openAccount 创建货主)已由开发 agent 移除 logo_url、domain 写入,app/ 下无 logo_url 残留引用", "methods/system.json:storeWarehouse.store.openAccount 的 params 删除 logo_url(name logo_url、type string、required false、source body、description Logo 链接)与 domain(name domain、type string、required false、source body、description 绑定域名)两个可选 body 入参对象;其余 17 个入参、response(store_id/account_id/contract_id/company_name/username/role_id)与 errors 均不变;版本 0.3.94 -> 0.3.95(docMeta.version),updatedAt 保持 2026-09-07", "影响说明:字段已无业务承载,前端若仍传参会被忽略;响应结构不变,无错误码、鉴权方式、公共请求头变化", "methods/ 全目录检索确认:logo_url、Logo 链接、绑定域名 仅存在于 methods/system.json 本方法参数块,无其他文件或方法残留引用", "本次仅同步文档,未修改任何代码、迁移脚本或数据库" ], "module": "storeWarehouse.store" }, { "version": "2026.09.07-order-delivery-dispatch-dispath-time", "date": "2026-09-07", "type": "changed", "summary": "配送表 wms_order_delivery_{wh}_dispatch 新增 dispath_time 字段(DATETIME 可空无默认值,comment 订单迁移进配送表的时间),用于记录订单从待处理表迁移进配送表的时刻:模型 dispatch 分支新增字段定义,出库迁移 buildDispatchRow 写入 new Date(),迁移脚本覆盖全部配送分表;仅配送表独有(基表/current/history/outsourced 不涉及),无接口入参/响应结构变化。", "methods": [ "order.manualOutboundOrder" ], "notes": [ "database/migrations/20260907120000-add-dispath-time-to-order-delivery-dispatch.js:为库内全部配送分表 wms_order_delivery_{wh}_dispatch 增加 dispath_time 列(DATETIME 可空无默认值,comment 订单迁移进配送表的时间),仅配送表独有、不加基表/current/history/outsourced 分表;describeTable 幂等检测,列已存在则跳过;开发、生产均已执行。", "app/model/order_delivery_table_schema.js buildTableAttributes:dispatch 分支新增 dispath_time 字段定义(Sequelize DATE / allowNull=true / comment 订单迁移进配送表的时间),与既有 dispatch_lane 并列,仅 dispatch 分表生效。", "app/service/systems/order_delivery_migration.js buildDispatchRow:写入配送表行时追加 dispath_time = new Date()(订单迁移进配送表的时刻),源表数据不受影响;保留先删除源行 dispatch_lane、再统一写 DISPATCH_LANE 的既有逻辑。", "methods/system.json:order.manualOutboundOrder description 补充「迁移写入配送表的订单行记录 dispath_time(buildDispatchRow 写入 new Date(),仅配送表独有)」说明;errors 由 description 键规范化为 message 键(文案不变,满足更新脚本 schema);版本 0.3.93 -> 0.3.94(docMeta.version),updatedAt 更新为 2026-09-07。", "无接口入参/响应结构/错误码/鉴权变化;配送表整行 raw 响应(order.pendingOrder.detail 订单头、order.list 列表行等)文档均为 raw 行引用而非全量字段清单,按既有口径不硬加字段说明,仅在本变更记录体现。", "AI_METHOD_ROUTING.md(函数清单,无配送表字段清单章节)与 AI_TOOLBOX.md(无配送表字段相关内容)均无需同步;README.md 与 docs/*.md 亦无配送表字段清单章节。", "发布版本 v1.0.0-20260907164410-c5150bc(2026-09-07 发布);本次仅同步文档,未修改任何代码、迁移脚本或数据库。" ], "module": "order.index" }, { "version": "2026.09.06-workbench-resetLoginCode-reset-token", "date": "2026-09-06", "type": "changed", "summary": "workbench.resetLoginCode 行为变更:重置登录码时同步重置工作台 token。生成新 64 位 hex token 与 login_code 一并持久化到 wms_workbench(record.update({ login_code, token }));更新库前先删除旧 workbench:token:{旧token} 缓存,旧 token 随即失效;立即回填新 token 信息缓存(复用 buildWorkbenchTokenInfo,含 members/current_wave/current_orders,TTL 300s);返回值新增 token 字段 { id, login_code, token },出口层展开后响应顶层含 id、login_code、token;旧行为「token 不变」相关描述已更新。旧 token 失效后旧会话返回 403,设备端需用新 token 继续工作。", "methods": [ "workbench.resetLoginCode" ], "notes": [ "app/service/systems/workbench.js:resetLoginCode(id) 同步重置 token:generateUniqueWorkbenchLoginCode 生成新 login_code、generateWorkbenchToken 生成新 64 位 hex token,先 delCacheAsync 删除旧 workbench:token:{旧token} 缓存(旧 token 随即失效),再 record.update({ login_code, token }) 一并持久化,随后 setCacheAsync 立即回填新 token 信息缓存(buildWorkbenchTokenInfo,含 members/current_wave/current_orders,TTL 300s),返回 { id, login_code, token }", "app/service/systemMethods/workbench.js:resetLoginCode 薄出口 this.success('重置成功', result) 展开后响应顶层含 id、login_code、token(原仅 id/login_code,本次新增 token)", "methods/system.json:workbench.resetLoginCode 条目 description 更新(说明 login_code 与 token 同步重置、旧 token 缓存删除使旧 token 随即失效、立即回填新 token 缓存),response 新增 token 字段(string,64 位 hex,必返回),errors 补充 403 备注(旧 token 失效后旧会话返回 403,设备端需用新 token 继续工作);版本 0.3.92 -> 0.3.93(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md:路由与方法清单无变化(5.3 节映射表与函数清单均未涉及行为描述),无需同步", "本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-queryOrder", "date": "2026-09-06", "type": "changed", "summary": "工作台模块新增免登录/免权限/免鉴权的 token 自校验只读接口 workbench.queryOrder(条码查询订单):入参 token(必填)+ barcode(必填),仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单);响应 data 与 business(queryOrder) 分支一致(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table,散单 order 附 intercept_flag/pack_flag 0/1 标志、团购附 batch 波次总量信息);只读查询不涉及缓存失效;错误码沿用统一口径:无 token 401、token 无效 403、工作台未绑定有效仓库 403,条码为空/未找到运单/未找到订单为业务失败(flag=failure、code=0)。", "methods": [ "workbench.queryOrder" ], "notes": [ "app/service/systemMethods/workbench.js:新增 queryOrder 薄出口(调用业务层 queryOrderByToken),systemInit 免登录/免权限/免鉴权白名单均已包含 queryOrder(未声明免日志,保留系统日志)", "app/service/systems/workbench.js:新增 queryOrderByToken(data):走 resolveWorkbenchContext(token) 统一 token 校验(无 token 401、token 无效 403),解析成功后从 ctx.workbenchWarehouseId 注入仓库(工作台未绑定有效仓库返回 403),复用 _queryOrder 业务实现;只读查询,不涉及缓存失效", "methods/system.json:工作台模块新增 workbench.queryOrder 条目(isNeedAuth=false、isNeedLogin=false、isNeedRight=false,入参仅 token/barcode,description 说明 warehouse_id/workbench_id 由服务端注入);版本 0.3.91 -> 0.3.92(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节新增 queryOrder 映射行与接口说明;本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-pack-order-finish-pack-send-weight", "date": "2026-09-06", "type": "changed", "summary": "工作台模块新增 3 个免登录/免权限/免鉴权的 token 自校验接口 workbench.packOrder(打包上报)、workbench.finishPack(打包完成)、workbench.sendWeight(称重上报,重量单位克),并统一公共 token 校验口径:新增 resolveWorkbenchContext(token) 公共校验方法(解析成功写入 ctx.workbenchToken/ctx.workbenchId/ctx.workbenchWarehouseId),无 token 统一返回 code=401(消息「工作台 token 不能为空」)、token 无效/工作台不存在保持 403;受影响的 workbench.getWorkbenchInfo/workbench.bindMember/workbench.removeMember 三个接口「无 token」错误码由 400 调整为 401,bindMember/removeMember 校验顺序变为 token 优先(token 无效且参数缺失的边界场景由 400 变 403)。", "methods": [ "workbench.packOrder", "workbench.finishPack", "workbench.sendWeight", "workbench.getWorkbenchInfo", "workbench.bindMember", "workbench.removeMember" ], "notes": [ "app/service/systemMethods/workbench.js:新增 packOrder/finishPack/sendWeight 三个薄出口(调用业务层 packOrderByToken/finishPackByToken/sendWeightByToken),systemInit 免登录/免权限/免鉴权白名单均已包含三个方法(未声明免日志,保留系统日志)", "app/service/systems/workbench.js:新增公共 token 校验方法 resolveWorkbenchContext(token):无 token 统一返回 401(消息「工作台 token 不能为空」),token 无效/工作台不存在(含软删除)返回 403(保持原口径);解析成功后写入 ctx.workbenchToken/ctx.workbenchId/ctx.workbenchWarehouseId 供后续方法使用(按仓库限定查询/写入,禁止跨仓库)", "新增 packOrderByToken/finishPackByToken/sendWeightByToken:仓库/工作台均由 token 解析上下文注入(body 传入 warehouse_id/workbench_id 被忽略),复用 _packOrder/_finishPack/_sendWeight 业务实现;打包/称重状态变更后失效对应工作台 token 缓存,保证 getWorkbenchInfo 及时返回最新信息", "行为变更:workbench.getWorkbenchInfo/workbench.bindMember/workbench.removeMember 无 token 时错误码由 400 调整为 401;bindMember/removeMember 校验顺序变为 token 优先(token 无效且参数缺失的边界场景由 400 变 403)", "methods/system.json:工作台模块新增 workbench.packOrder/workbench.finishPack/workbench.sendWeight 三条目(isNeedAuth=false、isNeedLogin=false、isNeedRight=false),并更新 workbench.getWorkbenchInfo/workbench.bindMember/workbench.removeMember 错误码(400→401);版本 0.3.90 -> 0.3.91(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节新增三个接口映射行与 401 口径说明;本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-getWorkbenchInfo-wave-items-total", "date": "2026-09-06", "type": "changed", "summary": "workbench.getWorkbenchInfo 响应 data.current_wave 新增 items_total 字段(number):波次商品总件数,口径为商品总件数(非 SKU 品种数),来源为订单分表 wms_order_delivery_{仓库}_{current/dispatch} 的 items_total 列按 wave_id+warehouse_id 求和(与既有 order_count 同款分表口径),带 15s 短缓存兜底;current_wave 其余字段(task_id/wave_id/wave_no/status/order_count/operator_text/start_time)不变,无团购任务时 current_wave 仍为空对象;items_total 随 token 缓存 workbench:token:{token}(TTL 300s)一并缓存,packOrder/finishPack 打包状态变更后主动失效缓存,下一次调用即返回最新数据。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "app/service/systems/workbench.js:新增 _sumWaveItemsTotal(并发遍历 current+dispatch 分表 SUM(items_total),按 wave_id+warehouse_id 过滤,单表失败按 0 处理)与 _sumWaveItemsTotalCached(cache:workbench:wave_items_total:{warehouseId}:{waveId},TTL 15s,缓存不可用降级实时统计);buildCurrentPackingInfo 组装 current_wave 时通过 Promise.all 并行统计 order_count 与 items_total,current_wave 新增 items_total 字段", "getWorkbenchInfoByToken 缓存优先(workbench:token:{token},TTL 300s),缓存值已包含 items_total;_packOrder/_finishPack 打包状态变更后调用 invalidateWorkbenchTokenCacheByWorkbenchId 删除 token 缓存,保证下一次 getWorkbenchInfo 返回最新打包信息", "methods/system.json:workbench.getWorkbenchInfo description 与 current_wave 对象描述补充 items_total 说明,response 新增 current_wave.items_total 条目(沿用 current_wave.xxx 嵌套命名惯例);版本 0.3.89 -> 0.3.90(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节接口文档行追加本变更记录版本号,当前打包信息行补充 items_total 口径;AI_TOOLBOX.md 无 workbench 相关内容,无需同步", "本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-getWorkbenchInfo-current-packing", "date": "2026-09-06", "type": "changed", "summary": "workbench.getWorkbenchInfo 响应 data 新增当前正在打包的波次与订单信息:current_wave(当前正在打包的团购波次:wms_pack_task 中 pack_mode=2 且 wave_id>0 的最新一条未结束任务(status<2)组装,无团购任务时为空对象,含 task_id/wave_id/wave_no/status/order_count/operator_text/start_time,order_count 为 15s 短缓存实时计数)与 current_orders(当前正在打包的订单数组:全部未结束任务按 id 倒序,逐单按 current→dispatch 分表补发货单号,无进行中任务时为空数组,每项含 task_id/order_id/delivery_order_code/wave_id/wave_no/pack_mode/status/pack_quantity/operator_text/start_time);打包信息随 token 缓存 workbench:token:{token}(TTL 300s)一并缓存,packOrder/finishPack 打包状态变更后主动失效缓存,下一次调用即返回最新数据;打包信息查询异常时降级(current_wave 空对象、current_orders 空数组),不影响主信息与 members。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "app/service/systems/workbench.js:新增 listCurrentPackTasks(wms_pack_task 按 workbench_id/warehouse_id 过滤 status<2(0=待处理/1=打包中),按 id 倒序)与 buildCurrentPackingInfo(组装 current_wave/current_orders:逐单按 current→dispatch 分表补 delivery_order_code;current_wave 取最新一条 pack_mode=2 且 wave_id>0 的未结束任务,order_count 走 _countWaveOrdersCached 实时计数 + 15s 短缓存;任一环节异常降级为空对象/空数组);buildWorkbenchTokenInfo 统一组装主表字段 + members + 打包信息", "getWorkbenchInfoByToken 缓存优先(workbench:token:{token},TTL 300s),缓存值同样含打包信息;_packOrder/_finishPack(workbench.business packOrder/finishPack 调度)打包状态变更后调用 invalidateWorkbenchTokenCacheByWorkbenchId 删除 token 缓存,保证下一次 getWorkbenchInfo 返回最新打包中信息", "methods/system.json:workbench.getWorkbenchInfo description 补充 current_wave/current_orders 与缓存失效行为说明,response 新增 current_wave/current_wave.* 与 current_orders/current_orders[].* 条目;版本 0.3.88 -> 0.3.89(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节接口文档行追加本变更记录版本号;AI_TOOLBOX.md 无 workbench 相关内容,无需同步", "本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-getWorkbenchInfo-members", "date": "2026-09-06", "type": "changed", "summary": "workbench.getWorkbenchInfo 响应 data 新增 members 成员数组:成员来自副表 wms_workbench_member 未软删除记录(按 id ASC),元素含 id/user_id/user_name(轻量结构);接口 token 缓存 workbench:token:{token}(TTL 300s)缓存值已包含 members,绑定/移除成员后缓存立即失效,下一次调用即返回最新成员;主表字段与不含 token/login_code 口径不变。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "app/service/systems/workbench.js:buildWorkbenchTokenInfo 统一组装主表字段(formatWorkbenchTokenInfo:id/warehouse_id/name/status/type/remark/device_ids/created_at/updated_at,不含 token/login_code)+ members(listWorkbenchMembers 查 wms_workbench_member 未软删除记录,attributes id/user_id/user_name,按 id ASC;查询失败降级空数组)", "getWorkbenchInfoByToken 缓存优先(workbench:token:{token},TTL 300s)、查库兜底回填缓存;removeWorkbenchMember/bindWorkbenchMember 成功后 delCacheAsync 清除 token 信息缓存,保证下一次调用立即反映最新成员", "methods/system.json:workbench.getWorkbenchInfo description 补充 members 与缓存行为说明,response 新增 members/members[].id/members[].user_id/members[].user_name 条目;版本 0.3.87 -> 0.3.88(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节接口文档行追加本变更记录版本号;AI_TOOLBOX.md 无 workbench 相关内容,无需同步", "本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-index.queryUserByToken", "date": "2026-09-06", "type": "added", "summary": "基础模块新增 index.queryUserByToken:按 ye4s 登录临时码 token 查询用户信息(免登录、免鉴权),命中返回 flag=success、code=200 与 real_name、wms_account_id,未命中返回 code=404 用户不存在,数据库异常返回 code=500。", "methods": [ "index.queryUserByToken" ], "notes": [ "app/service/systemMethods/index.js 新增 queryUserByToken:入参 token(ye4s 登录临时码,对应 ye4s 库 ye4s_user 表 tmp_code 字段),为空返回 code 400「token 不能为空」;命中返回 success + real_name(空串兜底)/wms_account_id(null 兜底),未命中返回 code 404「用户不存在」,异常返回 code 500", "免登录、免鉴权:queryUserByToken 已加入 _noNeedLogin / _noNeedAuth 白名单(systemInit 声明)", "methods/system.json:基础模块(module=index)新增 index.queryUserByToken 条目(isNeedAuth=false、isNeedLogin=false);版本 0.3.86 -> 0.3.87(docMeta.version),updatedAt 保持 2026-09-06", "本次任务仅同步文档,未修改任何业务代码" ], "module": "index" }, { "version": "2026.09.06-recheckOrder.remove-unprinted-intercepted", "date": "2026-09-06", "type": "enhanced", "summary": "复核链路新增自动清理:更新复核状态后,自动将波次内「已拦截且未打印」的订单移除出波次(回池),拦截解除后可重新抓取发货,避免拦截订单卡死波次完成判定。", "methods": [ "order.recheckOrder.confirmRecheck", "order.recheckOrder.batchQuickRecheck", "order.recheckOrder.batchQuickRecheckByWave" ], "notes": [ "app/service/systemMethods/order/recheckOrder.js 新增 removeUnprintedInterceptedOrdersFromWave:移除波次内 print_status='none' 且 intercept_status!='none'(空值按 none 处理)的订单(wave_id=0、wave_no/wave_strategy_version/wave_scan_result 清空),调用 wave.deleteOrderWaveIndexByOrderIds 删波次索引,删除 wms_wave_pick_task_order 任务订单关联,回写 wms_wave_batch total_orders/processed_orders 统计,写 ORDER_WAVE_REMOVE 操作日志,并触发 enqueueWaveStrategyQuickScanPostOrderChange 波次策略快扫(拦截未解除时策略仍排除,不会误抓)", "三个复核入口接入:updateTaskOrderReviewAndTryUnbindCart(confirmRecheck 单订单)、updateTaskOrdersReviewBatch(批量/团购)、_updateTaskOrderReviewInTransaction(batchQuickRecheck/batchQuickRecheckByWave 事务版,清理动作随事务执行并透传事务对象);清理失败仅记录 warn 日志,不影响复核主流程", "清理先于任务/波次完成判定执行,拦截订单移除后完成判定口径自然收敛,未改动既有完成判定 SQL;清理以 wave_id>0 为条件,幂等可重复触发", "已打印(print_status!='none')的拦截订单保持不动,避免已贴面单实物与波次记录分离;该类订单仍需人工 wave.batchRemoveOrders 处理", "单元测试:test/app/service/systemMethods/order/recheckOrder.removeUnprintedIntercepted.test.js(8 用例全通过,ESLint 0/0)" ], "module": "order.recheckOrder" }, { "version": "2026.09.06-stock.report.exportStore-lock-exclusion", "date": "2026-09-06", "type": "updated", "summary": "stock.report.exportStore(货主侧库存报表导出)变更记录口径收紧:变更记录 sheet 只导出出入库流水(INBOUND/OUTBOUND),锁定/解锁(LOCK/UNLOCK)记录一律不导出;export_mode/exportMode 参数对货主侧不再有任何效果(该参数仅仓库侧 stock.report.export 生效)。", "methods": [ "stock.report.exportStore", "stock.report.export" ], "notes": [ "app/service/systems/storage/report.js export():isStoreMode(货主侧)分支固定追加 t.transaction_type NOT IN ('LOCK','UNLOCK'),无视 exportMode;仓库侧维持 export_mode='item' 时含 LOCK、否则排除 LOCK 的既有行为", "methods/system.json:stock.report.exportStore 移除 export_mode/exportMode 参数条目,method description 补充“变更记录只含出入库流水(LOCK/UNLOCK 不导出)”与“export_mode/exportMode 不支持也不生效”;stock.report.export 的 export_mode 参数描述标注“仅仓库侧接口生效”,method description 补充“仓库侧”;版本 0.3.85 -> 0.3.86(docMeta.version),updatedAt 保持 2026-09-06", "本次任务仅同步文档,未修改任何业务代码" ], "module": "stock.report" }, { "version": "2026.09.06-order.list.waveScope", "date": "2026-09-06", "type": "updated", "summary": "order.list 订单列表 where 新增 wave_scope 波次范围虚拟筛选字段(订单表 wave_scope 字段直接过滤)", "methods": [ "order.list" ], "notes": [ "订单表(wms_order_delivery 与各仓库 current/history/dispatch/outsourced 分表)新增 wave_scope 字段:tinyint NOT NULL DEFAULT 0,取值 0=未分配波次 1=大团购 2=散单 3=小团购 4=单品单件。", "波次生成写入订单表时同步维护 wave_scope(app/service/systemMethods/order/wave.js resolveWaveScopeByWaveMeta):大团购=wave_type=1&source=0,小团购=wave_type=1&source=2,单品单件=wave_type=2&pickMode=2(策略 batch_mode=1),其余有波次为散单;移出波次重置为 0。", "order.list / 订单导出 where.wave_scope 直接按订单表 wave_scope 字段过滤(app/service/systemMethods/order/base.js buildWaveScopeFilterCondition),不再反查 wms_wave_batch 波次ID;支持单个值、数组多选与 { operator: in, value: [...] } 结构,非法值(非 0-4 整数)返回 400。", "数据库迁移:database/migrations/20260905100000-add-wave-scope-to-order-delivery.js(加列)、database/migrations/20260905130000-backfill-order-wave-scope.js(存量按口径回填,幂等)。", "列表响应 raw 行暂不输出 wave_scope 字段(ORDER_LIST_BASE_ATTRIBUTES 未包含),仅作为筛选条件使用。" ], "module": "order" }, { "version": "2026.09.05-storageTransaction-list-detail", "date": "2026-09-05", "summary": "storage.transaction.list 实现纠正:原实现错误查询 wms_stock_transaction 并按商品+单据类型聚合(合并模式),现改为查询 wms_storage_transaction 的逐条流水明细(与 stock.transaction.list 形态一致:裸 SQL 列白名单 + COUNT 分页 + 排序白名单)。聚合查询移除后,生产单仓库 160 万行聚合慢查询(约 9s)不复存在;明细查询实测 COUNT 约 0.2s。", "methods": [ "storage.transaction.list" ], "notes": [ "代码变更:systems/stock_transaction.js list() 由 ORM 聚合查询重写为 wms_storage_transaction 裸 SQL 逐条明细(列白名单含 storage_id/space_id/inventory_type/source_order_codes/before/after_intercept_locked_quantity,LEFT JOIN wms_stock_warehouse 返回 stockItem);systemMethods/storage/transaction.js 解构 whereValue 逐字段传参,warehouse_id 由服务端从 ctx.user.store_id 注入。", "行为变更:group_by_batch 参数废弃,恒返回逐条明细;原合并模式响应(quantity 合计/first_created_at/last_created_at/record_count)不再返回。", "where 支持字段:transaction_type、stock_id/stock_ids、space_id、store_id/store_ids、order_type、order_no(模糊)、batch_no、inventory_type、operator_name(模糊)、order_id、created_at(between)与 start_time/end_time;keyword 支持顶层或 where 内。", "排序白名单:created_at、quantity、stock_id、store_id、warehouse_id、space_id,非法回退 created_at DESC;pageSize 上限 200。", "前端调用方需按逐条明细结构适配(原合并模式渲染逻辑作废)。" ] }, { "version": "2026.09.04-storage.entry.quickInbound-noneed-notice", "date": "2026-09-04", "type": "enhanced", "summary": "storage.entry.quickInbound 新增参数 noNeedNotice(默认 0):0 时快捷直入完成后通知货主,1 时跳过通知,通知失败仍不影响入库主流程。", "methods": [ "storage.entry.quickInbound" ], "notes": [ "app/service/systemMethods/storage/entry.js:quickInbound 解析 data.noNeedNotice(默认 0)并透传底层 quickInbound({ id, noNeedNotice })", "app/service/systems/storage/entry.js:quickInbound(data) 解析 data.noNeedNotice(Number 归一化),事务提交后仅当 noNeedNotice !== 1 时调用 notifyEntryOrderCompleted", "methods/system.json:storage.entry.quickInbound 新增 noNeedNotice 参数说明与 description 补充;版本 0.3.83 -> 0.3.84(docMeta.version),updatedAt 保持 2026-09-04", "无数据库 schema 变更,未执行任何写库操作" ], "module": "storage.entry" }, { "version": "2026.09.04-storage.entry.commit-noneed-notice", "date": "2026-09-04", "type": "enhanced", "summary": "storage.entry.commit 新增参数 noNeedNotice(默认 0):0 时入库完成后通知货主,1 时跳过通知,通知失败仍不影响入库主流程。", "methods": [ "storage.entry.commit" ], "notes": [ "app/service/systemMethods/storage/entry.js:commit 解析 data.noNeedNotice(默认 0)并透传底层 inboundDirectLog.commit(entry_order_id, noNeedNotice)", "app/service/systems/inbound_direct_log.js:commit(entryOrderId, noNeedNotice = 0),事务提交后仅当 Number(noNeedNotice) !== 1 时调用 notifyEntryOrderCompleted(字符串 '1' 也兼容)", "methods/system.json:storage.entry.commit 新增 noNeedNotice 参数说明与 description 补充;版本 0.3.82 -> 0.3.83(docMeta.version),updatedAt 保持 2026-09-04", "无数据库 schema 变更,未执行任何写库操作" ], "module": "storage.entry" }, { "version": "2026.09.04-stock.report.export-stock-id-fix", "date": "2026-09-04", "type": "fixed", "summary": "修复 stock.report.export(含 search/searchStore/exportStore)where.stock_id 传数组时导出空白的问题:单数 stock_id 现兼容数组,避免被再包裹一层导致嵌套数组归一化为 NaN 全量过滤;同时修复默认分页上线后导出内部 search 被截断为第一页 20 条导致汇总/明细缺数据的回归。", "methods": [ "stock.report.search", "stock.report.searchStore", "stock.report.export", "stock.report.exportStore" ], "notes": [ "根因:where.stock_id 传数组时 systemMethods 层 [ stockIdRaw ] 再包一层形成嵌套数组,systems 层 Number(嵌套数组)=NaN 被全部过滤 → 汇总空 → 导出空白", "app/service/systemMethods/stock/report.js:search/searchStore/export/exportStore 四处 stock_id 解析兼容数组(Array.isArray ? 原样 : 包单元素)", "app/service/systems/storage/report.js:search 中 stockIds 归一化改用 flat() 防御嵌套;export 内部调用 search 显式传全量分页 { page: 1, pageSize: 1000000 }(新增常量 EXPORT_FULL_PAGE_SIZE),避免默认分页截断", "methods/system.json:search/searchStore 的 stock_id 描述补充“兼容数组”;export/exportStore 的 where 描述补充 stock_id/stock_ids/keyword,export 新增 export_mode 参数说明;版本 0.3.81 -> 0.3.82(docMeta.version),updatedAt 保持 2026-09-04", "验证:开发库 where.stock_id 传 20 个 ID 的 search 返回 20 行;export 同条件任务成功并产出 832KB Excel(非空白);无数据库 schema 变更,未执行任何写库操作" ], "module": "stock.report" }, { "version": "2026.09.04-stock.report.search-sort-fields", "date": "2026-09-04", "type": "enhanced", "summary": "stock.report.search 排序白名单扩充:新增 stock_id、item_code、item_name(与 begin_total、inbound_total、outbound_total、end_total 共 7 个字段),item_code/item_name 按字典序、其余按数值排序,与其他列表页面的 sort.sortField/sortOrder 用法保持一致。", "methods": [ "stock.report.search", "stock.report.searchStore", "stock.report.export", "stock.report.exportStore" ], "notes": [ "app/service/systems/storage/report.js:SORT_FIELD_WHITE_LIST 扩充为 7 字段;新增 STRING_SORT_FIELD_SET(item_code/item_name 字典序比较,localeCompare),其余字段数值比较;by_space=false 分支 baseStockRows 查询新增 sw.item_code/sw.item_name,groupedList 行携带(供排序与展示回退);by_space=true 分支 baseStorageRows LEFT JOIN wms_stock_warehouse sw ON sw.id=s.stock_id 取 MAX(sw.item_code)/MAX(sw.item_name);两分支最终 item_name/item_code 展示优先 getStockDetails,回退快照值", "app/service/systemMethods/stock/report.js:search JSDoc 同步白名单", "methods/system.json:search/searchStore/export/exportStore 的 sort 参数描述同步新白名单;版本 0.3.80 -> 0.3.81(docMeta.version),updatedAt 更新为 2026-09-04", "无数据库 schema 变更,未执行任何写库操作" ], "module": "stock.report" }, { "version": "2026.09.03-stock.report.search-default-pagination", "date": "2026-09-03", "type": "updated", "summary": "stock.report.search 分页改为默认生效:不传 data.pagination 或传非法分页时,默认按 page=1、pageSize=20 返回第一页,响应始终携带 data.pagination 分页信息(原为未传时全量返回)。分页参数同时支持顶层 page/pageSize/page_size(与其他 list 接口一致,顶层值优先)。", "methods": [ "stock.report.search" ], "notes": [ "app/service/systems/storage/report.js:paginateList 改为默认分页语义(未传/非法回退 page=1、pageSize=20,新增模块常量 DEFAULT_PAGE_SIZE=20);两个输出分支(by_space=false/true)响应 data.pagination 恒返回;200 空列表 early return 同步携带 pagination 元信息(total=0)", "app/service/systemMethods/stock/report.js:search 分页参数解析与其他 list 一致——data.pagination 优先,兼容顶层 data.page 与 data.pageSize / data.page_size(顶层值覆盖 pagination 对象);searchStore(货主侧)暂不支持分页,行为不变", "methods/system.json:pagination 参数与 data.list/data.pagination 响应描述更新为默认分页语义,data.pagination required 改为 true,新增 page/pageSize 顶层兼容参数条目;版本 0.3.78 -> 0.3.80(docMeta.version),updatedAt 保持 2026-09-03", "无数据库 schema 变更,未执行任何写库操作" ], "module": "stock.report" }, { "version": "2026.09.03-stock.report.search-pagination", "date": "2026-09-03", "type": "enhanced", "summary": "stock.report.search 新增分页支持:请求体 data.pagination = { page, pageSize } 时,先按现有排序规则排序再切片,仅对当前页行加载名称信息,响应 data.pagination 返回分页元信息;未传或非法分页保持全量返回(向后兼容)。", "methods": [ "stock.report.search" ], "notes": [ "app/service/systems/storage/report.js:新增模块函数 paginateList(归一化 page/pageSize,非法/未传返回 null 表示不分页);search 方法新增 pagination 入参,两个输出分支(by_space=false/true)均改为 sortReportList 先排序 → paginateList 切片 → 仅对 pageItems 加载名称信息(getStockDetails/Store/LocationSpace 只查当前页),分页时响应 data.pagination = { page, pageSize, total, totalPages, hasPrevious, hasNext }", "app/service/systemMethods/stock/report.js:search 透传 data.pagination(JSDoc 同步);searchStore(货主侧)暂不支持分页", "性能背景:生产实测全仓 33353 SKU 无分页约 4.6~8.8s,其中 getStockDetails 名称加载为耗时大头;分页后仅当前页触发缓存/DB 查询", "methods/system.json:stock.report.search 新增 pagination/pagination.page/pagination.pageSize 参数与 data.pagination 响应字段;版本 0.3.77 -> 0.3.78(docMeta.version),updatedAt 保持 2026-09-03", "无数据库 schema 变更,未执行任何写库操作" ], "module": "stock.report" }, { "version": "2026.09.03-workbench-barcode-removed", "date": "2026-09-03", "type": "removed", "summary": "下线工作台条码 barcode 相关字段(未使用):wms_workbench 删除 barcode 列及 idx_barcode、uk_warehouse_barcode 索引;workbench.list 移除 barcode 筛选与列表项、workbench.create/update 不再接收 barcode;workbench.checkBarcode 接口整体移除(方法、权限白名单、文档条目同步删除);order.packing.list / order.packing.detail 响应移除 workbench_barcode 字段(源列已删,恒为 null 无意义)。", "methods": [ "workbench.list", "workbench.create", "workbench.update", "workbench.getWorkbenchInfo", "workbench.checkBarcode", "order.packing.list", "order.packing.detail" ], "notes": [ "database/migrations/20260903180000-remove-barcode-from-wms-workbench.js:先删 uk_warehouse_barcode、idx_barcode 索引再删 barcode 列(幂等 describeTable/showIndex 判断),up/down 对称(down 恢复列与索引),已在开发库执行并验证(wms_workbench 现为 12 列)", "app/model/workbench.js:移除 barcode 字段定义与 idx_barcode、uk_warehouse_barcode 索引声明", "app/service/systems/workbench.js:list 移除 where.barcode 筛选;create/update 移除 barcode 处理;删除 checkBarcodeExists;formatWorkbenchTokenInfo 移除 barcode 输出", "app/service/systemMethods/workbench.js:删除 checkBarcode 方法,systemInit 免权限/免日志/免鉴权白名单移除 checkBarcode", "app/service/systems/order_packing.js:list/detail 扁平化输出移除 workbench_barcode 字段", "methods/system.json:工作台模块删除 workbench.checkBarcode 条目、list/create/update/getWorkbenchInfo 条目按无 barcode 形态重写;订单打包模块 order.packing.list / order.packing.detail description 移除 workbench_barcode 说明;版本 0.3.76 -> 0.3.77(docMeta.version),updatedAt 保持 2026-09-03", "本次未执行任何直接 DDL/写库操作;仅通过迁移文件在开发库(127.0.0.1:3307)执行 schema 变更并验证;生产库迁移需发布时按标准流程执行" ], "module": "workbench" }, { "version": "2026.09.03-workbench-member-bind", "date": "2026-09-03", "type": "enhanced", "summary": "新增接口 workbench.bindMember(免登录、免鉴权):入参用户ID(可为空,兼容非系统账号用户)+ 姓名(必填非空)+ 工作台 token,按 token 解析工作台后在 wms_workbench_member 副表新增成员行(user_id 空时仅存 user_name 姓名快照),返回新建成员行(id/workbench_id/user_id/user_name);token 无效返回失败 code=403。与已上线的 workbench.removeMember 构成成员增删闭环。", "methods": [ "workbench.bindMember" ], "notes": [ "app/service/systems/workbench.js:新增 bindWorkbenchMember(token 校验 → 姓名必填校验 → 用户ID归一化(空/非正整数处理)→ resolveWorkbenchByToken 解析工作台 → WorkbenchMember.create),复用既有 resolveWorkbenchByToken 缓存优先逻辑", "app/service/systemMethods/workbench.js:新增 bindMember 薄出口,systemInit 免登录/免权限/免日志/免鉴权声明补充 bindMember", "methods/system.json:工作台模块新增 workbench.bindMember 条目;版本 0.3.75 -> 0.3.76(docMeta.version),updatedAt 保持 2026-09-03", "无数据库 schema 变更(复用 wms_workbench_member 表),未执行任何写库操作" ], "module": "workbench" }, { "version": "2026.09.03-workbench-member-remove", "date": "2026-09-03", "type": "enhanced", "summary": "工作台新增成员/用户登录副表 wms_workbench_member(id/workbench_id/user_id/user_name/created_at/updated_at/deleted_at,user_id 允许为空以兼容非系统账号用户,user_name 存名称快照;索引 idx_workbench_id/idx_user_id)。新增接口 workbench.removeMember(免登录、免鉴权):入参成员行 ids 与工作台 token,按 token 解析工作台后仅软删除归属于该工作台的成员行,返回 removed 数量与 ids 列表;token 无效返回失败 code=403,无可移除成员返回 code=404。", "methods": [ "workbench.removeMember" ], "notes": [ "database/migrations/20260903150000-create-wms-workbench-member.js:创建 wms_workbench_member 表(幂等 showAllTables 判断)+ idx_workbench_id/idx_user_id 索引,up/down 对称,已在开发库执行并验证(user_id 列 IS_NULLABLE=YES)", "app/model/workbench_member.js:新增 WorkbenchMember 模型(paranoid 软删除),associate 声明 belongsTo Workbench(as workbench)与 belongsTo Account(as user)", "app/model/workbench.js:associate 新增 Workbench.hasMany(WorkbenchMember, as members)", "app/service/systems/workbench.js:新增 resolveWorkbenchByToken(缓存 workbench:token:{token} 优先、查库兜底并回填缓存)、normalizeWorkbenchMemberIds(数组/单值/逗号串,去重仅正整数)、removeWorkbenchMember(token 解析工作台后软删除归属成员行)", "app/service/systemMethods/workbench.js:新增 removeMember 薄出口,systemInit 免登录/免权限/免日志/免鉴权声明补充 removeMember", "methods/system.json:工作台模块新增 workbench.removeMember 条目;版本 0.3.74 -> 0.3.75(docMeta.version),updatedAt 保持 2026-09-03", "本次未执行任何直接 DDL/写库操作;仅通过迁移文件在开发库(127.0.0.1:3307)执行 schema 变更并验证表结构;生产库迁移需发布时按标准流程执行" ], "module": "workbench" }, { "version": "2026.09.03-workbench-login-code-token", "date": "2026-09-03", "type": "enhanced", "summary": "工作台登录码/令牌与绑定登录能力:wms_workbench 新增 token、login_code 两个字段(VARCHAR(64),login_code 前缀 wblc + 随机段共 64 位、全局唯一;token 随机 64 位)。新增 5 个接口:index.getWorkbenchBindCode(免登录免鉴权,参考 user.getLoginWechatCode:返回 client_code 并在缓存生成绑定码,传入 client_code 时长轮询等待绑定完成返回 token,超时/缓存失效重新生成绑定码后才返回数据)、workbench.bind(需登录需权限:校验缓存绑定码 + 工作台ID 关联绑定,成功后写入随机 token,旧 workbench:token:{token} 缓存删除)、workbench.getWorkbenchInfo(免登录免鉴权:token 查缓存 workbench:token:{token},未命中查库,无信息返回失败 code=403)、index.LoginWorkbenchByCode(免登录免鉴权:wms_workbench.login_code 入参换取 token,无匹配返回失败 code=403)、workbench.resetLoginCode(需登录需权限:随机重置 login_code)。workbench.list 返回 login_code(不返回 token),workbench.update 不受理 login_code 传入,workbench.create 自动创建 login_code。", "methods": [ "index.getWorkbenchBindCode", "index.LoginWorkbenchByCode", "workbench.bind", "workbench.getWorkbenchInfo", "workbench.resetLoginCode", "workbench.list", "workbench.create", "workbench.update" ], "notes": [ "database/migrations/20260903100000-add-login-code-token-to-wms-workbench.js:新增 login_code/token 两列(幂等 describeTable 判断)+ uk_login_code 唯一索引 + idx_token 索引,up/down 对称,已在开发库执行并验证", "app/model/workbench.js:新增 login_code/token 字段定义与 uk_login_code/idx_token 索引声明", "app/service/systems/workbench.js:新增绑定码/令牌能力(getWorkbenchBindCode/bindWorkbench/getWorkbenchInfoByToken/loginWorkbenchByCode/resetLoginCode 与配套缓存/生成/轮询辅助方法);list/detail 排除 token;create 自动生成唯一 login_code;update 白名单不含 login_code/token(传入不受理);缓存 key:workbench:bind:client:{clientCode}、workbench:bind:code:{code}(TTL 120s)、workbench:token:{token}(TTL 300s);长轮询 60s、每秒轮询缓存状态", "app/service/systemMethods/workbench.js:新增 bind/getWorkbenchInfo/resetLoginCode 薄出口,systemInit 免登录/免权限/免鉴权/免日志声明补充 getWorkbenchInfo(bind/resetLoginCode 走默认需登录需权限)", "app/service/systemMethods/index.js:新增 getWorkbenchBindCode/LoginWorkbenchByCode 薄出口,systemInit 免登录/免权限/免鉴权声明补充两方法(_noNeedLog 本就为 *)", "403 口径:/system 网关不支持方法内设置 HTTP 状态码,按现有惯例(stock/warehouse.js 同款)返回 flag=failure、code=403 业务失败", "methods/system.json:工作台模块新增 workbench.bind / workbench.getWorkbenchInfo / workbench.resetLoginCode 条目并更新 list/create/update 条目(list 响应补 login_code);基础模块新增 index.getWorkbenchBindCode / index.LoginWorkbenchByCode 条目;版本 0.3.73 -> 0.3.74(docMeta.version),updatedAt 保持 2026-09-03", "本次未执行任何直接 DDL/写库操作;仅通过迁移文件在开发库(127.0.0.1:3307)执行 schema 变更并验证列与索引;生产库迁移需发布时按标准流程执行" ], "module": "workbench" }, { "version": "2026.09.03-receiving-store-name-enrich", "date": "2026-09-03", "type": "changed", "summary": "storage.receiving.getReceivingList / getReceivingDetail 货主名称实时解析:列表每项与详情主单的 store_name 不再只依赖主表快照(约 26% 历史数据快照为空),改为优先取合约表 wms_store_warehouse.store_remask(货主备注名称,按 store_id + warehouse_id 维度),无合约或备注为空时回退 wms_store.company_name(公司全称),均无时保留主表快照(可能为空字符串)。", "methods": [ "storage.receiving.getReceivingList", "storage.receiving.getReceivingDetail" ], "notes": [ "app/service/systems/storage/receiving.js 新增 _resolveReceivingStoreNameMap(storeIds, warehouseId):批量解析货主名称映射——先查 wms_store_warehouse(store_id IN + warehouse_id)取 store_remask,再查 wms_store 取 company_name 兑底,返回 Map;口径与 afterSale._enrichListStoreNames / inventory.store_name 一致(store_remask 优先、company_name 兑底)", "app/service/systems/storage/receiving.js getReceivingList:拉取列表后批量调用 _resolveReceivingStoreNameMap,processedData 每项 store_name = 实时解析值 || 主表快照 || ''(实时值优先,兼容未绑定货主的存量数据)", "app/service/systems/storage/receiving.js getReceivingDetail:查到主单后按 receiving.store_id + receiving.warehouse_id 实时解析货主名称,解析有值时覆盖 receiving.store_name(否则保留快照)", "methods/system.json 收货单模块(module=storage_receiving):getReceivingList description 补充列表项 store_name 实时解析口径;getReceivingDetail 响应新增 receiving.store_name 字段描述;版本 0.3.72 -> 0.3.73(docMeta.version),updatedAt 保持 2026-09-03", "AI_METHOD_ROUTING.md / AI_TOOLBOX.md 本次未同步:两者仅登记服务方法名清单,不含字段级描述,无需改动", "本次仅查询验证(wms_receiving 共 1238 条、store_name 为空 319 条、store_id 为空 317 条;抽检 store_id=1000000 可经 store_remask='测试货主' 解析),未执行任何数据库写操作/DDL/Redis 操作;业务代码已通过 ESLint" ], "module": "storage.receiving" }, { "version": "2026.09.03-policy-allocate-start-time-cross-day", "date": "2026-09-03", "type": "enhanced", "summary": "货主策略与仓库级设置新增「开始自动分配时间」allocate_start_time(默认 08:00),支持跨天窗口:截单时间作为最后允许时间,开始时间晚于截单时间时截单时间视为次日;当前时间早于开始自动分配时间与超过截单时间行为一致(不自动分配快递/储位、不自动加团)。保存时开始时间等于截单时间(自动分配窗口为空)报 400。", "methods": [ "storeWarehouse.store.getPolicyConfigFields", "storeWarehouse.store.savePolicyConfig", "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "app/model/store_warehouse.js POLICY_CONFIG_FIELDS 新增 allocate_start_time(名称:开始自动分配时间,type string,default 08:00,min 00:00,max 23:59,maxLength 5);cutoff_order_time 的 min 从 12:00 放开为 00:00(支持凌晨截单/跨天窗口);cutoff_order_enabled/cutoff_order_time 描述补充跨天语义;normalizePolicyConfig 保存路径(sanitizeOnly=false)新增跨字段校验:allocate_start_time 与 cutoff_order_time 相同时抛错「policy_config.allocate_start_time 不能等于 policy_config.cutoff_order_time(自动分配窗口为空)」(400),读取路径(sanitizeOnly=true)不校验", "app/model/store.js DEFAULT_SUBJECT_CONFIG 新增 allocate_start_time: '08:00';CUTOFF_ORDER_TIME_MIN 放开为 00:00;normalizeSubjectConfig 新增 HH:mm 格式校验(非法抛「subject_config.allocate_start_time 格式必须为 HH:mm(如 08:00)」)与相等校验(显式同时提交两个时间字段且相等时抛错),旧数据读取自动补默认 08:00", "app/service/systems/setting/warehouse.js WAREHOUSE_SETTING_FIELDS 新增 allocate_start_time 字段元信息(default 08:00,min 00:00,max 23:59);cutoff_order_time 的 min 放开为 00:00;getFieldMeta 自动返回新字段元信息", "app/service/systems/delivery_order.js resolveCutoffOrderConfig 返回值新增 allocateStartTime(默认 08:00,货主-仓库级优先、仓库级兜底);新增 isAllocationWindowClosed(allocateStartTimeStr, cutoffTimeStr, nowDate):同天窗口(start=cutoff 禁止;跨天窗口(start>cutoff,截单视为次日)now in [cutoff,start) 禁止;start==cutoff 防御性全天禁止;asyncProcessOrderCreated 用 isAllocationBlocked 替换 isCutoffActive 控制自动分配快递/储位/自动加团,日志补充 allocateStartTime/cutoffTime", "methods/system.json:storeWarehouse.store.getPolicyConfigFields response 从空数组补充字段元信息说明(data[]、data[].allocate_start_time、data[].cutoff_order_time、data[].cutoff_order_enabled);storeWarehouse.store.savePolicyConfig params 补充 policy_config.cutoff_order_enabled/cutoff_order_time/allocate_start_time 字段文档与 400 错误说明,response 补充 data.policy_config.allocate_start_time;setting.warehouse.getSettings response 与 setting.warehouse.saveSettings params 补充 subject_config.allocate_start_time/subject_config.cutoff_order_time 字段文档(getFieldMeta 为通用字段元信息结构,无逐字段清单,无需改动);版本 0.3.71 -> 0.3.72(docMeta.version),updatedAt 更新为 2026-09-03", "本次仅文档同步(业务代码由 wms-dev-agent 完成:新增字段、跨天窗口判定、保存校验,并已通过 ESLint 与单元测试),未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "storeWarehouse.store" }, { "version": "2026.09.02-order-packing-list-perf-export", "date": "2026-09-02", "type": "changed", "summary": "order.packing.list 慢查询优化 + 新增导出与进度查询接口:list 查询将 findAndCountAll 拆分为 count(不带 include)+ findAll(带 include),避免 count 生成 COUNT(DISTINCT)+双 LEFT JOIN(生产实测 520ms,拆分后 count 走单表索引约 44ms);筛选/排序逻辑提取为 _buildListWhere/_buildListOrder 供列表与导出复用。新增 order.packing.export(提交异步导出任务,入参 where/sort 语义与 list 一致,warehouse_id 由服务端注入;后台生成单 Sheet Excel「打包任务列表」并上传 COS)与 order.packing.exportTaskProgress(按 task_id 查询进度与下载链接)。两接口免权限免日志免鉴权(与 order.export 口径一致,无 wms_permission 记录),需登录。", "methods": [ "order.packing.list", "order.packing.export", "order.packing.exportTaskProgress" ], "notes": [ "app/service/systems/order_packing.js:list 查询拆分——findAndCountAll 改为 count({where})(不带 include)+ findAll({where, include, limit, offset}),修复 hasMany include(videos/expresses)导致 count 生成 COUNT(DISTINCT)+双 LEFT JOIN 的慢查询(生产实测 520ms → 44ms);where 构建逻辑(status/pack_mode/waybill_code/wave_no/order_id/workbench_id/quickWhere/has_video/video_enable/时间范围)原样提取为 _buildListWhere(list/export 共用),排序提取为 _buildListOrder(list/export 共用);新增 createBusinessError 与 exportPackTask", "app/service/systems/order_packing.js exportPackTask:复用 _buildListWhere/_buildListOrder 并强制 warehouse_id(缺失抛 400 缺少仓库上下文);主表全量分页拉取(每页 500,无行数上限);批量关联工作台(wms_workbench)、视频(wms_pack_task_video,含 camera 名称)、运单(wms_order_express,按 order_id 分批 100);ExcelJS 流式单 Sheet「打包任务列表」18 列(任务ID/订单ID/波次号/运单号/关联运单号/打包模式/任务状态/打包数量/商品总数量/商品种类数/工作台/作业人员/开始打包时间/结束打包时间/创建时间/视频状态/录像可用/备注),经 systems.upload.uploadFile 上传(key=exports/pack_task/{warehouseId}/{timestamp}_{token}.xlsx,mimetype xlsx,category=document),结果含 filename/fileKey/url/cdnUrl/cosUrl/current_count/total_count/sheet_count", "app/service/systemMethods/order/packing.js:新增 export/exportTaskProgress 与任务缓存辅助方法(generateExportTaskId/normalizeExportTaskId/getExportTaskCacheKey/setExportTaskProgress/getExportTaskProgress):缓存键前缀 packing_export_task_,Redis TTL 1800 秒;export 提交后 setImmediate 异步执行并逐阶段回写进度(submitted(0) → running(5) → 数据拉取 10~30(未命中数据时 85)→ 关联拉取 30~55 → Excel 55~90 → 上传 92 → success(100),失败 failed + error);exportTaskProgress 入参兼容 task_id/taskId,download_url 从 result.url/cdnUrl/cosUrl/fileKey 兜底取,未命中返回 status=not_found(正常响应非报错)", "systemInit 权限声明:_noNeedRight/_noNeedLog/_noNeedAuth 由 'list,get' 扩展为 'list,get,export,exportTaskProgress'(导出异步任务免权限免日志免鉴权,与 order.export 口径一致);_noNeedLogin 不变", "methods/system.json order.packing 模块:新增 order.packing.export 与 order.packing.exportTaskProgress 两个 method 条目(追加于 order.packing.list 之后),版本 0.3.70 -> 0.3.71(docMeta.version),updatedAt 更新为 2026-09-02", "本次未修改 wms_pack_task 表结构,未执行数据库写操作/Redis 操作;未运行测试" ], "module": "order.packing" }, { "version": "2026.09.01-report-delivery-notify-group-routing-fix", "date": "2026-09-01", "type": "changed", "summary": "修复「补货预警报表定时投递群路由」缺陷(G1):生产上 3 条投递计划发出 5 条消息——报表文件消息被投递到投递计划未配置的「货主默认站内信群」(如 store-1000156 的收货群、store-1000159 的对接群被误发)。根因:deliverByChannel 未按计划配置解析群目标,按 group_type='store' 取任意货主默认群(与 notify_group_ids 配置无关)。修复:新增 resolveNotifyGroups 统一解析(过滤 is_blocked=1、软删、仓库维度一致)供投递与通知两路共用;配置了 notify_group_ids 的计划文件消息仅逐群投递到配置群,全部不可达(不存在/已删除/被屏蔽/仓库不一致)时抛错进入 failed 退避重试、不再回退未配置群;未配置通知群的历史计划保持旧行为回退货主默认站内信群;sendNotifyIfConfigured 复用 resolveNotifyGroups 删除重复查询逻辑。响应结构不变,仅群路由语义变更。", "methods": [ "report.deliveryPlan.save", "report.deliveryPlan.list", "report.deliveryPlan.copy" ], "notes": [ "app/service/systems/reportDelivery.js 新增 resolveNotifyGroups({plan, warehouseId}):notify_group_ids → 有效群行统一解析(is_blocked=0、软删自动排除、warehouse_id 维度一致),投递(deliverByChannel)与文本通知(sendNotifyIfConfigured)两路共用,保证口径一致;未配置群或全部被过滤时返回空数组,InboxGroup 模型不可用时抛错", "app/service/systems/reportDelivery.js deliverByChannel 群路由改造:计划配置 notify_group_ids 时报表文件消息只逐群投递到配置群,不再投递任意「货主默认群」(旧逻辑为 group_type='store' 按 id ASC 取最早一条,与计划配置无关);配置了群但全部不可达(不存在/已删除/被屏蔽/仓库不一致)时抛「货主 配置的通知群不可达…无法投递」进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s),不再静默回退到未配置群;未配置通知群的历史计划保持旧行为回退到货主默认站内信群(group_type='store',取最早一条)兼容存量计划", "app/service/systems/reportDelivery.js sendNotifyIfConfigured 复用 resolveNotifyGroups 解析通知群,删除重复查询逻辑,投递与通知共用同一解析口径", "methods/system.json 通用报表模块(module=report):report.deliveryPlan.save description 与 params/response 的 notify_group_ids 描述补充群路由口径(文件消息仅投递计划配置群、未配置回退货主默认站内信群、配置群全部不可达失败退避);report.deliveryPlan.list description 与 response 的 notify_group_ids 描述同步;report.deliveryPlan.copy description 补充复制计划通知群置空后投递回退目标货主默认站内信群语义;请求/响应结构、headers、errors 均不变;版本 0.3.69 -> 0.3.70(docMeta.version),updatedAt 保持 2026-09-01", "docs/report-config-guide.md 第 5 节补充文件消息投递目标/群路由口径(配置群定向投递、未配置回退默认群、全部不可达失败退避),第 5.1.2 节 notify_group_ids 补充同时作为文件消息投递目标的说明", "测试回归:140 测试全过(业务代码由开发任务完成并测试通过);本次仅文档同步,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.09.01-returnReceived.export", "date": "2026-09-01", "type": "added", "summary": "退回收到模块新增导出与进度查询接口:returnReceived.export(提交异步导出任务,入参 where/sort 语义与 returnReceived.list 一致,warehouse_id 由服务端注入 ctx.user.store_id;后台生成单 Sheet Excel「退回收到登记列表」并上传 COS)与 returnReceived.exportTaskProgress(按 task_id 查询任务进度与下载链接,未命中返回 status=not_found)。任务缓存 Redis TTL 30 分钟,全量分页拉取 500/页;两接口默认走 API 权限校验(需 wms_permission 存在类型为 api 的记录),需登录。", "methods": [ "returnReceived.export", "returnReceived.exportTaskProgress" ], "notes": [ "app/service/systemMethods/returnReceived.js 新增 export/exportTaskProgress 与任务缓存辅助方法(generateExportTaskId/normalizeExportTaskId/getExportTaskCacheKey/setExportTaskProgress/getExportTaskProgress):缓存键前缀 return_received_export_task_,Redis TTL 1800 秒(30 分钟);export 提交后 setImmediate 异步执行并逐阶段回写进度(submitted(0) → running(5) → 数据拉取 10~55(未命中数据时 85)→ Excel 生成 60 → success(100),失败 failed + error);exportTaskProgress 入参兼容 task_id/taskId,download_url 从 result.url/cdnUrl/cosUrl/fileKey 兜底取;task_id 为空或缓存未命中返回 status=not_found(正常响应非报错)", "systemInit 权限声明:_noNeedRight 仅 detail(export/exportTaskProgress 未加入免权限列表,默认走 API 权限校验,需 wms_permission 存在 returnReceived.export / returnReceived.exportTaskProgress 类型为 api 的记录);_noNeedLogin 为空(两接口均需登录,isNeedAuth=true、isNeedLogin=true);_noNeedLog 为空(记录操作日志);_noNeedAuth 为空(走仓库有效期检查)", "app/service/systems/return_received.js 新增 exportList/_generateExportExcel/_resolveStoreRemarkMap:复用 _buildListWhere/_buildListOrder(与 list 语义一致)并强制 warehouse_id=注入值(缺失抛 400 缺少仓库上下文);主表全量分页拉取(每页 500,无行数上限);货主备注批量解析(wms_store_warehouse.store_remask,失败降级空字符串不阻断导出)", "导出 Excel:单 Sheet「退回收到登记列表」,列=运单号/扫描日期/扫描人员/是否原单退回(是/否)/订单ID/货主备注/备注/登记时间/更新时间;ExcelJS 流式写入临时文件后经 systems.upload.uploadFile 上传(key=exports/return_received/{warehouseId}/{timestamp}_{token}.xlsx,mimetype xlsx,category=document),结果含 filename/fileKey/url/cdnUrl/cosUrl/current_count/total_count", "methods/system.json 退回收到模块(module=returnReceived)新增 returnReceived.export 与 returnReceived.exportTaskProgress 两个 method 条目(追加于 returnReceived.delete 之后),版本 0.3.68 -> 0.3.69(docMeta.version),updatedAt 保持 2026-09-01", "AI_METHOD_ROUTING.md 同步:app/service/systemMethods/returnReceived.js 方法计数 (5) -> (7),方法清单补充 export/exportTaskProgress;AI_TOOLBOX.md 未涉及 returnReceived 清单,无需改动", "本次仅文档同步(业务代码由开发任务完成),未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "returnReceived" }, { "version": "2026.09.01-intercept-locked-quantity-rework", "date": "2026-09-01", "type": "changed", "summary": "库内拦截确认时库存不再归还可用、改移入拦截锁定字段的改造落地:wms_storage_transaction 新增 before_intercept_locked_quantity / after_intercept_locked_quantity 两个拦截锁定快照字段(migration 20260901000200,尚未上线);wms_storage 可用数量统一口径 available_quantity = quantity - locked_quantity - intercept_locked_quantity;拦截相关流水新增 order_type=INTERCEPT_LOCK(拦截锁迁移/实物返还并拦截锁定)与 INTERCEPT_UNLOCK(拦截锁释放回落可用);stock.warehouse.search(with_stock)与 stock.warehouse.getStockDetail 按库位合并明细响应新增 intercept_locked_quantity 字段(向后兼容);order.recheckOrder.confirmIntercept / interceptScan 确认拦截时以拦截模式释放储位分配(interceptMode=true,库存不归还可用、移入拦截锁定)。", "methods": [ "stock.warehouse.getStockDetail", "stock.warehouse.search", "order.recheckOrder.confirmIntercept", "order.recheckOrder.interceptScan" ], "notes": [ "database/migrations/20260901000200-add-intercept-locked-snapshots-to-wms-storage-transaction.js:describeTable 幂等检测,新增 before_intercept_locked_quantity / after_intercept_locked_quantity(INT NULL,comment 变更前/后拦截锁定数量,与既有 before/after_locked_quantity 风格一致、可空无默认值、由写入逻辑维护);该 migration 尚未上线", "app/model/storage_transaction.js:在 after_locked_quantity 之后新增 before_intercept_locked_quantity / after_intercept_locked_quantity 字段定义(INTEGER(12)/allowNull=true,comment 变更前/变更后拦截锁定数量)", "app/service/systems/storage/index.js updateQuantity:新增 options.interceptLockedChange 变化量参数,统一重算 available_quantity = quantity - locked_quantity - intercept_locked_quantity,并校验拦截锁定数量非负、不超过库存数量、与锁定数量之和不超过库存数量;新增 interceptLockQuantity(作业锁迁移为拦截锁:locked -q、intercept +q、available 不变)/ interceptReceiveQuantity(实物返还并拦截锁定:quantity +q、intercept +q、available 不变)/ interceptUnlockQuantity(拦截锁释放回落可用:intercept -q、available +q)三个专用方法", "app/service/systems/order_storage_allocation.js cancelAllocateStorage:新增 interceptMode 开关——拦截确认模式下 pending 行执行作业锁迁移(locked -q、intercept +q、available 不变)、fin 行实物返还并拦截锁定(quantity +q、intercept +q、available 不变),流水 order_type 记为 INTERCEPT_LOCK 并记录 order_id 与 before/after_intercept_locked_quantity 快照;普通取消模式行为不变;新增 releaseInterceptLocksByOrderIds:按 INTERCEPT_LOCK 与 INTERCEPT_UNLOCK 流水按 (storage_id, order_id) 汇总净拦截量,净量大于 0 时逐库存行调用 interceptUnlockQuantity 释放拦截锁(intercept -q、available +q),写入 order_type=INTERCEPT_UNLOCK 流水并记录快照,重复调用幂等(净量归零后不再释放)", "app/service/systemMethods/order/recheckOrder.js confirmIntercept/interceptScan:释放储位分配改走 cancelAllocateStorage({ order_ids, interceptMode: true }),确认拦截时库存不再归还可用而是移入拦截锁定字段 intercept_locked_quantity;运单标记、订单状态、订单锁、工单、日志等其余口径不变", "app/service/systemMethods/order/pendingOrder.js runBatchUninterceptTask:解除拦截不操作拦截锁定数量字段(业务上拦截→取消拦截均不动库存口径,拦截锁定数量仅在库内拦截确定时占用,回落由后续特定入库处理链路接管)", "app/service/systems/return_received.js create:退货登记不释放拦截锁定库存(拦截锁回落由退货货物后续入库处理接管)", "app/service/systems/stock_store.js search(with_stock)与 getStockDetail:storage 查询 attributes 显式加入 intercept_locked_quantity,按库位合并模式累加拦截锁定数量并按统一口径重算 available_quantity;合并明细响应新增 intercept_locked_quantity(向后兼容,默认 0)", "methods/system.json 同步:stock.warehouse.getStockDetail response storageList 描述补充 intercept_locked_quantity 与 available_quantity 统一口径;stock.warehouse.search response storage 字段的库位分组汇总(children_grouped)与批次明细(children_batch)字段清单均新增 intercept_locked_quantity、available_quantity 口径说明更新为 quantity - locked_quantity - intercept_locked_quantity;order.recheckOrder.confirmIntercept / interceptScan 描述更新为拦截模式释放储位分配(库存不归还可用、移入拦截锁定);版本 0.3.67 -> 0.3.68(docMeta.version),updatedAt 保持 2026-09-01", "核查结论:methods/qimen.json 与 methods/openapi.json 无涉及本改造的接口(openapi.json 仅 order.cancel 描述中出现 intercept_status 字面量,与本改造无关),未同步;stock.transaction.list / stock.transaction.storeList / stock.transaction.export 使用显式 SQL 列白名单(不含拦截锁定快照字段),响应不受影响,文档无需同步;storage.transaction.list(group_by_batch=true)明细模式因模型整行序列化隐含新增 before/after_intercept_locked_quantity,但其 response 文档为对象结构(更新脚本要求数组格式,与既有处理一致),本次未改写,其 list_detail 示例本非全量字段清单", "本次仅文档同步,未修改 app/ 与 database/ 下任何代码与 migration,未执行数据库/Redis 操作,未运行测试" ], "module": "storage" }, { "version": "2026.09.01-receiving-detail-stock-id", "date": "2026-09-01", "type": "changed", "summary": "storage.receiving.getReceivingDetail 与 deleteDetail 明细项新增 stock_id 字段(与 system_product_id 语义一致,向后兼容)", "methods": [ "storage.receiving.getReceivingDetail", "storage.receiving.deleteDetail" ], "notes": [ "app/service/systems/storage/receiving.js getReceivingDetail:明细组装时新增 stock_id: detailBase.system_product_id ?? null(商品/库存ID,语义与 system_product_id 一致,缺失时为 null),system_product_id 保留向后兼容", "app/service/systems/storage/receiving.js deleteDetail:删除后剩余明细 formattedDetails 每项同步新增 stock_id = detailData.system_product_id ?? null,与 getReceivingDetail 明细项字段保持一致", "methods/system.json 收货单模块(module=storage_receiving):getReceivingDetail 响应新增 receiving.details.*.stock_id(number|null,语义与 system_product_id 一致,取 system_product_id、缺失为 null,system_product_id 保留向后兼容);deleteDetail 响应 data.details 描述补充 stock_id 说明;deleteDetail 按更新脚本规范补齐 response 各字段 required、errors 的 description 归一化为 message(语义不变);版本 0.3.66 -> 0.3.67(docMeta.version),updatedAt 保持 2026-09-01", "AI_METHOD_ROUTING.md / AI_TOOLBOX.md 本次未同步:两者仅登记服务方法名清单,不含 getReceivingDetail/deleteDetail 的字段级描述,无需改动", "本次仅文档同步(业务代码由 wms-dev-agent 完成),未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "storage.receiving" }, { "version": "2026.09.01-wms-storage-intercept-locked-quantity", "date": "2026-09-01", "type": "changed", "summary": "wms_storage 库存表新增「拦截锁定数量」字段 intercept_locked_quantity(INTEGER(12) NOT NULL DEFAULT 0,comment 拦截锁定数量),用于拦截场景数量锁定、与 locked_quantity 区分;纯数据模型变更:无接口入参/错误码/鉴权变化,现有写入点由模型默认值 0 兜底;明细模式接口响应因模型整行序列化隐含新增该字段(当前恒为 0,暂无业务读写)。", "methods": [ "storage.inventory.listByStockId" ], "notes": [ "database/migrations/20260901000000-add-intercept-locked-quantity-to-wms-storage.js:describeTable 幂等检测,缺省时 ALTER TABLE wms_storage ADD COLUMN intercept_locked_quantity INT(12) NOT NULL DEFAULT 0 COMMENT '拦截锁定数量';down 删除该字段", "app/model/storage.js:在 locked_quantity 之后新增 intercept_locked_quantity 字段定义(INTEGER(12)/allowNull=false/defaultValue=0/comment 拦截锁定数量);现有写入点(quickPutaway/directPutaway/commit 等)不显式传该字段,依赖模型默认值 0 兜底", "methods/system.json storage.inventory.listByStockId:data.list 明细行字段清单补充 intercept_locked_quantity(拦截锁定数量,默认 0);group_by_space=true 汇总行与 params/errors/isNeedAuth/isNeedLogin 均不变;版本 0.3.65 -> 0.3.66(docMeta.version),updatedAt 更新为 2026-09-01", "storage.inventory.list(group_by_batch=true 明细模式)响应同样隐含新增该字段,但其 response 文档为对象结构(脚本校验要求数组格式),本次未改写;其 list_detail 示例本非全量字段清单(未列 is_enabled/delete_at/supplier_id 等),不构成文档缺口", "storage.inventory.export(明细/汇总导出)、stock.warehouse.getStockDetail、库存报表 stockFlow 等查询均使用显式 attributes 白名单,不受该字段影响,文档无需同步", "本次仅文档同步,未修改 app/ 与 database/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "storage" }, { "version": "2026.08.31-report-stockflow-export-columns-restructure", "date": "2026-08-31", "type": "changed", "summary": "stockFlow 报表(库存变化以及补货报表)导出列结构调整:静态字段清单由 16 个顶层字段收敛为 9 组列(顺序固定:item_name 产品名称 / barcode 条码 / item_code 外部编码 / daily 每日出入库(children ck/rk) / pending_occupy 待处理订单占用数 / available 可用库存 / ck_total 7日总出库数量 / suggest 推荐采购量 / warn 是否触发预警);item_code 复用为外部编码列(key 不变、label 由「商品编码」改为「外部编码」,取值优先 wms_stock_store.item_code 按 stock_id 关联、回落 wms_stock_warehouse.item_code);新增 pending_occupy(取 wms_stock_warehouse.locked_quantity,非 wms_storage 聚合口径);移除 stock_id/rk_total/total/pending/locked/ck_avg/rk_avg/stock_days 共 8 个旧列不再导出(rk_total/日均/预计可售天数等仍内部计算供 suggest/warn 判定与复核,不进入导出列)。", "methods": [ "report.definition.typeList" ], "notes": [ "app/service/systems/report/queries/sevenDayStockFlow.js:FIELDS 静态字段清单由 16 个顶层字段收敛为 9 组列(item_name/barcode/item_code(asText=true)/daily(children ck/rk)/pending_occupy/available/ck_total/suggest(computed=true)/warn(computed=true),顺序固定),item_code 复用旧「商品编码」key、label 改为「外部编码」;头部口径注释同步重写(外部编码优先 wms_stock_store.item_code 按 stock_id 关联 wms_stock_warehouse.id、同 stock_id 多条按 id 升序取第一条非空、stock_id 为空不参与匹配,未匹配回落 wms_stock_warehouse.item_code,再无留空;pending_occupy 取 wms_stock_warehouse.locked_quantity;出入库仍用 wms_stock_transaction 变更数量 quantity;内部仍计算 rk_total/ck_avg/rk_avg/stock_days 供 suggest/warn 判定与复核,不进入导出列)", "app/service/systems/report/queries/index.js:注册表 stockFlow 类型 description 已随查询器口径更新为「…每日出/入库、外部编码、待处理订单占用数、可用库存、7日总出库数量、推荐采购量与是否触发预警」;fields 动态取自查询器 fields 常量,无需单独维护", "methods/system.json 通用报表模块(module=report):report.definition.typeList response 的 fields 描述由「含 16 个字段」更新为「共 9 组列,顺序固定」,fields[].label 示例由「商品编码」更新为「外部编码」;description/params/headers/errors/isNeedAuth/isNeedLogin 不变;版本 0.3.64 -> 0.3.65(docMeta.version),updatedAt 保持 2026-08-31", "docs/report-config-guide.md:第 2 节 stockFlow 全量字段清单表由 16 个顶层字段改写为 9 组列(新顺序/新 label/新 key,附 pending_occupy 口径与外部编码 fallback 口径、8 个旧列移除说明);第 2.1 节口径与假设按查询器头部注释重写(外部编码口径、待处理订单占用数口径、内部计算字段不导出);第 3 节 asText 适用对象改为「条码、外部编码」;第 6 节保存示例 fields 更新为 9 组列、勾选说明由「16 个顶层字段」改为「9 组列」;第 7.3 节 typeList 响应示例字段顺序与 label 同步(外部编码/推荐采购量/是否触发预警)", "AI_METHOD_ROUTING.md 本次未同步(report 能力清单不含 stockFlow 字段列表,仅指向 docs/report-config-guide.md,无需改动)", "本次仅文档同步(业务代码由开发完成),未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试;测试数据保留不清理" ], "module": "report" }, { "version": "2026.08.31-report-generate-store-dimension-file-key", "date": "2026-08-31", "type": "changed", "summary": "修复「货主限制不符」缺陷(报表文件 key 与投递/通知幂等键补充货主维度隔离):systems/report.generate 上传目录由 exports/report/{report_id} 改为 exports/report/{report_id}/store-{store_id}(storeId 有效时)/ warehouse-{warehouse_id}(storeId 缺省且 warehouseId 有效时)/ common(两者均缺省,手动导出兼容兜底),避免不同货主的报表文件在 COS 上互相覆盖;reportDelivery 投递幂等键由 report:{report_definition_id}:{biz_date}:{time_point} 改为 report:{store_id}:{report_definition_id}:{biz_date}:{time_point}、文本通知幂等键 report:notify:... 同步加入 store_id 维度,并在 processOne 增加 store_id/report_definition_id 强校验(任一无效拒绝生成跨货主报表)。", "methods": [ "report.generate" ], "notes": [ "app/service/systems/report.js generate:新增 ownerSegment 计算——normalizedStoreId>0 时 store-{storeId},否则 normalizedWarehouseId>0 时 warehouse-{warehouseId},否则 common;dir 由 exports/report/{reportId} 改为 exports/report/{reportId}/{ownerSegment}(经 excel.generateAndUpload 追加 {YYYYMMDD} 日期目录与文件名),JSDoc 同步更新隔离语义", "app/service/systems/reportDelivery.js deliverByChannel:投递幂等键 idempotentKey 加入 store_id 维度(report:{store_id}:{report_definition_id}:{biz_date}:{time_point}),ext_id 幂等复用口径不变,不同货主的投递消息互不复用/串扰;sendNotifyIfConfigured:文本通知幂等键 report:notify:{store_id}:{report_definition_id}:{biz_date}:{time_point} 同步加入 store_id 维度;processOne:新增 store_id/report_definition_id 强校验(任一无效抛「投递计划维度非法(…),拒绝生成报表」),uniqueWhere 与 generate/投递调用统一使用归一化后的 normalizedStoreId/normalizedReportId", "methods/system.json 通用报表模块(module=report):report.generate description 补充上传目录按(报表定义 + 货主/仓库)隔离口径与 common 兜底、免权限说明移除已下线的 meta(仅 generate/generateTaskProgress 免权限);store_id/storeId 参数描述补货主维度隔离语义;response result 描述补 fileKey 含货主/仓库隔离目录说明;params/headers/errors/isNeedAuth/isNeedLogin 口径不变;版本 0.3.63 -> 0.3.64(docMeta.version),updatedAt 保持 2026-08-31", "docs/report-config-guide.md:第 4 节上传目录由 exports/report// 更新为按货主/仓库维度隔离的三级目录格式(store-{store_id} / warehouse-{warehouse_id} / common,含 excel.generateAndUpload 追加的 {YYYYMMDD} 日期目录);第 5 节补充投递/通知幂等键格式(含 store_id 维度)与 processOne 货主维度强校验说明", "本次仅文档同步(业务代码由开发完成),未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试;测试数据保留不清理" ], "module": "report" }, { "version": "2026.08.31-storeWarehouse.store.openAccount-remask", "date": "2026-08-31", "type": "updated", "summary": "优化 storeWarehouse.store.openAccount:未传 store_remask(或传空)时默认用公司全称填充 wms_store_warehouse.store_remask(截断 50 字符),保证货主名称在列表/导出中始终有值", "methods": [ "storeWarehouse.store.openAccount" ], "notes": [ "app/service/systems/store_warehouse.js openAccount:签约关系创建时 store_remask 兜底为 store.company_name 前 50 字符(仅当未传 store_remask 或传空时),与项目“货主名称 store_remask 优先、无备注回退 company_name”口径一致", "methods/system.json 货主-仓库签约模块(module=storeWarehouse.store):openAccount 的 store_remask 参数描述补充默认值说明,版本 0.3.62 -> 0.3.63(docMeta.version),updatedAt 保持 2026-08-31", "本次为行为变更:新开户且未传 store_remask 时签约表 store_remask 将写入公司全称;已存在的历史开户数据不受影响(如需回填需另行处理)", "未执行数据库/Redis 操作,未运行测试;测试数据保留不清理" ], "module": "storeWarehouse" }, { "version": "2026.08.31-report-meta-removed", "date": "2026-08-31", "type": "removed", "summary": "移除 report.meta(免权限只读列元数据接口):接口下线,前端获取注册字段/窗口参数改由 report.definition.typeList 提供、某报表定义勾选字段经 report.definition.list 的 fields 数组获取。", "methods": [ "report.meta" ], "notes": [ "app/service/systemMethods/report.js:删除 meta 方法(含 JSDoc);_noNeedRight/_noNeedAuth 清单移除 meta(保留 generate,generateTaskProgress),免权限口径收窄", "app/service/systems/report.js:删除 getMeta 方法(仅被 systemMethods report.meta 调用),getDefinition/resolveTypeEntry 仍被 generate/buildWorkbookSheets/定义管理复用不受影响", "app/service/systemMethods/report/definition.js、app/service/systems/report/queries/index.js、app/service/systems/report/queries/sevenDayStockFlow.js:注释中 report.meta 引用同步清理(改指 report.definition.typeList)", "methods/system.json 通用报表模块(module=report):删除 report.meta 条目,版本 0.3.61 -> 0.3.62(docMeta.version),updatedAt 保持 2026-08-31", "AI_METHOD_ROUTING.md:删除 report.meta 表格行,更新 report.generate 鉴权描述(不再提 meta),新增接口移除说明并登记变更版本", "docs/report-config-guide.md:第 7 节标题与 7.1-7.4 移除 report.meta 相关内容(响应示例/字段 selected 标记/调用步骤),保留 report.definition.typeList 并补充替代说明(窗口参数取 typeList、勾选字段取 definition.list 的 fields)", "test/report_method_layer.cjs:删除 systemMethods.report.meta 套件;test/report_systems_engine.cjs:删除 systems/report.getMeta 套件并更新文件头覆盖说明;test/scripts/verify_report_delivery_gateway.cjs:移除 report.meta 冒烟调用(generateTaskProgress 保留)", "权限说明:report.meta 原为免权限(isNeedAuth=false、无 wms_permission 记录),移除后无需任何权限回收操作", "本次为破坏性变更:前端若仍调用 report.meta 将得到 method 不存在错误,需同步改为 report.definition.typeList + report.definition.list;未执行数据库/Redis 操作,未运行测试,测试数据保留不清理" ], "module": "report" }, { "version": "2026.08.31-storeWarehouse.store.export", "date": "2026-08-31", "type": "added", "summary": "新增 storeWarehouse.store.export(提交货主签约列表异步导出任务)与 storeWarehouse.store.exportTaskProgress(按 task_id 查询导出进度与下载链接):筛选条件与 storeWarehouse.store.list 语义一致(keyword/counterparty_id/store_id/auth_status/use_status/warehouse_use_status/id),page/page_size 忽略全量导出;后台生成 26 列中文表头 Excel 并上传 COS。", "methods": [ "storeWarehouse.store.export", "storeWarehouse.store.exportTaskProgress" ], "notes": [ "app/service/systems/store_warehouse.js:抽取 buildListForStoreWhere(data, currentSubject)(仓库在 warehouse_id 方、对方货主在 store_id 方,支持 id/contract_id/relation_id、counterparty_id/store_id、auth_status、use_status/warehouse_use_status、keyword 筛选),listForStore 改用它(行为不变);新增 exportListForStore(data):复用 buildListForStoreWhere + getRelationIncludes 全量查询(updated_at/id 倒序,不翻页、无行数上限),奇门配置经 getQimenConfigMap 映射 has_qimen_config,每行经 serializeRelation 序列化并输出 needs_my_confirm;ExcelJS 流式写入 26 列中文表头(签约关系ID/货主ID/货主名称/仓库ID/仓库名称/对方主体ID/对方主体名称/对方主体角色/备注名/当前视角启用状态/货主侧启用状态/仓库侧启用状态/签约状态/签约是否有效/剩余有效天数/面单余额/锁定面单余额/授权开始时间/授权结束时间/实际结束时间/申请时间/审核时间/申请原因/审核评语/是否已配置奇门/是否需要我确认,角色/启用状态/有效性/奇门/需确认为中文展示),经 systems.upload.uploadFile 上传(key=export/store_relation/{storeId}/{timestamp}_{filename}.xlsx,mimetype xlsx,category=document)并 uploadSuccessNotify 通知,返回 filename/fileKey/url/cdnUrl/cosUrl/total_count", "app/service/systemMethods/storeWarehouse/store.js:新增 export(提交异步任务,task_id 前缀 store_relation_list_export_,setImmediate 异步执行并逐阶段回写进度:submitted→running(10)→success(100)/failed+error;失败 error 记录 message)与 exportTaskProgress(入参兼容 task_id/taskId,download_url 从 result.url/cdnUrl/cosUrl/fileKey 兜底取,task_id 缺失或缓存未命中返回 status=not_found 正常响应);generateExportTaskId 增加 options.base 自定义基础前缀(默认 print_qty_log 不变,现有 exportPrintQuantityLogs/exportStorePrintQuantityLogs 调用不受影响);systemInit 免权限声明:_noNeedRight/_noNeedAuth 加入 export,exportTaskProgress(异步任务模式,与 order.export 口径一致,无 wms_permission 记录),_noNeedLogin 不含(两接口均需登录,isNeedAuth=false、isNeedLogin=true)", "methods/system.json 货主-仓库签约模块(module=storeWarehouse.store):新增 storeWarehouse.store.export 与 storeWarehouse.store.exportTaskProgress 两个 method 条目(追加于 createUser 之后),版本 0.3.60 -> 0.3.61(docMeta.version),updatedAt 保持 2026-08-31", "AI_METHOD_ROUTING.md 本次未同步(storeWarehouse.store 相关行未覆盖导出能力,待后续补)", "权限说明:export/exportTaskProgress 免权限(无 wms_permission 记录),仅登录可用;本次未扩任何角色授权,不执行权限同步 apply", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未执行数据库/Redis 操作,未运行测试;测试数据保留不清理" ], "module": "storeWarehouse" }, { "version": "2026.08.31-workbench-queryOrder-item-packing-requirements", "date": "2026-08-31", "type": "enhanced", "summary": "workbench.business(queryOrder/query) 响应 items 每项新增 packing_requirements 字段(stock 打包要求,来自 wms_stock_warehouse.packing_requirements,经 getStockDetails 返回,未命中/异常时归一化为空字符串),纯增量字段,不破坏既有调用方。", "methods": [ "workbench.business" ], "notes": [ "app/service/systems/workbench.js _queryOrder 步骤4 items 组装:新增 1 行 packing_requirements: String(stock.packing_requirements || '').trim(),stock 未命中(stockMap 兜底 {})或 getStockDetails 异常时取值为空字符串、不抛错;与 items 既有 sku_property/stock_unit 取值风格一致", "methods/system.json workbench.business queryOrder/query 响应结构:items 字段 description 末尾追加 packing_requirements 字段说明(打包要求,来自 stock,未命中/异常时为空字符串)", "纯增量字段,params/headers/errors/权限口径(isNeedAuth=false、isNeedLogin=false)均不变,不破坏既有调用方", "methods/system.json 文档版本 0.3.59 -> 0.3.60(docMeta.version),updatedAt 更新为 2026-08-31", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "workbench" }, { "version": "2026.08.30-report-delivery-plan-copy-target-store-status", "date": "2026-08-30", "type": "changed", "summary": "report.deliveryPlan.copy 目标货主校验语义调整(放宽):目标货主有效性由仅 status=1(正常)放宽为 status 为 1 或 2(正常/审核中)均有效;其余状态(0/3 等)或已软删货主仍计入 skipped(reason「货主不存在或状态异常」文案不变);源计划校验、store_ids 校验、同源跳过、同报表定义计划跳过、通知配置不复制、enabled 原样复制等其余口径均不变。", "methods": [ "report.deliveryPlan.copy" ], "notes": [ "app/service/systems/reportDelivery.js copyPlan:目标货主存在性校验由 where: { id: { [Op.in]: candidates }, status: 1 } 调整为 status: { [Op.in]: [1, 2] }(1=正常、2=审核中均有效),软删自动排除不变;未命中者仍计入 skipped(reason「货主不存在或状态异常」文案不变);方法注释同步更新为 status 为 1 或 2(正常/审核中)均有效口径", "app/service/systemMethods/report/deliveryPlan.js copy:包装层无变化(解构 id/store_ids 透传 copyPlan),无需改动", "methods/system.json 通用报表模块(module=report):report.deliveryPlan.copy description 目标货主校验口径由「状态正常(status=1)」改为「status 为 1 或 2(正常/审核中)均有效,其余状态或已软删自动排除」;response skipped.reason 枚举「货主不存在或状态异常」name 同步更新为 status∈{1,2} 口径;params/headers/errors/权限口径不变;版本 0.3.58 -> 0.3.59(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md:copy 相关行未提货主状态口径(仅概括「货主不存在或状态异常跳过」,与放宽后语义一致),无需改动", "权限口径不变:report.deliveryPlan.copy 与 save/list 相同(isNeedAuth=true、isNeedLogin=true),未执行权限变更、未扩大任何角色授权", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-report-delivery-plan-copy", "date": "2026-08-30", "type": "added", "summary": "新增 report.deliveryPlan.copy 批量复制接口:传入源计划ID id 与目标货主ID数组 store_ids(非空正整数数组,自动去重,兼容 storeIds 驼峰),快速复制源计划到其他货主;目标货主已存在同 report_definition_id 计划时跳过不覆盖;notify_group_ids/notify_member_ids 通知配置不复制(新计划置空);enabled 原样复制(保持复制语义),其余字段(report_definition_id/schedule_times/channel/late_grace_minutes/name/remark/notify_template)原样复制;事务批量创建,唯一键冲突单条降级 skipped。", "methods": [ "report.deliveryPlan.copy" ], "notes": [ "app/service/systemMethods/report/deliveryPlan.js copy:解构 id/store_ids(兼容 storeIds 驼峰,优先取驼峰形式,与 save 的 reportId 兼容口径一致),透传 systems.reportDelivery.copyPlan({ id, storeIds }),统一 success 包装 data={ created, skipped };systemInit 未声明免权限(_noNeedLogin/_noNeedRight/_noNeedAuth 均为空),与 save/list 同权限口径(需登录需鉴权,仅通配符角色或已授权角色可用)", "app/service/systems/reportDelivery.js copyPlan:id 必须为正整数(否则抛「计划ID无效」),findByPk 软删排除、不存在抛「计划不存在」;store_ids 经 parseJsonArray 解析为非空数组且元素为正整数并自动去重(空/非数组抛「目标货主 store_ids 必须为非空数组」,非法元素抛「目标货主 store_ids 含非法货主ID(需正整数): 」);与源计划 store_id 相同的目标计入 skipped(与源计划货主相同);wms_store 校验存在且 status=1(否则 skipped:货主不存在或状态异常);目标已存在同 report_definition_id 计划(软删排除)跳过(已存在同报表定义计划);新建 payload 中 notify_group_ids/notify_member_ids 置 null(通知配置不复制)、enabled 原样复制,其余字段原样复制;事务批量创建,并发撞 uk_store_report_definition 唯一索引时单条降级 skipped、不中断其余创建", "methods/system.json 通用报表模块(module=report):新增 report.deliveryPlan.copy 条目(description/headers/params id+store_ids+storeIds/response created+skipped(reason 枚举 与源计划货主相同/货主不存在或状态异常/已存在同报表定义计划)/errors);isNeedAuth=true、isNeedLogin=true;版本 0.3.57 -> 0.3.58(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md 5.1 节路由表新增 report.deliveryPlan.copy 行(service 路径 app/service/systemMethods/report/deliveryPlan.js、函数 copy、需登录、需授权),并新增批量复制特性说明;变更记录列表顶部追加本版本", "权限口径不变:report.deliveryPlan.copy 与 save/list 相同(isNeedAuth=true、isNeedLogin=true),未执行权限变更、未扩大任何角色授权", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-inbox-group-members-groupids-array", "date": "2026-08-30", "type": "changed", "summary": "inbox.group.members 入参由单个 groupId 改为数组 groupIds(必填,非空且每个元素为正整数,对应 wms_inbox_group.id),一次查询多个群的成员并在消息层多群聚合去重(多群共享同一 500 条聚合池);破坏性入参变更(移除 groupId),调用方需同步升级。", "methods": [ "inbox.group.members" ], "notes": [ "app/service/systemMethods/inbox.js groupMembers:解构 groupIds 透传给 systems 层;warehouseId 仍从 ctx.user?.store_id 服务端注入(Number 化),不信任前端传值;keyword/limit 透传不变", "app/service/systems/inbox/group.js members:groupIds 校验为非空数组且每个元素为数字或可解析数字字符串的正整数(否则抛「groupIds 无效」);InboxGroup.findAll({ where: { id: { [Op.in]: groupIds }, warehouse_id } }) 批量校验群存在(软删自动排除),无匹配抛「群不存在或无权限操作」;聚合所有群外部 group_id(去重、剔空),全为空返回 { list: [] };消息按 group_id IN + warehouse_id 拉取(id 倒序、limit 500 共享聚合池、user_id 排除 NULL/空串、软删排除);按 user_id 去重取最新 user_name;keyword 对聚合结果做 user_name/user_id 小写包含过滤;截断到 limit(默认20上限100)", "methods/system.json 站内信分组(module=inbox):inbox.group.members 描述改为多群聚合语义;params 删除 groupId、新增 groupIds(array,必填,非空数组,元素为正整数,对应 wms_inbox_group.id);errors 400 由「群ID无效 / warehouseId 无效」改为「groupIds 无效 / warehouseId 无效」;headers/响应结构/权限口径不变(warehouseId 仍服务端注入、567 权限);版本 0.3.56 -> 0.3.57(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md 5.2 节:members 底层实现描述由「groupId 必填」改为「groupIds 必填(数组,多群聚合)」;变更记录列表新增本版本", "权限不变:仍需 567(inbox.group.members,isNeedAuth=true、isNeedLogin=true),未执行权限变更", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "inbox" }, { "version": "2026.08.30-inbox-group-quicklist-dual-dim-filter", "date": "2026-08-30", "type": "changed", "summary": "inbox.group.quickList 改为双维度可选过滤:store_id(货主维度,对应 wms_inbox_group.store_id 列)与 warehouse_id(仓库维度,对应 wms_inbox_group.warehouse_id 列)均可选,可单独传、可同时传(AND),也可都不传(返回所有仓库/货主的群);本记录修正并取代 2026.08.30-inbox-group-quicklist-store-id(该版将 store_id 错误映射为 warehouse_id 列);新增 store_id 列索引迁移(待发布时执行)。", "methods": [ "inbox.group.quickList" ], "notes": [ "取代关系:本记录修正并取代 2026.08.30-inbox-group-quicklist-store-id 的口径——上一版将入参 store_id 错误映射为 wms_inbox_group.warehouse_id(仓库维度),本版明确 store_id=货主维度(对应 store_id 列)、warehouse_id=仓库维度(对应 warehouse_id 列),两维度均可选可组合,均不传时返回所有仓库/货主的群", "app/service/systemMethods/inbox.js groupQuickList:解构透传 data.store_id(storeId)与 data.warehouse_id(warehouseId)给 systems 层,不再从 ctx.user 注入任何仓库值;其余入参 keyword/groupType/limit 不变", "app/service/systems/inbox/group.js quickList:双列可选过滤——store_id(货主维度,String 化 trim 非空时 Number 化并校验 Number.isInteger 且 >0,否则抛「store_id 无效」)设置 where.store_id;warehouse_id(仓库维度,同样校验否则抛「warehouse_id 无效」)设置 where.warehouse_id;两者可同时传(AND)也可都不传(不加对应过滤条件);keyword 模糊匹配 group_name/group_id、groupType 筛选、limit 默认20上限100、created_at 倒序、软删自动排除均不变", "database/migrations/20260830150000-add-store-id-index-to-wms-inbox-group.js:为 wms_inbox_group.store_id 新增索引 idx_store_id(幂等 up/down,尚未执行,待发布时执行);warehouse_id 维度已由 uk_warehouse_group_id(warehouse_id, group_id) 前导列覆盖,双条件 AND 由两索引组合命中", "methods/system.json 站内信分组(module=inbox):inbox.group.quickList 描述改为双维度可选过滤口径;params 修正 store_id(货主维度,对应 store_id 列)并新增 warehouse_id(可选正整数,对应 warehouse_id 列);errors 400 由「store_id 无效」改为「store_id 无效 / warehouse_id 无效」;headers 保持登录凭证口径(不从中解析仓库上下文);版本 0.3.55 -> 0.3.56(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md 5.2 节:quickList 底层实现与仓库口径改为双维度口径(store_id=货主维度 / warehouse_id=仓库维度,均可选可组合、不传返回全部、不再从登录上下文注入),变更记录列表新增本版本并标注修正/取代上一版", "权限不变:仍需 566(inbox.group.quickList,isNeedAuth=true、isNeedLogin=true),未执行权限变更", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "inbox" }, { "version": "2026.08.30-inbox-group-quicklist-store-id", "date": "2026-08-30", "type": "changed", "summary": "inbox.group.quickList 新增可选入参 store_id(对应 wms_inbox_group.warehouse_id):传入时仅返回该仓库的群,不传或为空时返回所有仓库的群;旧口径「warehouseId 由服务端从登录上下文自动注入、不信任前端传值」作废,改为透传前端入参 store_id。", "methods": [ "inbox.group.quickList" ], "notes": [ "app/service/systemMethods/inbox.js groupQuickList:不再从 ctx.user.store_id 自动注入 warehouseId,改为解构透传 data.store_id(storeId)给 systems 层;其余入参 keyword/groupType/limit 不变", "app/service/systems/inbox/group.js quickList:storeId 可选(String(data.storeId ?? '').trim() 非空时 Number 化并校验 Number.isInteger 且 >0,否则抛「store_id 无效」);传入时 where.warehouse_id = storeId 过滤,不传或为空时不加 warehouse_id 过滤、返回所有仓库的群;keyword 模糊匹配 group_name/group_id、groupType 筛选、limit 默认20上限100、created_at 倒序、软删自动排除均不变", "methods/system.json 站内信分组(module=inbox):inbox.group.quickList 描述删除「warehouseId 由服务端从登录上下文自动注入」,补 store_id 口径(可选正整数,对应 warehouse_id,不传返回全部);params 新增 store_id(number|string,可选);errors 400 由「warehouseId 无效」改为「store_id 无效」;headers 描述改为登录凭证口径(不再从中解析 warehouseId 仓库上下文);版本 0.3.54 -> 0.3.55(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md 5.2 节:quickList 底层实现补 store_id 口径;仓库口径拆分为「quickList 透传前端 store_id(不再服务端注入)/ members 仍从 ctx.user.store_id 服务端注入」", "权限不变:仍需 566(inbox.group.quickList,isNeedAuth=true、isNeedLogin=true),未执行权限变更", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "inbox" }, { "version": "2026.08.30-report-delivery-plan-name-field", "date": "2026-08-30", "type": "enhanced", "summary": "投递计划新增计划名称 name 字段:report.deliveryPlan.save 新增可选入参 name(string|null;未传不覆盖,null/空串/全空白归一化为 null 显式清空,非空 trim 后 ≤100 超长报错),save 成功响应与 report.deliveryPlan.list 列表项新增 name 字段(缺省空串);name 仅展示字段,不参与幂等/关联逻辑。", "methods": [ "report.deliveryPlan.save", "report.deliveryPlan.list" ], "notes": [ "app/service/systems/reportDelivery.js:新增 normalizePlanName(value)(undefined=未传不覆盖返回 undefined;null/空串/全空白返回 null 显式清空;非空 trim 且 ≤PLAN_NAME_MAX_LENGTH(100),超长抛「计划名称 name 长度不能超过 100 字符」);savePlan 仅在 name !== undefined 时规范化并写入 payload.name,更新时不误清空", "app/service/systems/reportDelivery.js planToView:响应视图新增 name: String(plan.name || '')(缺省空串),save 成功响应与 list 列表项均带该字段", "app/service/systemMethods/report/deliveryPlan.js save:解构透传 name(仅入参存在时附加 saveArgs.name,保持旧调用形状与既有回归断言一致)", "wms_report_delivery_plan 新增 name 列(STRING(100) allowNull,comment「计划名称(前端展示用,缺省时可用报表名称兜底)」;迁移 20260830130000-add-name-to-wms-report-delivery-plan 已完成);name 仅展示字段,不参与 store_id+report_definition_id 幂等/关联逻辑", "methods/system.json 通用报表模块:report.deliveryPlan.save params 新增 name(string|null)、response 新增 name(缺省 '')、errors 新增「计划名称 name 长度不能超过 100 字符」;report.deliveryPlan.list response children 新增 name;版本 0.3.53 -> 0.3.54(docMeta.version),updatedAt 保持 2026-08-30", "docs/report-config-guide.md 第 5 节投递计划补 name 字段口径与保存示例;AI_METHOD_ROUTING.md 5.1 节补 name 变更条目与最新 changes 版本", "权限口径不变:report.deliveryPlan.save/list 仍 isNeedAuth=true(未声明免权限),仅执行 npm run permission:sync:system-api -- --dry-run 预演(不 apply、不扩任何角色授权)", "本次仅文档同步,未修改 app/ 下业务代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-report-type-list-merge-into-definition", "date": "2026-08-30", "type": "changed", "summary": "枚举接口并入 definition:report.type.list → report.definition.typeList。免权限只读的类型注册清单查询由独立模块 report/type.js 并入 report/definition.js(typeList 方法,systemInit 声明 _noNeedRight/_noNeedAuth/_noNeedLog='typeList',仅要求登录);同模块 save/list/delete 仍需授权。", "methods": [ "report.definition.typeList", "report.type.list" ], "notes": [ "app/service/systemMethods/report/type.js 已删除;app/service/systemMethods/report/definition.js 新增 typeList(data) 方法(无必填入参,忽略请求体),返回 success('ok', { list }),list 由 systems/report.js listRegisteredTypes() 提供(QUERIES.describe() 注册表全量描述,当前仅 stockFlow)", "权限口径:definition.js systemInit 声明 _noNeedRight/_noNeedAuth/_noNeedLog='typeList'(免权限/免鉴权/免审计日志,仅要求登录);同模块 save/list/delete 未声明免权限,仍需授权(isNeedAuth=true),同一模块内权限口径差异已在 method description 中注明", "methods/system.json 通用报表模块:删除 report.type.list,新增 report.definition.typeList(isNeedAuth=false、isNeedLogin=true、无入参;响应 { list: [{key,title,description,window:{dayCount,cutoverHour},fields:[{key,label,type,computed?,asText?,children?}]}] },字段口径与原 report.type.list 一致);版本 0.3.52 -> 0.3.53(docMeta.version),updatedAt 保持 2026-08-30", "docs/report-config-guide.md:report.type.list 全部替换为 report.definition.typeList(第 2/7 节标题、字段口径说明、请求/响应示例与设计器接口链),实现链由 report/type.js 改为 report/definition.js;AI_METHOD_ROUTING.md report 能力清单更新(report.definition.typeList → definition.js typeList)", "权限仅执行 npm run permission:sync:system-api -- --dry-run 预演(不 apply、不扩任何角色授权)", "本次仅文档同步(含文档脚本 update-api-doc.cjs 的 deleteMethods 能力扩展与缩进检测修正),未修改 app/ 下业务代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-report-definition-model-refactor", "date": "2026-08-30", "type": "changed", "summary": "报表定义模型重构:code→id 关联、type/fields 极简配置、注册表 stockFlow、新增 report.type.list。破坏性变更:report.generate/report.meta/report.deliveryPlan.* 的 report_code 入参全部替换为 report_id(=报表定义ID,兼容 reportId 驼峰),前端需同步改 report_id。", "methods": [ "report.generate", "report.meta", "report.type.list", "report.definition.save", "report.definition.list", "report.definition.delete", "report.deliveryPlan.save", "report.deliveryPlan.list", "report.deliveryLog.list" ], "notes": [ "模型重构(app/model/report_definition.js):移除 code/scope/description 与 output_config/source_config/sheet_config 三段 JSON 配置列,改为 name/type/file_name/fields/is_enabled/remark + 主键 id(唯一性由 id 承担,删除 uk_code);投递计划/记录表外键由 report_code 改为 report_definition_id,投递记录新增 report_name 名称快照", "app/service/systemMethods/report.js:generate/meta 入参 report_code 改为 report_id(reportId 驼峰优先);meta 响应由 report_code/name/scope/query/window/fields 改为 report_id/name/type/file_name/window/fields(fields 新增 selected 勾选标记与 asText 标记);generateTaskProgress 不变", "新增 app/service/systemMethods/report/type.js:report.type.list 免权限只读(systemInit 声明 _noNeedRight/_noNeedAuth/_noNeedLog 含 list,仅要求登录),返回注册类型清单 [{key,title,description,window:{dayCount,cutoverHour},fields:[{key,label,type,computed,asText,children}]}];当前仅注册 stockFlow(标题「库存变化以及补货报表」)", "app/service/systemMethods/report/definition.js:save 入参 {id?,name,type,file_name/fileName,fields,is_enabled,remark}(type 必须命中注册表、fields 必须为该类型注册字段子集,非法 key 报可读错误并列出可用字段;新增必填 type/file_name/fields);list where 改 name/type/is_enabled,sort 白名单 id/name/type/is_enabled/created_at/updated_at;delete 入参 id,引用拦截按 report_definition_id 统计启用中计划", "app/service/systems/report.js:新增 listRegisteredTypes/resolveTypeEntry/validateTypeFields,saveDefinition/listDefinitions/deleteDefinition 按 id 重写;渲染由 app/lib/report/render.js renderSheetByType 按类型硬编码字段规格完成(asText 由类型字段规格硬编码自动应用,string 字段 asText=true 时落地文本单元格),sheet_config 已删除", "app/service/systems/reportDelivery.js:savePlan/listPlans/listLogs 关联键由 report_code 改为 report_definition_id,listLogs 响应新增 report_name 快照;幂等键与唯一索引 uk_store_report_definition 同步改为 report_definition_id", "methods/system.json 通用报表模块:report.generate/report.meta/report.definition.save/report.definition.list/report.definition.delete/report.deliveryPlan.save/report.deliveryPlan.list/report.deliveryLog.list 8 个 method 按新形态重写,新增 report.type.list(report.generateTaskProgress 不受影响保持原样);版本 0.3.51 -> 0.3.52(docMeta.version),updatedAt 保持 2026-08-30", "docs/report-config-guide.md 整体改写(注册类型 stockFlow 标题/描述/16 字段表、report.type.list 用法、definition 保存示例 fileName+type+fields、plan 用 report_id、删除 sheet_config/asText 旧说明并按新渲染规则改写);AI_METHOD_ROUTING.md report 能力清单刷新", "权限口径:report.type.list 免权限(isNeedAuth=false);其余 report.* 沿用既有授权口径(管理类接口 isNeedAuth=true);仅执行 npm run permission:sync:system-api -- --dry-run 预演,未 apply、未扩任何角色授权", "本次仅文档同步,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-order-export-create-channel-column", "date": "2026-08-30", "type": "enhanced", "summary": "订单导出(order.export)waybill/item 两种导出模式在「平台」列之后新增导出列「来源」(字段 create_channel,中文取值:手工单/接口/奇门/出库转单);该列已自动纳入导出表头白名单 ORDER_EXPORT_ALL_COLUMN_HEADERS(waybill/item 两模式列头并集),export_columns/exportColumns 入参已支持传「来源」,不传或空数组时默认输出全部列。", "methods": [ "order.export" ], "notes": [ "app/service/systems/order_export.js:ORDER_EXPORT_COLUMNS(waybill 模式)与 ORDER_EXPORT_ITEM_COLUMNS(item 模式)均在「平台」(sys_platform_name)之后新增 { header: '来源', key: 'create_channel', width: 12 }", "ORDER_EXPORT_ALL_COLUMN_HEADERS 为 waybill/item 两模式列头并集(Object.freeze(new Set(...))),「来源」在列配置登记后自动可用:export_columns/exportColumns 传「来源」合法(校验不区分导出模式),不传或空数组时输出全部列(含来源)", "取值翻译:app/service/systemMethods/order/base.js CREATE_CHANNEL_LABELS = { MANUAL: '手工单', API: '接口', QM: '奇门', STOCKOUT: '出库转单' },formatCreateChannelLabel 未命中映射时原样返回 create_channel 原文", "methods/system.json:order.export 的 export_columns/exportColumns 参数描述中枚举由 51 个更新为 52 个(在「平台」之后插入「来源」),并补充来源列取值、位置(平台列之后)与两种模式均输出的说明;order.exportTaskProgress 无导出列枚举内容,无需改动", "methods/system.json 版本 0.3.50 -> 0.3.51(docMeta.version),updatedAt 2026-08-29 -> 2026-08-30", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "order.index" }, { "version": "2026.08.29-waybill-warehouse-waybillCode-array-exact-match", "date": "2026-08-29", "type": "enhanced", "summary": "运单列表与导出接口的 where.waybillCode 支持字符串数组精确匹配:waybill.warehouse.list / waybill.warehouse.export 的 where.waybillCode 由「仅字符串模糊搜索」扩展为「字符串模糊搜索(LIKE '%值%',向后兼容)/ 字符串数组精确匹配(Op.in,元素自动 trim 并过滤空值,空数组或全空值不加该筛选条件)」,修复此前数组入参被逗号拼接后做 LIKE 导致搜索无结果的问题。", "methods": [ "waybill.warehouse.list", "waybill.warehouse.export" ], "notes": [ "app/service/systems/waybill.js list() 第 226-235 行:where.waybillCode 为数组时先逐元素 String 化并 trim、过滤空值,非空则 waybill_code = { [Op.in]: waybillCodeList } 精确匹配;字符串时保持 waybill_code = { [Op.like]: '%trim%', } 模糊匹配(向后兼容)", "export 的筛选条件构建(第 767-776 行)与 list 逻辑一致:数组 Op.in 精确匹配、字符串 Op.like 模糊匹配", "修复前行为:数组入参会被逗号拼接后进入 LIKE 分支,导致搜索无结果;修复后数组元素 trim 并过滤空值,空数组/全空值不加 waybill_code 筛选条件", "methods/system.json:waybill.warehouse.list 与 waybill.warehouse.export 的 where.waybillCode 参数 type 由 string 更新为 string|string[],description 补充字符串模糊搜索与字符串数组精确匹配(元素 trim、过滤空值)规则", "methods/system.json 版本 0.3.49 -> 0.3.50(docMeta.version),updatedAt 保持 2026-08-29", "本次仅文档同步,业务代码已由开发侧修复(app/service/systems/waybill.js),未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "waybill.warehouse" }, { "version": "2026.08.29-order-packing-quickWhere-short-kw-guard", "date": "2026-08-29", "type": "enhanced", "summary": "order.packing.list 的 where.quickWhere 运单号降级模糊新增关键词长度校验:精确未命中后仅当 trim 后关键词长度 ≥ 4(QUICK_WHERE_WAYBILL_FUZZY_MIN_LENGTH)才降级 LIKE '%kw%' 模糊查询;长度 < 4 的短词(含单字符)禁止降级、运单号解析直接返回空结果(避免 %短词% 误命中海量历史单号);波次号模糊逻辑不变。", "methods": [ "order.packing.list" ], "notes": [ "app/service/systems/order_packing.js 第 12 行模块常量 QUICK_WHERE_WAYBILL_FUZZY_MIN_LENGTH = 4:注释说明短于该长度的输入(如单字符 \"7\")没有模糊搜索意义且 %短词% 极易误命中海量历史单号(实测 \"7\" 可命中 24149 行),因此禁止短词降级进入 %kw% 模糊分支", "list() 的 where.quickWhere 分支:波次号直接 LIKE '%kw%' 模糊不变;运单号先按「完整单号等值 + 剥离分段后缀主体等值 + 主体前缀 LIKE '主体-%'」精确集合查询 wms_order_express,第 206 行条件 expressRecords.length === 0 && kw.length >= QUICK_WHERE_WAYBILL_FUZZY_MIN_LENGTH 才降级 waybill_code LIKE '%kw%';短词(长度 < 4)不进入模糊分支,运单号解析保持空结果(仅保留波次号模糊条件)", "list() JSDoc 第 64 行 where.quickWhere 描述已同步:精确未命中且关键词长度≥4 时才降级模糊,短词禁止降级避免误命中", "methods/system.json:order.packing.list 的 where.quickWhere 参数描述补充「精确未命中且关键词长度 ≥ 4 才降级 %kw% 模糊;长度 < 4 短词不降级、直接返回空;波次号模糊不变」规则", "methods/system.json 版本 0.3.48 -> 0.3.49(docMeta.version),updatedAt 保持 2026-08-29", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "order.packing" }, { "version": "2026.08.29-wave-batchCancel-pick-status-guard", "date": "2026-08-29", "type": "enhanced", "summary": "取消波次增加拣货状态校验:order.wave.batchCancel 提交前新增两道业务校验(code 400)——波次内存在拣货中或拣货完成(pick_status 为 padding/fin)的订单、或波次状态已进入拣货及后续环节(wms_wave_batch.wave_status >= 3)时禁止取消波次;runBatchCancelTask 异步兜底命中上述条件跳过该波次并继续处理其余波次;order.wave.batchCancelTaskProgress 任务结果新增 skipped_wave_ids / skipped_wave_count / skipped_waves 字段。", "methods": [ "order.wave.batchCancel", "order.wave.batchCancelTaskProgress" ], "notes": [ "app/service/systemMethods/order/wave.js batchCancel():活动拣货任务校验后新增两道 400 校验——① getOrderModel('pendingOrder', warehouseId) 查询波次内 pick_status IN ('padding','fin') 的订单,命中返回「波次内存在已拣货完成或拣货中的订单,禁止取消波次」(附 wave_ids 与最多前 20 个 order_ids);② 查询 wms_wave_batch 中 wave_status >= 3 的波次,命中返回「波次已进入拣货或后续环节,禁止取消波次」(附 wave_ids)", "runBatchCancelTask():目标波次查询新增 wave_status 列;逐波次处理时先校验 wave_status >= 3(跳过明细 reason=wave_status_blocked,附 wave_status),再在事务内校验波次内 pick_status IN ('padding','fin') 的订单(reason=picked_orders_exist,附 picked_order_count),命中则回滚事务、跳过该波次并继续处理其余波次;无目标波次时 result 返回空 skipped_wave_ids 数组与 skipped_wave_count=0", "任务结果:success 与 failed 终态的 result 均新增 skipped_wave_ids(被跳过波次 ID 列表)、skipped_wave_count(数量)、skipped_waves(明细数组,字段 wave_id/wave_no/reason/wave_status/picked_order_count,其中 wave_status 仅 reason=wave_status_blocked、picked_order_count 仅 reason=picked_orders_exist)", "methods/system.json:order.wave.batchCancel 的 description 补充校验规则说明、errors 新增两条 400 描述;order.wave.batchCancelTaskProgress 的 description 与 response 补充 skipped_wave_ids / skipped_wave_count / skipped_waves 字段说明(含 children 明细),并同步更新 result 字段描述(补充 ids/affected_wave_ids/affected_order_count/skipped_* 等字段枚举)", "methods/system.json 版本 0.3.47 -> 0.3.48(docMeta.version),updatedAt 保持 2026-08-29", "本次仅文档同步,业务代码改动已完成(git diff app/service/systemMethods/order/wave.js),未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "order.wave" }, { "version": "2026.08.29-order-packing-waybill-code-match", "date": "2026-08-29", "type": "enhanced", "summary": "打包获取订单与订单快捷搜索的运单号匹配规则收敛:order.packing.list 的 where.waybill_code 由默认「%值%」模糊匹配改为「完整单号等值 + 剥离 -1-1- 分段后缀后主体单号等值 + 主体前缀 LIKE '主体-%'」精确匹配(不再支持部分单号模糊,无匹配返回空);quickWhere 运单号解析先按上述等值集合精确匹配、精确未命中才降级为 %kw% 模糊查询,波次号模糊逻辑不变;order.deliveryOrder.quickSearch 运单号条件同步扩展为「完整等值 + 主体等值 + 主体前缀 LIKE」,运单号不再落入模糊分支,发货单号/原始平台订单号模糊匹配不变(平台交易单号 pay_no 仅回显不参与匹配,修正文档过期描述)。", "methods": [ "order.packing.list", "order.deliveryOrder.quickSearch" ], "notes": [ "新增公共工具 app/lib/waybill_code.js:stripWaybillSegmentSuffix 剥离运单号尾部一单多件包裹序号分段(正则 /(?:-\\d+){2,}-?$/,如 JDX057941864338-1-1- → JDX057941864338,无分段原样返回);escapeLikeWildcards 转义 like 通配符 % _ \\,保证主体前缀匹配的主体部分被等值比较", "app/service/systems/order_packing.js list():where.waybill_code 通过 wms_order_express 解析 order_id(wms_pack_task.waybill_code 通常为空),条件集合为 [waybill_code=完整单号, waybill_code=剥离后缀后主体, waybill_code LIKE '转义主体-%'] 的 OR 组合,命中后按 order_id IN 过滤,无命中强制空结果(queryWhere.id=-1);不再使用 like '%值%' 模糊匹配", "order_packing.js list() 的 where.quickWhere:波次号直接 LIKE '%kw%' 模糊不变;运单号解析先按上述精确集合查询,expressRecords 为空才降级为 waybill_code LIKE '%kw%'(兼容输入部分单号场景);团购按 wave_no、散单按 order_id 查询链路不变", "app/service/systemMethods/order/deliveryOrder.js quickSearch():express 表 OR 条件中运单号扩展为 [完整等值, 主体等值, 主体前缀 LIKE '主体-%'],运单号不再落入 %kw% 模糊分支;delivery_order_code / source_order_codes 仍为 LIKE '%kw%' 模糊匹配;pay_no 不在搜索条件中(仅第三步订单详情输出回显),原文档「平台交易单号 pay_no(模糊)」为过期描述已按实现修正", "methods/system.json:order.packing.list 的 where.waybill_code 描述由「运单号(模糊匹配)」改为完整单号/剥离分段后缀主体/主体前缀三种匹配规则说明,quickWhere 描述补充「先精确后降级模糊」优先级;order.deliveryOrder.quickSearch 的 description 与 keyword 参数描述同步修正(express 表匹配口径、pay_no 仅回显);quickSearch 条目补充空 headers 数组以符合文档校验结构", "methods/system.json 版本 0.3.46 -> 0.3.47(docMeta.version),updatedAt 保持 2026-08-29", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "order.packing" }, { "version": "2026.08.29-return-unpack-max-record-minutes", "date": "2026-08-29", "type": "enhanced", "summary": "仓库设置新增「拆包最大录制时长」配置 return_unpack_max_record_minutes(分钟,默认 5,min 1):returnUnpack.submit 提交确认时,结束时间超过 开始时间+配置上限 时自动截断为上限时间点", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings", "returnUnpack.submit" ], "notes": [ "app/service/systems/setting/warehouse.js WAREHOUSE_SETTING_FIELDS 新增 return_unpack_max_record_minutes(名称:拆包最大录制时长(分钟),type integer,非必填,默认 5,min 1,描述:超过上限时提交的结束时间自动截断为开始时间+上限),与 single_order_pack_max_minutes(默认 3)/ group_order_pack_max_minutes(默认 40)并列;getFieldMeta 自动返回该字段元信息", "app/model/store.js DEFAULT_SUBJECT_CONFIG 增加 return_unpack_max_record_minutes: 5;normalizeSubjectConfig 非法值(非正整数)抛「subject_config.return_unpack_max_record_minutes 必须是大于 0 的整数」,空值回退默认 5", "app/service/systems/return_unpack.js submit() 新增私有方法 _resolveSubmitEndTime:候选 end_time 超过 start_time + 配置上限分钟时截断为上限时间点并记录 info 日志;配置读取 ctx.service.systems.deliveryOrder.getStoreSubjectConfig,配置非法/读取失败/start_time 缺失时不约束;其余行为不变(completed 终态、回写 is_back=1、货主群通知等均不变)", "methods/system.json:setting.warehouse.getSettings 响应与 setting.warehouse.saveSettings 入参新增 subject_config.return_unpack_max_record_minutes 字段文档;returnUnpack.submit description 与响应 record 补充「结束时间超过仓库配置的拆包最大录制时长上限时自动截断为开始时间+上限」语义;getFieldMeta 为通用字段元信息结构,无逐字段清单,无需改动", "向后兼容:新增字段可选,不影响既有仓库设置读写;本次仅文档同步,业务代码由 wms-dev-agent 完成", "methods/system.json 版本 0.3.45 -> 0.3.46(docMeta.version),updatedAt 保持 2026-08-29" ], "module": "returnUnpack" }, { "version": "2026.08.29-returnUnpack.export", "date": "2026-08-29", "type": "enhanced", "summary": "新增退回拆包导出与进度查询接口:returnUnpack.export(提交异步导出任务,入参 where/sort 语义与 returnUnpack.list 一致,warehouse_id 由服务端注入 ctx.user.store_id;后台生成双 Sheet Excel:Sheet1 正常退回运单号列表、Sheet2 明细表并上传)与 returnUnpack.exportTaskProgress(按 task_id 查询任务进度与下载链接,未命中返回 status=not_found)。任务缓存 Redis TTL 30 分钟,状态口径 submitted→running→数据拉取(10~30)→明细拉取(30~50)→Excel(55~90)→上传(92)→success(100),失败 failed+error。两接口免权限免日志口径与 order.export 一致(isNeedAuth=false、isNeedLogin=true)。", "methods": [ "returnUnpack.export", "returnUnpack.exportTaskProgress" ], "notes": [ "app/service/systemMethods/returnUnpack.js 新增 export/exportTaskProgress 与任务缓存辅助方法(generateExportTaskId/normalizeExportTaskId/setExportTaskProgress/getExportTaskProgress):缓存键前缀 return_unpack_export_task_,Redis TTL 1800 秒(30 分钟);export 提交后 setImmediate 异步执行并逐阶段回写进度;exportTaskProgress 入参兼容 task_id/taskId,download_url 从 result.url/cdnUrl/cosUrl/fileKey 兜底取(代码中同时兼容 cndUrl 拼写);task_id 为空或缓存未命中返回 status=not_found(正常响应非报错)", "systemInit 免权限声明:_noNeedRight/_noNeedAuth/_noNeedLog 均含 export,exportTaskProgress(异步任务模式,与 order.export 口径一致,无 wms_permission 记录);_noNeedLogin 不含(两接口均需登录,isNeedAuth=false、isNeedLogin=true)", "app/service/systems/return_unpack.js 新增 exportUnpack:复用 _buildListWhere/_buildListOrder(与 list 语义一致)并强制 warehouse_id=注入值;主表全量分页拉取(每页 500,无行数上限),明细按 unpack_id 分批(每批 100)拉取;货主名批量映射 wms_store.company_name、快递类型映射 wms_order_express.logistics_name(各自独立 try/catch,解析失败降级为空字符串不阻断导出)", "双 Sheet 结构:Sheet1「正常退回运单号列表」列=货主/快递号/商品类数/商品总数/记录人员/记录日期/开始时间/结束时间/是否原单(是/否)/快递类型/自定义店铺/平台单号;Sheet2「明细表」列=货主/快递号/商品名称/商品编码/条码/颜色/规格/数量/是否残次(是/否)/记录人员ID/记录日期/备注/是否原单(是/否)/快递类型/自定义店铺/平台单号;颜色取自明细 product_snapshot.sku_property 中「颜色:xxx」片段(兜底 spec 字段),无颜色信息为空;是否原单按 order_express_id 有值输出是/否;是否残次按 product_status=damaged 输出是/否", "导出上传:ExcelJS 流式写入临时文件后经 systems.upload.uploadFile 上传(key=exports/return_unpack/{warehouseId}/{timestamp}_{token}.xlsx,mimetype xlsx,category=document),结果含 filename/url/fileKey/cdnUrl/cosUrl/current_count/total_count/total_details/sheet_count=2;Sheet1 不加 status 过滤(如需只导特定状态由调用方传 where.status)", "methods/system.json 退回拆包模块(module=returnUnpack)新增 returnUnpack.export 与 returnUnpack.exportTaskProgress 两个 method 条目(追加于 returnUnpack.delete 之后),版本 0.3.44 -> 0.3.45(docMeta.version),updatedAt 保持 2026-08-29", "权限说明:export/exportTaskProgress 免权限(无 wms_permission 记录),仅登录可用;本次仅文档、未扩任何角色授权,不执行权限同步 apply", "仅文档变更,未改任何业务代码、表结构,未执行数据库/Redis 操作" ], "module": "returnUnpack" }, { "version": "2026.08.29-report-channel-normalize-doc-audit", "date": "2026-08-29", "type": "docs", "summary": "渠道默认值归一化 inbox + 文档一致性校对:全量核对「通用报表模块」全部 report.* method(generate/generateTaskProgress/meta/deliveryPlan.save/list/deliveryLog.list/definition.save/list/delete)与当前实现(app/service/systemMethods/report.js 及 report/ 子目录、app/service/systems/report.js、app/service/systems/reportDelivery.js、模型 report_definition/report_delivery_plan/report_delivery_log、迁移 20260829170000),仅发现 report.deliveryPlan.list / report.deliveryLog.list 响应 channel 字段存在过期描述(wecom/inbox/link),已修正为仅 inbox;其余 method 的 params/response/errors 均与实现一致,无接口行为变化。", "methods": [ "report.deliveryPlan.list", "report.deliveryLog.list" ], "notes": [ "迁移 database/migrations/20260829170000-normalize-report-channel-to-inbox.js:wms_report_delivery_plan / wms_report_delivery_log 的 channel 默认值 wecom → inbox、comment 收敛,存量 channel IN (wecom,link) 统一 UPDATE 为 inbox;模型同步(app/model/report_delivery_plan.js、app/model/report_delivery_log.js defaultValue: inbox)", "代码核对:app/service/systems/reportDelivery.js 的 DELIVERY_CHANNELS 收敛为 [inbox]、DEFAULT_CHANNEL=inbox;deliverByChannel 对非 inbox 渠道记录 warn 日志后按 inbox 兜底投递(不抛错);inbox 推送失败(success=false 或 push_status=3)立即经 ctx.service.inbox.message.retry 重推一次,重推失败进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s)", "修正点:report.deliveryPlan.list / report.deliveryLog.list 响应 channel 字段描述由「投递渠道:wecom/inbox/link」修正为「投递渠道:inbox(渠道已收敛,仅支持 inbox;历史数据已由迁移 20260829170000 归一化)」;仅文档描述修正,params/response 结构、错误码无任何变化", "report.definition.save 的 19 条错误、report.definition.list 排序白名单 id/code/name/scope/is_enabled/created_at/updated_at、notify_template(≤500,标签白名单 {time}/{url}/{report_name}/{biz_date})/notify_group_ids(正整数去重 ≤20,校验存在性排除软删)/notify_member_ids(非空字符串去重 ≤100)参数与校验规则均与代码一致,未改动", "report.generate/report.generateTaskProgress 免权限(_noNeedRight/_noNeedAuth 声明)、report.meta 免权限但保留审计日志(未列入 _noNeedLog)、report.deliveryPlan.*/report.deliveryLog.list/report.definition.* 需授权(isNeedAuth=true,未声明免权限)口径均与 systemInit 声明一致", "methods/system.json 版本 0.3.43 -> 0.3.44(docMeta.version),updatedAt 保持 2026-08-29", "配套文档核对:docs/report-config-guide.md 第 5 节渠道说明已与「仅 inbox + 兜底 + 重推」一致(补充迁移归一化说明);第 8 节 report.definition.save/list/delete 用法与实现一致;AI_METHOD_ROUTING.md 5.1 report 能力速查与路由说明已最新", "权限:仅执行 npm run permission:sync:system-api -- --dry-run 预演缺口,未执行 apply、未扩任何角色授权", "仅文档变更,未改任何业务代码、表结构,未执行数据库/Redis 操作" ], "module": "report" }, { "version": "2026.08.29-report-definition-management", "date": "2026-08-29", "type": "enhanced", "summary": "通用报表模块新增报表定义管理接口:report.definition.save/list/delete(wms_report_definition 管理侧 CRUD,均需登录且需鉴权 isNeedAuth=true,未扩任何角色授权)。save 按 code upsert(未传字段不覆盖),code 格式 ^[a-z][a-z0-9_]{1,63}$(长度 2-64)、name 必填 ≤100、scope 枚举 warehouse/store/open(默认 warehouse),output_config/source_config/sheet_config 三段 JSON 配置支持对象或 JSON 字符串,source_config.query 须为注册表已有查询器,sheet_config 列结构校验(static/expand/computed,expand pair 与查询器字段清单对齐),response 平铺 report_code;list 支持 where{code,name,scope,is_enabled}(code/name 模糊、scope/is_enabled 精确)/pagination/sort(白名单 id/code/name/scope/is_enabled/created_at/updated_at),response 全量字段含三段 JSON 配置;delete 按 code 软删(幂等),启用中的投递计划引用时拦截「存在 N 个启用的投递计划引用该报表,请先停用计划」。", "methods": [ "report.definition.save", "report.definition.list", "report.definition.delete" ], "notes": [ "app/service/systemMethods/report/definition.js 新增:save/list/delete 仅做出口包装与参数解构(save 仅附加入参中存在的字段,undefined 不进入参数对象,保持「未传不覆盖」语义;list 经 prepareWhereContext 解析 where 后取 code/name/scope/is_enabled),业务逻辑下沉 app/service/systems/report.js saveDefinition/listDefinitions/deleteDefinition", "saveDefinition:code 规范化 trim 后校验(空/格式非法分别报「报表编码 code 不能为空」「报表编码 code 格式非法:须以小写字母开头,仅含小写字母/数字/下划线,长度 2-64」,正则 ^[a-z][a-z0-9_]{1,63}$);name trim 必填 ≤100;scope 枚举校验;JSON 字段仅非 undefined 时经 parseRequiredJson 解析(对象原样返回/JSON 字符串解析/其余报「 解析失败:须为对象或合法 JSON 字符串」);source_config 的 query 必须为注册表已有查询器(resolveQueryKey 缺省 generic,未知报「未知的报表查询器: 」);sheet_config 经 validateDefinitionSheetConfig 校验列结构(columns 数组、列类型仅 static/expand/computed、static 列须有 field 或 value、computed 列须有 field 或 formatter、expand pair 须与查询器静态字段清单对齐否则报「sheet_config expand 列 pair 元素 '' 不在查询器 的字段清单中(可用: )」);is_enabled 仅 0/1;description/remark ≤500 截断", "upsert 细节:uk_code 唯一索引含 deleted_at,findOne 以 paranoid:false 完整查重;命中软删记录先 restore 再 update(restore 撞唯一索引报「存在多个同名已删除记录,无法自动恢复,请更换报表编码」);并发首次创建撞 SequelizeUniqueConstraintError 降级为重查并更新(查不到报「报表编码已存在,保存冲突,请重试」);保存成功返回 definitionToView 视图(JSON 字段解析为对象)", "listDefinitions:code/name LIKE 模糊(escapeLike 转义 \\%_)、scope 精确(非法报「scope 仅支持 warehouse/store/open,非法: 」)、is_enabled 空值不过滤(Number 化 0/1);pagination page≥1、pageSize 夹取 1-200;sort 白名单 id/code/name/scope/is_enabled/created_at/updated_at(sortField/sortOrder 兼容 sort_field/sort_order 别名,非法字段回退 id DESC);findAll+count 并行,raw 行映射 definitionToView", "deleteDefinition:先按 report_code+enabled=1 统计 wms_report_delivery_plan 启用中引用(>0 报「存在 个启用的投递计划引用该报表,请先停用计划」),停用计划不阻断;再按 code paranoid:false 查定义(不存在报「报表定义不存在: 」,已软删幂等返回 deleted=1),否则 destroy 软删", "method 层统一 catch 后 this.fail(error.message):错误响应 code=0、flag=failure(与 report.meta 惯例一致);save/delete 成功响应将定义 code 平铺为 report_code(避免覆盖统一响应 code=1)", "systemInit 未声明 _noNeedLogin/_noNeedRight/_noNeedAuth 免权限 → 3 个接口均 isNeedAuth=true、isNeedLogin=true,仅通配符角色(超级管理员/仓库管理员)或后续 wms_permission 同步授权角色可用;本次仅文档、未扩任何角色授权,不执行权限同步 apply", "methods/system.json 通用报表模块(module=report)新增 3 个 method 条目(追加于 report.meta 之后),版本 0.3.42 -> 0.3.43", "配套文档:docs/report-config-guide.md 新增第 8 节「报表模板管理接口」;AI_METHOD_ROUTING.md 5.1 report 能力速查表登记 3 个新 method", "仅文档变更,未改任何业务代码,未执行数据库/Redis 操作" ], "module": "report" }, { "version": "2026.08.29-inbox-group-quick-list-members", "date": "2026-08-29", "type": "enhanced", "summary": "新增站内信群选择下拉接口:inbox.group.quickList(群快速查询,keyword 模糊匹配群名称/外部群ID、groupType 筛选 store/warehouse/express、limit 默认20上限100,warehouseId 服务端注入,无分页,按创建时间倒序)与 inbox.group.members(群成员筛选,groupId 必填,按外部群ID在消息表聚合去重成员取每 user_id 最新 user_name,keyword 过滤后截断,外部群ID为空返回空列表);新增 API 权限 566(quickList)/567(members),授权角色 8/26/28/29,两接口均需登录且需鉴权。", "methods": [ "inbox.group.quickList", "inbox.group.members" ], "notes": [ "app/service/systems/inbox/group.js quickList:where 含 warehouse_id(服务端注入),keyword 对 group_name/group_id 双字段 LIKE 模糊匹配,limit 截断为 1-100(默认20),findAll 仅取 id/group_id/group_name/group_type/sub_type/is_blocked,按 created_at DESC,软删除由 paranoid 自动排除", "app/service/systems/inbox/group.js members:先按 id+warehouse_id 查 wms_inbox_group(不存在抛「群不存在或无权限操作」,id 无效抛「群ID无效」);externalGroupId 为空直接返回 {list:[]};再按外部群ID+仓库查 wms_inbox_message(最近 500 条按 id DESC,user_id 非空),Map 按 user_id 去重取首次(最新)user_name,keyword 在聚合结果上过滤 user_name/user_id,最后 slice(0, limit)", "app/service/systemMethods/inbox.js group.quickList/group.members 子入口:warehouseId 从 ctx.user.store_id 自动注入,不信任前端传值;inbox systemMethods 未声明 systemInit 免权限,两接口走标准 API 权限校验(isNeedAuth=true、isNeedLogin=true)", "权限迁移 database/migrations/20260829180000-add-inbox-group-select-permissions.js:固定权限 ID 566(inbox.group.quickList,API:群快速查询)/567(inbox.group.members,API:群成员列表),type=api,授权角色 26(仓库组-主管)/28(客服组-主管)/29(生产组-主管)/8(经理);超级管理员(7)/仓库管理员(2) 持 * 通配符自动拥有;INSERT IGNORE 幂等,角色权限数组追加后去重排序", "methods/system.json 站内信分组(module=inbox)新增 2 个 method 条目(追加于 inbox.group.messages 之后),版本 0.3.41 -> 0.3.42", "AI_METHOD_ROUTING.md 新增 5.2 inbox.group(站内信群管理)能力速查小节,登记两接口的实现文件/函数/登录/鉴权信息", "仅文档变更,未改任何代码,未执行数据库/Redis 操作" ], "module": "inbox" }, { "version": "2026.08.29-report-delivery-channel-converge", "date": "2026-08-29", "type": "changed", "summary": "报表投递渠道收敛:report.deliveryPlan.save 的 channel 收敛为仅支持 inbox(默认 inbox,移除 wecom/link,非法渠道报「投递渠道仅支持 inbox: 」);历史 wecom/link 计划投递时按 inbox 兜底执行(warn 日志不抛错);inbox 推送失败立即经 inbox.message.retry 重推一次(ext_id 幂等复用消息记录),重推仍失败进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s)。", "methods": [ "report.deliveryPlan.save" ], "notes": [ "app/service/systems/reportDelivery.js:DELIVERY_CHANNELS 收敛为 ['inbox'],DEFAULT_CHANNEL='inbox';savePlan 对 channel 规范化(trim+lowercase,缺省默认 inbox)后不在白名单则抛「投递渠道仅支持 inbox: 」(原「投递渠道不合法(wecom/inbox/link)」文案已移除)", "deliverByChannel:rawChannel !== 'inbox' 时记录 warn 日志「计划投递渠道 已弃用,按 inbox 兜底投递」后按 inbox 执行,不直接抛错(避免历史计划在 failed 退避循环中耗尽重试次数后永久卡死)", "inbox 推送失败判定双保险:pushResult.success=false 或消息记录回写 push_status=3;失败时复用 ctx.service.inbox.message.retry 重推一次(重置 push_status=0 异步重推,ext_id 幂等复用同一条消息记录不重复写);retry 自身抛错则抛「站内信推送失败且重推失败: <原因>」,交由上层 failed 退避循环(MAX_RETRY=3,退避 = retry_count × 60s)", "methods/system.json 通用报表模块:report.deliveryPlan.save 的 channel 参数枚举收敛为仅 inbox(默认 inbox)、响应 channel 字段说明同步收敛、errors 中渠道错误文案更新为「投递渠道仅支持 inbox: 」;版本 0.3.40 -> 0.3.41", "配套文档:docs/report-config-guide.md 投递章节更新渠道说明(移除 wecom/link、历史渠道按 inbox 兜底、inbox 推送失败自动重推);AI_METHOD_ROUTING.md 同步补充渠道收敛说明与变更版本号", "授权说明:本次仅文档、未扩任何角色授权。report.deliveryPlan.save/list、report.deliveryLog.list 仍为需授权接口(isNeedAuth=true),不涉及权限同步操作" ], "module": "report" }, { "version": "2026.08.29-report-delivery-notify-template-targets", "date": "2026-08-29", "type": "enhanced", "summary": "报表投递新增文本通知与定向群/成员:report.deliveryPlan.save 新增可选参数 notify_template(≤500 字符,标签白名单 {time}/{url}/{report_name}/{biz_date},未知标签报错列出非法标签)、notify_group_ids(wms_inbox_group.id 正整数去重 ≤20,保存时校验存在性且排除软删,缺失报错列出缺失 ID)、notify_member_ids(外部 IM 用户 ID 非空字符串去重 ≤100);report.deliveryPlan.list 响应带出上述 3 个配置字段;report.deliveryLog.list 响应新增 notify_targets 投递目标快照({group_ids, member_ids, notify_text})。", "methods": [ "report.deliveryPlan.save", "report.deliveryPlan.list", "report.deliveryLog.list" ], "notes": [ "app/service/systems/reportDelivery.js savePlan:notify_template/notify_group_ids/notify_member_ids 三个可选参数仅在入参存在(!== undefined)时生效,未传不进入 payload(更新时保持既有字段不动,不传参数行为与旧版完全一致)", "savePlan 校验:notify_template trim 后 ≤500 字符;notify_group_ids 正整数、去重升序、≤20,保存时 validateNotifyGroupExists 校验 wms_inbox_group 存在性(软删自动排除,不校验 is_blocked:被屏蔽群仍可选中,屏蔽属于发送时过滤维度);notify_member_ids 非空字符串、去重、≤100;两者支持数组或 JSON 字符串数组,非数组报「必须为数组」", "标签白名单渲染:app/lib/report/notifyTemplate.js ALLOWED_TAGS={time,url,report_name,biz_date},validateNotifyTemplate 提取 {xxx} 标签并列出非法标签,renderNotifyTemplate 仅替换白名单标签;{url} 为空时替换为兜底文案「文件生成中,稍后可在投递记录中查看」,不阻断投递", "发送链路:reportDelivery.deliverByChannel 投递完成后调用 sendNotifyIfConfigured(与渠道独立,link 渠道同样生效);未配置模板或未选任何群/成员返回 null(不发送);群多选按 wms_inbox_group 逐群推送(群维度协议字段单值),发送时过滤 is_blocked=1/软删/仓库维度不一致;成员 user_id 数组整体透传不循环拆发,选择群时随每个群推送携带,未选择群时单独一次仅成员推送;目标不可达或推送失败抛异常走失败退避重试", "快照:sendNotifyIfConfigured 返回 {group_ids(实际发送的内部群ID), member_ids, notify_text},markDelivered 随 delivered 写入 wms_report_delivery_log.notify_targets;listLogs 以 readJsonObject 读取并输出(未配置时为 null)", "app/service/systems/warehouseNotify.js pushSystemMessage 新增 userIds 参数(仅接受字符串数组,去重过滤空值),推送体 user_id 直接传数组(目标侧协议支持);向后兼容:不传 userIds 且传 group 时校验、幂等 ext_id、落库字段、推送体均与旧版一致;消息表 user_id 列不承载数组(避免超长截断),成员仅随推送体透传并记录在投递日志快照", "method 层 app/service/systemMethods/report/deliveryPlan.js save:仅当 notify_template/notify_group_ids/notify_member_ids 在入参存在时附加到 saveArgs(undefined 不进入参数对象),保持旧调用形状与既有回归断言一致", "授权说明:本次仅文档、未扩任何角色授权。report.deliveryPlan.save/list、report.deliveryLog.list 仍为需授权接口(isNeedAuth=true),不涉及权限同步操作", "methods/system.json 通用报表模块更新 3 个 method 的 params/response/errors(版本 0.3.39 -> 0.3.40);配套文档 docs/report-config-guide.md 投递章节新增「文本通知模板与定向群/成员」小节" ], "module": "report" }, { "version": "2026.08.29-report-meta", "date": "2026-08-29", "type": "enhanced", "summary": "新增 report.meta(免权限只读列元数据接口,供前端报表设计器拉取可用字段):按报表编码返回 wms_report_definition 的 report_code/name/scope/query 与窗口参数 window{dayCount,cutoverHour},以及查询器静态字段清单 fields(查询器模块挂载的 querier.fields,未挂载返回空数组),不执行真实数据查询。", "methods": [ "report.meta" ], "notes": [ "app/service/systemMethods/report.js meta:入参 report_code/reportCode 双写法(驼峰优先),为空返回 fail「报表编码 report_code 不能为空」(flag=failure、code=0、HTTP 200);调用 systems/report.getMeta 后组装 {report_code, name, scope, query, window, fields}(getMeta 的 code 字段回显为 report_code)", "systemInit 声明:_noNeedRight/_noNeedAuth 含 meta(免权限 + 免仓库有效期鉴权,仅登录),_noNeedLogin 不含 meta(必须登录);_noNeedLog 未含 meta → meta 保留审计日志(generate/generateTaskProgress 不写审计日志,两者行为不同,已在接口文档与配置指南中如实标注)", "app/service/systems/report.js getMeta:读 wms_report_definition(is_enabled=1,不存在/停用抛「报表定义不存在或已停用: 」,经 controller 兜底为 HTTP 500 接口错误);window 由 app/lib/report/day_window.resolveWindowConfig 解析(默认 dayCount=7、cutoverHour=7,[D 07:00, D+1 07:00) 半开区间,source_config 可覆盖);fields 由 resolveQuerierFields 读取查询器模块静态字段 querier.fields(未挂载返回空数组)", "静态字段清单挂载方式:查询器模块以 FIELDS 常量挂载到导出函数(queries/sevenDayStockFlow.js 挂载 12 个顶层字段 stock_id/item_code/item_name/barcode/daily/ck_total/rk_total/available/total/pending/suggest/warn;daily 为数组类型含 ck/rk 子字段,suggest/warn 为 computed=true 格式化器预计算字段;queries/generic.js 未挂载,fields 返回空数组)", "授权说明:本次仅文档、未扩任何角色授权。report.meta 免权限(isNeedAuth=false),不涉及权限同步操作", "methods/system.json 通用报表模块分组新增 report.meta 登记(版本 0.3.38 -> 0.3.39);配套文档 docs/report-config-guide.md 新增 report.meta 小节,AI_METHOD_ROUTING.md 刷新 report.meta 条目" ], "module": "report" }, { "version": "2026.08.29-report-config-driven-generate-delivery", "date": "2026-08-29", "type": "enhanced", "summary": "新增配置驱动通用报表与货主定时投递接口:report.generate(提交报表导出异步任务,仅登录免权限)、report.generateTaskProgress(查询导出任务进度,仅登录免权限)、report.deliveryPlan.save/list(货主报表投递计划新增/更新与分页查询,需授权)、report.deliveryLog.list(投递记录审计分页查询,需授权)。", "methods": [ "report.generate", "report.generateTaskProgress", "report.deliveryPlan.save", "report.deliveryPlan.list", "report.deliveryLog.list" ], "notes": [ "app/service/systemMethods/report.js:systemInit 声明 _noNeedRight/_noNeedAuth = generate,generateTaskProgress(免权限+免仓库有效期鉴权,仅登录);generate 的 warehouse_id 由服务端从登录上下文 ctx.user.store_id 自动注入,禁止前端传递;store_id 支持 store_id/storeId 双写法,<=0 视为不按货主过滤", "app/service/systemMethods/report/deliveryPlan.js 与 report/deliveryLog.js:systemInit 未声明免权限(_noNeedRight/_noNeedAuth 均为空),为需授权管理类接口;methods/system.json 中 isNeedAuth=true 已登记", "权限同步:本次仅写文档、未执行任何授权操作。report.deliveryPlan.save/list、report.deliveryLog.list 为需授权接口,后续请先执行 npm run permission:sync:system-api -- --dry-run 预演,再按标准流程授权;不扩大任何角色授权范围", "实现依赖:app/service/systems/report.js(getDefinition/resolveQuerier/buildWorkbookSheets/generate/generateBuffer)、app/service/systems/reportDelivery.js(savePlan/listPlans/listLogs/dispatch 投递编排)、app/lib/report/*(render/day_window/formatters 纯函数模块)、内置查询器注册表 app/service/systems/report/queries/index.js(sevenDayStockFlow/generic)", "报表配置驱动:wms_report_definition(app/model/report_definition.js)以 code/name/scope + output_config/source_config/sheet_config 三段 JSON 配置驱动,新报表优先加配置行、免发版;sheet_config 支持静态列/窗口展开列/计算列、headerRow1 的 {date} 模板、merges 绝对引用、style、rowFilter", "methods/system.json 新增「通用报表模块」分组(module=report,groupName=通用报表模块),登记 5 个 method 的参数(source=body)、响应与错误码;版本 0.3.37 -> 0.3.38", "配套文档:docs/report-config-guide.md 新增报表配置结构说明(三段 JSON 配置、列定义、{date} 模板、merges、style、rowFilter、查询器注册表与内置查询器口径假设);AI_METHOD_ROUTING.md 同步刷新 report 相关路由说明与服务清单" ], "module": "report" }, { "version": "2026.08.28-workbench-queryOrder-intercept-pack-flag", "date": "2026-08-28", "type": "enhanced", "summary": "workbench.business(queryOrder/query) 查询订单响应增强:order 对象新增 intercept_status 字段(拦截状态原始值,散单/团购均返回,与既有 pack_status 并列);散单(isSandan=1)时 order 额外返回 intercept_flag/pack_flag 两个 0/1 标志(拦截状态不等于 none 时 intercept_flag=1 否则 0,打包状态不等于 none 时 pack_flag=1 否则 0),团购不返回这两个标志;空值/null 统一归一化为 none。", "methods": [ "workbench.business" ], "notes": [ "app/service/systems/workbench.js _queryOrder 步骤6:intercept_status/pack_status 空值/null 归一化为 none(String(v||'').trim() || 'none'),interceptFlag = 状态 !== none ? 1 : 0,packFlag 同理", "_queryOrder 响应 order 对象新增 intercept_status(原始值,散单/团购均返回),与既有 pack_status 并列,原始状态字段原样保留、不破坏既有调用方", "仅散单(isSandan===1)向 result.order 追加 intercept_flag/pack_flag;团购(isSandan===0)不追加这两个标志字段,pack_status/intercept_status 原始值仍原样返回", "methods/system.json workbench.business 同步补充 queryOrder/query 响应结构:order.intercept_status 字段说明、散单场景 order.intercept_flag/order.pack_flag 字段说明与取值语义(状态不等于 none 返回 1,否则返回 0)" ], "module": "workbench" }, { "version": "2026.08.28-storage-entry-quickInbound-is-virtual-inbound", "date": "2026-08-28", "type": "enhanced", "summary": "storage.entry.quickInbound 事务内回写 is_virtual_inbound(是否虚拟入库):有绑定收货单 → 0(非虚拟入库),无绑定收货单 → 1(虚拟入库),与 order_status=COMPLETED 同一事务写入;wms_entry_order 新增 is_virtual_inbound 字段(TINYINT(1) NOT NULL DEFAULT 0)", "methods": [ "storage.entry.quickInbound" ], "notes": [ "app/service/systems/storage/entry.js quickInbound:eo.update 事务内新增 is_virtual_inbound 回写,值为 receivingIds.length > 0 ? 0 : 1(有绑定收货单 → 非虚拟入库,无绑定收货单 → 虚拟入库),与 order_status=COMPLETED、sync_status=SUCCESS 同一事务提交", "app/model/entry_order.js:wms_entry_order 新增 is_virtual_inbound 字段(TINYINT(1),allowNull:false,defaultValue:0,comment:是否虚拟入库:0=否 1=是)", "database/migrations/20260828100000-add-is-virtual-inbound-to-wms-entry-order.js:新增迁移(describeTable 已存在时跳过 addColumn),down 删除字段;迁移文件仅创建,本次文档任务未执行", "methods/system.json storage.entry.quickInbound 说明文字补充 is_virtual_inbound 判定规则;入参/出参不变(quickInbound 响应未返回该字段,list/get 查询白名单亦未包含该字段)" ], "module": "storage.entry" }, { "version": "2026.08.27-order-allocateStorage-allow-storage-location", "date": "2026-08-27", "type": "fixed", "summary": "order.pendingOrder.allocateStorage 修复 allow_storage_location=true 未生效:分配储位时仍强制校验库位类型 allow_allocation=1/is_active=1,存储储位被过滤。现在 allow_storage_location=true 时直接分配储位,无视库位类型的可分配/启用限制", "methods": [ "order.pendingOrder.allocateStorage" ], "notes": [ "app/service/systems/order_storage_allocation.js allocatePicking:storageRows 查询的 locationType include where(allow_allocation:1/is_active:1)改为仅当 allowStorageLocation=false 时生效;true 时不再过滤库位类型限制", "无候选库位时的缺货诊断 diagnoseStorageTypeRestriction 仅在 allowStorageLocation=false 时执行,避免「库位类型不可分配/未启用」被误报为缺货原因", "可分配库存查询完成日志补充 allowStorageLocation 字段", "同步更新 methods/system.json:order.pendingOrder.allocateStorage 描述与 allow_storage_location 参数说明" ], "module": "order" }, { "version": "2026.08.27-order-export-stock-query", "date": "2026-08-27", "type": "fixed", "summary": "order.export 修复携带产品查询(where.stock_query)时导出失败(Unknown column ... in where clause):导出链路补齐 stock_query 虚拟筛选提取,按商品编码/名称/ID/条码解析为订单ID集合后注入主查询,与 order.list 语义一致", "methods": [ "order.export" ], "notes": [ "app/service/systems/order_export.js exportOrders:在 extractBuyerMessageHasVirtualFilter 之后新增 extractStockQueryVirtualFilter,从 where 提取并移除 stock_query,避免其残留在 where 中经 buildWhere/parseWhereConditions 被当作数据库字段解析,导致 SQL Unknown column 报错", "stockQuery 非空时调用 findOrderIdsByStockQuery(商品编码/名称/ID/条码模糊匹配 → stock_id 集合 → order_items 关联订单ID),再经 appendOrderIdsFilterToWhere 注入主查询;无匹配商品时导出结果为空,与 order.list 行为一致", "stockQuery 模块名取 target.defaultWhereModuleName || target.sortModuleName || 'order',保证仅传 table_type 时按表类型推导对应模块(current/history 等)的 order_items 表类型" ], "module": "order" }, { "version": "2026.08.27-storage-entry-get-total-order-lines", "date": "2026-08-27", "type": "enhanced", "summary": "storage.entry.get 响应新增 total_order_lines(entryOrder 内)、total_quantity(应入库总数量)、received_quantity(已入库总数量)字段", "methods": [ "storage.entry.get", "storage.entry.getStore" ], "notes": [ "app/service/systems/storage/entry.js get:返回 data.entryOrder 新增 total_order_lines(直接取 wms_entry_order.total_order_lines)", "data 顶层新增 total_quantity = 明细 planned 之和(应入库总数量)、received_quantity = 明细 completed 之和(已入库总数量)", "getStore 共用同一底层实现,自动获得这些字段", "同步更新 get 方法 JSDoc 注释" ], "module": "storage.entry" }, { "version": "2026.08.27-directInbound-receiving-stock-occupancy", "date": "2026-08-27", "type": "enhanced", "summary": "storage.entry.commit 导入/PDA 入库支持绑定收货单占用:带 receiving_detail_id 的导入记录优先按明细扣减,未带 receiving_detail_id 的剩余导入量按 stock_id 匹配收货单明细占用并回写收货单入库状态", "methods": [ "storage.entry.commit", "storage.directInbound.commit" ], "notes": [ "app/service/systems/inbound_direct_log.js commit onSuccess 事务内新增 _applyReceivingStockOccupancy:绑定收货单(wms_entry_order_receiving)存在时,汇总未携带 receiving_detail_id 的导入记录数量,按 stock_id(=收货明细 system_product_id)匹配占用", "优先级:携带 receiving_detail_id 的记录先由 _syncReceivingStorageStatus 按明细扣减,随后剩余量复用 storage.entry._applyReceivingInboundUsage 按 stock_id 依次占用收货明细剩余可入数量(actual_quantity - stored_quantity),事务内行锁防并发超分", "占用后回写收货明细 stored_quantity/storage_status(all/partial),并汇总更新收货单主表 storage_status", "未绑定收货单或无剩余导入量时跳过,不影响原有非绑定模式入库行为", "storage.entry._applyReceivingInboundUsage 日志前缀由 [storage.entry.quickInbound] 改为 [storage.entry](方法现被 quickInbound 与 commit 两个流程复用)" ], "module": "storage.entry" }, { "version": "2026.08.27-storage-management-replenishmentDemand-owner-filter", "date": "2026-08-27", "type": "enhanced", "summary": "storage.management.replenishmentDemand 新增货主筛选:store_id(单值或数组)或 where.store_id 传入,仅返回指定货主的 SKU,summary 同步只统计筛选后数据", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "app/service/systemMethods/storage/management.js replenishmentDemand:解析 store_id / store_ids / where.store_id(单值/数组),归一化为正整数数组去重,非法值(非正整数)抛错;空值不筛选。", "app/service/systems/storage/management.js replenishmentDemand:options.storeIds 构建 Set,组装输出循环内非命中货主 SKU 直接跳过,list 与 summary 统计口径一致(仅含筛选货主)。", "同步更新 methods/system.json 参数文档(新增 store_id 参数说明)。" ], "module": "storage.management" }, { "version": "2026.08.27-quickInbound-receiving-intersection", "date": "2026-08-27", "type": "enhanced", "summary": "storage.entry.quickInbound 支持绑定收货单交集直入:有绑定时按 stock_id 只取收货单中剩余可入数量(actual_quantity - stored_quantity)与入库明细的较小值直入,并回写收货单明细已入库数量与收货单入库状态", "methods": [ "storage.entry.quickInbound" ], "notes": [ "app/service/systems/storage/entry.js quickInbound:新增绑定收货单查询(wms_entry_order_receiving),按 stock_id(=收货明细 system_product_id)聚合剩余可入数量 actual_quantity - stored_quantity", "入库明细实际直入量 = min(计划数量, 剩余可入数量);无交集商品跳过(明细 received_quantity 写 0),全部无交集或剩余为 0 时返回 400「收货单中无交集商品或剩余可入数量不足,无法快捷直入」", "未绑定收货单保持原行为:按明细计划数量全量直入", "存在截断/跳过明细时 isFin=false(confirmType=1, PARTFULFILLED)回传奇门/API", "新增 _applyReceivingInboundUsage 事务内回写:行锁重读收货明细,按明细 id 升序分配本次入库量(每个明细最多分配其剩余可入数量),更新 stored_quantity(使用了多少写多少)与 storage_status(all/partial),并汇总更新收货单主表 storage_status", "收货单主表 storage_status 按实际数量判定:全部明细 stored_quantity >= actual_quantity 才置 all;有部分入库置 partial;全部未入库置 none——收货单未全部使用所有商品时不会转为全部入库", "入库单明细 received_quantity 改为写实际入库量(原来写计划数量)", "响应新增 plan_quantity(计划入库总数量),total_quantity 语义改为实际入库总数量,items_count 语义改为实际入库明细条目数" ], "module": "storage.entry" }, { "version": "2026.08.27-storage-management-replenishmentDemand-owner-barcode", "date": "2026-08-27", "type": "enhanced", "summary": "storage.management.replenishmentDemand 响应 list 每项新增 store_id(货主ID)、store_name(货主名称)、barcodes(SKU 条码列表)字段", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "app/service/systems/storage/management.js replenishmentDemand:StockWarehouse 三处查询(严格/宽松/终极兜底)attributes 均新增 store_id,stockInfoMap 记录货主ID。", "新增货主名称查询:StoreWarehouse(store_remask 签约表备注名)优先、Store(company_name 商家公司名)兜底;新增 StockBarcode 按 stock_id 批量查询条码并分组为 barcodes: [{id, barcode}]。", "货主与条码查询与库存查询为顺序执行(货主/条码三表在 Promise.all 内并行)。", "响应字段:store_id (number) 货主ID;store_name (string) 货主名称;barcodes (array) 条码列表,children: id (number)/barcode (string)。", "同步更新 methods/system.json 响应文档。" ], "module": "storage.management" }, { "version": "2026.08.27-order-export-columns", "date": "2026-08-27", "type": "enhanced", "summary": "order.export 新增 export_columns/exportColumns 导出表头字段白名单参数(中文表头数组):不传或空数组输出全部列;传入时仅输出指定列;校验枚举覆盖 waybill/item 两种模式全部 51 个中文表头,非法表头抛错并列出非法值。", "methods": [ "order.export" ], "notes": [ "app/service/systems/order_export.js:新增 ORDER_EXPORT_ALL_COLUMN_HEADERS(waybill/item 两种模式表头并集,共 51 个);getOrderExportColumns(mode, selectedHeaders) 支持按中文表头过滤;新增 normalizeExportColumns(数组去重/trim/非法值抛错);exportOrders 读取 export_columns/exportColumns(下划线优先)并作用到初始 sheet 与自动续写的后续 sheet(resolvedColumns 复用)", "app/service/systemMethods/order/index.js export:解构 export_columns/exportColumns 并透传数组,未传时传空数组(输出全部列)", "methods/system.json order.export 新增 export_columns/exportColumns 参数文档:枚举全量 51 个中文表头,并标注仅 waybill 模式输出(系统订单号、外部订单号、平台单号、抓取波次号、商品明细)与仅 item 模式输出(订单ID、订单号、外部单号、波次号、仓库商品名称、商品条码、商品图片、数量)的字段" ], "module": "order" }, { "version": "2026.08.26-wave-batchList-store-id-filter", "date": "2026-08-26", "type": "enhanced", "summary": "order.wave.batchList 新增 where.store_id(货主ID)过滤:支持单值/数组/{operator,value} 结构(正整数),返回包含任一筛选货主订单的波次(含混合货主波次);未在 wms_wave_batch 加冗余 store_id 字段,通过订单分表 INNER JOIN 聚合匹配,零迁移零回填零口径漂移风险。", "methods": [ "order.wave.batchList" ], "notes": [ "app/service/systemMethods/order/wave.js buildBatchListWhereClause:allowedFields 新增 store_id,normalizeStoreIdList 归一化(单值/数组/{operator,value}→正整数数组去重,非法值抛错),返回值新增 storeIds", "batchList:storeIds 非空时在 wave_order_stats 之后追加 INNER JOIN wave_owner_filter(订单表 od.wave_id 匹配且 od.store_id IN (:whereStoreIds) 按 wave_id 分组),listSql/countSql replacements 新增 whereStoreIds", "设计决策:不在 wms_wave_batch 增加 store_id 冗余字段(混合填0),理由——batchList 原本就必须 LEFT JOIN 订单表做状态聚合,货主过滤挂同一次 JOIN 零额外成本;订单表已有 store_id 单列索引;冗余需覆盖抓取入波/策略任务建波/batchRemoveOrders/batchRemoveExceptionOrders 等 10+ 处写入点维护,遗漏即口径漂移;owner_name 展示已实时聚合订单 store_id,避免双口径", "实测:{operator:'',value:[1000281,1000000]} 过滤 wave_type=1&source=0 返回 196 条(库中该货主订单波次);单值/数组形式均返回 5 条;不存在货主 0 条;非法值报错;无过滤 baseline 278 条不受影响;原请求含 wave_status=0 返回 0 因库中活动波次均为 status=1", "同步更新 methods/system.json 的 batchList where 白名单说明" ], "module": "order.wave" }, { "version": "2026.08.26-wave-batchList-store-name", "date": "2026-08-26", "type": "enhanced", "summary": "order.wave.batchList 响应每条记录新增 store_name(货主信息):按波次内订单 store_id(货主ID)聚合,所有订单均为同一货主时返回货主名称,否则(多个货主、存在无货主订单或空波次)返回“混合”;货主名称优先取合约表 wms_store_warehouse.store_remask(货主备注名称),无合约或备注为空时回退 wms_store.company_name(公司全称)。", "methods": [ "order.wave.batchList" ], "notes": [ "app/service/systemMethods/order/wave.js batchList:wave_order_stats 子查询新增 owner_distinct_count(COUNT(DISTINCT NULLIF(store_id,0)))、owner_named_count(SUM 非空判定)、owner_store_id(MAX(NULLIF(store_id,0)))三个聚合字段,listSql SELECT 透出", "新增 resolveWaveBatchOwnerStoreNameMap:仅对满足单货主的波次批量查 StoreWarehouse(store_id+warehouse_id)取 store_remask,再查 wms_store.company_name 兑底,remask 覆盖 company_name;查询失败仅告警不影响列表", "判定口径:orderCount>0 且 ownerDistinctCount===1 且 ownerNamedCount===orderCount 且 ownerStoreId>0 才返回货主名称,否则返回“混合”(0 单波次同样返回“混合”)", "货主名称口径与 afterSale._enrichListStoreNames、inventory.store_name 一致(store_remask 优先、company_name 兑底);早期草稿曾按 shop_nick 店铺名称实现,已按项目货主口径修正", "同步更新 methods/system.json 的 batchList 描述与 response.list 字段说明" ], "module": "order.wave" }, { "version": "2026.08.26-workbench-queryOrder-pack-status", "date": "2026-08-26", "type": "enhanced", "summary": "工作台 workbench.business(queryOrder) 查询订单增强:接入订单序列表(wms_order_id_location_*)优先定位分表,未命中按 current→dispatch 回退遍历;响应 order 对象新增 pack_status 字段(散单/团购均返回)。", "methods": [ "workbench.business" ], "notes": [ "app/service/systems/workbench.js _queryOrder 步骤2:先经 orderDeliveryFactory.getOrderLocation(orderId, warehouseId) 获取序列表位置,命中则优先查对应分表,失败/未命中保持原 current→dispatch 遍历,与 _sendWeight/waybill/order_express 等模块的序列表优先定位语义一致", "_queryOrder 响应 order 对象新增 pack_status(none/padding/fin/error),与 pick_status/recheck_status 等状态机并列,工作台可根据打包状态判断该单是否已打包", "备注:_packOrder 订单查找仍按 delivery_order_code 双表遍历(序列表按 id 定位,发货单号场景暂不适用)" ], "module": "workbench" }, { "version": "2026.08.26-finishPack-sync-order-pack-status", "date": "2026-08-26", "type": "fixed", "summary": "修复打包任务结束事件不更新订单打包状态的问题:workbench.finishPack 结束任务后同步更新关联订单 pack_status 为 fin(散单按订单更新,团购按波次批量更新未拦截订单)并写完成操作日志;order.packing.setEndTime 手动结束同样同步订单;打包操作日志文案按任务状态区分(开始打包/打包完成),不再在开始打包时误写“打包完成”。", "methods": [], "notes": [ "问题定位:波次 B2026082503311(团购 7 单)开始打包时 packOrder(status=1) 写入的日志前缀硬编码为“团购打包完成”,实际尾部为“任务状态: 打包中”;设备结束事件走 finishPack 仅更新 wms_pack_task(end_time/status=2),未更新订单,导致订单 pack_status 停留在 padding", "app/service/systems/workbench.js 新增 _updateOrderPackStatus:遍历 current+dispatch 分表,散单按 order_id 更新单笔,团购按 wave_id 批量更新(intercept_status 空值按 none 处理,拦截订单跳过),异常仅记日志不影响主流程;_packOrder 步骤6.5 改为复用该方法", "app/service/systems/workbench.js _finishPack:任务结束后按 pack_mode 判定散单/团购,调用 _updateOrderPackStatus(packStatus=2) 同步订单,并按任务记录(含 operator_text 回填操作人)写入完成操作日志", "app/service/systems/order_packing.js setEndTime:任务由未完成转为已完成时同样调用 _updateOrderPackStatus 同步订单,与 finishPack 语义对齐", "app/service/systems/workbench.js _writePackOperationLog:日志前缀按 status 区分——status>=2 写“打包完成”,否则写“开始打包”,保留原有字段变更描述", "定时任务 auto_finish_pack_task 超时自动结束仅关闭任务记录、不更新订单(保持原语义,避免超时误标订单完成),如需要可在后续版本评估同步" ], "module": "workbench" }, { "version": "2026.08.26-stockout-listLogs", "date": "2026-08-26", "type": "added", "summary": "新增 storage.stockout.listLogs 出库单操作日志查询接口:按出库单ID或出库单号分页查询 wms_operation_log(business_type=stockout,business_id=出库单ID),覆盖转订单/确认/修改/取消等 STOCKOUT_* 操作,按创建时间倒序;配套 operationLog.queryStockoutLogs 服务方法与权限 565。", "methods": [ "storage.stockout.listLogs" ], "notes": [ "app/service/systemMethods/storage/stockout.js 新增 listLogs:支持 id 或 stockout_order_code 定位(出库单号先查表换ID),pagination.page/pageSize(兼容 page_size);出库单不存在返回空列表不报错;仓库上下文取 ctx.user.store_id", "app/service/systems/operation_log.js 新增 queryStockoutLogs:复用 queryLogsByBusinessType(query, 'stockout')", "database/migrations/20260826100000-add-stockout-listLogs-permission.js:权限 565,授权角色 8/26/28/29/30,开发库已执行", "storage.stockout.listItems 出库单明细接口此前已存在(按 stockout_order_code/id 查 wms_order_stockout_items),本次仅补 listLogs 文档", "实测:listLogs 按 stockout_order_code 与 id=22 均返回分页日志(STOCKOUT_TO_ORDER/STOCKOUT_UPDATE_INFO,含操作人/时间/消息/平台名),pagination.total=4 正确;注意权限迁移后短时间内用户权限上下文缓存可能未刷新导致 403,刷新后正常" ], "module": "storage.stockout" }, { "version": "2026.08.26-stockout-order-sync-channel", "date": "2026-08-26", "type": "added", "summary": "订单回传区分 STOCKOUT 创建渠道:待处理订单同步入口(syncOrderIds)按 create_channel 路由新增 syncStockoutOrders,回传时把订单实际快递编码/运单号写回出库单(express_code/express_name/waybill_code/waybill_codes),并按出库单来源通知外部(QM→奇门 taobao.qimen.stockout.confirm,API→OpenAPI 回调 event=stockout_completed,WMS 内部来源直接成功);通知成功后才扣减订单库存并完成同步(sync_status=fin、出库单 COMPLETED/SUCCESS),失败则订单 sync_status=error 标记待处理异常、出库单 sync_status=FAILED 记录失败原因。", "methods": [ "order.pendingOrder.syncOrderIds" ], "notes": [ "app/service/systems/order_async.js 新增 syncStockoutOrders/syncStockoutOrdersInternal/processStockoutOrderInternal/notifyStockoutExternalInternal/buildStockoutConfirmDataInternal/finalizeSuccessfulStockoutSyncInternal:反查出库单(订单 source_order_codes 首项或明细 source_order_code),运单号仅认 wms_order_express 表(不回退订单主表 express_code 面单前置);收尾事务内写回出库单 + 订单明细 outbound 扣库存 + sync_status=fin,SELECT FOR UPDATE 防重幂等", "app/service/systems/order_storage_allocation.js syncOrderIds 渠道路由新增 STOCKOUT 分支(原落入 MANUAL 兜底,不通知外部)", "出库单已 SUCCESS 的重试场景跳过重复通知,直接收尾;订单未分配运单号时回传失败并提示", "所有回传入口(pendingOrder.syncOrderIds 异步包装、express_platform 自动同步回传)均汇聚到同一路由,改动一处覆盖全部", "订单表无 sync_message 列:回传失败提示落在 order_flag 字段(markPendingExceptionInternal 同步置 inspection_status=error/step=3)", "实测失败路径:测试订单 122172(TEST-SO-20260826004828-003 转单)回传奇门 stockout.confirm 返回 JST_Error,订单 sync_status=error + order_flag 提示,出库单保持 TRANSFERRED + sync_status=FAILED + sync_message 记录原因", "实测成功路径:出库单 source_type 临时改 WMS(内部来源直接成功)触发回传,订单 sync_status=fin/order_flag 清空/step=2,出库单 COMPLETED/SUCCESS + 写回 express_code=SF/waybill_code/waybill_codes,库存 101389 quantity 100→95、locked 8→3,流水闭环 LOCK(QM_STOCKOUT)→UNLOCK(转单释放)→LOCK(DELIVERY_ORDER)→OUTBOUND(订单出库)" ], "module": "order.pendingOrder" }, { "version": "2026.08.26-stockout-cancel", "date": "2026-08-26", "type": "added", "summary": "新增 storage.stockout.cancel 出库单取消:仅 CREATED/PENDING 允许取消;事务内释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水)并置 CANCELLED,写 wms_operation_log 操作日志(STOCKOUT_CANCEL);TRANSFERRED/COMPLETED 禁止取消。新增权限 564 并授权。", "methods": [ "storage.stockout.cancel" ], "notes": [ "app/service/systemMethods/storage/stockout.js 新增 cancel:复用 lockItemStorages 负数量释放(锁定不足幂等跳过),与状态更新、操作日志同事务;仓库隔离与 confirm/updateInfo 一致", "database/migrations/20260826093000-add-stockout-cancel-permission.js:权限 564,授权角色 8/26/28/29/30,开发库已执行", "实测:取消测试单后 locked_quantity 101379 3→2,UNLOCK 流水(出库单取消释放锁定)与 STOCKOUT_CANCEL 操作日志均落库", "同步更新 methods/system.json 新增 cancel 接口文档" ], "module": "storage.stockout" }, { "version": "2026.08.26-stockout-operation-log", "date": "2026-08-26", "type": "added", "summary": "storage.stockout 链路补写 wms_operation_log 操作日志(businessType=stockout):confirm 直出成功、toOrder 转单成功、updateInfo 修改均写操作记录;新增 updateInfo API 权限 563 并授权;修复 updateInfo 证件号参数名与出库单 ID 冲突。", "methods": [ "storage.stockout.confirm", "storage.stockout.toOrder", "storage.stockout.updateInfo" ], "notes": [ "app/service/systemMethods/storage/stockout.js 新增 _writeStockoutOperationLog(operationLog.createOperationLogs,失败仅告警不影响主流程):confirm 成功路径与状态更新同事务写 STOCKOUT_CONFIRM(含释放锁总量);toOrder 转单后写 STOCKOUT_TO_ORDER(含新订单号);updateInfo 写 STOCKOUT_UPDATE_INFO(含改动字段摘要)", "修复:updateInfo 收件人证件号参数由 id 改为 receiver_id(原与出库单ID参数冲突,会把 data.id 误写入 receiver_id 字段)", "database/migrations/20260826090000-add-stockout-updateInfo-permission.js:新增权限 563(storage.stockout.updateInfo),授权角色 8/26/28/29/30,开发库已执行", "实测:updateInfo 修改后 wms_operation_log 落库(business_type=stockout、operation_code=STOCKOUT_UPDATE_INFO、operator 阿猫、message 含改动摘要)" ], "module": "storage.stockout" }, { "version": "2026.08.26-stockout-confirm-release-lock", "date": "2026-08-26", "type": "fixed", "summary": "storage.stockout.confirm 直出确认后释放出库单创建时占用的库存锁定:出站通知成功后,事务内逐明细 lockItemStorages(-plan_qty, orderType=QM_STOCKOUT) 释放锁定并自动写 UNLOCK 流水,与状态推进到 COMPLETED 同事务提交,失败回滚可重试;释放遇\"锁定不足\"视为幂等成功跳过。", "methods": [ "storage.stockout.confirm" ], "notes": [ "修复前:confirm 直出成功后 locked_quantity 一直占用(出库单无取消入口,锁只能靠转订单释放)", "出站通知失败时锁保持、状态不变(sync_status=FAILED),重试 confirm 成功后才会释放;已释放场景(锁定不足)跳过不阻断", "实测:本地 confirm 真实出站淘宝奇门返回 JST_Error 单号转换失败,锁保持(101379.locked=3/101389.locked=8 不变),符合设计;释放+UNLOCK 流水由 lockItemStorages 负数量链路保证" ], "module": "storage.stockout" }, { "version": "2026.08.26-directPutaway-default-location", "date": "2026-08-26", "type": "updated", "summary": "storage.inventory.directPutaway 默认库位改为读取仓库设置:直入库存写 wms_storage 时,收货明细 space_id 无效则使用 wms_store.subject_config.default_location_id(经 deliveryOrder.getStoreSubjectConfig 缓存优先读取),未设置时兜底库位 1。", "methods": [ "storage.inventory.directPutaway" ], "notes": [ "app/service/systems/storage/inventory.js directPutaway:步骤 10 写 wms_storage 的 spaceId 由硬编码 1 改为 defaultSpaceId(收货明细有库位仍按其库位),defaultSpaceId 在方法前段读取仓库设置(正整数有效才采用,否则 1),读取失败仅告警不影响入库", "与 storage.receiving.addDetail 默认库位口径一致(仓库设置优先,兜底 1)", "同步更新 methods/system.json directPutaway 的库位规则说明" ], "module": "storage.inventory" }, { "version": "2026.08.26-receiving-addDetail-default-location", "date": "2026-08-26", "type": "updated", "summary": "storage.receiving.addDetail 默认库位改为读取仓库设置:新增明细时 space_id 默认取 wms_store.subject_config.default_location_id(经 deliveryOrder.getStoreSubjectConfig 缓存优先读取),未设置时兜底库位 1;前端传入 item.space_id 时仍按传入值。", "methods": [ "storage.receiving.addDetail" ], "notes": [ "app/service/systems/storage/receiving.js addDetail:默认明细 space_id 由硬编码 1 改为优先读仓库设置 default_location_id(正整数有效才采用),否则兜底 1;读取失败仅告警不影响创建", "依赖 deliveryOrder.getStoreSubjectConfig(缓存 10 分钟),saveSettings 保存仓库设置时会同步清理该缓存键", "同步更新 methods/system.json addDetail 的 item.space_id 描述" ], "module": "storage.receiving" }, { "version": "2026.08.26-warehouse-setting-default-location", "date": "2026-08-26", "type": "added", "summary": "仓库设置(wms_store.subject_config)新增\"默认库位\"字段 default_location_id(type location):setting.warehouse.getFieldMeta 字段元信息新增该字段(不返回库位选项列表,库位数量大,前端按仓库搜索选择),saveSettings 传入时校验库位属于当前仓库,否则报 400 拒绝写入。", "methods": [ "setting.warehouse.getFieldMeta", "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "app/service/systems/setting/warehouse.js WAREHOUSE_SETTING_FIELDS 新增 default_location_id(名称:默认库位,type location,default null,描述:仓库未指定库位入库/上架时使用的默认库位);getFieldMeta 不注入库位选项列表(库位数量大,前端按 type=location 自行按仓库搜索库位)", "saveSettings 新增 validateDefaultLocation:传入 default_location_id 时校验其属于当前仓库,否则 400 '默认库位 {id} 不属于当前仓库';传 null/空清空", "app/model/store.js DEFAULT_SUBJECT_CONFIG 新增 default_location_id: null;normalizeSubjectConfig 新增正整数校验分支(空值置 null)", "同步更新 methods/system.json:getSettings 响应、saveSettings 参数补充 default_location_id 说明" ], "module": "setting.warehouse" }, { "version": "2026.08.25-stockout-updateInfo-transferred", "date": "2026-08-25", "type": "added", "summary": "新增 storage.stockout.updateInfo 修改出库单信息接口,并引入 TRANSFERRED 状态:转订单成功后出库单置为 TRANSFERRED(已转订单),该状态下禁止一键出库。", "methods": [ "storage.stockout.updateInfo", "storage.stockout.toOrder" ], "notes": [ "storage.stockout.updateInfo:修改范围限收件人(name/tel/mobile/company/email)、地址(province/city/area/town/detailAddress/zipCode/countryCode)、快递编码(express_code,自动解析 express_name)、来源平台(source_platform_code/name),未传入不修改;仅 CREATED/PENDING 状态允许修改(400);修改后收货信息不完整(name、(tel/mobile) 其一、省市区镇详细地址)禁止提交并列出缺失字段", "数据库迁移 20260825180000-add-transferred-status-and-platform-to-wms-order-stockout.js:order_status ENUM 追加 TRANSFERRED + 新增 source_platform_code(50)/source_platform_name(200) 列,开发库已执行并核验", "app/model/order_stockout.js:ENUM 补 TRANSFERRED、新增两平台字段、新增 isTransferred() 辅助方法", "storage.stockout.toOrder:转单成功后 order_status 置 TRANSFERRED(原 CANCELLED);deliveryOrder.sourcePlatformCode 优先用出库单已存平台,为空走兜底平台;confirm(一键出库)经 canConfirm 拒绝 TRANSFERRED 状态", "同步更新 methods/system.json:新增 updateInfo 接口文档,更新 toOrder 描述与状态说明", "实测(2026-08-26,测试单 20):正常修改 name/mobile/detailAddress + express_code=SF(自动解析 express_name=顺丰速运)+ source_platform_code 均落库,未传字段不变;detailAddress 清空被拦截(收货信息缺失,禁止提交:缺少 detailAddress(详细地址));COMPLETED 单被拦截(不允许修改);操作日志 STOCKOUT_UPDATE_INFO 含改动字段摘要(收件人姓名、移动电话、详细地址、快递编码、来源平台);测试数据已恢复原貌、日志保留" ], "module": "storage.stockout" }, { "version": "2026.08.25-stockout-toOrder-receiver-validate", "date": "2026-08-25", "type": "fixed", "summary": "storage.stockout.toOrder 增加收货信息必填校验与同快递建单:name、(tel/mobile) 至少一项、省市区镇详细地址缺失时拒绝转单并提示缺失字段;收货信息优先接口传入,未传回填出库单已存的 receiver_* 字段;新订单快递编码沿用出库单 express_code(相同快递),平台不传 sourcePlatformCode 走兜底平台。", "methods": [ "storage.stockout.toOrder" ], "notes": [ "app/service/systemMethods/storage/stockout.js toOrder:释放锁前先合并收货信息(storedReceiverInfo 从出库单 receiver_company/name/zip_code/tel/mobile/email/country_code/province/city/area/town/detail_address 回填,接口 receiverInfo 非空字段覆盖)并逐项校验,缺项返回 fail 提示缺失字段列表", "建单参数:logisticsCode = 出库单 express_code(create 时已解析的系统快递编码),不传 sourcePlatformCode(resolvePlatformSnapshot 自动使用合约兜底平台)", "同步更新 methods/system.json 中 storage.stockout.toOrder 的 description 与 receiverInfo 参数说明" ], "module": "storage.stockout" }, { "version": "2026.08.25-stockout-receiver-info-db", "date": "2026-08-25", "type": "added", "summary": "wms_order_stockout 表新增 13 个收件人字段(receiver_* 前缀),对应奇门 stockout.create 报文 receiverInfo 节点(company/name/zipCode/tel/mobile/email/countryCode/province/city/area/town/detailAddress/id),为出库单解析收件人信息与转订单回填做准备。", "methods": [ "storage.stockout.toOrder", "stockout.create" ], "notes": [ "database/migrations/20260825170000-add-receiver-info-to-wms-order-stockout.js 新增 13 列:receiver_company(200)/receiver_name(50)/receiver_zip_code(50)/receiver_tel(50)/receiver_mobile(50)/receiver_email(50)/receiver_country_code(50)/receiver_province(50)/receiver_city(50)/receiver_area(50)/receiver_town(50)/receiver_detail_address(200)/receiver_id(50),均允许 NULL;up/down 均带 describeTable 幂等保护", "app/model/order_stockout.js 同步新增 13 个字段定义(remark 与 express_code 之间)", "开发库已执行迁移并核验 SHOW COLUMNS 全部落库;生产库需在发布时按 db-migration-envs 规范执行" ], "module": "storage.stockout" }, { "version": "2026.08.25-storage.stockout.toOrder", "date": "2026-08-25", "type": "added", "summary": "storage.stockout.toOrder 从占位接口落地为真实实现:将非订单出库单(wms_order_stockout)转为正式销售订单,新订单 create_channel 固定为 STOCKOUT;转单时释放出库单库存锁定(QM_STOCKOUT)并转由新订单重新锁定,成功后原出库单置为 CANCELLED 并写入 extend_props.transferred_order_id(幂等,重复调用直接返回已转订单信息)。", "methods": [ "storage.stockout.toOrder" ], "notes": [ "app/service/systemMethods/storage/stockout.js toOrder 实现:入参 id(出库单ID,必填)、delivery_order_code(可选,不传自动生成 SK 前缀单号)、receiverInfo(可选收件人信息);校验出库单存在且 order_status 为 CREATED/PENDING(否则 400),extend_props.transferred_order_id 存在时幂等返回已转订单", "锁转移:事务内逐明细 lockItemStorages(-plan_qty, orderType=QM_STOCKOUT) 释放出库单锁 → 调 deliveryOrder.addOrder(data, info, 'STOCKOUT') 建单并重新锁库存 → 建单失败/订单号重复时 _restoreStockoutLocks 补偿恢复锁定;建单成功后更新出库单 order_status=CANCELLED 并记录 transferred_order_id/transferred_order_code/transferred_at", "新订单明细手工单风格传 stockId(wms_stock_warehouse.id),sourceOrderCode 写入出库单号便于追溯;create_channel=STOCKOUT 不触发 addOrder 的 API/QM 异步流程,也不会被自动同步任务推送", "app/service/systemMethods/storage/delivery.js toOrder 兼容转发改为透传 data 参数", "app/service/systemMethods/order/base.js CREATE_CHANNEL_LABELS 新增 STOCKOUT: '出库转单',订单工作台渠道列正确显示中文标签", "同步更新 methods/system.json 中 storage.stockout.toOrder 接口文档" ], "module": "storage.stockout" }, { "version": "2026.08.25-storeWarehouse.store.createUser", "date": "2026-08-25", "type": "added", "summary": "新增 storeWarehouse.store.createUser:为货主创建用户。按用户名查询平台账号:账号不存在则自动注册并随机生成 12 位密码返回;两种情况统一完成货主工号绑定并授予货主管理员角色(wms_role.id=5)。幂等:重复调用不会重复创建账号或绑定。", "methods": [ "storeWarehouse.store.createUser" ], "notes": [ "app/service/systems/store_warehouse.js 新增 createUser:校验 username(必填 + 3-50 位字母数字下划线,400)与 store_id(必填正整数,400)→ 货主存在校验(404)→ 按用户名查询账号(不存在则复用 auth.user.register 注册并随机生成 12 位密码)→ 事务内 AccountStoreEmployee.findOrCreate 绑定货主工号(已存在且 status!=1 时恢复为 1)→ 校验货主管理员角色 wms_role.id=5 已初始化(缺失抛 500)→ EmployeeRole.findOrCreate 授予角色(幂等)", "app/service/systemMethods/storeWarehouse/store.js 新增 createUser 包装方法;构造器 _noNeedRight/_noNeedAuth 白名单加入 createUser(isNeedLogin=true 需登录、isNeedAuth=false)", "响应 data:account_id、username、store_id、created(是否本次新建账号;false 表示账号已存在仅完成授权)、password(仅 created=true 时返回 12 位随机明文密码)", "同步更新 methods/system.json 中 storeWarehouse.store.createUser 接口文档" ], "module": "storeWarehouse" }, { "version": "2026.08.25-returnUnpack.forceRecord", "date": "2026-08-25", "type": "added", "summary": "新增 returnUnpack.forceRecord:强制重新录制拆包视频。参考 order.packing.forceRecord,入参 id(拆包单ID);校验仓库录制电脑(wms_print_computer is_recording=true)在线后,将 wms_return_unpack_video 视频记录重置为 created 并清空 video_url,再向打印服务 /record/force 推送 { unpack_id } 触发重新录制。", "methods": [ "returnUnpack.forceRecord" ], "notes": [ "app/service/systems/return_unpack.js 新增 forceRecord:_findByIdChecked 仓库隔离校验(不存在 404 / 跨仓库 403)→ 查询录制电脑(无则 400)→ Redis 在线键 warehouse:{warehouseId}:printer:{computerId} 校验在线(不在线 400)→ 重置视频状态为 created 并清空 video_url → POST {printService.url}/record/force 推送 { unpack_id }(失败抛 500 业务错误)", "app/service/systemMethods/returnUnpack.js 新增 forceRecord 包装方法(与 submit 同层,走 _call 统一错误包装)", "database/migrations/20260825120000-add-return-unpack-force-record-permission.js 新增权限记录 562(returnUnpack.forceRecord,API:退回拆包强制录制),授权角色与作业类 540-545 一致:仓库组-员工(27)/仓库组-主管(26)", "同步更新 methods/system.json 中 returnUnpack.forceRecord 的接口文档" ], "module": "returnUnpack" }, { "version": "2026.08.24-storage.entry-receivingCompare-merge", "date": "2026-08-24", "type": "fixed", "summary": "storage.entry.receivingCompare 对比主体修正:多个收货单先合并明细,再与入库单做一次对照。原实现每个收货单各对照一遍,入库计划数量被重复展开多份,前端对比表格出现重复行。", "methods": [ "storage.entry.receivingCompare" ], "notes": [ "app/service/systems/storage/entry.js receivingCompare 重写:批量校验收货单后合并全部有效收货单明细,新增 _buildMergedComparison(替代 _compareSingleReceiving)输出单一对照视图", "出参结构调整:comparisons[](按收货单拆分)改为 comparison[](合并后逐行对照,每个入库明细仅一行)+ receiving_only[] + summary;matched 行新增 receiving_quantity/receiving_allocated/receiving_available(合并值)与 receiving_sources[](各收货单来源明细),entry_only 行对应数量为 0 且 receiving_sources 为空", "total_summary.matched_count 语义调整为有效参与对比的收货单数(原为处理成功的对照数);无效收货单仍进入 errors[]", "同步更新 methods/system.json 中 receivingCompare 的 response 结构说明" ], "module": "storage.entry" }, { "version": "2026.08.23-returnUnpack.video-url-cdn-domain", "date": "2026-08-23", "type": "fixed", "summary": "修复拆包视频地址未拼接 CDN 域名的问题:returnUnpack.list / returnUnpack.detail / returnUnpack.videoList / returnUnpack.queryByWaybill 输出的 videos[].video_url 此前直接返回相对路径(如 /recordings/...),与 order.packing 输出完整 URL 的口径不一致。现在按打包侧相同规则拼接 http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{path}(录制电脑从 wms_print_computer 按 is_recording=true 获取,无录制电脑时保持原始路径)。", "methods": [ "returnUnpack.list", "returnUnpack.detail", "returnUnpack.videoList" ], "notes": [ "app/service/systems/return_unpack.js 新增 _getRecordingComputerId/_buildVideoUrl(与 order_packing.js 同口径,带实例级缓存)", "_enrichRow 视频派生块内对 videos[].video_url 拼接域名(覆盖 list/detail/submit 输出)", "videoList 按 unpack_id 反查 warehouse_id 后拼接;queryByWaybill(inbox 查退回)的 videos 同样拼接", "同步更新 methods/system.json 中 returnUnpack.list 与 returnUnpack.detail 的响应字段描述" ], "module": "returnUnpack" }, { "version": "2026.08.23-stock.warehouse-cache-invalidate-on-update", "date": "2026-08-23", "type": "fixed", "summary": "修复商品资料更新后 getStockDetails 详情缓存未清除的问题:saveWarehouseStock/handleBatchChange 使用 StockWarehouse.update 批量更新(不触发实例级 afterUpdate hook),导致 cache:stock_detail:{warehouseId}:{stockId} 旧数据在 TTL 内持续被读取(如 need_recheck 修改后复核扫描仍返回旧值)。现在两个编辑入口更新成功后显式调用 stockWarehouse.invalidateStockDetailCache 清除对应缓存。", "methods": [ "stock.warehouse.saveWarehouseStock", "stock.warehouse.handleBatchChange" ], "notes": [ "app/service/systems/stock_store.js saveWarehouseStock 提交事务后调用 service.systems.stockWarehouse.invalidateStockDetailCache(id, warehouseId)(失败仅告警不阻断主流程)", "同文件 handleBatchChange 批量更新后按 ids 批量清除详情缓存(Promise.allSettled,失败不阻断返回)", "实证验证:更新后 Redis 缓存 key 被删除,复核扫描/统一查询立即读取到新值" ], "module": "stock" }, { "version": "2026.08.23-recheckOrder.stock-need-recheck", "date": "2026-08-23", "type": "enhanced", "summary": "order.recheckOrder.scanOrder / scanTask 返回报文的 stock 明细新增 need_recheck 字段(Y=需要复核,N=不需要复核,缺省 Y):散单路径 enrichOrdersWithStock 组装与团购路径 buildGroupWaveList 的 stocks 映射均透出,供前端按商品判断是否免复核。", "methods": [ "order.recheckOrder.scanOrder", "order.recheckOrder.scanTask" ], "notes": [ "app/service/systemMethods/order/recheckOrder.js enrichOrdersWithStock stock 对象新增 need_recheck(取 getStockDetails 返回值,缺省 'Y')", "同文件 buildGroupWaveList 的 stocks 映射新增 need_recheck", "同步更新 methods/system.json 中 scanOrder 的 stock children 与 scanTask 的 stock 字段描述" ], "module": "order" }, { "version": "2026.08.23-stock.warehouse-need-recheck", "date": "2026-08-23", "type": "enhanced", "summary": "wms_stock_warehouse 新增 need_recheck(是否需要复核)字段:Y=需要复核(默认),N=不需要复核,非空。编辑(saveWarehouseStock/createWarehouseStock/getInfo/handleBatchChange)、导入(import 支持中文 需要/不需要 或 Y/N,缺省新建默认 Y、更新保留原值)、导出(仓库/外仓导出新增「是否需要复核」列,与导入列名对齐)全链路支持。", "methods": [ "stock.warehouse.getInfo", "stock.warehouse.saveWarehouseStock", "stock.warehouse.createWarehouseStock", "stock.warehouse.import", "stock.warehouse.handleBatchChange", "stock.warehouse.export", "stock.warehouse.externalExport" ], "notes": [ "database/migrations/20260823150000-add-need-recheck-to-wms-stock-warehouse.js 新增迁移(CHAR(1) NOT NULL DEFAULT 'Y',comment: 是否需要复核:Y=需要复核,N=不需要复核)", "app/model/stock_warehouse.js 新增 need_recheck 字段定义(默认 Y、非空)", "app/service/systems/stock_store.js getInfo attributes 增加 need_recheck;saveWarehouseStock 解构/更新数据增加 need_recheck;createWarehouseStock 解构并默认 'Y';validateSaveParams 校验非 Y/N 值报错;handleBatchChange 白名单增加 need_recheck 并校验 Y/N;exportWarehouseStock/exportExternalWarehouseStock 行数据输出中文 需要/不需要 并新增「是否需要复核」导出列", "app/service/systemMethods/stock/warehouse.js saveWarehouseStock 解构并透传 need_recheck;_normalizeWarehouseImportRow 解析「是否需要复核/need_recheck/needRecheck」列并新增 _normalizeNeedRecheckValue 归一化(需要→Y,不需要→N,非法值报错,缺省不覆盖)", "同步更新 methods/system.json 中 getInfo/saveWarehouseStock/createWarehouseStock/import/handleBatchChange 的字段说明" ], "module": "stock" }, { "version": "2026.08.23-pick.intercepted-skip-claim-pick", "date": "2026-08-23", "type": "fixed", "summary": "拦截订单不再阻隔领料/拣货且不参与作业数量:pick.waveClaimScan 打印校验与领料更新跳过拦截订单(拦截未打印不阻隔领料、拦截订单不置为 claim_status=fin,响应 data 新增 intercepted_order_count);pick.query 领料前置校验仅统计非拦截未领料订单(拦截未领料不阻隔拣货,fail data 新增 intercepted_order_count);pick.createWavePickTask 新增 excludeUnclaimed 选项,普通波次(source=0)创建拣货任务计算拣货数量(order_count/任务订单/筐)时剔除未领料订单。", "methods": [ "pick.waveClaimScan", "pick.query", "pick.wavePickComplete" ], "notes": [ "app/service/systemMethods/pick.js waveClaimScan 波次订单查询 attributes 增加 intercept_status,拦截订单集合不参与 unclaimed/unprinted 统计且不参与 claim_status=fin 更新", "app/service/systemMethods/pick.js 新增 getWaveClaimGateStats 辅助方法(统计 total/intercepted/unclaimed,unclaimed 仅计非拦截订单),query 领料门禁改用该统计", "app/service/systemMethods/pick.js createWavePickTask 新增 params.excludeUnclaimed(默认 false):为 true 时 attributes 增加 claim_status 并剔除 claim_status != fin 订单(未领料不参与 order_count/任务订单/筐数量);query 与 wavePickComplete 对普通波次(source=0)传 excludeUnclaimed=true(wavePickComplete 波次查询 SELECT 增加 source)", "同步更新 methods/system.json 中 pick.query 与 pick.waveClaimScan 的 description、400 错误说明与 response 字段" ], "module": "pick" }, { "version": "2026.08.23-returnUnpack.list-video-fields", "date": "2026-08-23", "type": "enhanced", "summary": "returnUnpack.list 对齐打包记录补齐视频字段:列表关联查询视频副表,每条记录新增 has_video(1=有视频记录/2=无)、video_enable(1=录像可用/2=不可用)派生字段与 videos 视频数组(id/video_url/status/camera_id/camera_name),并新增 has_video / video_enable 列表筛选(EXISTS 字面量,口径与 order.packing.list 一致)。", "methods": [ "returnUnpack.list" ], "notes": [ "app/service/systems/return_unpack.js list 改 raw:false 并 include ReturnUnpackVideo as videos(deleted_at IS NULL 过滤 + Camera 关联精简字段),行数据经 _flattenVideos 输出精简视频数组;_enrichRow 对含 videos 数组的记录派生 has_video/video_enable(create 幂等复用与 detail 返回同步受益,videos 结构不变);_buildListWhere 新增 has_video/video_enable 筛选(1/2,EXISTS/NOT EXISTS 字面量)", "同步更新 methods/system.json 中 returnUnpack.list 的 params(where.has_video / where.video_enable)与 response list 字段说明" ], "module": "returnUnpack" }, { "version": "2026.08.22-order.print-custom-area-wave-multiply-qty", "date": "2026-08-22", "type": "enhanced", "summary": "面单自定义区商品明细行尾新增「波次总单数×该行商品数量」:当波次 wms_wave_batch.source=0(普通波次)且 wave_type=1 时,每条商品明细行尾追加 波次总单数 × 该行商品数量(如 500 单 × 3 件 = 1500);策略抓取波次(source=1/2)与其他波次类型不追加。", "methods": [ "order.print.getOrderPrintData", "order.print.getWavePlatformPrintData", "order.print.getPrintDataByWaybillCodes" ], "notes": [ "app/service/systems/order_print.js queryWavesByIds 查询增加 source/wave_type 字段;getWavePlatformPrintData / getOrderPrintData / getPrintDataByWaybillCodes 三条路径构建 waveMetaMap 并在订单行附加 wave_source / wave_type", "app/lib/printer_data_builder.js buildWaybillCustomProductInfoLines 明细行构建时 waveSource=0 且 waveType=1 且 wave_total_orders>0 时行尾追加 波次总单数×qtyNumber(商品数量与乘数之间以两个空格分隔);7 个平台映射(快手/拼多多/抖音/菜鸟/小红书/视频号/京东)同步传入 waveSource/waveType", "更新 test/app/lib/printer_data_builder_package_material.test.js:新增 T15(source=0 且 wave_type=1 行尾乘数)与 T16(source=1 不追加乘数)", "同步更新 methods/system.json 中三个打印方法的 description" ], "module": "order" }, { "version": "2026.08.22-order.print-custom-area-total-qty", "date": "2026-08-22", "type": "enhanced", "summary": "面单打印自定义区首行在快递渠道名后新增「商品总数【n】」:n 优先取订单级商品总数(items_total,权威字段),其次商品明细数量累加,最后 items_count(商品种类数)兜底,避免订单 items 快照宽松文本(stock_id+数量)陈旧不完整导致数量偏差;覆盖菜鸟/京东/拼多多/抖音/快手/视频号/小红书全平台自定义区。", "methods": [ "order.print.getOrderPrintData", "order.print.getWavePlatformPrintData", "order.print.getPrintDataByWaybillCodes" ], "notes": [ "app/lib/printer_data_builder.js buildWaybillCustomProductInfoLines 头部行在快递渠道名后追加 商品总数【n】:fallbackTotalQty(items_total)>0 时优先,否则 safeItems 逐项 resolveItemQuantity 累加,再否则 fallbackItemsCount(items_count)兜底;7 个平台映射(快手/拼多多/抖音/菜鸟/小红书/视频号/京东)分别传入 fallbackTotalQty=items_total、fallbackItemsCount=items_count", "更新 test/app/lib/printer_data_builder_package_material.test.js(T10 包材前缀断言排除商品总数标签、新增 T11 商品总数累加、T12 items_total 兜底优先、T13 items 快照宽松文本不完整时取 items_total、T14 无 items_total 时回退明细累加)与 test/app/service/systems/order_print.getWavePlatformPrintData.test.js(W023 头部行断言追加 商品总数【2】)", "同步更新 methods/system.json 中三个打印方法的 description" ], "module": "order" }, { "version": "2026.08.22-pick.query-wave-claim-gate-source0", "date": "2026-08-22", "type": "enhanced", "summary": "pick.query 新增领料前置校验(仅普通波次 source=0):扫描命中普通波次时,若波次内存在未领料订单(claim_status != fin)则返回 400 并携带 action=wave_claim 提示「订单未领料,请先领料后再拣货」,阻隔开始拣货(中止拣货任务创建);已全部领料或策略抓取波次(source=1/2)不拦截。", "methods": [ "pick.query" ], "notes": [ "app/service/systemMethods/pick.js query 波次查询 SELECT 增加 source 字段并记录 targetWaveSource;目标波次信息校验后插入领料前置校验:source=0 时查询波次订单 claim_status,存在未领单订单 fail 400(data 含 action=wave_claim、wave_id、wave_no、wave_type、wave_source、pick_mode、unclaimed_order_count、total_order_count)", "同步更新 methods/system.json 中 pick.query 的 description 与 400 错误说明" ], "module": "pick" }, { "version": "2026.08.22-stock.warehouse.import-barcode-sync", "date": "2026-08-22", "type": "fixed", "summary": "修复 stock.warehouse.import 传入 barcode(条码)不生效的问题:归一化后条码未在新建/更新路径写入 wms_stock_barcodes 表。现在导入行携带非空 barcode 时,在商品创建/更新成功后调用 saveWarehouseStockBarcode 差异同步条码(未传条码则保留原有条码)。", "methods": [ "stock.warehouse.import" ], "notes": [ "app/service/systemMethods/stock/warehouse.js import():创建/更新成功后,若归一化 barcode 为非空数组,则按结果 id(缺省用行内 SKU)调用 systems.stockStore.saveWarehouseStockBarcode 同步到 wms_stock_barcodes 表", "条码同步失败计入该行 fail_items,且该行不再计入成功计数,便于定位", "未传 barcode(空数组)时不触发同步,避免误清空已有条码;barcode 格式与导出对齐(逗号分隔字符串)" ], "module": "stock.warehouse" }, { "version": "2026.08.22-storage.inventory.list-filter-zero-quantity", "date": "2026-08-22", "type": "enhanced", "summary": "storage.inventory.list 过滤总数量为 0 的商品或明细行:基础查询条件增加 quantity > 0,明细模式(group_by_batch=true)不再返回 quantity=0 的明细行,合并模式(group_by_batch=false)不再返回总数量为 0 的商品。storage.inventory.export 同步保持一致。", "methods": [ "storage.inventory.list", "storage.inventory.export" ], "notes": [ "app/service/systems/storage/inventory.js:getInventoryList 与 exportInventoryList 的 baseWhere 均增加 { quantity: { [Op.gt]: 0 } },动态 where/stock_query 条件不受影响", "明细模式:quantity=0 的 storage 行直接过滤;合并模式:某商品所有明细行均无正数量时分组自然消失,总量为 0 的商品不返回", "storage.inventory.export 入参与 list 语义保持一致(导出同样过滤零量行/零量商品)" ], "module": "storage.inventory" }, { "version": "2026.08.22-storage.inventory.listByStockId-group-by-space", "date": "2026-08-22", "type": "enhanced", "summary": "storage.inventory.listByStockId 新增 group_by_space 双模式:false(默认,不汇总)逐条返回 quantity > 1 明细行(含批次/效期/预警字段,行为不变);true(按库位汇总)先筛 quantity > 1 明细行,再按 space_id 汇总 quantity/locked_quantity/available_quantity,返回库位级汇总行(含 batch_count、first/last_inbound_time、stock/space/store_name),不含批次与效期/预警字段。", "methods": [ "storage.inventory.listByStockId" ], "notes": [ "app/service/systems/storage/inventory.js:getStorageListByStockId(stockId, groupBySpace=false) 两种模式共用同一查询(先筛 quantity > 1 明细行),group_by_space=true 时用新增 _aggregateStorageRowsBySpace 按 space_id 在内存汇总(求和、批次数、最早/最晚入库时间),并保留商品/库位关联与条码图片附属信息", "app/service/systemMethods/storage/inventory.js:listByStockId 透传 group_by_space(支持 true/'true' 布尔/字符串)", "汇总口径:先筛 quantity > 1 的明细行再按库位求和;汇总行不返回批次与效期/库存预警字段" ], "module": "storage.inventory" }, { "version": "2026.08.22-storage.inventory.store-stock-join-dedup", "date": "2026-08-22", "type": "fixed", "summary": "修复库存接口按 stock_id 查询返回重复 storage 行(同 id 多条)的问题:store_stock 关联(belongsTo StoreWarehouse,按 store_id 关联)未按仓库收敛,货主在多仓库存在签约行时 JOIN 多行匹配导致同一库存行重复且 store_name 不一致。改为统一使用 StoreWarehouse.buildStoreStockInclude(按 warehouse_id + warehouse_use_status=1 收敛,命中唯一签约行)。", "methods": [ "storage.inventory.listByStockId", "storage.inventory.list" ], "notes": [ "app/service/systems/storage/inventory.js:getStorageListByStockId、getInventoryList(明细模式与合并模式)三处 store_stock 嵌套 include 均改为 buildStoreStockInclude({ warehouseId, required: false, attributes: ['store_id','store_remask'] })", "wms_store_warehouse 存在 (store_id, warehouse_id) 唯一索引,按仓库收敛后每商品至多命中一行签约关系,不再产生重复明细;合并模式下 SUM(quantity) 也不会因 JOIN 多行而翻倍", "同时修正 storage.inventory.list 同源隐患(明细模式重复行、合并模式数量翻倍),返回结构不变" ], "module": "storage.inventory" }, { "version": "2026.08.22-storage.inventory.listByStockId", "date": "2026-08-22", "type": "added", "summary": "新增 storage.inventory.listByStockId 接口:传入 stock_id,返回该商品在当前仓库下所有 quantity > 1 的 wms_storage 明细行(按 id 倒序),返回结构与 storage.inventory.list 明细模式一致(含 stock 条码/图片、space 库位、货主名称及效期/库存预警字段)。", "methods": [ "storage.inventory.listByStockId" ], "notes": [ "app/service/systemMethods/storage/inventory.js 新增 listByStockId 包装方法,并加入 _noNeedRight/_noNeedLog/_noNeedAuth 豁免列表(与 list 一致)", "app/service/systems/storage/inventory.js 新增 getStorageListByStockId:校验 stock_id 正整数与当前仓库上下文,where 条件 warehouse_id+stock_id+quantity>1+is_enabled=1+delete_at=null,include stock/space 与明细模式一致", "重构 getInventoryList 明细分支:提取 _loadInventoryWarningRanges 与 _formatBatchStorageRows 复用,现有 storage.inventory.list 行为不变" ], "module": "storage.inventory" }, { "version": "2026.08.21-returnUnpack.create-orderItems", "date": "2026-08-21", "type": "enhanced", "summary": "returnUnpack.create 返回新增顶层 order_items 字段:原订单商品明细数组(即 order.items 的顶层透出,含 item_code/item_name/sku_property/quantity/plan_qty/barcodes/image_url 等),仅原单退回且原订单详情解析成功时返回;非原单退回或原订单详情缺失时为 null。新建与幂等复用两个分支返回结构一致。", "methods": [ "returnUnpack.create" ], "notes": [ "app/service/systems/return_unpack.js create:新建分支返回 order_items(order.items 为数组时透出,否则 null);幂等复用分支从 detail().related.order 提取同名字段,与 order 字段同源", "向后兼容:仅新增顶层字段,order/record 等既有字段不变", "同步更新 methods/system.json 中 returnUnpack.create 的 response(新增 order_items 字段说明)" ], "module": "returnUnpack" }, { "version": "2026.08.21-stock.warehouse.search-return-images", "date": "2026-08-21", "type": "enhanced", "summary": "stock.warehouse.search 默认模式返回数据新增 images 字段:批查 wms_file_reference(business_type=stock)+ wms_file 获取商品图片URL列表,按 display_order 升序;无图片时返回空数组。mode=\"combo\" 时不返回该字段。", "methods": [ "stock.warehouse.search" ], "notes": [ "app/service/systems/stock_store.js search:formattedResults 生成后批量查询 FileReference(include File.file_url,raw),按 business_id(商品ID)分组注入 item.images,与 stock.warehouse.list 图片口径一致", "同步更新 methods/system.json 中 stock.warehouse.search 的 response 字段" ], "module": "stock" }, { "version": "2026.08.21-order.pendingOrder.cloneOrder-sync-status-inherit", "date": "2026-08-21", "type": "enhanced", "summary": "order.pendingOrder.cloneOrder 同步状态继承原订单:原订单已同步(sync_status=fin)时新订单直接置 fin,避免克隆后重复回传平台;原订单未同步/同步失败(padding/error)则重置为 padding 重新走同步流程。", "methods": [ "order.pendingOrder.cloneOrder" ], "notes": [ "app/service/systemMethods/order/pendingOrder.js cloneOrder 第 4 步 newOrderData.sync_status 按 original.sync_status 判定:fin→fin,其余→padding(RESET_FIELDS 保留 padding 兜底)", "已同步新订单分配运单号不受 sync_status 限制(createWaybillCodePipeline 只校验 step 1/2/3/4、status、拦截、锁定、已分配运单号),但新订单 step=0 需先审核进入待处理才能分配;已同步订单分配新运单号后不会自动回传平台", "同步更新 methods/system.json 中 cloneOrder 的 description" ], "module": "order" }, { "version": "2026.08.21-order.pendingOrder.cloneOrder-storage-release-tolerant", "date": "2026-08-21", "type": "enhanced", "summary": "order.pendingOrder.cloneOrder 支持克隆已同步(sync_status=fin)订单且库存释放失败不阻断:原订单已分配储位时先清除已分配库存,cancelAllocateStorage 失败降级为告警(与 cancelOrder 策略一致),克隆继续执行;残留占用保留在原订单名下,克隆新订单不重新占用库存(storage_status=none,创建过程不触发储位分配与库存锁定)。", "methods": [ "order.pendingOrder.cloneOrder" ], "notes": [ "app/service/systemMethods/order/pendingOrder.js cloneOrder 第 2 步:清除已分配库存失败由抛错阻断改为 ctx.logger.warn 降级,不影响克隆主流程", "克隆新订单库存零占用(storage_status 重置 none、无自动储位分配),后续如需发货需在待处理工作台重新分配储位", "同步更新 methods/system.json 中 cloneOrder 的 description" ], "module": "order" }, { "version": "2026.08.21-order.pendingOrder.cloneOrder-unique-delivery-code", "date": "2026-08-21", "type": "fixed", "summary": "修复 order.pendingOrder.cloneOrder 复制原单号导致唯一键冲突:新订单 delivery_order_code 重新生成(SYS+时间戳+随机4位,与 createOrder 同规则),原单号写入 pre_delivery_order_code 保留克隆追溯链;此前复制原单号会命中 (delivery_order_code, store_id, warehouse_id) 唯一索引,克隆报「Validation error」且原订单已被取消、新订单未创建(原订单损坏)。", "methods": [ "order.pendingOrder.cloneOrder" ], "notes": [ "app/service/systemMethods/order/pendingOrder.js cloneOrder:COPY_FIELDS 移除 delivery_order_code,新订单单号改为 SYS${Date.now()}${1000~9999 随机} 生成;原订单无 pre_delivery_order_code 时写入原单号保留追溯链;注释说明唯一索引约束与 UniqueConstraintError 表现", "同步更新 methods/system.json 中 cloneOrder 的 description" ], "module": "order" }, { "version": "2026.08.21-index.searchSpaces-batch-search", "date": "2026-08-21", "type": "added", "summary": "新增 index.searchSpaces 批量库位查询接口:keywords 传入字符串数组,逐项按当前仓库上下文模糊查询(space_code/custom_barcode/custom_name,每项最多 50 条),结果按传入顺序以二维数组返回,无记录对应项返回空数组。", "methods": [ "index.searchSpaces" ], "notes": [ "app/service/systems/space.js 抽取 _searchByKeyword 私有查询方法(searchSpace 与 searchSpaces 共用同一查询口径),新增 searchSpaces 并行查询每个关键字并保持传入顺序输出,无记录项返回 []", "app/service/systemMethods/index.js 新增 searchSpaces 出口方法,并加入 _noNeedRight/_noNeedAuth 白名单(与 searchSpace 一致,免鉴权免权限、需登录)", "同步更新 methods/system.json 与 AI_METHOD_ROUTING.md" ], "module": "index" }, { "version": "2026.08.20-order.wave.matched-count-same-express-split", "date": "2026-08-20", "type": "fixed", "summary": "order.wave.waveStrategyList 的 matched_order_count_filtered 计数口径与按策略抓取保持一致:require_same_express=1 的策略按「结构(items_hash)+快递」分组计数并应用 min/max_same_structure,不再仅按结构分组统计,避免列表显示有命中订单但 waveStrategyFetchAdmin 实际抓取为 0 的口径不一致。", "methods": [ "order.wave.waveStrategyList" ], "notes": [ "app/service/systemMethods/order/wave.js getWaveStrategyMatchedOrderCountFilteredMap 改为接收策略行数组并按 require_same_express 拆分两类计数查询:同快递策略按 items_hash+快递(sys_logistics_code>logistics_code>logistics_name COALESCE 口径)分组,其余仅按 items_hash 分组;max_same_structure<=0 视为不设上限,与抓取候选 SQL 归一化一致;调用方 waveStrategyList 改传当前页策略行 list", "同步更新 methods/system.json 中 matched_order_count_filtered 字段描述" ], "module": "order" }, { "version": "2026.08.20-pick.waveClaimScan-print-gate", "date": "2026-08-20", "type": "enhanced", "summary": "pick.waveClaimScan 新增波次打印校验:整波领料前检查波次下全部订单 print_status,存在未打印订单(print_status != fin)时返回 400「波次未打印,禁止领料」(data 含 wave_id、wave_no、unprinted_order_count、total_order_count),波次全部打印后才允许将订单 claim_status 置为 fin;已全部领料幂等结果优先返回,不受打印校验拦截。", "methods": [ "pick.waveClaimScan" ], "notes": [ "app/service/systemMethods/pick.js waveClaimScan 波次订单查询 attributes 增加 print_status,already_claimed 幂等判断之后插入打印校验:unprinted_order_count > 0 时 fail 400「波次未打印,禁止领料」", "同步更新 methods/system.json 中 pick.waveClaimScan 的 description 与 400 错误说明" ], "module": "pick" }, { "version": "2026.08.20-pick.waveClaimScan-source-gate", "date": "2026-08-20", "type": "enhanced", "summary": "pick.waveClaimScan 整波领料资格判定收敛为仅普通波次(wms_wave_batch.source=0)生效:符合时将该波次下全部未领单订单 claim_status 置为 fin 并返回 wave_id/wave_no 与领单说明;策略抓取波次(source=1/2)返回「该波次为抓取波次,无需领料」(data 含 no_claim_needed=true、wave_id、wave_no);波次已全部领料返回 already_claimed 并提示「该波次已领料,无需重复领取」;面单号无记录/订单不在待处理订单表返回 404 无记录提示。", "methods": [ "pick.waveClaimScan" ], "notes": [ "app/service/systemMethods/pick.js waveClaimScan 资格判定由(大团购 wave_type=1 且 pick_mode=5 / 非抓取散单 wave_type=2 且 source=0)改为仅按 source 判定:source=0 全部支持整波领料,source∈{1,2} 返回抓取波次无需领料并携带 no_claim_needed=true、wave_id、wave_no,其余返回不支持提示;already_claimed tip 改为「该波次已领料,无需重复领取」", "app/dict/businessDict.js OPERATION_CODE 补记 ORDER_WAVE_CLAIM:'领取波次'", "同步更新 methods/system.json 中 pick.waveClaimScan 的 description/400/404 错误说明" ], "module": "pick" }, { "version": "2026.08.19-print-custom-area-stock-merge", "date": "2026-08-19", "type": "fixed", "summary": "修复打印自定义区同库位不同商品被合并为一行的问题:拣货明细聚合键由「库位」改为「库位+stock_id」复合键,仅同一库位同一商品才合并数量;stock_id 缺失时依次回退 order_item_id、商品名称+条码,无法识别商品身份时不再跨行合并。", "methods": [ "order.print.getOrderPrintData", "order.print.getWavePlatformPrintData", "order.print.getPrintDataByWaybillCodes" ], "notes": [ "app/service/systems/order_print.js buildPrintOrderRowMapWithPicking 阶段五聚合改为 buildPrintItemAggregationKey 复合键(pick_location::stock:stock_id),同库位不同商品保持独立行,数量/条码不再串;stock_id 字段延迟到聚合完成后才删除,避免污染 items JSON" ], "module": "order" }, { "version": "2026.08.19-pick.claim-prompt-refine", "date": "2026-08-19", "type": "enhanced", "summary": "领料提示文案细化:pick.query 领单前置校验拦截时直接提示「订单未领料,请先领料后再拣货」;pick.waveClaimScan 对抓取的波次(团购小波次 pick_mode=1、策略抓取散单波次 source=1/2)返回「该波次为抓取波次,无需领料」提示(失败 data 新增 no_claim_needed=true),其余未知类型保留通用不支持提示。", "methods": [ "pick.query", "pick.waveClaimScan" ], "notes": [ "app/service/systemMethods/pick.js query 领单前置校验拦截文案由「该波次尚未领单,请先整波领单后再拣货」改为「订单未领料,请先领料后再拣货」,action=wave_claim 等失败 data 字段不变", "app/service/systemMethods/pick.js waveClaimScan 资格判定失败时细分提示:抓取波次(wave_type=2 且 source∈{1,2},或 wave_type=1 且 pick_mode=1)返回「该波次为抓取波次,无需领料」并携带 no_claim_needed=true;其他未知类型保留「当前波次类型不支持整波领单」", "同步更新 methods/system.json 中 pick.query 与 pick.waveClaimScan 的 description/400 错误说明" ], "module": "pick" }, { "version": "2026.08.19-pick.query-wave-claim-gate", "date": "2026-08-19", "type": "enhanced", "summary": "pick.query 新增领单前置校验:扫描命中的波次属于大团购(pick_mode=5)或非抓取散单(wms_wave_batch.source=0 普通波次)时,若波次内存在未领单订单(claim_status != fin)则返回 400 并携带 action=wave_claim 提示先整波领单(pick.waveClaimScan),中止拣货任务创建;已全部领单则继续原流程。", "methods": [ "pick.query" ], "notes": [ "app/service/systemMethods/pick.js query 在解析目标波次后、活动任务去重前插入领单校验:复用 getWavePickModeByWaveId 与 wms_wave_batch.source 判定波次类型(大团购=wave_type 1 且 pick_mode 5;非抓取散单=wave_type 2 且 source 0),查询波次订单 claim_status,存在未领单订单时 fail 400(data 含 action=wave_claim、wave_id、wave_no、wave_type、wave_source、pick_mode、unclaimed_order_count、total_order_count)", "同步更新 methods/system.json 中 pick.query 的 description 与 400 错误说明" ], "module": "pick" }, { "version": "2026.08.19-pick.waveClaimScan", "date": "2026-08-19", "type": "enhanced", "summary": "新增 pick.waveClaimScan 整波领单接口:PDA 扫描波次内一个面单号后,针对大团购(pick_mode=5 团购大波次)与非抓取的散单(wms_wave_batch.source=0 普通波次)将该波次下全部订单 claim_status 置为 fin(领单完成),并写入 ORDER_WAVE_CLAIM 订单操作日志;团购小波次与策略抓取散单波次不支持整波领单,返回 400;波次已全部领单时返回 already_claimed 幂等结果。", "methods": [ "pick.waveClaimScan" ], "notes": [ "app/service/systemMethods/pick.js 新增 waveClaimScan:面单号定位订单(wms_order_express.waybill_code)→ 订单定位波次 → 读取 wms_wave_batch(wave_type/source)与拣货任务 pick_mode 判定资格(大团购=wave_type 1 且 pick_mode 5;非抓取散单=wave_type 2 且 source 0)→ 整波订单 claim_status='fin',并新增 getWavePickModeByWaveId 查询关联拣货模式", "app/service/systemMethods/pick.js 鉴权配置:waveClaimScan 加入 _noNeedRight/_noNeedAuth(免权限、免仓库有效期校验),保留登录校验与请求日志", "app/dict/businessDict.js OPERATION_CODE 新增 ORDER_WAVE_CLAIM:'领取波次'", "同步更新 methods/system.json 中 pick.waveClaimScan 接口文档" ], "module": "pick" }, { "version": "2026.08.19-manual-order-stock-store-guard", "date": "2026-08-19", "type": "fixed", "summary": "手工单(order.pendingOrder.createOrder)新增库存归属货主校验:item_id 直接传仓库 stock_id 时,校验 wms_stock_warehouse.store_id 与订单货主 store_id 一致,跨货主传库存将被拒绝,杜绝把其他货主库存挂在当前货主订单下。", "methods": [ "order.pendingOrder.createOrder" ], "notes": [ "app/service/systems/delivery_order.js addOrderLines 手工单分支(line.stockId)新增 StockWarehouse 归属校验,不一致时计入 errors 并跳过该行,错误文案:商品《xxx》编码《xxx》库存归属货主(store_id=…)与当前货主(store_id=…)不一致,无法创建订单", "同步更新 methods/system.json 中 order.pendingOrder.createOrder 的 notes 说明" ], "module": "order" }, { "version": "2026.08.19-wave-fallback-excluded-reason-cn-label", "date": "2026-08-19", "type": "enhanced", "summary": "order.wave.waveStrategyFallbackOrderList 响应 excluded_reason 由英文枚举值改为中文标签:locked→已锁定、intercepted→已拦截、printed→已打印、no_match→未匹配策略。", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "app/service/systemMethods/order/wave.js 新增 WAVE_STRATEGY_FALLBACK_EXCLUDED_REASON_LABELS 常量并用于 buildWaveStrategyFallbackOrderListItem,判定优先级不变", "同步更新 methods/system.json 中该接口 excluded_reason 字段与 list 说明" ], "module": "order" }, { "version": "2026.08.19-wave-fallback-excluded-reason-lock-fix", "date": "2026-08-19", "type": "fixed", "summary": "修复 order.wave.waveStrategyFallbackOrderList 所有行 excluded_reason 恒为 locked 的问题:列表行经 normalizeOrderListItem 后 lock_status 已归一化为 Y/N,原判断 lock_status !== 'none' 恒成立导致全部误标 locked;改为兼容归一化值(Y=锁定,N/none/空=未锁定)与原始值(warehouse/store 等),恢复 locked/intercepted/printed/no_match 的正确判定。", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "app/service/systemMethods/order/wave.js buildWaveStrategyFallbackOrderListItem 新增 lockStatus 归一化与 isLocked 判定(Y 或非 none/非 N 的原始值视为锁定),excluded_reason 优先级不变:locked > intercepted > printed > no_match" ], "module": "order" }, { "version": "2026.08.19-order-list-wave-index-range-filter", "date": "2026-08-19", "type": "enhanced", "summary": "订单列表 where 新增 wave_index 波次内序号范围查询入参:工作台订单列表(经 listByModule 的 9 个列表)与订单导出支持 wave_index 虚拟筛选(eq/in/gt/lt/ge/le/between/notbetween,between 要求 value 为长度 2 的数组);复核散单列表支持 wave_index between 与 wave_index_min/wave_index_max。", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list", "order.recheckOrder.recheckOrderList", "order.recheckOrder.queryRecheckOrderSingleList" ], "notes": [ "新增 app/model/order_wave_index.js 模型(wms_order_wave_index,timestamps=false),供副表条件查询", "app/service/systemMethods/order/base.js 新增 extractWaveIndexVirtualFilter(从 where 提取 wave_index/waveIndex,兼容数值简写按 eq 处理)与 findOrderIdsByWaveIndexCondition(用 parseWhereConditions 解析条件后查副表得 order_id 集合);listByModule 在 stock_query 之后接入,命中为空时主查询结果为空", "app/service/systems/order_export.js exportOrders 同样接入 wave_index 虚拟筛选,与列表 where 语义一致", "app/service/systemMethods/order/recheckOrder.js queryRecheckOrderSingleList 新增 wave_index 筛选(between/gte/lte/eq 或 wave_index_min/wave_index_max),countSql 同步 LEFT JOIN wms_order_wave_index 保持总数一致", "同步更新 methods/system.json 中 order.list 与复核列表 where 参数说明" ], "module": "order" }, { "version": "2026.08.19-order-list-wave-index-join", "date": "2026-08-19", "type": "enhanced", "summary": "所有订单列表统一联查 wms_order_wave_index 并输出 wave_index(波次内序号,无记录时降级为 0):覆盖 9 个工作台订单列表(order.list / reviewOrder.list / pendingOrder.list / outboundOrder.list / expectionOrder.list / entrustOrder.list / deliveryOrder.list / deliveryExpectionOrder.list / archiveOrder.list)、复核散单列表与波次策略兜底列表;订单导出(waybill/item 两种模式)新增「波次序号」列。", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list", "order.recheckOrder.recheckOrderList", "order.recheckOrder.queryRecheckOrderSingleList", "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "app/service/systemMethods/order/base.js 新增 attachOrderWaveIndex:按列表行 id 批量查询 wms_order_wave_index(warehouse_id + order_id,命中唯一索引),无记录或查询异常时降级为 0 并告警;listByModule 在 attachOrderExpressNumbers 之后接入,统一覆盖全部工作台订单列表", "app/service/systemMethods/order/wave.js waveStrategyFallbackOrderList 接入 attachOrderWaveIndex,buildWaveStrategyFallbackOrderListItem 输出 wave_index(默认 0)", "app/service/systemMethods/order/recheckOrder.js queryRecheckOrderSingleList 列表 SQL 增加 LEFT JOIN wms_order_wave_index(warehouse_id + order_id),响应行新增 wave_index;recheckOrderList 散单分支同源生效", "app/service/systems/order_export.js exportOrders 接入 attachOrderWaveIndex,ORDER_EXPORT_COLUMNS / ORDER_EXPORT_ITEM_COLUMNS 在波次号后新增「波次序号」列,mapOrderExportRow commonFields 新增 wave_index", "同步更新 methods/system.json 中上述接口的 response 字段说明" ], "module": "order" }, { "version": "2026.08.19-recheckOrder.confirmIntercept-ids", "date": "2026-08-19", "type": "enhanced", "summary": "order.recheckOrder.confirmIntercept 入参由单值 order_id 改为批量 ids:支持数组或以逗号分隔的字符串(兼容 id/order_id/orderId 单值写法),批量确认拦截,返回 success/failed 列表与 success_count/failed_count 计数;单个订单失败不再阻断整体,未找到订单与更新失败订单记录在 failed 列表", "methods": [ "order.recheckOrder.confirmIntercept" ], "notes": [ "app/service/systemMethods/order/recheckOrder.js confirmIntercept:用 base.normalizeOrderIds 解析 ids(兼容 ids/id/order_id/orderId),findAll 批量查询后逐订单执行拦截主流程(intercept_status=intercepted_at_warehouse、step=4、outbound_status=fin,运单标记 is_back/is_intercept='Y',释放储位分配与订单锁,写入 ORDER_INTERCEPT_CONFIRM 操作日志),未找到订单与处理异常订单记录 failed 不抛错,仅 ids 全部无效时 400「订单ID列表不能为空」", "确认拦截前置校验:仅拦截发起中状态(requested/requesting/intercepting,历史值 intercepted 兼容)允许确认;未发起拦截(none/空)的订单直接静默跳过不参与处理,已确认拦截(intercepted_at_warehouse)订单跳过避免重复副作用并记录 failed「订单已确认拦截」,其余非可确认状态(intercepted_in_transit/returning/returned/delivered_by_mistake/timeout/cancelled/failed/exception)记录 failed「订单拦截状态不允许确认拦截: {状态}」;更新 SQL where 同时限定 intercept_status 白名单(CONFIRMABLE_INTERCEPT_STATUSES),防止查询后状态被并发修改导致误更新", "售后工单+快递群通知由原每订单调用改为按成功订单 ID 汇总后统一调用一次 afterSale.createInterceptWorkOrdersAndNotify,失败仅告警", "返回结构由单对象改为 { success, failed, success_count, failed_count },success 每项保持 order_id/order_no/intercept_status/updated_at,failed 每项含 order_id/delivery_order_code/reason", "同步更新 methods/system.json 中该接口 params(ids)、response 与 errors 文档" ], "module": "order.recheckOrder" }, { "version": "2026.08.18-order-list-lock-status-filter-doc", "date": "2026-08-18", "type": "enhanced", "summary": "订单列表 where 补充 lock_status 筛选说明:未锁定传 lock_status=none,已锁定(所有非 none)传 lock_status={operator:ne,value:none};筛选用数据库原始枚举 none/warehouse/store 而非响应 Y/N,条件值为空自动忽略。", "methods": [ "order.pendingOrder.list" ], "notes": [ "仅文档补充,无代码改动:methods/system.json 中 order.pendingOrder.list 的 where 参数 description 增加 lock_status 筛选说明", "行为依据:app/service/systemMethods/order/base.js listByModule/buildWhere 对 where 无字段白名单(仅禁止 warehouse_id/warehouseId),可直接传订单表列名;app/lib/query_condition_parser.js 支持 ne 操作符且条件值为空时自动忽略(isEmptyValue 跳过)", "lock_status 数据库原始枚举 none/warehouse/store(app/model/order_delivery.js LOCK_STATUS),列表响应仍统一输出 Y/N(normalizeLockStatusFlag:none→N,其余→Y),筛选入参必须用原始枚举而非响应 Y/N", "同样经 listByModule 的其它工作台订单列表(order.reviewOrder.list / order.outboundOrder.list / order.expectionOrder.list / order.entrustOrder.list / order.deliveryOrder.list / order.deliveryExpectionOrder.list / order.archiveOrder.list)where 语义一致,本次保持其文档不变,重点仅更新 order.pendingOrder.list" ], "module": "order" }, { "version": "2026.08.18-setting.expressInterface.update-doc-params", "date": "2026-08-18", "type": "enhanced", "summary": "补全 setting.expressInterface.update 接口文档:入参由 3 个字段扩展为全量可更新字段(含 town_name/townName、is_enabled/isEnabled、providertype 等),并补充全量响应字段与错误码说明。", "methods": [ "setting.expressInterface.update" ], "notes": [ "入参按 app/service/systems/setting/expressInterface.js update() 与包装层 app/service/systemMethods/setting/expressInterface.js update() 实际支持的字段补齐,含驼峰别名(shopId/townName/isEnabled 等),仅传入的字段被更新", "响应按 normalizeInterfaceRow 返回结构补齐全量字段", "仅文档变更,无代码改动" ], "module": "setting.expressInterface" }, { "version": "2026.08.18-order-lock-status-guard-and-list-yn", "date": "2026-08-18", "type": "enhanced", "summary": "新增锁定订单作业门禁与订单列表 lock_status 转 Y/N:lock_status 非 none(枚举 warehouse/store)的订单在分配储位、分配快递、抓取波次、自动加团等流程中被直接跳过,跳过明细通过 skipped_locked_order_ids / excluded_locked_order_ids / skipped_orders 等字段返回;订单列表 lock_status 统一输出 Y/N(none→N,其余→Y)。", "methods": [ "order.pendingOrder.list", "order.pendingOrder.allocateExpressCode", "order.pendingOrder.allocateStorage", "order.wave.singleFetchByIds", "order.wave.waveStrategyFallbackOrderList", "order.wave.batchAllocateExpress", "order.wave.batchAllocateExpressTaskProgress", "order.wave.batchAllocateStorage", "order.wave.batchAllocateStorageTaskProgress" ], "notes": [ "新增 app/lib/lock_guard.js isLockedOrderStatus:lock_status 非 'none' 即视为已锁定(枚举 none/warehouse/store)", "app/service/systems/order_storage_allocation.js allocatePicking:过滤循环新增锁定订单跳过,skipped 记录含 lock_status 与 skipped_reason='locked';order.storageAllocation.allocateStorage / order.pendingOrder.allocateStorage / order.wave.batchAllocateStorage 共用该底层入口", "app/service/systems/express.js createWaybillCodePipeline:查询新增 lock_status 字段,锁定订单与拦截订单同样剔除,返回结果新增 skipped_locked_order_ids", "app/service/systemMethods/order/wave.js runBatchAllocateExpressTask:查询新增 lock_status,任务进度与 result 新增 skipped_locked_order_ids;singleFetchByIds 查询属性新增 lock_status 并过滤锁定订单,响应新增 excluded_locked_order_ids(两个返回分支均返回);waveStrategyFallbackOrderList 查询追加 lock_status/intercept_status 非 none 条件,列表行新增 excluded_reason(locked/intercepted/printed/no_match)", "app/service/systems/delivery_order.js asyncProcessOrderCreated:订单已锁定时跳过自动分配快递/储位/自动加团三步;appendOrderToWave 增加锁定校验且更新波次时 where 追加 lock_status='none';countCandidateGroupOrders 过滤 lock_status='none'(内部流程,无公开接口)", "app/service/systemMethods/order/base.js 新增 normalizeLockStatusFlag:none(含空值)返回 'N',其余值一律返回 'Y';normalizeOrderListItem 统一覆盖 lock_status 输出为 Y/N,影响 order.pendingOrder.list、order.wave.waveStrategyFallbackOrderList 及经 listByModule 的各类工作台订单列表", "同步更新 methods/system.json 中上述 method 的 description 与 response 字段" ], "module": "order" }, { "version": "2026.08.18-storage.entry.addItem-non-binding", "date": "2026-08-18", "type": "fixed", "summary": "库存导入(storage.entry.addItem 导入/PDA 入库)不再强制绑定收货单:原 PENDING 状态下未绑定收货单拒绝上架、每项缺少 receiving_detail_id 拒绝,导致移除绑定收货单后仍限制必须传入收货单 ID。现 PENDING 状态允许不绑定收货单直接导入(非绑定模式,数量受计划数量限制),传 receiving_detail_id 时仍走绑定模式(预占收货明细)", "methods": [ "storage.entry.addItem" ], "notes": [ "app/service/systems/inbound_direct_log.js addItem:删除 PENDING 状态下 hasReceivingBindings 与 receiving_detail_id 的强制校验,绑定模式 space_id/可用数量校验仍由 _addSingleItem 统一处理;CREATED 已绑定收货单需先审核的限制保留", "PENDING 非绑定模式导入数量仍受计划数量限制(isManualImport 仅 CREATED 且非绑定可超计划),防止超计划入库", "同步更新 methods/system.json 中 storage.entry.addItem 的 description、receiving_detail_id 参数说明与错误码列表(移除两条 PENDING 绑定错误码)" ], "module": "storage.entry" }, { "version": "2026.08.18-recheckOrder.scanOrder.singleIntercept", "date": "2026-08-18", "type": "fixed", "summary": "修复 order.recheckOrder.scanOrder 散单模式拦截订单识别:原逻辑对波次内所有订单执行复核校验,只要波次内存在一单已进入拦截流程(requested/requesting/intercepting/intercepted_in_transit/intercepted_at_warehouse,历史值 intercepted 兼容),整个散单扫描视图即报错「订单已被拦截,无法提交复核」,导致波次内其他正常订单也无法复核。现拦截订单保留在 list 中按单提示(intercept_status),不再阻断整个扫描视图加载,且不计入复核/打印统计", "methods": [ "order.recheckOrder.scanOrder", "order.recheckOrder.scanTask" ], "notes": [ "buildSingleWaveScanView:用 isInterceptedOrderStatus 分离拦截订单,仅非拦截订单参与 assertOrderCanRecheck 校验与 reviewed/unreviewed/printed/unprinted 统计,拦截订单保留在 list 中按单提示", "车号/任务模式(cart/task)合并多个波次后,reviewed_count/unreviewed_count 仅统计非拦截订单,total_orders 仍为订单总数", "同步更新 methods/system.json 中 scanOrder 散单订单项 intercept_status 字段说明" ], "module": "order" }, { "version": "2026.08.17-inbox-group-reset", "date": "2026-08-17", "type": "enhanced", "summary": "新增 inbox.group.reset 群操作接口:入参群记录主键ID,清空群类型配置(group_type/sub_type/store_id/express_interfaces/system_express_code 置空、ai_enabled 重置为0),仅保留群创建时信息(群名称/群ID/仓库/来源/屏蔽状态/扩展数据)", "methods": [ "inbox.group.reset" ], "notes": [ "app/service/systems/inbox/group.js reset:仓库隔离按主键 id 定位群,清空类型相关字段并写操作日志,返回重置后群信息", "app/service/systemMethods/inbox.js 新增 groupReset,注册到 inbox.group 子入口", "数据库迁移 20260817120000-add-inbox-group-reset-permission.js:权限ID 556 授权角色 8/26/28/29", "同步更新 methods/system.json 中 inbox.group.reset 接口文档" ], "module": "inbox.group" }, { "version": "2026.08.17-afterSale-handleWorkOrder-remark-notify-group", "date": "2026-08-17", "type": "enhanced", "summary": "afterSale.handleWorkOrder 处理备注同步发送到对应货主售后群:填写 remark 时推送到货主售后群(工单 store_id 定位,缺失时从来源消息所在群反查货主,不转发快递群);消息内容格式为「【工单 售后单号】处理备注:备注内容」;响应新增 notified_groups 返回发送群数量", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "app/service/systems/afterSale.js handleWorkOrder:新增 notifyGroup 参数(方法层交互处理传 true,内部自动处理如库内拦截/退回已收到不传),事务提交后按 remark 非空发送:store_id 定位货主 → findStoreAfterSalesGroups 发货主售后群;无 store_id 时按 inbox_message_id 查来源消息 group_id → InboxGroup 反查 store_id 再发送;发送失败仅告警不影响处理结果", "app/service/systemMethods/afterSale.js handleWorkOrder:调用 systems 层时传 notifyGroup: true", "同步更新 methods/system.json 中 afterSale.handleWorkOrder 的 description、remark 参数说明与 notified_groups 响应说明" ], "module": "afterSale" }, { "version": "2026.08.16-waybill-createAt-between", "date": "2026-08-16", "type": "enhanced", "summary": "waybill.warehouse.list / export 创建时间筛选统一为 between 区间写法:where.createdAt 支持 {operator:\"between\", value:[起始,结束]},保留 createdAtStart/createdAtEnd 旧写法兼容", "methods": [ "waybill.warehouse.list", "waybill.warehouse.export" ], "notes": [ "app/service/systems/waybill.js list/export:createdAt 数组区间两端可单独为空,分别落 create_at gte/lte;同时兼容 createAt 别名与 createdAtStart/createdAtEnd 旧写法", "同步更新 methods/system.json 中 waybill.warehouse.list / export 的 where.createdAt 参数文档" ], "module": "waybill.warehouse" }, { "version": "2026.08.16-order-packing-list-time-filter", "date": "2026-08-16", "type": "enhanced", "summary": "order.packing.list 时间筛选统一为 between 区间写法:start_time / end_time / create_time 支持 {operator:\"between\", value:[起始,结束]},与已有 start_time_start/start_time_end 旧写法兼容", "methods": [ "order.packing.list" ], "notes": [ "app/service/systems/order_packing.js list:新增 applyTimeRangeFilter,统一处理 start_time/end_time/create_time 的 between 区间条件(数组两端可单独为空,按 gte/lte 拼接),与 warehouse_id 隔离及其他筛选叠加", "保留 start_time_start/start_time_end 旧拆分写法的兼容处理", "同步更新 methods/system.json 中 order.packing.list 的 where 参数文档" ], "module": "order.packing" }, { "version": "2026.08.16-waybill-export-ids", "date": "2026-08-16", "type": "enhanced", "summary": "waybill.warehouse.export 新增 where.ids 入参:支持按运单ID列表(勾选)导出快递号,与仓库隔离条件叠加过滤", "methods": [ "waybill.warehouse.export" ], "notes": [ "app/service/systems/waybill.js export:新增 where.ids 处理,数组值经 Number 转换并过滤非法值后生成 id IN (...) 条件,与 warehouse_id 隔离条件叠加,不影响其他筛选字段", "入口层 systemMethods/waybill/warehouse.js export 原样透传 where,无需改动", "同步更新 methods/system.json 中 waybill.warehouse.export 的 where.ids 参数文档" ], "module": "waybill.warehouse" }, { "version": "2026.08.15-packing-setEndTime-cap", "date": "2026-08-15", "type": "enhanced", "summary": "order.packing.setEndTime 增加结束时间上限约束:传入结束时间超过仓库配置的打包最大时长上限(散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes)时,自动截断为 开始时间+上限时长 后落库", "methods": [ "order.packing.setEndTime" ], "notes": [ "app/service/systems/order_packing.js setEndTime:结束时间不能早于开始时间校验之后,复用 workbench.resolvePackTaskEndTime 做上限截断(按 pack_mode 区分散单/团购配置,未配置有效时长时不约束)", "截断使用最终值落库与响应(end_time/status 同步返回截断后的时间)", "与 workbench.finishPack / packOrder 关闭旧任务 / 定时任务自动结束 的 end_time 上限语义对齐", "同步更新 methods/system.json 中 order.packing.setEndTime 的 description、end_time 参数与响应说明" ], "module": "order.packing" }, { "version": "2026.08.15-pack-task-end-time-cap", "date": "2026-08-15", "type": "enhanced", "summary": "打包任务结束时间增加上限约束:工作台结束任务时(finishPack 手动结束、packOrder 关闭上一个未结束任务),若结束时间超过仓库配置的打包最大时长上限(散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes),自动截断为 开始时间+上限时长", "methods": [], "notes": [ "app/service/systems/workbench.js 新增 resolvePackTaskEndTime:按 warehouse_id+pack_mode 读取配置上限分钟,候选结束时间超过 开始时间+上限 时返回上限时间点,未配置有效时长或 start_time 非法时不约束", "_packOrder 步骤4 关闭上一个未结束任务、_finishPack 手动结束 两处结束路径统一接入约束,_finishPack 响应 end_time 同步返回约束后的时间", "与定时任务 auto_finish_pack_task 语义一致:end_time 最多为 开始时间+上限时长,自动结束与手动结束行为对齐", "创建任务时即完成(packStatus>=2)的场景 end_time=start_time,不超上限,无需处理" ], "module": "setting.warehouse" }, { "version": "2026.08.15-pack-task-auto-finish", "date": "2026-08-15", "type": "added", "summary": "新增打包任务自动结束定时任务(每小时一次):扫描 wms_pack_task 未结束任务,按仓库配置 single_order_pack_max_minutes(散单,默认 3 分钟)/ group_order_pack_max_minutes(团购,默认 40 分钟)判断超时,当前时间-开始时间超过上限时将 end_time 置为开始时间+上限时长并标记已完成", "methods": [], "notes": [ "新增 app/schedule/auto_finish_pack_task.js:interval 1h、type worker、非 immediate,单 worker 防重入(ctx.app._autoFinishPackTaskRunning)", "新增 app/service/systems/pack_task_auto_finish.js:扫描 status < 2 且 start_time 非空的任务,按 warehouse_id 去重后经 deliveryOrder.getStoreSubjectConfig(缓存优先)拉取配置,pack_mode=2 按团购时长、其余按散单时长", "超时判定:当前时间 - 开始时间 > 配置分钟数;结束时间 = 开始时间 + 上限时长(而非当前时间),status 置为 2", "未配置有效时长(缺失或非正整数)的仓库跳过,不做自动结束;任务 start_time 非法时跳过", "配置字段与仓库设置联动:single_order_pack_max_minutes / group_order_pack_max_minutes 已在 WAREHOUSE_SETTING_FIELDS 与 Store.normalizeSubjectConfig 中注册,默认值 3 / 40 分钟" ], "module": "setting.warehouse" }, { "version": "2026.08.15-warehouse-pack-max-minutes", "date": "2026-08-15", "type": "added", "summary": "仓库设置 setting.warehouse 新增打包最大时长配置:single_order_pack_max_minutes 散单打包最大时长(分钟,默认 3)、group_order_pack_max_minutes 团购打包最大时长(分钟,默认 40)", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings" ], "notes": [ "在 WAREHOUSE_SETTING_FIELDS 中新增 single_order_pack_max_minutes(integer,非必填,默认 3,min 1)与 group_order_pack_max_minutes(integer,非必填,默认 40,min 1)", "wms_store.subject_config 默认值同步补齐(app/model/store.js DEFAULT_SUBJECT_CONFIG),normalizeSubjectConfig 增加大于 0 的整数校验,空值回退默认", "methods/system.json 中 getSettings 响应与 saveSettings 入参补充对应字段文档", "向后兼容:新增字段为可选,不影响既有仓库设置读写" ], "module": "setting.warehouse" }, { "version": "2026.08.15-recheckOrder.scanOrder.groupInterceptSeq", "date": "2026-08-15", "type": "fixed", "summary": "修复 order.recheckOrder.scanOrder 团购模式拦截订单识别:原逻辑仅匹配不存在的 'intercepted' 状态,导致已进入拦截流程的订单(requested/requesting/intercepting/intercepted_in_transit/intercepted_at_warehouse)被当作正常订单,团购复核数据不输出拦截订单及其序号。现统一按真实拦截状态枚举归类到波次项 intercepted 列表,并输出 wave_index 波次内序号", "methods": [ "order.recheckOrder.scanOrder", "order.recheckOrder.scanTask" ], "notes": [ "新增 isInterceptedOrderStatus 辅助方法:intercepted / requested / requesting / intercepting / intercepted_in_transit / intercepted_at_warehouse 均视为拦截流程状态", "buildGroupWaveList 拦截订单分离改用 isInterceptedOrderStatus,拦截订单不再进入正常订单校验与统计,仓库已拦截订单不再阻断整个团购扫描视图加载", "团购波次项 intercepted 列表每项新增 waybill_no 字段,wave_index 为波次内序号(优先读取 wms_order_wave_index 真实序号,无记录时降级数组临时序号)", "confirmRecheckByWaveId 团购波次批量复核同步修正拦截识别,拦截订单不再被批量标记复核", "同步更新 methods/system.json 中 scanOrder 团购波次项 intercepted 字段说明" ], "module": "order" }, { "version": "2026.08.15-parseAddress.batch", "date": "2026-08-15", "type": "enhanced", "summary": "parseAddress 支持数组批量入参:addresses(或 address)传字符串数组时批量解析,响应 data.list 按输入顺序返回每条地址的解析结果(含失败条目逐条错误信息)", "methods": [ "order.pendingOrder.parseAddress" ], "notes": [ "入参兼容三种形态:address 字符串(单条,原行为不变)、address 字符串数组、addresses 字符串数组(优先)", "批量解析:按每 10 条合并为一个 DeepSeek 请求并行发出(deepseek-v4-flash),全部返回后按输入顺序聚合,单次上限 50 条;失败/缺失条目逐条回退单条解析,不影响其他条目", "批量响应 data.list 每条元素包含 address/flag/message/province/city/area/town/detailAddress/name/mobile,失败条目 flag=failure、message 为具体错误原因、解析字段为空字符串,不影响其他条目", "抽取 _parseSingleAddress 私有方法复用单条解析逻辑,单条响应结构与之前完全一致", "同步更新 methods/system.json 中 parseAddress 的参数与响应字段说明" ], "module": "order" }, { "version": "2026.08.14-afterSale.detail-desc-first-step", "date": "2026-08-14", "type": "enhanced", "summary": "enhance: afterSale.detail 步骤列表默认将售后详细描述作为第一条 step 输出(虚拟步骤不落库),保证详情页首条即可看到售后问题描述。", "methods": [ "afterSale.detail" ], "notes": [ "售后主表 description 非空时,steps 列表头部前置一条虚拟步骤:action=售后描述、remark=description、step_status=pending、created_at=主表创建时间、attachments=[]、is_virtual=true、id=null", "虚拟步骤不写入 wms_after_sale_detail,仅在 detail 响应中动态拼接", "after_sale.started_at 仍取首条真实步骤记录的创建时间,不受虚拟步骤影响", "description 为空时不生成虚拟步骤,行为与之前一致", "同步更新 methods/system.json 中 afterSale.detail 的 steps 字段说明" ], "module": "afterSale" }, { "version": "2026.08.14-afterSale.workList-storeName", "date": "2026-08-14", "type": "changed", "summary": "afterSale.workList 返回列表行新增 store_name 货主名称字段:取合约表 wms_store_warehouse.store_remask 货主备注名称,无合约或备注为空时回退 wms_store.company_name 公司全称,无货主时为空字符串", "methods": [ "afterSale.workList" ], "notes": [ "systems/afterSale.js list() 新增 opts.enrichStoreName 开关,开启后调用新增私有方法 _enrichListStoreNames 批量补充:按行收集 store_id/warehouse_id,一次查询 StoreWarehouse(store_remask)与 Store(company_name),映射后写入每行 store_name", "systemMethods/afterSale.js workList 调用 list 时传 enrichStoreName: true;auditList 不受影响", "向后兼容:仅在列表行新增 store_name 字段,不影响既有字段", "同步更新 methods/system.json 中 afterSale.workList 的 response.list 字段说明" ], "module": "afterSale" }, { "version": "2026.08.14-returnUnpack.stockDetails", "date": "2026-08-14", "type": "changed", "summary": "returnUnpack 明细补充库存详情:detail/detailList/addDetail/updateDetail 返回的明细行统一走 stockWarehouse.getStockDetails 通用方法附加 stock 字段(item_code/item_name/sku_property/barcodes 条码数组/image_url 图片数组/packing_requirements/stock_unit/quantity/locked_quantity 等,带缓存),补齐条码与照片信息;create 幂等复用返回的 record.details 同步受益", "methods": [ "returnUnpack.detail", "returnUnpack.detailList", "returnUnpack.addDetail", "returnUnpack.updateDetail", "returnUnpack.create" ], "notes": [ "systems/return_unpack.js 新增私有方法 _enrichDetailsWithStock:收集明细 stock_id 批量调用 stockWarehouse.getStockDetails(缓存 key cache:stock_detail:{warehouseId}:{stockId}),按 stock_id 映射为明细行 stock 字段;未识别明细(stock_id 为空)/商品失效/拉取失败时 stock=null,不影响主流程", "detail:record.details 逐条附加 stock;detailList:list 逐条附加 stock(取首行 warehouse_id 作为查询仓库);addDetail/updateDetail:返回 detail 附加 stock(用主表 warehouse_id)", "向后兼容:明细行原有字段与 stockWarehouse 关联保持不变,仅新增 stock 字段", "同步更新 methods/system.json 中 create/detail/detailList/addDetail/updateDetail 的响应字段说明" ], "module": "returnUnpack" }, { "version": "2026.08.14-returnUnpack.createReuse", "date": "2026-08-14", "type": "changed", "summary": "returnUnpack.create 增加幂等复用:同一仓库同一运单号 3 个月内已存在非 cancelled 拆包单时不重复创建,直接返回已有拆包单的主表+明细(record.details)+视频+原订单详情,并携带 reused=true 标识;同运单号多张拆包单时优先复用已录明细的最新单;超过 3 个月视为运单号复用,按新单正常创建", "methods": [ "returnUnpack.create" ], "notes": [ "开单前先按 warehouse_id+waybill_code+created_at>=3个月前 查全部非 cancelled 拆包单(created_at DESC, id DESC)", "同运单号存在多张拆包单时优先复用已录明细的最新单(按 wms_return_unpack_detail 真实计数判定,不依赖主表冗余 total_items),避免命中并发/重复点击产生的空单导致返回明细为空;全部无明细时复用最新单", "命中时复用 detail 查询逻辑组装 record(含 details 明细+stockWarehouse 关联、videos、returnReceived)与 related.order,返回字段新增 reused=true", "查重失败仅记日志不阻断开单主流程;3 个月时间基准与退回查询记录反查货主窗口一致", "同步更新 methods/system.json 中 returnUnpack.create 的 description 与 response(record/reused 字段说明)" ], "module": "returnUnpack" }, { "version": "2026.08.14-warehouse-receive-address", "date": "2026-08-14", "type": "added", "summary": "仓库设置 setting.warehouse 新增仓库收货地址配置字段 receiver_address(一行文本,退货/退件收件地址)", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings" ], "notes": [ "在 WAREHOUSE_SETTING_FIELDS 中新增 receiver_address(string,非必填,默认空字符串,最大长度 500)", "wms_store.subject_config 默认值同步补齐(app/model/store.js DEFAULT_SUBJECT_CONFIG)", "methods/system.json 中 getSettings 响应与 saveSettings 入参补充对应字段文档", "向后兼容:新增字段为可选,不影响既有仓库设置读写" ], "module": "setting.warehouse" }, { "version": "2026.08.13-stockQueryWhere", "date": "2026-08-13", "type": "added", "summary": "storage.receiving.getReceivingList / getStoreReceivingList 新增 stock_query_where 参数:按商品条码/商品编码/商品ID 搜索,经收货明细关联过滤收货单列表(仓库侧与货主侧同步支持)", "methods": [ "storage.receiving.getReceivingList", "storage.receiving.getStoreReceivingList" ], "notes": [ "新增 stock_query_where 入参(string|string[], optional, body,前端通常传数组),搜索范围:wms_stock_barcodes.barcode + wms_stock_warehouse.item_code + wms_stock_warehouse.id(纯数字时精确匹配)", "解析链路:stock_query_where → wms_stock_warehouse.id 集合 → wms_receiving_detail.system_product_id IN 集合 → receiving_id 列表", "与 filterDepleted、entry_order_id 可组合使用(多组过滤取交集,仓库侧),无匹配结果时返回空列表", "代码变更:systems/storage/receiving.js 新增 _resolveStockQueryReceivingIds 并对两个列表方法注入过滤;systemMethods/storage/receiving.js 两个列表方法均透传 stock_query_where;methods/system.json 两个接口均新增参数文档" ], "module": "storage" }, { "version": "2026.08.12-confirmIntercept-doc", "date": "2026-08-12", "type": "updated", "summary": "order.recheckOrder.confirmIntercept 文档描述补全:补充释放储位分配、释放订单锁等副作用说明,明确各副作用失败不阻断主流程的容错语义", "methods": [ "order.recheckOrder.confirmIntercept" ], "notes": [ "description 补充:拦截成功后会释放储位分配(cancelAllocateStorage)与订单锁(lock_status=none)", "description 补充:储位释放、锁释放、日志写入失败均不影响主流程(try/catch 容错)", "仅文档变更,不修改业务代码" ], "module": "order" }, { "version": "2026.08.12-interceptScan", "date": "2026-08-12", "type": "added", "summary": "order.recheckOrder.interceptScan 新增拦截扫描接口:通过运单号查找运单,标记退回+拦截(is_back='Y', is_intercept='Y');运单记录不存在时自动创建补充;处理关联售后工单(写入「库内拦截成功」并完结);订单级拦截覆盖所有面单含子面单(与 confirmIntercept 一致)", "methods": [ "order.recheckOrder.interceptScan" ], "notes": [ "入参:waybill_code(string, required),运单号", "运单记录不存在时自动创建(INSERT wms_order_express),而非抛 404,确保缺失快递被补充", "同时设置 is_back='Y' 和 is_intercept='Y'", "查 wms_after_sale 表(未完结工单),命中则调用 handleWorkOrder 写入「库内拦截成功」步骤并置 status=completed;工单处理失败不阻断主流程", "订单拦截与 confirmIntercept 一致:只要有 order_id 即更新 wms_order_delivery.intercept_status = intercepted_at_warehouse,并释放储位分配与订单锁,写入 ORDER_INTERCEPT_CONFIRM 操作日志;不再区分 business_key,子面单同样会触发订单级拦截", "免权限/免日志/免鉴权(与 confirmIntercept 同级)", "代码变更:recheckOrder.js 构造函数 + interceptScan 方法(~180行);methods/system.json 新增 API 文档" ], "module": "order" }, { "version": "2026.08.10-storageTransaction-keyword", "date": "2026-08-10", "type": "updated", "summary": "storage.transaction.list 新增 keyword 快捷搜索参数,支持按 item_code(商品编码) 和 barcode(条码) 模糊匹配,内部解析为 stock_id 列表后以 IN 条件合并到查询中", "methods": [ "storage.transaction.list" ], "notes": [ "新增 keyword 参数(string, optional),搜索范围为 stock_warehouse.item_code + stock_barcodes.barcode", "keyword 解析复用已有 _resolveKeywordToStockIds 方法,与 stock.report.search 的 keyword 解析逻辑一致", "keyword 可与 where 条件叠加使用(交集),无匹配结果时直接返回空列表", "代码变更:stock_transaction.js list() 增加 keyword 参数并在 baseWhere 中注入 stock_id IN 条件;systemMethods/storage/transaction.js 透传 keyword" ], "module": "storage" }, { "version": "2026.08.10-stockTransaction-keyword-doc", "date": "2026-08-10", "type": "updated", "summary": "stock.transaction.list 补全 keyword 快捷搜索参数文档。代码层已支持 keyword(通过 queryList → _resolveKeywordToStockIds),本次仅补文档", "methods": [ "stock.transaction.list" ], "notes": [ "新增 where.keyword 参数文档(string, optional),搜索范围为 stock_warehouse.item_code/item_name/goods_code + stock_barcodes.barcode + SKU ID", "keyword 解析复用已有 _resolveKeywordToStockIds 方法,与 stock.report.search 逻辑一致", "keyword 与 stock_ids 互斥(keyword 优先),无匹配结果时返回空列表", "仅文档变更,不修改业务代码" ], "module": "stock" }, { "version": "2026.08.09-afterSale-doc", "date": "2026-08-09", "type": "updated", "summary": "补全 afterSale 组全部 11 个 method 的文档:workList/auditList/detail/create/transfer/handleWorkOrder/registerClaim/export/exportTaskProgress/workCount 的 params 与 response 补全 description,移除 create 中冗余 warehouse_id 参数(后端自动注入),明确各枚举值、关联表、业务语义。", "methods": [ "afterSale.workList", "afterSale.auditList", "afterSale.detail", "afterSale.create", "afterSale.transfer", "afterSale.handleWorkOrder", "afterSale.registerClaim", "afterSale.export", "afterSale.exportTaskProgress", "afterSale.workCount" ], "notes": [ "afterSale.create:移除 warehouse_id 参数(后端从 ctx.user.store_id 自动注入),补全所有 12 个参数的 description(含 type/sub_type 枚举值),response 新增 status 和 role_group 字段。", "afterSale.transfer:补全 id/role_group/remark 的 description,response 新增 role_group 字段。", "afterSale.handleWorkOrder:补全 action/status/attachment_ids 的 description,明确 action 示例和 status 枚举。", "afterSale.registerClaim:补全 10 个参数的 description,明确 claim_status/carrier_claim_status 枚举值(pending/reviewing/approved/paid/monthly/rejected)。", "afterSale.workList/auditList:补全 pagination/where/sort 与 response 的 description。", "afterSale.export/exportTaskProgress:补全参数和响应的 description,明确 task_id 用途。", "afterSale.workCount:已有完整 description,本次未修改。", "仅文档变更,不修改任何业务代码或接口语义。" ], "module": "afterSale" }, { "version": "2026.08.07-stockout-express", "date": "2026-08-07", "type": "changed", "summary": "wms_order_stockout 表新增 express_code / express_codes 字段;storage.stockout.confirm 改为读表字段回传,不再随机生成;新增 storage.stockout.updateExpress 接口。", "methods": [ "storage.stockout.confirm", "storage.stockout.updateExpress" ], "notes": [ "DB 迁移:20260807120000-add-express-code-to-wms-order-stockout.js 添加 express_code VARCHAR(50) 和 express_codes JSON 字段。", "Model:order_stockout.js 新增 express_code / express_codes 字段定义。", "storage.stockout.confirm:回传时不再随机生成 expressCode,改为读取表中 express_code / express_codes;express_code 为空则拒绝确认(400)。", "storage.stockout.updateExpress:新增接口,用于在确认前更新运单号,支持 express_code(单个)和 express_codes(列表)两个字段。", "qimenMethods/stockout.js confirm 同步调整,透传 expressCodes。" ], "module": "storage" }, { "version": "2026.08.07-stockout-confirm", "date": "2026-08-07", "type": "added", "summary": "新增 storage.stockout.confirm 直出确认接口:不改变内部库存,按出库单明细计划数量直接确认,状态推进到 COMPLETED。", "methods": [ "storage.stockout.confirm" ], "notes": [ "入参:id(出库单ID,必填)。", "逻辑:校验 canConfirm (CREATED/PENDING) → 事务内更新 order_status=COMPLETED、actual_qty=plan_qty。", "返回:id、stockout_order_code、order_status、logisticsName(固定OTHER)、expressCode(随机生成)。", "对应奇门 stockout.confirm 接口,由 qimenMethods/stockout.js confirm 方法调用。" ], "module": "storage" }, { "version": "2026.08.07-stockout-list-fix", "date": "2026-08-07", "type": "changed", "summary": "修复 storage.stockout.list / listItems 读错表:从 OrderDeliveryFactory/OrderItemsFactory 改为直接读取 OrderStockout/OrderStockoutItems 模型(wms_order_stockout 表)。", "methods": [ "storage.stockout.list", "storage.stockout.listItems" ], "notes": [ "list:数据源 OrderDeliveryFactory → OrderStockout;软删字段 delete_at → deleted_at;快速搜索字段适配 stockout_order_code/remark;排序字段适配 order_status/order_type/created_at/order_create_time。", "listItems:数据源 OrderDeliveryFactory+OrderItemsFactory → OrderStockout+OrderStockoutItems;参数 delivery_order_code → stockout_order_code(兼容旧参数名)。", "response 字段 items → list,与实际返回一致。" ], "module": "storage" }, { "version": "2026.08.06-inbox-bindCode", "date": "2026-08-06", "type": "added", "summary": "新增货主绑群码生成接口。校验 StoreWarehouse 合约有效性后生成12位随机码(大写字母+数字),缓存 key 为 chat:bind:{warehouseId}:{code},TTL 300秒。实现位于 systems/store.js → bindCode(),由 systemMethods/inbox.js → bindCode() 委托调用。", "methods": [ "inbox.bindCode" ], "notes": [ "调用链:/system → systemMethods/inbox.bindCode → systems/store.bindCode。", "前置校验:StoreWarehouse 合约 auth_status=2 AND warehouse_use_status=1,不满足则返回500。", "缓存策略:app.setCacheAsync('chat:bind:{warehouseId}:{code}', { store_id, initiator_subject_id, warehouse_id, group_type, sub_type }, 300)。", "绑定时消费:processor.tryBindGroup 匹配 '授权:CODE' 模式,读取缓存执行绑定,成功即清缓存。", "warehouseId:从 ctx.user.store_id 自动注入,前端无需传递。" ], "module": "inbox" }, { "version": "2026.08.05-inbox-group", "date": "2026-08-05", "type": "added", "summary": "站内信模块新增群管理接口:群列表拉取、群禁用/解禁、群信息修改(支持群类型/子类型/货主/快递接口/系统快递编码)、按群查询消息列表。仓库ID由服务端自动注入。express_interfaces输出为数组,systemExpressCode在express类型时必填校验。", "methods": [ "inbox.group.list", "inbox.group.disable", "inbox.group.update", "inbox.group.messages" ], "notes": [ "inbox.group.list:按群类型/关键词筛选,分页返回。express_interfaces 存储逗号分隔输出数组。", "inbox.group.disable:通过群主键ID禁用/解禁(isBlocked=1禁用/0启用)。", "inbox.group.update:支持修改groupType/subType/storeId/expressInterfaces/systemExpressCode。切换为express类型时systemExpressCode必填且需校验wms_express.code存在,expressInterfaces需校验wms_express_interface.id存在。非express类型忽略express相关字段。", "inbox.group.messages:按groupId拉取消息列表,支持direction/keyword筛选,仓库隔离,查询命中idx_warehouse_group_created索引。", "公共:所有方法warehouseId均从ctx.user.store_id自动注入,前端无需传递。" ], "module": "inbox" }, { "version": "2026.08.01-system-01", "date": "2026-08-01", "type": "added", "summary": "新增 apiApp 仓库 API 应用管理模块,支持当前仓库维度的 API 应用 CRUD、AppKey/Secret 自动生成与重新生成、IP 白名单、回调地址、限流等配置", "methods": [ "apiApp.list", "apiApp.detail", "apiApp.create", "apiApp.update", "apiApp.delete", "apiApp.regenerateSecret" ], "notes": [ "apiApp.list:分页查询当前仓库 API 应用列表,支持按 app_name(模糊)、is_enabled 筛选,Secret 自动脱敏(前8位+****)。", "apiApp.detail:按 ID 查询单个应用详情,需同时匹配 warehouse_id(自动注入 ctx.user.store_id),Secret 脱敏。", "apiApp.create:创建应用时自动生成 AppKey(AK{yyyyMMddHHmmss}{random8hex})和 AppSecret(64位hex)。默认 interface_type_id 取 WH_CHANNEL。仅创建时返回完整 Secret。", "apiApp.update:更新可编辑字段(app_name、self_ip_whitelist、callback_url、rate_limit、sign_method、is_enabled),不可变字段为 self_app_key 和 interface_type_id。", "apiApp.delete:软删除(is_enabled=0),不物理删除。", "apiApp.regenerateSecret:重新生成 64位hex AppSecret,旧 Secret 立即失效。仅此次返回完整 Secret。", "仓库隔离:所有操作按 ctx.user.store_id → warehouse_id 自动过滤。", "Secret 安全策略:list/detail/update 返回脱敏值,仅 create/regenerateSecret 返回完整 Secret。" ], "module": "apiApp" }, { "version": "2026.07.31-system-02", "date": "2026-07-31", "type": "added", "summary": "新增 storage.inventory.export 库存导出与 storage.inventory.exportTaskProgress 导出进度查询,入参复用 list 的 where/sort/group_by_batch 语义,支持两种导出模式(聚合汇总 / 逐条明细),库位信息一并导出", "methods": [ "storage.inventory.export", "storage.inventory.exportTaskProgress" ], "notes": [ "storage.inventory.export:异步提交导出任务,返回 task_id 与受理信息,后端异步生成 Excel 并上传。入参 where/sort/group_by_batch 与 storage.inventory.list 完全一致,无需额外学习成本。", "group_by_batch=false(默认):按 stock_id + space_id(库位)聚合导出库存汇总,含商品编码/名称/规格/单位/货主/库位编码/名称/总库存/锁定/可用/批次数/最近入库时间。", "group_by_batch=true:按 storage_id 逐条导出库存明细,含库存记录ID/商品信息/库位信息/批次号/库存类型/数量/生产日期/过期日期/入库时间/入库单号/供应商批次号。", "新增 storage.inventory.exportTaskProgress:按 task_id/taskId 查询导出任务进度与状态(submitted/running/success/failed/not_found),status=success 时返回 download_url 供客户端下载。", "导出文件目录:exports/storage/inventory/{warehouseId}/,缓存 TTL 1800 秒。" ], "module": "storage.inventory" }, { "version": "2026.07.31-system-01", "date": "2026-07-31", "type": "added", "summary": "新增按波次批量快捷复核接口 batchQuickRecheckByWave,支持批量波次 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败", "methods": [ "order.recheckOrder.batchQuickRecheckByWave" ], "notes": [ "新增 order.recheckOrder.batchQuickRecheckByWave 方法,复用 batchQuickRecheck 的 _completePickForOrder / _markRecheckForOrder / _tryCompleteWaveInTransaction 等内部事务方法", "入参 wave_ids 支持数组或逗号分隔字符串,兼容 waveIds(驼峰)、wave_id(单值)", "按波次维度批量查询订单后逐波次、逐订单执行前置校验与复核,每个订单独立事务,部分失败不影响其他订单", "响应包含 success/failed 列表及计数,failed 项含 order_id、wave_id、delivery_order_code、reason 说明;波次下无订单时仅返回 wave_id + reason" ], "module": "order.recheckOrder" }, { "version": "2026.07.29-system-01", "date": "2026-07-29", "type": "added", "summary": "补全 waybill.warehouse group API 文档参数定义:完善 list/detail/export 的 params 与 response,新增 exportTaskProgress 异步进度查询接口", "methods": [ "waybill.warehouse.list", "waybill.warehouse.detail", "waybill.warehouse.export", "waybill.warehouse.exportTaskProgress" ], "notes": [ "waybill.warehouse.list:params 含 pagination/where/sort 完整字段定义,where 支持 15 个筛选维度(运单号、主单号、订单ID、订单号、物流编码、物流接口ID、平台编码、状态、退回/拦截/星河签收、包材ID、已称重、关键词、创建时间范围),sort 白名单 create_at/weighing_weight/id。response 含 list(28 个字段)+ pagination。", "waybill.warehouse.detail:修正 id 参数为可选(required: false),与 waybillCode 二选一,waybillCode 优先。response 含 id/waybill_code/main_waybill_code/waybill_type/business_key/sibling_waybills/order/logistics/status_info/weight/package/print_records/print_count 等完整详情。", "waybill.warehouse.export:response 补充 progress/message/update_time 字段,完整覆盖异步任务返回信息。", "新增 waybill.warehouse.exportTaskProgress:按 task_id/taskId 查询导出进度,response 含 task_id/status/progress/current_count/total_count/message/result/error/download_url/update_time。", "所有接口 isNeedAuth: false, isNeedLogin: true,仓库隔离通过 ctx.user.store_id 自动注入。" ], "module": "waybill.warehouse" }, { "version": "2026.07.28-system-01", "date": "2026-07-28", "type": "added", "summary": "新增 order.pendingOrder.batchMarkPrinted:批量设置订单为已打印状态,将 print_status 更新为 'fin'", "methods": [ "order.pendingOrder.batchMarkPrinted" ], "notes": [ "同步批量更新接口,传入订单ID数组,直接将符合条件的订单 print_status 设为 'fin'。", "双表查询:先查 current 表(wms_order_delivery_{warehouseId}),未命中的 ID 再兜底查 dispatch 表(wms_order_delivery_{warehouseId}_dispatch)。", "dispatch 表查询失败仅记录 warn 日志,不影响 current 表已更新的结果。", "仅允许 step 在 [1,2,3] 且 status 不为 'cancel' 的订单操作,已打印(print_status='fin')的订单会被静默跳过。", "仓库上下文强制从 ctx.user.store_id 获取,禁止传入外部仓库ID。", "入参支持 order_ids / orderIds / ids 三种别名,优先级 order_ids > orderIds > ids。", "返回 updated_count 表示实际更新条数(current + dispatch 合计),ids 原样回传请求的订单ID列表。", "写入操作日志 operation_code: ORDER_BATCH_MARK_PRINTED。" ], "module": "order.pendingOrder" }, { "version": "2026.07.27-system-03", "date": "2026-07-27", "type": "changed", "summary": "storage.receiving 导出接口拆分:export 改为按仓库维度,新增 storeExport 按货主维度导出", "methods": [ "storage.receiving.export", "storage.receiving.exportTaskProgress", "storage.receiving.storeExport", "storage.receiving.storeExportTaskProgress" ], "notes": [ "export 改为仓库维度:过滤条件从 store_id(平台激活货主)改为 warehouse_id(ctx.user.store_id),与 getReceivingList 保持一致。", "exportTaskProgress 同步更新为仓库维度进度查询,任务 ID 前缀 receiving_export_。", "新增 storeExport:货主维度导出,通过平台激活上下文获取 store_id,过滤逻辑与 getStoreReceivingList 一致。", "新增 storeExportTaskProgress:货主维度进度查询,复用 exportTaskProgress 的缓存逻辑,任务 ID 前缀 receiving_store_export_。", "导出格式:双 Sheet Excel(Sheet1=收货单列表 21 列,Sheet2=收货单明细 17 列),通过 ExcelJS stream + uploadService 上传 COS。", "仓库导出上传路径 exports/receiving/{warehouseId}/,货主导出上传路径 exports/receiving/store/{storeId}/。", "修复 exportReceivingList 中 where 条件二次解析问题:增加 ctx.whereParsed 复用(与 getStoreReceivingList 一致),避免 prepareWhereContext 已解析后再重复 parseWhereConditions 导致边界条件丢失。", "命名对齐 entry 侧:storeExport / storeExportTaskProgress 方法名、任务 ID 前缀、上传路径均与 storage.entry.storeExport 模式一致。" ], "module": "storage.receiving" }, { "version": "2026.07.27-system-02", "date": "2026-07-27", "type": "added", "summary": "新增 order.pendingOrder.allocateSubOrderNumber:待处理订单分配子单号(异步任务),business_key 从 2 开始递增,跳过已分配运单号;新增 allocateSubOrderNumberProgress 按 task_id/business_key 查询进度", "methods": [ "order.pendingOrder.allocateSubOrderNumber", "order.pendingOrder.allocateSubOrderNumberProgress" ], "notes": [ "新增 allocateSubOrderNumber:入参 order_id + sub_order_count,按 business_key 2..(2+count-1) 全量传入 createWaybillCodePipeline。", "并发安全:全量传入 pipeline,由其内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引保证并发去重。", "pipeline 内部 createWaybillCode 事务:status=1 已分配→跳过;status=0 占位中→复用;无记录→INSERT status=0 占位。", "异步任务模式:请求立即返回 task_id(sub_ 前缀),后台 setImmediate 执行,进度通过 Redis 缓存追踪。", "新增 allocateSubOrderNumberProgress:支持 task_id 查整体进度,business_key 可选参数过滤单个业务ID的详情。", "进度状态 submitted→running→success/partial/failed,progress 对应 5/50/80/100。", "result.details 数组记录每个 business_key 的 status(skipped/allocated/failed/pending)与 waybill_code。", "buildSubOrderDetails 回查最终状态:status=1+waybill→allocated,status=0→failed,无记录→failed。" ], "module": "order.pendingOrder" }, { "version": "2026.07.27-system-01", "date": "2026-07-27", "type": "added", "summary": "新增 order.packing 打包任务模块:list/get 查询 + setEndTime 设置结束时间,含视频 CDN URL 拼接与状态回写", "methods": [ "order.packing.list", "order.packing.get", "order.packing.setEndTime", "order.packing.forceRecord" ], "notes": [ "新增 order.packing.list:按仓库维度查询打包任务列表,支持分页/筛选/排序,关联工作台、视频和运单信息。", "新增 order.packing.get:按 id + warehouse_id 查询单条打包任务详情。", "新增 order.packing.setEndTime:设置打包任务结束时间,入参 id + end_time;若任务状态不是已完成(2)则同步更新为已完成。", "新增 order.packing.forceRecord:强制重新录制打包任务视频,入参 id;校验录制电脑在线后重置视频状态并推送打印服务。", "前端默认值逻辑:若任务已有 end_time 则打开时默认为当前时间,否则默认为 start_time + 5分钟。", "视频 URL 自动拼接 CDN 域名前缀:http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{videoPath};录制电脑从 wms_print_computer 按 is_recording=true 获取。", "视频响应新增 status 字段(created/recording/completed/failed),与数据库 ENUM 保持一致。", "pack_task_video Model 的 status 字段从 TINYINT 改为 STRING(20) 以匹配 DB ENUM 迁移。", "forceRecord 通过打印服务 /record/force 推送录制任务,传入 pack_task_id、warehouse_id、computer_id、camera_ids。" ], "module": "order.packing" }, { "version": "2026.07.10-system-01", "date": "2026-07-10", "type": "added", "summary": "新增 storage.report.searchStore 货主侧库存报表,以 store_id 为主维度查询库存流水", "methods": [ "storage.report.searchStore", "storage.report.exportStore" ], "notes": [ "新增 searchStore 方法:与 search 共享核心逻辑,通过 searchMode='store' 切换主维度从 warehouse_id → store_id。", "新增 exportStore 方法:与 export 共享核心逻辑,支持货主侧导出 Excel(含汇总 + 变更记录两个 sheet)。", "systems 层 search/export 方法新增 searchMode 参数(默认 'warehouse'),不影响现有 warehouse 侧行为。", "货主侧使用 ctx.user.store_id 作为主维度 store_id,辅助维度支持 warehouse_ids 过滤特定仓库。", "systemMethods 层 searchStore 从 where.warehouse_ids 取值传给 search 的 storeIds(承载 warehouse 过滤)。", "输出新增 warehouse_id / warehouse_name 字段,货主侧可区分不同仓库的库存。search 方法也同步输出这两个字段(向后兼容)。", "修复 getStockDetails 的 warehouseId 判断:从 != null 改为 !== undefined,使显式传 null 可跳过 warehouse 过滤。", "修复 loadReportReferenceMaps 未传递 warehouseId 给 getStockDetails 的问题。" ], "module": "storage.report" }, { "version": "2026.07.09-system-01", "date": "2026-07-09", "type": "updated", "summary": "签约 sign 方法改造:统一当前主体→store_id,解除角色校验,仓库可签仓库", "methods": [ "storeWarehouse.store.sign", "storeWarehouse.warehouse.sign" ], "notes": [ "resolvePairIds:统一当前主体始终在 store_id(货主方/消费方),对方在 warehouse_id(仓库方/提供方)。不再根据 isWarehouse 分支。", "getCounterparty:移除 expectedRole 角色校验(仓库不再只能签货主,可签仓库)。", "findScopedRelation:改为 OR 查询 store_id/warehouse_id 两边,兼容新旧签约数据。", "sign preview:counterparty.role 改为根据对方 project 真实返回(warehouse/store),不再硬编码反推。", "签仓库:仓库发起签约时对方 ID 传 counterparty_id,系统自动将当前仓库放 store_id。" ], "module": "storeWarehouse" }, { "version": "2026.07.08-system-01", "date": "2026-07-08", "type": "updated", "summary": "storeWarehouse.store.list 与 storeWarehouse.warehouse.list 拆分实现,不再共用;仓库侧支持查询外部合作仓库", "methods": [ "storeWarehouse.store.list", "storeWarehouse.warehouse.list" ], "notes": [ "拆分:store.list 调用 listForStore,warehouse.list 调用 listForWarehouse,不再共用同一个 list 方法。", "新规则:两个方法均按 store_id = 当前主体ID 过滤(主体在 store_id 为货主方/消费方,对方在 warehouse_id 为仓库方/提供方)。", "warehouse.list 新增支持查询外部合作仓库:当对方主体的 project='warehouse' 时为仓库-仓库合作,counterparty_role='warehouse'。", "响应新增 counterparty_role 字段(store/warehouse),标识对方主体的真实角色。", "warehouse.list 响应 use_status 改为 store_use_status(仓库在 store_id 方时,己方启用状态应为 store_use_status)。", "旧 list 方法保留标记为 @deprecated,保持向后兼容。", "新增 buildListWhereByStoreId 统一按 store_id 维度构建查询条件。" ], "module": "storeWarehouse" }, { "version": "2026.07.06-system-01", "date": "2026-07-06", "type": "updated", "summary": "order.wave.batchList:响应新增 pick_assignment_status(拣货分配状态),按订单 pick_status 聚合判定", "methods": [ "order.wave.batchList" ], "notes": [ "响应 list 每项新增字段 pick_assignment_status (string):拣货分配状态,按波次下订单的 pick_status 聚合判定。", "取值语义与 resolveAssignmentStatus 一致,自定义标签:未拣货(全 none)、部分拣货(混合且无 error)、已拣货(全 fin)、拣货异常(含 error)。", "SQL 子查询新增 pick_none_count / pick_fin_count / pick_error_count 聚合列。" ], "module": "order.wave" }, { "version": "2026.07.05-system-01", "date": "2026-07-05", "type": "added", "summary": "新增 pick.wavePickComplete:传入 wave_id 一键完成整个波次拣货,内部复用 query 去重与任务创建逻辑后自动调用 wavePickTaskComplete(mode=1)", "methods": [ "pick.wavePickComplete" ], "notes": [ "新增方法:pick.wavePickComplete,入参 wave_id(number,必填)。", "内部流程:按 wave_id 查波次 → 活动任务去重(同用户复用 / 他人409冲突)→ 完成任务去重 → 无任务则创建(source=2 后台抓取)→ 调用 pick.wavePickTaskComplete mode=1 全部确认。", "创建任务 remark 格式:pick.wavePickComplete wave_id={waveId},用于与 pick.query 区分。", "响应:task_id、status(completed / already_completed)、tip、confirmed_order_ids、is_completed、progress。", "错误码:400(参数/波次无订单)、401(缺少操作人)、404(波次不存在)、409(他人活动任务冲突)、500(创建/完成失败)。" ], "module": "pick" }, { "version": "2026.07.03-system-02", "date": "2026-07-03", "type": "added", "summary": "新增 order.pendingOrder.updateRemark:批量修改待处理订单备注(remark),不受 post_status 限制", "methods": [ "order.pendingOrder.updateRemark" ], "notes": [ "新增方法:order.pendingOrder.updateRemark,用于批量修改待处理订单的备注(remark)字段。", "入参:ids(number[],必填,正整数数组,不能为空)、remark(string,必填,最大500字符)。", "特性:不受 post_status 限制,可对所有状态的订单生效;纯批量不支持单ID。", "更新成功后写入操作日志。", "响应:updated_count(number,实际更新行数)、ids(number[],原样返回请求的ID数组)。", "错误码:400(ids 不能为空 / ids 仅支持正整数数组 / remark 不能为空)。" ], "module": "order.pendingOrder" }, { "version": "2026.07.03-system-01", "date": "2026-07-03", "type": "updated", "summary": "将 quick.waybill.toOrder 迁移为 index.toOrder 并移入基础模块,新增 waves 返回字段", "methods": [ "quick.waybill.toOrder", "index.toOrder" ], "notes": [ "移除快捷操作(quick)模块分组,原 quick.waybill.toOrder 方法从 methods/system.json 删除。", "在基础模块(index)新增 index.toOrder 方法:入参仍为 waybill_code,响应从单一 order_id 扩展为 order_id + waves 结构。", "waves 为数组,每项含 wave_id(波次ID)、wave_no(波次号)、order_ids(波次下所有订单ID列表),无波次时为空数组。", "查询路径:运单号 → wms_order_express(status=1)→ order_id + warehouse_id → 遍历 current/history/dispatch 表获取波次信息 → 再遍历多表获取同波次所有订单ID。" ] }, { "date": "2026-06-24", "type": "addition", "summary": "新增批量绑定入库单明细与收货单明细接口,支持明细级数量分配与部分成功", "version": "2026-06-24-add-bind-receiving-details", "methods": [ "storage.entry.bindReceivingDetails" ], "notes": [] }, { "date": "2026-06-24", "type": "deprecation", "summary": "废弃手动匹配入库单收货单接口,由 storage.entry.bindReceivingDetails 替代", "version": "2026-06-24-deprecate-manual-match-entry-order", "methods": [ "storage.receiving.manualMatchEntryOrder" ], "notes": [] }, { "version": "2026.06.16-system-03", "date": "2026-06-16", "summary": "order.wave.waveStrategyFallbackOrderList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null。", "响应 list 每项新增字段 weight_type (string):重量类型中文标签,来自 wms_order.weight_type 经 formatWeightTypeLabel 转换;取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.16-system-04", "date": "2026-06-16", "summary": "order.wave.singleOrderFetchList 响应新增 items_weight(总重量g)字段", "methods": [ "order.wave.singleOrderFetchList" ], "notes": [ "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", "为 null 时返回 null。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.05.20-system-03", "date": "2026-05-20", "summary": "新增 storeWarehouse.store.queryPrintQuantityLogs:按 store_id 分页查询面单余额变更日志", "methods": [ "storeWarehouse.store.queryPrintQuantityLogs" ], "notes": [ "新增方法:storeWarehouse.store.queryPrintQuantityLogs,用于按货主(store_id)分页查询面单余额变更日志。", "入参:store_id(必填)、page(可选)、page_size / pageSize(可选,兼容别名)。", "仅同步 methods/system.json 与本变更记录,不修改业务代码或测试。", "返回:使用默认分页格式,响应在 `data` 下包含 `list`(变更日志数组)和 `pagination` 对象,`pagination` 字段:`page`、`pageSize`、`total`、`totalPages`、`hasPrevious`、`hasNext`。" ], "type": "added", "module": "storeWarehouse" }, { "version": "2026.05.13-system-01", "date": "2026-05-13", "summary": "完善 print.send 的 API 文档与返回说明", "methods": [ "print.send" ], "notes": [ "补充请求参数说明:computerId、printer、template、data、type 标为必填,count、timestamp 保持可选。", "补充 template 的子字段说明:page_width、page_height、template_content。", "补充响应结构:flag、code、message、printId;其中成功时 code=200。", "补充错误码说明:1001 对应不支持的打印类型,504 对应打印任务发送失败(包含打印机不存在、脱机、通讯失败等场景)。" ], "type": "updated" }, { "version": "2026.05.08-system-06", "date": "2026-05-08", "summary": "新增取消拣货任务接口:order.wave.wavePickTaskCancel", "methods": [ "order.wave.wavePickTaskCancel" ], "notes": [ "接口功能:取消拣货任务,同时释放关联波次(物理删除波次记录,订单回池)、解绑拣货车、写操作日志。", "限制:仅允许在任务状态为 0(待开始)、1(拣货中)、2(待复核)时取消;状态为 3(已完成)或 9(已取消)时禁止取消,返回 400。", "事务内操作:将任务状态更新为 9(已取消)、删除关联波次、清空订单 wave_id(回池)、解绑拣货车、写入 action_log 与 order_pick_trace;若有任一步骤失败则回滚并返回 500。" ], "type": "added" }, { "version": "2026.07.01-system-01", "date": "2026-07-01", "summary": "storage.directInbound.addItem 参数名修正:entry_order_code → entry_order_id,类型 string → number", "methods": [ "storage.directInbound.addItem" ], "notes": [ "文档 params 中 entry_order_code(string)改为 entry_order_id(number),与代码 app/service/systems/inbound_direct_log.js 第 544 行实际校验保持一致", "同步修正 app/service/systemMethods/storage/direct_inbound.js JSDoc:@param {string} data.entry_order_code → @param {number} data.entry_order_id" ], "type": "fixed", "module": "storage.directInbound" }, { "version": "2026.07.01-system-02", "date": "2026-07-01", "summary": "新增 storage.entry.queryEntryLogs 接口文档定义", "methods": [ "storage.entry.queryEntryLogs" ], "notes": [ "代码 method 层(systemMethods/storage/entry.js L284)和 systems 层(systems/operation_log.js L318)均已实现,补充文档定义", "参数:id(number, required)、page(number, optional, 默认1)、pageSize(number, optional, 默认20)" ], "type": "added", "module": "storage.entry" }, { "version": "2026.06.18-system-01", "date": "2026-06-18", "summary": "order.pendingOrder.downloadCreateTemplate:模板列顺序调整,店铺名称(shop_nick)从末尾移至第2列B列,紧接*订单号之后", "methods": [ "order.pendingOrder.downloadCreateTemplate" ], "notes": [ "调整 Excel 导入模板列顺序:店铺名称(shop_nick)从原第25列(Y列/末尾)移动至第2列(B列),紧跟在*订单号(delivery_order_code)之后。", "同步更新 description 中的列顺序描述,明确 25 列(A-Y)的完整排列。", "响应结构中移除冗余的 shop_nick 字段(模板列不属于 API 响应字段)。" ], "type": "updated", "module": "order.pendingOrder" }, { "version": "2026.05.17-system-09", "date": "2026-05-17", "summary": "为 storage.receiving.deleteDetail 文档补充约束:收货单已完成/已取消时禁止删除明细", "methods": [ "storage.receiving.deleteDetail" ], "notes": [ "在 storage.receiving.deleteDetail 的 description 中补充:若关联收货单状态为 completed(已完成)或 cancelled(已取消),接口会返回删除失败(400),不允许删除明细。", "在 errors 中补充或合并 400 描述以明确禁止删除已完成/已取消的收货单明细。" ], "type": "updated", "module": "storage" }, { "version": "2026.05.17-system-08", "date": "2026-05-17", "summary": "完善 storage.receiving.deleteDetail 文档:补充入参/返回/错误说明,明确用户上下文来源及删除约束", "methods": [ "storage.receiving.deleteDetail" ], "notes": [ "补充 storage.receiving.deleteDetail 的参数说明:detail_id(来自请求体,必填);说明 creator_id 与 warehouse_id 来源于当前登录用户(ctx.user.employees_id / ctx.user.store_id)。", "补充返回结构:成功时返回 code/message/data,data 包含 details(删除后剩余明细)和 selectId(建议选中ID);product_snapshot 若存在将被解析为对象或 null。", "补充常见错误码:404(明细不存在或无权访问),400(收货单状态/已入库/删除失败),500(服务器异常)。", "仅文档更新,不修改任何业务实现。" ], "type": "updated", "module": "storage" }, { "version": "2026.05.17-system-05", "date": "2026-05-17", "summary": "移除 storage.receiving.addItem(方法已下线/实现不存在)", "methods": [ "storage.receiving.addItem" ], "notes": [ "仅同步文档:从 methods/system.json 中移除 storage.receiving.addItem,未修改任何业务代码或实现。", "该方法已下线或实现不存在;请以当前 methods/system.json 的 SSOT 为准。" ], "type": "removed" }, { "version": "2026.05.17-system-04", "date": "2026-05-17", "summary": "新增 stock.warehouse.import:仓库商品批量 JSON 导入(数组导入),SKU 为空创建/非空更新,支持 goods_code/货物编码 导入,更新写操作日志", "methods": [ "stock.warehouse.import" ], "notes": [ "支持直接传入商品数组 JSON(主方式为数组,兼容 rows/items/list/data 包装)。", "每项仅需传商品相关字段;SKU 为空时创建新商品,SKU 非空时为更新操作。", "更新操作会写入操作日志以便审计。", "支持导入 goods_code(货物编码)字段别名。", "仅同步文档,不修改业务代码或实现。" ], "type": "added" }, { "version": "2026.05.17-system-03", "date": "2026-05-17", "summary": "完善 stock.warehouse.handleBatchChange 文档:补充入参/出参/错误示例", "methods": [ "stock.warehouse.handleBatchChange" ], "notes": [ "补充方法入参说明:ids/method/value 的字段类型、是否必填、来源与示例;完善响应结构示例与常见错误码说明。", "仅文档更新,不改业务实现或语义。" ], "type": "updated" }, { "version": "2026.05.17-system-02", "date": "2026-05-17", "summary": "stock.warehouse.export 由同步改为异步任务并新增进度查询 exportTaskProgress", "methods": [ "stock.warehouse.export", "stock.warehouse.exportTaskProgress" ], "notes": [ "stock.warehouse.export 改为异步提交导出任务:接口返回 task_id 与受理信息,后端异步生成导出文件。", "新增 stock.warehouse.exportTaskProgress:按 task_id 查询任务状态与进度;当 status=success 时返回 download_url 供客户端下载;未找到时 status=not_found。", "调用方式:先调用 stock.warehouse.export 获取 task_id,然后轮询 stock.warehouse.exportTaskProgress 直到 status=success 并获取 download_url。" ], "type": "updated" }, { "version": "2026.05.17-system-01", "date": "2026-05-17", "summary": "新增 stock.warehouse.export:仓库商品导出(支持 where/sort),返回文件下载信息", "methods": [ "stock.warehouse.export" ], "notes": [ "新增方法:stock.warehouse.export。复用 stock.warehouse.list 的 where/sort 过滤语义(支持 operator/value/type 标准 where 结构与历史简写)。", "响应返回导出结果(示例字段:file_key、url),表示生成的 Excel 已上传并可下载/查询。" ], "type": "added" }, { "version": "2026.05.16-system-01", "date": "2026-05-16", "summary": "同步 setting.expressInterface.create 文档入参:移除未使用的 express_platform_id,标注必填字段", "methods": [ "setting.expressInterface.create" ], "notes": [ "移除文档中 express_platform_id(服务端实现未使用);确认必填字段 name/express_code/platform_code;仓库由系统自动填充,禁止传入 warehouse_id/warehouseId。" ], "type": "updated" }, { "version": "2026.05.12-system-01", "date": "2026-05-12", "summary": "调整订单打印中间态返回结构为 waveGroups(波次 -> 平台 -> 订单)", "methods": [ "order.print.getWavePlatformPrintData" ], "notes": [ "主要变更:将方法的主返回结构改为 waveGroups,按波次分组,波次内按平台分组,平台内为订单列表(波次 -> 平台 -> 订单)。", "兼容性:保留旧字段 platform_groups 与 order_list 作为向后兼容字段,但文档主结构与推荐使用为 waveGroups。", "返回结构说明:summary(total_waves/total_orders/total_platforms)、wave_ids(通过过滤的波次ID数组)、waveGroups(数组,项含 wave_id、wave_no、order_count、platforms[...],platforms项含 platform、platform_name、order_count、orders[...])、ext(missing_wave_ids、filtered_wave_ids)。", "errors:保留 400 / 500 不变。" ], "type": "modified" }, { "version": "2026.05.11-system-05", "date": "2026-05-11", "summary": "order.wave.batchList:支持 express/print 分配状态筛选,入参改为英文枚举(express/print)", "methods": [ "order.wave.batchList" ], "notes": [ "修复 where.express_assignment_status 可按快递分配状态筛选。", "新增 where.print_assignment_status 筛选(按打印分配聚合判断)。", "express_assignment_status / print_assignment_status 要求使用英文枚举值:express=unassigned/partially_assigned/assigned,print=unprinted/partially_printed/printed;storage_assignment_status 继续兼容中文枚举(未分配/部分分配/已分配)。", "若传入非法枚举值,接口返回 400(参数校验失败),message 中会说明允许取值。" ], "type": "updated" }, { "version": "2026.05.11-system-04", "date": "2026-05-11", "summary": "调整 order.wave.waveStrategyFetchAdmin:由创建任务改为直接创建波次(不创建拣货任务)", "methods": [ "order.wave.waveStrategyFetchAdmin" ], "notes": [ "接口行为变更:按策略直接抓取命中订单并创建波次,不再创建拣货任务(不返回 task_id/task_no 等任务字段)。", "响应调整为建波结果:fetch_state(1=成功/2=失败)、wave_ids、wave_nos、created_wave_count、created_order_count、order_ids、(可选)wave_prefix、wave_prefix_source、tip/message。", "错误调整:策略校验失败返回 400(并可能返回 validation_errors),缺少仓库上下文返回 400,建波失败返回 500 并在 message 中说明。" ], "type": "updated" }, { "version": "2026.05.11-system-03", "date": "2026-05-11", "summary": "更新 pick.query:由查询拣货明细调整为按 keyword 获取/创建拣货任务", "methods": [ "pick.query" ], "notes": [ "入参由 waybill_code/full_display 调整为 keyword(支持运单号或波次号)。", "接口语义调整为任务化返回:命中活动任务则返回 existing 任务ID;无活动任务则创建并返回 created 任务ID。", "新增任务归属冲突错误:当活动任务创建人非当前用户时返回冲突提示,并附带创建人及任务ID信息。" ], "type": "updated" }, { "version": "2026.05.11-system-02", "date": "2026-05-11", "summary": "新增 pick.wavePickTaskCurrent:PDA 无参查询当前进行中拣货任务", "methods": [ "pick.wavePickTaskCurrent" ], "notes": [ "新增 PDA 专用无参接口 pick.wavePickTaskCurrent。", "按当前登录用户上下文(pick_user_id + warehouse_id)查询状态在 0/1/2 的最新任务。", "命中返回 task_id,未命中返回 task_id=null。" ], "type": "added" }, { "version": "2026.05.10-system-04", "date": "2026-05-10", "summary": "pick.wavePickTaskDetail 新增按任务类型区分的 picking_view 形态输出", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "新增响应字段:picking_view(object),按 task.pick_mode 区分 5 种形态输出。", "picking_view 字段说明:mode_code, mode_name, require_box_allocations, group_by, sort_by, items[](每项含 space_id、space_name、location_space、item_code、item_name、stock_id、total_qty、box_allocations[])。", "当 pick_mode=1/3/4 时 require_box_allocations=true;当 pick_mode=2/5 时 require_box_allocations=false。" ], "type": "updated" }, { "version": "2026.05.10-system-02", "date": "2026-05-10", "summary": "order.wave.waveStrategyFetchPda/Admin 返回新增 fetch_state 三态与简短 tip", "methods": [ "order.wave.waveStrategyFetchPda", "order.wave.waveStrategyFetchAdmin" ], "notes": [ "新增返回字段:fetch_state(number)、tip(string)、can_enter_pick_flow(boolean)", "fetch_state 含义:1=创建成功(返回 task_id/task_no),2=普通失败(task_id=null),3=存在未完成任务(返回 existing task_id/task_no,前端可直接进入拣货流程)", "当 fetch_state=3 时,字段 can_enter_pick_flow=true,表示前端可直接进入拣货流程;tip 为简短提示文本" ], "type": "updated" }, { "version": "2026.05.10-system-03", "date": "2026-05-10", "summary": "裁剪 pick.wavePickTaskDetail 返回:移除 waves/orders,精简 task 并补充 boxes 拣货统计字段", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "移除响应中的 waves 与 orders 子表,接口仅返回精简的 task、boxes、picking_details 与 picking_summary。", "task 子字段裁剪为:task_id, task_no, status, pick_mode, start_at, finish_at, batch_no。", "boxes 补充并明确返回:ref_label(箱参考标签)、required_qty(箱内需拣总数)、picked_qty(已拣数量)。", "本次变更为文档层面的返回裁剪,前端应以新字段集合为准,旧字段可能不再返回。" ], "type": "updated" }, { "version": "2026.05.10-system-01", "date": "2026-05-10", "summary": "order.wave.waveStrategyList 新增 strategy_type 最小过滤(散单/团购)", "methods": [ "order.wave.waveStrategyList" ], "notes": [ "新增 strategy_type 过滤,仅 1/2", "支持顶层 strategy_type 和 where.strategy_type,顶层优先", "当前不引入其他 where 字段" ], "type": "updated" }, { "version": "2026.05.09-system-02", "date": "2026-05-09", "summary": "新增 pick.wavePickTaskDetail:按任务ID解析拣货任务详情", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "新增 pick.wavePickTaskDetail:传入 task_id 获取拣货任务完整信息,包含主表字段(task/pick_mode/status/wave_count/order_count/box_count 等)及三张子表数据(waves/orders/boxes)。", "安全限制:接口会校验当前登录用户(operator_id/employees_id)与任务的 pick_user_id 是否一致;不一致时直接返回 403,不返回任何拣货信息。", "鉴权配置:noNeedRight=true,noNeedAuth=true,isNeedLogin=true。" ], "type": "added" }, { "version": "2026.05.08-system-05", "date": "2026-05-08", "summary": "order.wave.batchList:新增 source 字段并支持 where.source 过滤,返回 list item 中新增 source 字段", "methods": [ "order.wave.batchList" ], "notes": [ "新增 where.source(可选,number)用于按来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。", "响应 list 每条记录新增字段 source(number),用于区分波次来源。", "仅更新文档,业务代码不在此变更范围。" ], "type": "updated" }, { "version": "2026.05.08-system-04", "date": "2026-05-08", "summary": "完善 order.wave.wavePickTaskList 文档:补充入参、分页与返回字段兼容说明", "methods": [ "order.wave.wavePickTaskList", "order.wave.wavePickTaskCancel" ], "notes": [ "入参补充:warehouse_id(必填)、status(支持单值或数组,建议传数组)、source、keyword、page_no、page_size;保留 pagination 对象以兼容旧客户端。", "兼容说明:接口同时支持历史 where 结构与顶层参数;当存在同名顶层参数时以顶层参数优先;pagination 支持 page/current 与 pageSize/size 别名。", "返回格式:响应包含 total 与 list;list 每项包含字段:task_id、task_no、status、source、pick_mode、wave_count、order_count、box_count、operator_id、operator_name、start_at、finish_at、created_at。为兼容旧客户端,响应同时保留旧字段:pick_user_id、pick_user_name、start_time、finish_time、create_time。", "入参 strategy_id 当前主表未存,接口会忽略该过滤,不建议使用。", "默认排序:create_time desc.", "文档变更:移除 order.wave.wavePickTaskCancel 的入参 operator_id 与 warehouse_id;入参改为仅支持 task_ids(数组,必填),不再兼容单个 task_id;操作人与仓库由请求上下文(例如当前登录用户上下文)自动获取;若上下文缺失接口将返回错误。响应补充批量结果字段:cancelled_count、task_ids、task_nos(若后端返回)。仅更新文档,未修改业务实现。" ], "type": "updated" }, { "version": "2026.05.08-system-03", "date": "2026-05-08", "summary": "升级按策略抓取接口为创建任务主流程:order.wave.waveStrategyFetchPda / order.wave.waveStrategyFetchAdmin", "methods": [ "order.wave.waveStrategyFetchPda", "order.wave.waveStrategyFetchAdmin" ], "notes": [ "将 PDA/Admin 场景的按策略抓取接口由受理壳方法升级为 '创建任务主流程':接口会执行参数校验并在同步响应中创建任务记录(state=created),返回 task_id、task_no、plan 与 plan_summary 供前端展示与后续查询。", "入参新增/扩展与创建流程相关字段:至少包含 cart_id(关联拣货车/作业车ID)、source(操作来源语义)并保留并透传 strategy_id 与 strategy_params(策略参数),以支持在创建阶段对策略进行局部覆盖或透传。", "成功返回示例字段:state=created、task_id、task_no、plan(对象)和 plan_summary(字符串);失败场景会返回 validation_errors(数组,每项含 field/message)或 message 描述创建失败原因。", "边界说明:当前为最小主流程(创建与计划预览),后续扫描/任务执行阶段(如实际抓取订单、写入 wave 等)将在后续版本中追加与完善。" ], "type": "updated" }, { "version": "2026.05.08-system-02", "date": "2026-05-08", "summary": "调整按策略抓取壳方法:order.wave.waveStrategyFetch 更名为 order.wave.waveStrategyFetchPda,并新增 order.wave.waveStrategyFetchAdmin", "methods": [ "order.wave.waveStrategyFetch", "order.wave.waveStrategyFetchPda", "order.wave.waveStrategyFetchAdmin" ], "notes": [ "waveStrategyFetchPda 仅用于 PDA 场景", "waveStrategyFetchAdmin 仅用于后台管理场景", "两者当前均为壳子受理方法,不执行真实抓取" ], "type": "updated" }, { "version": "2026.05.08-system-01", "date": "2026-05-08", "summary": "新增 order.wave.waveStrategyFetch:按策略提交抓取任务(壳子方法)", "methods": [ "order.wave.waveStrategyFetch" ], "notes": [ "当前方法为壳子方法:仅受理并返回任务受理信息,不执行真实抓取逻辑,后续补齐执行链路。" ], "type": "added" }, { "version": "2026.05.07-system-05", "date": "2026-05-07", "summary": "新增 order.wave.waveStrategyCreate 与 order.wave.waveStrategyUpdate:波次策略创建与更新接口(含参数校验与版本推进)", "methods": [ "order.wave.waveStrategyCreate", "order.wave.waveStrategyUpdate" ], "notes": [ "仓库 ID 与创建人(creator_name)由当前登录仓库/操作者上下文获取,接口不接受外部覆盖。", "入参 allowed_owners 与 allowed_expresses 会校验是否在系统可用范围内(基于仓库签约货主或系统快递列表),若存在非法值接口会直接报错(400)。", "max_same_structure 受仓库配置 min_group_order_fetch_quantity 限制:若传入值 >= min_group_order_fetch_quantity,则自动下调为 min_group_order_fetch_quantity - 1(最小值为 1)。", "新建/更新成功后会触发仓库的 wave_strategy_version 自增(+1)并失效相关仓库配置缓存,调用方可通过策略版本推进或缓存变化感知策略已生效。" ], "type": "added" }, { "version": "2026.05.07-system-06", "date": "2026-05-07", "summary": "收敛 order.wave.waveStrategyFallbackOrderList 返回字段,限定 where 白名单,补充 order.wave.singleFetchByIds 别名与返回语义", "methods": [ "order.wave.waveStrategyFallbackOrderList", "order.wave.singleFetchByIds" ], "notes": [ "收敛 order.wave.waveStrategyFallbackOrderList response.list 字段为 id, delivery_no, tracking_no, items_count, items_total, sys_logistics_name, store_name, province, sys_platform_name, item_snapshot;item_snapshot 格式示例:商品名称*数量|...。", "限制 order.wave.waveStrategyFallbackOrderList.where 白名单,禁止传入 warehouse_id / warehouseId;传入未列出字段或别名冲突将返回 400。", "补充 order.wave.singleFetchByIds:明确支持 ids / order_ids / orderIds 三个别名(优先顺序 ids -> order_ids -> orderIds)并说明返回字段 fetched_order_ids、excluded_existing_wave_order_ids、skipped_order_ids、not_found_order_ids 的语义与兼容性。" ], "type": "updated" }, { "version": "2026.05.07-system-04", "date": "2026-05-07", "summary": "更新 order.wave.waveStrategyFallbackOrderList,新增商品快照字段 item_snapshot", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "item_snapshot 返回格式为 商品名称1*数量|商品名称2*数量" ], "type": "updated" }, { "version": "2026.05.07-system-03", "date": "2026-05-07", "summary": "新增 order.wave.waveStrategyQuickScan 与进度查询接口", "methods": [ "order.wave.waveStrategyQuickScan", "order.wave.waveStrategyQuickScanTaskProgress" ], "notes": [ "同仓只允许一个扫描任务并使用缓存锁;扫描范围为当前表非待审核、未分配波次且订单策略版本与仓库当前版本不一致的订单;命中策略标记 wave_scan_result=1,否则=2" ], "type": "added" }, { "version": "2026.05.07-system-02", "date": "2026-05-07", "summary": "新增 order.wave.waveStrategyList:查询当前仓库波次策略列表", "methods": [ "order.wave.waveStrategyList" ], "notes": [ "从 wms_wave_strategy 拉取当前仓库的波次策略列表,分页返回" ], "type": "added" }, { "version": "2026.05.07-system-01", "date": "2026-05-07", "summary": "移除 order.wave.singleOrderFetchDetailList,新增 order.wave.waveStrategyFallbackOrderList(内置固定筛选条件)", "methods": [ "order.wave.singleOrderFetchDetailList", "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "移除 order.wave.singleOrderFetchDetailList。", "新增 order.wave.waveStrategyFallbackOrderList。", "新接口基于订单通用查询口径,固定内置筛选条件:step != 0、wave_id = 0、wave_scan_result = 2。" ], "type": "updated" }, { "version": "2026.05.06-system-06", "date": "2026-05-06", "summary": "新增 order.wave.singleOrderFetchDetailList:订单级散单候选明细视图", "methods": [ "order.wave.singleOrderFetchDetailList" ], "notes": [ "新增 order.wave.singleOrderFetchDetailList:提供订单级的散单候选明细列表,返回按订单聚合的明细(非分组级)。", "返回订单级而非分组级;响应每项包含订单 id、group_count、item_detail_machine、item_detail_machine_snapshot、item_detail、item_snapshot、logistics_name、store_id、distinguish_express、create_at 与 status_summary 等关键字段。", "仍沿用 same_order_quantity 阈值来排除团购命中分组(仅保留 group_count < same_order_quantity 的候选项)。", "singleOrderFetchList 暂保留以兼容现有前端,前端可在切换到订单级视图后迁移到本接口。" ], "type": "added" }, { "version": "2026.05.06-system-05", "date": "2026-05-06", "summary": "storage.receiving.get 返回扩展:data.details[*] 新增 box_remainder、box_weight", "methods": [ "storage.receiving.get" ], "notes": [ "storage.receiving.get 的响应在 data.details[*] 中新增可选字段:box_remainder(箱内剩余数量/零散数量,number,默认 0)与 box_weight(实测箱重,number,默认 0)。", "兼容性:新增字段为可选,旧客户端无需修改;建议前端在需要展示箱内余量/箱重时使用这些字段。" ], "type": "updated" }, { "version": "2026.05.06-system-04", "date": "2026-05-06", "summary": "storage.receiving.getReceivingDetail 返回扩展:明细增加 box_remainder、box_weight;storage.receiving.completeReceiving 通知包含这两个字段", "methods": [ "storage.receiving.getReceivingDetail", "storage.receiving.completeReceiving" ], "notes": [ "为支持箱规统计与通知回传,getReceivingDetail 的明细项(receiving.details 或 data.details)在响应中新增可选字段:box_remainder(箱内剩余数量/零散数量,number)与 box_weight(实测箱重,number,单位同系统重量)。", "completeReceiving 在完成收货后会发送通知(或回调),通知 payload/metadata 中将包含每条明细的 box_remainder 与 box_weight 字段,供下游系统/前端展示或审计使用。", "兼容性:新增字段为可选,旧客户端在未使用这些字段时无需变更。" ], "type": "updated" }, { "version": "2026.05.06-system-03", "date": "2026-05-06", "summary": "storage.receiving.detailChange:新增入参/出参字段 box_remainder、box_weight", "methods": [ "storage.receiving.detailChange" ], "notes": [ "为支持箱规细化与回写,detailChange 新增可选入参 box_remainder(箱内余量/零散数量)和 box_weight(实测箱重,单位同系统重量),写入后会回写至明细并在响应 data 中返回对应字段。", "兼容性:新增字段为可选,不传入则不影响现有调用;建议前端在需要回写箱余与箱重时一并传入。" ], "type": "updated" }, { "version": "2026.05.06-system-02", "date": "2026-05-06", "summary": "新增 order.wave.singleFetchByIds:按订单ID抓取到一个散单波次", "methods": [ "order.wave.singleFetchByIds" ], "notes": [ "新增 order.wave.singleFetchByIds:按入参 ids(兼容 order_ids/orderIds)去重后筛选当前仓库内待处理且不在波次中的订单,若存在可抓取订单则创建单个散单波次并把这些订单写入该波次(不区分快递);成功后批量写入订单操作日志;若无可抓取订单返回 wave_id=0。", "接口行为严格对齐实现:过滤条件包含 step in [1,2,3]、status != 'cancel'、outbound_status != 'padding';已在波次的订单会被排除并返回 excluded_existing_wave_order_ids;响应包含 ids、wave_id、wave_no、fetched_order_ids、fetched_order_count、excluded_existing_wave_order_ids、skipped_order_ids、not_found_order_ids。" ], "type": "added" }, { "version": "2026.05.06-system-01", "date": "2026-05-06", "summary": "新增 order.wave.groupFetch 与 order.wave.singleFetch;order.wave.fetch 保留兼容别名;抓取进度补充上限字段", "methods": [ "order.wave.groupFetch", "order.wave.singleFetch", "order.wave.fetch", "order.wave.fetchTaskProgress" ], "notes": [ "新增 order.wave.groupFetch:抓取团购接口(异步任务提交),参数 structure_list 与原 fetch 一致。", "新增 order.wave.singleFetch:抓取散单接口(异步任务提交),在 structure_list 每项新增必填字段 max_fetch_quantity(最大抓取上限,订单数,正整数)。", "order.wave.fetch 保留为兼容别名(等同 groupFetch),避免误导客户端。", "groupFetch/singleFetch/fetch 的响应新增可选字段 fetch_mode;singleFetch 响应额外返回 max_fetch_quantity。", "order.wave.fetchTaskProgress 的响应增加单模式相关字段:fetch_mode、max_fetch_quantity、limit_reached、stop_reason,用于描述散单抓取的上限与停止原因。" ], "type": "updated" }, { "version": "2026.05.05-system-02", "date": "2026-05-05", "summary": "order.wave.batchList:新增 where.storage_assignment_status 的过滤语义说明", "methods": [ "order.wave.batchList" ], "notes": [ "新增 where 字段 `storage_assignment_status`:类型 string,可选值:`未分配`、`部分分配`、`已分配`;默认不传:不做分配状态限制。", "过滤语义:`已分配`:聚合后全部 fin;`部分分配`:不含 error,且既不是全 none,也不是全 fin;`未分配`:全 none 或包含 error(异常并入未分配筛选集合)。", "说明:返回字段 `storage_assignment_status` 的展示值保持不变;包含 error 时仍可能展示“分配异常”,但 where 的过滤语义把异常算到“未分配”集合,避免把过滤语义与展示值混淆。" ], "type": "updated" }, { "version": "2026.05.05-system-01", "date": "2026-05-05", "summary": "新增 order.wave.singleOrderFetchList:散单候选分组查询(排除团购命中分组)", "methods": [ "order.wave.singleOrderFetchList" ], "notes": [ "新增 order.wave.singleOrderFetchList:返回按机器结构分组的散单候选列表,接口会排除已达团购阈值(同组订单数量 >= same_order_quantity 或仓库配置 min_group_order_fetch_quantity)的分组,仅返回同组订单数量 < 阈值 的分组(散单候选)。", "与 order.wave.groupOrderFetchList 的关键差异:groupOrderFetchList 返回满足团购阈值(>=)的分组;singleOrderFetchList 返回未达阈值(<)的散单候选分组。", "影响范围:订单波次抓取相关前端/调度服务。兼容性:不影响或修改现有 order.wave.groupOrderFetchList,两个接口可并行使用。" ], "type": "added" }, { "version": "2026.05.04-system-04", "date": "2026-05-04", "summary": "完善商品编码唯一性校验接口文档,补充 item_id(排除自身)和 owner_id(货主ID)入参说明,新增 unique/isUnique 返回字段描述", "methods": [ "stock.warehouse.checkItemCodeUnique" ], "notes": [ "完善商品编码唯一性校验接口文档,补充 item_id(排除自身)和 owner_id(货主ID)入参说明,新增 unique/isUnique 返回字段描述" ], "type": "modified" }, { "version": "2026.05.04-system-02", "date": "2026-05-04", "summary": "修改 pick.query 入参:order_id -> waybill_code", "methods": [ "pick.query" ], "notes": [ "入参从 order_id 改为 waybill_code(快递号),通过快递号查找订单后再查波次拣货信息" ], "type": "breaking_change" }, { "version": "2026.05.04-system-01", "date": "2026-05-04", "summary": "新增 system method pick.query:按订单查询波次拣货信息", "methods": [ "pick.query" ], "notes": [ "按订单查询该订单所属波次的拣货信息,支持 full/full_display/is_full 控制是否完整显示;接口按当前登录用户仓库上下文过滤,防止跨仓越界。" ], "type": "added" }, { "version": "2026.05.03-system-09", "date": "2026-05-03", "summary": "新增按 request_id 查询分配状态/结果接口", "methods": [ "order.pendingOrder.allocateStorageProgress" ], "notes": [ "新增按 request_id 查询储位分配异步任务状态/结果接口,支持 status:submitted/running/success/failed/not_found;success 返回 result(底层分配结果),failed 返回 error(错误信息);兼容 requestId 参数名。" ], "type": "updated" }, { "version": "2026.05.03-system-07", "date": "2026-05-03", "summary": "新增抓取进度查询接口", "methods": [ "order.wave.fetch", "order.wave.fetchTaskProgress" ], "notes": [ "新增按 task_id 查询抓取任务进度的接口 order.wave.fetchTaskProgress,支持返回 status(submitted/running/success/failed/not_found)及进度相关字段:progress_percent、finished_structure_count、total_fetched_quantity、duration_ms、error、update_time 等;同时明确 order.wave.fetch 为异步任务提交接口,客户端可通过 task_id 调用 order.wave.fetchTaskProgress 查询进度和最终结果。" ], "type": "updated" }, { "version": "2026.05.03-system-05", "date": "2026-05-03", "summary": "补齐仓库设置模块 setting.warehouse 的 methods 文档", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings" ], "notes": [ "补齐仓库配置 methods API 文档" ], "type": "updated" }, { "version": "2026.05.03-system-04", "date": "2026-05-03", "summary": "order.wave:自动加团新增跳过规则并新增批量结束自动加团接口", "methods": [ "order.wave.batchAutoGrouping", "order.wave.batchFinishAutoGrouping" ], "notes": [ "开启自动加团新增“已打印/超最大波次容量”跳过规则并在响应中返回跳过明细;新增批量结束自动加团接口(将 wave_status=0 的波次批量置为 1)" ], "type": "updated" }, { "version": "2026.05.03-system-03", "date": "2026-05-03", "summary": "裁剪 order_list 以轻量化返回", "methods": [ "order.wave.batchList" ], "notes": [ "移除响应中的 order_list 字段,接口仅返回波次基础信息与状态汇总(order_count / storage_assignment_status / express_assignment_status / print_assignment_status)" ], "type": "updated" }, { "version": "2026.05.03-system-02", "date": "2026-05-03", "summary": "新增 order.wave.batchAutoGrouping:批量改为自动加团中", "methods": [ "order.wave.batchAutoGrouping" ], "notes": [ "新增批量改为自动加团中接口及返回字段" ], "type": "updated" }, { "version": "2026.04.22-system-02", "date": "2026-04-22", "summary": "新增 order.pendingOrder.syncOrderIds:待处理订单同步透传入口", "methods": [ "order.pendingOrder.syncOrderIds" ], "notes": [ "新增 order.pendingOrder.syncOrderIds:仅接收 order_ids 并转发到服务层,当前不做业务处理。", "接口保留登录态校验,入参仅接受订单 ID 相关字段,响应以服务层返回值为准。", "该方法用于预留同步链路,后续补齐业务逻辑时再扩展服务层实现。" ], "type": "updated" }, { "version": "2026.04.22-system-01", "date": "2026-04-22", "summary": "补全订单工作台各模块 detail 方法文档", "methods": [ "order.detail", "order.pendingOrder.detail", "order.reviewOrder.detail", "order.expectionOrder.detail", "order.outboundOrder.detail", "order.deliveryOrder.detail", "order.deliveryExpectionOrder.detail", "order.entrustOrder.detail", "order.archiveOrder.detail" ], "notes": [ "补全文档:detail 为订单工作台通用详情方法,入参支持 ids/id/order_id/orderId;可选 tableType/tablePosition/type/moduleName,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等。", "返回包含 order/detail(订单头)、orderItems/items(商品明细)、expresses(运单信息)、waybill_codes(去重运单号数组)。" ], "type": "updated" }, { "version": "2026.04.19-system-01", "date": "2026-04-19", "summary": "新增方法 setting.expressInterface.listByWarehousePlatformCode:按 warehouse_id + platform_code 查询全字段列表并支持缓存", "methods": [ "setting.expressInterface.listByWarehousePlatformCode" ], "notes": [ "新增 setting.expressInterface.listByWarehousePlatformCode:按 warehouse_id + platform_code 返回快递接口的全字段数组(不分页),每条记录包含 express 关联对象(id/code/name/platform 等)。", "支持缓存,缓存键由 warehouse_id + platform_code 组成;缓存命中将直接返回缓存结果以提升查询性能。", "在创建/更新/删除操作(setting.expressInterface.create/update/delete)后,会主动清理对应 warehouse_id + platform_code 的缓存以确保数据一致性。" ], "type": "added" }, { "version": "2026.04.17-system-08", "date": "2026-04-17", "summary": "新增快递编码管理模块批量软删除接口 setting.express.delete", "methods": [ "setting.express.delete" ], "notes": [ "新增批量软删除接口 setting.express.delete:接受 ids(数组、逗号字符串或单值),对属于当前仓库且未被删除的记录执行软删除(设置 deleted_at),并清理 express 列表缓存。", "当任一目标记录的 code 被 wms_express_interface.express_code 引用时,接口会拒绝删除并返回 409,错误信息中包含被引用的编码列表。", "响应包含 ids、deleted_ids、already_deleted_ids 与 status,已删除与未删除的 id 会明确分类。仅记录已实现行为。" ], "type": "added" }, { "version": "2026.04.17-system-05", "date": "2026-04-17", "summary": "新增文档分组:平台编码管理模块(收口 index.getPlatformList 与 setting.platform.*)", "methods": [ "index.getPlatformList", "setting.platform.list", "setting.platform.create", "setting.platform.update", "setting.platform.delete" ], "notes": [ "新增独立文档分组 '平台编码管理模块',将平台基础列表(index.getPlatformList)与平台设置管理接口(setting.platform.*)归并为单一分组以便维护;仅文档变更,不修改实现。", "文档中仅包含已实现的方法与字段,未新增或推断不存在的参数/返回字段。" ], "type": "added" }, { "version": "2026.04.17-system-04", "date": "2026-04-17", "summary": "新增独立平台设置模块 setting.platform(wms_platfrom_setting)及其 CRUD 接口:list/create/update/delete。", "methods": [ "setting.platform.list", "setting.platform.create", "setting.platform.update", "setting.platform.delete" ], "notes": [ "新增独立模块 setting.platform,映射数据表 wms_platfrom_setting;list 支持 where(id/code/name/platform_code/quickWhere)与 pagination(兼容 page/pageSize/page_size);create/update 要求 platform_code 必须存在于系统平台表(wms_platform),且禁止越权写入 warehouse_id;delete 需传入 id 并校验当前仓库范围。" ], "type": "added" }, { "version": "2026.04.15-system-07", "date": "2026-04-15", "summary": "将 docs/order-workbench-list-api.md 引用统一为 window 链接格式", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list" ], "notes": [ "将所有 methods/system.json 中指向 docs/order-workbench-list-api.md 的说明统一替换为 docs/order-workbench-list-api.md 格式,以便 HTML 渲染识别为 window 链接。", "仅修改 methods/system.json 的文档字段,不涉及任何业务代码或接口契约变化。" ], "type": "updated" }, { "version": "2026.04.15-system-06", "date": "2026-04-15", "summary": "订单工作台列表文档补全 raw 字段字典与中文语义说明", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list" ], "notes": [ "在 docs/order-workbench-list-api.md 中补充所有订单列表通用 raw 字段字典,明确每个字段的中文语义与 enum 取值。", "补充 express_numbers / waybill_codes 两个服务层派生字段说明,便于前端直接渲染多个快递号。", "methods/system.json 中所有订单 list 的 response.list 描述已指向该字段字典章节。" ], "type": "updated" }, { "version": "2026.04.15-system-05", "date": "2026-04-15", "summary": "基础模块新增快递/平台列表查询接口并设置为不鉴权,复用缓存 service", "methods": [ "index.getExpressList", "index.getPlatformList" ], "notes": [ "新增 index.getExpressList,归属基础模块(module=index),对应 app/service/systems/express.js 中的 getExpressList。", "index.getExpressList 设置为不鉴权,不需要 Authorization 头。", "新增 index.getPlatformList,归属基础模块(module=index),对应 app/service/systems/platform.js 中的 getPlatformList。", "index.getPlatformList 设置为不鉴权,不需要 Authorization 头。", "快递列表与平台列表都支持缓存优先,缓存未命中时回源数据库并写入缓存。", "平台列表支持缓存优先,缓存未命中时回源 wms_platform 并写入缓存。" ], "type": "added" }, { "version": "2026.04.15-system-02", "date": "2026-04-15", "summary": "签约策略字段元信息新增 default_express_code / default_platform_code list 选项", "methods": [ "storeWarehouse.store.getPolicyConfigFields" ], "notes": [ "getPolicyConfigFields 现在返回 default_express_code 与 default_platform_code 两个 list 字段,并从 wms_express / wms_platform 读取选项列表。", "默认值仍保留为 default_express_code=STO、default_platform_code=TB。" ], "type": "updated" }, { "version": "2026.04.15-system-03", "date": "2026-04-15", "summary": "签约策略字段移除 sku_visibility,receive_mode options 改为 value/label 结构", "methods": [ "storeWarehouse.store.savePolicyConfig", "storeWarehouse.store.getPolicyConfigFields" ], "notes": [ "策略字段定义不再包含 sku_visibility,历史值读取时仍会被归一化忽略。", "receive_mode 的 options 改为 [{ value, label }] 格式,便于前端直接渲染。" ], "type": "updated" }, { "version": "2026.04.15-system-04", "date": "2026-04-15", "summary": "按文件模块拆分 order 目录系统文档分组,覆盖订单工作台入口及各子模块方法", "methods": [ "order.list", "order.manualOutboundOrder", "order.badgeCount", "order.outboundOrder.manualOutboundOrder", "order.reviewOrder.list", "order.reviewOrder.reviewOrder", "order.pendingOrder.list", "order.pendingOrder.reverseReviewOrder", "order.pendingOrder.markPendingOutboundOrder", "order.pendingOrder.cancelOrder", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list" ], "notes": [ "按 app/service/systemMethods/order 下的实际对外方法补全 methods/system.json 文档,只覆盖 system,不处理 qimen。", "order 文档已按 index / reviewOrder / pendingOrder / outboundOrder / expectionOrder / entrustOrder / deliveryOrder / deliveryExpectionOrder / archiveOrder 拆成多个模块分组。", "同步根据当前代码意图补充 params / response / errors,且不再把 index.js 已移除的兼容接口写回文档。" ], "type": "updated" }, { "version": "2026.04.15-system-01", "date": "2026-04-15", "summary": "货主主体配置默认补齐 default_express_code / default_platform_code", "methods": [ "store.createStore", "store.createWarehouse" ], "notes": [ "当 subject_config 未传或缺少字段时,自动补齐 default_express_code=STO、default_platform_code=TB,并保留现有的 max_notice_webhook_count 默认值。", "同步更新 methods/system.json 中 store.createStore 与 store.createWarehouse 的参数说明。" ], "type": "updated" }, { "version": "2026.04.14-system-01", "date": "2026-04-14", "summary": "库存列表新增货主名称字段 stock.store_name", "methods": [ "storage.inventory.list" ], "notes": [ "在 methods/system.json 的 storage.inventory.list response 中补充 stock.store_name:来源于签约表 store_remask,若无签约关系则为 null。", "只同步文档,不修改业务代码。" ], "type": "updated" }, { "version": "2026.04.13-system-01", "date": "2026-04-13", "summary": "补全 storage.receiving.detailChange 的入参/出参契约与错误码说明", "methods": [ "storage.receiving.detailChange" ], "notes": [ "在 methods/system.json 中补充 storage.receiving.detailChange 的 params/response/errors,明确 id 与 receiving_id 必填。", "说明 expiry_date 小于当前日期时返回 400 且 message 为 \"到期日期已过期,不能录入收货\"。", "说明当传入 system_product_id 时会回填条码、重量、箱规、商品名称与 product_snapshot;未传时 barcode/product_name 也可单独更新。", "同步补充文档:docs/storage-receiving-api.md 中新增 detailChange 段落。" ], "type": "updated" }, { "version": "2026.04.07-system-01", "date": "2026-04-07", "summary": "修正 warehouse.getAreaRacks 的鉴权/权限链路文档,明确该接口需要 登录并走权限校验。", "methods": [ "warehouse.getAreaRacks" ], "notes": [ "对齐当前 system 文档中的 isNeedAuth=true、isNeedLogin=true。", "用于补充该接口权限链路修正文档的历史上下文,不改变 methods/system.json 的 SSOT 角色。" ] }, { "version": "2026.04.07-system-02", "date": "2026-04-07", "summary": "补充签约配置相关接口文档,覆盖策略字段元信息查询与面单数量人工调整。", "methods": [ "storeWarehouse.store.getPolicyConfigFields", "storeWarehouse.store.adjustPrintQuantity" ], "notes": [ "getPolicyConfigFields 说明为获取签约策略可配置字段元信息列表。", "adjustPrintQuantity 说明为人工调整签约关系下的面单余额并记录变更日志,并 明确 id、change_quantity、reason 等关键入参。" ] }, { "version": "2026.04.07-system-03", "date": "2026-04-07", "summary": "对外命名从 qimenConfig 收口为 apiConfig,并在接口配置文档中强调 interface_type_id 校验。", "methods": [ "storeWarehouse.store.listApiConfig", "storeWarehouse.store.saveApiConfig", "storeWarehouse.store.deleteQimenConfig" ], "notes": [ "文档对外统一使用 apiConfig / api_config 命名,减少 qimenConfig 历史别名歧义。", "saveApiConfig 要求 interface_type_id 为必填且必须指向已存在的 wms_interface_type 记录。", "listApiConfig / deleteQimenConfig 同步补充 interface_type_id 字段说明。" ] }, { "version": "2026.04.07-system-04", "date": "2026-04-07", "summary": "补充 /api/docs 文档体验增强说明,新增查看变更记录与查看原文 JSON 的入口说明。", "methods": [ "/api/docs", "/api/docs/:docName", "/api/docs/:docName/raw", "/api/docs/:docName/changes" ], "notes": [ "sidecar 变更数组用于承载文档历史说明,不替代 methods/system.json 作为 SSOT。", "原文 JSON 入口继续用于直接查看当前生效文档。" ] }, { "version": "2026.04.07-system-05", "date": "2026-04-07", "summary": "修正 storeWarehouse.store.adjustPrintQuantity 的面单余额调整语义:由增减/累加改为覆盖设置目标余额。", "methods": [ "storeWarehouse.store.adjustPrintQuantity" ], "notes": [ "adjustPrintQuantity 当前兼容 print_quantity、target_quantity、change_quantity、adjust_quantity 作为目标面单余额输入,不再按增减量解释。", "变更日志中的 change_quantity 由 before/after 自动计算差值,以兼容历史审计与展示。" ] }, { "version": "2026.04.07-system-06", "date": "2026-04-07", "summary": "按接口类型分类限制必填字段,OPEN_API 创建时自动生成 self_app_key/self_app_secret", "methods": [ "storeWarehouse.store.saveApiConfig" ], "notes": [ "QM_WMS 类型须填写 qimen_app_key/qimen_customer_id/qimen_warehouse_code;OPEN_API 类型三个奇门字段非必填,创建时自动生成 self_app_key(WMS+32位HEX)和 self_app_secret(64位HEX),更新时保留已有密钥。" ], "type": "changed" }, { "version": "2026.04.07-system-07", "date": "2026-04-07", "summary": "新增接口类型列表查询接口,归属基础模块,无需权限", "methods": [ "index.listInterfaceTypes" ], "notes": [ "返回所有已启用的接口类型(wms_interface_type),包含 id、interface_code、interface_name、interface_category、description 字段。设置 isNeedAuth: false, isNeedLogin: true。" ], "type": "added" }, { "version": "2026.04.07-system-08", "date": "2026-04-07", "summary": "app_name 改为必传参数", "methods": [ "storeWarehouse.store.saveApiConfig" ], "notes": [ "app_name 不再有默认值自动生成逻辑,调用方必须传入非空的 app_name,否则返 回 400 错误。" ], "type": "changed" }, { "version": "2026.04.07-system-09", "date": "2026-04-07", "summary": "新增收货单快捷入库上架接口", "methods": [ "storage.inventory.quickPutaway" ], "notes": [ "新建 storage.inventory 库存操作模块。quickPutaway 从收货单直接生成入库单 (SCRK)并写入 wms_storage 库存表,同时更新 wms_stock_warehouse 库存数量(悲观行锁),回填收货明细入库状态。要求收货单已完成且所有明细已匹配系统商品。" ], "type": "added" }, { "version": "2026.04.08-system-01", "date": "2026-04-08", "summary": "新增收货单与入库单匹配入库接口", "methods": [ "storage.inventory.matchPutaway" ], "notes": [ "接收多个收货单和入库单,按商品(stock_warehouse_id)进行数量匹配入库,完 成后根据入库单来源(QM/API)自动触发回传。入参为 receiving_ids(数组)和 entry_order_ids(数组),返回匹配汇总、各收货单入库状态、各入库单状态及回传结果。isNeedAuth=true, isNeedLogin=true, isNeedRight=false。" ], "type": "added" }, { "version": "2026.04.08-system-02", "date": "2026-04-08", "summary": "saveApiConfig 新增 callback_url 可选参数", "methods": [ "storeWarehouse.store.saveApiConfig" ], "notes": [ "新增 callback_url 参数(VARCHAR(500),可选),用于 OPEN_API 类型入库单的 回调地址配置。" ], "type": "changed" }, { "version": "2026.04.08-system-03", "date": "2026-04-08", "summary": "serializeQimenConfig 新增返回 callback_url 字段,影响 list 和 listApiConfig 两个接口", "methods": [ "storeWarehouse.store.list", "storeWarehouse.store.listApiConfig" ], "notes": [ "serializeQimenConfig() 序列化方法新增 callback_url(string)字段。storeWarehouse.store.list 返回的每条记录 api_config 对象中包含 callback_url;storeWarehouse.store.listApiConfig 返回的 list 数组中每条配置包含 callback_url。" ], "type": "changed" }, { "version": "2026.04.08-system-04", "date": "2026-04-08", "summary": "新增库存移库(库位转移)接口", "methods": [ "storage.inventory.transferLocation" ], "notes": [ "新增 storage.inventory.transferLocation 接口,支持批量多商品多库位移库, 包含部分数量移库与全量移库。入参为 warehouse_id(仓库ID)和 transfers 数组(storage_id、target_space_id、quantity),触发 storage_transfer_completed 通知事件, 每条移库记录独立操作日志。isNeedAuth=true, isNeedLogin=true。" ], "type": "added" }, { "version": "2026.04.08-system-05", "date": "2026-04-08", "summary": "简化移库接口入参,从批量 transfers 数组改为单条移库", "methods": [ "storage.inventory.transferLocation" ], "notes": [ "移除 warehouse_id 和 transfers 数组入参,改为扁平的 storage_id + target_space_id + quantity 三个顶层参数。warehouse_id 从库存记录自动获取,接口从批量移库简化为单商品单库位移库。响应结构同步简化为单条结果对象。" ], "type": "modified" }, { "version": "2026.04.08-system-06", "date": "2026-04-08", "summary": "新增商品库存明细查询接口", "methods": [ "stock.warehouse.getStockDetail" ], "notes": [ "新增 stock.warehouse.getStockDetail 接口,按库位/批次维度查询商品库存分布。入参为 stock_id(必填,商品库存ID)和 pagination(可选,含 page/pageSize)。返回 stockItem(商品概要)、storageList(wms_storage 明细数组,含批次号、库位、数 量、锁定数量、生产日期、过期日期等,关联 location_space 库位信息)、pagination 分页信息。isNeedAuth=false, isNeedLogin=true。底层调用 stockStore.getStockDetail,自动校验商品归属当前仓库。" ], "type": "added" }, { "version": "2026.04.08-system-07", "date": "2026-04-08", "summary": "新增入参 group_by_batch,支持按批次维度切换库存明细聚合方式", "methods": [ "stock.warehouse.getStockDetail" ], "notes": [ "新增可选布尔参数 group_by_batch(默认 false)。false 时按库位合并数量,批次相关字段(batch_no, production_date, expiry_date, inbound_time, inbound_order_no, supplier_batch_no)置 null;true 时保持原逻辑返回每条明细。出参结构不变,但 storageList 中批次字段在合并模式下为 null。" ], "type": "modified" }, { "version": "2026.04.08-system-08", "date": "2026-04-08", "summary": "新增按商品维度移库接口", "methods": [ "storage.inventory.transferByProduct" ], "notes": [ "新增 storage.inventory.transferByProduct 接口,按库位+商品查找所有库存记 录合并移动。入参为 space_id(原库位ID)、stock_id(商品SKU ID,即 wms_stock_warehouse.id)、target_space_id(目标库位ID)、quantity(移库数量)。开启批次管理(is_batch_mgmt=Y)的商品会被拒绝,需使用 transferLocation 按库存记录精确移库。复用 storage_transfer_completed 通知事件,操作日志编码 STORAGE_TRANSFER_BY_PRODUCT。isNeedAuth=true, isNeedLogin=true。" ], "type": "added" }, { "version": "2026.04.08-system-09", "date": "2026-04-08", "summary": "补充 storeWarehouse.store.list 完整 response 输出字段说明,移除 api_config / apiConfig", "methods": [ "storeWarehouse.store.list" ], "notes": [ "从返回结果中移除 api_config 和 apiConfig 字段(代码中 delete serialized.api_config / delete serialized.apiConfig),文档 response 补充完整输出字段列表:id, store_id, store_name, warehouse_id, warehouse_name, counterparty_id, counterparty_name, current_subject_role, auth_status, auth_status_label, apply_reason, review_comment, apply_time, review_time, auth_start, auth_end, actual_end, print_quantity, applied_by, reviewed_by, ended_by, remask, use_status, policy_config, is_auth_valid, remaining_days 以及分页和 current_subject 信息。" ], "type": "updated" }, { "version": "2026.04.08-system-10", "date": "2026-04-08", "summary": "货主列表返回新增 has_qimen_config 布尔字段", "methods": [ "storeWarehouse.store.list" ], "notes": [ "storeWarehouse.store.list 返回的 data.list[] 中新增 has_qimen_config(boolean),表示该货主是否已配置奇门。" ], "type": "changed" }, { "version": "2026.04.08-system-11", "date": "2026-04-08", "summary": "补全 stock.warehouse.search 接口文档,新增 params / response / errors 完整说明", "methods": [ "stock.warehouse.search" ], "notes": [ "入参补充 keyword(string,模糊匹配 item_code / item_name / goods_code / barcode)和 store_id(number,按货主筛选)。响应补充 data 数组各字段(id, item_code, goods_code, item_name, sku_property, stock_unit, quantity, locked_quantity, brand_name, item_type, barcodes, store_stock)以及 total。errors 补充 code=0 搜 索失败场景。" ], "type": "updated" }, { "version": "2026.04.08-system-12", "date": "2026-04-08", "summary": "新增 with_stock / is_batch 参数,支持返回关联库存明细(按库位分 组或按批次逐条)", "methods": [ "stock.warehouse.search" ], "notes": [ "入参新增 with_stock(boolean,默认 false,是否返回关联库存数据)和 is_batch(boolean,默认 false,仅 with_stock=true 时生效,按批次明细返回)。响应 data[] 新增 storage[] 字段:is_batch=false 时按库位分组汇总(含 space_id、space、inventory_type、quantity、locked_quantity、available_quantity);is_batch=true 时逐 条返回批次明细(含 id、stock_id、space_id、batch_no、inventory_type、quantity、locked_quantity、available_quantity、production_date、expiry_date、inbound_time、inbound_order_no、supplier_batch_no、created_at、space)。" ], "type": "updated" }, { "version": "2026.04.08-system-13", "date": "2026-04-08", "summary": "新增 wms_stock_transaction 表和模型", "methods": [ "wms_stock_transaction" ], "notes": [ "新增出入库流水记录表 wms_stock_transaction,含 transaction_type(INBOUND/OUTBOUND)、warehouse_id、store_id、stock_id、storage_id、space_id、quantity、batch_no、inventory_type、order_type、order_no、order_id、receiving_id、entry_order_id、operator_id、operator_name、remark 等字段,关联 StockWarehouse 和 Storage 模型。" ], "type": "added" }, { "version": "2026.04.08-system-14", "date": "2026-04-08", "summary": "quickPutaway 和 matchPutaway 入库时自动写入出入库记录", "methods": [ "storage.inventory.quickPutaway", "storage.inventory.matchPutaway" ], "notes": [ "入库操作完成后自动写入 wms_stock_transaction 记录。quickPutaway 写入 order_type='SCRK'(收货入库),matchPutaway 写入 order_type='MATCH'(匹配入库),均 自动填充 warehouse_id、store_id、stock_id、storage_id、space_id、quantity、batch_no、inventory_type 等字段。" ], "type": "updated" }, { "version": "2026.04.08-system-15", "date": "2026-04-08", "summary": "新增 storage.inventory.list 出入库记录列表查询接口", "methods": [ "storage.inventory.list" ], "notes": [ "出入库记录列表查询,支持 where 条件(transaction_type、stock_id、space_id、store_id、order_type、order_no、inventory_type、operator_name、created_at)、 分页(pagination)、排序(sort)和 group_by_batch 参数。默认合并模式按库位+商品 聚合返回合计数量与记录条数,group_by_batch=true 时返回每条明细含 batch_no、order_no、operator_name 等完整信息。响应均关联 stockItem(item_code、item_name、sku_property、stock_unit)。" ], "type": "added" }, { "version": "2026.04.08-system-16", "date": "2026-04-08", "summary": "出入库流水记录查询接口从 storage.inventory.list 改名为 storage.transaction.list", "methods": [ "storage.transaction.list" ], "notes": [ "将出入库流水记录查询从 storage.inventory.list 迁移到 storage.transaction.list,避免与库存列表概念混淆。功能和参数不变。isNeedAuth=false, isNeedLogin=true, isNeedRight=false。" ], "type": "rename", "module": "storage" }, { "version": "2026.04.08-system-17", "date": "2026-04-08", "summary": "新增 storage.inventory.list 库存列表查询接口", "methods": [ "storage.inventory.list" ], "notes": [ "新增库存列表查询接口,查询 wms_storage 表。支持 where 条件(stock_id/space_id/store_id/inventory_type/batch_no/inbound_order_no/available_quantity/inbound_time/created_at)、分页、排序。支持 group_by_batch 参数:默认 false 按库位+商 品合并(SUM quantity/locked_quantity/available_quantity),true 返回每条明细含 batch_no/production_date/expiry_date 等。关联 stockItem(商品信息)和 space(库位信息)。isNeedAuth=false, isNeedLogin=true, isNeedRight=false。" ], "type": "add", "module": "storage" }, { "version": "2026.04.08-system-18", "date": "2026-04-08", "summary": "移除 storage.entry.create 创建入库单接口", "methods": [ "storage.entry.create" ], "notes": [ "不再允许通过 API 创建入库单。入库单仅由快捷入库(quickPutaway)和匹配入库(matchPutaway)等内部流程自动创建。底层 service 实现保留但不再通过 systemMethods 对外暴露。" ], "type": "remove", "module": "storage" }, { "version": "2026.04.08-system-19", "date": "2026-04-08", "summary": "移除 storage.entry.addDetail / deleteDetail / detailChange 对外 接口", "methods": [ "storage.entry.addDetail", "storage.entry.deleteDetail", "storage.entry.detailChange" ], "notes": [ "入库单明细编辑能力不再通过 systemMethods 对外暴露,入库单模块仅保留 list/get/cancel/completeEntry。" ], "type": "remove", "module": "storage" }, { "version": "2026.04.08-system-20", "date": "2026-04-08", "summary": "新增 storage.stockout 出库单模块(非订单出库单能力)", "methods": [ "storage.stockout.list", "storage.stockout.toOrder", "storage.stockout.listItems" ], "notes": [ "新增 storage.stockout.list / toOrder / listItems 接口,作为非订单出库单的主出口(对应奇门 stockout.create)。storage.delivery.* 仅作为兼容转发保留;底层 部分能力仍复用 order 模块。" ], "type": "add", "module": "storage" }, { "version": "2026.04.08-system-21", "date": "2026-04-08", "summary": "将 storage.stockout.toOrder 标记为占位接口", "methods": [ "storage.stockout.toOrder" ], "notes": [ "storage.stockout.toOrder 当前仅保留方法名用于后续扩展,暂不开放实际逻辑。调用时返回 code=405、message=占位接口,暂未开放。" ], "type": "change" }, { "version": "2026.04.09-system-01", "date": "2026-04-09", "summary": "storage.entry.cancel 支持批量作废,新增 ids 入参并兼容单条 id", "methods": [ "storage.entry.cancel" ], "notes": [ "新增入参 `ids`(number[])以支持批量作废,兼容旧入参 `id`;当同时传入 `ids` 与 `id` 时以 `ids` 为准。", "参数校验:`ids` 必须为非空数组;非法 ID 或空数组返回 400。", "业务约束:已完成/已作废/处于不可作废状态的单据不允许作废;批量场景下任一 单据不存在或状态不允许时整体返回 404/400,未执行部分更新。", "响应说明:单条作废返回字段 `id`(number);批量作废返回字段 `ids`(number[])。", "已同步更新 methods/system.json(storage.entry.cancel)为 SSOT。" ] }, { "version": "2026.04.09-system-02", "date": "2026-04-09", "summary": "新增基础模块车牌识别接口 index.recognizeLicensePlate", "methods": [ "index.recognizeLicensePlate" ], "notes": [ "入参:base64(string,必填)或 imageBase64/image_base64(兼容)", "响应:返回归一化后的识别对象,包含 licensePlate、plateNumber、color、confidence、requestId、imageSize、rawData", "错误:400(参数或图片格式/尺寸问题),500(第三方 OCR 调用失败或云密钥未 配置)", "文档中不包含任何敏感配置;实际腾讯云密钥保留在配置文件中,勿在文档中暴露 。" ], "type": "added" }, { "version": "2026.04.09-system-03", "date": "2026-04-09", "summary": "收紧基础模块车牌识别接口响应,仅返回 licensePlate 字段", "methods": [ "index.recognizeLicensePlate" ], "notes": [ "出参由 {licensePlate, plateNumber, color, confidence, requestId, imageSize, rawData} 调整为 {licensePlate}", "调用方请仅依赖 licensePlate 字段以适配新版本;历史字段已裁剪且不再保证存 在。", "文档中未包含任何云密钥或敏感配置信息。" ], "type": "changed" }, { "version": "2026.04.10-system-01", "date": "2026-04-10", "summary": "订单审核字段由 audit_status 替换为整数字段 step,并添加数据库迁移", "methods": [ "order.getreviewOrderlist", "order.reviewOrder.getreviewOrderlist", "order.reviewOrder.reviewOrder", "order.deliveryOrder.getdeliveryOrderlist", "order.list", "order.stats" ], "notes": [ "字段变更:order 相关审核字段从字符串/枚举 audit_status 替换为整数 step。", "step 映射:0=未审核,1=已审核,2=处理中,3=驳回/异常,4=配送中,5=已完成,9=已关闭。", "reviewOrder 接口在更新 inspection_status 的同时会写入 step 字段。", "必须执行迁移脚本:20260410150000-replace-audit-status-with-step-on-order-delivery-tables.js" ], "type": "changed" }, { "version": "2026.04.13-system-02", "date": "2026-04-13", "summary": "stock.warehouse.search 返回新增效期管理字段并保留 is_shelf_life_mgmt", "methods": [ "stock.warehouse.search" ], "notes": [ "响应 data[] 中新增字段:inbound_min_days、outbound_min_days、shelf_life_days、remaining_threshold_days(均为 number,单位:天)。", "保留并说明 is_shelf_life_mgmt 布尔字段(boolean),表示是否启用效期管理(true=启用)。", "仅更新文档(methods/system.json 与变更记录),代码行为不变。" ], "type": "updated" }, { "version": "2026.04.13-system-02", "date": "2026-04-13", "summary": "新增 storage.expiry.list 库存有效期列表查询接口", "methods": [ "storage.expiry.list" ], "notes": [ "该接口查询 wms_storage,关联 stockWarehouse 和 locationSpace,并按当前仓库与 remaining_threshold_days / expiry_date 过滤。" ], "type": "added" }, { "version": "2026.04.13-system-03", "date": "2026-04-13", "summary": "新增 storage.inventory.list 库存列表返回效期字段与预警标记", "methods": [ "storage.inventory.list" ], "notes": [ "库存列表响应增加生产日期、过期日期、效期预警是否触发字段", "预警标记仅在商品启用保质期管理且到期日满足阈值条件时为 true" ], "type": "updated" }, { "version": "2026.04.14-system-01", "date": "2026-04-14", "summary": "更新 index.searchSpace 文档", "methods": [ "index.searchSpace" ], "notes": [ "补充 index.searchSpace 的 params/response,按 ctx.user.store_id 作为仓库上下文;keyword 为可选字符串,对 space_code 与 custom_barcode 做 %keyword% 模糊匹配;返回字段 id、space_code、custom_barcode、custom_name,最多 50 条;仅文档同步,无代码变更。" ], "type": "updated" }, { "version": "2026.04.16-system-01", "date": "2026-04-16", "summary": "基础模块新增快递产品类型查询接口", "methods": [ "index.getExpressProductTypeList" ], "notes": [ "新增 index.getExpressProductTypeList,归属基础模块(module=index),用于查询指定快递公司的产品类型列表。", "对应服务实现:app/service/systems/express.js 中的 getExpressProductTypeList,支持传入 express_code 作为可选筛选参数(source=body)。", "接口设置为免鉴权(isNeedAuth=false)但需登录(isNeedLogin=true),与 index.getExpressList / index.getPlatformList 一致,优先从缓存读取。" ], "type": "added" }, { "version": "2026.04.17-system-01", "date": "2026-04-17", "summary": "新增快递管理模块(setting.express)及 5 个接口文档", "methods": [ "setting.express.list", "setting.express.listBase", "setting.express.create", "setting.express.checkCodeUnique", "setting.express.update" ], "notes": [ "新增独立模块组:快递管理模块(module=setting.express),将快递映射管理相关接口独立为一组以便维护。", "接口实现参考:app/service/systems/setting/express.js(返回结构)与 app/service/systemMethods/setting/express.js(对外方法包装)。", "接口鉴权与上下文:isNeedAuth=false, isNeedLogin=true;需在请求中传入 Authorization 以携带登录上下文(用于获取当前仓库/货主上下文)。", "已同步更新 methods/system.json,补充 params/response/errors,保持文档与实现一致。" ], "type": "added" }, { "version": "2026.04.17-system-02", "date": "2026-04-17", "summary": "setting.express.list 分页入参统一为 pagination", "methods": [ "setting.express.list" ], "notes": [ "将 setting.express.list 的分页入参文档从顶层 page/page_size/pageSize 迁移为 pagination 对象,主形态为 pagination;兼容 snake_case 的 page_size 与 camelCase 的 pageSize。", "文档与当前实现一致:顶层 page/page_size/pageSize 会被归一化到 data.pagination 并转发到系统服务。" ], "type": "updated" }, { "version": "2026.04.17-system-03", "date": "2026-04-17", "summary": "新增快递接口管理模块(setting.expressInterface)及 4 个接口文档", "methods": [ "setting.expressInterface.list", "setting.expressInterface.create", "setting.expressInterface.update", "setting.expressInterface.delete" ], "notes": [ "新增独立模块组:快递接口管理模块(module=setting.expressInterface),对应实现:app/service/systems/setting/expressInterface.js 与对外包装 app/service/systemMethods/setting/expressInterface.js。", "接口为当前仓库范围(基于 ctx.user.store_id),仓库边界由系统服务强制校验;禁止通过接口指定 warehouse_id/warehouseId。操作需登录(isNeedLogin=true),无需额外鉴权(isNeedAuth=false)。", "已在 methods/system.json 新增对应接口的 params/response/errors 文档,保持与实现一致。" ], "type": "added" }, { "version": "2026.04.18-system-01", "date": "2026-04-18", "summary": "补充订单储位分配接口文档:order.storageAllocation.allocateStorage", "methods": [ "order.storageAllocation.allocateStorage" ], "notes": [ "新增 order.storageAllocation.allocateStorage:按订单批量分配储位,支持多种入参别名(order_ids/ids/orderId 等)与仓库上下文优先级。", "响应包含 requested_order_ids, pending_order_ids, allocated_order_ids, shortage_order_ids, skipped_orders, picking_count, stock_lock_summary, storage_lock_summary 等字段,用于前端展示分配结果与不足提示。" ], "type": "added" }, { "version": "2026.04.18-system-02", "date": "2026-04-18", "summary": "新增 order.pendingOrder.allocateExpressCode:待处理订单模块的批量分配首单快递号(异步接口),复用 express.createWaybillCodePipeline。", "methods": [ "order.pendingOrder.allocateExpressCode" ], "notes": [ "异步接口:调用后立即返回 task_id,后台执行运单创建,通过 allocateExpressCodeTaskProgress 查询进度。", "入参为 ids(订单 ID 数组),sys_platform_code/logistics_code 等由后端从数据库读取。", "拆单场景请使用 order.pendingOrder.allocateSubOrderNumber。" ], "type": "added" }, { "version": "2026.04.18-system-03", "date": "2026-04-18", "summary": "将 order.storageAllocation.allocateStorage 迁移到 order.pendingOrder.allocateStorage,并移除原有公开分组。", "methods": [ "order.pendingOrder.allocateStorage" ], "notes": [ "将对外入口从 order.storageAllocation.allocateStorage 迁移到 order.pendingOrder.allocateStorage,旧的 order.storageAllocation 分组已从 methods/system.json 中移除。", "新的对外接口不接受 warehouse_id / warehouseId,仓库上下文由当前登录用户(ctx.user.store_id)提供。", "本次变更仅同步文档位置与对外方法名,底层实现保留且通过新的 system 方法暴露。" ], "type": "changed" }, { "version": "2026.04.19-system-02", "date": "2026-04-19", "summary": "新增待处理模块取消分配储位接口 order.pendingOrder.cancelAllocateStorage", "methods": [ "order.pendingOrder.cancelAllocateStorage" ], "notes": [ "新增待处理模块取消分配储位接口 `order.pendingOrder.cancelAllocateStorage`,直接对接 `service.systems.orderStorageAllocation.cancelAllocateStorage` 实现。", "接口现在仅接受订单ID(order_ids),不再接受 allow_storage_location;禁止传入 `warehouse_id/warehouseId`,仓库上下文由当前登录用户的 `store_id` 提供。", "响应返回标准 { flag, code, message, data } 结构,data 包含取消分配的汇总结果(warehouse_id, requested_order_ids, cancellable_order_ids, skipped_orders, orders, picking_count, storage_unlock_summary, stock_unlock_summary)。" ], "type": "added" }, { "version": "2026.04.21-system-01", "date": "2026-04-21", "summary": "新增 order.pendingOrder.updateOrderPlatform 方法:批量修改待处理订单平台信息", "methods": [ "order.pendingOrder.updateOrderPlatform" ], "notes": [ "通过 code 查找 wms_platform,平台不存在时返回 404 错误。", "仅操作当前仓库的当前订单表。", "noNeedRight=true,noNeedAuth=true(isNeedAuth: true 在 spec 中对应权限配置 noNeedAuth=true)。" ], "type": "added" }, { "version": "2026.04.21-system-02", "date": "2026-04-21", "summary": "新增方法 order.pendingOrder.updateOrderExpress:批量修改待处理订单的快递信息", "methods": [ "order.pendingOrder.updateOrderExpress" ], "notes": [ "新增 order.pendingOrder.updateOrderExpress:批量修改待处理订单的快递信息,按 express_code 从仓库快递列表(带缓存)匹配快递项。", "自定义映射(is_system_setting=true)时,sys_logistics_code/name 写入系统快递编码和名称,logistics_code/name 写入自定义编码和名称;系统快递(is_system_setting=false)时四个字段均写系统快递的 code/name。", "只操作当前仓库的当前订单表,不处理其他订单表;操作后写入操作日志(ORDER_UPDATE_EXPRESS)。" ], "type": "added" }, { "version": "2026.04.21-system-03", "date": "2026-04-21", "summary": "新增 order.expectionOrder.resolveException:将待处理异常订单转回正常待处理状态", "methods": [ "order.expectionOrder.resolveException" ], "notes": [ "新增 order.expectionOrder.resolveException:批量将 step=3 的异常订单恢复为 step=2 正常待处理状态。", "入参 ids 为订单ID 正整数数组,不能为空;仅操作当前仓库当前订单表。", "返回 updated_count(实际更新行数)与 ids(本次操作ID列表)。", "权限配置:noNeedLogin=false、noNeedRight=true、noNeedLog=false、noNeedAuth=true" ], "type": "added" }, { "version": "2026.04.21-system-04", "date": "2026-04-21", "summary": "新增 order.pendingOrder.cloneOrder 方法:克隆待处理订单", "methods": [ "order.pendingOrder.cloneOrder" ], "notes": [ "支持对 step 0/1/2/3 的待处理订单进行克隆操作。", "若原订单已分配储位(storage_status=fin),克隆前自动清除已分配库存。", "原订单取消后(step→9, status→cancel),以原订单业务数据创建新订单,流程状态字段全部重置为初始落库状态。", "克隆订单明细含 stock_id,新订单 ID 重新绑定。", "noNeedAuth=true,noNeedRight=true,noNeedLogin=false。" ], "type": "added" }, { "version": "2026.04.21-system-06", "date": "2026-04-21", "summary": "新增 order.pendingOrder.createOrder:手动创建待处理/待审核订单", "methods": [ "order.pendingOrder.createOrder" ], "notes": [ "新增 order.pendingOrder.createOrder:手动创建订单,step 由货主策略 need_order_approval 决定(1→待审核 step=0,0→待处理 step=1)。", "必填字段:store_id、name、mobile/tel 至少一项、detail_address、items[](含 item_code 和 plan_qty)。", "delivery_order_code 不传则自动生成(SYS+时间戳+随机4位);logistics_code/sys_platform_code 不传则读货主合约策略 default_express_code/default_platform_code。", "不做库存锁定,储位分配为独立步骤。操作日志写入 ORDER_CREATE。", "noNeedRight=true,noNeedAuth=true,noNeedLogin=false。" ], "type": "added" }, { "version": "2026.04.21-system-07", "date": "2026-04-21", "summary": "新增 Excel 模板下载与批量导入创建订单接口:order.pendingOrder.downloadCreateTemplate 和 order.pendingOrder.importOrdersFromExcel", "methods": [ "order.pendingOrder.downloadCreateTemplate", "order.pendingOrder.importOrdersFromExcel" ], "notes": [ "新增 order.pendingOrder.downloadCreateTemplate:生成 Excel 导入模板,返回 base64 编码的 xlsx 文件,表头中带 * 的列为必填项(橙色背景),可选列为灰色背景,含示例数据行和填写说明工作表。", "新增 order.pendingOrder.importOrdersFromExcel:接受 base64 编码的 xlsx 文件,按订单号分组,每组调用 createOrder 逻辑创建订单;不中断执行,逐条记录成功/失败结果返回。", "多行相同订单号的行组成一个完整订单,每行代表一条商品明细;订单头信息(收件人、地址等)取每组第一行。", "step 由货主策略 need_order_approval 决定(与 createOrder 一致);通过事务保证每个订单的主记录与明细原子写入。" ], "type": "added" }, { "version": "2026.05.01-system-01", "date": "2026-05-01", "summary": "新增基础模块 IM 登录码接口文档:index.loginToIm", "methods": [ "index.loginToIm" ], "notes": [ "新增 index.loginToIm 文档,入参为空对象({}),依赖当前登录用户上下文生成一次性 code。", "响应增加 data.code 字段,长度固定 64 位(hex),默认有效期 5 分钟。", "错误码补充:401(用户未登录)、400(用户信息不完整,缺 employees_id 或 employees_name)。", "该接口仅做登录码签发,实际换取员工信息由 IM 侧 ssoCodeToId 完成并在成功后使 code 失效。" ], "type": "added" }, { "version": "2026.05.01-system-03", "date": "2026-05-01", "summary": "扩展 index.loginToIm 返回字段:增加主体/主体类型/头像信息", "methods": [ "index.loginToIm" ], "notes": [ "登录码签发接口响应新增 employees_id、employees_name、subject、store_type、avatar 字段。", "subject 包含 id/name;store_type 严格取自 wms_store.project 字段,不再返回 subject_type 兼容字段。", "同一批字段会写入 code 缓存,供 IM 侧 ssoCodeToId 换取并在成功后失效。" ], "type": "updated" }, { "version": "2026.05.01-system-04", "date": "2026-05-01", "summary": "index.loginToIm 与 ssoCodeToId 改为严格字段模式,不再做兼容回退", "methods": [ "index.loginToIm" ], "notes": [ "loginToIm 仅读取 ctx.user 标准字段:employees_id、employees_name、store_id、store_name、store_type、avatar。", "不再兼容 id/real_name/username/company_name/avatar_url 等历史字段。", "ssoCodeToId 返回值不再使用默认兜底,缺少关键字段时按 code 无效处理。" ], "type": "updated" }, { "version": "2026.05.03-system-01", "date": "2026-05-03", "summary": "将 order.wave.fetch 调整为异步任务提交接口,删除同步返回抓取结果字段", "methods": [ "order.wave.fetch" ], "notes": [ "接口从同步返回抓取结果改为提交任务并异步处理。", "移除原方法中 result_list / total_request_quantity / total_fetched_quantity 等同步返回字段。" ], "type": "updated" }, { "version": "2026.05.03-system-06", "date": "2026-05-03", "summary": "order.wave.batchList:新增 where 支持并限制传入字段", "methods": [ "order.wave.batchList" ], "notes": [ "batchList 新增 where 支持及白名单过滤;禁止传入 warehouse_id/warehouseId。" ], "type": "updated" }, { "version": "2026.05.03-system-08", "date": "2026-05-03", "summary": "order.pendingOrder.allocateStorage 改为异步提交", "methods": [ "order.pendingOrder.allocateStorage" ], "notes": [ "接口变更为异步提交:调用后立即返回 request_id,后端异步执行储位分配;接口不再在响应中同步返回分配明细(如 requested_order_ids、allocated_order_ids 等)。客户端可后续通过任务 ID / 查询链路或事件获取最终分配结果。" ], "type": "updated" }, { "version": "2026.05.03-system-10", "date": "2026-05-03", "summary": "新增订单批量移出波次接口", "methods": [ "order.wave.batchRemoveOrders" ], "notes": [ "按订单ID批量移出波次;仅处理待处理订单表中非待审核订单(step in [1,2,3])。", "操作在单事务内完成:清空订单的 wave_id/wave_no,并回写 wms_wave_batch 统计(重算 total_orders;当波次被清空时将 wave_status 置为 -1)。", "仓库上下文来自当前登录用户(ctx.user.store_id)。" ], "type": "updated" }, { "version": "2026.05.08-system-05", "date": "2026-05-08", "summary": "order.wave.batchList:新增 source 字段并支持 where.source 过滤,返回 list item 中新增 source 字段", "methods": [ "order.wave.batchList" ], "notes": [ "新增 where.source(可选,number)用于按来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。", "响应 list 每条记录新增字段 source(number),用于区分波次来源。", "仅更新文档,业务代码不在此变更范围。" ], "type": "updated" }, { "version": "2026.05.09-system-01", "date": "2026-05-09", "summary": "新增 order.wave.wavePickTaskCancelSelf;order.wave.waveStrategyList 新增预演计数字段/参数", "methods": [ "order.wave.wavePickTaskCancelSelf", "order.wave.waveStrategyList" ], "notes": [ "新增接口 `order.wave.wavePickTaskCancelSelf`:仅支持单个 `task_id`(number,必填),明确不支持 `task_ids` 批量参数。", "业务约束:仅允许取消当前登录用户本人创建的拣货任务;若尝试取消非本人创建任务,接口应返回 400 错误(仅允许取消本人创建任务)。", "返回建议:与现有取消接口风格一致,包含 `cancelled_count`(0/1)、`task_id`、`task_no`(若后端返回)或相应的取消结果汇总。", "错误码建议:400 参数不合法(task_id 缺失或传了 task_ids);400 仅允许取消本人创建任务;500 取消失败。", "新增参数:calculate_next_fetch_order_count(number,可选),含别名 calculateNextFetchOrderCount;取值 0=不计算(默认),1=计算并返回每条策略的 next_fetch_order_count,用于前端在策略列表中预览抓取量。", "新增响应字段:list[*].next_fetch_order_count(number),含义:按当前策略口径预演一次自动抓取时,预计会选中的订单数量;当未开启计算时返回 0。" ], "type": "added" }, { "version": "2026.05.11-system-01", "date": "2026-05-11", "summary": "新增字段 wave_prefix(策略层波次前缀),并补充 PDA 抓取波次号生成行为说明", "methods": [ "order.wave.waveStrategyList", "order.wave.waveStrategyCreate", "order.wave.waveStrategyUpdate", "order.wave.waveStrategyFetchPda" ], "notes": [ "在 wave strategy 对象中新增可选字段 wave_prefix:策略波次前缀,优先于仓库前缀。", "校验规则:长度 1-5,仅允许 A-Z0-9;保存时会转为大写;为空时回退仓库前缀:团购使用 group_wave_prefix,散单使用 delete_order_wave_prefix。", "在 order.wave.waveStrategyList 的返回 list[*] 中新增字段 wave_prefix(string)。", "在 order.wave.waveStrategyCreate / waveStrategyUpdate 的入参中新增可选字段 wave_prefix(string),创建/更新成功后保存为大写且触发策略版本推进。", "在 order.wave.waveStrategyFetchPda 的行为说明中补充:生成波次号(wave_no)时优先使用策略层 wave_prefix,否则按策略类型回退到仓库前缀;前缀校验同上。" ], "type": "updated" }, { "version": "2026.05.15-system-01", "date": "2026-05-15", "summary": "仅更新文档:将 setting.express.create 入参与实现对齐(新增 express_code,移除 platform)", "methods": [ "setting.express.create" ], "notes": [ "仅同步文档,与实现对齐,未修改任何业务代码或行为" ], "type": "updated" }, { "version": "2026.05.15-system-02", "date": "2026-05-15", "summary": "新增 storage.report.search:库存流水统计报表,支持按时间闭区间过滤与按库位/按商品聚合", "methods": [ "storage.report.search" ], "notes": [ "方法新增:storage.report.search", "时间过滤为闭区间:created_at >= start_time 且 created_at <= end_time", "当 where.by_space 为 false(默认)时,按商品+货主聚合(多个库位汇总);当为 true 时按商品+库位返回", "不返回无流水的商品/键(仅返回在查询区间内出现过流水的数据)" ], "type": "added" }, { "version": "2026.05.15-system-03", "date": "2026-05-15", "summary": "库存报表模块主入口迁移到 stock.report.search,storage.report.search 保持兼容别名", "methods": [ "stock.report.search", "storage.report.search" ], "notes": [ "新增主入口方法 stock.report.search,沿用既有报表统计口径(时间闭区间、by_space/store_ids、返回字段保持一致)。", "保留 storage.report.search 作为兼容别名,并在描述中明确建议迁移到 stock.report.search。", "仅更新 methods 文档配置,不修改业务代码。" ], "type": "updated" }, { "version": "2026.05.15-system-04", "date": "2026-05-15", "summary": "文档主入口统一为 stock.report.search,storage.report.search 调整为兼容别名简述", "methods": [ "stock.report.search", "storage.report.search" ], "notes": [ "保留 stock.report.search 作为库存报表唯一完整文档入口。", "storage.report.search 不再维护完整重复字段,仅保留迁移与兼容说明。", "仅更新 methods 文档配置,不修改业务代码。" ], "type": "updated" }, { "version": "2026.05.15-system-05", "date": "2026-05-15", "summary": "拆分 storage.report 模块并移除错误 stock.report.search 文档入口", "methods": [ "storage.report.search", "stock.report.search" ], "notes": [ "将库存报表从 storage.inventory 中拆分为独立模块 storage.report,storage.report.search 文档改为主入口语义(不再作为兼容别名)。", "从 storage.inventory 分组中移除错误的 stock.report.search 文档入口以及兼容别名条目 storage.report.search。", "最终归属:storage.report.search 属于模块 storage.report;stock.report.search 的文档入口已移除以避免混淆(代码实现保留于 app/service/systemMethods/storage/report.js 的 storage.report.search)。", "仅修改文档,不修改应用代码实现。" ], "type": "updated" }, { "version": "2026.05.15-system-06", "date": "2026-05-15", "summary": "storage.report.search 新增排序能力文档说明", "methods": [ "storage.report.search" ], "notes": [ "补充 sort 参数:支持 sortField/sort_field、sortOrder/sort_order。", "补充排序白名单:begin_total、inbound_total、outbound_total、end_total。", "补充非法排序字段/顺序回退默认排序说明。", "响应说明补充:已按 sort 规则排序返回。" ], "type": "updated" }, { "version": "2026.05.16-system-01", "date": "2026-05-16", "summary": "新增 storage.report.export:按与 storage.report.search 相同条件导出库存报表 Excel", "methods": [ "storage.report.export" ], "notes": [ "新增方法:storage.report.export,复用 storage.report.search 的 where/sort 查询条件。", "导出文件包含两个 sheet:汇总、变更记录。", "用于在统计结果基础上回溯明细流水,提升库存变动追溯效率。" ], "type": "added" }, { "version": "2026.05.16-system-02", "date": "2026-05-16", "summary": "storage.report.export 改为异步任务 + 新增 exportTaskProgress", "methods": [ "storage.report.export", "storage.report.exportTaskProgress" ], "notes": [ "调用方式调整为两步:先调用 storage.report.export 提交任务并获取 task_id,再调用 storage.report.exportTaskProgress 轮询任务进度。", "下载链接获取方式:当 status=success 时,从 exportTaskProgress 响应的 download_url 字段获取导出文件地址。", "任务状态值补充:submitted/running/success/failed/not_found。" ], "type": "updated" }, { "version": "2026.05.16-system-03", "date": "2026.05.16", "summary": "同步 setting.expressInterface.create/update 入参与系统快递编码映射规则", "methods": [ "setting.expressInterface.create", "setting.expressInterface.update" ], "notes": [ "补充入参:sys_express_code、weight_type、address、town_name、ispickup、shipperno,并保留既有字段。", "在参数说明补充 camelCase 别名支持:sysExpressCode、weightType、townName、isPickup、shipperNo 等。", "同步约束变化:不再因同仓快递编码重复或平台重复直接返回 409;当 express_code 无法匹配系统快递编码时返回 400,文案为 express_code 未匹配到系统快递编码。" ], "type": "updated" }, { "version": "2026.05.17-system-05", "date": "2026-05-17", "summary": "同步 storage.receiving.addDetail 的参数与返回值(从实现提取)", "methods": [ "storage.receiving.addDetail" ], "notes": [ "补充 receiving_id 入参说明", "补充返回的 details 数组与 selectId 字段", "补充可能的错误码:404/400/500" ], "type": "updated" }, { "version": "2026.05.17-system-06", "date": "2026-05-17", "summary": "重新同步 addDetail 文档", "methods": [ "storage.receiving.addDetail" ], "notes": [ "再次从实现代码核对并补充参数/返回值/错误码,确保文档与实现一致", "仅同步文档,不修改业务代码" ], "type": "updated" }, { "version": "2026.05.17-system-07", "date": "2026-05-17", "summary": "addDetail 新增可选 item 入参并兼容空白创建链路", "methods": [ "storage.receiving.addDetail" ], "notes": [ "item 有值时按传入字段创建(服务端覆盖 receiving_id 与 creator_id)", "兼容不传 item 的空白创建链路;item.children 需覆盖关键字段(有则写、无则补齐)。" ], "type": "updated" }, { "version": "2026.05.17-system-10", "date": "2026-05-17", "summary": "调整 storage.receiving.getReceivingDetail 库位字段输出语义:space_id 改为展示名称并补充兼容字段", "methods": [ "storage.receiving.getReceivingDetail" ], "notes": [ "将 receiving.details.*.space_id 定义为展示名称(string|null),优先 custom_space_name,其次 space_name,不再作为原始数值ID文档语义。", "新增并明确 receiving.details.*.space_id_raw(number|null)用于保留原始库位ID,兼容旧调用方。", "补充 receiving.details.*.space_name(库位名称/编码)与 receiving.details.*.custom_space_name(自定义名称,可空)字段说明。" ], "type": "updated" }, { "version": "2026.05.17-system-11", "date": "2026-05-17", "summary": "补充 subject_config.enable_external_express_code 字段文档与默认值语义", "methods": [ "store.createStore", "store.createWarehouse", "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "在 store.createStore 与 store.createWarehouse 的 subject_config 入参中新增字段:enable_external_express_code(boolean),默认 false;开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)。", "此 change 同时用于说明将在 setting.warehouse.getSettings / saveSettings 中补充该字段的文档说明(后续 doc-only 写入)。" ], "type": "updated", "module": "store" }, { "version": "2026.05.17-system-12", "date": "2026-05-17", "summary": "storeWarehouse.store 策略配置文档新增 enable_external_express_code 字段说明(向后兼容)", "methods": [ "storeWarehouse.store.getPolicyConfig", "storeWarehouse.store.savePolicyConfig" ], "notes": [ "在 getPolicyConfig / savePolicyConfig 的出参说明中补充 data.policy_config.enable_external_express_code 字段,明确为 flag(0=关闭,1=开启),默认 0。", "在 savePolicyConfig 的入参说明中补充 policy_config.enable_external_express_code 字段定义。", "本次为向后兼容的文档增强:新增可选策略字段说明,不影响现有调用。" ], "type": "updated" }, { "version": "2026.05.19-system-01", "date": "2026-05-19", "summary": "补充 storage.entry.list 的 expense_record 筛选语义与未迁移环境错误提示", "methods": [ "storage.entry.list" ], "notes": [ "在 where 参数说明中补充 expense_record 字段语义(费用是否记录)及 eq/in 支持。", "明确 true/false、1/0、y/n、yes/no 的归一化规则与等价写法示例。", "补充未完成表结构迁移时可能返回 400 及错误提示文案。" ], "type": "updated" }, { "version": "2026.05.20-system-01", "date": "2026-05-20", "summary": "同步 order.recheckOrder.scanOrder 返回结构,补充 cart_match_view 语义化视图说明", "methods": [ "order.recheckOrder.scanOrder" ], "notes": [ "新增返回字段:match_type(waybill/cart)与 cart_match_view(仅 cart 命中返回)。", "cart_match_view 包含通用子字段:mode_code / mode_name / view_type / task;当车号命中时按 pick_mode 返回语义化结构:mode 1/5 返回 groups,mode 2 返回 orders,mode 3 返回 pick_groups,mode 4 返回 box_groups。" ], "type": "updated" }, { "version": "2026.05.22-system-01", "date": "2026-05-22", "summary": "新增 index.getPlatformOauthLink 文档,补充平台授权链接接口说明", "methods": [ "index.getPlatformOauthLink" ], "notes": [ "入参支持 code、platform_code、platformCode 三种平台编码字段别名。", "当前仅支持 PDD;成功返回 data.platform_code、data.oauth_link 和 code=200,其他平台返回 code=400。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.22-system-02", "date": "2026-05-22", "summary": "更新 index.getPlatformOauthLink 文档,补充仓库上下文、预占记录与错误说明", "methods": [ "index.getPlatformOauthLink" ], "notes": [ "补充真实行为:从 ctx.user.store_id 读取当前仓库 ID,从 wms_platform.auth_base_url 读取授权基础地址,并在 wms_shops 创建平台授权预占记录。", "补充 oauth_link 细节:追加 client_id、redirect_uri(配置非空时)以及长查询参数 wms_authorization_reservation_code,对应唯一 auth_random_code。", "补充常见错误:平台编码为空、仓库上下文缺失、平台不存在、授权基础地址缺失/格式错误、不支持的平台,以及预占记录创建失败。" ], "type": "updated", "module": "index" }, { "version": "2026.05.22-system-03", "date": "2026-05-22", "summary": "同步 index.getPlatformOauthLink 当前实现:裸码入库与 state 拼接规则", "methods": [ "index.getPlatformOauthLink" ], "notes": [ "补充真实行为:从 ctx.user.store_id 读取当前仓库,从 wms_platform.auth_base_url 读取基础授权链接,并优先复用 wms_shops 中 status=0 的未授权记录。", "明确 auth_random_code 当前以裸码保存;若复用到历史带前缀记录,会先去掉 platformOauthReservationCodePrefix 后再回写。", "更新 oauth_link 说明:state 由“前缀 + 平台编码 + '_' + 裸码”组成并整体 URL 编码后直接拼接到基础授权链接后,例如 xxxxx_PDD_;同时移除已不存在的基础地址格式错误/不支持平台错误描述。" ], "type": "updated", "module": "index" }, { "version": "2026.05.22-system-04", "date": "2026-05-22", "summary": "修正 index.getPlatformOauthLink 文档中的残留平台限制描述", "methods": [ "index.getPlatformOauthLink" ], "notes": [ "移除 index.getPlatformOauthLink 参数与返回字段中残留的“当前仅支持 PDD”描述,避免与当前实现不一致。", "保留授权链接仅依赖平台已配置基础授权链接模式的说明,不再把示例平台编码误写成实现限制。" ], "type": "updated", "module": "index" }, { "version": "2026.05.22-system-05", "date": "2026-05-22", "summary": "新增 index.getShopList 文档,并同步 custom_name 与店铺列表脱敏返回规则", "methods": [ "index.getShopList" ], "notes": [ "新增 index.getShopList:接口依赖当前登录仓库上下文 ctx.user.store_id,不接受额外业务入参,缺少仓库时返回 400:未识别到当前仓库。", "补充真实返回结构:data.list 为数组,包含 id、warehouse_id、platform_code、shop_name、custom_name、status、auth_expire_at、token_expires_at、refresh_token_expires_at、scope、created_at、updated_at 以及脱敏后的 owner_id、access_token、refresh_token、auth_random_code。", "同步脱敏规则:owner_id 非空且长度大于 5 时返回前 3 位 + *** + 后 2 位,长度小于等于 5 时返回 ***;access_token、refresh_token、auth_random_code 非空时固定返回 ***,空值返回 null。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改任何业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.22-system-06", "date": "2026-05-22", "summary": "新增 index.getShopExpressList 文档,补充店铺快递列表统一返回结构", "methods": [ "index.getShopExpressList" ], "notes": [ "按 ctx.user.store_id 校验店铺归属,仅允许查询当前登录仓库下的店铺。", "服务端按店铺所属平台拉取并收敛快递签约/电子面单可用列表,统一返回前端消费结构。", "未接入平台当前返回空列表;若店铺缺少授权 access_token,则返回 400:店铺未授权。", "仅文档同步,不改业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.22-system-07", "date": "2026-05-22", "summary": "同步快递接口文档:is_share 仅展示不可编辑", "methods": [ "setting.expressInterface.list", "setting.expressInterface.create", "setting.expressInterface.update" ], "notes": [ "create/update 不再接受 is_share", "list 仍可返回 is_share 作为展示信息", "仅文档同步,不改业务代码" ], "type": "updated", "module": "setting.expressInterface" }, { "version": "2026.05.22-system-08", "date": "2026-05-22", "summary": "同步快递接口列表文档,移除未返回字段说明", "methods": [ "setting.expressInterface.list" ], "notes": [ "根据 app/service/systems/setting/expressInterface.js 的 list() 查询字段与 normalizeInterfaceRow() 返回结构,同步 setting.expressInterface.list 不返回 token。", "按当前实现清理 response.children 中未返回的 share_id、can_use_count 字段说明。", "保留 is_share,并明确其仅用于展示,不作为编辑入参。" ], "type": "updated", "module": "setting.expressInterface" }, { "version": "2026.05.22-system-09", "date": "2026-05-22", "summary": "index.getShopList 支持按平台编码筛选店铺", "methods": [ "index.getShopList" ], "notes": [ "index.getShopList 兼容 platform_code 与 platformCode 两种传参方式,服务端按 platform_code、platformCode 顺序读取首个 trim 后非空值作为平台筛选条件。", "未传平台参数时返回当前登录仓库下全部已授权店铺;传入非空平台编码时仅返回该平台的已授权店铺。", "本次仅补充筛选条件文档,不影响返回结构、排序规则与 owner_id/access_token/refresh_token/auth_random_code 的脱敏规则。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改任何业务代码。" ], "type": "updated", "module": "index" }, { "version": "2026.05.22-system-10", "date": "2026-05-22", "summary": "快递接口配置新增 shop_id 字段", "methods": [ "setting.expressInterface.create", "setting.expressInterface.update", "setting.expressInterface.list" ], "notes": [ "create/update 支持 shop_id/shopId(兼容 snake_case 与 camelCase),为店铺 ID,未传或空值按 null 处理。", "list 返回 shop_id 字段,列表 where 支持按 shop_id 过滤。" ], "type": "updated" }, { "version": "2026.05.22-system-11", "date": "2026-05-22", "summary": "调整快递接口列表排序规则", "methods": [ "setting.expressInterface.list" ], "notes": [ "setting.expressInterface.list 改为按 weight ASC, id DESC 排序;优先按权重排序,权重相同再按 id 倒序。", "本次仅同步该接口排序说明,不影响返回结构。" ], "type": "updated", "module": "setting.expressInterface" }, { "version": "2026.05.22-system-12", "date": "2026-05-22", "summary": "index.getShopExpressList 返回新增系统快递编码", "methods": [ "index.getShopExpressList" ], "notes": [ "data.list[*] 新增 sys_express_code 字段,由平台快递编码 wp_code 映射系统快递编码,未匹配时返回空字符串。", "补充 data.list[*].wp_name 说明:由系统快递基础表根据平台快递编码映射得到名称,未匹配时返回空字符串。", "原有请求参数、鉴权方式与返回主结构保持不变。", "仅文档同步,不改业务代码。" ], "type": "updated", "module": "index" }, { "version": "2026.05.23-system-01", "date": "2026-05-23", "summary": "补充快递接口列表 is_system_express_code 返回字段说明", "methods": [ "setting.expressInterface.list" ], "notes": [ "在 setting.expressInterface.list 的 response.children 中补充 is_system_express_code 字段说明。", "该字段表示当前行 express_code 是否为系统快递编码;不是系统快递编码返回 0,否则返回 1。", "仅文档同步,不改业务代码。" ], "type": "updated", "module": "setting.expressInterface" }, { "version": "2026.05.23-system-02", "date": "2026-05-23", "summary": "完善 index.getExpressList 文档:补充过滤规则、返回字段与仓库维度行为", "methods": [ "index.getExpressList" ], "notes": [ "补充 `systemOnly`、`express_code`、`expressCode` 的真实入参语义,明确真值识别规则与字段优先级。", "补充默认模式、系统模式、按快递编码过滤模式下的返回差异,说明当前登录仓库维度来自 `ctx.user.store_id`。", "补充 `data[*]` 各字段含义,明确系统基础快递与仓库自定义快递编码的差异字段。", "仅文档同步,不修改业务代码。" ], "type": "updated", "module": "index" }, { "version": "2026.05.24-system-01", "date": "2026-05-24", "summary": "同步 index.getExpressList 文档:移除 expressCode 别名并明确 express_code 筛选语义", "methods": [ "index.getExpressList" ], "notes": [ "移除 index.getExpressList 文档中的 expressCode 驼峰别名参数,仅保留 express_code。", "明确当 systemOnly=false 且传入 express_code 时,接口按自定义映射记录中的系统快递编码字段 express_code 过滤,而不是按自定义 code 过滤。", "保留 systemOnly=true 按系统快递编码过滤系统基础快递列表,以及默认合并逻辑、缓存优先、仓库维度来源不变的说明。" ], "type": "updated" }, { "version": "2026.05.24-system-02", "date": "2026-05-24", "summary": "新增 index.getCainiaoStfTemplates 接口文档并明确模板返回语义", "methods": [ "index.getCainiaoStfTemplates" ], "notes": [ "新增无参接口 index.getCainiaoStfTemplates:从当前仓库首个已授权 TB 店铺发起 cainiao.waybill.ii.search 查询菜鸟 STF 模板。", "补充返回结构说明:data.platform_code 固定为 TB;data.list 返回模板数组并包含 template_id/template_name/template_url/cp_code/wp_code 字段。", "明确模板列表为宽松结构解析并按 template_id/template_name/template_url 核心语义去重。", "补充错误码说明:未识别仓库返回 400;当前仓库无已授权 TB 店铺返回 404。" ], "type": "added" }, { "version": "2026.05.24-system-03", "date": "2026-05-24", "summary": "调整 index.getCainiaoStfTemplates 为免登录/免鉴权接口", "methods": [ "index.getCainiaoStfTemplates" ], "notes": [ "将 index.getCainiaoStfTemplates 的 isNeedLogin 调整为 false,接口改为免登录访问。", "保持 isNeedAuth=false,并同步免权限拦截配置,避免登录态与鉴权拦截。", "该接口仍为无请求参数,headers 调整为空数组。" ], "type": "updated", "module": "index" }, { "version": "2026.05.24-system-04", "date": "2026-05-24", "summary": "调整 index.getCainiaoStfTemplates 为公共无参模板查询接口", "methods": [ "index.getCainiaoStfTemplates" ], "notes": [ "index.getCainiaoStfTemplates 改为公共无参查询,不再依赖当前仓库、登录态或店铺授权。", "接口直接调用 requestTbWaybillSearch({ cpCode: '' }) 查询公共模板,返回 data.platform_code='TB' 与模板数组。", "requestTbWaybillSearch 支持 accessToken 缺失时不下发 session,因此该接口不再依赖 session。" ], "type": "updated" }, { "version": "2026.05.24-system-05", "date": "2026-05-24", "summary": "同步 index.getCainiaoStfTemplates 改用淘宝标准模板公共接口", "methods": [ "index.getCainiaoStfTemplates" ], "notes": [ "index.getCainiaoStfTemplates 改为调用淘宝开放平台 cainiao.cloudprint.stdtemplates.get,不再复用 cainiao.waybill.ii.search。", "接口不需要用户授权,不下发 session,继续使用 https://eco.taobao.com/router/rest 与 TOP 公共签名参数。", "模板列表改为从 cainiao_cloudprint_stdtemplates_get_response.result.datas[*].standard_templates[*] 做宽松兼容解析,统一返回 template_id/template_name/template_url/cp_code/wp_code。" ], "type": "updated" }, { "version": "2026.05.24-system-06", "date": "2026-05-24", "summary": "新增 index.getPrintPlatformList 接口文档并明确打印平台下拉返回结构", "methods": [ "index.getPrintPlatformList" ], "notes": [ "新增 index.getPrintPlatformList 文档,说明该接口供快递接口新增/编辑页下拉选择使用。", "补充接口行为:仅返回未删除且状态为 ACTIVE 的打印平台,不分页,按 platform_name 与 id 升序返回。", "补充 data[*] 返回字段说明,明确 code/name/value/label/platform_code/platform_name/status/remark 的含义。", "仅文档同步,不修改业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.24-system-07", "date": "2026-05-24", "summary": "新增 index.getPrintPlatformTemplateList 文档,明确 express_code 必填与模板过滤语义", "methods": [ "index.getPrintPlatformTemplateList" ], "notes": [ "新增 index.getPrintPlatformTemplateList 方法文档,补充 platform_code 与 express_code 入参,其中 express_code 标记为必填。", "明确业务语义:接口按 platform_code(默认 CAINIAO)定位 wms_express 中对应打印平台字段,并使用 express_code 过滤模板结果后返回。", "补充返回结构 data.platform_code / data.express_code / data.responseData,说明未实现平台返回空对象。", "仅文档同步,不修改业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.25-system-01", "date": "2026-05-25", "summary": "新增 index.polyapiAuthorizeUrl 接口文档并标注免登录免鉴权特征", "methods": [ "index.polyapiAuthorizeUrl" ], "notes": [ "新增基础模块方法 index.polyapiAuthorizeUrl,说明其为公共无参接口。", "明确接口固定调用菠萝派 Differ.JH.BuildeAuthorizeUrl,返回体中以 data.respone 原样包裹上游响应。", "同步标注 isNeedLogin=false、isNeedAuth=false,headers 为空数组。" ], "type": "added" }, { "version": "2026.05.25-system-02", "date": "2026-05-25", "summary": "新增店铺模块相关接口文档(shops.list/add/del/edit)及授权会话接口 shops.GetAuthorizeSessionKey", "methods": [ "shops.list", "shops.add", "shops.del", "shops.edit", "shops.GetAuthorizeSessionKey" ], "notes": [ "同步实现:shops.list 支持 where 分页与 quickWhere 快速搜索;shops.add/edit 校验 platform_code 存在且为 ACTIVE,custom_name 必填且长度限制;shops.del 为软删除,会返回 deleted=true 并清空敏感字段,若存在快递接口引用返回 409;shops.GetAuthorizeSessionKey 对 PDD/CAINIAO 平台生成预占码并返回 authorize_url,其他平台返回 501。", "字段命名兼容说明:接口实现兼容 snake_case 与 camelCase 入参,文档以 snake_case 为主并注明兼容性。" ], "type": "added" }, { "version": "2026.05.25-system-03", "date": "2026-05-25", "summary": "同步 shops.add 去入参化:移除 shop_name 入参并明确由授权后获取店铺名称", "methods": [ "shops.add" ], "notes": [ "shops.add 入参移除 shop_name(及同义传参语义),仅保留 custom_name 与 platform_code 为关键请求字段。", "补充说明:新增时 shop_name 由服务端生成 PENDING_* 占位名,后续以授权回调同步真实店铺名称。", "仅文档同步,不修改任何业务代码。" ], "type": "updated", "module": "shops" }, { "version": "2026.05.28-system-02", "date": "2026-05-28", "summary": "新增 method: order.print.unlockWavePlatformPrintDataByGroup,按分组解锁波次平台打印锁", "methods": [ "order.print.unlockWavePlatformPrintDataByGroup" ], "notes": [ "新增方法:order.print.unlockWavePlatformPrintDataByGroup,用于按分组规则批量解锁波次内被锁定的订单(将 print_lock_status 设为 'none')。", "入参说明:group_type 默认为 platform_express(支持 platform、platform_express、order),unlock_scope 默认为 group(支持 group、wave);groups 为必须项,元素对象可包含 wave_id、platform、sys_logistics_code、order_ids 等字段。", "返回说明:返回 summary(解锁统计)、unlocked_order_ids、unlocked_orders、ext.missing_wave_ids、ext.filtered_wave_ids 等字段。", "实现参考:app/service/systemMethods/order/print.js 与 app/service/systems/order_print.js 的 unlockWavePlatformPrintDataByGroup 实现,相关单元测试位于 test/app/controller/system.order.print.unlockByGroup.test.js 与 test/app/service/systems/order_print.unlockWavePlatformPrintDataByGroup.test.js。" ], "type": "updated" }, { "version": "2026.05.28-system-03", "date": "2026-05-28", "summary": "新增 order.updateExpressWeighingWeight 方法文档并补充单/多运单称重写入规则", "methods": [ "order.updateExpressWeighingWeight" ], "notes": [ "新增 order.updateExpressWeighingWeight 入参说明:order_id、waybill_code、weighing_weight。", "明确规则:单运单订单忽略 waybill_code 并直接更新唯一运单;多运单订单必须传 waybill_code 且需匹配订单下运单。", "补充成功返回字段:order_id、waybill_code、weighing_weight。", "补充错误码:400(参数校验与多运单缺失运单号)、404(运单记录不存在或未匹配)、500(模型未初始化或更新失败)。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" ], "type": "added", "module": "order.index" }, { "version": "2026.05.28-system-01", "date": "2026-05-28", "summary": "新增包材相关 methods(create/update/delete/get),并提供 list 兼容说明", "methods": [ "setting.packageMaterial.create", "setting.packageMaterial.update", "setting.packageMaterial.delete", "setting.packageMaterial.get", "setting.packageMaterial.list" ], "notes": [ "实现参考:app/service/systems/setting/packageMaterial.js", "list 为兼容别名,内部转发至 get,建议新接入方改用 get" ], "type": "updated" }, { "version": "2026.05.28-system-04", "date": "2026-05-28", "summary": "Add packageSupplier methods (create/update/delete/get) with list alias note", "methods": [ "setting.packageSupplier.create", "setting.packageSupplier.update", "setting.packageSupplier.delete", "setting.packageSupplier.get", "setting.packageSupplier.list" ], "notes": [ "Reference implementation: app/service/systems/setting/packageSupplier.js", "list is a compatibility alias; prefer get" ], "type": "updated" }, { "version": "2026.05.28-system-05", "date": "2026-05-28", "summary": "新增 order.bindExpressPackageMaterial 方法文档,支持按订单运单绑定包材", "methods": [ "order.bindExpressPackageMaterial" ], "notes": [ "新增 order.bindExpressPackageMaterial 入参说明:order_id、waybill_code、package_material_code(均必填)。", "补充行为说明:按订单ID+运单号匹配 wms_order_express,按包材编码匹配包材并绑定 package_material_id 与 package_material_name_snapshot。", "补充成功返回字段:order_id、waybill_code、package_material_id、package_material_name_snapshot、package_material_code。", "补充错误码:400 参数错误、404 包材编码不存在、404 订单运单记录不存在、500 绑定包材失败。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" ], "type": "added", "module": "order.index" }, { "version": "2026.05.29-system-01", "date": "2026-05-29", "summary": "新增 order.export 与 order.exportTaskProgress:订单导出异步任务与进度查询", "methods": [ "order.export", "order.exportTaskProgress" ], "notes": [ "order.export:提交导出任务,入参支持 table_type/tableType(枚举 current/history/dispatch/outsourced,兼容订单模块别名)与 module/module_name,where/sort 语义与 order.list 一致。接口提交后立即返回 task_id,后台异步执行导出,导出进度与结果通过 order.exportTaskProgress 查询。", "order.exportTaskProgress:按 task_id 查询任务进度,返回 task_id、status、progress、current_count、total_count、message、error、download_url、update_time;任务上传完成后 download_url 返回可下载链接,未找到时 status=not_found。" ], "type": "added", "module": "order.index" }, { "version": "2026.05.30-system-01", "date": "2026-05-30", "summary": "新增 print.notifyLock(及 notify_lock 兼容别名),并补充 print.send 写入订单操作日志的行为说明", "methods": [ "print.notifyLock", "print.notify_lock", "print.send" ], "notes": [ "新增 print.notifyLock:入参支持 order_ids/orderIds、waveGroups、data.waveGroups(至少一类提供订单 ID);仅执行订单锁定流程,不发送打印任务;写打印任务日志 + 订单操作日志;返回 locked_count、order_ids_count、order_ids、source;错误:无有效订单ID(400)、锁定失败(500)。", "补充 print.send 文档:说明接口在执行打印任务记录的同时会写入订单操作日志(记录打印相关操作)。", "新增兼容别名 print.notify_lock:文档说明等价转调到 print.notifyLock。" ], "type": "updated", "module": "print" }, { "version": "2026.06.03-system-01", "date": "2026-06-03", "summary": "同步 pick.query 文档为 keyword 任务化语义并补充冲突错误码", "methods": [ "pick.query" ], "notes": [ "入参由 waybill_code/full_display 统一为 keyword(支持运单号或波次号)。", "成功返回调整为 task_id/status/tip,status 取值 existing 或 created。", "补充 409 冲突语义:波次已有他人活动任务时返回任务归属信息。" ], "type": "updated" }, { "version": "2026.06.03-system-02", "date": "2026-06-03", "summary": "更新 pick.wavePickTaskDetail:增加快递号/储位分配前置校验并返回 action+order_ids", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "新增前置校验:任务内若存在未分配快递号订单,返回 400,data.action=assign_express,data.order_ids 为未分配订单ID列表。", "新增前置校验:任务内若存在未分配储位订单,返回 400,data.action=assign_storage,data.order_ids 为未分配订单ID列表。", "保留原有权限校验与详情结构,仅补充分配校验失败分支的返回约定。" ], "type": "updated" }, { "version": "2026.06.03-system-03", "date": "2026-06-03", "summary": "更新 order.wave.batchList:新增同步状态输出与筛选 sync_assignment_status", "methods": [ "order.wave.batchList" ], "notes": [ "新增返回字段语义:list[].sync_assignment_status,取值为未同步/部分同步/已同步/同步异常。", "新增筛选入参 where.sync_assignment_status,支持 unsynced/partially_synced/synced 英文枚举。", "同步状态筛选规则与分配状态一致:error 并入 unsynced 过滤集合。" ], "type": "updated" }, { "version": "2026.06.03-system-04", "date": "2026-06-03", "summary": "更新拣货中间态流程文档:wavePickTaskDetail 增加完成标记,并新增中间态/完全提交接口", "methods": [ "pick.wavePickTaskDetail", "pick.wavePickTaskSubmit", "pick.wavePickTaskComplete" ], "notes": [ "更新 pick.wavePickTaskDetail 返回:新增 task.is_completed、task.progress(total_orders/picked_orders/pending_orders)以及顶层 is_completed。", "新增 pick.wavePickTaskSubmit:支持保存中间态 payload 到任务 ext_json.pick_intermediate,并返回当前完成状态与进度。", "新增 pick.wavePickTaskComplete:支持 mode=1 全部确认与 mode=2 部分确认(order_ids),返回 confirmed_order_ids 与最新进度。" ], "type": "updated" }, { "version": "2026.06.03-system-05", "date": "2026-06-03", "summary": "拣货车能力拆分为一级模块 pickCart:扫码查询、任务绑车、CRUD、编码查重", "methods": [ "pickCart.scan", "pickCart.bindTaskCart", "pickCart.create", "pickCart.update", "pickCart.delete", "pickCart.detail", "pickCart.list", "pickCart.codeDuplicateCheck" ], "notes": [ "拣货车能力独立为一级模块 pickCart,不再挂在 pick 模块下。", "新增 pickCart.scan:PDA 按 cart_code 扫码查询拣货车信息,用于进入任务绑定流程。", "新增 pickCart.bindTaskCart:支持按 cart_id/cart_code 将拣货车绑定到指定拣货任务,若车已绑定其他活动任务则返回冲突。", "新增 pickCart.create/pickCart.update/pickCart.delete/pickCart.detail/pickCart.list:补齐拣货车增删查改与分页查询能力。", "新增 pickCart.codeDuplicateCheck:支持 exclude_cart_id 排除自身,供编辑场景做非自身重复校验;拣货车编码在当前仓库内不可重复。" ], "type": "updated" }, { "version": "2026.06.03-system-06", "date": "2026-06-03", "summary": "更新 order.wave.batchList:新增 only_todo、复核状态聚合与复核筛选", "methods": [ "order.wave.batchList" ], "notes": [ "新增入参 only_todo(默认 0):传 1/true 时仅返回仍有未复核订单的波次(unreviewed_order_count > 0)。", "新增返回字段:list[].unreviewed_order_count(未复核订单数)与 list[].review_assignment_status(未复核/部分复核/已复核)。", "新增 where.review_assignment_status 筛选,支持 unreviewed/partially_reviewed/reviewed 英文枚举。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.04-system-01", "date": "2026-06-04", "summary": "裁剪 pick.wavePickTaskDetail 返回:团购小波次(pick_mode=1)不返回 picking_details 字段以减少带宽", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "在 picking_details 字段 description 中补充:当 pick_mode=1(团购小波次)时该字段不返回,减少带宽浪费;其他 pick_mode(2/3/4/5)正常返回 picking_details。", "在接口 description 中补充该裁剪行为的说明。", "picking_summary、picking_view、boxes 等字段不受影响,pick_mode=1 时仍正常返回。" ], "type": "updated" }, { "version": "2026.06.04-system-02", "date": "2026-06-04", "summary": "完善 index.getPlatformList 文档:补充入参 systemOnly/full、响应字段及错误码 500", "methods": [ "index.getPlatformList" ], "notes": [ "补充入参说明:systemOnly(可选,支持 is_system 别名,真值识别 true/1/'1'/'true')、full(可选,真值识别同上,为 true 时返回全量表字段与 route_platform_code/platid 等扩展信息)", "补充响应 data 数组每项字段:code、name、value、label、platform_code、platform_name、default_express_interface、is_system_setting、id(仅仓库自定义项)、alias(仅仓库自定义项)、full 模式扩展字段说明", "说明合并逻辑:系统平台在前,仓库自定义在后,同 code 仅保留首条(系统优先);systemOnly=true 仅返回系统平台", "补充缓存策略:优先读缓存,key 格式为 platform:list:{warehouseId}[:full] 或 platform:list:system[:full]", "补充错误码 500:数据库或缓存访问异常", "仅文档更新,不修改任何业务实现" ], "type": "updated", "module": "index" }, { "version": "2026.06.04-system-03", "date": "2026-06-04", "summary": "作废 order.pendingOrder.downloadCreateTemplate 和 order.pendingOrder.importOrdersFromExcel", "methods": [ "order.pendingOrder.downloadCreateTemplate", "order.pendingOrder.importOrdersFromExcel" ], "notes": [ "order.pendingOrder.downloadCreateTemplate:下载订单导入模板方法已从代码中移除,标记为 deprecated。", "order.pendingOrder.importOrdersFromExcel:从 Excel 导入订单方法已从代码中移除,标记为 deprecated。", "两个方法的文档条目保留在 methods/system.json 中,仅追加 status: 'deprecated' 与 description 中的'(已作废)'标记,未删除。" ], "type": "deprecated" }, { "version": "2026.06.05-system-01", "date": "2026-06-05", "summary": "新增 storeWarehouse.store.openAccount 接口:仓库代货主一键开户(合并注册账号+创建货主+签约)", "methods": [ "storeWarehouse.store.openAccount" ], "notes": [ "新增 storeWarehouse.store.openAccount 方法,归属货主-仓库签约模块(storeWarehouse.store)。", "接口同时完成账号注册、货主创建和仓库-货主签约,一步完成开户全流程。", "当前主体必须为仓库角色(Authorization header 中携带的 token 对应仓库用户)。", "必填参数:username(登录账号)、password(初始密码)、company_name(公司全称)、business_license(营业执照号)、contact_person(联系人)、contact_phone(联系电话)。", "响应返回新创建的 store_id、account_id、contract_id、company_name、username、role_id。" ], "type": "added", "module": "storeWarehouse" }, { "version": "2026.06.05-system-02", "date": "2026-06-05", "summary": "优化 storeWarehouse.store.openAccount 必填参数:password 改为随机生成、business_license 和 contact_phone 改为可选,必填仅剩 username/company_name/contact_person 三个", "methods": [ "storeWarehouse.store.openAccount" ], "notes": [ "password:由必填改为可选,不传时自动随机生成 12 位密码", "business_license:由必填改为可选", "contact_phone:由必填改为可选" ], "type": "updated" }, { "version": "2026.06.05-system-03", "date": "2026-06-05", "summary": "saveApiConfig 增加 callback_url 参数,支持配置 API 回调通知地址", "methods": [ "storeWarehouse.store.saveApiConfig" ], "notes": [ "新增 callback_url 参数:OpenAPI 类型接口支持配置回调通知 URL", "兼容别名 callbackUrl,最大 500 字符", "存入 wms_api_app.callback_url 字段" ], "type": "modified" }, { "version": "2026.06.05-system-04", "date": "2026-06-05", "summary": "createOrder 入参 item_code 改为 item_id,province/city/area 改为必填", "methods": [ "order.pendingOrder.createOrder" ], "notes": [ "items[].item_code → items[].item_id:改用商品主键直接匹配,不依赖外部系统商品推送", "province/city/area 新增必填校验,空值返回 400", "item_name 优先外部传入,其次从 StockStore 缓存获取,最后兜底'商品'" ], "type": "modified" }, { "version": "2026.06.05-system-05", "date": "2026-06-05", "summary": "新增 order.pendingOrder.parseAddress 智能地址解析方法", "methods": [ "order.pendingOrder.parseAddress" ], "notes": [ "使用 DeepSeek AI 模型将非结构化地址字符串解析为省/市/区/详细地址/收件人/手机号", "解析结果可直接用于 createOrder 的 receiverInfo 字段", "DeepSeek API Key 通过 DEEPSEEK_API_KEY 环境变量配置" ], "type": "added" }, { "version": "2026.06.05-system-06", "date": "2026-06-05", "summary": "waveStrategyUpdate/waveStrategyCreate 新增 wave_prefix 参数", "methods": [ "order.wave.waveStrategyUpdate", "order.wave.waveStrategyCreate" ], "notes": [ "新增 wave_prefix 波次编号前缀字段,最多 5 个字符,为空存 null" ], "type": "modified" }, { "version": "2026.06.05-system-07", "date": "2026-06-05", "summary": "parseAddress 响应新增 town 字段(乡镇/街道)", "methods": [ "order.pendingOrder.parseAddress" ], "notes": [ "响应 data 中新增 town 字段,返回 AI 解析出的乡镇/街道名称" ], "type": "modified" }, { "version": "2026.06.05-system-08", "date": "2026-06-05", "summary": "为 order.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-09", "date": "2026-06-05", "summary": "为 order.reviewOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.reviewOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-10", "date": "2026-06-05", "summary": "为 order.pendingOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.pendingOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-11", "date": "2026-06-05", "summary": "为 order.outboundOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.outboundOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-12", "date": "2026-06-05", "summary": "为 order.expectionOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.expectionOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-13", "date": "2026-06-05", "summary": "为 order.entrustOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.entrustOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-14", "date": "2026-06-05", "summary": "为 order.deliveryOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.deliveryOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-15", "date": "2026-06-05", "summary": "为 order.deliveryExpectionOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.deliveryExpectionOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-16", "date": "2026-06-05", "summary": "为 order.archiveOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.archiveOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.06-system-01", "date": "2026-06-06", "summary": "恢复 order.pendingOrder.downloadCreateTemplate:方法仍存在于代码中,取消 deprecated 标记,完善文档描述", "methods": [ "order.pendingOrder.downloadCreateTemplate" ], "notes": [ "order.pendingOrder.downloadCreateTemplate 方法在 pendingOrder.js 中仍存在(line 2099),此前被误标记为 deprecated。", "取消 status: 'deprecated' 标记,恢复为 active 状态。", "移除 description 中的'(已作废)'后缀。", "完善 description:说明模板包含必填列(橙色背景)、可选列(灰色背景)、示例数据行和填写说明工作表。", "补充 response 字段说明:filename 和 mime 为固定值。" ], "type": "updated" }, { "version": "2026.06.07-system-01", "date": "2026-06-07", "summary": "order.pendingOrder.createOrder 文档新增 shop_nick 入参(店铺名称,可选,最大长度200)", "methods": [ "order.pendingOrder.createOrder" ], "notes": [ "在 order.pendingOrder.createOrder 的 request params 中新增 shop_nick 字段(string,非必填),对应代码实现中 shopNick: String(requestData.shop_nick || requestData.shopNick || '').trim()。", "shop_nick 已在 COPY_FIELDS 白名单中(pendingOrder.js L1738),仅文档缺失,本次为补齐。" ], "type": "updated" }, { "version": "2026.06.07-system-02", "date": "2026-06-07", "summary": "order.pendingOrder.downloadCreateTemplate:模板新增 shop_nick 列(店铺名称),store_id/province/city/area 标注为非必填", "methods": [ "order.pendingOrder.downloadCreateTemplate" ], "notes": [ "模板新增 shop_nick(店铺名称)列,非必填。", "明确标注 store_id(货主ID)、province(省份)、city(城市)、area(区/县)为非必填列。", "响应文档中新增 shop_nick 字段说明。" ], "type": "updated" }, { "version": "2026.06.07-system-03", "date": "2026-06-07", "summary": "新增 order.pendingOrder.updateAddress:批量修改待处理订单收件地址,限制未分配快递时可用", "methods": [ "order.pendingOrder.updateAddress" ], "notes": [ "新增 method:order.pendingOrder.updateAddress,免权限(isNeedAuth=false),需登录", "功能:批量修改待处理订单收件地址(name/mobile/tel/zip_code/province/city/area/town/detail_address)", "约束:仅 post_status='none'(未分配快递)的订单可修改;至少提供一个有效地址字段", "响应:返回 updated_count(实际更新行数)和 ids(请求订单ID数组)" ], "type": "added" }, { "version": "2026.06.07-system-04", "date": "2026-06-07", "summary": "order.wave.wavePickTaskCancel 扩展可取消状态至 status=3,并新增拣货状态回退", "methods": [ "order.wave.wavePickTaskCancel" ], "notes": [ "可取消状态从 [0,1,2] 扩展为 [0,1,2,3](status=3 已完成现在也可取消)", "取消 status=2(待复核)或 status=3(已完成)任务时,自动回退 wms_wave_pick_task_order.pick_status(1→0)和 order_delivery.pick_status(fin→padding)", "错误码 400 描述同步更新,补充 403 错误码说明" ], "type": "updated" }, { "version": "2026.06.07-system-05", "date": "2026-06-07", "summary": "order.wave.wavePickTaskList 响应新增 cart_name 字段(拣货车名称)", "methods": [ "order.wave.wavePickTaskList" ], "notes": [ "响应 list 子项新增 cart_name(string):通过 current_cart_id LEFT JOIN wms_pick_cart 表获取,未绑定拣货车时为空字符串。" ], "type": "updated" }, { "version": "2026.06.07-system-06", "date": "2026-06-07", "summary": "pick.wavePickTaskComplete 新增后台抓取任务(source=2)拣货车绑定校验,未绑定拣货车时拒绝提交", "methods": [ "pick.wavePickTaskComplete" ], "notes": [ "description 补充说明:后台抓取创建的任务(source=2)必须先绑定拣货车才能提交,否则返回 400。", "errors 中 400 错误补充:后台抓取任务(source=2)未绑定拣货车时拒绝提交,错误消息为\"后台抓取任务必须先绑定拣货车才能提交\"。" ], "type": "updated" }, { "version": "2026.06.07-system-07", "date": "2026-06-07", "summary": "order.wave.batchList 文档修正:移除代码中不存在的 sync_assignment_status 引用", "methods": [ "order.wave.batchList" ], "notes": [ "从 where 描述中移除 sync_assignment_status(代码 buildBatchListWhereClause allowedFields 中不存在该字段,BATCH_LIST_ASSIGNMENT_FILTER_SCHEMAS 中也无 review 之外的同步类型)。", "从 response list 描述中移除 sync_assignment_status(代码响应映射中仅返回 storage/express/print/review 四种 assignment_status,无 sync_assignment_status)。", "v2026.06.03-system-03 变更记录中声称新增的 sync_assignment_status 实际从未在代码中实现,本次仅为文档修正,不涉及代码变更。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.07-system-08", "date": "2026-06-07", "summary": "order.recheckOrder.confirmRecheck 补充后置行为说明:波次任务全部复核完成后自动解绑车任务", "methods": [ "order.recheckOrder.confirmRecheck" ], "notes": [ "在 description 中补充:确认复核后,若该订单所属波次拣货任务下所有订单均已复核完成,则自动解绑车任务。解绑操作包括:清空 wms_wave_pick_task 的 current_cart_id/current_cart_code_snapshot、停用 wms_pick_task_cart_binding(is_active=0 并记录解绑人和时间)、释放 wms_pick_cart(清空 current_task_id/bind_user_id)。", "解绑失败仅记录 warn 日志,不影响复核主流程。", "入参和返回结构未变,仅补充行为说明。" ], "type": "updated" }, { "version": "2026.06.07-system-10", "date": "2026-06-07", "summary": "移除 order.wave.groupFetch / singleFetch / fetch 响应中已废弃的 auto_fetch_disabled_marker 字段", "methods": [ "order.wave.groupFetch", "order.wave.singleFetch", "order.wave.fetch" ], "notes": [ "auto_fetch_disabled_marker 字段已从代码 submitFetchTask 响应中移除,文档同步删除该字段的描述。", "auto_fetch_disabled 字段同样已从代码中移除,且原文档中不存在此字段(仅有 auto_fetch_disabled_marker),无需额外处理。", "涉及 method:order.wave.groupFetch、order.wave.singleFetch、order.wave.fetch,均移除 response 中的 auto_fetch_disabled_marker 字段。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.08-system-01", "date": "2026-06-08", "summary": "order.recheckOrder 模块 scanOrder 返回值重构为统一 list 输出,新增 confirmIntercept 与 recheckOrderList 接口", "methods": [ "order.recheckOrder.scanOrder", "order.recheckOrder.confirmIntercept", "order.recheckOrder.recheckOrderList" ], "notes": [ "scanOrder 返回值重构:统一使用 list 字段输出,新增 list_type 字段区分散单/团购模式。散单模式顶层新增 picker_id、picker_name、wave_id、wave_no、wave_type、pick_mode、strategy_id、strategy_name、total_orders、reviewed_count、unreviewed_count 等汇总字段。list 中每项新增 waybill_no、is_printed、is_reviewed、wave_index、intercept_status、store_remark、stock[](含 stock_id、item_code、item_name、sku_property、packing_requirements、barcodes[]、images[]、plan_qty、has_shared_barcode)。移除旧字段 logs、order、order_id(顶层)、waybill_no(顶层旧位置)、wave_match_view、items、expresses、cart_match_view。", "scanOrder 入参新增 wave_no / waveNo 支持波次号直接扫描匹配。", "新增 order.recheckOrder.confirmIntercept:确认拦截接口,将订单 intercept_status 更新为 intercepted_at_warehouse,返回 order_id、order_no、intercept_status、updated_at。", "新增 order.recheckOrder.recheckOrderList:复核订单列表查询,支持 list_type=single(散单)与 list_type=group(团购),均返回统一 list + pagination 结构。" ], "type": "updated" }, { "version": "2026.06.08-system-02", "date": "2026-06-08", "summary": "order.recheckOrder 模块新增 batchIntercept/batchInterceptTaskProgress,更新 scanOrder 团购模式响应结构,完善 confirmIntercept/recheckOrderList 文档", "methods": [ "order.recheckOrder.batchIntercept", "order.recheckOrder.batchInterceptTaskProgress", "order.recheckOrder.scanOrder", "order.recheckOrder.confirmIntercept", "order.recheckOrder.recheckOrderList" ], "notes": [ "新增 order.recheckOrder.batchIntercept:批量提交订单拦截(异步任务模式),入参支持 order_ids/orderIds/ids(订单ID数组,不再使用 wave_ids),将 intercept_status 设为 'requested',返回 task_id/warehouse_id/message/accepted_at。支持幂等提交与 warehouse_id 校验。", "新增 order.recheckOrder.batchInterceptTaskProgress:按 task_id 查询批量拦截任务进度,返回 state(submitted/running/success/failed/not_found)及对应的进度/计数/结果/错误字段。", "更新 order.recheckOrder.scanOrder 响应文档:团购模式(cart 命中)list 项新增 wave_id/wave_no/wave_type/wave_status/total_orders/processed_orders/creator/create_time/update_time/order_count/pick_mode/box_no/orders[] 等波次级别字段;补充散单无波次信息时的回退详情模式说明(detail/items/expresses/logs)。", "完善 order.recheckOrder.confirmIntercept:补充操作日志写入说明(ORDER_INTERCEPT_CONFIRM)及失败不影响主流程的容错描述。", "完善 order.recheckOrder.recheckOrderList:补充散单模式默认排除 pick_status='none' 和 recheck_status='fin' 的说明;团购模式 where 支持 wave_no(模糊搜索)的说明。" ], "type": "updated" }, { "version": "2026.06.08-system-03", "date": "2026-06-08", "summary": "移除 order.recheckOrder.batchIntercept 的 warehouse_id/warehouseId 入参,仓库ID统一使用当前上下文", "methods": [ "order.recheckOrder.batchIntercept" ], "notes": [ "移除入参 warehouse_id / warehouseId:仓库ID统一从当前上下文(ctx.user.store_id)获取,不再由调用方传入。", "移除对应错误码:warehouse_id 参数不合法(400)、warehouse_id 与当前仓库上下文不一致(400)。", "description 中补充说明仓库ID来源为当前上下文。", "response 中 warehouse_id 字段描述改为「取自当前上下文」。" ], "type": "updated" }, { "version": "2026.06.08-system-10", "date": "2026-06-08", "summary": "batchIntercept / batchInterceptTaskProgress 从 order.recheckOrder 迁移至 order.pendingOrder", "methods": [ "order.pendingOrder.batchIntercept", "order.pendingOrder.batchInterceptTaskProgress" ], "notes": [ "method 从 order.recheckOrder.batchIntercept 重命名为 order.pendingOrder.batchIntercept,分组从订单复核模块迁移至订单待处理模块", "method 从 order.recheckOrder.batchInterceptTaskProgress 重命名为 order.pendingOrder.batchInterceptTaskProgress,分组从订单复核模块迁移至订单待处理模块", "接口入参、响应、错误码均保持不变,仅变更 method 名称与所属分组" ], "type": "updated" }, { "version": "2026.06.08-system-04", "date": "2026-06-08", "summary": "新增 order.print.getOrderPrintData:按订单ID拉取打印数据,返回结构与 getWavePlatformPrintData 一致,不限制锁定状态", "methods": [ "order.print.getOrderPrintData" ], "notes": [ "新增 order.print.getOrderPrintData 接口文档,入参为 warehouse_id + order_ids(非空数组),返回与 getWavePlatformPrintData 结构一致的 waveGroups / summary / wave_ids / ext", "与 getWavePlatformPrintData 的区别:入参为 order_ids(非 wave_ids),ext 中返回 missing_order_ids / filtered_order_ids(非 missing_wave_ids / filtered_wave_ids)", "不限制打印锁定状态,所有订单(无论是否被锁定)统一返回打印数据", "自动过滤 post_status !== 'fin' 的订单(快递未完全分配),被过滤订单出现在 ext.filtered_order_ids" ], "type": "added", "module": "order.print" }, { "version": "2026.06.08-system-11", "date": "2026-06-08", "summary": "新增 order.pendingOrder 批量锁定/解锁/解除拦截及对应进度查询共 6 个异步任务接口文档", "methods": [ "order.pendingOrder.batchLock", "order.pendingOrder.batchLockTaskProgress", "order.pendingOrder.batchUnlock", "order.pendingOrder.batchUnlockTaskProgress", "order.pendingOrder.batchUnintercept", "order.pendingOrder.batchUninterceptTaskProgress" ], "notes": [ "新增 batchLock:批量锁定订单,lock_status → 'warehouse',操作日志 ORDER_LOCK,task_id 格式 order_lock_{warehouseId}_{timestamp}_{rand}。", "新增 batchLockTaskProgress:查询批量锁定进度,返回 locked_order_count / locked_order_ids 等。", "新增 batchUnlock:批量解锁订单,lock_status → 'none',操作日志 ORDER_UNLOCK,task_id 格式 order_unlock_{warehouseId}_{timestamp}_{rand}。", "新增 batchUnlockTaskProgress:查询批量解锁进度,返回 unlocked_order_count / unlocked_order_ids 等。", "新增 batchUnintercept:批量解除拦截订单,intercept_status → 'none',操作日志 ORDER_INTERCEPT_CANCEL,task_id 格式 order_unintercept_{warehouseId}_{timestamp}_{rand}。", "新增 batchUninterceptTaskProgress:查询批量解除拦截进度,返回 unintercepted_order_count / unintercepted_order_ids 等。", "以上 6 个接口均采用与已有 batchIntercept/batchInterceptTaskProgress 一致的异步任务模式:提交返回 task_id,进度查询返回 state + 进度字段。", "仅同步文档,不修改业务代码或实现。" ], "type": "added", "module": "order" }, { "version": "2026.06.08-system-12", "date": "2026-06-08", "summary": "更新 order.print.getOrderPrintData:移除锁定限制,所有订单统一返回打印数据,不再区分锁定/未锁定", "methods": [ "order.print.getOrderPrintData" ], "notes": [ "移除打印锁定限制:所有订单(包括已锁定)统一返回打印数据,不再区分锁定/未锁定状态", "移除 locked_count、locked_orders、locked_wave_groups 等锁定相关字段", "返回结构与 getWavePlatformPrintData 完全一致:summary / waveGroups / wave_ids / ext", "ext 中使用 missing_order_ids / filtered_order_ids(替代锁定相关字段),与代码实现完全对齐" ], "type": "updated", "module": "order.print" }, { "version": "2026.06.08-system-13", "date": "2026-06-08", "summary": "更新 order.print.getOrderPrintData:移除 warehouse_id 入参,仓库ID统一从当前上下文获取", "methods": [ "order.print.getOrderPrintData" ], "notes": [ "移除 warehouse_id / warehouseId 入参,仓库ID统一从 this.getContextWarehouseId() 获取", "同步移除 errors 中 warehouse_id 必填 相关错误码", "description 补充说明仓库ID从上下文获取,无需调用方传入", "params 仅保留 order_ids(非空数组),与代码 method 层 getOrderPrintData(data) 解构一致" ], "type": "updated", "module": "order.print" }, { "version": "2026.06.08-system-14", "date": "2026-06-08", "summary": "新增 order.recheckOrder.scanTask 接口文档,并为 scanOrder 响应补充 task_id 字段", "methods": [ "order.recheckOrder.scanTask", "order.recheckOrder.scanOrder" ], "notes": [ "新增 order.recheckOrder.scanTask:按拣货任务 ID 拉取复核数据,数据结构与 scanOrder 完全一致,用于前端刷新。入参为 task_id(必填,number),返回 match_type='task',散单模式(pick_mode 2/3/4)返回扁平订单列表,团购模式(pick_mode 1/5)返回分组波次列表。", "更新 order.recheckOrder.scanOrder 响应定义:补充 task_id 字段说明(散单有波次时由 buildSingleWaveScanView 返回,团单车号命中时由 cartMatchContext 返回)。", "仅同步文档,不修改任何业务代码或实现。" ], "type": "updated" }, { "version": "2026.06.08-system-15", "date": "2026-06-08", "summary": "新增 order.pendingOrder.manualWaybill 接口(手工录入运单号)", "methods": [ "order.pendingOrder.manualWaybill" ], "notes": [ "为待处理订单手动录入运单号,写入 wms_order_express 表", "仅允许 step 在 [1,2,3] 且 outbound_status 不为 'padding' 的订单操作", "免权限(isNeedAuth: false),需登录", "成功返回运单记录的 id、order_id、waybill_code、create_at" ], "type": "added" }, { "version": "2026.06.09-system-01", "date": "2026-06-09", "summary": "order.pendingOrder.updateAddress 新增 remark 字段:订单留言/备注批量覆盖,不受 post_status 限制", "methods": [ "order.pendingOrder.updateAddress" ], "notes": [ "在 params 中新增 remark 字段(string,可选,最大500字符),支持批量覆盖所选订单的 remark", "remark 更新不受 post_status 限制,可对所有订单生效(地址字段仍仅允许 post_status='none')", "更新 description 明确 remark 与地址字段的独立性", "更新 response 中 updated_count 说明:取地址更新行数与备注更新行数的最大值", "更新 errors 中缺少字段的错误描述,改为「至少需要提供一个地址字段或备注进行修改」", "业务代码已同步实现,本次仅同步文档" ], "type": "updated" }, { "version": "2026.06.09-system-02", "date": "2026-06-09", "summary": "order.updateExpressWeighingWeight 新增运单号模式文档:order_id=0 时从运单号反查,支持散单与团购批量两种返回结构", "methods": [ "order.updateExpressWeighingWeight" ], "notes": [ "order_id 参数说明补充:设为0时切换为运单号模式,需配合 waybill_code 使用。", "waybill_code 参数说明补充:运单号模式(order_id=0)下必填。", "description 更新:明确订单模式与运单号模式两种路径及团购波次批量行为。", "response 新增运单号散单场景字段(order_id、waybill_code、weighing_weight)与运单号团购批量场景字段(wave_no、business_key、weighing_weight、success_count)。", "errors 新增运单号模式相关错误码:运单号不存在(404)、运单号对应的订单不存在(404)、波次下未找到订单(404)、批量更新失败(500)。", "仅文档同步,不修改业务代码。" ], "type": "updated" }, { "version": "2026.06.09-system-03", "date": "2026-06-09", "summary": "order.updateExpressWeighingWeight 团购返回新增拆单汇总字段,移除 success_count/total_count", "methods": [ "order.updateExpressWeighingWeight" ], "notes": [ "团购批量模式 response 新增 total_weight(所有拆单重量累加)、split_count(waybill_code 非空的 business_key 数量)、splits(按 business_key 分组的拆单明细数组,每项含 business_key/weighing_weight/waybill_code)、store_name(货主名称)和 sys_logistics_name(系统快递名称)。", "移除 response 中的 success_count 与 total_count 字段,改为由 total_weight 和 split_count 提供汇总信息。", "更新 description 以反映团购模式返回拆单汇总结构。" ], "type": "updated" }, { "version": "2026.06.10-system-01", "date": "2026-06-10", "summary": "order.detail 接口文档:expresses 数组新增字段 weighing_weight、sys_logistics_code、sys_logistics_name、business_key、created_at", "methods": [ "order.detail" ], "notes": [ "expresses 数组新增字段:weighing_weight(称重重量,number|null)、sys_logistics_code(系统物流公司编码,string)、sys_logistics_name(系统物流公司名称,string)、business_key(业务标识,string)、created_at(创建时间戳毫秒,number|null)", "字段来源:getOrderExpressesByOrderId 方法中 sys_logistics_code/sys_logistics_name 取自订单表 sys_logistics_code/sys_logistics_name,其余字段取自 OrderExpress 表" ], "type": "updated" }, { "version": "2026.06.10-system-02", "date": "2026-06-10", "summary": "dashboard.order_trend 从 mock 数据改为查询真实数据库,按小时统计当日订单数与发货数,补充完整返回结构与错误说明", "methods": [ "dashboard.order_trend" ], "notes": [ "接口实现从 mock 静态数据改为查询真实数据库(wms_order_delivery 与 dispatch 表),数据实时反映仓库当日运营情况。", "订单筛选条件:step in [1,2,3],排除 outbound_status='padding' 和 status='cancel',统计 create_at 在今日 00:00 到当前时刻的订单,按 HOUR(create_at) 分组。", "发货筛选条件:dispatch_lane='m4',统计 delivery_time 在今日 00:00 到当前时刻的发货记录,按 HOUR(delivery_time) 分组。", "时段范围:从 08:00 到当前小时(最晚 23:00),若当前时间早于 08:00 则从 08:00 开始。", "返回新增 summary 汇总对象:total_orders(订单总数)、total_shipments(发货总数)、shipment_rate(发货率百分比)、peak_hour(峰值时段)、peak_orders(峰值订单数)。", "categories/orders/shipments 三个数组一一对应,提供按时段的订单与发货趋势数据,可直接用于前端折线图/柱状图渲染。", "需要登录(Authorization header),从 token 中获取 warehouseId;若缺少仓库上下文则返回 flag='fail'。" ], "type": "updated", "module": "dashboard" }, { "version": "2026.06.10-system-03", "date": "2026-06-10", "summary": "order.pendingOrder.manualWaybill 新增可选参数 logistics_interface_name 与响应字段 business_key/logistics_interface_name,补充行为说明", "methods": [ "order.pendingOrder.manualWaybill" ], "notes": [ "新增可选参数 logistics_interface_name(string,选填,trim 后为空则传 null)", "响应新增字段 business_key(number):同一订单下从已有最大值 +1 递增,无记录时从 1 开始", "响应新增字段 logistics_interface_name(string/null):写入的物流接口名称", "补充 description 行为说明:完成后自动更新 wms_order_delivery_* 表的 print_status 和 post_status 为 'fin'", "wms_order_express 表写入时 status 固定为 1,warehouse_id 从订单记录取" ], "type": "updated" }, { "version": "2026.06.10-system-04", "date": "2026-06-10", "summary": "stock.warehouse.import 新增 barcode(条码)字段支持", "methods": [ "stock.warehouse.import" ], "notes": [ "新增 barcode(条码)字段支持,支持别名:条码、bar_code、barCode、barcodeList、barcode_list、barcode。", "条码字段支持数组格式(如 [\"6901234567890\"])和分号分隔字符串格式(如 \"6901234567890;6901234567891\")。", "新建和更新路径均已支持条码导入,条码写入 wms_stock_barcodes 表。", "仅同步文档,不修改业务代码或实现。" ], "type": "updated" }, { "version": "2026.06.10-system-05", "date": "2026-06-10", "summary": "stock.warehouse.import 的 barcode 字段分隔符改为逗号,对齐 stock.warehouse.export 导出格式;仅接收字符串格式,不再支持数组", "methods": [ "stock.warehouse.import" ], "notes": [ "barcode 字段分隔符从分号 ; 改为逗号 ,", "barcode 字段仅接收字符串格式,不再支持数组格式", "格式示例:\"6901234567890,6901234567891\",与 stock.warehouse.export 导出格式一致" ], "type": "modified" }, { "version": "2026.06.13-system-01", "date": "2026-06-13", "summary": "setting.warehouse 的 auto_outbound_rules 新增 require_print 和 require_pick 两个可选条件字段(同步代码实现)", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "在 getSettings 响应和 saveSettings 入参中补充 subject_config.auto_outbound_rules 对象的完整字段文档(enabled、require_recheck、require_pack、require_weigh、require_sync、require_print、require_pick)。", "require_print:是否要求已打印(print_status=fin),默认 true。", "require_pick:是否要求已拣货(pick_status=fin),默认 true。", "该规则由自动出库定时任务 order_auto_outbound 消费,全部开启的条件均满足时自动标记待出库。" ], "type": "updated" }, { "version": "2026.06.13-system-02", "date": "2026-06-13", "summary": "order.recheckOrder.scanOrder 团购模式响应新增 orders_detail 字段,暴露非拦截订单的详细列表(含 is_printed、is_reviewed 等状态字段)", "methods": [ "order.recheckOrder.scanOrder" ], "notes": [ "团购模式(list_type='group')波次视图项新增 orders_detail 字段:非拦截订单详细列表,每项含 order_id、delivery_order_code、waybill_no、pick_status、is_printed(print_status === 'fin')、is_reviewed(recheck_status === 'fin')、recheck_status、shop_nick、items_count、wave_index、intercept_status", "orders_detail 与现有 order_ids(纯数字 ID 数组)并存,均在团购模式的波次视图项中返回", "orders_detail 仅在 list_type='group' 时返回,散单模式不受影响", "同步更新 list 字段 description 以反映 group 模式新增的 order_ids、orders_detail、stocks 字段" ], "type": "updated" }, { "version": "2026.06.13-system-03", "date": "2026-06-13", "summary": "新增批量快捷复核接口 batchQuickRecheck,支持批量订单 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败。拣货完成后同步更新 wms_wave_pick_task 状态", "methods": [ "order.recheckOrder.batchQuickRecheck" ], "notes": [ "新增 order.recheckOrder.batchQuickRecheck 方法", "入参 ids 支持数组或逗号分隔字符串", "响应包含 success/failed 列表及计数,failed 项含 reason 说明" ], "details": { "description": "包含拣货任务状态同步:全部拣完→任务状态=2(已完成),未全拣完→任务状态推进为1(拣货中)" }, "type": "added" }, { "version": "2026.06.14-system-01", "date": "2026-06-14", "summary": "新增 order.bindExpressPackageMaterialByWaybill 方法:支持仅凭运单号绑定包材,无需传入订单ID", "methods": [ "order.bindExpressPackageMaterialByWaybill" ], "notes": [ "新增 order.bindExpressPackageMaterialByWaybill 入参说明:waybill_code(运单号,必填)、package_material_code(包材编码,必填)。无需传入 order_id。", "成功返回字段:order_id、waybill_code、package_material_id、package_material_name_snapshot、package_material_code。", "错误码定义:400(参数错误)、404(运单号不存在 / 包材编码不存在)、500(绑定包材失败)。" ], "type": "added" }, { "version": "2026.06.15-system-01", "date": "2026-06-15", "summary": "order.detail / order.deliveryOrder.detail 的 expresses 数组新增包材字段", "methods": [ "order.detail", "order.deliveryOrder.detail" ], "notes": [ "expresses 数组每个元素新增 package_material_id(包材ID,number|null)和 package_material_name_snapshot(包材名称快照,string|null)字段。" ], "type": "updated" }, { "version": "2026.06.15-system-02", "date": "2026-06-15", "summary": "order.deliveryOrder.detail 的 expresses 数组新增包材字段", "methods": [ "order.deliveryOrder.detail" ], "notes": [ "expresses 数组每个元素新增 package_material_id(包材ID,number|null)和 package_material_name_snapshot(包材名称快照,string|null)字段。" ], "type": "updated" }, { "version": "2026.06.15-system-03", "date": "2026-06-15", "summary": "新增 setting.packageMaterial.search 方法:支持按关键字模糊搜索包材编码和名称", "methods": [ "setting.packageMaterial.search" ], "notes": [ "新增 setting.packageMaterial.search 入参 keyword(可选),为空返回前 50 条启用中包材,有值时对 material_code 和 material_name 做模糊匹配。", "返回包材数组,字段:id、material_code、material_name、material_type、spec、status。" ], "type": "added" }, { "version": "2026.06.16-system-01", "date": "2026-06-16", "summary": "新增 order.recheckOrder.queryRecheckOrderSingleList:散单复核列表接口,响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", "methods": [ "order.recheckOrder.queryRecheckOrderSingleList" ], "notes": [ "新增方法 order.recheckOrder.queryRecheckOrderSingleList,为 recheckOrderList 散单模式的独立入口。", "响应 list 每项新增字段 items_weight (DECIMAL(10,2)):订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null。", "响应 list 每项新增字段 weight_type (string):重量类型中文标签,来自 wms_order.weight_type 经 formatWeightTypeLabel 转换;取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。" ], "type": "added", "module": "order.recheckOrder" }, { "version": "2026.06.16-system-02", "date": "2026-06-16", "summary": "为 order.wave.groupOrderFetchList / waveStrategyFallbackOrderList / singleOrderFetchList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", "methods": [ "order.wave.groupOrderFetchList", "order.wave.waveStrategyFallbackOrderList", "order.wave.singleOrderFetchList" ], "notes": [ "order.wave.groupOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", "order.wave.waveStrategyFallbackOrderList:响应 list 每项新增 items_weight (number|null):订单总重量(g),来自 wms_order.items_weight;新增 weight_type (string):重量类型中文标签,取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。", "order.wave.singleOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", "所有新增字段均为可选(required=false),为 null 时返回 null。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.17-system-01", "date": "2026-06-17", "summary": "新增 order.pendingOrder.replenishmentDemand 分拣缺货补货需求计算接口文档", "methods": [ "order.pendingOrder.replenishmentDemand" ], "notes": [ "新增分拣缺货补货需求计算方法,用于计算待处理订单的SKU在分拣区与存货区的库存分布及补货缺口", "入参 order_ids/warehouse_id 均为可选;不传 order_ids 时自动查询当前仓库所有未完成储位分配的订单", "纯只读查询接口,不修改任何数据", "响应包含 list(明细)与 summary(汇总),其中 shortage = max(0, total_demand - pick_zone_quantity),replenishment_needed = min(shortage, storage_zone_quantity)" ], "type": "add", "module": "order.pendingOrder" }, { "version": "2026.06.17-system-02", "date": "2026-06-17", "type": "update", "module": "order.pendingOrder", "method": "order.pendingOrder.replenishmentDemand", "description": "移除 order_ids 参数,改为纯仓库级别计算,自动查询当前仓库所有未完成储位分配的订单" }, { "version": "2026.06.17-system-03", "date": "2026-06-17", "type": "update", "module": "order.pendingOrder", "method": "order.pendingOrder.replenishmentDemand", "description": "新增 is_true_shortage 字段标识真正缺货(两区均无库存),summary 新增 total_true_shortage_skus 统计" }, { "version": "2026.06.17-system-04", "date": "2026-06-17", "type": "migrate", "module": "storage.management", "summary": "从 order.pendingOrder.replenishmentDemand 迁移至 storage.management.replenishmentDemand(库存管理模块),原路径已删除,开发阶段无需兼容", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "将 replenishmentDemand 接口从 order.pendingOrder 模块迁移到新建的 storage.management 库存管理模块。", "旧条目 order.pendingOrder.replenishmentDemand 已从 order.pendingOrder 组中移除。", "开发阶段无需兼容旧路径。" ] }, { "version": "2026.06.17-system-05", "date": "2026-06-17", "type": "update", "module": "storage.management", "summary": "storage.management.replenishmentDemand 移除 warehouse_id 入参,仓库ID改为纯从用户上下文(ctx.user)获取,接口无需入参", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "移除 warehouse_id 入参,仓库ID改为纯从用户上下文(ctx.user)获取,接口无需入参" ] }, { "version": "2026.06.17-system-06", "date": "2026-06-17", "type": "update", "module": "storage.management", "method": "storage.management.replenishmentDemand", "description": "新增分页入参(pagination)、排序入参(sort,默认按 shortage DESC)、响应新增 replenishment_locations(存货区可补货库位,最多5条)、响应新增 pagination 分页信息" }, { "version": "2026.06.17-system-07", "date": "2026-06-17", "type": "update", "module": "storage.management", "summary": "replenishment_locations 新增 space_name 字段,优先取自定义名称(custom_name),无则回退库位编码(space_code)", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "在 replenishment_locations.children 中新增 space_name 字段(string, required),放在 space_code 之后、available_quantity 之前。", "space_name 取值逻辑:优先使用库位自定义名称 custom_name,若无自定义名称则回退为库位编码 space_code。" ] }, { "version": "2026.06.17-system-08", "date": "2026-06-17", "type": "update", "module": "storage.management", "summary": "合并 is_sufficient 和 is_true_shortage 为 replenishment_status 枚举字段(replenishable/true_shortage)", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "删除 is_sufficient(boolean)和 is_true_shortage(boolean)两个字段。", "新增 replenishment_status(string)枚举字段:replenishable=存货区足够覆盖缺口,移库可解决;true_shortage=存货区不足以覆盖缺口或两区均无库存,需采购。" ] }, { "version": "2026.06.18-system-01", "date": "2026-06-18", "summary": "入库单完成后异步匹配收货单并回传:completeEntry / entryorderConfirm 入库完成时自动匹配收货单,明细一致则按来源回传(奇门/OpenAPI),覆盖场景标记收货单部分入库;completeReceiving 完成后清除收货单缓存", "methods": [ "storage.entry.completeEntry", "storage.receiving.completeReceiving" ], "notes": [ "新增 app/service/systems/receiving_entry_match.js:入库单完成后异步匹配收货单并回传的核心服务,含 Redis 缓存收货单列表(TTL 300s)、remark 匹配收货单号、明细对比、奇门回传、OpenAPI 回调、部分入库标记等能力。", "storage.entry.completeEntry 完成后通过 setImmediate 异步触发 matchAfterEntryCompleted,不阻塞主流程。", "entry_order.js entryorderConfirm() 事务提交后(isFin 最终完成)同样异步触发匹配。", "storage.receiving.completeReceiving 完成后清除收货单 Redis 缓存(cache:receiving_orders:warehouse:{warehouseId}),确保下次匹配获取最新收货单列表。", "匹配规则:入库单 remark 包含收货单号 → 对比 SKU+数量 → 完全一致回传 / 收货单覆盖标记部分入库 / 其他不处理。", "回传路径:source_type=QM → 奇门 taobao.qimen.entryorder.confirm;source_type=API → OpenAPI 回调(entry_order_receiving_matched 事件)。" ], "type": "updated" }, { "version": "2026.06.18-system-02", "date": "2026-06-18", "summary": "新增 storage.receiving.manualMatchEntryOrder 接口", "methods": [ "storage.receiving.manualMatchEntryOrder" ], "notes": [ "新增 storage.receiving.manualMatchEntryOrder:手动匹配入库单与收货单,传入 receivingId 和 entryOrderId,复用异步匹配服务的明细对比和回传逻辑,同步返回匹配结果", "参数:receivingId (number, 必填)、entryOrderId (number, 必填)", "校验:入库单存在性、收货单存在性、同仓库校验", "返回 matchType (full_match/receiving_covers_entry/entry_exceeds_receiving/no_match)、comparisonResult、callbackSent、callbackResult、partialStorageMarked、entryOrder、receivingOrder" ], "type": "added", "module": "storage" }, { "version": "2026.06.18-system-03", "date": "2026-06-18", "summary": "新增 storage.receiving.getAvailableInboundQuantity 接口:按 stock_id 查询已审核收货单的可入库数量(actual_quantity - stored_quantity),排除未审核和已取消的收货单", "methods": [ "storage.receiving.getAvailableInboundQuantity" ], "notes": [ "新增 system method:storage.receiving.getAvailableInboundQuantity,按 stock_id 查询已审核收货单中各明细的可入库数量(actual_quantity - stored_quantity),仅返回尚有可入库余量的明细。", "实现文件:app/service/systemMethods/storage/receiving.js(包装层)、app/service/systems/storage/receiving.js(业务层)。", "接口无需鉴权(isNeedAuth=false),但需要登录(isNeedLogin=true)。", "入参 stock_id 为必填,对应 stock_warehouse.id;服务端从 ctx.user.store_id 获取仓库上下文。" ], "type": "added", "module": "storage" }, { "version": "2026.06.18-system-04", "date": "2026-06-18", "summary": "新增 storage.entry.bindReceivingDetails 接口和 wms_entry_receiving_binding 中间表:入库单明细可显式绑定收货明细(pending状态),提交入库时事务内完成双向扣减(stored_quantity/received_quantity),通过唯一约束和行锁防止超分和重复绑定。同时重构 completeEntry 调用链为 commitEntryWithBindings,无绑定时向后兼容。", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.completeEntry" ], "notes": [ "新增 storage.entry.bindReceivingDetails 方法:入库单明细绑定收货明细,pending 状态软绑定,每次调用清除旧 pending 绑定后创建新绑定。", "新增 wms_entry_receiving_binding 中间表(migration: 20260618150000-create-wms-entry-receiving-binding.js),用于记录入库明细与收货明细的绑定关系。", "重构 completeEntry 调用链:systemMethods 层 completeEntry 改为调用 commitEntryWithBindings,有绑定则事务内完成双向扣减(stored_quantity/received_quantity),无绑定时向后兼容仅变更入库单状态。", "通过数据库唯一约束和行锁(SELECT ... FOR UPDATE)防止超分和重复绑定。", "涉及文件: app/model/entry_receiving_binding.js, app/service/systems/storage/entry.js, app/service/systemMethods/storage/entry.js, database/migrations/20260618150000-create-wms-entry-receiving-binding.js" ], "type": "added", "module": "storage.entry" }, { "version": "2026.06.18-system-05", "date": "2026-06-18", "summary": "storage.entry.get 响应追加 pending_total/total_planned/bindings 字段,storage.receiving.getAvailableInboundQuantity 响应追加 pending_allocated_quantity 字段:前端可通过 get 查看入库明细的绑定状态,getAvailableInboundQuantity 的可用量已扣除全局 pending 绑定总量", "methods": [ "storage.entry.get", "storage.receiving.getAvailableInboundQuantity" ], "notes": [ "storage.entry.get:items 数组每项新增 pending_total(该入库明细当前 pending 绑定的总预分配数量)、total_planned(计划入库数量=count)、bindings(pending 绑定列表,每项含 id/entry_item_id/receiving_detail_id/allocated_quantity/status/receivingDetail 子对象)", "storage.receiving.getAvailableInboundQuantity:list 每项新增 pending_allocated_quantity(该收货明细在当前 stock_id 所有入库单中的 pending 绑定总量),available_quantity 计算已扣除该值" ], "type": "updated" }, { "version": "2026.06.18-system-06", "date": "2026-06-18", "summary": "bindReceivingDetails 重构为\"绑定即实收\"(received_quantity 在绑定时更新,不再等到 completeEntry),新增 unbindReceivingDetails 解绑接口(删除 pending 绑定并回退 received_quantity),commitEntryWithBindings 移除 received_quantity 更新逻辑", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails", "storage.entry.completeEntry" ], "notes": [ "storage.entry.bindReceivingDetails:改为绑定即实收,绑定成功后立即更新入库明细 received_quantity;重复调用时先回退旧绑定量再创建新绑定,避免重复累加。", "storage.entry.unbindReceivingDetails:新增解绑接口,删除该入库明细的所有 pending 绑定记录,并将 received_quantity 回退到绑定前的值;收货明细可用数量随绑定记录删除自动恢复。", "storage.entry.completeEntry:commitEntryWithBindings 中移除 received_quantity 更新逻辑(received_quantity 已在绑定时更新,completeEntry 仅完成收货单侧入库数量扣减和库存上架)。" ], "type": "updated" }, { "version": "2026.06.19-system-01", "date": "2026-06-19", "summary": "order.recheckOrder.scanOrder 响应 list[] 新增 items_weight(订单商品总重量g)和 suggested_package_material(推荐包材)字段", "methods": [ "order.recheckOrder.scanOrder" ], "notes": [ "响应 list 每项新增 items_weight (number|null):订单商品总重量(g),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量,为 null 时返回 0)。", "响应 list 每项新增 suggested_package_material (object|null):推荐包材信息,根据订单商品结构(items_hash + items_crc)匹配 wms_package_material_item_relation 历史绑定记录,按 bind_count 降序取最优匹配。若 items_hash 为空或无匹配记录则为 null。包含子字段:id、code、name、spec、type、weight、length、width、height、bind_count。", "同步更新 method description 和 list 字段 description,补充新增字段的说明。" ], "type": "updated", "module": "order.recheckOrder" }, { "version": "2026.06.21-system-01", "date": "2026-06-21", "summary": "order.bindExpressPackageMaterialByWaybill:入参 package_material_code 改为 package_material_id,类型由 string 改为 number|string", "methods": [ "order.bindExpressPackageMaterialByWaybill" ], "notes": [ "入参字段名从 package_material_code 改为 package_material_id。", "入参类型从 string 改为 number|string,与代码 normalizePackageMaterialId 的实现一致。", "同步更新该方法 description 中'包材编码'为'包材ID'。" ], "type": "updated", "module": "order" }, { "version": "2026.06.21-system-comboGoods-01", "date": "2026-06-21", "summary": "新增 comboGoods 组合商品模块 5 个接口文档:list/create/update/delete/search", "methods": [ "comboGoods.list", "comboGoods.create", "comboGoods.update", "comboGoods.delete", "comboGoods.search" ], "notes": [ "comboGoods.list:组合商品列表查询(分页),支持按 combo_code/combo_name/status/warehouse_id 筛选,返回含 simpleNotation 和 nameNotation 简记字段", "comboGoods.create:创建组合商品(含明细一次性提交),校验 combo_code 唯一性、子商品有效性和货主一致性,事务保证原子写入", "comboGoods.update:编辑组合商品(含明细替换),支持部分字段更新,传入 items 则先删旧明细再插入新明细", "comboGoods.delete:软删除组合商品(status 置为 0)", "comboGoods.search:关键字搜索组合商品,模糊匹配 combo_code 或 combo_name,仅返回启用状态记录,上限100条", "数据表:wms_combo_goods(主表)+ wms_combo_goods_item(明细表);子商品校验依赖 wms_stock_warehouse 表", "代码文件:app/service/systems/comboGoods.js(业务逻辑层)+ app/service/systemMethods/comboGoods.js(接口包装层)", "isNeedAuth:list/search 无需鉴权,create/update/delete 需要鉴权" ], "type": "added", "module": "comboGoods" }, { "version": "2026.06.21-system-comboGoods-02", "date": "2026-06-21", "summary": "comboGoods 模块新增 custom_code(自定义编码)功能:create/update 支持传入 custom_code 并校验按货主唯一,list/search 返回新增 custom_code 字段,search 搜索范围扩展至 custom_code 且优先排列匹配项", "methods": [ "comboGoods.list", "comboGoods.create", "comboGoods.update", "comboGoods.search" ], "notes": [ "新增字段 custom_code(VARCHAR(64) NULL),仅做按货主唯一性校验(排除已删除记录),非全局唯一。", "wms_combo_goods 表新增索引 uk_store_custom_code(warehouse_id, custom_code)。", "comboGoods.create:新增可选入参 custom_code,如果非空则校验同货主非删除记录中 unique;返回新增 custom_code 字段。", "comboGoods.update:新增可选入参 custom_code,如果非空则校验同货主非删除记录中 unique(排除自身 id)。", "comboGoods.list:返回每条记录新增 custom_code 字段。", "comboGoods.search:搜索条件扩大为 custom_code LIKE / combo_code LIKE / combo_name LIKE,custom_code 匹配项按 ORDER BY CASE 排在前面;返回新增 custom_code 字段。" ], "type": "updated" }, { "version": "2026.06.21-system-comboGoods-03", "date": "2026-06-21", "summary": "stock.warehouse.search 新增 mode=\"combo\" 组合商品查询模式,新增 id/custom_code 参数,补充组合商品响应结构", "methods": [ "stock.warehouse.search" ], "notes": [ "新增入参 mode(查询模式,传 \"combo\" 时搜索组合商品),id(mode=combo 时按组合商品ID精确查询),custom_code(mode=combo 时按自定义编码模糊查询)", "原有 keyword 参数在 mode=combo 时模糊匹配 combo_code / combo_name / custom_code", "mode=combo 响应结构新增 combo_code、combo_name、custom_code、items(子商品数组含 item_goods_sku_id/item_quantity)、simpleNotation(stock_id|数量格式)、nameNotation(【数量】商品名称格式)", "mode=combo 时不返回 stock 模式特有的字段(item_code/goods_code/item_name/sku_property/stock_unit/quantity/locked_quantity/brand_name/item_type/barcodes/store_stock/效期字段/storage)", "with_stock 和 is_batch 参数在 mode=combo 时不生效" ], "type": "updated" }, { "version": "2026.06.22-system-wavePickTaskList-01", "date": "2026-06-22", "summary": "order.wave.wavePickTaskList 响应新增 wave_list 数组:每个拣货任务返回关联波次列表", "methods": [ "order.wave.wavePickTaskList" ], "notes": [ "wavePickTaskList 响应 list 每项新增 wave_list 数组字段,通过批量查询 wms_wave_pick_task_wave 表获取关联波次详情。", "wave_list 每项包含:wave_id(波次ID)、wave_no(波次号)、box_no(框号)、status(波次关联状态)、bind_time(绑定时间)、pick_time(拣货完成时间)。", "无需额外入参,默认对所有拣货任务返回 wave_list;查询为空时返回空数组 []。", "同步更新 methods/system.json 响应文档。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.22-system-order-export-mode-01", "date": "2026-06-22", "summary": "order.export 新增 export_mode 参数:支持 waybill(默认,按运单展开)与 item(按商品明细展开)两种导出模式", "methods": [ "order.export" ], "notes": [ "新增入参 export_mode/exportMode,枚举值:waybill(默认)— 按运单号展开,每运单一组,items_detail 列汇总商品;item — 按商品明细展开,每商品一行,运单信息汇总填充。", "方法层(OrderIndexService.export)新增 export_mode/exportMode 解构并透传到 systems.orderExport.exportOrders。", "同步更新 methods/system.json 文档:description 补充 export_mode 说明,params 新增 export_mode/exportMode 条目。", "order.export 导出的列新增:业务类型、运单接口、包材ID、包材编码、包材名称。" ], "type": "updated", "module": "order.index" }, { "version": "2026.06.22-system-directInbound-01", "date": "2026-06-22", "summary": "新增 storage.directInbound 导入/PDA直接入库模块:getItems(获取入库信息)、addItem(增量添加商品)、commit(提交完成入库并回传)", "methods": [ "storage.directInbound.getItems", "storage.directInbound.addItem", "storage.directInbound.commit" ], "notes": [ "新增 storage.directInbound 模块,用于非收货单途径的导入/PDA 直接入库场景。", "storage.directInbound.getItems:根据入库单号获取入库明细及已有的导入/PDA 入库记录,返回每项的可入库余量。", "storage.directInbound.addItem:按 stock_id 增量添加导入/PDA 入库记录,累加超过该 stock_id 在入库单中的计划总量时拒绝。支持 import(导入)和 pda(PDA)两种方式。", "storage.directInbound.commit:提交确认完成入库,按实收数量写入 wms_storage 库存和 wms_storage_transaction 流水,同 stock_id 多条明细只写一次库存,更新入库单状态为 COMPLETED 并同步 sync_status=SUCCESS,异步触发奇门/API 回传(按实收数量回传)。不足量提交时未入库商品跳过。", "新增数据表 wms_inbound_direct_log(migration: 20260622100000-create-wms-inbound-direct-log.js):记录非收货单途径入库操作,含 warehouse_id、stock_id、quantity、inbound_type(import/pda)、entry_order_id、operator 等字段。模型文件:app/model/inbound_direct_log.js。", "新增操作日志:addItem 记录 DIRECT_INBOUND_ADD(异步),commit 记录 DIRECT_INBOUND_COMMIT(事务内)。commit 响应返回 order_status=COMPLETED 和 sync_status=SUCCESS。", "涉及文件:app/service/systems/inbound_direct_log.js(业务层)、app/service/systemMethods/storage/direct_inbound.js(包装层)、app/model/inbound_direct_log.js、database/migrations/20260622100000-create-wms-inbound-direct-log.js、methods/system.json(新增导入/PDA入库模块)。", "E2E 测试:test/e2e_direct_inbound.test.js(53项断言全覆盖)。" ], "type": "added", "module": "storage.directInbound" }, { "version": "2026.06.22-system-directInbound-02", "date": "2026-06-22", "summary": "storage.directInbound.addItem 新增批量模式(items 数组),getItems 响应 summary 新增 total_import/total_pda 分类型汇总", "methods": [ "storage.directInbound.addItem", "storage.directInbound.getItems" ], "notes": [ "addItem 新增批量模式:支持传入 items 数组一次添加多条商品,每项含 stock_id/quantity/inbound_type/remark。单条模式(stock_id/quantity/inbound_type 顶层字段)保持向后兼容。批量模式下所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。", "addItem 批量模式响应结构:{ count, total_quantity, items: [...] },items 每项含 id/stock_id/quantity/inbound_type/plan_quantity/existing_before/existing_after/remaining。", "getItems 响应 summary 新增 total_import(导入入库总数)和 total_pda(PDA入库总数)字段。", "同步更新 methods/system.json 文档。" ], "type": "updated", "module": "storage.directInbound" }, { "version": "2026.06.22-system-directInbound-03", "date": "2026-06-22", "summary": "storage.directInbound 新增 space_id 库位支持:addItem 支持传入 space_id(单条和批量),commit 从入库记录取 space_id 写入 wms_storage 替代硬编码 1", "methods": [ "storage.directInbound.addItem", "storage.directInbound.commit", "storage.directInbound.getItems" ], "notes": [ "addItem 新增可选入参 space_id(单条模式顶层字段 / 批量模式 items[].space_id),指定存放库位ID,关联 wms_location_space.id。", "wms_inbound_direct_log 表新增 space_id 字段(migration: 20260622110000-add-space-id-to-wms-inbound-direct-log.js)。", "commit 从入库记录中取第一个非空 space_id 写入 wms_storage,无记录时兜底使用库位 1。", "getItems 响应中 direct_logs 每条记录包含 space_id 字段。", "同步更新 methods/system.json 文档及模型文件。" ], "type": "updated", "module": "storage.directInbound" }, { "version": "2026.06.23-system-01", "date": "2026-06-23", "summary": "入库单(wms_entry_order)新增 CREATED 状态:order_status ENUM 从 CREATING/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 扩展为 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED;默认值从 PENDING 变更为 CREATED;validTransitions 增加 CREATED 节点(CREATED→PENDING/CANCELLED,CREATING→CREATED/CANCELLED)", "methods": [ "storage.entry.list", "storage.entry.get", "storage.entry.cancel", "storage.entry.completeEntry", "storage.entry.bindReceivingDetails" ], "notes": [ "Model 层:app/model/entry_order.js order_status ENUM 新增 CREATED,默认值从 PENDING 变更为 CREATED", "Service 层:app/service/systems/entry_order.js addOrder 创建后状态从 CREATING→CREATED,validTransitions 增加 CREATED 节点", "Service 层:app/service/systems/storage/entry.js createEntry 默认状态 PENDING→CREATED", "Service 层:app/service/systems/storage/inventory.js 快捷入库默认 CREATED", "文档同步:storage.entry.list where.order_status 枚举补充 CREATED;storage.entry.get description 补充 order_status 枚举含 CREATED;storage.entry.cancel 补充 CREATED 可作废说明;storage.entry.completeEntry/bindReceivingDetails 补充可操作状态含 CREATED" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.23-system-02", "date": "2026-06-23", "summary": "入库单 CREATED 状态限制:CREATED 状态不允许绑定货物和完成入库,仅 PENDING/CONFIRMED/PARTIAL_RECEIVED 状态可操作", "methods": [ "storage.entry.cancel", "storage.entry.completeEntry", "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails" ], "notes": [ "completeEntry / bindReceivingDetails / unbindReceivingDetails / commitEntryWithBindings 的可操作状态从原来的白名单(包含 CREATED)改为 PENDING / CONFIRMED / PARTIAL_RECEIVED,排除 CREATED。", "CREATED 状态仅允许确认入库(→PENDING)或作废(→CANCELLED)。", "storage.entry.cancel 补充明确 COMPLETED 状态不可作废,CREATED 可作废。", "同步更新对应 method 的 description、errors 描述。" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.23-system-03", "date": "2026-06-23", "summary": "storage.entry.cancel:CONFIRMED(已确认)状态不再允许作废,仅 CREATED 和 PENDING 可作废", "methods": [ "storage.entry.cancel" ], "notes": [ "canCancel() 白名单移除 CONFIRMED,仅保留 CREATED 和 PENDING", "validTransitions 中 CONFIRMED 不再可转为 CANCELLED", "cancel() 方法新增 CONFIRMED 状态拦截,返回 400:已确认入库单不允许作废,请先完成收货", "PARTIAL_RECEIVED 仍可作废,COMPLETED 不允许作废(行为不变)", "更新 description 明确各状态可作废规则,errors 中补充 CONFIRMED 不可作废的说明" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.23-system-04", "date": "2026-06-23", "summary": "入库单状态从 7 个简化为 5 个:移除 CONFIRMED 和 PARTIAL_RECEIVED,最终状态为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED;同步更新 storage.entry 所有 method 的状态枚举和错误信息描述", "methods": [ "storage.entry.list", "storage.entry.get", "storage.entry.cancel", "storage.entry.completeEntry", "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails" ], "notes": [ "wms_entry_order.order_status ENUM 从 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 简化为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED", "storage.entry.list: where.order_status 描述和 where 参数描述中的状态枚举同步更新", "storage.entry.get: entryOrder.order_status 描述同步更新", "storage.entry.cancel: 移除 PARTIAL_RECEIVED 可作废和 CONFIRMED 不可作废的描述,仅保留 CREATED 和 PENDING 可作废,COMPLETED 不可作废", "storage.entry.completeEntry: 可完成状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", "storage.entry.bindReceivingDetails: 可操作状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", "storage.entry.unbindReceivingDetails: 可操作状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", "cancel() 取消 CONFIRMED 状态拦截(状态已不存在),COMPLETED 拦截保持不变" ], "type": "updated" }, { "version": "2026.06.23-system-05", "date": "2026-06-23", "summary": "入库单状态语义调整:CREATED=已创建待审核,PENDING=已审核;同步更新 storage.entry 所有 method 的 description 中状态说明", "methods": [ "storage.entry.list", "storage.entry.get", "storage.entry.cancel", "storage.entry.completeEntry", "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails" ], "notes": [ "CREATED 含义从\"已创建\"改为\"已创建待审核\"(需审核后才能绑定和完成入库)", "PENDING 含义从\"待收货/收货中\"改为\"已审核\"(审核通过,可绑定和完成入库)", "CREATED→PENDING 步骤语义:绑定审核", "addOrder() 新增可选参数 autoReview(boolean,默认 false),false 创建后状态 CREATED(需审核),true 创建后状态 PENDING(自动审核通过)", "快捷入库 quickPutaway 内部流程改为调用 addOrder({autoReview:true}) → bindReceivingDetails → commitEntryWithBindings,不再直接写库存,对外返回格式不变", "storage.entry.list / storage.entry.get description 中补充 CREATED/PENDING 语义说明", "storage.entry.cancel description 中补充可作废状态说明", "storage.entry.completeEntry description 中补充可完成状态说明", "storage.entry.bindReceivingDetails / storage.entry.unbindReceivingDetails description 中补充可绑定/解绑状态说明" ], "type": "updated" }, { "version": "2026.06.23-system-06", "date": "2026-06-23", "summary": "storage.inventory.quickPutaway description 更新:补充内部已改为走 addOrder→bind→commit 链路,不再直接写库存", "methods": [ "storage.inventory.quickPutaway" ], "notes": [ "快捷入库 quickPutaway 内部流程改为调用 addOrder({autoReview:true}) → bindReceivingDetails → commitEntryWithBindings,不再直接写库存,外部返回格式不变", "description 中补充内部调用链路说明" ], "type": "updated" }, { "version": "2026.06.23-system-07", "date": "2026-06-23", "summary": "storage.entry 大范围清理:删除 bindReceivingDetails/unbindReceivingDetails(明细级绑定已弃用),更新 completeEntry 为纯状态变更(不再做库存写入/异步匹配)", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails", "storage.entry.completeEntry" ], "notes": [ "storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。库存写入统一由 storage.inventory.matchPutaway 完成。", "storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。", "storage.entry.completeEntry:改为纯状态变更(PENDING → COMPLETED),不再做库存写入和异步匹配回调。库存写入统一由 storage.inventory.matchPutaway 完成。" ], "type": "updated" }, { "version": "2026.06.23-system-08", "date": "2026-06-23", "summary": "storage.inventory 清理:删除 quickPutaway(快捷入库已下线,统一由 matchPutaway 完成匹配入库)", "methods": [ "storage.inventory.quickPutaway" ], "notes": [ "storage.inventory.quickPutaway:已从代码中删除,快捷入库功能下线。请使用 storage.inventory.matchPutaway 替代。" ], "type": "removed" }, { "version": "2026.06.23-system-09", "date": "2026-06-23", "summary": "入库流程弃用清理:bindReceivingDetails/unbindReceivingDetails 标记为已删除并补充弃用原因,completeEntry 明确不涉及库存写入", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails", "storage.entry.completeEntry" ], "notes": [ "storage.entry.bindReceivingDetails 与 storage.entry.unbindReceivingDetails 已从代码中移除,入库单与收货单关系改为 wms_entry_order_receiving 主表级关联,不再需要逐明细绑定/解绑。", "wms_entry_receiving_binding 表不再写入新数据。", "storage.entry.completeEntry 仅做状态变更(PENDING→COMPLETED),库存写入统一由 storage.inventory.matchPutaway 完成。", "commitEntryWithBindings(内部方法)不再使用,库存写入统一走 matchPutaway 链路。" ], "type": "updated" }, { "version": "2026.06.23-system-10", "date": "2026-06-23", "summary": "quickPutaway 弃用说明完善:明确替代方案为 matchPutaway;matchPutaway 标明为目前唯一库存写入入库链路", "methods": [ "storage.inventory.quickPutaway", "storage.inventory.matchPutaway" ], "notes": [ "storage.inventory.quickPutaway 已从代码中移除,替代方案为 storage.inventory.matchPutaway(支持多收货单+多入库单批量匹配入库)。", "storage.inventory.matchPutaway 是目前唯一的库存写入入库链路,入库单状态变更由 storage.entry.completeEntry 单独处理。", "本次为文档补充说明,不涉及代码变更。" ], "type": "updated" }, { "version": "2026.06.23-system-11", "date": "2026-06-23", "summary": "删除 storage.receiving.getAvailableInboundQuantity:该方法依赖已弃用的 wms_entry_receiving_binding 明细绑定表,已从代码中移除", "methods": [ "storage.receiving.getAvailableInboundQuantity" ], "notes": [ "该方法原用于按 stock_id 查询已审核收货单中各明细的可入库数量(actual_quantity - stored_quantity - pending_allocated_quantity)。", "由于 wms_entry_receiving_binding 明细绑定表已弃用,入库单与收货单的关联改为通过 wms_entry_order_receiving 主表级关联,该查询方法不再适用。", "替代方案:使用 storage.entry.get 查询入库单详情,通过顶层 receivingBindings 获取关联的收货单信息。" ], "type": "removed" }, { "version": "2026.06.23-system-12", "date": "2026-06-23", "summary": "storage.entry.get 响应结构变更:不再返回 items[].bindings(明细级绑定),改为返回顶层 receivingBindings(主表级关联收货单信息)", "methods": [ "storage.entry.get" ], "notes": [ "移除 items[].bindings(明细级绑定,原基于 wms_entry_receiving_binding 表),该绑定表已弃用。", "新增顶层 receivingBindings(wms_entry_order_receiving 主表级关联),每项含 id/receiving_id/receiving(含 id/receiving_number/status/storage_status/created_at)。", "items 中保留 external_item_code/external_item_id/warehouse_item_code/warehouse_item_name/warehouse_item_spec 等扁平化字段。", "响应结构变更与 storage.directInbound.getItems 的返回结构对齐,后者同样使用顶层 receivingBindings。" ], "type": "modified" }, { "version": "2026.06.23-system-13", "date": "2026-06-23", "summary": "新增 storage.entry.* 下 4 个 DirectInbound 方法:getDirectInboundItems、addItem、commit、removeItem,原 storage.directInbound.* 方法保留向后兼容并标记 deprecated", "methods": [ "storage.entry.getDirectInboundItems", "storage.entry.addItem", "storage.entry.commit", "storage.entry.removeItem" ], "notes": [ "storage.entry.getDirectInboundItems:获取入库单的导入/PDA 入库信息,参数与响应格式同原 storage.directInbound.getItems", "storage.entry.addItem:按商品增量添加导入/PDA 入库记录(支持单条和批量),参数与响应格式同原 storage.directInbound.addItem", "storage.entry.commit:提交确认完成导入/PDA 入库,按实收数量写入库存并异步回传奇门/API,参数与响应格式同原 storage.directInbound.commit", "storage.entry.removeItem:移除一条导入/PDA 入库记录,参数与响应格式同原 storage.directInbound.removeItem", "底层 inbound_direct_log.js 实现不变,仅入口从 storage.directInbound 模块迁入 storage.entry 模块" ], "type": "added" }, { "version": "2026.06.23-system-14", "date": "2026-06-23", "summary": "storage.directInbound.* 下 4 个方法标记 deprecated,指向 storage.entry.* 下对应新方法", "methods": [ "storage.directInbound.getItems", "storage.directInbound.addItem", "storage.directInbound.commit", "storage.directInbound.removeItem" ], "notes": [ "storage.directInbound.getItems → 替代方法 storage.entry.getDirectInboundItems", "storage.directInbound.addItem → 替代方法 storage.entry.addItem", "storage.directInbound.commit → 替代方法 storage.entry.commit", "storage.directInbound.removeItem → 替代方法 storage.entry.removeItem", "旧方法保留向后兼容,参数与响应格式不变,仅入口模块变更" ], "type": "deprecated" }, { "version": "2026.06.23-system-15", "date": "2026-06-23", "summary": "storage.inventory.matchPutaway 标记 deprecated,替代方案为 storage.entry.commit", "methods": [ "storage.inventory.matchPutaway" ], "notes": [ "storage.inventory.matchPutaway 已弃用,请迁移至 storage.entry.commit", "commit 提供导入/PDA 入库完成确认功能,按实收数量写入库存并异步回传" ], "type": "deprecated" }, { "version": "2026.06.23-system-16", "date": "2026-06-23", "summary": "清理已弃用 method 条目:从 system.json 删除 storage.entry.bindReceivingDetails、storage.entry.unbindReceivingDetails、storage.inventory.matchPutaway 三个已从代码中移除的 method 文档条目", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails", "storage.inventory.matchPutaway" ], "notes": [ "storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。入库单与收货单关系改为 wms_entry_order_receiving 主表级关联。", "storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。", "storage.inventory.matchPutaway:已从代码中删除,匹配入库功能下线。替代方案为 storage.entry.commit。", "storage.inventory.quickPutaway:之前已标记 [已删除],本次确认条目保留(与 matchPutaway 同一 group,保留作为历史参考)。", "storage.entry.create / addDetail / deleteDetail / detailChange:systems 层方法已删除,但从未在 system.json 中暴露为 API method,无需文档变更。" ], "type": "removed" }, { "version": "2026.06.23-system-17", "date": "2026-06-23", "summary": "storage.entry.get 响应新增仓库库存、条码、入库进度字段", "methods": [ "storage.entry.get" ], "notes": [ "items 每项新增 warehouse_quantity(仓库库存总量)、warehouse_locked_quantity(锁定数量)、warehouse_is_batch_mgmt(是否批次管理)、warehouse_is_shelf_life_mgmt(是否效期管理)、warehouse_image_url(商品图片URL)、warehouse_is_images(是否有图片)", "items 每项新增 barcodes(条码列表,每项含 id/barcode/sku_property)", "items 每项新增 direct_inbound_quantity(导入/PDA已入库数量)、remaining_quantity(剩余可入库数量)", "同步更新 response 字段定义,将原有概要描述展开为逐字段说明", "仅文档同步,不改业务代码" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.24-system-01", "date": "2026-06-24", "summary": "新增批量绑定入库单明细与收货单明细接口 storage.entry.bindReceivingDetails,支持明细级数量分配与部分成功", "methods": [ "storage.entry.bindReceivingDetails" ], "notes": [ "新增 storage.entry.bindReceivingDetails:批量绑定入库单明细与收货单明细,支持明细级数量分配与部分成功", "storage.entry.get 追加 available_receiving_details 字段加载可匹配的收货单明细" ], "type": "addition" }, { "version": "2026.06.24-system-02", "date": "2026-06-24", "summary": "storage.entry.bindReceivingDetails:response.failed 字段从简单 reason 描述升级为结构化错误返回(含 error_code、message、detail);同步更新 400 错误说明", "methods": [ "storage.entry.bindReceivingDetails" ], "notes": [ "response.failed 新增 items 定义,每项含 entry_item_id、receiving_detail_id、allocated_quantity、error_code、message、detail", "error_code 枚举:ENTRY_ITEM_NOT_FOUND、STOCK_NOT_FOUND、RECEIVING_DETAIL_MISMATCH、RECEIVING_DETAIL_NOT_FOUND、INSUFFICIENT_AVAILABLE_QUANTITY、ENTRY_ORDER_STATUS_INVALID", "400 错误说明更新:入库单状态不允许绑定时,所有 bindings 均返回 failed 且 error_code 为 ENTRY_ORDER_STATUS_INVALID" ], "type": "updated" }, { "version": "2026.06.24-system-03", "date": "2026-06-24", "summary": "新增 storage.entry.quickInbound 快捷直入/虚拟入库接口", "methods": [ "storage.entry.quickInbound" ], "notes": [ "新增 quickInbound 方法:入库单所有商品按明细数量一键直入虚拟库位(space_id=2),跳过收货/质检流程", "支持状态:CREATED、PENDING 状态的入库单可执行", "拒绝状态:CANCELLED(已作废)、COMPLETED(已完成)", "事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、变更入库单状态为 COMPLETED", "事务外异步回传奇门/API" ], "type": "addition" }, { "version": "2026.06.24-system-04", "date": "2026-06-24", "summary": "收窄 storage.entry.quickInbound 状态约束:仅允许 CREATED 状态执行快捷直入", "methods": [ "storage.entry.quickInbound" ], "notes": [ "收窄状态约束:仅允许 CREATED 状态执行快捷直入,PENDING 状态不再允许" ], "type": "updated" }, { "version": "2026.06.24-system-05", "date": "2026-06-24", "summary": "修正 storage.entry.quickInbound errors[4] message 以匹配代码实现:改为动态状态描述", "methods": [ "storage.entry.quickInbound" ], "notes": [ "errors[4].message 从「入库单状态不允许快捷直入(仅支持CREATED状态)」改为「入库单状态不允许快捷直入,当前状态:非CREATED(如PENDING等)」,反映代码中 `${entryOrder.order_status}` 动态模板特性" ], "type": "updated" }, { "version": "2026.06.24-system-06", "date": "2026-06-24", "summary": "新增入库单与收货单商品对照预览接口", "methods": [ "storage.entry.receivingCompare" ], "notes": [ "新增 storage.entry.receivingCompare 方法:给定入库单ID和收货单ID,返回入库商品与收货商品的逐行对照视图。", "comparison 列表中每项含 match_status(matched/entry_only),以及入库侧和收货侧的商品与数量信息。", "receiving_only 列表包含仅存在于收货单中的商品明细。", "summary 提供 total_entry_items、matched_items、entry_only_items、receiving_only_items 汇总统计。", "纯只读接口,不产生任何数据写入或状态变更。" ], "type": "addition" }, { "version": "2026.06.24-system-07", "date": "2026-06-24", "summary": "setting.warehouse 模块新增 7 个发件人信息字段到 subject_config", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "在 getSettings 的 response 中新增 subject_config.sender_name(发件人姓名)、sender_tel(发件人电话)、province_name(省份)、city_name(城市)、district_name(区/县)、town_name(镇/街道)、address(详细地址)共 7 个字段,均为可选字符串,默认空。", "在 saveSettings 的 params 中新增对应的 7 个入参字段,source 为 body.subject_config,均为可选字符串,默认空,并标注 maxLength。", "字段 key 与 store_warehouse.policy_config 中发件人字段命名完全一致,统一仓库级发件人默认值配置。", "getFieldMeta 接口无需修改文档——其返回的字段元信息由 WAREHOUSE_SETTING_FIELDS 定义在运行时自动生成,新增字段会随代码自动纳入返回列表。" ], "type": "updated", "module": "setting.warehouse" }, { "version": "2026.06.25-system-01", "date": "2026-06-25", "summary": "新增 storage.entry.bindReceiving 接口:将收货单绑定到入库单(主表级关联,不做明细数量分配)", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "新增入库单与收货单的主表绑定接口,与已有的 storage.entry.bindReceivingDetails(明细级绑定)区分:bindReceiving 仅建立 wms_entry_order_receiving 主表关联,不做明细数量分配。", "入库单需为 CREATED 或 PENDING 状态;收货单需存在、同仓库且未取消。", "支持部分成功模式:逐条校验收货单,校验通过的建立绑定,不通过的返回 error_code 和 message。", "响应包含 success(成功列表)、failed(失败列表)、success_count、failed_count。" ], "type": "addition" }, { "version": "2026.06.25-system-02", "date": "2026-06-25", "summary": "storage.entry.bindReceiving:新增 OWNER_MISMATCH 错误码,用于收货单与入库单货主不一致校验", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "在 storage.entry.bindReceiving 的 errors 数组中新增 OWNER_MISMATCH(收货单与入库单货主不一致)错误码。", "同步更新 response.failed.error_code 的枚举描述,补充 OWNER_MISMATCH。" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.25-system-03", "date": "2026-06-25", "summary": "storage.entry.bindReceiving:新增收货单未审核错误码 RECEIVING_NOT_REVIEWED", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "在 errors 数组中新增错误码 RECEIVING_NOT_REVIEWED(收货单未审核),用于标识绑定前收货单尚未完成审核的场景。", "同步更新 response.failed.items.properties.error_code.description,在可能值列表中补充 RECEIVING_NOT_REVIEWED。" ], "type": "updated" }, { "version": "2026.06.25-system-04", "date": "2026-06-25", "summary": "storage.entry.list 响应新增 receivingBindings 和 hasReceiving 字段,where 新增 hasReceiving 虚拟筛选条件", "methods": [ "storage.entry.list" ], "notes": [ "响应 list 数组每项新增 receivingBindings(收货单绑定列表,主表级关联)和 hasReceiving(是否存在收货单绑定,boolean)字段。", "入参 where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单,内部通过 wms_entry_order_receiving 表查询实现。", "同步更新 description 以说明 hasReceiving 虚拟筛选的使用方式。" ], "type": "updated" }, { "version": "2026.06.26-system-01", "date": "2026-06-26", "summary": "storage.entry.receivingCompare 支持多收货单对照预览", "methods": [ "storage.entry.receivingCompare" ], "notes": [ "支持多个收货单ID对照预览(新增 receiving_ids 数组入参,优先于 receiving_id 使用)", "入参 receiving_id 从 required 改为 optional,与 receiving_ids 二选一", "出参结构调整为 comparisons[] 数组(多收货单),新增 errors[] 和 total_summary", "向后兼容原 receiving_id 单值传参(底层自动转为单元素数组)", "新增 400 错误码:receiving_ids 或 receiving_id 必填", "移除 404 错误码:收货单不存在(已改为在 comparisons[]/errors[] 中以 status=error 形式返回)" ], "type": "enhancement" }, { "version": "2026.06.26-system-02", "date": "2026-06-26", "summary": "storage.receiving.getReceivingList 新增 filterDepleted 可选参数;storage.entry.receivingCompare 返回值 receiving_only 字段新增 receiving_allocated 和 receiving_available 说明", "methods": [ "storage.receiving.getReceivingList", "storage.entry.receivingCompare" ], "notes": [ "storage.receiving.getReceivingList:params 新增 filterDepleted(boolean, 默认 false),用于过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)。", "storage.entry.receivingCompare:response 中 receiving_only 字段的 description 补充 receiving_allocated(已分配数量)和 receiving_available(可再用量)两个子字段说明。" ], "type": "updated" }, { "version": "2026.06.26-system-03", "date": "2026-06-26", "summary": "storage.receiving.getReceivingList:新增可选参数 entry_order_id,按入库单商品交集过滤收货单列表", "methods": [ "storage.receiving.getReceivingList" ], "notes": [ "新增可选参数 entry_order_id(number),传入入库单 ID 后只返回至少有一条明细的 system_product_id 在入库单明细中存在的收货单。", "与现有 filterDepleted 参数可组合使用,二者取交集。", "不传则不过滤,保持原有行为不变。" ], "type": "updated" }, { "version": "2026.06.27-system-01", "date": "2026-06-27", "summary": "新增 storage.entry.reviewEntry 接口:审核入库单(CREATED→PENDING),需绑定收货单", "methods": [ "storage.entry.reviewEntry" ], "notes": [ "新增入库单审核接口,支持 CREATED→PENDING 状态流转。", "审核前置条件:入库单必须已绑定收货单(EntryOrderReceiving 存在关联记录)。", "审核通过后写入操作日志(ENTRY_ORDER_REVIEW)。" ], "type": "added" }, { "version": "2026.06.29-system-01", "date": "2026-06-29", "summary": "storage.inventory.quickPutaway 重新实现:收货单快捷转入库单", "methods": [ "storage.inventory.quickPutaway" ], "notes": [ "此前已从代码中删除(2026.06.23-system-08),现由 wms-dev-agent 重新实现。", "核心流程:参数校验 → 加载收货单及明细 → 检查货主配置 policy_config.allow_receiving_quick_putaway → 按 stock_id(system_product_id)分组合并数量 → 创建入库单 SCRK(自动审批到 PENDING)→ 写入 wms_entry_order_receiving 主表级绑定 → 更新收货单 storage_status 为 partial → 更新收货单明细 storage_status/stored_quantity → 提交事务。", "前置条件:收货单状态为 completed 且 is_review=true(已审核),货主仓库签约配置 allow_receiving_quick_putaway=1。", "与旧实现的区别:不涉及 wms_entry_receiving_binding 明细级绑定,使用 wms_entry_order_receiving 主表级关联;直接创建入库单并写入绑定,不再走 matchPutaway 匹配链路。", "返回:entry_order_id、entry_order_code(SCRK 格式)、order_status(PENDING)、receiving_id、total_lines、total_quantity。" ], "type": "addition" }, { "version": "2026.06.29-system-02", "date": "2026-06-29", "summary": "storage.entry.list:quickWhere 搜索范围扩展,新增收货单 ID(receiving_id)支持 PDA 扫描托盘唛头搜索绑定的入库单", "methods": [ "storage.entry.list" ], "notes": [ "quickWhere 搜索字段新增 receiving_id(收货单 ID / 托盘唛头),通过 wms_entry_order_receiving 绑定表关联搜索。", "同步更新 description 和 where 参数的 description,明确 quickWhere 完整搜索字段列表:entry_order_code、purchase_order_code、supplier_name、store_name、warehouse_name、receiving_id。" ], "type": "updated", "module": "storage" }, { "version": "2026.06.29-system-03", "date": "2026-06-29", "summary": "新增 storage.receiving.scanDetail 接口:PDA 上架扫码定位收货明细", "methods": [ "storage.receiving.scanDetail" ], "notes": [ "新增 storage.receiving.scanDetail(PDA专用):通过 entry_order_id + barcode 扫码快速定位收货明细。", "搜索逻辑:纯数字 barcode 优先按明细 ID 精确匹配(托盘唛头),未命中则模糊匹配商品条码;非纯数字仅模糊匹配商品条码。", "入参:entry_order_id(必填 number)、barcode(必填 string)。", "出参:detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status。", "错误码:入库单不存在或无权访问、该入库单尚未关联收货单、未找到匹配的收货明细。" ], "type": "added" }, { "version": "2026.06.29-system-04", "date": "2026-06-29", "summary": "storage.receiving.scanDetail 响应结构从单条改为列表:返回 { list, total } 支持同一条码匹配多条明细", "methods": [ "storage.receiving.scanDetail" ], "notes": [ "响应结构变更:原返回 data.detail_id/data.receiving_id 等单条字段,现改为顶层 list 数组 + total 计数。", "同一条码可能匹配到多条收货明细(不同收货单的同一商品),以列表形式返回所有匹配结果。", "list 中每条明细包含 detail_id/receiving_id/barcode/product_name/actual_quantity/receiving_status。", "补充错误码:用户未绑定仓库、入库单ID/条码为空、未找到可用的收货明细、500服务器错误。", "PDA专用接口,description 更新说明匹配逻辑。" ], "type": "updated", "module": "storage.receiving" }, { "version": "2026.06.30-system-01", "date": "2026-06-30", "summary": "新增 storage.entry.containerList:PDA 上架时拉取入库单绑定收货单中指定商品的可用容器列表", "methods": [ "storage.entry.containerList" ], "notes": [ "新增接口 storage.entry.containerList,用于 PDA 上架场景拉取入库单已绑定收货单中指定 stock_id 的可用收货明细(容器)列表。", "入参:entry_order_id(入库单ID,必填)、stock_id(商品 stock_id,必填)。", "出参:data.list 返回可用明细列表,每项含 detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status;data.total 为总数。", "已绑定占用的收货明细(wms_entry_receiving_binding 中已有记录且未软删除)会被排除。", "PDA 专用接口,无需额外鉴权(isNeedAuth=false)。" ], "type": "added" }, { "version": "2026.06.30-system-02", "date": "2026-06-30", "summary": "storage.entry.addItem 入参变更:entry_order_code → entry_order_id(number);quantity 改为可选(传入 receiving_detail_id 时自动计算);新增 receiving_detail_id/allocated_quantity 参数支持 PDA 上架收货明细绑定模式;space_id 绑定模式下必填", "methods": [ "storage.entry.addItem" ], "notes": [ "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.addItem 实现对齐", "quantity 改为可选:传入 receiving_detail_id 时自动从收货明细计算可用数量(actual_quantity - 已绑定数量)", "新增 receiving_detail_id 参数:PDA 上架绑定收货明细时传入,触发预占绑定(wms_entry_receiving_binding status=pending)", "新增 allocated_quantity 参数:预分配数量,默认等于 quantity", "space_id 在绑定模式下必填;非绑定模式可选(commit 时兜底为 1)", "PENDING 状态入库单必须传 receiving_detail_id 且已绑定收货单方可操作", "CREATED + 已绑定收货单的入库单需先审核(reviewEntry)后才能上架", "批量模式 items 数组同步支持 receiving_detail_id/allocated_quantity 字段", "补充完整错误码列表:超量、可用数量不足、状态校验等" ], "type": "updated" }, { "version": "2026.06.30-system-03", "date": "2026-06-30", "summary": "storage.entry.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐", "methods": [ "storage.entry.commit" ], "notes": [ "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐", "补充 description 说明先同步后写库两段式流程:① 奇门/API 回传 → ② onSuccess 内事务写库存", "补充 commit 后 EntryReceivingBinding 状态从 pending 更新为 committed 的说明" ], "type": "updated" }, { "version": "2026.06.30-system-04", "date": "2026-06-30", "summary": "storage.directInbound.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐", "methods": [ "storage.directInbound.commit" ], "notes": [ "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐", "该方法已标记 deprecated,推荐使用 storage.entry.commit" ], "type": "updated" }, { "version": "2026.06.30-system-05", "date": "2026-06-30", "summary": "storage.entry.getDirectInboundItems 响应结构重构:entryOrder 精简字段,items[].count→planned、direct_inbound_quantity→completed,items[].bindings 新增,移除 direct_logs/summary 等冗余字段", "methods": [ "storage.entry.getDirectInboundItems" ], "notes": [ "entryOrder 精简为 id / entry_order_code / order_status / store_remask 四个字段", "items[].count → planned(计划数量),items[].direct_inbound_quantity → completed(已完成数量)", "items[].bindings 新增,结构为 { detail_id, binding_id, allocated_quantity, space_id, space_name }", "items[].stock 新增,返回 getStockDetails 缓存的商品详情(item_code、item_name、barcodes 等)", "移除 direct_logs(现有响应中已不存在该顶层字段)", "移除 summary(现有响应中已不存在该字段)", "移除 items[].received_quantity、items[].remaining_quantity、items[].pending_binding_total 等旧字段", "新增 receivingBindings 字段说明:入库单层级收货单绑定关系" ], "type": "updated" }, { "version": "2026.06.30-system-06", "date": "2026-06-30", "summary": "storage.directInbound.getItems 响应结构重构:entryOrder 精简字段,items[].count→planned、direct_inbound_quantity→completed,items[].bindings 新增,移除 direct_logs/summary 等冗余字段", "methods": [ "storage.directInbound.getItems" ], "notes": [ "响应结构与 storage.entry.getDirectInboundItems 对齐(两者共用同一个底层实现 inboundDirectLog.getItems)", "entryOrder 精简为 id / entry_order_code / order_status / store_remask", "items[].count → planned,items[].direct_inbound_quantity → completed", "items[].bindings 新增 { detail_id, binding_id, allocated_quantity, space_id, space_name }", "items[].stock 新增", "移除 direct_logs、summary、items[].received_quantity、items[].remaining_quantity 等旧字段", "新增 receivingBindings 字段" ], "type": "updated" }, { "version": "2026.06.30-system-07", "date": "2026-06-30", "summary": "storage.entry.containerList 响应结构补充 stock 字段:返回商品详情(item_code、item_name、barcodes 等)", "methods": [ "storage.entry.containerList" ], "notes": [ "响应 list[].stock 字段补充为必返回:通过 getStockDetails 批量获取商品详情缓存", "stock 对象包含 item_code、item_name、sku_property、barcodes 等字段" ], "type": "updated" }, { "version": "2026.06.30-system-08", "date": "2026-06-30", "summary": "storage.receiving.scanDetail 响应结构补充 stock 字段:返回商品详情(item_code、item_name、barcodes 等)", "methods": [ "storage.receiving.scanDetail" ], "notes": [ "响应 list[].stock 字段补充为必返回:通过 getStockDetails 批量获取商品详情缓存", "stock 对象包含 item_code、item_name、sku_property、barcodes 等字段", "完善 error 列表:补充 未找到可用的收货明细、未找到匹配的收货明细、入库单ID不能为空、扫描条码不能为空 等错误" ], "type": "updated" }, { "version": "2026.06.30-system-09", "date": "2026-06-30", "summary": "订单列表 list 响应新增 store_remark(货主备注)字段", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list" ], "notes": [ "数据库字段 store_remask,返回给前端的字段名为 store_remark。", "服务层从 wms_store_warehouse.store_remask 按 store_id+warehouse_id 聚合批量填充。", "货主备注值可能为空字符串(当货主未设置备注时)。", "该字段对订单列表的所有 method 均适用(current/dispatch/outsourced/history 模型均返回)。" ], "type": "updated" }, { "version": "2026.07.02-system-02", "date": "2026-07-02", "summary": "新增 quick.waybill.toOrder 接口:根据运单号快速查询订单ID", "methods": [ "quick.waybill.toOrder" ], "notes": [ "新增 quick 模块组(快捷查询)", "查询 wms_order_express 表中 status=1 的有效记录", "无需登录和鉴权(免登录/免鉴权)" ], "type": "added" }, { "version": "2026.07.02-system-01", "date": "2026-07-02", "summary": "修正 quick.waybill.toOrder 的 isNeedLogin 为 true,与代码实现保持一致", "methods": [ "quick.waybill.toOrder" ], "notes": [ "文档中 isNeedLogin 为 false,但代码 systemMethods/quick/waybill.js 中 _noNeedLogin 为空字符串,未将 toOrder 加入免登录列表,实际需要登录验证,修正文档以与代码一致。" ], "type": "fixed" }, { "version": "2026.07.03-system-01", "date": "2026-07-03", "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", "methods": [ "storage.entry.getDirectInboundItems" ], "notes": [ "bindings 数组 description 中 wms_entry_receiving_binding 引用更新为 InboundDirectLog,明确旧表已弃用", "binding_id description 中 wms_entry_receiving_binding.id 更新为 InboundDirectLog.id", "allocated_quantity description 中补充来源 InboundDirectLog.quantity", "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" ], "type": "updated" }, { "version": "2026.07.03-system-02", "date": "2026-07-03", "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", "methods": [ "storage.directInbound.getItems" ], "notes": [ "bindings 数组 description 中更新为来自 InboundDirectLog,明确旧表已弃用", "binding_id description 更新为 InboundDirectLog.id", "allocated_quantity description 中补充来源 InboundDirectLog.quantity", "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" ], "type": "updated" }, { "version": "2026.07.03-system-03", "date": "2026-07-03", "summary": "binding 表弃用文档同步:commit 描述中 EntryReceivingBinding 更新为 InboundDirectLog", "methods": [ "storage.entry.commit" ], "notes": [ "commit description 中将 pending 状态的 EntryReceivingBinding 更新为 pending 状态的 InboundDirectLog,与代码实现一致" ], "type": "updated" }, { "version": "2026-07-03-entry-get-params-fix", "date": "2026-07-03", "type": "updated", "summary": "修正 storage.entry.get 文档:id 改为必填;移除未实现的 entry_order_code 参数;修正错误码与实际返回一致;补充 available_receiving_details 响应字段;修正 remaining_quantity 计算公式及 warehouse_image_url 实际行为", "methods": [ "storage.entry.get" ], "notes": [ "params: 移除 entry_order_code(代码中从未使用该参数),id 从 required=false 改为 required=true", "params: id 描述从'二选一'改为'必填'", "errors: 400 的 message 从'参数错误:id 与 entry_order_code 至少提供一个'改为'id 参数不能为空'", "errors: 移除不存在的 404 error,入库单不存在时实际返回 code=0, message='入库单不存在或无权访问'", "errors: 删除不存在的 500 error", "response: 新增 entryOrder.items[].available_receiving_details 字段及其描述", "response: remaining_quantity 描述从 'count - received_quantity - direct_inbound_quantity' 修正为 'max(0, count - received_quantity)'", "response: warehouse_image_url 描述从 StockWarehouse.image_url 改为'当前固定返回空字符串'", "response: warehouse_is_images 类型从 number(0/1) 改为 string(Y/N),与 StockWarehouse.is_images 实际存储一致", "response: warehouse_quantity/warehouse_locked_quantity/warehouse_is_batch_mgmt/warehouse_is_shelf_life_mgmt 补充无匹配时为 null 的说明", "description: 更新描述以反映实际逻辑流程" ] }, { "version": "2026.07.03-system-04", "date": "2026-07-03", "type": "modified", "summary": "order.pendingOrder.updateAddress 移除 remark(备注)修改功能,现在仅支持地址字段批量修改;备注修改已独立为 order.pendingOrder.updateRemark", "methods": [ "order.pendingOrder.updateAddress" ], "notes": [ "移除入参 remark 参数定义项。", "移除 remark 更新逻辑及相关描述,updateAddress 现在仅处理地址字段(name/mobile/tel/zip_code/province/city/area/town/detail_address)。", "description 更新:去掉 remark 相关描述,仅描述地址字段修改规则。", "response updated_count 描述更新:从「取地址更新行数与备注更新行数的最大值」改为单纯描述地址更新行数。", "errors 更新:移除 remark 相关错误说明('remark 字段不受此限制' 等),修改 '至少需要提供一个地址字段或备注进行修改' 为 '至少需要提供一个地址字段进行修改'。", "备注修改功能已独立为 order.pendingOrder.updateRemark 方法。" ], "module": "order.pendingOrder" }, { "version": "2026-07-16", "date": "2026-07-16", "summary": "新增 workbench.bindCamera 接口,支持工作台绑定/解绑摄像头", "methods": [ "workbench.bindCamera" ], "notes": [ "通过 device_ids JSON 字段存储绑定关系", "传空数组可解绑" ] }, { "version": "2026.07.17-stock-report-migration-01", "date": "2026-07-17", "type": "updated", "summary": "storage.report 模块迁移至 stock.report:修正语义错误,库存报表属于 stock 域而非 storage 域", "methods": [ "stock.report.search", "stock.report.searchStore", "stock.report.export", "stock.report.exportStore", "stock.report.exportTaskProgress" ], "notes": [ "将 systemMethods/storage/report.js 移动到 systemMethods/stock/report.js", "内部引用同步更新:类名 StorageReportMethodService→StockReportMethodService,缓存键 storage_report→stock_report,日志前缀 [storage.report]→[stock.report]", "旧文件直接删除,不保留兼容(storage.report 为语义错误,调用方需同步更新 method 名)", "更新 systems/storage/entry.js L273 注释引用", "文档:methods/system.json module storage.report→stock.report,5个 method 名同步更新" ] }, { "version": "2026.07.17-stock-transaction-export-01", "date": "2026-07-17", "type": "added", "summary": "新增 stock.transaction 商品流水导出(仓库侧+货主侧),异步任务模式,支持与列表查询一致的条件筛选", "methods": [ "stock.transaction.export", "stock.transaction.exportStore", "stock.transaction.exportTaskProgress" ], "notes": [ "systems/stock_transaction.js 新增 exportList(),复用 queryList 的查询逻辑,不分页导出 Excel(上限 50000 条)", "systemMethods/stock/transaction.js 新增 export/exportStore/exportTaskProgress,采用异步任务模式(setImmediate + 缓存)", "仓库侧导出自动限定 warehouse_id=ctx.user.store_id,货主侧需传 store_id", "导出 Excel 列:序号/创建时间/流水类型/仓库ID/货主ID/商品ID/变动数量/变更前库存/变更后库存/变更前锁定/变更后锁定/批次号/单据类型/单据号/收货单ID/入库单ID/发货单ID/操作人/备注" ] }, { "version": "2026.07.29-system-01", "date": "2026-07-29", "type": "added", "summary": "新增 waybill.warehouse 运单模块(仓库侧):list(列表)、detail(详情)、export(导出)3 个接口,支持运单号独立查询与管理", "methods": [ "waybill.warehouse.list", "waybill.warehouse.detail", "waybill.warehouse.export" ], "notes": [ "新增 waybill.warehouse.list:仓库侧运单列表查询,支持分页与多条件筛选(运单号/主单号/订单ID/订单号/物流公司/物流接口/平台/状态/退回/拦截/星河签收/包材/称重/关键词/时间范围),默认按 create_at desc 排序。", "新增 waybill.warehouse.detail:仓库侧运单详情查询,含关联订单信息、兄弟运单(sibling_waybills)、物流信息、状态信息、称重信息、打包信息(打包状态/打包人/打包时间)、打印记录列表。", "新增 waybill.warehouse.export:仓库侧运单导出,复用 list 筛选逻辑,异步任务模式,支持自定义导出字段。", "仓库隔离策略:所有接口自动注入 warehouse_id = ctx.user.store_id(全系统统一约定),不可由前端入参覆盖。", "快照字段方案:wms_order_express 表新增 delivery_order_code、store_id_snapshot、store_name_snapshot、warehouse_name_snapshot 四个快照列,列表查询无需 JOIN 订单表或货主表,仅单表查询 + SELF JOIN(主单号)。", "主单号/子单号规则:同一 order_id 下 business_key=1 为主单号,business_key>1 为子单号,沿用系统已有约定。", "命名空间规划:waybill.warehouse.* 本期实现(仓库侧),后续预留 waybill.store.*(货主侧)。", "本模块一期仅提供只读查询,不涉及运单创建/修改/删除,不修改任何现有接口。" ], "module": "waybill.warehouse" }, { "version": "2026.07.30-system-01", "date": "2026-07-30", "type": "changed", "summary": "更新 waybill.warehouse group API 文档:list 新增 waybillType/storeId 筛选、移除 pack_status 响应字段;detail 精简 package 对象;export 响应改为纯异步任务模式(仅含 task_id/status/progress/message/update_time)", "methods": [ "waybill.warehouse.list", "waybill.warehouse.detail", "waybill.warehouse.export", "waybill.warehouse.exportTaskProgress" ], "notes": [ "waybill.warehouse.list:新增 where.waybillType 筛选(\"main\"/\"1\"=主单号,\"child\"/\"2\"=子单号),新增 where.storeId 货主ID等值筛选。where.orderNo 标注暂不可用(待快照字段就绪)。response 移除 pack_status 字段(两表无关联,不再返回),list 字段数从 28 减至 27。", "waybill.warehouse.detail:package 对象移除 pack_status/pack_quantity/pack_at/packer_name 四个字段,仅保留 package_material_id 和 package_material_name。description 同步去掉\"打包状态\"相关描述。", "waybill.warehouse.export:响应简化为纯异步任务模式,data 仅含 task_id/status/progress/message/update_time,不含 total_count/current_count/result/error/download_url 等执行期字段(这些信息由 exportTaskProgress 接口返回)。export 的 where 参数同步新增 waybillType 和 storeId。", "waybill.warehouse.exportTaskProgress:无变更,保持不变。" ], "module": "waybill.warehouse" }, { "version": "2026.08.03-system-01", "date": "2026-08-03", "type": "added", "summary": "新增站内信(Inbox)管理模块,支持消息列表、详情、对话链、回信、重推、统计等管理功能,仓库维度隔离,warehouseId 由服务端上下文注入", "methods": [ "inbox.list", "inbox.detail", "inbox.thread", "inbox.reply", "inbox.retry", "inbox.stats" ], "notes": [ "入口:POST /system,body.method=inbox.{action},路由到 app/controller/inbox.index", "inbox.list:分页查询消息列表,支持 direction/pushStatus/targetChannel/keyword 筛选,列表不含 ext_data 和 push_response 大字段", "inbox.detail:查单条消息详情,含完整 push_response 推送响应信息", "inbox.thread:对话链查询,从指定消息向上查找根消息,向下收集所有回信,按时间升序返回", "inbox.reply:系统回信,自动继承原消息 ext_data/ref_code,写入 direction=outbound + parent_id 形成对话链,异步推送到目标渠道", "inbox.retry:手动重推失败消息(仅 push_status=3 可重推),重置为 push_status=0 并触发 setImmediate 异步推送", "inbox.stats:按方向/推送状态汇总统计 + 最近24小时新增数量", "安全边界:warehouse_id 由 ctx.user.store_id 注入(内部管理端),外部不可传入,保证仓库隔离", "底层服务:app/service/inbox/index.js(查询管理)+ app/service/inbox/receiver.js(接收推送)" ], "module": "inbox" }, { "version": "2026.08.03-system-02", "date": "2026-08-03", "summary": "setting.expressInterface.list 返回新增 quantity/recycled_quantity/cancel_quantity/allocated_quantity 扁平字段,数据源为 index.getShopExpressList", "methods": [ "setting.expressInterface.list" ], "notes": [ "每条记录新增四个扁平字段:quantity(可用面单数)、recycled_quantity(已回收)、cancel_quantity(已取消)、allocated_quantity(已分配)", "数据通过 Promise.all 并行调用 index.getShopExpressList 获取各店铺快递签约数据", "匹配逻辑分三层:sys_express_code 匹配快递 → site_code/branch_code 匹配网点 → shipperno/customer_code_list 匹配账号", "无店铺或无数据时四个字段均为 0" ] }, { "version": "2026.08.03-system-03", "date": "2026-08-03", "summary": "补全 setting.expressInterface.list response 所有返回字段文档,包含 express 子对象、quantity 四字段等", "methods": [ "setting.expressInterface.list" ], "notes": [ "补全所有 response list children 字段:从原有的 4 个扩展为 42 个完整字段", "新增 express 子对象文档(code/name/polyapi_code/polyapi_extra_info/pdd_code/ks_code/dyxd_code)", "保留 quantity/recycled_quantity/cancel_quantity/allocated_quantity 四个扁平面单数量字段" ] }, { "version": "2026.08.03-system-04", "date": "2026-08-03", "type": "added", "summary": "新增店铺-快递绑定策略模块 storeExpressBindingPolicy,支持仓库维度的货主/店铺->快递绑定策略 CRUD,按优先级匹配,可附加商品/地区/重量/金额等条件", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "storeExpressBindingPolicy.list:分页查询策略列表,支持 where 条件筛选(id/custom_name/store_id/shop_id/express_code/priority/is_enabled/creator_id/quickWhere),按 priority DESC、updated_at DESC 排序。", "storeExpressBindingPolicy.add:新增策略,必填 custom_name 和 express_code。express_code 须存在于 wms_express。同仓库下 custom_name 唯一。可选 store_id/shop_id/priority/is_enabled/match_condition/remark/creator_id。", "storeExpressBindingPolicy.edit:编辑策略,必填 id。仅更新传入的非 undefined 字段。修改 custom_name 时校验同仓库唯一性。", "storeExpressBindingPolicy.del:软删除策略(deleted_at + is_enabled=0),不物理删除。", "仓库隔离:所有操作按 ctx.user.store_id → warehouse_id 自动过滤。", "匹配条件 match_condition(JSON):支持 platform_codes/provinces/cities/item_codes/min_weight_g/max_weight_g/min_amount/max_amount。" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.03-system-05", "date": "2026-08-03", "type": "changed", "summary": "精简 storeExpressBindingPolicy:移除 store_id/shop_id 冗余字段,custom_name 明确为纯自由文本标签(与系统 shops 无关)", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "移除 add/edit 入参中的 store_id/shop_id(含 camelCase 兼容)", "list 响应不再返回 store_id/shop_id", "custom_name 为纯自由文本标签,与系统 shops 表无关" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-01", "date": "2026-08-04", "type": "changed", "summary": "storeExpressBindingPolicy 字段重构: match_condition JSON 拆分为独立字段 provinces/cities/min_weight_g/max_weight_g/weight_type,新增 prohibited_type_id", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "移除 match_condition JSON,拆分 provinces TEXT逗号分隔 + cities TEXT逗号分隔 + min_weight_g INT + max_weight_g INT + weight_type TINYINT 默认0", "weight_type 枚举 0=常规 1=轻货 2=重货 3=冷链 必填默认0", "新增 prohibited_type_id 关联 wms_prohibited_type.id" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-02", "date": "2026-08-04", "type": "changed", "summary": "合并 provinces/cities 为单一 regions 字段 TEXT逗号分隔", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "移除 provinces/cities 两个字段,合并为 regions TEXT 逗号分隔" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-03", "date": "2026-08-04", "type": "added", "summary": "新增 exclude_regions 排除地区字段", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "新增 exclude_regions 排除地区字段 TEXT逗号分隔" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-04", "date": "2026-08-04", "type": "changed", "summary": "修正 API 文档风格,对齐项目 shops.list 等模块规范", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "list page/pageSize 描述对齐 shops.list 风格", "add/edit 参数描述补充兼容性说明和详细格式" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-05", "date": "2026-08-04", "type": "added", "summary": "新增 shop_name 字段,用于包含店铺名称匹配", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "新增 shop_name TEXT逗号分隔,与 custom_name区分:custom_name=策略名称,shop_name=包含店铺名称" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-06", "date": "2026-08-04", "type": "added", "summary": "新增shop_name和store_ids字段", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "新增shop_name包含店铺名称", "新增store_ids限定货主ID" ], "module": "storeExpressBindingPolicy" }, { "version": "2026-08-05-wavePickTaskDetail-waveNo", "date": "2026-08-05", "summary": "pick.wavePickTaskDetail 响应 task 对象新增 wave_no 字段,从 wms_wave_pick_task_wave 关联 wms_wave_batch 获取波次号", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "task 对象新增 wave_no(string)字段,位于 task_no 之后;查询失败时降级为空字符串。", "数据来源:wms_wave_pick_task_wave INNER JOIN wms_wave_batch ON wave_id。" ] }, { "version": "2026-08-06", "date": "2026-08-06", "summary": "sign_method 收紧为仅支持 md5:create 固定为 md5 不可选,update 不允许修改 sign_method,list/detail 响应描述同步更新", "methods": [ "apiApp.list", "apiApp.detail", "apiApp.create", "apiApp.update" ], "notes": [ "验证确认 /openapi 和 /warehouse 实际只使用 MD5 签名算法", "apiApp.create: 删除 sign_method 入参,硬编码为 md5", "apiApp.update: sign_method 字段改为不可修改,传入即报错", "apiApp.list / apiApp.detail: sign_method 响应描述更新为「当前仅支持 md5」" ] }, { "version": "2026.08.10-afterSale-handleWorkOrder-remove-action", "date": "2026-08-10", "type": "changed", "summary": "afterSale.handleWorkOrder 移除 action 参数:action 不再由前端传入,改为服务端固定写入\"处理工单\";处理说明统一使用 remark 字段。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "移除 action 参数(原为必填 string,前端传入操作动作描述),前端不再需要也不接受此参数。", "步骤记录的 action 字段由服务端在 systems/afterSale.js handleWorkOrder 中硬编码为\"处理工单\"。", "处理说明统一使用 remark 字段承载。", "代码变更:systemMethods/afterSale.js handleWorkOrder 移除 action 解构与必填校验;systems/afterSale.js handleWorkOrder 移除 message 参数,addStep action 固定为\"处理工单\"。" ], "module": "afterSale" }, { "version": "2026.08.10-afterSale-handleWorkOrder-status-whitelist", "date": "2026-08-10", "type": "changed", "summary": "afterSale.handleWorkOrder 新增 status 枚举白名单校验:status 必须与 wms_after_sale 主表 AFTER_SALE_STATUS 枚举一致(pending/processing/completed/closed/cancelled),补全 cancelled 枚举值文档。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "status 参数新增枚举白名单校验:从 AfterSale.AFTER_SALE_STATUS 取 key 列表,不在白名单内返回 400。", "文档 status 枚举值补全 cancelled,与主表模型保持一致(pending | processing | completed | closed | cancelled)。", "校验同时在 systemMethods/afterSale.js(方法层)和 systems/afterSale.js(业务层)两层生效。", "仅代码校验增强 + 文档修正,不改变业务语义。" ], "module": "afterSale" }, { "version": "2026.08.10-afterSale-handleWorkOrder-status-default-processing", "date": "2026-08-10", "type": "changed", "summary": "afterSale.handleWorkOrder status 参数改为容错模式:不填或填错时默认 processing(处理中),不再返回 400 错误。status 始终写入主表。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "status 参数行为变更:原来不传时保持当前状态(有 if 判断),现在不填或填错默认 processing,始终写入主表。", "校验方式从白名单拒绝改为容错兜底:safeStatus = (targetStatus 合法) ? targetStatus : 'processing'。", "updateFields.status 从条件写入改为始终写入 safeStatus。", "role_group 回退判断同步从 targetStatus 改为 safeStatus。", "代码变更:systemMethods/afterSale.js + systems/afterSale.js 两层均改为容错逻辑。" ], "module": "afterSale" }, { "version": "2026.08.10-afterSale-handleWorkOrder-exclude-pending", "date": "2026-08-10", "type": "changed", "summary": "afterSale.handleWorkOrder status 白名单排除 pending:pending 是创建默认值(表示尚未处理),处理工单时不允许回退到此状态。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "handleWorkOrder 允许的 status 从全部 AFTER_SALE_STATUS 中排除 pending,剩余:processing | completed | closed | cancelled。", "若前端传 status=pending 视为填错,容错兜底为 processing。", "代码变更:两处 ALLOWED_STATUSES 增加 .filter(s => s !== 'pending')。" ], "module": "afterSale" }, { "version": "2026.08.10-afterSale-step-status-align-main-table", "date": "2026-08-10", "type": "changed", "summary": "wms_after_sale_detail.step_status 改为与 wms_after_sale.status 完全一致:字段类型从 TINYINT 改为 VARCHAR(20),每次写入步骤时记录主表当前 status 快照。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "DB 迁移:20260810140000-alter-wms-after-sale-detail-step-status-to-varchar.js — step_status 从 TINYINT UNSIGNED 改为 STRING(20),已有数据回填 processing。", "Model:after_sale_detail.js 移除 TINYINT 引用,step_status 改为 STRING(20),STEP_STATUS 枚举对齐主表 AFTER_SALE_STATUS。", "addStep 默认值从 2 改为 'processing'。", "transfer:step_status 取 update() 返回的 updated.status。", "handleWorkOrder:step_status 取 safeStatus(与写入主表的 status 完全一致)。", "registerClaim:step_status 取 afterSale.status(主表当前状态)。" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-add-waiting-status", "date": "2026-08-11", "type": "added", "summary": "新增 waiting(等待外部处理)状态:用于内部处理完成后等待外部第三方(快递、客户、平台)响应的场景。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "Model:after_sale.js AFTER_SALE_STATUS 新增 waiting: '等待外部处理'。", "Model:after_sale_detail.js STEP_STATUS 同步新增 waiting。", "handleWorkOrder 白名单自动包含 waiting(从 AFTER_SALE_STATUS 派生,仅排除 pending)。", "状态流转:processing → waiting → processing/completed。", "设计文档同步更新 ER 图、状态流转图、枚举表。" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-rename-pending-feedback", "date": "2026-08-11", "type": "changed", "summary": "waiting 重命名为 pending_feedback(等待外部反馈):语义更精确——内部已处理完并将信息发给外部,等待反馈后再决定是否继续处理,等待期间不需要内部介入。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "Model/DB/文档中 waiting 全部替换为 pending_feedback", "workList/workCount 排除列表新增 pending_feedback(等待反馈期间不需要内部处理)", "典型场景:客服收到拦截工单 → 发信息给运方 → 设为 pending_feedback 等待运方反馈 → 收到反馈后回到 processing 通知客户" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-batchSetPendingFeedback", "date": "2026-08-11", "type": "added", "summary": "新增 afterSale.batchSetPendingFeedback 批量设为待反馈接口:传入 ids 列表,按仓库 policy_config.after_sale_followup_hours 配置自动计算 followup_at,事务内批量更新状态并写入步骤记录。", "methods": [ "afterSale.batchSetPendingFeedback" ], "notes": [ "新增 method:afterSale.batchSetPendingFeedback,入参 ids(number[])和 remark(string, optional)", "业务层 systems/afterSale.js 新增 batchSetPendingFeedback:预校验 ids 有效性/终态/跨仓库,事务内逐条更新 status=pending_feedback + followup_at=NOW()+INTERVAL hours HOUR + 步骤记录", "方法层 systemMethods/afterSale.js 新增 batchSetPendingFeedback:从 ctx.user 提取 operator 信息和 warehouseId,委托 systems 层执行", "followup_at 时长复用现有 _resolveFollowupHours 三级查找:仓库 policy_config → 内置 DEFAULTS 映射 → 兜底 24h", "终态工单(completed/closed/cancelled)不可设为待反馈,跨仓库工单被拒绝,均返回在 failed 列表中", "已在 _noNeedRight 和 _noNeedAuth 中注册,写入操作会记录日志" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-batchClose", "date": "2026-08-11", "type": "added", "summary": "新增 afterSale.batchClose 批量完结/关闭接口:传入 ids + status(completed|closed),事务内批量更新状态、写入步骤记录,completed 时自动写入 resolved_at 并清除 followup_at。", "methods": [ "afterSale.batchClose" ], "notes": [ "新增 method:afterSale.batchClose,入参 ids(number[])、status(completed|closed)、resolution(string, optional)、remark(string, optional)", "业务层 systems/afterSale.js 新增 batchClose:预校验 ids 有效性/终态/跨仓库,事务内逐条更新 status + resolved_at + followup_at 清除 + 步骤记录", "方法层 systemMethods/afterSale.js 新增 batchClose:从 ctx.user 提取 operator 信息和 warehouseId,委托 systems 层执行", "终态工单(completed/closed/cancelled)不可重复完结/关闭,跨仓库工单被拒绝,均返回在 failed 列表中", "已在 _noNeedRight 和 _noNeedAuth 中注册,写入操作会记录日志" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-detail-enrich", "date": "2026-08-11", "type": "enhanced", "summary": "enhance: afterSale.detail 响应新增 related 字段,自动补充关联订单详情(收件人/发件人/商品明细/打包视频)和货主合约备注(store_remask)。", "methods": [ "afterSale.detail" ], "notes": [ "响应新增 related 对象:含 related.order(订单详情)和 related.store_contract(货主合约备注),仅在售后单有关联单据时有值", "related.order.recipient:从 wms_order_delivery 提取收件人姓名/电话/手机/邮箱/省市区/详细地址", "related.order.sender:从货主 store.subject_config 提取发件人信息(sender_name/sender_tel/地址)", "related.order.current_table:根据 dispatch_status/outbound_status/status 判断订单当前所在表(main/dispatch/history)", "related.order.items:从 order_delivery.items JSON 字段解析商品明细数组", "related.order.pack_videos:通过 PackTask → PackTaskVideo 关联查询打包视频列表(含 video_url/camera_id)", "related.store_contract:从 wms_store_warehouse 查询 store_remask(商家备注)/warehouse_remask(仓库备注)/使用状态", "所有关联查询使用 try-catch 兜底,查询失败时仅打 warn 日志,不影响主流程", "systems/afterSale.js 新增 _enrichAfterSaleDetail / _resolveOrderDetail / _resolveStoreContractNote 三个私有方法" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-detail-waybill", "date": "2026-08-11", "type": "enhanced", "summary": "enhance: afterSale.detail 响应 related 新增 waybill 字段,自动补充运单详情(快递公司名称 + 使用的物流接口)。", "methods": [ "afterSale.detail" ], "notes": [ "响应 related 新增 related.waybill 字段(waybill_id 不为空时自动返回)", "related.waybill.logistics_name:快递公司名称(如 圆通/中通/顺丰),来源 wms_order_express.logistics_name", "related.waybill.logistics_interface_name:使用的物流接口名称,来源 wms_order_express.logistics_interface_name", "related.waybill.logistics_code:物流编码,来源 wms_order_express.logistics_code", "related.waybill 同时返回 waybill_code/status/is_back/is_intercept/create_at 等基础字段", "systems/afterSale.js 新增 _resolveWaybillDetail 私有方法,查询失败仅打 warn 日志不影响主流程", "仅文档 + 代码变更,不涉及数据库变更" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-create-order-id-alias", "date": "2026-08-11", "type": "enhanced", "summary": "enhance: afterSale.create 入参新增 order_id 别名,与 order_delivery_id 等效,优先取 order_delivery_id,为空时回退到 order_id。", "methods": [ "afterSale.create" ], "notes": [ "create 方法解构时新增 order_id 别名读取;优先使用 order_delivery_id,为空时取 order_id", "仅方法层变更(systemMethods/afterSale.js),业务层无改动", "同时更新 JSDoc 注释,标注 order_delivery_id 兼容别名 order_id" ], "module": "afterSale" }, { "version": "2026.08.11-inbox-group-update-subtype-enum", "date": "2026-08-11", "summary": "enhance: inbox.group.update 子类型枚举补全三层约束。groupType=store 可用 after_sales/finance/receiving,groupType=warehouse 新增 production/stockout/all/exception,groupType=express 补全 pickup/after_sales。同步更新 subType description 和 400 错误码描述", "type": "enhance", "methods": [ "inbox.group.update" ], "notes": [ "subType 枚举由 GROUP_TYPES 统一定义,与 AI 函数分组同源", "后端已新增两层类型校验:subType 必须在对应 groupType 的合法子类型列表中" ] }, { "version": "2026.08.11-inbox-group-update-subtype-enum-v2", "date": "2026-08-11", "summary": "enhance: inbox.group.update 子类型枚举补全三层约束。groupType=store 可用 after_sales/finance/receiving,groupType=warehouse 新增 production/stockout/all/exception,groupType=express 补全 pickup/after_sales。同步更新 subType description 和 400 错误码描述", "type": "enhance", "methods": [ "inbox.group.update" ], "notes": [ "subType 枚举由 GROUP_TYPES 统一定义,与 AI 函数分组同源", "后端已新增两层类型校验:subType 必须在对应 groupType 的合法子类型列表中" ] }, { "version": "2026.08.11-inbox-group-update-subtype-enum-v3", "date": "2026-08-11", "summary": "enhance: inbox.group.update 子类型枚举补全三层约束。groupType=store 可用 after_sales/finance/receiving,groupType=warehouse 新增 production/stockout/all/exception,groupType=express 补全 pickup/after_sales。同步更新 subType description 和 400 错误码描述", "type": "enhance", "methods": [ "inbox.group.update" ], "notes": [ "subType 枚举由 GROUP_TYPES 统一定义,与 AI 函数分组同源", "后端已新增两层类型校验:subType 必须在对应 groupType 的合法子类型列表中" ] }, { "version": "2026.08.13-returnReceived", "date": "2026-08-13", "type": "added", "summary": "新增退回收到模块(returnReceived):退回包裹扫码登记、分页列表、详情、删除四个接口。扫码登记30日内同仓库同单号幂等(以第一次为准),反查原运单判定是否原单退回并同步标记 is_back='Y';列表/详情/删除仓库隔离。配套权限 527/528/529(扫码登记→仓库员工及以上,列表/删除→客服员工及以上)", "methods": [ "returnReceived.create", "returnReceived.list", "returnReceived.detail", "returnReceived.delete" ], "notes": [ "新增表 wms_return_received(仓库隔离 warehouse_id、退回收件单号 waybill_code、扫描日期 scan_date、扫描人员 scanner_id/scanner_name、运单关联 order_express_id/order_id/store_id 非必填)", "returnReceived.create:30日幂等 + 反查 wms_order_express.waybill_code,命中回填关联字段并同步 is_back='Y',返回 is_original_return/store_remark/duplicated", "returnReceived.list:分页列表,仓库隔离由服务端注入 warehouse_id,支持运单号/日期/扫描人员/货主/是否原单退回筛选", "returnReceived.detail:详情含原运单与货主合约备注,免权限但需登录+仓库隔离", "returnReceived.delete:物理删除,需权限+仓库隔离", "权限:527 returnReceived.create(仓库员工及以上)、528 returnReceived.list、529 returnReceived.delete(客服员工及以上);detail 复用 list 权限", "代码变更:app/model/return_received.js、app/service/systems/return_received.js、app/service/systemMethods/returnReceived.js、database/migrations/20260812160000-create-wms-return-received.js、20260813100000-create-return-received-permissions.js" ], "module": "returnReceived" }, { "version": "2026.08.13-shops-GetAuthorizeSessionKey-doc-sync", "date": "2026-08-13", "type": "updated", "summary": "同步 shops.GetAuthorizeSessionKey 文档:实现已切换为调用授权服务 saveShop 换取授权会话,旧的 PDD/CAINIAO 预占码方案已下线。", "methods": [ "shops.GetAuthorizeSessionKey" ], "notes": [ "实现:按店铺 platform_code 取 wms_print_platform.get_auth_platform_name 作为 platName,POST 授权服务 saveShop,携带 RedirectCodeUrl/shopName;京东平台附 VenderID,视频号平台改传 appId/toUserName 且不带 RedirectCodeUrl", "成功后更新店铺 access_token=sessionKey、status=1,返回 data.message='获取授权成功';上游 code≠0 或未返回 sessionKey 时抛 500", "文档更新:移除旧 data.session_key/authorize_url/state 返回结构与 501 未实现错误,补充 appId/toUserName 入参及 shop_id/callbackurl/platform_code 校验错误码", "仅文档同步,不修改业务代码" ], "module": "shops" }, { "version": "2026.08.13-interceptScan-non-intercept-guard", "date": "2026-08-13", "type": "updated", "summary": "order.recheckOrder.interceptScan 增加非拦截订单前置校验:运单不存在或未发起系统拦截时直接拒绝并提示「非拦截订单」,移除原先自动创建运单补充记录的逻辑。", "methods": [ "order.recheckOrder.interceptScan" ], "notes": [ "校验规则:运单记录不存在即拒绝;运单 is_intercept≠'Y' 时回查关联订单,intercept_status 不在 requested/intercepting 也拒绝,提示「非拦截订单」", "校验通过后原逻辑不变:标记 is_back='Y'/is_intercept='Y'、处理未完结售后工单、订单级更新 intercepted_at_warehouse 并释放储位分配与订单锁", "移除运单不存在时自动创建补充记录的分支(未发起拦截的运单不再被静默置为拦截)", "同步更新 JSDoc 与 methods/system.json 文档,错误码新增 400 非拦截订单" ], "module": "order.recheckOrder" }, { "version": "2026.08.13-returnUnpack", "date": "2026-08-13", "type": "added", "summary": "新增退回拆包模块(returnUnpack):开拆包单、录明细、更新明细、移除明细、取消、提交确认、分页列表、明细列表、详情、删除十个接口。开单反查原运单判定原单退回并回填货主,未命中原单时按 warehouse_id+waybill_code 从退回查询记录反查货主;拆包单号 RP+YYYYMMDD+6位序号;状态机 unpacking/completed/cancelled;明细识别状态 none_recognized/partial_recognized/all_recognized;全接口仓库隔离(服务端注入 warehouse_id)。配套权限 540-549(作业类→仓库员工及以上,查询/删除类→客服员工及以上,detail 免权限复用列表权限)", "methods": [ "returnUnpack.create", "returnUnpack.addDetail", "returnUnpack.updateDetail", "returnUnpack.removeDetail", "returnUnpack.cancel", "returnUnpack.submit", "returnUnpack.list", "returnUnpack.detailList", "returnUnpack.detail", "returnUnpack.delete" ], "notes": [ "新增表 wms_return_unpack(主表)/ wms_return_unpack_detail(明细)/ wms_return_unpack_video(视频,paranoid 软删)/ wms_return_query_log(退回查询记录)", "returnUnpack.create:waybill_code 必填;反查 wms_order_express.waybill_code 命中则回填 order_express_id/order_id/store_id 并返回原订单详情(复用 afterSale._resolveOrderDetail);未命中再从 wms_return_query_log 按 warehouse_id+waybill_code 反查货主(限最近 3 个月内登记);返回 id/record/is_original_return/store_remark/order", "returnUnpack.addDetail:主单非终态校验;stock_id 有值 → 查 wms_stock_warehouse 校验货主归属(不一致 403)+ 回填 is_recognized=1 与快照;主表 store_id 为空时以首个识别商品回填货主;写明细后重算 total_items/total_quantity/detail_status", "returnUnpack.updateDetail:白名单仅 quantity/remark;仅 quantity 变更时重算主表汇总", "returnUnpack.removeDetail:明细表 paranoid:false 硬删除 + 重算主表汇总", "returnUnpack.cancel:仅 unpacking 状态;事务内硬删主表+明细,软删视频", "returnUnpack.submit:仅 unpacking;status=completed + 回写 end_time,并同步更新 wms_return_query_log.is_back=1(失败不阻断主流程)", "returnUnpack.list:主表分页,仓库隔离服务端注入 warehouse_id;where 支持 unpack_no/waybill_code 模糊、unpack_date/start_time/end_time 范围、status/detail_status/unpacker_id/return_received_id/store_id/order_express_id/order_id 等值", "returnUnpack.detailList:明细分页 + stockWarehouse 关联(命中时);where 支持 unpack_id/stock_id/barcode/is_recognized/product_status", "returnUnpack.detail:主表 + details(stockWarehouse) + videos(camera) + returnReceived;原单退回时返回 related.order;免权限仅登录 + 仓库隔离", "returnUnpack.delete:后台删除不限状态;事务物理删主表+明细,软删视频", "仓库隔离:全部接口禁止前端传入 warehouse_id,由服务端注入 ctx.user.store_id;拆包单号规则 RP+YYYYMMDD+6位序号(仓库维度序号)", "权限:540 returnUnpack.create、541 addDetail、542 updateDetail、543 removeDetail、544 cancel、545 submit(仓库员工及以上);546 list、547 detailList、548 detail、549 delete(客服员工及以上);detail 免权限(复用列表权限)", "代码变更:app/model/return_unpack.js、return_unpack_detail.js、return_unpack_video.js、return_query_log.js;app/service/systems/return_unpack.js;app/service/systemMethods/returnUnpack.js;database/migrations/20260813120000-20260813120300 建表、20260813130000 权限" ], "module": "returnUnpack" }, { "version": "2026.08.13-returnReceived.createResponse", "date": "2026-08-13", "type": "updated", "summary": "returnReceived.create 出参结构调整:由平铺返回登记字段改为包装结构 { record, is_original_return, store_remark, duplicated },record 含登记记录完整字段与派生字段 is_original_return/store_remark,与代码实现(app/service/systems/return_received.js)及设计文档对齐", "methods": [ "returnReceived.create" ], "notes": [ "原出参平铺 id/waybill_code/scan_date/scanner_id/scanner_name/order_express_id/order_id/store_id/remark/is_original_return/store_remark/duplicated,现改为四个顶层字段:record(object,必填)、is_original_return(boolean,必填)、store_remark(string,必填)、duplicated(boolean,必填)", "record 内字段:id、waybill_code、scan_date、scanner_id、scanner_name、order_express_id、order_id、store_id、remark、created_at、updated_at(时间为格式化字符串)+ 派生字段 is_original_return、store_remark", "顶层 is_original_return / store_remark / duplicated 为 record 之外独立返回字段,与 record 内同名字段取值一致", "仅文档变更,代码实现已对齐(create 返回 { record, is_original_return, store_remark, duplicated },30日幂等命中与新建分支结构一致)" ], "module": "returnReceived" }, { "version": "2026.08.13-returnWaybill", "date": "2026-08-13", "type": "added", "summary": "新增运单退回登记模块(returnWaybill):复用 wms_return_query_log 表实现「货主 + 运单号」退回关系的增删查改五个接口(create/update/list/detail/delete)。create 校验货主合约并幂等返回已有记录;update 支持改运单号/货主/备注,改后冲突 409 拒绝;list 分页筛选(运单号模糊/货主/是否已通知/是否退回/登记时间范围);detail 免权限仅登录+仓库隔离;delete 物理删除。全接口仓库隔离(warehouse_id 服务端注入)。配套权限 551-555(作业类 create/update→仓库员工及以上,查询/删除类 list/detail/delete→客服员工及以上,detail 免权限复用列表权限)", "methods": [ "returnWaybill.create", "returnWaybill.update", "returnWaybill.list", "returnWaybill.detail", "returnWaybill.delete" ], "notes": [ "复用表 wms_return_query_log(20260813120300 迁移已落地):warehouse_id/store_id/waybill_code/remark/is_notified/is_back/created_at/updated_at;登记接口不维护 is_notified/is_back(由定时任务与拆包联动维护)", "returnWaybill.create:waybill_code/store_id 必填;货主合约校验(wms_store_warehouse 存在 store_id+warehouse_id,无合约 400 拒绝);同仓库+货主+运单号已存在时幂等返回已有记录 duplicated=true;写入 is_notified=0/is_back=0", "returnWaybill.update:id 必填;仓库隔离校验;waybill_code/store_id/remark 可选更新;store_id 变更时校验新货主合约;改后与另一条同仓库+货主+运单号冲突则 409 拒绝", "returnWaybill.list:pagination(pageSize 上限 500 默认 20)+ where(waybill_code 模糊、store_id、is_notified、is_back、created_at 起止)+ sort(id/created_at/updated_at/waybill_code,默认 created_at desc)", "returnWaybill.detail:免权限(复用列表权限),仅登录 + 仓库隔离校验", "returnWaybill.delete:物理删除(表 paranoid:false),返回被删除记录 id", "仓库隔离:所有接口 warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入", "权限:551 create、552 update(仓库员工及以上);553 list、554 detail、555 delete(客服员工及以上);detail 免权限复用 list 权限", "代码变更:app/service/systems/return_waybill.js、app/service/systemMethods/returnWaybill.js、database/migrations/20260813160000-create-return-waybill-permissions.js" ], "module": "returnWaybill" }, { "version": "2026.08.13-returnUnpack.detailAuth", "date": "2026-08-13", "type": "updated", "summary": "returnUnpack.detail 鉴权配置变更:不再免权限(原 _noNeedRight='detail'),改为走 API 权限校验(固定权限 ID 548,客服员工及以上),与 app/service/systemMethods/returnUnpack.js 实现对齐。", "methods": [ "returnUnpack.detail" ], "notes": [ "isNeedAuth:false → true;description 同步说明「需 548 权限(客服员工及以上)」", "代码对齐:returnUnpack.js _noNeedRight 改为空字符串,detail 与其他接口一致走 API 权限校验", "权限 548 为客服员工及以上(与原「查询类→客服员工及以上」设计一致)", "仅文档同步,其余接口与模块不动" ], "module": "returnUnpack" }, { "version": "2026.08.13-returnUnpack.addDetailBarcode", "date": "2026-08-13", "type": "updated", "summary": "returnUnpack.addDetail 新增 barcode 入参(可选):stock_id 为空时按条码反查本仓库商品(wms_stock_barcodes)再走识别流程,反查不到按无关联货物处理;条码同步写入明细作记录(此前固定写 null)。复用基础模块条码索引,支持 PDA 扫描条码录明细。", "methods": [ "returnUnpack.addDetail" ], "notes": [ "params 新增 barcode(string,可选,最长100,body)", "识别优先级:stock_id > barcode 反查 > 无关联货物", "明细 barcode 字段由固定 null 改为记录扫描条码", "business 层按 warehouse_id+barcode 匹配 wms_stock_barcodes(uk_barcode 全局唯一,加仓库过滤防跨仓串货)" ], "module": "returnUnpack" }, { "version": "2026.08.13-returnUnpack.addDetailBarcodeV2", "date": "2026-08-13", "type": "updated", "summary": "returnUnpack.addDetail 识别策略调整:未指定 stock_id 时一律标注未知商品(item_name=未知商品),移除按条码自动反查 stock_id 的逻辑(同一条码可能对应多个 stock_id,自动匹配易误配);barcode 仍写入明细作记录。", "methods": [ "returnUnpack.addDetail" ], "notes": [ "移除 barcode 反查 wms_stock_barcodes 自动识别逻辑(v1 新增,本次回退)", "未指定 stock_id:is_recognized=0,item_name=未知商品(此前为 null)", "barcode 参数保留:仅作记录写入明细,不参与商品匹配", "docs 同步:addDetail description / stock_id / barcode 参数说明更新" ], "module": "returnUnpack" }, { "version": "2026.08.13-returnUnpack.orderInfoSnapshot", "date": "2026-08-13", "type": "updated", "summary": "wms_return_unpack 主表新增订单信息快照字段 source_order_codes(平台交易单号)/ shop_name(店铺名称=货主自定义店铺名称 store_remask),returnUnpack.create 原单退回时回填;退回查询(查退回)优先取主表快照返回交易单号与自定义店铺。", "methods": [ "returnUnpack.create" ], "notes": [ "迁移 20260813170000-add-return-unpack-order-info.js:addColumn source_order_codes VARCHAR(500) + shop_name VARCHAR(50)", "create 原单退回:source_order_codes 取 wms_order_express.source_order_codes,shop_name 取 store_remask", "addDetail 首个识别商品回填主表 store_id 时同步回填 shop_name", "退回查询 _resolveReturnOrderInfo 优先主表快照,空时实时兜底(交易单号→原运单/原订单,店铺→store_remask)" ], "module": "returnUnpack" }, { "version": "2026.08.18-storeWarehouse-sign-confirmSign-doc", "date": "2026-08-18", "type": "added", "summary": "补齐 storeWarehouse 签约接口文档(纯文档补全,无业务代码变更):新增 storeWarehouse.store.confirmSign(货主侧确认签约)、storeWarehouse.warehouse.sign(仓库侧发起签约)、storeWarehouse.warehouse.confirmSign(仓库侧确认签约)三个方法的入参/出参/错误码说明。", "methods": [ "storeWarehouse.store.confirmSign", "storeWarehouse.warehouse.sign", "storeWarehouse.warehouse.confirmSign" ], "notes": [ "storeWarehouse.store.confirmSign:当前主体作为对方主体确认待签约申请,auth_status 由 1(申请中)变更为 2(已通过);入参 id(兼容 contract_id);400=id 缺失或签约状态非待签约、403=当前主体不在签约关系中或发起方自确认、404=签约关系不存在;响应 data.mode=confirm 与 data.contract 精简对象(id/store_id/warehouse_id/counterparty_name/remask/use_status/auth_status/auth_status_label/auth_end/print_quantity/has_qimen_config)", "storeWarehouse.warehouse.sign:仓库侧发起签约,当前仓库在 store_id 方、对方在 warehouse_id 方,支持签约外部合作仓库;入参 counterparty_id(兼容 warehouse_id / store_id),当前主体自动识别;响应 data.mode=initiate/already_exists/already_confirmed 与 data.contract;400=对方主体缺失/日期非法,404=签约对象不存在", "storeWarehouse.warehouse.confirmSign:仓库侧确认签约,校验逻辑与货主侧确认一致(400/403/404 同 storeWarehouse.store.confirmSign)", "代码对齐:app/service/systemMethods/storeWarehouse/store.js#confirmSign、app/service/systemMethods/storeWarehouse/warehouse.js#sign/#confirmSign 均已注册(_noNeedAuth 含三个方法,isNeedAuth=false、isNeedLogin=true);实现位于 app/service/systems/store_warehouse.js#sign/#confirmSign;权限表 method id 397「签约确定」", "仅文档变更,无业务代码修改" ], "module": "storeWarehouse" }, { "version": "2026.08.21-storage.inventory.list-stock-query", "date": "2026-08-21", "type": "updated", "summary": "storage.inventory.list 新增 where.stock_query 虚拟筛选:按商品编码/名称/货物编码/条码/SKU ID 模糊匹配库存列表", "methods": [ "storage.inventory.list" ], "notes": [ "与订单查询一致的 stock_query 虚拟筛选字段,如 where.stock_query = { operator: 'like', value: '111' }。", "解析链路:stock_query → wms_stock_warehouse(item_code/item_name/goods_code/纯数字精确 id)+ wms_stock_barcodes(barcode)→ stock_id 集合 → wms_storage.stock_id IN 过滤;无匹配时返回空列表。", "代码变更:systemMethods/storage/inventory.js#list 新增 extractStockQueryVirtualFilter(从 where 提取并移除 stock_query);systems/storage/inventory.js#getInventoryList 新增 stockQuery 参数与 resolveStockQueryToStockIds;methods/system.json 同步 where 参数文档(export 注明暂不支持 stock_query)。" ], "module": "storage" }, { "version": "2026.08.24-storage.inventory.directPutaway", "date": "2026-08-24", "type": "added", "summary": "新增 storage.inventory.directPutaway 接口:收货单直入库存(一步完成),直接写 wms_storage 并生成入库单", "methods": [ "storage.inventory.directPutaway" ], "notes": [ "新增收货单直入库存接口,与 storage.inventory.quickPutaway(转入库单,不写库存)并存,名称不交换保持兼容。", "核心流程:校验收货单(completed + is_review=true,未作废)→ 检查货主配置 policy_config.allow_receiving_direct_putaway=1 → 过滤未入库明细(storage_status!=all)并校验全部已匹配系统商品 → 事务内锁定收货单行防并发 → 创建入库单 SCRK(order_status=COMPLETED、sync_status=SUCCESS,一步完成)→ 入库单明细与收货明细一一对应(不合并,每行 count/received_quantity=actual_quantity)→ 写入 wms_entry_order_receiving 主表级绑定 → 按 stock_id 聚合悲观行锁更新 wms_stock_warehouse 总库存并写 wms_stock_transaction(order_type=SCRK,与现有链路一致)→ 按收货明细库位 space_id 逐明细写入/累加 wms_storage 并写 wms_storage_transaction(order_type=entry_order,与现有 storage.entry.commit 链路一致)→ 逐明细写入 wms_inbound_direct_log(entry_item_id/receiving_detail_id/space_id 齐全,status=committed、inbound_type=import,与 storage.entry.commit 链路口径一致,保证 scanDetail/可用数量占用统计等读取链路数据一致)→ 回填收货明细 storage_status=all/stored_quantity 与主表 storage_status(all/partial)→ 操作日志。", "日志全量写入:storage 变更记录(wms_storage_transaction,逐明细含 before/after 数量与锁定量)、stock 变更记录(wms_stock_transaction,按 SKU 聚合含 before/after 数量与锁定量)、stock 变更(wms_stock_warehouse 悲观行锁 increment quantity);操作日志(wms_operation_log)同时写三条:businessType=entry_order(ENTRY_ORDER_DIRECT_PUTAWAY)、businessType=storage(STORAGE_DIRECT_PUTAWAY,记录库位库存写入笔数与数量)、businessType=stock(STOCK_DIRECT_PUTAWAY,记录各 SKU 总量变更前后值摘要)。", "库位规则:明细 space_id 有效则按其库位入库,否则回退默认库位 1;批次取收货明细 batch_number,无批次则以入库单号作为批次号;生产/效期日期取收货明细 production_date/expiry_date。", "与 quickPutaway 的区别:directPutaway 一步直接写库存(入库单 COMPLETED),quickPutaway 仅转入库单(PENDING)不写库存,需再走 storage.entry.commit 才写库存。", "货主开关:policy_config 新增 allow_receiving_direct_putaway(默认未开启时 400 拒绝),与 allow_receiving_quick_putaway 相互独立;app/model/store_warehouse.js 的 POLICY_CONFIG_FIELDS 白名单已补充该字段(否则模型 getter sanitizeOnly 会过滤掉该键导致开关无法读取)。", "代码变更:app/service/systems/storage/inventory.js#directPutaway、app/service/systemMethods/storage/inventory.js#directPutaway(_noNeedAuth 新增 directPutaway)、methods/system.json 新增 method 文档、database/migrations/20260824 新增权限记录(path=storage.inventory.directPutaway)。" ], "module": "storage" }, { "version": "2026.09.10-order.wave.wavePickTaskList-cart-code", "date": "2026-09-10", "type": "updated", "summary": "order.wave.wavePickTaskList 新增 cart_code 筛选:按拣货车编码查询拣货任务", "methods": [ "order.wave.wavePickTaskList" ], "notes": [ "新增 cart_code 过滤字段,匹配拣货任务主表快照字段 wms_wave_pick_task.current_cart_code_snapshot(与列表返回的 current_cart_code_snapshot 同源),支持操作符对象 { operator: 'like'|'notlike'|'eq', value },默认 like;顶层 cart_code 与 where.cart_code 均支持,顶层参数优先。", "keyword 关键字搜索同步覆盖 current_cart_code_snapshot 字段(此前文档已声明支持,本次代码补齐)。", "代码变更:app/service/systemMethods/order/wave.js#normalizeWavePickTaskListRequest 新增 cart_code 顶层合并、#buildWavePickTaskListWhereClause 新增 cart_code 白名单与条件拼接(复用 appendNameCondition)。", "顺带修正:该接口失败响应未透传业务码(this.fail(msg, 400) → this.fail(msg, {}, 400/500)),并将「不支持的 operator」类入参错误归为 400,与其它 systemMethods 约定及本文档错误码一致。", "测试:test/app/service/systemMethods/order/wave.wavePickTaskList.test.js 补充 cart_code 操作符/默认模糊/顶层优先/keyword 覆盖用例,并修复原 mock 缺失 QueryTypes.SELECT 导致的既有用例失败。" ], "module": "order" } ]