# 开发管理 - 数据模型文档

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

---

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

### Schema 摘要

| 字段 | 内容 |
|------|------|
| Schema 名称 | `platform_devtracker` |
| 业务域 | 研发任务管理 |
| 核心实体 | DevItem |

### 实体字段清单（最小）

| 实体 | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| DevItem | id | UUID | ✅ | 主键 |
| DevItem | code | String | ✅ | 可读编号（DT-YYYY-MODULE-TYPE-SEQ） |
| DevItem | title | String | ✅ | 标题 |
| DevItem | description | String | ❌ | 描述 |
| DevItem | itemType | Enum | ✅ | MODULE/FEATURE/BUG |
| DevItem | status | Enum | ✅ | DRAFT/REVIEWED/IN_DEVELOPMENT/IN_TESTING/USER_TESTING/DONE/CANCELLED/ARCHIVED |
| DevItem | priority | Enum | ✅ | P0/P1/P2/P3 |
| DevItem | severity | Enum | ❌ | S1/S2/S3/S4（仅 BUG） |
| DevItem | moduleKey | String | ❌ | 模块名称（仅英文，生成编号缩写） |
| DevItem | parentId | UUID | ❌ | 父工作项 ID |
| DevItem | ownerId | UUID | ✅ | 负责人 |
| DevItem | reporterId | UUID | ✅ | 创建人 |
| DevItem | reviewerId | UUID | ❌ | 评审人（状态 REVIEWED 时填充） |
| DevItem | reviewedAt | DateTime | ❌ | 评审时间（状态 REVIEWED 时填充） |
| DevItem | startAt | DateTime | ❌ | 开始时间 |
| DevItem | devEtaAt | DateTime | ❌ | 预计开发完成时间 |
| DevItem | devCompletedAt | DateTime | ❌ | 开发完成时间 |
| DevItem | testEtaAt | DateTime | ❌ | 预计测试结束时间 |
| DevItem | testCompletedAt | DateTime | ❌ | 测试完成时间 |
| DevItem | etaAt | DateTime | ❌ | 预计完成时间 |
| DevItem | completedAt | DateTime | ❌ | 完成时间 |
| DevItem | content | JSON | ❌ | 需求文档内容（编辑器 JSON） |
| DevItem | labels | JSON | ❌ | 标签 |
| DevItem | createdAt | DateTime | ✅ | 创建时间 |
| DevItem | updatedAt | DateTime | ✅ | 更新时间 |
| DevItem | deletedAt | DateTime | ❌ | 软删除时间 |
| ReleaseNote | id | UUID | ✅ | 主键 |
| ReleaseNote | version | String | ✅ | 版本号 |
| ReleaseNote | title | String | ✅ | 更新标题 |
| ReleaseNote | content | JSON | ❌ | 更新内容（编辑器 JSON） |
| ReleaseNote | releasedAt | DateTime | ✅ | 发布日期 |
| ReleaseNote | createdBy | UUID | ✅ | 创建人 |
| ReleaseNote | createdAt | DateTime | ✅ | 创建时间 |
| ReleaseNote | updatedAt | DateTime | ✅ | 更新时间 |
| DevItemSequence | prefix | String | ✅ | 编号前缀（DT-YYYY-MODULE-TYPE） |
| DevItemSequence | current | Int | ✅ | 当前序号 |
| DevItemSequence | createdAt | DateTime | ✅ | 创建时间 |
| DevItemSequence | updatedAt | DateTime | ✅ | 更新时间 |

### 关系与约束

| 关系/约束 | 说明 |
|-----------|------|
| DevItem → DevItem | 父子工作项自关联，一对多 |
| DevItem → User | 负责人、创建人、评审人引用用户 |
| 状态约束 | 状态流转遵循状态机 |
| Bug 约束 | itemType=BUG 时允许 severity，非 BUG 不填 |
| 层级约束 | FEATURE/BUG 必须有 parentId 且指向 MODULE |
| 编号约束 | code 唯一，格式 DT-YYYY-MODULE-TYPE-SEQ（MODULE 从 moduleKey 或 parent.moduleKey 取，空则 GEN；TYPE=MOD/FT/BUG；MODULE 为英文单词首字母或单词前 3 字母） |
| 更新记录约束 | version 唯一；createdBy 必填；releasedAt 必填 |

---

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

### 详细表结构（如需）

```sql
CREATE TABLE platform_devtracker.dev_items (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  code TEXT NOT NULL,
  title TEXT NOT NULL,
  description TEXT,
  item_type TEXT NOT NULL,
  status TEXT NOT NULL,
  priority TEXT NOT NULL,
  severity TEXT,
  module_key TEXT,
  parent_id UUID,
  owner_id UUID NOT NULL,
  reporter_id UUID NOT NULL,
  reviewer_id UUID,
  reviewed_at TIMESTAMP,
  start_at TIMESTAMP,
  dev_eta_at TIMESTAMP,
  dev_completed_at TIMESTAMP,
  test_eta_at TIMESTAMP,
  test_completed_at TIMESTAMP,
  eta_at TIMESTAMP,
  completed_at TIMESTAMP,
  content JSONB,
  labels JSONB,
  created_at TIMESTAMP NOT NULL DEFAULT now(),
  updated_at TIMESTAMP NOT NULL DEFAULT now(),
  deleted_at TIMESTAMP
);

CREATE TABLE platform_devtracker.dev_item_sequences (
  prefix TEXT PRIMARY KEY,
  current INT NOT NULL DEFAULT 0,
  created_at TIMESTAMP NOT NULL DEFAULT now(),
  updated_at TIMESTAMP NOT NULL DEFAULT now()
);
```