执行重构加入镀锌线1的后端调用接口

ems-cost-allocation-notes.md

@@ -0,0 +1,225 @@
+# 能源分摊（现有实现）与加入“备件/辅料分摊”的接入方案
+
+## 0. 时间线（用于交接，持续更新）
+
+- **2026-01-20**
+  - **已改动（代码）**：
+    - `klp-ems/src/main/java/com/klp/ems/domain/vo/CoilTotalCostVo.java`：新增 `auxCost/spareCost` 字段，`totalCost` 注释更新。
+    - `klp-ems/src/main/java/com/klp/ems/domain/vo/CoilTotalMergedExportVo.java`：新增导出列 `auxCost/spareCost`。
+    - `klp-ems/src/main/resources/mapper/WmsEnergyCoilDailyMapper.xml`：`selectCoilTotalMerged` 与 `selectCoilTotalMergedExport` 已加入 `auxCost/spareCost` 计算与 join，并更新 `totalCost` 公式。
+    - `klp-ems/src/main/java/com/klp/ems/controller/EnergyCostReportController.java`：导出接口已补充 `auxCost/spareCost` 赋值。
+    - `klp-ui/src/views/ems/cost/cost.vue`：列表新增列展示 `auxCost/spareCost`；顶部卡片展示 `materialSummary`（当前按列表行求和）；总成本计算加入备件/辅料。
+
+- **2026-01-26**
+  - **新增（前端页面）**：按数据库路由方式新增两个独立页面（不在前端代码写路由）。
+    - `klp-ui/src/views/ems/cost/auxAllocation.vue`：辅料成本分摊页面（按入场卷号汇总），包含“分摊明细”弹窗与导出；并新增“辅料消耗构成（分摊口径）”区域（展示用了哪些辅料、几种、数量与金额）。
+    - `klp-ui/src/views/ems/cost/spareAllocation.vue`：备件成本分摊页面（按入场卷号汇总），包含“分摊明细”弹窗与导出；并新增“备件消耗构成（分摊口径）”区域（展示用了哪些备件、几种、数量与金额）。
+  - **路由 component 配置建议（写入数据库）**：
+    - 辅料：`ems/cost/auxAllocation`
+    - 备件：`ems/cost/spareAllocation`
+  - **接口复用说明**：
+    - 汇总：两个页面均复用 `GET /ems/energy/report/coilTotal/merged` 与 `GET /ems/energy/report/coilTotal/merged/export`，分别取字段 `auxCost` / `spareCost`。
+    - 构成：新增两个接口返回“按物料/备件聚合后的分摊构成”（数量与金额均按日分摊系数切分）：
+      - `GET /ems/energy/report/material/aux/breakdown`
+      - `GET /ems/energy/report/material/spare/breakdown`
+  - **口径（构成）**：
+    - 全厂按日聚合消耗（`eqp_*_change`，`change_type='减少'`，金额取 `ABS(amount)`，数量取 `ABS(change_quantity)`）
+    - 当日卷分摊系数：`coil_minutes_day / total_minutes_day`（分钟基于 `wms_coil_pending_action.create_time ~ complete_time/now`）
+    - 最终按物料/备件汇总：`allocatedQty = Σ_D (day_item_qty * factor_day)`，`allocatedAmount = Σ_D (day_item_amount * factor_day)`
+  - **重要说明**：
+    - merged 仍不返回按日池/分钟明细；页面“分摊明细”弹窗仍为汇总占位。
+    - 构成接口可在不强制 enterCoilNo 的情况下使用：不传 enterCoilNo 时可用于查看全厂消耗构成（allocated≈total）。
+
+- **2026-01-20**
+  - **口径确认**：备件/辅料分摊池按**全厂**聚合（不按库区/设备/产线拆分）。
+  - **过滤规则确认**：
+    - `wms_coil_pending_action`：按 `pa.create_time` 落在 `[startDate, endDate]` 过滤。
+    - `eqp_*_change`：按 `change_time` 落在同一 `[startDate, endDate]` 过滤。
+    - 仅统计 `change_type = '减少'`（消耗）。
+  - **金额按天切分规则确认**：采用 **A 方案**（按 `DATE(pa.create_time)` 归属到某一天；不做跨天拆分时长）。消耗金额按天形成日池（例如 3 天形成 3 个日池、5 天形成 5 个日池），再在当日内按钢卷时长占比分摊。
+  - **跨库可达性确认**：EMS/WMS 可以直接查询到 MES 的 `eqp_auxiliary_material_change`、`eqp_spare_parts_change` 两张变动表（可在 EMS 侧 SQL 直接使用）。
+  - **已完成**：梳理前端 `klp-ui/src/views/ems/cost/cost.vue` 的查询/展示/接口调用。
+  - **已完成**：定位后端 `EnergyCostReportController` 与 `WmsEnergyCoilDailyMapper.xml`。
+  - **已修正**：早期将能源分摊概括为“库区时间窗”会误导备件/辅料接入；备件/辅料分摊以 `wms_coil_pending_action` 的待操作时间窗为中心（见本时间线确认项）。
+  - **已确认（MES 成本记账规则）**：
+    - 台账表（`eqp_spare_part`、`eqp_auxiliary_material`）补充 `unit_price/total_amount`。
+    - 入库单价来源：**前端必传**（老接口与前端一并改造）。
+    - 入库/增加时采用移动加权平均价：`new_unit_price = (old_unit_price*old_qty + in_unit_price*in_qty) / (old_qty+in_qty)`。
+    - 消耗/减少时在变动表写入 `unit_price_snapshot` 并计算 `amount`（**有符号**；减少为负：`-unit_price_snapshot * change_quantity`）。
+    - 分摊侧聚合消耗金额使用 `ABS(amount)`。
+
+> 范围：
+> - 前端页面：`klp-ui/src/views/ems/cost/cost.vue`
+> - 后端接口：`klp-ems/src/main/java/com/klp/ems/controller/EnergyCostReportController.java`
+> - 主要 SQL：`klp-ems/src/main/resources/mapper/WmsEnergyCoilDailyMapper.xml`
+> - MES 表结构：`script/sql/mysql/eqp_auxiliary_material.sql`
+
+## 1. 现有页面做了什么（前端）
+
+页面名称：`CoilTotalCost`（钢卷成本汇总）
+
+### 1.1 查询条件
+
+`queryParams`：
+
+- `enterCoilNo`：入场卷号（页面标记 required，支持模糊）
+- `currentCoilNo`：当前卷号（支持模糊）
+- `startDate`：开始日期（yyyy-MM-dd）
+- `endDate`：结束日期（yyyy-MM-dd）
+
+点击“查询”会同时触发三块数据加载：
+
+- **能源成本汇总 + 明细**（EMS）
+- **囤积成本明细/汇总**（WMS）
+- **能源+囤积 合并汇总**（EMS 聚合接口）
+
+### 1.2 页面展示结构
+
+- **顶部 4 个卡片**
+  - **能源成本**：来自 `energySummary.totalEnergyCost`，并展示耗能、时长
+  - **本日囤积成本**：来自 `stockSummary.todayCost`，并展示净重/毛重
+  - **辅料成本**：当前写死 `0.00`（`暂不计`）
+  - **总成本**：`能源 + 囤积 + 辅料(当前为 0)`
+
+- **表格：成本汇总（按入场卷号）**
+  - 数据源：`mergedRows`
+  - 列：入场卷号、当前卷号、能源成本、囤积成本(当日)、总成本、净重、毛重
+  - 操作：查看详情
+
+- **详情弹窗**
+  - 能源分摊明细（按待操作时间跨度分摊）
+  - 囤积成本（单行汇总）
+
+### 1.3 前端调用的接口
+
+能源相关（同一模块 `@/api/ems/energyCostReport`）：
+
+- `fetchCoilTotalEnergySummary(params)`
+  - 对应后端：`GET /ems/energy/report/coilTotal/summary`
+
+- `fetchCoilTotalEnergyDetail(params)`
+  - 对应后端：`GET /ems/energy/report/coilTotal/detail`
+
+- `fetchCoilTotalMerged(params)`
+  - 对应后端：`GET /ems/energy/report/coilTotal/merged`
+
+- `exportCoilTotalMerged(params)`
+  - 对应后端：`GET /ems/energy/report/coilTotal/merged/export`
+
+囤积成本（WMS 模块 `@/api/wms/cost`）：
+
+- `getStockpileCostList(params)`
+
+## 2. 现有“能源分摊”后端是怎么做的（与备件/辅料接入相关的部分）
+
+核心 Controller：`EnergyCostReportController`
+
+- `GET /ems/energy/report/coilTotal/summary`
+- `GET /ems/energy/report/coilTotal/detail`
+- `GET /ems/energy/report/coilTotal/merged`
+- `GET /ems/energy/report/coilTotal/merged/export`
+
+入参对象：`CoilTotalCostBo`：`enterCoilNo/currentCoilNo/startDate/endDate`
+
+当前实现中，`coilTotal/*` 相关 SQL 主要围绕 `wms_coil_pending_action` 的时间跨度计算（分钟/小时），并将能耗/成本按占比分配到卷。
+
+## 3. 备件/辅料分摊：最新确认的正确口径（可直接实现）
+
+### 3.1 总体思路
+
+- 备件/辅料成本池：按**全厂**聚合。
+- 成本池按**日**切分：以 `DATE(change_time)` 形成每日消耗金额池。
+- 分摊权重按**日**切分：以 `DATE(pa.create_time)` 形成每日钢卷“待操作时长”池。
+- 当天内按“入场卷号的总时长 / 全厂总时长”占比，将当日消耗金额分摊到各入场卷号。
+
+### 3.2 关键定义（A 方案：不拆跨天时长）
+
+#### (1) 当日消耗金额池（仅减少）
+
+- `aux_pool_day(D) = SUM(eqp_auxiliary_material_change.amount)`
+- `spare_pool_day(D) = SUM(eqp_spare_parts_change.amount)`
+
+过滤：
+
+- `change_type = '减少'`
+- `DATE(change_time) = D`
+- 且 `change_time` 在 `[startDate, endDate]` 范围内（与查询一致）
+
+#### (2) 当日全厂总时长池
+
+- `minutes(pa) = TIMESTAMPDIFF(MINUTE, pa.create_time, COALESCE(pa.complete_time, NOW()))`
+- `total_minutes_day(D) = SUM(minutes(pa))`
+
+过滤：
+
+- `pa.create_time` 在 `[startDate, endDate]`
+- `DATE(pa.create_time) = D`
+
+#### (3) 当日按入场卷号的时长
+
+- `coil_minutes_day(D, enter_coil_no) = SUM(minutes(pa))`
+
+其中 `enter_coil_no` 通过：
+
+- `wms_coil_pending_action.pa.coil_id -> wms_material_coil.coil_id -> wms_material_coil.enter_coil_no`
+
+#### (4) 当日分摊与汇总
+
+- `aux_cost_day = aux_pool_day(D) * coil_minutes_day / total_minutes_day`
+- `spare_cost_day = spare_pool_day(D) * coil_minutes_day / total_minutes_day`
+
+最终：
+
+- `auxCost = Σ_D aux_cost_day`
+- `spareCost = Σ_D spare_cost_day`
+
+### 3.3 SQL 接入点（在 EMS merged 中 join）
+
+建议在 `WmsEnergyCoilDailyMapper.xml`：
+
+- `selectCoilTotalMerged`
+- `selectCoilTotalMergedExport`
+
+新增 join 结构：
+
+1. 先构造“按入场卷号的每日分钟数”子查询：`coil_day_minutes`
+2. 再构造“全厂每日总分钟数”子查询：`total_day_minutes`
+3. 再构造“全厂每日消耗金额池（备件/辅料）”子查询：`aux_day_amount` / `spare_day_amount`
+4. 通过 `day` 将以上子查询 join 起来，得到 `Σ( day_amount * coil_day_minutes / total_day_minutes )`
+5. 最终在 `merged` 的 select 列表中补充：
+   - `IFNULL(x.aux_cost, 0) AS auxCost`
+   - `IFNULL(x.spare_cost, 0) AS spareCost`
+   - `totalCost = energy_cost + stock_cost + aux_cost + spare_cost`
+
+> 注意：实现时需要防止分母为 0：`CASE WHEN total_day_minutes > 0 THEN ... ELSE 0 END`。
+
+## 4. 需要改动的后端/前端文件清单（待实现）
+
+### 4.1 EMS 后端（klp-ems）
+
+- `klp-ems/src/main/java/com/klp/ems/domain/vo/CoilTotalCostVo.java`
+  - 增加字段：`auxCost`、`spareCost`（以及 `totalCost` 公式更新）
+
+- `klp-ems/src/main/resources/mapper/WmsEnergyCoilDailyMapper.xml`
+  - 修改：`selectCoilTotalMerged`、`selectCoilTotalMergedExport`
+
+- `klp-ems/src/main/java/com/klp/ems/controller/EnergyCostReportController.java`
+  - 导出映射：`coilTotalMergedExport` 增加导出字段赋值
+
+- `klp-ems/src/main/java/com/klp/ems/domain/vo/CoilTotalMergedExportVo.java`
+  - 增加列：备件成本、辅料成本（以及总成本）
+
+### 4.2 前端（klp-ui）
+
+- `klp-ui/src/views/ems/cost/cost.vue`
+  - 顶部卡片：“辅料成本”从 0 改为接口返回（或新增 summary 聚合）
+  - 表格增加两列：`auxCost`、`spareCost`
+  - 总成本公式更新：能源 + 囤积 + 备件 + 辅料
+
+---
+
+## 5. 当前状态（给新 agent 的交接结论）
+
+- 分摊口径已最终确认并记录：**全厂池 + 按天切分 + A 方案（按 `DATE(pa.create_time)` 归属）**。
+- EMS/WMS 可直接查询 MES 的 change 表，允许在 `WmsEnergyCoilDailyMapper.xml` 内直接 join 实现。
+- 尚未开始实际代码改造；下一步按第 4 节清单逐项实现，并在每次提交后回写本文件时间线（记录修改了哪些文件/字段/SQL）。