X-Financial/document/development/rules/rule-version-center-ui-plan.md

# 规则版本中心 UI 方案

## 1. 背景

当前“任务规则中心 > 财务规则 > 公司差旅费报销规则”已经具备：

- 在线 Excel 编辑
- 工作版本 / 线上版本分离
- 最近 5 个版本展示
- 审核、上线、恢复能力

但页面仍然存在一个明显问题：  
**版本治理能力已经有了，用户却很难第一眼看见。**

当前版本列表更像“历史记录”，不是一个明确的“版本操作中心”。  
用户无法快速判断：

1. 当前真正生效的是哪个版本
2. 当前正在编辑的是哪个版本
3. 从哪里进入版本切换
4. 从哪里发起版本对比
5. 某个版本经历了哪些流转动作

因此，需要把现有“版本列表”升级为一个真正可用的 **版本中心**。

---

## 2. 设计目标

### 2.1 用户一眼能看懂

进入规则详情页后，用户无需点击就能立即识别：

- 当前线上版本
- 当前工作版本
- 是否存在未上线工作稿
- 最近版本是否处于待审 / 已通过 / 已驳回状态

### 2.2 关键操作显性化

以下操作不能再隐藏在不明显的位置：

- 切换查看版本
- 与线上版本对比
- 查看完整流转
- 从历史版本恢复

### 2.3 保持 OnlyOffice 是主角

该页面的核心仍然是 Excel 规则表。  
版本中心必须增强治理能力，但不能把主表格压缩成附属内容。

---

## 3. 推荐方案

采用：

> **左侧 OnlyOffice 主工作区 + 右侧版本中心 + 顶部显性入口 + 抽屉式详情**

这是比“单独开二级页签”更适合当前页面的方案，因为用户经常需要：

- 一边看表
- 一边知道自己看的是什么版本
- 一边进入版本对比或恢复

---

## 4. 页面整体布局

```text
┌────────────────────────────────────────────────────────────────────┐
│ 标题区：公司差旅费报销规则                                         │
│ 线上版本 v1.0.5 已上线    工作版本 v1.0.6 待审核                   │
│ [下载 Excel] [上传表格] [版本对比] [查看流转]                      │
├───────────────────────────────────────────────┬────────────────────┤
│                                               │ 版本中心           │
│                                               │                    │
│                                               │ ┌──────────────┐  │
│                                               │ │ 线上版本      │  │
│                                               │ │ v1.0.5        │  │
│                                               │ └──────────────┘  │
│                 OnlyOffice                    │ ┌──────────────┐  │
│                 规则表主工作区                 │ │ 工作版本      │  │
│                                               │ │ v1.0.6        │  │
│                                               │ └──────────────┘  │
│                                               │                    │
│                                               │ 最近版本           │
│                                               │ v1.0.6 待审核      │
│                                               │ v1.0.5 已上线      │
│                                               │ v1.0.4 历史版本    │
│                                               │                    │
│                                               │ 最近流转           │
│                                               │ [查看完整流转]     │
└───────────────────────────────────────────────┴────────────────────┘
```

---

## 5. 顶部操作区设计

顶部必须保留并强化四个动作：

| 按钮 | 用途 |
| --- | --- |
| 下载 Excel | 下载当前预览版本 |
| 上传表格 | 导入内容生成新工作稿 |
| 版本对比 | 打开对比抽屉 |
| 查看流转 | 打开流转抽屉 |

### 5.1 版本对比按钮

这是一级入口，不能只藏在版本列表里。  
默认行为：

- 基准版本：当前线上版本
- 对比版本：当前工作版本

如果两者相同，则按钮仍可用，但进入后提示：

> 当前工作版本与线上版本一致，可选择其他历史版本进行比较。

### 5.2 查看流转按钮

用于进入当前规则的完整生命周期视图。  
不应只展示审计日志，而要展示“版本业务履历”。

---

## 6. 右侧版本中心设计

### 6.1 顶部双版本卡片

```text
线上版本
v1.0.5
已上线

工作版本
v1.0.6
待审核
```

#### 设计目的

用户进入页面后，最先要知道的是：

- **谁在线上**
- **谁正在被编辑**

而不是先看一个无上下文的历史列表。

### 6.2 最近版本列表

每个版本项包含：

- 版本号
- 生命周期状态
- 创建时间
- 变更说明
- 操作入口

建议样式：

```text
v1.0.6    待审核
2026-05-18 09:12
补充出差补助标准
[查看] [与线上比]

v1.0.5    已上线
2026-05-18 08:40
新增补助页签
[查看]

v1.0.4    历史版本
2026-05-17 17:20
修正住宿标准
[查看] [恢复]
```

#### 规则

- `查看`：切换当前预览版本
- `与线上比`：直接以线上版本为基准进入对比
- `恢复`：仅高级管理人员可见
- 当前 `working_version` 不显示“恢复”

### 6.3 最近流转摘要

右侧版本中心底部展示最近 3 条流转：

```text
最近流转
09:12 曹笑竹 保存工作稿
09:25 曹笑竹 提交审核
10:08 顾承宇 审核通过
[查看完整流转]
```

---

## 7. 版本流转时间线设计

## 7.1 入口

两个入口：

