WMS_MAIN/docs/report-config-guide.md
liufumingren 9af7dcf8fb feat(storeWarehouse): 签约关系接口配置按货主开放接口落库且回调地址统一取配置
- storeWarehouse.store.saveApiConfig:新增 resolveContractApiInterfaceType,
  interface_type_id=3(OPEN_API_WAREHOUSE 仓库开放接口)自动映射为 2(OPEN_API 货主开放接口)落库,
  不再要求当前主体为仓库(货主可维护自身签约关系下的接口配置)
- callback_url 不再取入参(含 callbackUrl 别名),统一写入 config.openapi.defaultCallbackUrl(新增配置项,默认空)
- storeWarehouse.store.listApiConfig:interface_type_id 过滤同步映射(传 3 按 2 查询)
- 文档:methods/system.json 升级 0.3.350、methods/changes/system.json 变更记录、docs/openapi-callback-events.md 回调地址来源说明
- 测试:saveApiConfig 新增 4 条用例(3→2 落库、忽略入参回调地址、默认值未配置、货主主体可保存、缺失类型 404),listApiConfig 新增 1 条过滤映射用例

同时提交工作区其余在制品改动:
- waybill:移除 wms_order_express_trace 模型并新增 drop 迁移,轨迹查询/取号/打印链路调整
- order:订单 SN 编码(order_item_sn / order_item_sn_log / sn_code_rule、has_sn_item 回填迁移),pendingOrder/recheckOrder/wave/base 调整
- express_platform、order_async、order_export、order_storage_allocation、storage.report、stock_store 配套修复
- lib:新增 jd_client,调整 qimen_client、callback_functions 及配套测试

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-14 17:14:04 +08:00

32 KiB
Raw Permalink Blame History

配置驱动通用报表与货主定时投递 — 配置结构说明

