# 故障处置（车辆运维）设计规格

| 项 | 说明 |
|---|---|
| 日期 | 2026-07-22 |
| 状态 | 已确认 |
| 方案 | 方案一：新建原型 + 工作台同源数据 |
| 原型 ID（拟定） | `vehicle-fault-handling` |
| 菜单 | OneOS → 车辆运维 → 故障处置 |
| 关联 | `oneos-web-workbench-new`（预警 KPI + 运维看板故障登记） |

---

## 1. 问题与目标

运维需要承接 **AI 故障机器人**上报的原始故障（聊天摘要、图片、视频），在系统内完成处置、挂起与归档，并满足 **30 天闭环** 时限与催办。处置记录须足够详细，作为日后向整车厂索赔的**证据链**基础。

**本期目标**

1. 新建「故障处置」列表 + **独立详情页**，完成待处理 → 处理中 → 挂起 → 已归档。
2. 证据链多附件与归档硬门槛。
3. 时限与通知规则演示（含短信/邮件模板与发送记录，不接真实通道）。
4. 工作台预警 KPI + 运维看板「故障登记」与本模块同口径。

**非目标（二期 / 占位）**

- AI 对话上报界面（机器人仅作数据来源）
- 真实短信 / 邮件网关
- 品牌 · 车型 · 部位 · 等级完整分类统计看板
- 按品牌车型一键出具故障证明与自动分析结论（本期仅入口占位）

---

## 2. 信息架构

```text
OneOS
└── 车辆运维（新一级菜单）
    ├── 故障处置          ← 本期主功能
    ├── 分类统计          ← 二期占位
    └── 故障证明          ← 二期占位
```

- 新建原型目录：`src/prototypes/vehicle-fault-handling/`
- 不改造旧合包 `oneos-web-ops` 内「故障管理」页为唯一入口；旧页可暂并存，导航以新菜单为准。
- AI 上报：无 UI；以种子数据模拟「已入库的待处理原始记录」。

---

## 3. 状态机

| 状态 | 进入条件 |
|------|----------|
| 待处理 | AI 上报后系统自动入库 |
| 处理中 | 运维首次保存处置内容（可分次保存） |
| 挂起 | 运维选择暂时挂起，**必须填写挂起原因** |
| 已归档 | 通过归档硬门槛，完成闭环 |

**流转规则**

- `待处理` → 首次保存 → `处理中`
- `待处理` / `处理中` → 挂起 → `挂起`
- `挂起` → 恢复继续 → `处理中`
- `处理中` → 归档校验通过 → `已归档`
- **挂起不可直接归档**；须先恢复为处理中，补齐硬门槛后再归档

---

## 4. 时限规则（文档中的「SLA」含义）

此处 **SLA = 处理时效约定**，非另有系统模块：

- 时针从 **故障记录上报时刻** 起算，**30 个自然日内必须已归档**
- **暂时挂起不停表**（挂起期间仍计入 30 天）

| 时机 | 条件 | 收件人 | 通道 | 频次 |
|------|------|--------|------|------|
| 临期 | 未归档，且剩余天数 ≤ 7（未逾期），进入临期窗口时触发 | 当前处理人；无人接手 → 运维主管 | 短信 + 邮件 | 进入临期窗口触发一次 |
| 逾期升级 | 已超 30 天，仍未归档 | **固定运维主管** | 短信 + 邮件 | 逾期当天 1 次；之后 **每周 1 次**，直至归档 |

原型：展示「通知记录」列表与模板正文；标记「已发送（演示）」，不接真实通道。

### 4.1 通知模板

**临 7 天 · 短信**

```text
【OneOS故障】${故障号} ${车牌/车型} 将于 ${截止日} 到期（剩7天）仍未归档，请尽快处置。详情见故障处置。
```

**临 7 天 · 邮件**

- 标题：`【故障临期提醒】${故障号} 距闭环截止还剩 7 天`
- 正文须含：故障号、车辆、上报时间、当前状态、截止日、处理人、系统链接

**超 30 天 · 短信**

```text
【OneOS故障·逾期】${故障号} 已超 30 天未归档（状态：${状态}），请主管督促闭环。
```

**超 30 天 · 邮件**

- 标题：`【故障逾期升级】${故障号} 已超过 30 天未归档`
- 正文须含：上述字段 + 逾期天数、历史挂起原因摘要、末次催办时间

---

## 5. 页面结构

采用 **列表 + 独立详情页**（非抽屉）。

### 5.1 列表页

