diff --git a/methods/changes/system.json b/methods/changes/system.json index c984ee9..3e99e45 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,203 @@ [ + { + "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", @@ -18,6 +217,26 @@ ], "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", @@ -39,6 +258,207 @@ ], "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", diff --git a/methods/system.json b/methods/system.json index bf188c0..4ab019d 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.48", - "updatedAt": "2026-08-29", + "version": "0.3.58", + "updatedAt": "2026-08-30", "headers": [ { "name": "platform", @@ -2543,7 +2543,7 @@ "type": "array", "required": false, "source": "body", - "description": "导出表头字段白名单(中文表头字符串数组,如 [\"系统订单号\",\"外部订单号\"]);不传或空数组时输出全部列。枚举(共 51 个,校验不区分导出模式):系统订单号、外部订单号、平台单号、订单ID、订单号、外部单号、订单状态、抓取波次号、波次号、波次序号、货主、平台、店铺昵称、收件人、收件人电话、省、市、区、镇、详细地址、商品明细、仓库商品名称、商品条码、商品图片、数量、物流公司、运单号、业务类型、运单接口、包材ID、包材编码、包材名称、分配时间、商品种数、商品件数、商品重量、称重重量(g)、订单金额、实收金额、创建时间、支付时间、发货时间、出库状态、复核状态、复核完成状态、配货状态、打包状态、备注、买家留言、卖家留言、归档时间。其中仅 waybill 模式输出:系统订单号、外部订单号、平台单号、抓取波次号、商品明细;仅 item 模式输出:订单ID、订单号、外部单号、波次号、仓库商品名称、商品条码、商品图片、数量;其余为两种模式通用(选了当前模式不存在的表头时该列自动忽略)。传入非法表头会报错(错误信息列出非法值);支持 export_columns 与 exportColumns 两种写法" + "description": "导出表头字段白名单(中文表头字符串数组,如 [\"系统订单号\",\"外部订单号\"]);不传或空数组时输出全部列。枚举(共 52 个,校验不区分导出模式):系统订单号、外部订单号、平台单号、订单ID、订单号、外部单号、订单状态、抓取波次号、波次号、波次序号、货主、平台、来源、店铺昵称、收件人、收件人电话、省、市、区、镇、详细地址、商品明细、仓库商品名称、商品条码、商品图片、数量、物流公司、运单号、业务类型、运单接口、包材ID、包材编码、包材名称、分配时间、商品种数、商品件数、商品重量、称重重量(g)、订单金额、实收金额、创建时间、支付时间、发货时间、出库状态、复核状态、复核完成状态、配货状态、打包状态、备注、买家留言、卖家留言、归档时间。其中仅 waybill 模式输出:系统订单号、外部订单号、平台单号、抓取波次号、商品明细;仅 item 模式输出:订单ID、订单号、外部单号、波次号、仓库商品名称、商品条码、商品图片、数量;其余为两种模式通用(选了当前模式不存在的表头时该列自动忽略)。来源列(字段 create_channel,中文取值:手工单/接口/奇门/出库转单)位于平台列之后,waybill/item 两种模式均输出。传入非法表头会报错(错误信息列出非法值);支持 export_columns 与 exportColumns 两种写法" } ], "response": [ @@ -6918,7 +6918,7 @@ "name": "waybill_code", "type": "string", "required": false, - "description": "运单号(模糊匹配)" + "description": "运单号。通过 wms_order_express 表解析 order_id 后按订单过滤(wms_pack_task.waybill_code 通常为空)。匹配规则(不再支持部分单号模糊匹配):①完整单号等值匹配;②剥离一单多件包裹序号分段后缀(如 -1-1-)后的主体单号等值匹配;③主体单号前缀匹配(LIKE '主体-%',同主体不同分段序号,通配符已转义)。无任何匹配时返回空列表" }, { "name": "wave_no", @@ -6942,7 +6942,7 @@ "name": "quickWhere", "type": "string", "required": false, - "description": "快捷搜索:波次号模糊匹配 + 运单号通过 express→order→wave 链路解析" + "description": "快捷搜索:波次号模糊匹配(LIKE '%kw%',逻辑不变)+ 运单号经 express→order→wave 链路解析(团购按波次号查、散单按订单ID查)。运单号匹配优先级:先按「完整单号等值 + 剥离一单多件分段后缀(如 -1-1-)后的主体单号等值 + 主体前缀 LIKE '主体-%'」精确匹配;精确未命中且关键词 trim 后长度 ≥ 4(QUICK_WHERE_WAYBILL_FUZZY_MIN_LENGTH)时才降级为 LIKE '%kw%' 模糊查询(兼容输入部分单号的场景);trim 后长度 < 4 的短词(含单字符如 \"7\")禁止降级模糊,运单号解析直接返回空结果(避免 %短词% 误命中海量历史单号);波次号模糊逻辑不变" }, { "name": "start_time", @@ -11199,16 +11199,17 @@ }, { "method": "order.deliveryOrder.quickSearch", - "description": "订单快速搜索。跨表联合搜索:运单号(wms_order_express 精确匹配)、发货单号/外部订单号/平台交易单号(dispatch 表模糊匹配)。返回匹配的订单列表(最多20条),包含关键字段及关联运单号。", + "description": "订单快速搜索。跨表联合搜索:运单号(wms_order_express,支持完整单号等值、剥离一单多件包裹序号分段后缀(如 -1-1-)后的主体单号等值、主体前缀 LIKE '主体-%' 匹配,不再做部分单号模糊匹配)、发货单号 delivery_order_code / 原始平台订单号 source_order_codes(express 表快照字段,模糊匹配)。返回匹配的订单列表(最多20条),包含关键字段及关联运单号;平台交易单号 pay_no 仅作为结果字段回显,不参与搜索匹配。", "isNeedAuth": false, "isNeedLogin": true, + "headers": [], "params": [ { "name": "keyword", "type": "string", "required": true, "source": "body", - "description": "搜索关键词。同时匹配运单号(精确)、发货单号 delivery_order_code(模糊)、外部订单号 source_order_codes(模糊)、平台交易单号 pay_no(模糊)" + "description": "搜索关键词。运单号按「完整单号等值 + 剥离一单多件分段后缀(如 -1-1-)后的主体单号等值 + 主体前缀 LIKE '主体-%'」匹配(不做部分单号模糊);发货单号 delivery_order_code、原始平台订单号 source_order_codes 为模糊匹配(LIKE '%kw%');平台交易单号 pay_no 仅回显、不参与匹配" } ], "response": [ @@ -22652,7 +22653,7 @@ }, { "method": "storage.entry.quickInbound", - "description": "快捷直入(虚拟入库):将入库单商品直入到虚拟库位(space_id=2),跳过收货/质检流程。有绑定收货单时,只取收货单中与入库单明细有交集(按 stock_id 判断)且剩余可入数量(actual_quantity - stored_quantity)的商品直入,实际入库量 = min(明细计划数量, 收货单剩余可入数量),并在事务内回写收货单明细已入库数量与收货单入库状态;未绑定收货单时按明细计划数量全量直入。仅支持 CREATED 状态的入库单;CANCELLED(已作废)、COMPLETED(已完成)、PENDING 等其他状态均拒绝操作。事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、回写收货单明细、变更入库单状态为 COMPLETED。事务外异步回传奇门/API。", + "description": "快捷直入(虚拟入库):将入库单商品直入到虚拟库位(space_id=2),跳过收货/质检流程。有绑定收货单时,只取收货单中与入库单明细有交集(按 stock_id 判断)且剩余可入数量(actual_quantity - stored_quantity)的商品直入,实际入库量 = min(明细计划数量, 收货单剩余可入数量),并在事务内回写收货单明细已入库数量与收货单入库状态;未绑定收货单时按明细计划数量全量直入。仅支持 CREATED 状态的入库单;CANCELLED(已作废)、COMPLETED(已完成)、PENDING 等其他状态均拒绝操作。事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、回写收货单明细、变更入库单状态为 COMPLETED,并在同一事务内回写入库单 is_virtual_inbound(是否虚拟入库):有绑定收货单 → 0(非虚拟入库),无绑定收货单 → 1(虚拟入库)。事务外异步回传奇门/API。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], @@ -31467,7 +31468,7 @@ }, { "method": "workbench.business", - "description": "工作台业务入口(免登录免鉴权,入参 name + data,业务逻辑待实现)", + "description": "工作台业务入口(免登录免鉴权,入参 name + data)。name 支持 queryOrder/query(条码查订单,data 需 barcode+warehouseId)、packOrder(开始打包)、finishPack(结束打包)、sendWeight(称重);不支持的业务名称报错。以下响应结构为 queryOrder/query(条码查订单)的返回。", "isNeedAuth": false, "isNeedLogin": false, "headers": [], @@ -31477,31 +31478,216 @@ "type": "string", "required": true, "source": "body", - "description": "业务名称(用于分发具体逻辑)" + "description": "业务名称:queryOrder/query(条码查订单)、packOrder、finishPack、sendWeight" }, { "name": "data", "type": "object", "required": false, "source": "body", - "description": "业务数据(透传)" + "description": "业务数据(透传)。queryOrder/query 需 barcode(运单号,必填)+ warehouseId(仓库ID,必填)" } ], "response": [ { - "name": "name", + "name": "barcode", "type": "string", "required": true, - "description": "回显业务名称" + "description": "条码(运单号)" }, { - "name": "received", - "type": "boolean", + "name": "waybill_code", + "type": "string", "required": true, - "description": "是否已接收" + "description": "运单号" + }, + { + "name": "isSandan", + "type": "number", + "required": true, + "description": "是否散单:1=散单 0=团购(波次类型 wave_type=1 时判定为团购)" + }, + { + "name": "store_remark", + "type": "string", + "required": true, + "description": "货主备注(合约表 store_warehouse.store_remask,无合约或为空时为空字符串)" + }, + { + "name": "express", + "type": "object", + "required": true, + "description": "运单信息:logistics_name(快递公司名称)、weighing_weight(称重重量)、package_material_name(包材名称快照)" + }, + { + "name": "order", + "type": "object", + "required": true, + "description": "订单详情", + "children": [ + { + "name": "id", + "type": "number", + "description": "订单ID" + }, + { + "name": "delivery_order_code", + "type": "string", + "description": "发货单号" + }, + { + "name": "order_type", + "type": "number", + "description": "订单类型" + }, + { + "name": "warehouse_id", + "type": "number", + "description": "仓库ID" + }, + { + "name": "store_id", + "type": "number", + "description": "货主ID" + }, + { + "name": "status", + "type": "number", + "description": "订单状态" + }, + { + "name": "step", + "type": "number", + "description": "订单步骤" + }, + { + "name": "wave_id", + "type": "number", + "description": "波次ID" + }, + { + "name": "wave_no", + "type": "string", + "description": "波次号" + }, + { + "name": "post_status", + "type": "string", + "description": "过账状态" + }, + { + "name": "pick_status", + "type": "string", + "description": "拣货状态" + }, + { + "name": "pack_status", + "type": "string", + "description": "打包状态(原始值):none/padding/fin/error,空值/null 归一化为 none" + }, + { + "name": "intercept_status", + "type": "string", + "description": "拦截状态(原始值):空值/null 归一化为 none;散单/团购均返回" + }, + { + "name": "recheck_status", + "type": "string", + "description": "复核状态" + }, + { + "name": "outbound_status", + "type": "string", + "description": "出库状态" + }, + { + "name": "items_count", + "type": "number", + "description": "商品件数" + }, + { + "name": "items_total", + "type": "number", + "description": "商品总数" + }, + { + "name": "items_weight", + "type": "number", + "description": "商品总重量" + }, + { + "name": "source_platform_code", + "type": "string", + "description": "来源平台编码" + }, + { + "name": "logistics_name", + "type": "string", + "description": "快递公司名称" + }, + { + "name": "create_at", + "type": "string", + "description": "创建时间" + }, + { + "name": "updated_at", + "type": "string", + "description": "更新时间" + }, + { + "name": "intercept_flag", + "type": "number", + "description": "拦截标志(仅散单 isSandan=1 返回,团购不返回):拦截状态(intercept_status)不等于 none 时为 1,等于 none 时为 0" + }, + { + "name": "pack_flag", + "type": "number", + "description": "打包标志(仅散单 isSandan=1 返回,团购不返回):打包状态(pack_status)不等于 none 时为 1,等于 none 时为 0" + } + ] + }, + { + "name": "items", + "type": "array", + "required": true, + "description": "订单商品明细,每项含 id/order_id/item_id/item_code/item_name/plan_qty/actual_price/stock_id/order_line_no/inventory_type/sku_property/stock_unit/barcodes/image_url" + }, + { + "name": "source_table", + "type": "string", + "required": true, + "description": "订单命中分表:current(待处理表)或 dispatch(配送表)" + }, + { + "name": "batch", + "type": "object", + "required": false, + "description": "波次汇总(仅团购 isSandan=0 返回):wave_id(波次ID)、wave_no(波次号)、wave_type(波次类型,1=团购)、total_orders(波次订单总数)" } ], - "errors": [] + "errors": [ + { + "code": "400", + "message": "条码不能为空" + }, + { + "code": "400", + "message": "仓库ID不能为空" + }, + { + "code": "400", + "message": "未找到条码 [xxx] 对应的运单记录" + }, + { + "code": "400", + "message": "未在待处理或配送表中找到订单 [id=xxx, warehouse=xxx]" + }, + { + "code": "400", + "message": "不支持的业务类型: xxx" + } + ] }, { "method": "workbench.bindCamera", @@ -32535,10 +32721,10 @@ }, { "name": "where.waybillCode", - "type": "string", + "type": "string|string[]", "required": false, "source": "body.where", - "description": "运单号(模糊搜索)" + "description": "运单号筛选:字符串时为模糊搜索(LIKE '%值%',向后兼容);字符串数组时为精确匹配(Op.in,元素自动 trim 并过滤空值,空数组或全空值时不加该筛选条件)" }, { "name": "where.mainWaybillCode", @@ -33356,10 +33542,10 @@ }, { "name": "where.waybillCode", - "type": "string", + "type": "string|string[]", "required": false, "source": "body.where", - "description": "运单号(模糊搜索)" + "description": "运单号筛选:字符串时为模糊搜索(LIKE '%值%',向后兼容);字符串数组时为精确匹配(Op.in,元素自动 trim 并过滤空值,空数组或全空值时不加该筛选条件)" }, { "name": "where.mainWaybillCode", @@ -35530,6 +35716,178 @@ "message": "groupId 不能为空 / warehouseId 无效" } ] + }, + { + "method": "inbox.group.quickList", + "description": "群快速查询(下拉选择用,不分页):关键词同时模糊匹配群名称与外部群ID,按创建时间倒序返回轻量字段,软删除记录自动排除;支持双维度可选过滤:store_id(货主维度,对应 wms_inbox_group.store_id 列)与 warehouse_id(仓库维度,对应 wms_inbox_group.warehouse_id 列)均可选,可单独传、可同时传(AND 关系),也可都不传(返回所有仓库/货主的群),非法值分别报「store_id 无效」「warehouse_id 无效」。需 566 权限(inbox.group.quickList,已授权仓库组-主管/客服组-主管/生产组-主管/经理,超级管理员与仓库管理员持通配符自动拥有)", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(登录凭证,权限校验用)" + } + ], + "params": [ + { + "name": "store_id", + "type": "number|string", + "required": false, + "source": "body", + "description": "货主ID(可选,货主维度,对应 wms_inbox_group.store_id 列):传入时须为正整数,仅返回该货主的群;不传或为空时不加货主过滤(返回所有货主的群);与 warehouse_id 可单独传或同时传(AND 关系)" + }, + { + "name": "warehouse_id", + "type": "number|string", + "required": false, + "source": "body", + "description": "仓库ID(可选,仓库维度,对应 wms_inbox_group.warehouse_id 列):传入时须为正整数,仅返回该仓库的群;不传或为空时不加仓库过滤(返回所有仓库的群);与 store_id 可单独传或同时传(AND 关系)" + }, + { + "name": "keyword", + "type": "string", + "required": false, + "source": "body", + "description": "关键词,模糊匹配 group_name(群名称)与 group_id(外部群ID)" + }, + { + "name": "groupType", + "type": "string", + "required": false, + "source": "body", + "description": "群类型筛选:store(货主) / warehouse(仓库) / express(快递)" + }, + { + "name": "limit", + "type": "number", + "required": false, + "source": "body", + "description": "返回条数上限,默认20,最大100(无分页)" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "群快速列表(按创建时间倒序,无分页),每项含 id/group_id/group_name/group_type/sub_type/is_blocked", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "群记录主键ID(wms_inbox_group.id)" + }, + { + "name": "group_id", + "type": "string", + "required": false, + "description": "外部群ID(未绑定时为 null)" + }, + { + "name": "group_name", + "type": "string", + "required": true, + "description": "群名称" + }, + { + "name": "group_type", + "type": "string", + "required": false, + "description": "群类型:store / warehouse / express(未配置时为 null)" + }, + { + "name": "sub_type", + "type": "string", + "required": false, + "description": "群子类型(未配置时为 null)" + }, + { + "name": "is_blocked", + "type": "number", + "required": true, + "description": "是否屏蔽:1=屏蔽 0=正常" + } + ] + } + ], + "errors": [ + { + "code": "400", + "message": "store_id 无效 / warehouse_id 无效" + } + ] + }, + { + "method": "inbox.group.members", + "description": "查询一个或多个群的成员列表(下拉选择用,多群聚合):先按内部主键ID数组+仓库批量校验群存在(软删除自动排除),再聚合所有群的外部群ID(去重、剔除空值),按外部群ID集合在消息表中聚合去重成员(每个 user_id 取最新一条消息的 user_name),关键词在聚合结果上过滤,最后截断到 limit 条;所有外部群ID为空时返回空列表。多群共享同一聚合池(最多取最近 500 条消息,更早消息中的成员不会出现在结果中);user_id 为 NULL/空串的消息被排除。warehouseId 由服务端从登录上下文自动注入。需 567 权限(inbox.group.members,已授权仓库组-主管/客服组-主管/生产组-主管/经理,超级管理员与仓库管理员持通配符自动拥有)", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(从中解析 warehouseId 仓库上下文)" + } + ], + "params": [ + { + "name": "groupIds", + "type": "array", + "required": true, + "source": "body", + "description": "群记录主键ID数组(wms_inbox_group.id,必填,非空数组,每个元素为正整数,支持数字或可解析数字字符串)" + }, + { + "name": "keyword", + "type": "string", + "required": false, + "source": "body", + "description": "关键词,模糊匹配 user_name(用户名)与 user_id(用户ID),对聚合结果做小写包含过滤" + }, + { + "name": "limit", + "type": "number", + "required": false, + "source": "body", + "description": "返回条数上限,默认20,最大100(无分页)" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "群成员列表(多群聚合去重,无分页),每项含 user_id/user_name;所有群外部群ID为空时返回空列表", + "children": [ + { + "name": "user_id", + "type": "string", + "required": true, + "description": "成员用户ID(外部IM用户ID,跨群去重)" + }, + { + "name": "user_name", + "type": "string", + "required": true, + "description": "成员用户名(该用户最新一条消息的 user_name,无则为空字符串)" + } + ] + } + ], + "errors": [ + { + "code": "400", + "message": "groupIds 无效 / warehouseId 无效" + }, + { + "code": "500", + "message": "群不存在或无权限操作" + } + ] } ] }, @@ -37946,6 +38304,179 @@ "message": "服务器内部错误" } ] + }, + { + "method": "returnUnpack.export", + "description": "提交退回拆包导出任务(异步)。入参 where/sort 语义与 returnUnpack.list 一致;warehouse_id 由服务端从 ctx.user.store_id 注入,禁止前端传入。提交后立即返回 task_id,后台异步生成双 Sheet Excel(Sheet1「正常退回运单号列表」+ Sheet2「明细表」)并上传,导出进度/下载请通过 returnUnpack.exportTaskProgress 查询。数据来源 wms_return_unpack 主表 + wms_return_unpack_detail 明细表;货主名取自 wms_store.company_name,快递类型取自 wms_order_express.logistics_name;颜色列取自明细 product_snapshot.sku_property 中「颜色:xxx」片段(兜底 spec),无颜色信息为空;全量分页拉取,无行数上限;Sheet1 不加 status 过滤(如需只导特定状态由调用方传 where.status)。任务缓存 Redis TTL 30 分钟;状态口径 submitted → running → 数据拉取(10~30) → 明细拉取(30~50) → Excel(55~90) → 上传(92) → success(100),失败 failed + error。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "查询条件,语义与 returnUnpack.list 的 where 一致(支持 {operator,value,type} 标准结构或直接值;字段含 unpack_no/waybill_code 模糊、unpack_date/start_time/end_time/created_at/updated_at 范围、status/detail_status/store_id/order_express_id/order_id/unpacker_id/return_received_id 等值、has_video/video_enable 等);禁止传入 warehouse_id/warehouseId(服务端注入);不传 status 时不过滤状态" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数,语义与 returnUnpack.list 的 sort 一致:sortField 白名单 id/created_at/updated_at/unpack_date/start_time/end_time/unpack_no/waybill_code,sortOrder asc/desc,默认 created_at desc" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "任务 ID(后端生成,格式 return_unpack_export_{warehouseId}_{timestamp}_{random})" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态,枚举:submitted/running/success/failed/not_found(提交成功时为 submitted)" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "当前进度百分比(0-100),提交时返回 0" + }, + { + "name": "current_count", + "type": "number", + "required": true, + "description": "当前已处理记录数(拆包单条数)" + }, + { + "name": "total_count", + "type": "number", + "required": true, + "description": "总记录数(若有)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务提示信息" + }, + { + "name": "result", + "type": "object", + "required": true, + "description": "任务执行结果(提交时为 null;后台完成后为上传信息对象,含 filename/url/fileKey/cdnUrl/cosUrl/current_count/total_count/total_details/sheet_count)" + }, + { + "name": "error", + "type": "string", + "required": true, + "description": "失败时的错误信息(可选,非失败时为空字符串)" + }, + { + "name": "update_time", + "type": "number", + "required": true, + "description": "任务更新时间(Unix 毫秒时间戳)" + } + ], + "errors": [ + { + "code": "400", + "message": "参数格式不正确或 where 条件非法" + }, + { + "code": "500", + "message": "导出任务提交失败" + } + ] + }, + { + "method": "returnUnpack.exportTaskProgress", + "description": "按 task_id 查询退回拆包导出任务进度,返回 task_id、status、progress、current_count、total_count、message、result、error、download_url、update_time;上传完成后 download_url 返回下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);任务缓存 Redis TTL 30 分钟,task_id 缺失或缓存未命中时 status=not_found(正常响应,非报错)。状态口径 submitted → running → 数据拉取(10~30) → 明细拉取(30~50) → Excel(55~90) → 上传(92) → success(100),失败 failed + error。免权限免日志口径与 order.exportTaskProgress 一致。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "task_id / taskId", + "type": "string", + "required": true, + "source": "body|query", + "description": "任务 ID,兼容 task_id(下划线)与 taskId(驼峰)两种写法" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "任务 ID(task_id 缺失时为回显的空字符串,status=not_found)" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/failed/not_found" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "进度百分比(0-100)" + }, + { + "name": "current_count", + "type": "number", + "required": true, + "description": "当前已处理记录数(拆包单条数)" + }, + { + "name": "total_count", + "type": "number", + "required": true, + "description": "总记录数" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务提示信息" + }, + { + "name": "result", + "type": "object", + "required": true, + "description": "任务执行结果对象(完成后含 filename/url/fileKey/cdnUrl/cosUrl 等;未完成或 not_found 时为 null)" + }, + { + "name": "error", + "type": "string", + "required": true, + "description": "失败时的错误信息(可选,非失败时为空字符串)" + }, + { + "name": "download_url", + "type": "string", + "required": true, + "description": "任务完成后下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);未完成或不存在时为空字符串" + }, + { + "name": "update_time", + "type": "number", + "required": true, + "description": "最近一次状态更新时间(Unix 毫秒时间戳)" + } + ], + "errors": [ + { + "code": "500", + "message": "查询失败或内部错误" + } + ] } ] }, @@ -38304,6 +38835,1646 @@ ] } ] + }, + { + "groupName": "通用报表模块", + "module": "report", + "list": [ + { + "method": "report.generate", + "description": "提交报表导出异步任务(手动导出):按报表定义ID读取 wms_report_definition(is_enabled=1)配置,经注册类型对应的内置查询器(type=stockFlow 等)取数,并按类型硬编码字段规格(app/lib/report/render.js renderSheetByType)渲染 Excel 上传。立即返回任务受理信息(task_id/status=submitted),后台异步执行(执行中的错误体现在任务进度 error 字段),完成后可通过 report.generateTaskProgress 轮询进度并获取下载链接。warehouse_id 由服务端从登录上下文(ctx.user.store_id)自动注入,前端无需传递。仅登录即可调用(免权限:systemInit 声明 generate/generateTaskProgress/meta 免权限;generate 不写审计日志)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "report_id", + "type": "number", + "required": false, + "source": "body", + "description": "报表定义ID(必填,与 reportId 二选一;均传时优先 reportId)。须为 wms_report_definition 中已启用(is_enabled=1)的报表定义" + }, + { + "name": "reportId", + "type": "number", + "required": false, + "source": "body", + "description": "报表定义ID驼峰别名(兼容,优先级高于 report_id)" + }, + { + "name": "store_id", + "type": "number", + "required": false, + "source": "body", + "description": "货主ID(可选,货主维度报表时传入;>0 生效,<=0 视为不按货主过滤)" + }, + { + "name": "storeId", + "type": "number", + "required": false, + "source": "body", + "description": "货主ID驼峰别名(兼容,优先级高于 store_id)" + }, + { + "name": "params", + "type": "object", + "required": false, + "source": "body", + "description": "查询器业务参数(透传给内置查询器,如 bizDate/dayCount/cutoverHour)" + }, + { + "name": "params.bizDate", + "type": "string", + "required": false, + "source": "body", + "description": "数据日期(YYYY-MM-DD),用于导出文件名 file_name 模板的 {date} 占位;缺省取服务器当天" + }, + { + "name": "params.dayCount", + "type": "number", + "required": false, + "source": "body", + "description": "窗口数量覆盖(stockFlow 查询器经 resolveWindowConfig 解析,缺省 7,<=0 视为 7)" + }, + { + "name": "params.cutoverHour", + "type": "number", + "required": false, + "source": "body", + "description": "切点小时覆盖(缺省 7,钳制到 0-23)" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "导出任务ID(report_generate_ 前缀)" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/failed。受理时恒为 submitted,最终状态经 report.generateTaskProgress 查询" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "任务进度百分比(0-100)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务状态说明(受理时为「导出任务已提交」)" + }, + { + "name": "result", + "type": "object|null", + "required": true, + "description": "任务结果对象;导出成功后为 { fileKey, url, filename, size },未完成或失败时为 null" + }, + { + "name": "error", + "type": "string", + "required": true, + "description": "失败时的错误信息;成功时为空字符串" + }, + { + "name": "update_time", + "type": "number", + "required": true, + "description": "任务状态更新时间(毫秒时间戳)" + } + ], + "errors": [ + { + "code": 0, + "message": "报表ID report_id 必须为正整数" + } + ] + }, + { + "method": "report.generateTaskProgress", + "description": "查询报表导出任务进度与结果:按 task_id 读取任务缓存(缓存 TTL 1800 秒)。status 可能值:submitted/running/success/failed/not_found;任务成功后 download_url 返回报表文件下载链接。仅登录即可调用(免权限)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "task_id", + "type": "string", + "required": false, + "source": "body", + "description": "导出任务ID(下划线写法,与 taskId 二选一)" + }, + { + "name": "taskId", + "type": "string", + "required": false, + "source": "body", + "description": "导出任务ID(驼峰写法,兼容别名)" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "导出任务ID;未传入时为空字符串" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/failed/not_found(任务不存在时)" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "任务进度百分比(0-100);not_found 时为 0" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务状态说明" + }, + { + "name": "result", + "type": "object|null", + "required": true, + "description": "任务结果对象;导出成功后为 { fileKey, url, filename, size },未完成或失败时为 null" + }, + { + "name": "error", + "type": "string", + "required": true, + "description": "失败时的错误信息;成功时为空字符串" + }, + { + "name": "download_url", + "type": "string", + "required": true, + "description": "任务成功后返回的下载链接(取 result.url/cndUrl/cosUrl/fileKey 兜底);未完成或失败时为空字符串" + }, + { + "name": "update_time", + "type": "number", + "required": true, + "description": "任务状态更新时间(毫秒时间戳)" + } + ], + "errors": [] + }, + { + "method": "report.deliveryPlan.save", + "description": "新增/更新货主报表投递计划(货主 store_id + 报表定义ID report_id 唯一,存在则更新):先校验报表定义存在且启用(wms_report_definition.is_enabled=1),schedule_times 自动去重并按升序排序,channel 仅支持 inbox(默认 inbox,wecom/link 已弃用,非法渠道报错;历史 wecom/link 计划在投递时按 inbox 兜底执行),late_grace_minutes 夹取到 0-1440。可选计划名称 name(仅展示字段,不参与幂等/关联逻辑;未传不覆盖,null/空串/全空白清空,非空 trim 后 ≤100 字符,超长报错)。inbox 推送失败自动经 inbox.message.retry 立即重推一次,重推仍失败进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s)。可选文本通知配置:notify_template(≤500,标签白名单 {time}/{url}/{report_name}/{biz_date},未知标签报错)、notify_group_ids(wms_inbox_group.id,正整数去重 ≤20,保存时校验存在性且排除软删)、notify_member_ids(外部 IM 用户 ID,非空字符串去重 ≤100);三者仅在入参存在时生效(未传保持原值,不传行为与旧版一致)。需授权接口(管理类操作,systemInit 未声明免权限,仅通配符角色或已授权角色可用)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "store_id", + "type": "number", + "required": true, + "source": "body", + "description": "货主ID(必填,正整数;<=0 报错)" + }, + { + "name": "report_id", + "type": "number", + "required": false, + "source": "body", + "description": "报表定义ID(必填,与 reportId 二选一;均传时优先 reportId)。须为已启用(is_enabled=1)的报表定义" + }, + { + "name": "reportId", + "type": "number", + "required": false, + "source": "body", + "description": "报表定义ID驼峰别名(兼容,优先级高于 report_id)" + }, + { + "name": "schedule_times", + "type": "array", + "required": true, + "source": "body", + "description": "每日投递时间点数组(HH:mm 24 小时制,非空;自动去重并按升序排序;支持 JSON 字符串数组)" + }, + { + "name": "channel", + "type": "string", + "required": false, + "source": "body", + "description": "投递渠道(可选):仅支持 inbox,默认 inbox;wecom/link 已弃用,传入非法渠道报错「投递渠道仅支持 inbox: 」;历史 wecom/link 计划在投递时按 inbox 兜底执行", + "list": [ + { + "value": "inbox", + "name": "站内信" + } + ] + }, + { + "name": "late_grace_minutes", + "type": "number", + "required": false, + "source": "body", + "description": "补投宽限分钟(0-1440),默认 60;越界值夹取到 0-1440" + }, + { + "name": "name", + "type": "string|null", + "required": false, + "source": "body", + "description": "计划名称(可选,仅展示字段,不参与幂等/关联逻辑)。未传不覆盖既有值;null/空串/全空白归一化为 null(显式清空);非空 trim 后最长 100 字符,超长报错「计划名称 name 长度不能超过 100 字符」" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注(最长 500 字符,超出截断)" + }, + { + "name": "notify_template", + "type": "string", + "required": false, + "source": "body", + "description": "文本通知模板(可选,最长 500 字符,超出报错)。支持标签 {time}/{url}/{report_name}/{biz_date},含白名单外标签时报错并列出非法标签;空值视为未启用(清空配置);仅入参存在时生效,未传不修改既有配置" + }, + { + "name": "notify_group_ids", + "type": "array", + "required": false, + "source": "body", + "description": "通知群ID数组(可选,wms_inbox_group.id;正整数自动去重并升序,最多 20 个;保存时校验存在性,软删已删除的群报错并列出缺失 ID,被屏蔽的群仍可选中;支持 JSON 字符串数组;空数组视为不选择群)" + }, + { + "name": "notify_member_ids", + "type": "array", + "required": false, + "source": "body", + "description": "通知成员ID数组(可选,外部 IM 用户 ID;非空字符串自动去重,最多 100 个;推送时 user_id 支持数组整体透传不循环拆发;支持 JSON 字符串数组;空数组视为不选择成员)" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "投递计划ID" + }, + { + "name": "store_id", + "type": "number", + "required": true, + "description": "货主ID" + }, + { + "name": "report_definition_id", + "type": "number", + "required": true, + "description": "报表定义ID(wms_report_definition.id)" + }, + { + "name": "schedule_times", + "type": "array", + "required": true, + "description": "每日投递时间点数组(HH:mm,去重升序)" + }, + { + "name": "channel", + "type": "string", + "required": true, + "description": "投递渠道:inbox(渠道已收敛,仅支持 inbox)" + }, + { + "name": "enabled", + "type": "number", + "required": true, + "description": "是否启用:0=停用 1=启用" + }, + { + "name": "late_grace_minutes", + "type": "number", + "required": true, + "description": "补投宽限分钟(0-1440)" + }, + { + "name": "name", + "type": "string", + "required": true, + "description": "计划名称(未设置时为空字符串)" + }, + { + "name": "remark", + "type": "string", + "required": true, + "description": "备注" + }, + { + "name": "notify_template", + "type": "string", + "required": true, + "description": "文本通知模板(未配置时为空字符串)" + }, + { + "name": "notify_group_ids", + "type": "array|null", + "required": true, + "description": "通知群ID数组(内部 wms_inbox_group.id,去重升序;未选择时 null)" + }, + { + "name": "notify_member_ids", + "type": "array|null", + "required": true, + "description": "通知成员ID数组(外部 IM 用户 ID,去重;未选择时 null)" + }, + { + "name": "created_at", + "type": "string", + "required": true, + "description": "创建时间" + }, + { + "name": "updated_at", + "type": "string", + "required": true, + "description": "更新时间" + } + ], + "errors": [ + { + "code": 500, + "message": "货主ID store_id 不能为空" + }, + { + "code": 500, + "message": "报表ID report_id 必须为正整数" + }, + { + "code": 500, + "message": "报表定义不存在或已停用: id=" + }, + { + "code": 500, + "message": "schedule_times 必须为 HH:mm 字符串数组且不能为空" + }, + { + "code": 500, + "message": "schedule_times 含非法时间点(需 HH:mm 24 小时制):