本文档与代码实现保持一致(模型:app/model/report_definition.js;引擎:app/service/systems/report.js; 渲染翻译层:app/lib/report/render.js;内置查询器:app/service/systems/report/queries/*; 投递编排:app/service/systems/reportDelivery.js)。 接口定义见 methods/system.json 分组「通用报表模块」(module=report)。

破坏性变更(2026-08-30 模型重构):报表定义由 code 编码改为主键 id 关联,接口入参 report_code 全部替换为 report_id(=报表定义ID,兼容 reportId 驼峰);code/scope/description 与 output_config/source_config/sheet_config 三段 JSON 配置字段已随模型删除, 列渲染由注册类型硬编码字段规格自动完成(无自定义列配置)。

1. 总览

报表采用「配置驱动」:wms_report_definition 一行配置 = 一个报表(type + fields 极简配置), 大部分新报表场景只需加配置行或新增内置查询器类型,免发版。

模型 app/model/report_definition.js 关键字段:

列 类型 说明
id BIGINT UNSIGNED 主键,报表定义ID(接口入参 report_id,唯一性由主键承担)
name STRING(100) 报表名称
type STRING(50) 报表类型(内置查询器注册 key,如 stockFlow)
file_name STRING(200) 导出文件名模板(支持 {date} 数据日期、{time} 生成时刻 HHmmss、{datetime} 数据日期_生成时刻、{timestamp} 毫秒时间戳,如 7日出入库_{date}.xlsx、库内拦截_{date}_{time}.xlsx)
fields JSON 勾选的字段 key 数组(该类型注册字段的子集;列头/合并/样式/格式化由类型硬编码字段规格决定)
is_enabled TINYINT(1) 是否启用:0=停用 1=启用(导出只读 is_enabled=1 的定义)
remark STRING(500) 备注
created_at/updated_at/deleted_at DATE 时间戳与软删标记

生成链路:

report.generate(method 层,异步任务,入参 report_id)
  -> systems/report.js getDefinition(读定义,is_enabled=1,软删自动排除)
  -> resolveTypeEntry / resolveQuerier(type 查注册表)
  -> 内置查询器取数 {windows, rows, meta}
  -> lib/report/render.js renderSheetByType(按类型硬编码字段规格渲染)
  -> excel.generateAndUpload(产物 fileKey/url/filename/size)

2. 注册类型(report.definition.typeList / wms_report_definition.type)

查询器注册表 app/service/systems/report/queries/index.js,type 即注册方法 key; 查询器签名统一:async ({ ctx, storeId, warehouseId, params }) => ({ windows, rows, meta }), 每个查询器模块挂载静态字段清单 fields 与缺省窗口参数 defaultWindow。

当前注册类型:

key 标题 说明
stockFlow 库存变化以及补货报表 按日窗口聚合出入库流水与正品库存,输出每 SKU 产品名称/条码/外部编码/每日出入库/待处理订单占用数/可用库存/7日总出库数量/推荐采购量与是否触发预警
interceptOrder 库内确定拦截订单明细 以配送表 dispath_time(订单迁移进配送表的时间)为时间基准,统计昨日自然日库内确定拦截订单(intercept_status='intercepted_at_warehouse'),按商品明细展开(一个商品一行),列与订单导出含明细模式(order.export export_mode=item)一致、仅不含「商品图片」列,并附 2 列拦截时间(通知拦截时间/库内确定拦截时间)

stockFlow 缺省窗口参数:window = { dayCount: 7, cutoverHour: 7 }。

interceptOrder 缺省窗口参数:window = { dayCount: 1, cutoverHour: 0 }(单个自然日、 00:00 切日)。 该类型不使用 params.dayCount/params.cutoverHour 入参,统计日由 params.bizDate 控制(缺省=昨日)。

stockFlow 全量字段清单(9 组列,顺序固定,report.definition.typeList 直接返回该规格):

key label type computed asText 说明
item_name 产品名称 string - -
barcode 条码 string - ✅ 文本单元格落地,防科学计数法
item_code 外部编码 string - ✅ 文本单元格落地,防科学计数法;key 复用旧「商品编码」列(label 变更,兼容既有定义 fields 勾选)
daily 每日出入库 array - - children:ck(出库数,number)/ rk(入库数,number)
pending_occupy 待处理订单占用数 number - - 口径:wms_stock_warehouse.locked_quantity(仓库商品主表锁定数量,非 wms_storage 聚合口径)
available 可用库存 number - - wms_storage 正品库位明细 SUM(available_quantity)
ck_total 7日总出库数量 number - - 窗口内 OUTBOUND 流水变更数量 quantity 合计
suggest 推荐采购量 number ✅ - 预计算字段(formatters 注册表,低库存补偿口径见 2.1 第 8 条)
warn 是否触发预警 boolean ✅ - 预计算字段

外部编码(item_code)取值口径:优先 wms_stock_store.item_code(按 stock_id 关联 wms_stock_warehouse.id,同 stock_id 多条时按 id 升序取第一条非空 item_code,stock_id 为空的记录不参与匹配)→ 回落 wms_stock_warehouse.item_code → 均无则留空。

已移除旧列(不再导出,共 8 个):stock_id、rk_total、total、pending、locked、ck_avg、rk_avg、stock_days; 行内仍计算 rk_total/日均/预计可售天数等字段供 suggest/warn 判定与测试复核,但不进入导出列清单。

2.1 stockFlow 口径与假设(8 条,供测试复核)

  1. 窗口:dayCount 个 [D cutoverHour:00, D+1 cutoverHour:00) 本地时区半开区间 (缺省 7 天、07:00 切点,可由请求 params.dayCount/cutoverHour 覆盖)。
  2. 流水:wms_stock_transaction,transaction_type IN (INBOUND, OUTBOUND),显式排除 LOCK/UNLOCK, 按 created_at 落入窗口,INBOUND→rk、OUTBOUND→ck(变更数量 quantity 即出入库数)。
  3. 可用库存:wms_storage(库位级正品明细),inventory_type='ZP'、is_enabled=1、未删除, SUM(available_quantity)=可用库存(行内 available 列);SUM(quantity)/SUM(locked_quantity)/ 待出库存等仅保留为行内内部计算字段,已不在导出列清单中。
  4. 条码:wms_stock_barcodes 多值取字典序第一条(表内无主条码标志,等价旧 PHP MIN(barcode) 语义)。
  5. 外部编码:优先 wms_stock_store.item_code(按 stock_id 关联 wms_stock_warehouse.id,同 stock_id 多条时 按 id 升序取第一条非空 item_code,stock_id 为空的记录不参与匹配),未匹配则回落 wms_stock_warehouse.item_code,再无则留空。
  6. 待处理订单占用数:取 wms_stock_warehouse.locked_quantity(仓库商品主表锁定数量, 不是 wms_storage 聚合的 locked_quantity 口径)。
  7. 行范围:窗口内有流水或有正品库存的 SKU 均出列,按 item_code 升序、stock_id 升序。
  8. suggest/warn:由 formatters 注册表计算。低库存补偿:available < 20 且 rk_total < 20 时 推荐采购量补偿到不低于 30;预警判定由 warnOf(ck_total, available, rk_total) 计算。 行内仍计算 rk_total/日均/预计可售天数等字段供判定与复核,但不进入导出列清单。

2.2 interceptOrder 口径与假设(供测试复核)

  1. 数据源:配送表 wms_order_delivery_{warehouse_id}_dispatch(订单出库迁移后的表位; 查询器经 orderExport.getOrderModelByTableType('dispatch', warehouseId) 取动态模型)。
  2. 拦截状态:仅取 intercept_status = 'intercepted_at_warehouse'(库内确定拦截;由 order.recheckOrder.confirmIntercept 与 intercept_auto_confirm 写入,同时 step=4、outbound_status=fin)。 注意该枚举没有 intercepted 值,历史遗留值不参与统计。
  3. 时间基准:dispath_time(配送表独有列,= 订单迁移进配送表的时刻,由 orderDeliveryMigration.buildDispatchRow 写入 new Date();2026-09-07 迁移 20260907120000 上线, 仅 dispatch 分表有该列,当前分表/历史表/委外表无此列)。
  4. 统计区间:默认「昨日自然日」[昨日 00:00:00.000, 今日 00:00:00.000)(本地时区半开区间, 与 stockFlow 的 07:00 切日口径不同);params.bizDate(YYYY-MM-DD,兼容 biz_date) 传入且为真实存在的日期时,按该日整天统计,缺省/非法一律回落昨日自然日。 统计日不得晚于昨天:传今天/未来日期一律回落昨日(上界恒为今日 00:00:00,不含), 保证「今天生成/投递的报表不含今天的数据」——当天新迁入配送表的拦截单只会出现在次日报表; 比昨天更早的显式日期仍被尊重(补数场景)。
  5. 明细粒度与取值:按订单 ID 升序分页(单页 1000 单,循环至不足一页)复用 orderExport.buildOrderExportPage({ mode: 'item' }) → mapOrderExportRow(item),因此状态中文翻译、 货主备注(wms_store_warehouse.store_remask)、仓库商品名/条码回落、运单汇总(多运单逗号拼接、 主/子单号业务类型、包材编码/名称、称重汇总)、收件人字段等与订单导出逐格一致; 行再按注册字段裁剪(丢弃 item_image 等未注册键,缺失值回落空字符串)。
  6. 无商品明细的订单:输出一行订单级数据(运单字段汇总、商品列为空),与订单导出 item 模式一致。
  7. 主维度:warehouseId 必填(配送表按仓库分表;<=0 抛「interceptOrder 查询器缺少仓库维度 warehouseId」); storeId > 0 时追加 store_id 过滤(货主维度报表/定时投递),否则仓库维度全量。
  8. 行数保护与 meta:明细行数达 MAX_EXPORT_ROWS = 200000 时截断并打 warn(meta.truncated = true); meta 返回 bizDate/startTime/endTime/warehouseId/storeId/interceptStatus/timeField/orderCount/rowCount/truncated。
  9. 波次序号:wave_index 沿用订单导出同款 attachOrderWaveIndex(仓库ID取 ctx.user.store_id), 定时投递(无 ctx.user)场景该列降级为 0,仓库主体手工导出为真实序号。
  10. 附加列(订单导出 item 模式无此 3 列):
    • source_order_codes(平台交易单号)= 配送表 source_order_codes 原值 (mapOrderExportRow(item) 不输出该列,由查询器回查补充,列位置紧跟「外部单号」);
    • intercept_notice_time(通知拦截时间)= 配送表 intercept_time。该字段自 2026-09-10 起 语义统一为「最近一次发起拦截的通知时刻」(见 app/lib/intercept_time.js):首次发起时写入、 重复发起不覆盖、库内拦截确认/退回入库均不覆盖、取消/解除拦截置空; 若该列为空则回落 wms_operation_log 中 operation_code='ORDER_INTERCEPT_REQUEST' 的最早记录时间 (历史数据兼容,查询按 business_type='order' + business_id=订单ID + warehouse_id=当前仓库 三重过滤,订单 ID 按仓库发号必须同仓隔离);
    • intercept_confirm_time(库内确定拦截时间)= 配送表 dispath_time (订单迁移进配送表的时间;库内确定拦截后订单会走 outbound_status=fin 的自动迁移,故等价于库内确定拦截时刻。 不再使用 intercept_time,因为确认时不再覆盖该字段);
    • 两列均格式化为 YYYY-MM-DD HH:mm:ss(空值输出空字符串); meta.noticeTimeFilledCount / meta.confirmTimeFilledCount 返回两列的有值行数,便于核对覆盖率。

字段清单(49 列,顺序固定,全为 string 静态列;report.definition.typeList 直接返回该规格):

key label
id 订单ID
delivery_order_code 订单号
external_order_code 外部单号
source_order_codes 平台交易单号
status 订单状态
wave_no 波次号
wave_index 波次序号
store_id 货主
sys_platform_name 平台
create_channel 来源
shop_nick 店铺昵称
receiver_name 收件人
receiver_mobile 收件人电话
receiver_province 省
receiver_city 市
receiver_district 区
receiver_town 镇
receiver_detail 详细地址
item_name 仓库商品名称
item_barcode 商品条码
item_quantity 数量
logistics_name 物流公司
waybill_code 运单号
business_type 业务类型
logistics_interface_name 运单接口
package_material_id 包材ID
package_material_code 包材编码
package_material_name 包材名称
waybill_allocated_at 分配时间
items_count 订单商品总类数
items_total 订单商品总数
items_weight 商品重量
weighing_weight 称重重量(g)
total_amount 订单金额
got_amount 实收金额
create_at 创建时间
pay_time 支付时间
delivery_time 发货时间
outbound_status 出库状态
inspection_status 复核状态
recheck_status 复核完成状态
post_status 配货状态
pack_status 打包状态
remark 备注
buyer_message 买家留言
seller_message 卖家留言
archive_time 归档时间
intercept_notice_time 通知拦截时间
intercept_confirm_time 库内确定拦截时间

与订单导出 item 模式的差异:不含 item_image(商品图片)列,另附加 3 列—— source_order_codes(平台交易单号,位置紧跟「外部单号」)、intercept_notice_time(通知拦截时间)、 intercept_confirm_time(库内确定拦截时间),订单导出无这 3 列; 另外订单导出 item 模式新增了 sn_quantity(SN码数量,明细中启用序列号管理商品的 plan_qty)与 sn_codes(SN码,该商品行复核时登记的 SN 列表),waybill 模式新增 sn_codes_summary(SN码汇总,订单级),本报表未启用这些列。配置示例:

// report.definition.save(新增拦截明细报表)
{
  "name": "库内确定拦截订单明细",
  "type": "interceptOrder",
  "file_name": "库内确定拦截订单明细_{date}.xlsx",
  "fields": ["id", "delivery_order_code", "external_order_code", "waybill_code", "item_name", "item_quantity", "create_at"],
  "remark": "每日导出昨日库内确定拦截订单明细"
}

注:fields 必须为该类型注册字段的子集(新增时必填,且不能为空数组——渲染层按勾选字段生成列, 空数组会得到无列的空表;需全部 49 列时请显式列出全部 key),完整可选 key 见上文清单。

3. 渲染规则(renderSheetByType,无 sheet_config)

列定义不再由 sheet_config.columns 配置,而由注册类型字段规格硬编码自动生成 (app/lib/report/render.js renderSheetByType,按定义勾选字段顺序渲染):

字段类型 渲染规则
string 静态列(表头=label);字段规格 asText: true 时整列落地为 Excel 文本单元格
number 静态列,统一 zeroToDash(0 / '0' / null / '' 显示 -)
boolean 静态列,统一 yesNo(真→'是'、假→'否',PHP 布尔语义)
array 窗口展开列:per=窗口数(缺省 7)、pair=children 字段键;表头第 1 行每窗口输出窗口开始日期 'Y/n/j'(无前导零,如 2026/8/23),pair 数>1 时每窗口表头横向合并(如 D1:E1 … P1:Q1);表头第 2 行按 children label 填充;子字段 number 统一 zeroToDash
  • 存在展开列时启用两行表头,其余列表头纵向合并(如 A1:A2),合并区域自动生成,无需配置。
  • asText(文本单元格):由类型字段规格硬编码(如 item_code/barcode 声明 asText: true), 渲染层 renderSheetByType 将声明 asText 的列收集为 textColumns(0 基列索引数组,未声明任何 asText 列时不输出该字段), 由 app/service/systems/excel.js 落地:ExcelJS 路径逐单元格 numFmt='@' 并把值转为字符串(原始对象除外), SheetJS 路径逐单元格 t:'s'、z:'@' 并把值字符串化。适用于条码、外部编码等长数字串 (防止被 Excel 按数值展示成科学计数法),无需再配合 textPrefix 的 ' 前缀 (textPrefix 格式化器保留注册仅向后兼容)。
  • sheet 名称为类型标题(如「库存变化以及补货报表」);columns 恒输出空数组 (数据以 AOA 二维数组形式输出,表头行内联在 rows 首位)。

4. 导出文件名(file_name)与上传目录(fileKey)

  • file_name 为文件名模板,占位符(本地时区,2026-09-10 扩充):
    • {date}:数据日期(请求 params.bizDate,缺省服务器当天,YYYY-MM-DD);
    • {time}:生成时刻 HHmmss(如 200745);
    • {datetime}:{date}_{time}(如 2026-09-09_200745);
    • {timestamp}:生成时刻毫秒时间戳。 同一天多次投递/手动导出同一报表时,文件名带生成时刻(如 interceptOrder_{date}_{time})可避免 COS 同名覆盖 (同名文件会被后一次写覆盖,且 CDN 可能仍回源旧内容)。
  • 缺省模板:<name>_<date>.xlsx;不以 .xlsx/.xls 结尾时自动补 .xlsx。
  • 上传目录(COS 文件 key)按「报表定义 + 货主/仓库」维度隔离(2026-08-31 修复「货主限制不符」缺陷: 修复前统一为 exports/report/<report_id>/,不同货主的报表文件会互相覆盖):
    • store_id 有效(>0):exports/report/<report_id>/store-<store_id>/;
    • store_id 缺省且 warehouse_id 有效(>0):exports/report/<report_id>/warehouse-<warehouse_id>/;
    • 两者均缺省:exports/report/<report_id>/common/(手动导出兼容兜底)。
  • 完整 COS key 由 app/service/systems/excel.js generateAndUpload 在上述目录后追加 {YYYYMMDD}/ 日期目录与文件名; report.generate 任务结果 result.fileKey / download_url 即该隔离 key。
  • 货主定时投递固定走 store-<store_id> 隔离(reportDelivery.processOne 必传货主并强校验); 手动导出未传 store_id 时按 warehouse-<warehouse_id>(登录上下文仓库)或 common 兜底。

5. 货主定时投递(wms_report_delivery_plan / wms_report_delivery_log)

  • 投递计划 wms_report_delivery_plan:store_id + report_definition_id 唯一(唯一索引 uk_store_report_definition, report_definition_id 即报表定义ID、接口入参 report_id);schedule_times(HH:mm 数组,去重升序)、 channel(仅支持 inbox,默认 inbox;wecom/link 已弃用,保存时传非法渠道报错「投递渠道仅支持 inbox: 」)、 late_grace_minutes(补投宽限 0-1440,默认 60)、name(计划名称,仅展示字段,≤100 字符,可空)、enabled。
  • 计划名称 name(2026-08-30 新增,仅展示字段,不参与 store_id + report_definition_id 幂等/关联逻辑): report.deliveryPlan.save 可选入参(未传不覆盖既有值;null/空串/全空白归一化为 null 显式清空; 非空 trim 后最长 100 字符,超长报错「计划名称 name 长度不能超过 100 字符」); save 成功响应与 report.deliveryPlan.list 列表项均返回 name(未设置时为空字符串)。
// report.deliveryPlan.save(name 可选)
{
  "store_id": 1001,
  "report_id": 1,
  "schedule_times": ["09:00", "17:30"],
  "name": "每日库存报表投递",
  "late_grace_minutes": 60
}
  • 渠道收敛兜底:历史计划残留的 wecom/link 渠道在投递时按 inbox 兜底执行(仅记录 warn 日志,不抛错,避免历史计划卡死)。
  • 迁移归一化:迁移 20260829170000 已把两表 channel 列默认值 wecom → inbox、comment 收敛, 存量 channel IN ('wecom','link') 行统一 UPDATE 为 inbox(模型 defaultValue: 'inbox' 同步); report.deliveryPlan.list / report.deliveryLog.list 响应 channel 恒为 inbox。
  • 投递记录 wms_report_delivery_log:状态机与 status 一致: pending → exporting → delivered / failed / cancelled;report_definition_id 关联报表定义ID, report_name 为投递时报表名称快照(审计回放,定义删除后仍可追溯)。
  • 调度(reportDelivery.dispatch,分钟级):按 HH:mm + 宽限窗口命中后, 对每个 (store_id, report_definition_id, biz_date, time_point) 幂等生成报表并投递(防重不防漏)。
  • 投递/通知幂等键含货主维度(2026-08-31 修复「货主限制不符」缺陷):inbox 投递消息 ext_id 为 report:{store_id}:{report_definition_id}:{biz_date}:{time_point},文本通知幂等键为 report:notify:{store_id}:{report_definition_id}:{biz_date}:{time_point}; 修复前不含 store_id,不同货主的投递/通知消息会互相复用、串扰。
  • 货主维度强校验(2026-08-31):processOne 对 store_id/report_definition_id 强校验, 任一无效直接抛错「投递计划维度非法(…),拒绝生成报表」,绝不生成跨货主报表。
  • 文件消息投递目标与群路由口径(2026-09-01 修复 G1 缺陷):报表文件消息(inbox 渠道) 只投递到计划配置的通知群 notify_group_ids,不再投递任意「货主默认群」; 未配置通知群的历史计划保持旧行为,回退投递到货主默认站内信群(group_type='store',按 id ASC 取最早一条)。 配置了群但全部不可达(不存在/已删除/被屏蔽/仓库不一致)时直接抛错「配置的通知群不可达…无法投递」 进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s),不再静默回退到未配置群。 投递与文本通知共用 resolveNotifyGroups 解析口径(过滤 is_blocked=1、软删、仓库维度一致)。
  • 失败自动重推:inbox 推送失败(success=false 或消息回写 push_status=3)时,立即复用 inbox.message.retry 重推一次(ext_id 幂等复用同一条消息记录,不重复写);重推仍失败进入 failed 退避重试:MAX_RETRY=3,退避 retry_count × 60s;重试扫描条件 status=failed 且 retry_count<3 且 next_retry_at<=now;卡在 exporting 超过 30 分钟视为陈旧可重扫。
  • biz_date 口径:正常投递为触发日 T-1;跨零点补投(时间点晚于当前时刻)为触发日 T-2, 与昨日正常投递口径一致,避免与次日正常投递撞幂等键。

5.1 文本通知模板与定向群/成员(notify_template / notify_group_ids / notify_member_ids)

投递计划可在投递完成后附带发送一条文本通知(与投递渠道独立,inbox 渠道投递后同样生效;未配置时行为与旧版完全一致)。 三个字段均为可选,仅在 report.deliveryPlan.save 入参存在时生效(更新时未传保持原值)。

5.1.1 notify_template(文本通知模板)

  • 最长 500 字符,超出报错;空值/未传视为未启用。
  • 标签白名单(仅以下 4 个标签会被渲染,其余 {xxx} 视为未知标签,保存时报错并列出非法标签):
标签 渲染内容
{time} 发送时间,格式 YYYY-MM-DD HH:mm
{url} 报表文件下载链接;链接为空时替换为兜底文案「文件生成中,稍后可在投递记录中查看」
{report_name} 报表名称
{biz_date} 数据日期 YYYY-MM-DD
  • 示例模板:【{report_name}】{biz_date} 数据报表已生成,下载:{url}(生成时间 {time})

5.1.2 notify_group_ids(通知群,定向内部群)

  • 元素为 wms_inbox_group.id(内部群 ID),正整数、自动去重并升序,最多 20 个。
  • 保存时校验存在性:软删(已删除)的群报错并列出缺失 ID;被屏蔽(is_blocked=1)的群仍可选中, 屏蔽属于发送时过滤维度。
  • 同时为报表文件消息的投递目标:计划配置了 notify_group_ids 时,文件消息(inbox 渠道) 仅逐群投递到这些配置群,不再投递任意「货主默认群」;未配置通知群的历史计划回退投递到 货主默认站内信群(group_type='store',取最早一条);配置的群全部不可达 (不存在/已删除/被屏蔽/仓库不一致)时投递抛错进入 failed 退避重试。
  • 发送时逐群推送(群维度协议字段 group_id/group_name 为单值),并再次过滤 is_blocked=1、软删、仓库维度不一致的群;此类群不发送且不进入投递记录快照。

5.1.3 notify_member_ids(通知成员,定向外部成员)

  • 元素为外部 IM 用户 ID,非空字符串、自动去重,最多 100 个。
  • 推送时 user_id 数组整体透传(目标侧协议支持 user_id 数组),不循环拆发; 选择群时成员数组随每个群推送携带,未选择群时单独做一次仅成员推送。

5.1.4 发送规则与投递记录快照

  • 未配置模板或未选择任何群/成员时不发送(投递行为不变)。
  • 发送时机:报表生成并完成渠道投递后(delivered 回写前),失败抛异常走失败退避重试 (MAX_RETRY=3,退避 retry_count × 60s)。
  • 发送结果快照 notify_targets 随投递记录落库并在 report.deliveryLog.list 返回:
{
  "group_ids": [1, 3],
  "member_ids": ["user-1001", "user-1002"],
  "notify_text": "【7日出入库数据】2026-08-28 数据报表已生成,下载:https://...(生成时间 2026-08-29 09:00)"
}
  • group_ids 为实际发送的群内部 ID 列表;member_ids 为实际发送的成员 ID 列表; notify_text 为标签替换后的最终文本;未发送文本通知时快照为 null。

6. 报表定义保存示例(report.definition.save)

{
  "name": "库存变化以及补货报表",
  "type": "stockFlow",
  "fileName": "库存变化_{date}.xlsx",
  "fields": ["item_name", "barcode", "item_code", "daily", "pending_occupy", "available", "ck_total", "suggest", "warn"],
  "is_enabled": 1,
  "remark": ""
}
  • type 必须命中注册表(当前 stockFlow、interceptOrder,未知报「未知的报表类型: 」); fields 必须为该类型注册字段子集(9 组列任意勾选,含非法 key 报可读错误并列出可用字段)。
  • file_name 兼容 fileName 驼峰写法(驼峰优先);新增必填 name/type/file_name/fields; 更新按 id upsert,未传字段不覆盖;软删记录命中时自动恢复。
  • 保存成功后响应即报表定义视图: { id, name, type, file_name, fields, is_enabled, remark, created_at, updated_at }。

7. report.definition.typeList(前端元数据接口)

7.1 用途

report.definition.typeList:免权限只读(仅登录),返回注册类型清单 [{ key, title, description, window, fields }],供前端报表设计器渲染「报表类型」选择与字段树。

实现:report.definition.typeList → app/service/systemMethods/report/definition.js → systems/report.js listRegisteredTypes。

鉴权/日志口径:report.definition.typeList 在 definition.js 的 systemInit 名单内 (_noNeedRight/_noNeedAuth/_noNeedLog='typeList':免权限 + 免鉴权 + 不写审计日志,仅登录; 同模块 save/list/delete 未声明免权限,仍需授权)。

历史:report.meta 已于 2026-08-31 移除(下线)。前端获取窗口参数 window.dayCount/cutoverHour 请用 report.definition.typeList;某报表定义勾选字段 请用 report.definition.list 响应中的 fields 数组(与 typeList 字段树 key 对照)。

7.2 请求示例

// report.definition.typeList(无必填参数)
{}

7.3 响应示例

// report.definition.typeList
{
  "flag": "success",
  "code": 1,
  "message": "ok",
  "list": [
    {
      "key": "stockFlow",
      "title": "库存变化以及补货报表",
      "description": "按日窗口聚合出入库流水与正品库存,……",
      "window": { "dayCount": 7, "cutoverHour": 7 },
      "fields": [
        { "key": "item_name", "label": "产品名称", "type": "string" },
        { "key": "barcode", "label": "条码", "type": "string", "asText": true },
        { "key": "item_code", "label": "外部编码", "type": "string", "asText": true },
        { "key": "daily", "label": "每日出入库", "type": "array", "children": [
          { "key": "ck", "label": "出库数", "type": "number" },
          { "key": "rk", "label": "入库数", "type": "number" }
        ]},
        { "key": "pending_occupy", "label": "待处理订单占用数", "type": "number" },
        { "key": "available", "label": "可用库存", "type": "number" },
        { "key": "ck_total", "label": "7日总出库数量", "type": "number" },
        { "key": "suggest", "label": "推荐采购量", "type": "number", "computed": true },
        { "key": "warn", "label": "是否触发预警", "type": "boolean", "computed": true }
      ]
    }
  ]
}

说明:list 按注册顺序返回全部注册类型(当前 stockFlow、interceptOrder),上例仅展开 stockFlow; interceptOrder 的 window 为 { "dayCount": 1, "cutoverHour": 0 },fields 为 46 个 type: "string" 静态列 (列清单与口径见 2.2 节)。

字段元素结构:{ key, label, type, computed?, asText?, children? }:

  • type:string / number / boolean / array;
  • computed: true:预计算字段(非原始表字段,如 suggest/warn);
  • asText: true:该列以文本单元格落地(由类型字段规格硬编码,如 item_code/barcode);
  • children:数组类型字段的子字段(如 daily 的 ck/rk)。

7.4 前端如何获取可用字段

  1. 调用 method=report.definition.typeList(POST /system,header 带 Authorization: Bearer <token> 与 platform) 获取全部注册类型与字段树(含窗口参数 window.dayCount/cutoverHour);
  2. 保存报表定义时按类型字段树勾选 fields(method=report.definition.save);
  3. 渲染/导出前用 report.definition.list 取该报表定义已勾选的 fields 数组(与 typeList 字段树 key 对照);
  4. 导出 sheet 的列由「勾选字段 × 类型硬编码规格」自动生成,前端无需下发任何列配置。

8. 报表定义管理接口(report.definition.save / list / delete)

管理侧维护 wms_report_definition 的 3 个接口,均需登录且需鉴权(isNeedAuth=true、isNeedLogin=true, POST /system,header 带 Authorization: Bearer <token> 与 platform)。

  • report.definition.save:按 id upsert(未传 id 新增),入参 { id?, name, type, file_name/fileName, fields, is_enabled?, remark? }; type 必须命中注册表、fields 必须为该类型注册字段子集(非法 key 报可读错误列出); 新增必填 name/type/file_name/fields;软删记录命中时自动恢复。
  • report.definition.list:where { name, type, is_enabled } + pagination + sort (sort 白名单 id/name/type/is_enabled/created_at/updated_at,默认 id DESC); 响应每行 { id, name, type, file_name, fields, is_enabled, remark, created_at, updated_at },软删自动排除。
  • report.definition.delete:入参 id;删除前按 report_definition_id 统计投递计划引用, 仅拦截「启用中」的计划(enabled=1,报「存在 N 个启用的投递计划引用该报表,请先停用计划」), 停用计划不阻断;重复删除同一 ID 幂等成功(deleted 恒为 1)。 实现:app/service/systemMethods/report/definition.js → app/service/systems/report.js 的 saveDefinition / listDefinitions / deleteDefinition。

鉴权口径:三个接口 systemInit 均未声明免权限(isNeedAuth=true),仅通配符角色 (超级管理员/仓库管理员)或已授权角色可用;本次仅文档同步,未扩任何角色授权 (权限缺口可用 npm run permission:sync:system-api -- --dry-run 预演)。