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

docs/oee-report-design.md

@@ -0,0 +1,492 @@
+# OEE 报表页面设计（酸轧线、镀锌一线）
+
+> ⚠️ **状态说明（2026-01）**：`klp-da` 中 `OeeReportServiceImpl` 的旧实现已全部移除，目前仅保留可编译运行的空骨架（接口返回空数据）。本设计文档中所有“✅ 当前实现口径/实现说明/回归实现细节”等内容已不再成立，需要以新的实现方案为准。
+
+> 目标：在现阶段**不依赖班次/工单/客户维度**的前提下，完成可对比的两条产线 OEE 报表页面，包含 **OEE + 三大构成指标（时间稼动率/性能稼动率/良品率）**、**趋势**、**7 大损失**、**明细**，并在页面中**展示公式与口径**，方便统一认知与复核。
+
+---
+
+## 1. 范围与非范围
+
+### 1.1 本期范围（V1）
+- **对象**：两条产线
+  - 酸轧线
+  - 镀锌一线
+- **时间粒度**：
+  - 报表查询：按日（必做）
+  - 趋势图：按日（必做），可扩展按小时/班次（后续）
+- **核心指标**：
+  - OEE
+  - 时间稼动率（Availability）
+  - 性能稼动率（Performance）
+  - 良品率（Quality）
+- **分析内容**：
+  - 两线对比：KPI + 趋势
+  - 7 大损失（分类汇总 + Top 原因）
+  - 停机/损失明细列表（可筛选：产线/日期/损失类别）
+
+### 1.2 非范围（V1 不做）
+- 班次维度、工单维度、客户维度
+- 设备级 OEE（仅产线级；如产线下含多设备，可在数据层聚合）
+- 复杂的理论产能模型（先以**标准节拍**/标准速度为主）
+
+---
+
+## 2. 页面信息架构（IA）与交互
+
+### 2.1 页面入口与路由建议
+- 菜单：EMS / 报表 / **OEE 报表**
+- 路由：`/ems/oee`（建议）
+
+### 2.2 查询区（页面顶部）
+- **日期范围**：开始日期、结束日期（默认最近 7 天/30 天）
+- **产线选择**：
+  - 默认勾选：酸轧线、镀锌一线（两线同时展示）
+  - 支持单选/多选（便于对比）
+- **统计口径选择（可选）**：
+  - 负荷时间口径：是否扣除“计划停机”（默认扣除）
+  - 性能口径：使用标准节拍（默认）/使用标准速度（可选）
+- 查询按钮、重置按钮
+
+### 2.3 KPI 总览区（第一屏）
+以“产线”为列，指标为行（或每条产线一张卡片）：
+- **OEE（%）**
+- **时间稼动率（%）**
+- **性能稼动率（%）**
+- **良品率（%）**
+- 辅助数值（建议展示，便于解释指标波动）：
+  - 负荷时间（min）
+  - 停机时间（min）
+  - 实际运转时间（min）
+  - 产量（件/吨/卷，按你们产线计量单位）
+  - 不良数
+
+> 建议：KPI 卡片中同时显示“数值 + 分子/分母”摘要，例如：时间稼动率 87%（运转 400 / 负荷 460）。
+
+### 2.4 趋势区（第二屏）
+- 折线图 1：两条产线 **OEE 日趋势**（同一图两条线）
+- 折线图 2：两条产线 **三大指标日趋势**（可 Tab 切换或分三图）
+
+### 2.5 7 大损失区（第三屏）
+- 维度：产线（Tab：酸轧线 / 镀锌一线 / 合计）
+- 图表：
+  - 柱状图：7 大损失分类的**时间损失（min）**
+  - 帕累托：TopN 原因（来自停机原因/质量原因）占比
+- 表格：
+  - 7 大损失分类：损失时间、占比、次数（可选）、平均时长（可选）
+
+### 2.6 明细区（第四屏）
+- 停机/损失事件明细表
+  - 日期时间、产线、损失类别、原因、开始/结束、时长、备注
+- 支持筛选：
+  - 产线、日期、损失类别、关键词（原因/备注）
+
+### 2.7 公式与口径说明区（页面底部或抽屉）
+> 你希望页面上展示公式：建议做成“口径说明”卡片 + 可折叠（默认折叠），避免占用首屏空间。
+
+内容包括：OEE 公式、三大指标公式、字段定义、边界规则（见第 3、6 节）。
+
+---
+
+## 3. 指标定义与公式（页面需展示）
+
+### 3.1 总公式
+**设备综合效率（OEE）**：
+\[
+OEE = 时间稼动率 \times 性能稼动率 \times 良品率
+\]
+
+### 3.2 时间稼动率（Availability）
+定义：在负荷时间内，真正处于“运转”的时间比例。
+
+\[
+时间稼动率 = \frac{负荷时间 - 停机时间}{负荷时间} \times 100\%
+\]
+
+字段解释：
+- **负荷时间**：计划生产时间扣除计划停机后的时间（V1 默认扣除计划停机）
+- **停机时间**：属于“停止损失”的所有停机/中断的总时长
+
+### 3.3 性能稼动率（Performance）
+定义：在实际运转时间内，理论应完成的产量对应的时间占比（或等价的速度比）。
+
+以“标准节拍”为口径（推荐、通用）：
+\[
+性能稼动率 = \frac{理论节拍 \times 产量}{实际运转时间} \times 100\%
+\]
+
+字段解释：
+- **理论节拍**：每单位产出的理论加工时间（如 min/吨、sec/卷，需统一单位）
+- **产量**：该期间内的产出总量（单位需与理论节拍匹配）
+- **实际运转时间**：负荷时间 - 停机时间
+
+> 备注：如果你们更习惯“标准速度”，可替换为速度比口径：
+> \[
+> 性能稼动率 = \frac{实际产量}{理论产量} \times 100\%
+> \]
+> 其中理论产量 = 实际运转时间 / 理论节拍。
+
+### 3.4 良品率（Quality）
+\[
+良品率 = \frac{良品数}{总产量} \times 100\%
+\]
+
+字段解释：
+- **总产量**：产出总量（良品 + 不良/报废/返工产出，按你们定义）
+- **良品数**：合格产出数量
+
+---
+
+## 4. 7 大损失（分类口径）
+
+> 7 大损失的目的：把 OEE 的损失拆解成可行动的改善项。V1 先做“分类汇总 + Top 原因”，不强依赖复杂的自动归因。
+
+### 4.1 7 大损失分类（建议编码）
+1. **故障**（Breakdown）
+2. **换模换线/调整**（Setup & Adjustment）
+3. **刀具交换**（Tool Change）
+4. **暖机**（Warm-up）
+5. **空转/短暂停机**（Idling & Minor Stops）
+6. **速度下降**（Reduced Speed）
+7. **不良/修正**（Defects & Rework）
+
+### 4.2 数据落地建议（最小可用）
+V1 推荐按“事件表 + 分类映射”实现：
+- 停机事件（1~5 类）：从停机事件表按原因映射到分类
+- 速度下降（6 类）：允许先不拆事件，直接以“性能损失分钟数”计算后挂到第 6 类
+- 不良/修正（7 类）：从质量数据汇总；可换算成时间损失或先仅显示数量/比例（见 5.3）
+
+> 关键点：**分类映射表**要可配置（原因码 -> 损失类别），便于后期持续维护与纠正。
+
+---
+
+## 5. 数据需求（V1 最小数据集）
+
+### 5.1 维表：产线定义（必需）
+用于固定两条产线的展示与筛选。
+- `line_id`：产线 ID（建议固定，例如 `SY`、`DX1`）
+- `line_name`：产线名称（酸轧线、镀锌一线）
+
+### 5.2 事实表 A：产线日汇总（推荐：可由明细聚合生成）
+用于 KPI 与趋势图（按日、按产线）。
+
+字段（按日、按产线一行）：
+- `stat_date`：日期（yyyy-MM-dd）
+- `line_id`
+- `planned_time_min`：计划时间（min，可选）
+- `planned_downtime_min`：计划停机（min，可选；若无则置 0）
+- `loading_time_min`：负荷时间（min）= planned_time_min - planned_downtime_min
+- `downtime_min`：停机时间（min，来自停机事件汇总）
+- `run_time_min`：实际运转时间（min）= loading_time_min - downtime_min
+- `total_output`：总产量（单位：吨/卷/件，需统一）
+- `good_output`：良品量
+- `defect_output`：不良量（= total_output - good_output，或单独提供）
+- `ideal_cycle_time_min_per_unit`：理论节拍（min/单位；若按产品不同，可取当日主产品或加权平均）
+
+派生指标（后端返回也可以，前端不必重复算）：
+- `availability`：时间稼动率（0~1 或 0~100）
+- `performance`：性能稼动率
+- `quality`：良品率
+- `oee`：OEE
+
+### 5.3 事实表 B：停机/损失事件明细（必需）
+用于“停机明细”和 7 大损失（1~5 类）。
+
+字段（每次事件一行）：
+- `line_id`
+- `event_start_time`：开始时间
+- `event_end_time`：结束时间
+- `duration_min`：时长（min，可由 start/end 计算）
+- `raw_reason_code`：原始原因码（PLC/MES/人工）
+- `raw_reason_name`：原因描述
+- `loss_category_code`：损失分类（7 大损失之一；可由映射表生成）
+- `loss_category_name`
+- `remark`：备注（可选）
+
+### 5.4 映射表：原因 -> 7 大损失类别（强烈建议）
+- `reason_code`
+- `reason_name`
+- `loss_category_code`（1~7 或枚举）
+- `enabled`
+- `updated_by/updated_time`
+
+### 5.5 事实表 C：质量汇总（必需，至少按日/产线）
+用于良品率与第 7 类损失。
+
+字段（按日、按产线一行，或更细）：
+- `stat_date`
+- `line_id`
+- `total_output`
+- `good_output`
+- `defect_output`
+- `defect_reason_code`/`defect_reason_name`（如有则可做 Pareto）
+
+> 若当前系统只有“总产量 + 不良量”，也可先做，Pareto 暂缺。
+
+---
+
+## 6. 计算规则与边界（避免口径争议）
+
+### 6.1 单位与精度
+- 时间统一用 **分钟（min）**，产量统一用某一个单位（吨/卷/件三选一，不建议混用）
+- 比例类指标输出：
+  - 存储：`0~1`（推荐）或 `0~100`（二选一，接口需固定）
+  - 展示：百分比 `%`，保留 1~2 位小数
+
+### 6.2 负荷时间缺失的处理
+若 V1 暂无计划时间/计划停机：
+- 方案 A（推荐）：先把 **负荷时间**直接作为外部输入（由业务提供/班组报工）
+- 方案 B：以“日历时间（24h）”近似（不推荐，会误导）
+
+### 6.3 性能稼动率上限与异常
+理论上性能稼动率可能 > 100%（标准节拍偏大、或实际速度超标）。
+建议规则：
+- **展示值**：允许 >100%，但同时给出提示“标准节拍/标准速度需校准”
+- **可选**：提供开关将 performance clamp 到 100%（不建议默认 clamp，会掩盖问题）
+
+### 6.4 速度下降（第 6 类）如何得到“分钟数”
+当你们没有“速度下降事件”时，建议以性能损失折算分钟数：
+- `ideal_time_min = ideal_cycle_time_min_per_unit * total_output`
+- `performance_loss_min = max(0, run_time_min - ideal_time_min)`
+将 `performance_loss_min` 作为第 6 类“速度下降”损失时间。
+
+> 注意：如果 `ideal_time_min > run_time_min`，说明当日速度优于标准（或标准过宽），此时性能损失为 0。
+
+### 6.5 不良/修正（第 7 类）如何换算“分钟数”（可选）
+V1 可先只展示“不良量/不良率”；若要换算成时间损失：
+- `quality_loss_min = defect_output * ideal_cycle_time_min_per_unit`
+并作为第 7 类损失时间。
+
+---
+
+## 7. 接口设计（建议）
+
+> 下面为接口设计说明。注意：本文不再描述“当前后端实现细节”，仅给出建议的接口形态与字段含义，具体实现以代码为准。
+
+### 7.0 多服务（多 IP/端口）接入原则
+
+当前两条产线来自**两个不同服务**（不同 IP/端口），需在接口设计中显式考虑：
+
+- **方式 A（推荐）：后端统一网关/中台**
+  - 在现有 Java 服务或 API 网关中，新增一个 **OEE 聚合接口** 模块：
+    - 内部分别调用「酸轧线服务」与「镀锌一线服务」的地址
+    - 对外仍暴露统一的 `/api/ems/oee/...` 风格接口
+  - 优点：前端无感知多服务、网络安全/鉴权可统一；后期扩展新产线也只需后端配置。
+- **方式 B：前端直连多服务（不推荐，仅在现有架构强约束时考虑）**
+  - 需在 `vue.config.js` 中配置多个 `proxy`，例如 `/ems-sy` -> 酸轧线、`/ems-dx1` -> 镀锌一线
+  - 前端在请求时根据 `lineId` 选择不同前缀（易产生逻辑分叉、难复用）
+
+> 设计目标：**对前端暴露统一接口**，由后端负责区分产线来源服务并做数据聚合与清洗。
+
+以下接口路径均以“后端统一聚合后”的 API 为准。
+
+- 路由前缀：以 `klp-da` 实际 Controller 为准（本文不再假设已实现的固定前缀）。
+
+### 7.1 KPI + 趋势汇总
+`GET /oee/line/summary`
+
+参数：
+- `startDate`：yyyy-MM-dd
+- `endDate`：yyyy-MM-dd
+- `lineIds`：逗号分隔（例如 `SY,DX1`）
+
+返回（示例结构）：
+- `lines[]`
+  - `lineId`
+  - `lineName`
+  - `total`：区间汇总
+    - `loadingTimeMin`
+    - `downtimeMin`
+    - `runTimeMin`
+    - `totalOutput`
+    - `goodOutput`
+    - `defectOutput`
+    - `availability`
+    - `performance`
+    - `quality`
+    - `oee`
+  - `daily[]`：按日明细（用于趋势图）
+
+- 指标口径：以业务定义为准（负荷时间/停机/运转/产出/良品率/理论节拍的具体取数来源与规则需在新实现中明确）。
+
+### 7.2 7 大损失汇总
+`GET /oee/line/loss7`
+
+参数同上，额外：
+- `topN`：默认 10
+
+返回：
+- `byLine[]`
+  - `lineId`
+  - `lineName`
+  - `losses[]`
+    - `lossCategoryCode`
+    - `lossCategoryName`
+    - `lossTimeMin`
+    - `lossTimeRate`（占比，分母为“停机损失 + 速度下降损失”）
+    - `count`（次数，部分分类可能为空）
+    - `avgDurationMin`（平均时长，部分分类可能为空）
+  - `topReasons[]`：TopN 原因（按原因文本聚合）
+
+- 速度下降（第 6 类）建议口径：可用“性能损失分钟数”折算（详见 6.4），具体落地以新实现为准。
+
+### 7.3 停机/损失事件明细
+`GET /oee/line/events`
+
+参数：
+- `startTime`、`endTime`（支持到分钟）
+- `lineId`（可选）
+- `lossCategoryCode`（可选）
+- `keyword`（可选）
+- `pageNum`、`pageSize`
+
+返回：
+- `rows[]`：事件列表
+- `total`
+
+> ✅ **当前实现说明**  
+> - 事件来源：分别调用两条产线各自的停机事件接口进行聚合；并支持 `keyword/lossCategoryCode` 过滤与分页。
+
+### 7.4 理论节拍回归（散点 + 拟合线，用于前端绘图）
+`GET /oee/line/theoryCycle/regression`
+
+用途：
+- 前端绘制“散点 + 回归折线”的**理论节拍回归图**
+- 同时为 `summary` / `loss7` 提供 **理论节拍（分钟/吨）** 数据源（Performance 计算）
+
+参数：
+- 复用 `OeeQueryBo` 的 `startTime/endTime`（可选，格式 `yyyy-MM-dd HH:mm:ss`）
+- 不传时默认近 6 个月（由 WMS 侧默认）
+
+返回（结构透传 WMS 回归结果）：
+- `lines[]`
+  - `lineId`：`SY` / `DX1`
+  - `lineName`
+  - `slopeMinPerTon`：**分钟/吨（核心值，可作为理论节拍）**
+  - `interceptMin`：截距（分钟）
+  - `r2`：拟合优度
+  - `sampleCount`：参与回归样本数
+  - `startTime` / `endTime`
+  - `points[]`：散点
+    - `weightTon`（X）
+    - `durationMin`（Y）
+    - `actionId`
+    - `createTime`
+  - `linePoints[]`：拟合线两个端点（前端可直接画线）
+
+> ✅ **当前实现的数据来源（WMS）**  
+> - `SY`：`wms_coil_pending_action.action_type=11`，单卷，吨数来自该记录 `coil_id` 对应钢卷的 `netWeight/grossWeight`。  
+> - `DX1`：`action_type=501`，`remark` 为钢卷 id 列表字符串（提取数字），按列表汇总吨数。  
+> - 样本过滤：`action_status=2`、`create_time` 在近 6 个月、`completeTime-createTime` > 0、吨数 > 0。
+
+---
+
+## 8. 前端页面实现建议（klp-ui）
+
+### 8.1 组件拆分建议
+- `views/ems/oee/index.vue`（主页面）
+  - `OeeQueryBar`：查询区
+  - `OeeKpiCards`：KPI 区
+  - `OeeTrendCharts`：趋势区
+  - `OeeLoss7Panel`：7 大损失区
+  - `OeeEventTable`：明细区
+  - `OeeFormulaCard`：公式与口径说明（可折叠）
+
+### 8.2 公式展示（建议文案）
+页面“口径说明”中直接展示下列内容（与第 3 节一致）：
+- \( OEE = A \times P \times Q \)
+- \( A = (负荷时间-停机时间)/负荷时间 \)
+- \( P = (理论节拍 \times 产量)/实际运转时间 \)
+- \( Q = 良品数/总产量 \)
+
+并附“字段解释”与“边界规则”（第 6 节）。
+
+---
+
+## 9. 打印与 Word 导出设计
+
+当前会议使用**打印好的纸张**，因此 OEE 报表页面必须：
+- 在浏览器中**一屏内可阅读**，同时
+- 能以固定版式打印到 A4 纸上（或多页），并且
+- 能方便地导出到 **Word 文档** 中（便于留存与二次编辑）。
+
+### 9.1 页面布局对打印友好化
+
+- 整体布局遵循「自上而下」结构：
+  1. 标题 + 查询条件概览（日期范围、产线）
+  2. KPI 总览（两产线对比表格）
+  3. OEE & 三大指标趋势图
+  4. 7 大损失汇总表 + 图
+  5. 停机/损失明细表（可只打印 Top N，避免过多页）
+  6. 公式与口径说明
+- 为打印准备专用 CSS：
+  - 使用 `@media print` 隐藏页面导航、按钮等交互元素
+  - 控制分页：在关键模块间加 `page-break-before/after: always;`，保证章节不要被随机拆页
+  - 统一字体（建议 `SimSun` 或 `Microsoft YaHei`）与字号（正文 10–12pt）
+
+### 9.2 打印实现（浏览器直接打印）
+
+- 页面中提供 **“打印 OEE 报表”** 按钮：
+  - 触发 `window.print()`，由浏览器生成打印预览
+  - 打印模板由 `@media print` 样式控制
+- 打印前展示一个小弹窗/提示：
+  - 确认当前查询条件（日期范围、产线）
+  - 提示：如“明细表仅打印前 50 条记录”
+
+### 9.3 Word 导出方案（前后端二选一）
+
+#### 方案 A（推荐）：后端生成 Word 模板
+- 在 Java 后端使用如 **Apache POI** 或 **docx4j**：
+  - 准备一个固定 Word 模板（包括标题、表格样式、公司抬头等）
+  - 将 OEE 汇总、趋势（可只写数据表）、7 大损失、公式说明填入模板
+  - 返回 `application/vnd.openxmlformats-officedocument.wordprocessingml.document` 文件流
+- 前端仅需增加一个 **“导出 Word”** 按钮：
+  - 请求 `/oee/line/exportWord?startDate=...&endDate=...&lineIds=...`
+  - 将响应保存为 `.docx` 文件。
+
+#### 方案 B：前端转为 Word（适合作为备选）
+- 使用 JS 库（如 `html-docx-js` / `PizZip + Docxtemplater` 等）：
+  - 将页面区域（或结构化数据）转换为 docx
+  - 但对版式与中文支持不如后端模板稳妥
+
+> 综上，建议优先采用：**后端模板 + 导出 Word 接口**，前端仅承载触发与参数传递。
+
+---
+
+## 10. 验收标准（V1）
+- 支持选择日期范围，展示两条产线（酸轧线、镀锌一线）的：
+  - KPI：OEE、A、P、Q + 辅助数值
+  - 按日趋势：OEE + A/P/Q
+  - 7 大损失：分类时间损失 + 占比
+  - 明细：停机事件列表可筛选/分页
+- 页面包含“口径说明/公式展示”，且与接口口径一致
+- 任一指标可追溯：KPI 卡片能够对上分子/分母（至少时间稼动率与良品率）
+ - 页面支持 **直接打印为纸质报表**（版式稳定），并提供 **Word 导出** 功能
+
+---
+
+## 11. 需要你补充/确认的最少信息（不影响先做页面骨架）
+1. **产量计量单位**：酸轧/镀锌使用“吨/卷/件”的哪一个？能否统一？
+2. **标准节拍来源**：是否已有“产线/产品”标准节拍表？若暂时没有，V1 可先按产线固定一个标准值。
+3. **停机事件来源**：当前是否已有停机记录表（start/end/reason）？原因码是否稳定？
+
+---
+
+## 12. 后端实现与配置（用于前端对接与联调）
+
+### 12.1 路由前缀说明
+- **DA 聚合服务**（OEE 对外统一接口）：`/oee/line/*`
+- **WMS 回归服务**（内部数据源，DA 会代理调用）：`/wms/coilPendingAction/theoryCycle/regression`
+
+### 12.2 DA（klp-da）需要的配置项
+- `da.oee.acid-line-base-url`：酸轧线数据源服务地址（klp-pocket）
+- `da.oee.galvanize-line-base-url`：镀锌一线数据源服务地址（Fizz）
+- `da.oee.wms-base-url`：WMS 服务地址（用于代理调用理论节拍回归接口；不配默认 `http://localhost:8080`）
+- `da.oee.ideal-cycle-time-min-per-unit.sy`：理论节拍兜底值（分钟/吨）
+- `da.oee.ideal-cycle-time-min-per-unit.dx1`：理论节拍兜底值（分钟/吨）
+
+### 12.3 WMS 回归与缓存说明
+- WMS 会将回归的斜率（分钟/吨）写入 Redis：
+  - Key：`oee:ideal-cycle-time`，field：`SY` / `DX1`，value：`slopeMinPerTon`
+  - Key：`oee:ideal-cycle-time:intercept`，field：`SY` / `DX1`，value：`interceptMin`
+- DA 在计算 `summary/loss7` 时会优先使用回归斜率（并在 DA 内做 60s 本地 TTL 缓存），回归不可用时才回退到 `da.oee.ideal-cycle-time-min-per-unit.*`。