# 配置驱动通用报表与货主定时投递 — 配置结构说明 > 本文档与代码实现保持一致(模型:`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`)。 - 缺省模板:`_.xlsx`;不以 `.xlsx`/`.xls` 结尾时自动补 `.xlsx`。 - 上传目录:`exports/report//`。 ## 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`(未设置时为空字符串)。 ```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`,未知报「未知的报表类型: 」); `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=`。 ### 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 ` 与 `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 ` 与 `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` 预演)。