- 筛选：状态、等级、品牌/车型、临期、逾期
- 搜索：故障号、车牌
- 列：故障号/车辆、部位·等级、状态、剩余天数（或逾期天数）、操作「处置」
- 临期 / 逾期视觉标识

### 5.2 详情页分区

1. **原始记录（只读）**：AI 聊天摘要、图、视频  
2. **处置主档**：故障时间、地点、部位、等级、处置结果、备注、关联车辆（品牌/车型/车牌）  
3. **证据链**：多附件（图片、视频、PDF、Word 等常用类型）；可预览示意；记录文件名、类型、上传人、时间  
4. **挂起与通知**：挂起原因历史；短信/邮件发送记录  
5. **底栏**：保存（→ 处理中）· 挂起 · 归档（硬门槛）

### 5.3 归档硬门槛

必须全部满足方可归档：

- 故障时间、地点、部位、等级、处置结果  
- 至少 **1** 个证据附件  
- 备注选填  

任一缺失：阻断归档并提示缺项。

---

## 6. 工作台接入

数据与 `vehicle-fault-handling` **同源**（本地共享种子 / `src/common` 模块，未接真实 API）。

### 6.1 欢迎区预警 KPI（运维角色可见；多角色并集规则沿用工作台现规）

| 指标 | 口径 | 点击 |
|------|------|------|
| 临 7 天未归档 | 未归档且剩余天数 ≤ 7 且未逾期 | 故障处置列表 · 临期筛选 |
| 已超 30 天未归档 | 未归档且已过截止日 | 列表 · 逾期筛选 |
| 待处理积压 | 状态 = 待处理 | 列表 · 待处理 |

### 6.2 运维看板「故障登记」

- 总数 = 全部故障记录（含已归档）  
- 已归档 = 状态为已归档  
- 闭环率 = 已归档 / 总数  
- 可辅显：挂起数、临期数  
- 可见性：主管/兼岗全量 + 按人筛；普通运维本人/本地区（沿用现有 `OpsCockpit` 规则）

---

## 7. 数据对象（摘要）

`FaultRecord` 主要字段：

- 标识：故障号、上报时间、截止时间、来源（AI）  
- 状态与处理人  
- 原始：聊天摘要、媒体列表  
- 处置：时间、地点、部位、等级、结果、备注、车辆引用  
- 证据附件列表、挂起历史、通知历史  

二期统计 / 证明所需的品牌、车型、部位、等级字段在一期处置主档中已采集，证明生成逻辑本期不做。

---

## 8. 组件与实现边界（实现阶段指引）

| 单元 | 职责 | 依赖 |
|------|------|------|
| `vehicle-fault-handling` 原型 | 列表、详情、状态流转、证据链、通知演示 | 共享故障种子 |
| 共享数据模块（如 `src/common/vehicle-fault/`） | 记录类型、状态派生、时限计算、看板/KPI 聚合 | 无真实 API |
| `oneos-web-workbench-new` | KPI 瓦片 + OpsCockpit 故障列改读共享数据 | 共享模块 |
| 导航 | `nav-menu.json` 增加车辆运维 / 故障处置；`nav:sync` | — |

错误处理：归档校验失败明确列出缺项；挂起无原因不可提交。

---

## 9. 已确认决策记录

| 决策点 | 选择 |
|--------|------|
| AI 端 | 仅数据来源，不做对话 UI |
| 落地路径 | 方案一：新原型 + 工作台同源 |
| 菜单 | 车辆运维 → 故障处置 |
| 中间态名称 | 处理中 |
| 挂起与时针 | 不停表 |
| 临 7 天含义 | 未归档且剩余天数 ≤ 7（未逾期） |
| 一期范围 | 处置闭环 + 证据链；统计/证明占位 |
| 归档 | 硬门槛 |
| 工作台 | 预警 + 看板都接 |
| 临期收件人 | 处理人，无人接手→主管 |
| 逾期 | 固定主管；当天 1 次 + 每周 1 次 |
| 详情布局 | 列表 + 独立详情页 |

---

## 10. 验收重点（设计层）

1. 种子数据入库即为待处理；保存后为处理中；挂起必填原因；归档卡硬门槛。  
2. 列表可按临期/逾期筛选；详情可看原始记录与证据链。  
3. 通知记录可演示临期与逾期模板内容。  
4. 工作台运维角色可见三类故障预警；看板故障登记闭环率与模块数据一致。  
5. 菜单路径正确；二期入口为占位说明。