---
name: 生产令号综合看板报表
overview: 新增一个以生产令号为顶层索引的聚合接口（及可选导出），串联 SQL Server 订单追溯（含采购线与生产线）、MySQL 工序计划主从表、以及工序汇报/委外两张快照表；在令号维度汇总生产入库、采购订单入库等指标。工序汇报与委外依赖快照数据时需约定日期过滤策略。
todos:
  - id: bo-vo
    content: 新增 KingdeeProductionBoardQueryBo / 聚合 VO（令号→订单→计划/追溯/快照；令号维度的生产入库汇总 + 采购入库汇总）
    status: pending
  - id: service-merge
    content: 实现 KingdeeProductionBoardService：trace → MO 集合 → 计划批量查询 → 快照 Mapper 过滤 → 采购/生产入库汇总 → 内存组装 VO
    status: pending
  - id: purchase-inbound-summary
    content: 基于 purchaseList 按 purchaseBillNo（+可选物料）groupBy 聚合 sumPurchaseQty/sumInstockQty，并写入令号级 PurchaseInboundSummaryVo
    status: pending
  - id: planning-reuse
    content: 从 SfcOperationPlanningMainServiceImpl 抽取 DTO 组装逻辑供看板复用（避免重复）
    status: pending
  - id: controller
    content: 新增 POST /system/kingdee/productionBoard/query + 权限与参数校验
    status: pending
  - id: date-normalize
    content: 快照日期过滤：首版文档说明格式差异；可选实现简单规范化（同一 sync 窗口内通常可接受仅按订单号关联）
    status: pending
---

> **说明**：Cursor 全局计划文件可能在用户目录下，例如  
> `C:\Users\<用户名>\.cursor\plans\生产令号综合看板报表_f0c1e308.plan.md`  
> 本文件为仓库内副本，路径：`docs/plans/生产令号综合看板报表.md`。

# 生产令号综合看板（大报表）方案

## 目标与边界

- **索引**：生产令号 `sclh`（支持多个令号一次查询）。
- **下钻**：每个令号下挂 **生产订单列表**；每个订单下聚合 **工序计划（本地库）**、**生产线追溯行**、**工序汇报汇总（快照）**、**委外转移（快照）**，以及 **生产入库小计**。
- **采购侧**：`queryOrderTrace` 返回的 `purchaseList`（[`KingdeePoTraceVo`](../../ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/KingdeePoTraceVo.java)：采购订单号 `purchaseBillNo`、`purchaseQty`、`instockBillNo`、`instockQty` 等）挂在同一令号下；除明细列表外，增加 **采购入库汇总**：
  - **令号维度**：如 `totalPurchaseInstockQty` = 对该令号下所有采购明细行的 `instockQty` 求和（空/null 按 0）；可选 `totalPurchaseOrderQty` = `purchaseQty` 之和，便于对比「采购下单 vs 已入库」。
  - **按采购订单汇总**（推荐）：`List<PurchaseInboundSummaryRow>`，键为 `purchaseBillNo`（+ 可选物料维度若一行一单多料），聚合 `sumPurchaseQty`、`sumInstockQty`、行数/入库单列表摘要；数据来源仍为当前追溯 SQL 的扁平行，仅内存 groupBy。
- **数据来源约定**：
  - 追溯：沿用 [`MssqlQueryService.queryOrderTrace`](../../ruoyi-system/src/main/java/com/ruoyi/system/service/MssqlQueryService.java)（`@DS("sqlserver")`），与 [`KingdeeOrderTraceController`](../../ruoyi-system/src/main/java/com/ruoyi/system/controller/KingdeeOrderTraceController.java) 一致。
  - 工序计划：MySQL [`sfc_operation_planning_main`](../../ruoyi-system/src/main/java/com/ruoyi/system/domain/SfcOperationPlanningMain.java) / `sfc_operation_planning_detail`，过滤条件与 [`buildQueryWrapper`](../../ruoyi-system/src/main/java/com/ruoyi/system/service/impl/SfcOperationPlanningMainServiceImpl.java) 对齐：`hbytSclh` 精确匹配（或与项目号 OR 逻辑按需收窄为「仅令号」以免扩 scope）。
  - 工序汇报 / 委外：**优先使用已入库快照** [`kingdee_operation_report_sum`](../../script/sql/update/kingdee-report-snapshot.sql)、[`kingdee_subcontract_transfer`](../../script/sql/update/kingdee-report-snapshot.sql)，按 **生产订单号** `mo_bill_no` / `product_order_codes` 与追溯得到的 `moBillNo` 集合关联。
