ln-bi/docs/asset-fault-management.md

# 故障管理

2026-10-13：故障管理为左侧独立业务入口 `/asset#faults`，与资产管理并列。首页展示四项总统计及故障趋势统计，不展示旧版维度排行或常驻故障明细。点击任一卡片进入多维分析，再进入故障明细。

## 四项指标

| 指标 | 口径 |
| --- | --- |
| 今日新增 | `fault_report_time` 在北京时间今日自然日内 |
| 本日解决 | 状态已归档且 `archived_at` 在北京时间今日内，与提报日无关 |
| 当前在办 | 全部待处理、处理中故障，不限制提报日期；按最新确认，在办 = 待处理 + 处理中 |
| 累计台账 | 全部有效故障台账，包括归档、未闭环和其他状态 |

「当前在办」卡片以“待处理 ＋ 处理中”展示构成，逾期以总量旁的“逾期”独立标记，均使用故障多维分析与故障明细下钻。按最新确认，在办仅为待处理与处理中之和，挂起保留在累计台账；旧兼容接口的全部未闭环口径保持不变。

- 待处理/处理中：按 OneOS 标准化任务状态分别统计，兼容待处置、未处理、处置中等历史值。
- 逾期：待处理或处理中，且保存的 `deadline_at` 严格早于本次数据时间。按北京时间解释截止时间，挂起和已归档不计入；无截止时间不自行以提报时间或固定 30 天推算。与 OneOS `selectSupervisorRows.overdueCount` 汇总口径一致，存储的截止时间包含业务端 SLA 配置及挂起顺延结果。
- 逾期是当前在办的重叠子集，不与待处理、处理中相加。下钻明细不展示处置截止时间，也不提供该字段的统计维度；该字段仅保留用于逾期计算。
- 四张卡片使用统一紧凑高度：桌面 164px、移动端 132px。

所有数量以故障主键去重、单位为“单”；同车多故障分别统计。有效范围为 `vehicle_fault_manage.del_flag='0' AND is_submit IN (0,1)`。保留退出运营、缺失车辆关联的历史故障；缺失日期不以创建时间补齐。

## 下钻

在资产管理九个维度（车型、型号、区域、城市、部门、业务负责人、客户、资产用途、运营状态）基础上，增加独立的「运维处置人」「车牌」「故障工单状态」，共十二个维度，「运维处置人」固定为第二个维度选项，「车牌」为第三个。车牌取故障台账车牌，同车多故障按故障单计数，缺失车牌归入「未关联车辆」。支持组合分组、多选筛选、合并单元格、组内小计、排序、筛选此组、故障明细搜索和分批加载。运维处置人与业务负责人独立，按人员 ID 分组，同名不同 ID 不合并；多人共同处置分别计入各人，总数、上级小计和明细按故障去重，人员行不可直接相加。

车辆相关维度使用车辆当前资料，运维处置人取故障或关联工单的当前处置分配。城市使用 OneOS `vehicle_info.operation_city` 对应的城市，不使用车机 GPS；区域采用 Asset BI 的宏观区域映射。客户/部门/业务负责人取每车最新 `vehicle_lease_order_record`，按 `last_delivery_time DESC,id DESC`，型号与车型复用资产管理的别名和分类函数。无匹配资料保留未知组。客户键采用散列，展示名称脱敏，不因相同脱敏名称合并不同客户。

明细第一列主显示车牌、辅显示故障单号，第二列为运维处置人；其后依次展示故障描述、状态、提报时间、归档时间、运营城市、客户 / 部门。处置人来源优先级：有效来源任务工单多人→任务工单单人→故障多人→故障单人或历史姓名；用户 BIGINT ID 保持字符串精度，停用/删除人员保留历史姓名。

## 权限与接口

- `GET /api/asset-faults/overview`：北京时间日期、数据时间、四项总数。
- `GET /api/asset-faults/analysis?metric=reported|closed|open|waiting|processing|suspended|overdue|ledger`：所选指标的授权记录及分析单元，供前端在同份数据上分组和下钻。
- 旧 `GET /api/asset-faults` 查询接口保留兼容，首页不再使用。

接口以只读一致性事务读取数据，不修改 OneOS 业务表，不运行定时任务或迁移。汇总及下钻先应用既有全量/部门/本人权限；历史故障不继承公共库存的权限放宽规则；缺车辆资料仅全量权限可见。无共享响应缓存，HTTP `no-store`。401 未认证、400 无效参数、503 查询失败。首页和下钻分别读取最新数据，实时变化可能造成短暂数量差异。

源码依据（`oneos/ln-asset-management`）：`FaultLedgerStatus`、`FaultLedgerQuerySupport`、`FaultManualCreateSupport`、`FaultHandlerAssignmentService.resolveForSupervisorBatch`、`VehicleFaultDispositionServiceImpl.archiveNow`、`VehicleFaultDispositionMapper.xml`、`VehicleLeaseOrderRecordMapper.xml`。

