# 开发管理 - 状态机文档

> **版本**: v1.0  
> **最后更新**: 2026-01-20  
> **维护者**: 开发团队

---

## ✅ 机器读取区（必填）

### 核心对象

| 字段 | 内容 |
|------|------|
| 对象类型 | DevItem |
| 状态字段 | `devItem.status` |
| 数据表 | `dev_items` |

### 状态列表

| 状态代码 | 说明 | 终态 |
|---------|------|------|
| DRAFT | 需求提出 | ❌ |
| REVIEWED | 需求已评审 | ❌ |
| IN_DEVELOPMENT | 开发中 | ❌ |
| IN_TESTING | 测试中 | ❌ |
| USER_TESTING | 用户测试 | ❌ |
| DONE | 已完成 | ✅ |
| CANCELLED | 已取消 | ✅ |
| ARCHIVED | 已归档 | ✅ |

### 合法流转（DevItem 状态）

| 当前状态 | 可流转到 | 触发动作 | 执行者 | 前置条件 |
|---------|---------|---------|--------|---------|
| DRAFT | REVIEWED | 完成评审 | 评审人/管理员 | 评审结论通过，记录 reviewerId/reviewedAt |
| REVIEWED | IN_DEVELOPMENT | 进入开发 | 负责人/管理员 | 已指定负责人，写入 startAt，devEtaAt 默认 +7 天 |
| IN_DEVELOPMENT | IN_TESTING | 进入测试 | 负责人/管理员 | 开发完成，写入 devCompletedAt |
| IN_TESTING | USER_TESTING | 进入用户测试 | 负责人/管理员 | 内测通过，写入 testCompletedAt |
| USER_TESTING | DONE | 完成工作项 | 负责人/管理员 | 用户测试通过 |
| USER_TESTING | IN_DEVELOPMENT | 退回开发 | 负责人/管理员 | 用户测试未通过 |
| IN_TESTING | IN_DEVELOPMENT | 退回开发 | 负责人/管理员 | 测试未通过 |
| DONE | ARCHIVED | 归档工作项 | 管理员 | 任务完结 |
| ANY | CANCELLED | 取消工作项 | 管理员 | 记录取消原因 |

---

## 🧭 人类阅读区（可选）

### 状态流转图

```mermaid
stateDiagram-v2
    [*] --> DRAFT: 提出
    DRAFT --> REVIEWED: 评审通过
    REVIEWED --> IN_DEVELOPMENT: 进入开发
    IN_DEVELOPMENT --> IN_TESTING: 进入测试
    IN_TESTING --> USER_TESTING: 用户测试
    USER_TESTING --> DONE: 通过
    USER_TESTING --> IN_DEVELOPMENT: 退回
    IN_TESTING --> IN_DEVELOPMENT: 退回
    DONE --> ARCHIVED: 归档
    DRAFT --> CANCELLED: 取消
    REVIEWED --> CANCELLED: 取消
    IN_DEVELOPMENT --> CANCELLED: 取消
    IN_TESTING --> CANCELLED: 取消
```