479 lines
32 KiB
Markdown
479 lines
32 KiB
Markdown
# 配置驱动通用报表与货主定时投递 — 配置结构说明
|
||
|
||
> 本文档与代码实现保持一致(模型:`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 | 时间戳与软删标记 |
|
||
|
||
生成链路:
|
||
|
||
```text
|
||
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 列。配置示例:
|
||
|
||
```json
|
||
// 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: <channel>」)、
|
||
`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`(未设置时为空字符串)。
|
||
|
||
```json
|
||
// 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` 返回:
|
||
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
```json
|
||
{
|
||
"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`,未知报「未知的报表类型: <type>」);
|
||
`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 请求示例
|
||
|
||
```json
|
||
// report.definition.typeList(无必填参数)
|
||
{}
|
||
```
|
||
|
||
|
||
### 7.3 响应示例
|
||
|
||
```json
|
||
// 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` 预演)。
|
||
|