# 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.*`。