---
title: 版本模块 Phase 1 设计规格
date: 2026-06-09
module: versions
---

# 版本模块 Phase 1 — 列表增强 + 详情页 + 生命周期

## 1. 版本生命周期状态机

```
规划中 → 进行中(各阶段) → 已发布
         ↕                  
       已暂停              已关闭
```

- 规划中(planned)：已创建但未开始
- 进行中(developing)：有 currentStage 标识具体阶段（调研/产品设计/UI设计/开发/联调/测试）
- 已暂停(paused)：手动暂停，可恢复为进行中
- 已关闭(closed)：手动关闭，终态不可恢复
- 已发布(released)：上线完成，终态

操作：
- 开始：规划中 → 进行中
- 暂停：进行中 → 已暂停
- 恢复：已暂停 → 进行中
- 关闭：规划中/进行中/已暂停 → 已关闭
- 发布：进行中 → 已发布

## 2. 新增字段

### 版本数据结构扩展

```typescript
interface VersionItem {
  // 已有
  id: string;
  name: string;
  status: 'planned' | 'developing' | 'paused' | 'closed' | 'released';
  currentStage?: Stage;
  startDate?: string | null;
  expectedReleaseDate?: string | null;  // 截止日期
  releaseDate: string | null;
  createdAt: string;
  members?: VersionMember[];
  progress?: RoleProgress[];

  // 新增
  priority: 'P0' | 'P1' | 'P2' | 'P3' | 'P4';
  riskLevel?: 'low' | 'medium' | 'high';       // 系统自动计算
  delayStatus?: 'normal' | 'warning' | 'delayed'; // 系统自动计算
  links?: {
    research?: string;   // 调研报告地址
    prototype?: string;  // 原型地址
    ui?: string;         // UI 设计稿地址
  };
}
```

### 风险等级自动计算规则

- **低风险(low/绿)**：一切正常
- **中风险(medium/橙)**：
  - 整体进度落后于时间进度 20%+
  - 即将延期（截止日期 - 3天内）
  - 版本被暂停
- **高风险(high/红)**：
  - 已延期（当前日期 > 截止日期 且未发布/关闭）
  - 整体进度落后于时间进度 40%+

计算公式：
- 时间进度 = (当前日期 - 开始日期) / (截止日期 - 开始日期) × 100%
- 整体进度 = 各角色进度百分比的平均值
- 落后比 = 时间进度 - 整体进度

### 延期状态自动计算规则

- **正常(normal/绿)**：当前日期 < 截止日期 - 3天
- **即将延期(warning/橙)**：截止日期 - 3天 ≤ 当前日期 ≤ 截止日期
- **已延期(delayed/红)**：当前日期 > 截止日期 且状态不是已发布/已关闭

已发布和已关闭的版本不计算延期状态，统一显示"-"。

### 优先级

P0(紧急) / P1(高) / P2(中) / P3(低) / P4(最低)

手动设置，默认 P2。列表可按优先级排序。

## 3. 版本列表页改造

### 列定义

| 列 | 宽度 | 说明 |
|---|---|---|
| 版本号 | auto | 如"考勤V1.2"，点击进详情 |
| 优先级 | 60px | P0-P4 标签，颜色区分 |
| 当前阶段 | 100px | 显示胶囊对应的阶段名，跟项目详情一致 |
| 整体进度 | 120px | 进度条 + 百分比 |
| 风险等级 | 70px | 颜色点 + 文字（低/中/高） |
| 延期状态 | 80px | 颜色标签（正常/即将延期/已延期） |
| 截止日期 | 100px | YYYY-MM-DD |
| 负责人 | auto | 紧凑展示：产品:张三 前端:赵六... |
| 操作 | 80px | 下拉菜单（编辑/暂停/恢复/关闭） |

### 筛选条件

- 搜索：版本号模糊匹配
- 状态筛选：全部 / 调研 / 产品设计 / UI设计 / 开发 / 联调 / 测试 / 已发布 / 已暂停 / 已关闭 / 规划中
- 项目筛选：下拉选择
- 优先级筛选：P0-P4 多选
- 风险等级筛选：低/中/高

### 排序

默认按优先级降序 > 创建时间倒序。可点击表头切换排序。

## 4. 版本详情页 `/versions/[id]`

### 页面结构

```
┌─────────────────────────────────────────────────────┐
│ Header: ← 版本  /  考勤V1.2    [编辑] [暂停] [关闭]│
├─────────────────────────────────────────────────────┤
│ 标签行: P1标签  风险:中  即将延期  产品:翻台宝      │
├─────────────────────────────────────────────────────┤
│ 胶囊分段条（CapsuleStages 组件复用）                 │
├─────────────────────────────────────────────────────┤
│ 信息网格 (3列)                                       │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐             │
│ │开始日期   │ │截止日期   │ │已耗时     │             │
│ │2024-04-15│ │2024-06-10│ │34天      │             │
│ └──────────┘ └──────────┘ └──────────┘             │
│                                                     │
│ 负责人区域                                           │
│ 产品:张三  UI:王五  前端:赵六  后端:孙八  测试:周九  │
│                                                     │
│ 外链区域                                             │
│ 📄 调研报告  🎨 原型地址  🖼 UI设计稿               │
├─────────────────────────────────────────────────────┤
│ 下半部分（Phase 2 占位）                             │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Tabs: 需求 | 开发任务 | 测试用例 | Bug           │ │
│ │                                                 │ │
│ │        功能开发中，敬请期待                        │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```

### 上半部分详细说明

- **Header**：面包屑导航 + 版本名 + 操作按钮组
- **标签行**：优先级(P0-P4) + 风险等级(颜色点) + 延期状态(标签) + 所属产品/项目
- **胶囊分段条**：复用 CapsuleStages 组件，展示各阶段进度和耗时
- **信息网格**：开始日期、截止日期、已耗时天数
- **负责人**：复用 MemberChips 组件
- **外链**：调研报告/原型/UI 设计稿链接，点击新窗口打开，无链接显示"未设置"

### 下半部分（Phase 2 占位）

Tab 栏显示：需求 / 开发任务 / 测试用例 / Bug

Phase 1 内容为空占位："功能开发中"

## 5. 项目详情页同步调整

项目详情页的版本记录卡片同步增加优先级标签显示。

## 6. 新建版本弹窗扩展

在现有字段基础上增加：
- 优先级选择（默认 P2）
- 截止日期选择（日期选择器）
- 负责人选择（按角色分组，后续可从历史推荐）

## 7. 涉及文件变更

| 文件 | 变更 |
|---|---|
| `apps/web/lib/stage.ts` | 无变更 |
| `apps/web/lib/version-status.ts` | 新增 paused/closed 状态 |
| `apps/web/stores/useProductStore.ts` | VersionItem 扩展字段，MOCK数据补充 |
| `apps/web/app/versions/page.tsx` | 列表页重构 |
| `apps/web/app/versions/[id]/page.tsx` | 新增详情页 |
| `apps/web/app/projects/[id]/page.tsx` | 版本卡片加优先级 |
| `apps/web/lib/risk.ts` | 新增：风险等级和延期状态计算函数 |