1. 顶部 `查看流转`
2. 右侧版本中心底部 `查看完整流转`

## 7.2 容器

使用右侧宽抽屉，不使用小弹窗。  
原因：

- 时间线内容会逐步增长
- 审核意见需要足够宽度展示
- 后续可能接入版本说明、操作人、来源版本

## 7.3 时间线内容

时间线按时间倒序或正序展示，推荐默认正序：

```text
● 2026-05-18 09:12
  v1.0.6 工作稿创建
  曹笑竹 保存工作稿
  变更说明：补充出差补助标准

● 2026-05-18 09:25
  提交审核
  曹笑竹 提交当前工作版本

● 2026-05-18 10:08
  审核通过
  顾承宇：口径已核对，可上线

○ 待正式上线
```

如果版本来自恢复：

```text
● 基于 v1.0.3 恢复生成 v1.0.7
```

## 7.4 时间线事件类型

| 事件类型 | 说明 |
| --- | --- |
| `created` | 创建版本 |
| `submitted` | 提交审核 |
| `approved` | 审核通过 |
| `rejected` | 驳回 |
| `published` | 正式上线 |
| `restored` | 基于历史版本恢复 |

---

## 8. 版本差异对比设计

## 8.1 入口

版本对比必须有两个入口：

1. 顶部一级按钮：`版本对比`
2. 每个历史版本行内操作：`与线上比`

这样既满足“主动进入”，也满足“看到某个版本就顺手比较”。

## 8.2 容器

使用宽抽屉，推荐宽度：

- 桌面：页面宽度的 70% ~ 80%
- 小屏：全屏

不建议用普通弹窗，因为：

- Excel 差异需要足够展示宽度
- 版本选择器、摘要、表格都要共存

## 8.3 顶部区域

```text
版本对比

基准版本 [v1.0.5 已上线 ▼]
对比版本 [v1.0.6 待审核 ▼]
```

默认值：

- `baseVersion = published_version`
- `targetVersion = working_version`

## 8.4 差异摘要

优先先给决策信息，再给底层明细。

```text
差异摘要
- 修改 2 个工作表
- 新增 1 个工作表
- 修改 12 个单元格
- 删除 2 行
```

如果无差异：

```text
两个版本内容一致，没有发现表格差异。
```

## 8.5 差异详情

第一阶段优先支持 Excel 规则表：

| 工作表 | 位置 | 旧值 | 新值 | 类型 |
| --- | --- | --- | --- | --- |
| 出差补助标准 | B4 | 75 | 90 | 修改 |
| 差旅住宿费标准 | A106 | - | 新增城市 | 新增 |

后续可扩展：

- 仅看新增
- 仅看删除
- 仅看数值变化
- 按工作表筛选

## 8.6 对比结果的业务语气

不要把页面做成“程序员 diff 工具”。  
它应该像制度审核页面：

- 先讲影响
- 再讲位置
- 最后给证据

---

## 9. 数据接口设计

## 9.1 时间线接口

建议新增：

```http
GET /agent-assets/{asset_id}/version-timeline
```

返回：

- 版本号
- 事件类型
- 操作人
- 操作时间
- 审核意见
- 来源版本（如有）

## 9.2 对比接口

建议新增：

```http
GET /agent-assets/{asset_id}/versions/compare?base_version=v1.0.5&target_version=v1.0.6
```

返回：

- 基准版本
- 对比版本
- 工作表差异摘要
- 单元格级差异明细

---

## 10. 视觉规范

### 10.1 颜色

沿用当前系统已有色彩，不引入新风格：

| 状态 | 建议色 |
| --- | --- |
| 已上线 | 绿色 |
| 工作稿 | 蓝色 |
| 待审核 | 橙色 |
| 已驳回 | 红色 |
| 历史版本 | 灰色 |

### 10.2 密度

- 右侧版本中心应为紧凑型信息面板
- 不要使用过大的卡片间距
- 不能明显压缩 OnlyOffice 主区域

### 10.3 交互反馈

- 可点击元素必须有 hover
- 当前预览版本必须有 active 高亮
- 抽屉打开后保留明确关闭按钮
- 恢复操作必须二次确认

---

## 11. 推荐实施顺序

### 第一阶段

1. 顶部新增 `版本对比`、`查看流转`
2. Excel 详情页改成：
   - 左侧 OnlyOffice
   - 右侧版本中心
3. 右侧展示：
   - 线上版本
   - 工作版本
   - 最近 5 个版本
   - 最近 3 条流转

### 第二阶段

1. 实现版本流转抽屉
2. 实现版本对比抽屉
3. 补齐真实后端接口

### 第三阶段

1. 增加更细的工作表筛选
2. 增加更多 diff 维度
3. 增加版本差异导出能力

---

## 12. 本次开发目标

本次开发直接完成以下内容：

1. 规则详情页出现明确的版本中心
2. 页面上出现明确的：
   - `版本对比`
   - `查看流转`
3. 最近版本列表增加：
   - `查看`
   - `与线上比`
   - `恢复为工作稿`
4. 版本流转抽屉可用
5. 版本对比抽屉可用
6. 对比结果至少支持 Excel 表格的：
   - 工作表新增 / 删除
   - 单元格新增 / 删除 / 修改