chore: 更新配置和构建脚本

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

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