# 规则版本管理功能 PRD

## 1. 文档信息

| 属性 | 值 |
|------|-----|
| 文档名称 | 规则版本管理功能 PRD |
| 所属模块 | 全知平台 / 风控模块 / 风险规则 |
| 文档版本 | v1.1 |
| 编写日期 | 2026-05-27 |
| 编写目的 | 为风险规则建立显式版本管理体系，为后续准确率追踪打基础 |

---

## 2. 背景与需求

### 2.1 业务背景

平台已实现 AI 规则和普通规则的疑点甄别功能（确认/排除疑点），但准确率追踪功能尚未实现。准确率追踪需要将准确率数据绑定到具体的规则版本上，才能通过版本迭代看出准确率的变化趋势。

当前规则没有显式的版本概念——版本仅隐式存在于区块链事件的标签中，数据模型中没有版本字段，页面上也没有版本管理入口。

### 2.2 当前系统能力分析

| 能力项 | 现有情况 | 差距 |
|--------|---------|------|
| 规则编辑 | 已上线规则支持原地编辑并上链 | 保存时声称"生成新版本"但无实际版本管理 |
| 区块链存证 | 链事件可携带 `version` 标签 | 无独立的版本数据结构，版本号无统一管理 |
| 版本查看 | 无 | 规则详情页无版本历史入口 |
| 存量规则 | 无版本标记 | 需要统一迁移到 V1 |

### 2.3 为什么需要手动发布版本

编辑保存和版本发布是两个不同粒度的操作：
- **编辑保存**：修正错别字、调整措辞、更新制度关联等日常操作，不需要产生新版本
- **版本升级**：监控逻辑变更、风险等级调整、阈值修改等有意义的变更，需要正式记录为新版本

手动触发确保每个版本都有明确的业务含义，避免版本号膨胀。

### 2.4 版本与规则状态的关系

版本是"已上线"规则的概念：
- 草稿/审核中规则 → 无版本
- 首次上线 → 自动成为 V1（系统自动完成，无需用户操作）
- 后续需要变更版本 → 用户手动点击"版本升级"按钮

---

## 3. 设计原则

### 3.1 手动触发

版本发布由用户主动点击"版本升级"按钮触发，编辑保存不自动升版本。首次上线自动 V1，后续版本升级需手动操作。

### 3.2 简单递增

版本号采用简单递增格式：V1, V2, V3...，不区分主版本/次版本。

### 3.3 全量快照

每个版本存储规则全量快照（基本信息 + 技术信息），不做差分存储，便于后续查看历史版本。

### 3.4 编辑保存与版本发布分离

| 操作 | 数据变更 | 上链 | 版本号变化 |
|------|----------|------|-----------|
| 编辑保存 | 是 | 是 | 不变 |
| 版本升级 | 否（快照当前状态） | 是 | +1 |

### 3.5 权限复用

版本发布按钮的可见性与编辑按钮一致：管理员 + 规则提交人可见。

---

## 4. 功能范围

| ID | 功能 | 说明 | 优先级 |
|----|------|------|--------|
| F1 | 当前版本展示 | 规则详情页头部操作区显示当前版本号 | P0 |
| F2 | 版本升级按钮 | 详情页头部操作区，权限控制，仅"我的规则"入口显示 | P0 |
| F3 | 版本升级流程 | 快照 + 版本号递增 + 上链 + 确认弹窗 | P0 |
| F4 | 版本历史Tab | 规则详情页新增版本历史Tab | P0 |
| F5 | 列表页版本列 | 我的规则、公共规则库列表显示当前版本 | P0 |
| F6 | 存量规则迁移 | 已上线规则统一标记为 V1 | P0 |

### 不在范围内

- 版本对比（Diff）
- 版本回滚/恢复
- 按版本的准确率追踪（下一期实现）
- 列表页按版本筛选
- 规则验证环节的版本管理

---

## 5. 功能详细说明

### 5.1 F1：当前版本展示

**位置**：规则详情页头部操作按钮组左侧。

**展示形式**：
```
← 返回我的规则                    [V5]  [版本升级]  [编辑]
```

**样式**：蓝色描边圆角标签（`#409EFF` 文字，`#ecf5ff` 背景，`#b3d8ff` 边框），13px 字号。

**显示文案**：`当前版本号V1`、`当前版本号V2`...

**无版本时**：不显示版本标签（草稿/审核中规则无版本概念）。

**入口控制**：
- 从"我的规则"进入（`from=my`）：显示版本标签、版本升级按钮、编辑按钮
- 从"公共规则库"进入（`from=public`）：不显示版本标签、不显示版本升级按钮、不显示编辑按钮

---

### 5.2 F2：版本升级按钮

**位置**：规则详情页头部操作区，"编辑"按钮左侧。

**按钮名称**：`版本升级`

**展示形式**：
```
← 返回我的规则                    [V5]  [版本升级]  [编辑]
```

**按钮样式**：与"编辑"按钮同系列同尺寸，但底色不同（`#2b7de9` 深蓝），视觉上更突出，表示这是一个重要操作。

**显示条件**（需同时满足）：