- **不在首版默认开启**：每次请求实时调用 `JdUtil.getSysReportData`（除非你后续明确要求 `live` 参数）；避免一次看板触发多次金蝶报表压力。

```mermaid
flowchart TD
  subgraph input [输入]
    sclhList[sclh列表]
    dateOpt[可选快照日期范围]
  end
  subgraph ss [SQLServer]
    trace[queryOrderTrace]
  end
  subgraph mysql [MySQL]
    planMain[sfc_operation_planning_main/detail]
    rptSnap[kingdee_operation_report_sum]
    subSnap[kingdee_subcontract_transfer]
  end
  sclhList --> trace
  trace --> moSet[生产订单号集合]
  moSet --> planMain
  moSet --> rptSnap
  moSet --> subSnap
  trace --> prodInstockAgg[生产入库汇总]
  trace --> poInstockAgg[采购入库汇总]
  planMain --> vo[聚合VO]
  rptSnap --> vo
  subSnap --> vo
  prodInstockAgg --> vo
  poInstockAgg --> vo
```

## 聚合数据结构（建议）

新建聚合 VO（名称可定为 `KingdeeProductionBoardVo`），层级示例：

- `sclh`
- `purchaseList`：来自追溯 `purchaseList`（与该令号一致）
- `purchaseInboundSummary`：**按采购订单（及按需物料）聚合**的入库汇总行（见上文）；与明细并存，便于报表只看汇总
- **采购汇总标量**（可选与 summary 冗余）：`totalPurchaseInstockQty`、`totalPurchaseOrderQty`
- `productionTraceList`：该令号下全部 [`KingdeeMoTraceVo`](../../ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/KingdeeMoTraceVo.java) 行
- **生产侧汇总字段**：`totalProductionInstockQty`（对该令号下生产追溯行 `instockQty` 求和；原方案中的生产入库总值）；可按需 `totalMoQty`（`qty` 订单数量之和）
- `orders`：`List<MoBoardNode>`
  - `moBillNo`、`materialNumber`/`materialName`（可从追溯首行或计划主档带出）
  - `planning`：单个 [`OperationPlanResultDTO`](../../ruoyi-system/src/main/java/com/ruoyi/system/domain/dto/OperationPlanResultDTO.java) 或与主表 1:1 的列表（若一单多计划则列表）
  - `reportRows`：`List<KingdeeOperationReportSum>`（或精简 DTO）按 `mo_bill_no` 过滤后的快照行；可选再提供按 `report_date + op_oper` 的 **当日汇总**（内存 groupBy）
  - `subcontractRows`：`List<KingdeeSubcontractTransfer>` 按 `product_order_codes = moBillNo` 过滤
  - `moInstockQty`：该订单维度 **生产入库** `instockQty` 合计（来自 `KingdeeMoTraceVo`）
  - **说明**：采购入库按业务通常挂在 **令号 / 采购订单**，与生产订单号可能无一一映射字段；首版不强行拆到每个 `MoBoardNode`，除非后续在金蝶侧补充关联字段后再挂订单下钻。

多令号时返回 `List<KingdeeProductionBoardVo>` 或外层 `{ boards: [...] }`，二选一（建议 **列表**，与前端遍历一致）。

## 请求入参（新建 Bo）

