# 规则版本治理方案

## 1. 背景

当前“任务规则中心”的规则资产只有一个 `current_version` 指针。  
它同时承担了三种含义：

1. 财务人员正在编辑的版本
2. 审核中的候选版本
3. 系统运行时真正生效的线上版本

这会直接带来三个问题：

- 财务人员一旦修改 Excel，最新内容就会立刻成为 `current_version`，容易被误解为已经正式生效
- 审核、上线、回滚都围绕同一个指针转，权限边界不清晰
- 如果误上线，虽然能切换历史版本，但缺少“线上版本”和“工作版本”分离后的安全缓冲

## 2. 设计目标

这次改造要解决的不是“多存几个历史版本”，而是建立一套可长期使用的规则治理机制：

1. 财务人员可以编辑规则，但编辑结果默认只是草稿
2. 只有高级管理人员审核通过后，规则才能成为正式线上版本
3. 系统运行时只能读取正式线上版本，不能读取草稿
4. 前台要能清楚区分：
   - 当前线上版本
   - 当前工作版本
   - 最近 5 个历史版本
5. 如果误操作上线，可以快速恢复，但恢复动作仍然要留下完整审计链

## 3. 核心模型

### 3.1 双指针版本模型

在规则资产上新增两个版本指针：

| 字段 | 含义 |
| --- | --- |
| `published_version` | 当前正式在线上生效的版本 |
| `working_version` | 当前最新的工作稿 / 待审稿 |

兼容策略：

- 现有 `current_version` 暂时保留，用于兼容历史代码
- 对规则资产来说，后续它只承担“当前工作版本”的兼容语义
- 运行时逻辑不再读取 `current_version`，而是优先读取 `published_version`

### 3.2 版本状态

不额外在版本表中硬存一套容易失真的状态，而是根据“版本指针 + 最新审核记录”动态推导：

| 条件 | 版本状态 |
| --- | --- |
| `version == published_version` | 已上线 |
| `version == working_version` 且无审核记录 | 草稿 |
| `version == working_version` 且最新审核为 `pending` | 待审核 |
| `version == working_version` 且最新审核为 `approved` | 已通过待上线 |
| `version == working_version` 且最新审核为 `rejected` | 已驳回 |
| 其他历史版本 | 历史版本 |

这样可以避免“版本状态”和“审核记录”两套数据互相打架。

## 4. 权限边界

| 角色 | 能力 |
| --- | --- |
| 财务人员 `finance` | 编辑工作稿、上传/导入 Excel、提交审核 |
| 高级管理人员 `manager` / `admin` | 审核通过、驳回、正式发布、恢复历史版本 |
| 其他普通员工 | 只读 |

### 4.1 财务人员

- 可以直接编辑当前 `working_version`
- 每次保存自动生成新版本，并把它设为新的 `working_version`
- 不能把草稿直接变成 `published_version`

### 4.2 高级管理人员

- 可以对 `working_version` 发起：
  - 审核通过
  - 驳回
  - 正式发布
- 只有 `approved` 的工作版本才能发布

## 5. 发布与回滚流程

### 5.1 正常发布

1. 财务人员编辑并保存
2. 系统生成新版本，例如 `v1.0.6`
3. `working_version = v1.0.6`
4. 财务人员提交审核
5. 高级管理人员审核通过
6. 高级管理人员点击“正式上线”
7. `published_version = v1.0.6`
8. 系统运行时切换到新版本

### 5.2 驳回

1. 财务人员提交审核
2. 高级管理人员驳回
3. 当前工作版本保留，但状态显示为“已驳回”
4. 财务人员继续编辑，形成新的工作版本

### 5.3 恢复历史版本

不直接把 `published_version` 指回旧版本，而是采用“复制恢复”的方式：

1. 管理员在最近 5 个版本中选择一个历史版本
2. 系统基于该历史版本内容生成一个新的恢复版本，例如 `v1.0.7`
3. 新版本写入 `working_version`
4. 审核通过后再正式发布

这么做的好处：

- 不会破坏历史链路
- 每一次恢复都有明确的责任人与时间
- 既能快速回滚，又保留审计闭环

## 6. 版本保留策略

### 6.1 前台展示

- 详情页固定展示最近 5 个版本
- 每个版本显示：
  - 版本号
  - 状态
  - 创建人
  - 创建时间
  - 变更说明

### 6.2 后台保存

后台不能机械地“只保留 5 个版本”，否则可能把关键线上版本挤掉。  
建议策略：

1. 始终保留当前 `published_version`
2. 始终保留当前 `working_version`
3. 额外保留最近 5 个历史版本

这样既满足前台简洁，也能避免误删关键版本。

## 7. 前端交互

### 7.1 规则详情页顶部

展示两个醒目的版本标签：

- 当前线上版本
- 当前工作版本

如果两者不同，需要明确提示：

> 当前存在尚未上线的工作稿，系统运行仍以线上版本为准。

### 7.2 编辑区

- 财务人员看到“可编辑工作稿”
- 普通用户只读
- 管理员可编辑，但主要职责仍是审核与发布

### 7.3 版本区

最近 5 个版本中每条都显示状态：

- 已上线
- 草稿
- 待审核
- 已通过待上线
- 已驳回
- 历史版本

可执行操作：

- 查看
- 基于该版本恢复
- 对当前工作版本提交审核 / 审核 / 发布

## 8. 后端改造清单

1. `agent_assets`
   - 新增 `published_version`
   - 新增 `working_version`
2. 兼容旧数据
   - 历史规则资产初始化时：
     - `published_version = current_version`
     - `working_version = current_version`
3. 版本保存
   - 保存新版本后：
     - 只更新 `working_version`
     - `current_version` 同步为 `working_version` 以兼容旧逻辑
4. 审核
   - 审核只针对 `working_version`
5. 发布
   - 只允许把已审核通过的 `working_version` 推到 `published_version`
6. 运行时
   - 只读取 `published_version`
7. 回滚
   - 新增“基于历史版本恢复为新工作稿”的接口

## 9. 前端改造清单

1. 资产详情模型增加：
   - `publishedVersion`
   - `workingVersion`
   - 每个历史版本的派生状态
2. 规则详情页展示：
   - 当前线上版本
   - 当前工作版本
   - 最近 5 个版本
3. 操作权限拆分：
   - finance：编辑、上传、提交审核
   - manager/admin：审核、上线、恢复
4. OnlyOffice 编辑逻辑：
   - 默认编辑工作版本
   - 历史版本只读
5. 正式上线按钮：
   - 只有工作版本已审核通过时可用

## 10. 本次实现边界

本轮优先完成以下能力：

1. 规则版本双指针
2. 财务角色可编辑工作稿
3. 正式上线只切换 `published_version`
4. 运行时只读取 `published_version`
5. 最近 5 个版本展示
6. 基于历史版本快速恢复为新工作稿

后续如需要，再继续补：

- 版本差异对比
- 审核意见流转面板
- 发布说明 / 审批单号
- 定时生效