1) 报表导出列重构为 9 组列(产品名称/条码/外部编码/每日出入库/待处理订单占用数/可用库存/7日总出库数量/推荐采购量/是否触发预警),外部编码 stock_store 优先 fallback,新增 pending_occupy 取仓库主表锁定数量;2) 投递货主隔离修复(上传目录按货主/仓库隔离、投递与通知幂等键含 storeId、processOne 货主维度强校验);3) 文档与 methods 变更记录同步。
22 KiB
配置驱动通用报表与货主定时投递 — 配置结构说明
本文档与代码实现保持一致(模型:
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} 占位,如 7日出入库_{date}.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日总出库数量/推荐采购量与是否触发预警 |
stockFlow 缺省窗口参数:window = { dayCount: 7, cutoverHour: 7 }。
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 条,供测试复核)
- 窗口:
dayCount个[D cutoverHour:00, D+1 cutoverHour:00)本地时区半开区间 (缺省 7 天、07:00 切点,可由请求params.dayCount/cutoverHour覆盖)。 - 流水:
wms_stock_transaction,transaction_type IN (INBOUND, OUTBOUND),显式排除 LOCK/UNLOCK, 按created_at落入窗口,INBOUND→rk、OUTBOUND→ck(变更数量quantity即出入库数)。 - 可用库存:
wms_storage(库位级正品明细),inventory_type='ZP'、is_enabled=1、未删除,SUM(available_quantity)=可用库存(行内available列);SUM(quantity)/SUM(locked_quantity)/ 待出库存等仅保留为行内内部计算字段,已不在导出列清单中。 - 条码:
wms_stock_barcodes多值取字典序第一条(表内无主条码标志,等价旧 PHPMIN(barcode)语义)。 - 外部编码:优先
wms_stock_store.item_code(按 stock_id 关联wms_stock_warehouse.id,同 stock_id 多条时 按 id 升序取第一条非空 item_code,stock_id 为空的记录不参与匹配),未匹配则回落wms_stock_warehouse.item_code,再无则留空。 - 待处理订单占用数:取
wms_stock_warehouse.locked_quantity(仓库商品主表锁定数量, 不是wms_storage聚合的 locked_quantity 口径)。 - 行范围:窗口内有流水或有正品库存的 SKU 均出列,按
item_code升序、stock_id升序。 - suggest/warn:由
formatters注册表计算。低库存补偿:available < 20且rk_total < 20时 推荐采购量补偿到不低于 30;预警判定由warnOf(ck_total, available, rk_total)计算。 行内仍计算rk_total/日均/预计可售天数等字段供判定与复核,但不进入导出列清单。
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为文件名模板,{date}替换为数据日期(请求params.bizDate,缺省服务器当天,YYYY-MM-DD)。- 缺省模板:
<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.jsgenerateAndUpload在上述目录后追加{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强校验, 任一无效直接抛错「投递计划维度非法(…),拒绝生成报表」,绝不生成跨货主报表。 - 失败自动重推: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)的群仍可选中, 屏蔽属于发送时过滤维度。 - 发送时逐群推送(群维度协议字段
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,未知报「未知的报表类型: 」);fields必须为该类型注册字段子集(9 组列任意勾选,含非法 key 报可读错误并列出可用字段)。file_name兼容fileName驼峰写法(驼峰优先);新增必填name/type/file_name/fields; 更新按idupsert,未传字段不覆盖;软删记录命中时自动恢复。- 保存成功后响应即报表定义视图:
{ 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 }
]
}
]
}
字段元素结构:{ 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 前端如何获取可用字段
- 调用
method=report.definition.typeList(POST /system,header 带Authorization: Bearer <token>与platform) 获取全部注册类型与字段树(含窗口参数window.dayCount/cutoverHour); - 保存报表定义时按类型字段树勾选
fields(method=report.definition.save); - 渲染/导出前用
report.definition.list取该报表定义已勾选的fields数组(与typeList字段树 key 对照); - 导出 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:按idupsert(未传 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预演)。