238 lines
6.6 KiB
Markdown
238 lines
6.6 KiB
Markdown
# 规则版本治理方案
|
||
|
||
## 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. 基于历史版本快速恢复为新工作稿
|
||
|
||
后续如需要，再继续补：
|
||
|
||
- 版本差异对比
|
||
- 审核意见流转面板
|
||
- 发布说明 / 审批单号
|
||
- 定时生效
|
||
|