WMS_MAIN/docs/report-config-guide.md

343 lines
20 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 每日出/入库、可用/总库存、锁定数、待出、日均出/入库、预计可售天数、建议补货量与库存预警 |
`stockFlow` 缺省窗口参数:`window = { dayCount: 7, cutoverHour: 7 }`。
`stockFlow` 全量字段清单(16 个顶层字段,`report.definition.typeList` / `report.meta` 直接返回该规格):
| key | label | type | computed | asText | 说明 |
|---|---|---|---|---|---|
| `stock_id` | 库存ID | number | - | - | |
| `item_code` | 商品编码 | string | - | ✅ | 文本单元格落地,防科学计数法 |
| `item_name` | 商品名称 | string | - | - | |
| `barcode` | 条码 | string | - | ✅ | 文本单元格落地,防科学计数法 |
| `daily` | 每日出入库 | array | - | - | children:`ck`(出库数,number)/ `rk`(入库数,number) |
| `ck_total` | 出库合计 | number | - | - | |
| `rk_total` | 入库合计 | number | - | - | |
| `available` | 可用库存 | number | - | - | |
| `total` | 总库存 | number | - | - | |
| `pending` | 待出库存 | number | - | - | |
| `locked` | 锁定数 | number | - | - | |
| `ck_avg` | 出库日均(×10) | number | ✅ | - | 预计算字段 |
| `rk_avg` | 入库日均(×10) | number | ✅ | - | 预计算字段 |
| `stock_days` | 预计可售天数 | number | ✅ | - | 预计算字段 |
| `suggest` | 建议补货量 | number | ✅ | - | 预计算字段 |
| `warn` | 库存预警 | boolean | ✅ | - | 预计算字段 |
### 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。
3. **库存口径**:`wms_storage`(库位级正品明细),`inventory_type='ZP'`、`is_enabled=1`、未删除,
`SUM(quantity)`=总库存、`SUM(available_quantity)`=可用库存、`SUM(locked_quantity)`=锁定数、
待出库存=总库存-可用库存;与 `wms_stock_warehouse` 主表的 `quantity/locked_quantity` 可能存在口径差异。
4. **条码**:`wms_stock_barcodes` 多值取字典序第一条(表内无主条码标志,等价旧 PHP `MIN(barcode)` 语义)。
5. **行范围**:窗口内有流水或有正品库存的 SKU 均出列,按 `item_code` 升序、`stock_id` 升序。
6. **日均口径**:`ck_avg/rk_avg = int(合计/天数×10)`(`formatters.avgDaysPerWeek`)。
7. **预计可售天数**:出库日均>0 时 `int(可用库存×10/出库日均×10)`(`available×10/ckAvg` 取整),无出库时为 null。
8. **suggest/warn**:由 `formatters` 注册表计算。低库存补偿:`available < 20` 且 `rk_total < 20` 时
建议补货量补偿到不低于 30;预警判定由 `warnOf(ck_total, available, 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)
- `file_name` 为文件名模板,`{date}` 替换为数据日期(请求 `params.bizDate`,缺省服务器当天,`YYYY-MM-DD`)。
- 缺省模板:`<name>_<date>.xlsx`;不以 `.xlsx`/`.xls` 结尾时自动补 `.xlsx`。
- 上传目录:`exports/report/<report_id>/`。
## 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)` 幂等生成报表并投递(防重不防漏)。
- **失败自动重推**: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_code", "item_name", "barcode", "daily", "ck_total", "rk_total", "available", "total", "pending", "locked", "ck_avg", "suggest", "warn"],
"is_enabled": 1,
"remark": ""
}
```
- `type` 必须命中注册表(当前仅 `stockFlow`,未知报「未知的报表类型: <type>」);
`fields` 必须为该类型注册字段子集(16 个顶层字段任意勾选,含非法 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 / report.meta(前端元数据接口)
### 7.1 用途
- `report.definition.typeList`:免权限只读(仅登录),返回注册类型清单
`[{ key, title, description, window, fields }]`,供前端报表设计器渲染「报表类型」选择与字段树。
- `report.meta`:免权限只读(仅登录,保留审计日志),按 `report_id` 返回
`report_id/name/type/file_name/window/fields`(fields 含 `selected` 勾选标记与 `asText` 标记),
**不执行真实数据查询**。
实现:`report.definition.typeList` → `app/service/systemMethods/report/definition.js` → `systems/report.js listRegisteredTypes`;
`report.meta` → `app/service/systemMethods/report.js` → `systems/report.js getMeta`。
> 鉴权/日志口径:`report.definition.typeList` 在 `definition.js` 的 `systemInit` 名单内
> (`_noNeedRight/_noNeedAuth/_noNeedLog='typeList'`:免权限 + 免鉴权 + 不写审计日志,仅登录;
> 同模块 `save/list/delete` 未声明免权限,仍需授权);`report.meta` 在 `_noNeedRight/_noNeedAuth` 名单内
> (免权限 + 免仓库有效期校验,仅登录),未列入 `_noNeedLog` → **保留审计日志**
> (`generate`/`generateTaskProgress` 不写审计日志,二者行为不同)。
### 7.2 请求示例
```json
// report.definition.typeList(无必填参数)
{}
// report.meta
{ "report_id": 1 }
```
- `report_id` 与 `reportId` 二选一(均传时优先 `reportId`);为空返回
`flag=failure, code=0, message=报表ID report_id 必须为正整数`(HTTP 200)。
- 定义不存在或已停用 → HTTP 500,`接口错误: 报表定义不存在或已停用: id=<id>`。
### 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_code", "label": "商品编码", "type": "string", "asText": true },
{ "key": "daily", "label": "每日出入库", "type": "array", "children": [
{ "key": "ck", "label": "出库数", "type": "number" },
{ "key": "rk", "label": "入库数", "type": "number" }
]},
{ "key": "suggest", "label": "建议补货量", "type": "number", "computed": true }
]
}
]
}
// report.meta
{
"flag": "success",
"code": 1,
"message": "ok",
"report_id": 1,
"name": "库存变化以及补货报表",
"type": "stockFlow",
"file_name": "库存变化_{date}.xlsx",
"window": { "dayCount": 7, "cutoverHour": 7 },
"fields": [
{ "key": "item_code", "label": "商品编码", "type": "string", "asText": true, "selected": true },
{ "key": "barcode", "label": "条码", "type": "string", "asText": true, "selected": false }
]
}
```
字段元素结构:`{ key, label, type, computed?, asText?, children?, selected? }`:
- `type`:`string` / `number` / `boolean` / `array`;
- `computed: true`:预计算字段(非原始表字段,如 `suggest`/`warn`);
- `asText: true`:该列以文本单元格落地(由类型字段规格硬编码,如 `item_code`/`barcode`);
- `children`:数组类型字段的子字段(如 `daily` 的 `ck`/`rk`);
- `selected`(仅 `report.meta` 返回):该报表定义是否勾选此字段。
### 7.4 前端如何获取可用字段
1. 调用 `method=report.definition.typeList`(`POST /system`,header 带 `Authorization: Bearer <token>` 与 `platform`)
获取全部注册类型与字段树;
2. 保存报表定义时按类型字段树勾选 `fields`(`method=report.definition.save`);
3. 渲染/导出前调用 `method=report.meta`(入参 `report_id`)取窗口参数 `window.dayCount/cutoverHour` 与勾选标记 `selected`;
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` 预演)。