Files
klp-oa/docs/oee-report-design.md

493 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`)与字号(正文 1012pt
### 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
- 支持选择日期范围,展示两条产线(酸轧线、镀锌一线)的:
- KPIOEE、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 DAklp-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.*`