WMS_MAIN/docs/report-config-guide.md
liufumingren 2597faac4c feat(report): stockFlow 报表 9 列新顺序重构与投递货主隔离修复
1) 报表导出列重构为 9 组列(产品名称/条码/外部编码/每日出入库/待处理订单占用数/可用库存/7日总出库数量/推荐采购量/是否触发预警),外部编码 stock_store 优先 fallback,新增 pending_occupy 取仓库主表锁定数量;2) 投递货主隔离修复(上传目录按货主/仓库隔离、投递与通知幂等键含 storeId、processOne 货主维度强校验);3) 文档与 methods 变更记录同步。
2026-09-01 00:42:30 +08:00

340 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 配置驱动通用报表与货主定时投递 — 配置结构说明
> 本文档与代码实现保持一致(模型:`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 | 时间戳与软删标记 |
生成链路:
```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日总出库数量/推荐采购量与是否触发预警 |
`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 条,供测试复核)
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`/日均/预计可售天数等字段供判定与复核,但不进入导出列清单。
## 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.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` 强校验,
任一无效直接抛错「投递计划维度非法(…),拒绝生成报表」,绝不生成跨货主报表。
- **失败自动重推**: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` 返回:
```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`,未知报「未知的报表类型: <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 }
]
}
]
}
```
字段元素结构:`{ 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` 预演)。