- 必填：`List<String> sclh`（或兼容逗号分隔单参，与追溯 Bo 一致）。
- 可选：`reportSnapshotBegin` / `reportSnapshotEnd`（字符串或 `yyyy-MM-dd`）：用于过滤快照中的 `report_date`、`document_date`。  
  - **注意**：金蝶返回日期格式可能为 `2026/4/11`，实现上建议：**先在 Java 侧将快照中的日期列规范化为可比较形式**，或用「同步时写入规范化日期列」的二期优化；首版可采用 **宽松策略**（仅按订单号关联 + 可选区间子串/解析）并在文档中说明局限。
- 可选：`includePurchase`（默认 true）、`includeSnapshots`（默认 true）：便于关闭大块数据。

## 服务层实现要点

- 新建 `IKingdeeProductionBoardService` + `KingdeeProductionBoardServiceImpl`（或挂在现有 `MssqlQueryService` 旁，保持单一职责）。
- 步骤：
  1. 构造 [`KingdeeOrderTraceQueryBo`](../../ruoyi-system/src/main/java/com/ruoyi/system/domain/bo/KingdeeOrderTraceQueryBo.java)，仅填 `sclh`，调用 `queryOrderTrace`。
  2. 从 `productionList` 提取 `moBillNo` 去重集合；按 `sclh` 分组。
  3. **工序计划**：对每组令号，用 `LambdaQueryWrapper` `in(moNumber, ...)` 且 `eq(hbytSclh, sclh)` 批量查主表 + `detailMapper.in(mainId, ...)`；组装为 `OperationPlanResultDTO`（可复用 `queryCascadePageList` 中的组装片段，提取私有方法避免复制粘贴）。
  4. **快照**：`KingdeeOperationReportSumMapper.selectList(mo_bill_no in (...))`；`KingdeeSubcontractTransferMapper.selectList(product_order_codes in (...))`，必要时加日期条件。
  5. **采购入库汇总**：将 trace.`purchaseList` 按当前令号分组后，对组内数据 `groupBy(purchaseBillNo [, materialNumber])`，聚合 `purchaseQty`、`instockQty`（BigDecimal 累加），生成 `purchaseInboundSummary` 及令号级合计字段。
  6. 内存合并为上述 VO。

## Controller

- 新建 [`KingdeeProductionBoardController`](../../ruoyi-system/src/main/java/com/ruoyi/system/controller/)（或与 `KingdeeOrderTraceController` 同包）：`POST /system/kingdee/productionBoard/query`（POST 便于传多个 `sclh`）。
- 权限：建议与追溯一致 `system:mssql:query`，或拆新权限 `system:kingdee:productionBoard`（需菜单 SQL，首版可沿用前者减少配置）。

## 「给我看大报表」形态

- **首版**：返回 JSON（层级清晰，前端表格/折叠面板即可）。
- **可选二期**：基于同一 Service 增加 `export`（EasyExcel 多 Sheet：令号总览 / 采购入库汇总 / 生产订单 / 汇报 / 委外 / 入库明细），不阻塞首版。

## 风险与前置条件

- 工序汇报、委外 **快照未同步** 时对应块为空；文档或接口 `msg` 中提示先调用已有 `/system/kingdee/operationReportSum/sync` 与 `/system/kingdee/subcontractTransfer/sync`。
- 追溯 SQL 若条件过宽会导致 `mo` 集合过大：可对 `moBillNo` 数量设上限（如 500）超出则报错提示缩小令号范围。

## 主要新增/改动文件

- 新建：`KingdeeProductionBoardQueryBo`、`KingdeeProductionBoardVo`、`MoBoardNode`、`PurchaseInboundSummaryVo`（或同类命名）、`IKingdeeProductionBoardService`、`KingdeeProductionBoardServiceImpl`、`KingdeeProductionBoardController`。
- 必要时分摊：从 [`SfcOperationPlanningMainServiceImpl`](../../ruoyi-system/src/main/java/com/ruoyi/system/service/impl/SfcOperationPlanningMainServiceImpl.java) **抽取**「主表+明细 → OperationPlanResultDTO」为 package-private 或组件方法，供看板复用。