| 条件 | 结果 |
|------|------|
| 来源为"我的规则"（`from=my`） | 否则隐藏整个操作区 |
| 规则已上线 | 否则无版本概念 |
| 用户是管理员 或 规则提交人 | 否则隐藏 |

**禁用状态**：编辑模式下按钮禁用，tooltip 提示"请先保存或取消当前编辑"。

---

### 5.3 F3：版本升级流程

```
用户点击"版本升级"
    │
    ├── 检查：是否在编辑模式？
    │       └── 是 → 禁用按钮
    │
    ├── 打开确认弹窗
    │       标题：发布新版本（蓝色，tag图标）
    │       内容：
    │         - 当前版本：V5 → 新版本：V6
    │         - 升级说明 textarea（必填）
    │         - 警告："发布后将生成新版本快照并上链记录，版本号不可回退"
    │
    ├── 点击"确认发布"
    │       1. 快照当前规则数据（basic + tech）
    │       2. 版本号递增：V5 → V6
    │       3. 更新 ruleDatabase[code].currentVersion
    │       4. 新增 versionHistoryMap[code] 条目
    │       5. 新增链事件到 chainLifecycleMap[code].chain
    │       6. 更新版本徽章
    │       7. 刷新版本历史Tab（如激活）
    │       8. 刷新区块链信息Tab
    │       9. 提示"版本 V6 已发布成功并提交上链"
    │
    └── 点击"取消" → 关闭弹窗
```

---

### 5.4 F4：版本历史Tab

**位置**：规则详情页，"区块链信息"Tab 之后（最后一个Tab）。

**Tab标签**：`fa-history` 图标 + "版本历史"

**表格列定义**：

| 列名 | 宽度 | 内容 |
|------|------|------|
| 版本号 | 80px | "V1", "V2"... 当前版本蓝色高亮 |
| 发布时间 | 180px | "2026-02-10 17:00:00" |
| 发布人 | 100px | 发布人姓名 |
| 角色 | 80px | "管理员" / "规则提交人" |
| 升级说明 | 自适应 | 升级摘要文字，过长截断+tooltip |

**当前版本行**：浅蓝背景（`#ecf5ff`），带"当前"徽章。

**空状态**：居中提示"暂无版本记录。"

---

### 5.5 F5：列表页版本列

**涉及页面**：

| 页面 | 位置 |
|------|------|
| `风险规则-我的规则.html` | "已入库"Tab，"规则名称"列之后（"未入库"Tab不显示） |
| `风险规则-公共规则库.html` | 列表，"规则名称"列之后 |

**展示形式**：蓝色描边圆角标签（V1, V2...），无版本时显示"-"。

---

### 5.6 F6：存量规则迁移

| 规则类型 | 迁移方案 |
|----------|----------|
| 已上线规则（无版本） | currentVersion = 'V1'，版本历史新增一条"规则初始上线" |
| 已有链事件版本标签的规则（如 V1~V5） | 按链事件还原所有版本历史条目 |
| 草稿/审核中规则 | 不迁移，无版本 |
| 新规则首次上线 | 系统自动设置 currentVersion = 'V1'，无需用户手动操作 |

---

## 6. 数据结构

### 6.1 规则数据新增字段

```javascript
ruleDatabase[code] = {
    currentVersion: 'V1',  // 新增：当前版本号
    basic: { ... },
    tech: { ... }
}
```

### 6.2 版本历史数据结构

```javascript
versionHistoryMap[code] = [
    {
        version: 'V1',                    // 版本号
        publishTime: '2026-02-04 18:30:00', // 发布时间
        publisher: '张三',                  // 发布人
        publisherRole: '管理员',            // 发布人角色
        changeSummary: '规则初始上线',      // 变更说明
        snapshot: {                         // 全量快照
            basic: { /* 完整 basic 字段 */ },
            tech: { /* 完整 tech 字段 */ }
        }
    }
]
```

### 6.3 区块链事件新增标记

版本发布产生的链事件增加 `isVersionPublish: true` 标记：

```javascript
{
    event: '版本发布 [V6]',
    blockHeight: 12851300,
    txHash: '0xab12...cd34',
    time: '2026-02-10 18:00:00',
    evidenceNo: 'CZ20260210180000013',
    contentHash: '0xef56...7890',
    version: 'V6',
    isVersionPublish: true,  // 新增：标识为版本发布事件
    current: true
}
```

---

## 7. 与现有功能的关系

| 现有功能 | 影响 |
|----------|------|
| 已上线规则编辑 | 编辑保存不再声称"生成新版本"，文案修改 |
| 区块链信息Tab | 版本升级事件在时间轴中展示 |
| 规则列表页 | "已入库"Tab 新增版本列，"未入库"Tab 不显示 |
| 规则详情页入口 | 通过 URL `from` 参数区分来源，控制按钮显示/隐藏 |
| 疑点甄别 | 无影响，甄别数据不绑定版本（下期绑定） |
| 规则统计分析 | 无影响 |

---

## 8. 待讨论项

1. 版本发布是否需要审批流程？（本期不做，后续可扩展）
2. 版本数量是否有上限？（本期不限制）
3. 版本发布是否需要通知相关人员？（本期不做）