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

规则版本治理方案

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. 基于历史版本快速恢复为新工作稿

后续如需要，再继续补：

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