## 验证

故障模型与路由测试覆盖北京时间午夜边界、跨日归档、全部日期在办、累计范围、权限隔离、客户脱敏、同车多故障、资产维度映射及总数与明细一致。同步运行导航、资产分组/筛选/合并单元格回归、TypeScript检查、生产构建及桌面/手机 Playwright 交互验证。仅本地开发，未部署。

## 故障趋势统计

复用交还车的日期选择器，默认北京时间近30天，支持自选日期（最多370天）、按日/按月切换。以 `fault_report_time` 划分新增批次，统计同一批故障截至查询时刻的已闭环（已归档）和未闭环（其他状态，含挂起）。不将该日归档的其他批次故障混入，归档时间可在提报区间之后。

堆叠柱总高度为新增数，新增 = 已闭环 + 未闭环。零新增周期补零；无提报时间不进入趋势；月聚合严格保持起止边界，不扩展整月。每日/每月统计表按新日期在前展示新增、已闭环、未闭环和闭环率（零分母显示横线）。汇总与周期数字均可下钻到故障多维分析及故障明细。点击柱图内已闭环 / 未闭环色块，按对应日或月和状态下钻；趋势下钻默认按「运维处置人 → 故障工单状态」分组，重置也恢复这两个维度，按月仍保留所选日期边界。

接口 `GET /api/asset-faults/trend?start=YYYY-MM-DD&end=YYYY-MM-DD&granularity=day|month` 返回区间汇总与周期序列。`GET /api/asset-faults/trend-analysis` 使用同样区间及粒度，可附 `period=YYYY-MM-DD|YYYY-MM` 和 `status=all|closed|unclosed`。两个接口均先应用原有数据权限，范围/粒度/周期校验在查询数据库前执行。总览和下钻按请求分别读取最新数据。

## 故障运维周报

周报复用故障处理趋势的日期选择器，默认业务周（周六至周五），支持自选最多370天。按最新要求仅展示「新增故障」「解决故障」两项区间合计、日期倒序的每日数量及表尾合计，均可下钻。汇总下方增加每日折线图，蓝色实线表示新增故障，绿色实线表示解决故障，与日期选择器、每日统计表使用同一份数据；补齐零值日期、纵轴从零开始，保留表格提供精确数量与下钻。

- 新增故障：按 `fault_report_time` 当日计单。
- 解决故障：已归档故障按 `archived_at` 当日计单，不受提报日期限制。

已移除接收处理汇总、每日列、说明及故障明细中的接收时间列。现有接口暂保留接收指标兼容能力，页面不使用；不更改业务数据。

接口：`GET /api/asset-faults/weekly-report?start=YYYY-MM-DD&end=YYYY-MM-DD`；下钻 `GET /api/asset-faults/weekly-report-analysis` 传 `metric=reported|closed`，可附 `day=YYYY-MM-DD`。所有计数和下钻均先应用既有业务数据权限，沿用只读事务及 HTTP no-store。

页面时间标签统一为「解决时间」，底层仍取 `archived_at`，统计口径不变。周报折线图仍按时间正序，采用平滑实线、顶部图例、浅网格与统一悬浮提示。

故障工单状态独立于车辆运营状态：已归档为「已闭环」，其他状态（含待处理、处理中、挂起）均为「未闭环」，与故障处理趋势口径一致。所有故障下钻入口均可按该维度分组、多选筛选、查看明细。

所有下钻明细按提报时间倒序展示，无提报时间排在末尾；同一提报时间按故障 ID 倒序稳定排序。先筛选、排序，再分页，搜索和加载更多保持该顺序。

客户展示：已关联车辆且当前运营状态为库存、客户为空时，客户分组、筛选和明细显示「库存车」（独立键 `inventory-unlinked`）；非库存或缺失车辆资料的空客户仍为「未关联客户」。有客户名称时仍按原客户展示和脱敏。此调整不改业务数据及权限。

下钻维度和筛选按入口保存在当前页面内存中；关闭、误点遮罩或 Esc 后重新打开恢复已应用设置。各入口互不覆盖，桌面与手机共用。点击重置恢复该入口默认维度并清空筛选；刷新整个页面后全部清除，不写入 localStorage 或跨刷新存储。每次重开仍重新请求实时数据。

## 报表导出

故障处理趋势和故障运维周报标题右侧均提供「导出 Excel」。导出当前已加载且经过权限过滤的统计快照；日期范围、趋势按日/按月粒度与页面一致，不重新查询或扩大数据范围。加载中及请求失败时禁用导出，生成文件期间显示进度状态并防止重复点击，失败可重试。

