chore: 更新配置和构建脚本

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

@@ -0,0 +1,453 @@
+# 规则版本中心 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 表格的：
+   - 工作表新增 / 删除
+   - 单元格新增 / 删除 / 修改
+

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