- 趋势：提报日期/月份、新增故障、已闭环、未闭环、闭环率，包含全部统计日期，按日期倒序。
- 周报：日期、星期、新增故障、解决故障，按日期倒序；不导出接收处理指标。
- XLSX 包含带标题、范围、数据时间、汇总指标的统计表；当前有图表时附加「图表」工作表，以图片保存页面图表快照并保持比例。图表为静态快照，修改统计表不会联动图表。
- 统一深色表头、指标配色、交替底色、今日浅色标记；真实 Excel 日期和数字格式、合计及闭环率公式、冻结表头、筛选与打印设置。ExcelJS 按导出操作动态加载。

## 风险与服务分析总览（2026-10-13）

故障管理按最新确认保留「管理总览 / 多维分析 / 故障明细」三个页签。管理总览与处理效率合并，恢复原有页面及统计：今日新增、本日解决、当前在办（待处理 + 处理中，逾期为子集）、累计台账，沿用 `/overview` 接口；下方直接展示原有故障处理趋势与故障运维周报。趋势默认近30天，周报默认周六至周五，分别选择日期、导出和下钻。管理总览不受其他页签的业务筛选影响。多维分析、故障明细保留新增分析能力及统一日期、区域、客户、品牌车型查询；更多筛选包含城市、业务部门、运维处置人、故障程度、故障部位、库存状态，点击查询生效。

- 期间新增故障：所选提报日期内的有效故障。卡片增加“运维提报”和“AI提报”数量及下钻；两者之和等于期间新增，沿用日期、权限及业务筛选。来源优先读取 `report_method`：运维上报显示“运维提报”，客户上报显示“AI提报”；旧数据未标明有效上报方式时，有真实 `source_work_order_id` 关联归客户上报，否则归运维上报，与 OneOS 历史展示逻辑一致。该分类不使用 `fault_source` 故障来源字典，也不推断所有客户上报均由 AI 自动创建。对比上期采用紧邻本期、天数相同的区间；上期为零时显示无可比基数。
- 受影响车辆：同批故障按关联车辆 ID 去重，缺 ID 时使用故障车牌；两者都缺失的不计车辆数，单列数据完整性提示。车辆跨组可能重复，不直接累加。
- 当前在办：已应用业务筛选下，所有日期的待处理 + 处理中。逾期为其子集；最长逾期按截止时间到数据时间的天数向上取整。
- 区域、等级、客户、车型分布和车型×部位矩阵：按本期提报队列统计，闭环状态截至更新时间。一单多部位分别计入单元格，车型合计按单去重。
- 客户影响表：本期影响车辆去重；同一客户的当前在办不限提报日期。库存空客户单列库存车。仅展示本期存在故障的客户组。
- 重点跟进：只展示 L1-特急且未闭环（状态非已归档，含挂起等）的故障，沿用权限及业务筛选，不限制提报日期。逾期优先，同优先级按提报时间倒序，最多展示5单；统计标签使用同一 L1 未闭环范围，没有符合条件的故障时显示空态。“查看全部”始终可用，进入当前权限内的全部故障台账，清除业务筛选和搜索条件，不限等级、状态及提报日期。完整明细可切换本期、在办、逾期及累计台账，搜索车牌、单号、描述或运维处置人。

新增只读字段：`fault_level`、`fault_categories`、`solve_process`。等级映射经 OneOS 字典核对：1=L1-特急、2=L2-紧急、3=L3-一般、4=L4-提示；缺失等级/部位独立显示未标注。处置记录使用 `solve_process`，不将 AI 流转字段 `process_status` 当作业务处理进度。没有同期服务车辆规模、实际停运和修复时长依据，发生频率禁用并提示缺少分母，停运和修复时长提示待补数据。

新增接口：
- `GET /api/asset-faults/dashboard?start=YYYY-MM-DD&end=YYYY-MM-DD`：授权范围内汇总、筛选项、分布、交叉矩阵、重点跟进和完整性信息。
- `GET /api/asset-faults/dashboard-analysis`：同样日期和业务筛选；`scope=focus|cohort|open|waiting|processing|overdue|ledger|reported|closed`。focus 为全部提报日期的 L1 未闭环故障；cohort 为提报日期队列，reported/closed 为北京时间今日，其他为全部日期当前状态；可附 `id` 查看单条记录。
- 趋势、周报及其下钻接口同时支持上述业务筛选。所有接口先执行权限筛选，筛选项也仅来自授权记录，保持 no-store，不写业务数据库。

总览导出新增 6 张 Excel 工作表：管理总览、区域分布、故障程度、客户影响、车型分布、车型与部位。导出已加载统计快照，包含日期、业务筛选、数据时间、冻结表头、交替底色和数字格式。趋势、周报的既有导出保留，并增加业务筛选说明。