# 开发管理 - API 文档

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

---

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

### 统一约定

- Base URL: `/api/v1/devtracker`
- 认证: Bearer Token (JWT)
- 错误码: [08-error-codes.md](./08-error-codes.md)
- 统一拦截器: 成功响应由 `TransformInterceptor` 统一包装；错误响应由 `AllExceptionsFilter` 统一格式化
- 响应封装:
  - 成功: `{ "success": true, "data": {...}, "message": "success", "timestamp": "...", "path": "/api/v1/..." }`
  - 分页: `{ "success": true, "data": { items, pagination: { page, pageSize, total, totalPages } }, "timestamp": "...", "path": "/api/v1/..." }`
  - 失败: `{ "success": false, "error": { "code": "<ERROR_CODE>", "message": "<i18n.key>", "...": "..." }, "timestamp": "...", "path": "/api/v1/...", "method": "GET", "statusCode": 400 }`

### 通用状态码

| 状态码 | 说明 |
|-------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 参数错误/业务校验失败 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 业务冲突（状态不允许/重复） |
| 422 | 数据校验失败 |

### API 说明

- 覆盖研发工作项管理接口，与 UI/状态机/数据模型一致
- 所有接口返回统一封装格式
- 变更接口需同步更新错误码文档与测试场景

### 接口数量汇总

- 总计: 8 个接口
- 统计口径: 下方“接口清单（按域）”中的全部路径

---

## 接口清单（按域）

### 1) 工作项（6）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 001 | GET | /items | 开发工程师/管理员 |
| 002 | GET | /items/:id | 开发工程师/管理员 |
| 003 | POST | /items | 开发工程师/管理员 |
| 004 | PUT | /items/:id | 负责人/管理员 |
| 005 | PATCH | /items/:id/status | 评审人/负责人/管理员 |
| 006 | DELETE | /items/:id | 管理员 |

### 2) 更新记录（2）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 007 | GET | /release-notes | 开发工程师/管理员 |
| 008 | POST | /release-notes | 管理员 |

---

## 数据结构定义（字段级）

### 通用响应封装

#### SuccessResponse<T>

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| success | Boolean | ✅ | 成功标记，固定为 true |
| data | T | ✅ | 业务数据 |
| message | String | ✅ | 提示信息，默认 `success` |
| timestamp | DateTime | ✅ | 响应时间 |
| path | String | ✅ | 请求路径 |

#### ErrorResponse

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| success | Boolean | ✅ | 成功标记，固定为 false |
| error.code | String | ✅ | 错误码（与 08-error-codes 一致） |
| error.message | String | ✅ | i18n key 或可读信息 |
| error.details | JSON | ❌ | 额外上下文 |
| timestamp | DateTime | ✅ | 响应时间 |
| path | String | ✅ | 请求路径 |
| method | String | ✅ | HTTP 方法 |
| statusCode | Int | ✅ | HTTP 状态码 |

### 通用列表与分页

#### PageResult<T>

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| items | T[] | ✅ | 列表数据 |
| pagination | Pagination | ✅ | 分页信息 |

#### Pagination

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | Int | ✅ | 页码（从 1 开始） |
| pageSize | Int | ✅ | 每页数量 |
| total | Int | ✅ | 总数 |
| totalPages | Int | ✅ | 总页数 |

### 业务实体与 DTO

#### DevItem

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

#### DevItemListQuery

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | Int | ❌ | 页码 |
| pageSize | Int | ❌ | 每页数量 |
| itemType | Enum | ❌ | 类型过滤 |
| status | Enum | ❌ | 状态过滤 |
| ownerId | UUID | ❌ | 负责人过滤 |
| parentId | UUID | ❌ | 父级过滤 |
| priority | Enum | ❌ | 优先级过滤 |
| keyword | String | ❌ | 关键字搜索 |

#### DevItemCreateRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | String | ✅ | 标题 |
| description | String | ❌ | 描述 |
| itemType | Enum | ✅ | MODULE/FEATURE/BUG |
| priority | Enum | ✅ | P0/P1/P2/P3 |
| severity | Enum | ❌ | 仅 BUG 时允许 |
| moduleKey | String | ❌ | 关联系统模块 |
| parentId | UUID | ❌ | 父工作项（MODULE） |
| ownerId | UUID | ✅ | 负责人 |
| devEtaAt | DateTime | ❌ | 预计开发完成时间 |
| testEtaAt | DateTime | ❌ | 预计测试结束时间 |
| etaAt | DateTime | ❌ | 预计完成时间 |
| content | JSON | ❌ | 需求文档内容（编辑器 JSON） |
| labels | JSON | ❌ | 标签 |

#### DevItemUpdateRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | String | ❌ | 标题 |
| description | String | ❌ | 描述 |
| priority | Enum | ❌ | 优先级 |
| severity | Enum | ❌ | 仅 BUG 时允许 |
| ownerId | UUID | ❌ | 负责人 |
| startAt | DateTime | ❌ | 开始时间 |
| devEtaAt | DateTime | ❌ | 预计开发完成时间 |
| testEtaAt | DateTime | ❌ | 预计测试结束时间 |
| etaAt | DateTime | ❌ | 预计完成时间 |
| content | JSON | ❌ | 需求文档内容（编辑器 JSON） |
| labels | JSON | ❌ | 标签 |

#### DevItemStatusUpdateRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | Enum | ✅ | 状态变更（评审时记录 reviewerId/reviewedAt） |

#### ReleaseNote

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 更新记录 ID |
| version | String | ✅ | 版本号 |
| title | String | ✅ | 更新标题 |
| content | JSON | ❌ | 更新内容（编辑器 JSON） |
| releasedAt | DateTime | ✅ | 发布日期 |
| createdBy | UUID | ✅ | 创建人 |
| createdAt | DateTime | ✅ | 创建时间 |
| updatedAt | DateTime | ✅ | 更新时间 |

#### ReleaseNoteListQuery

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | Int | ❌ | 页码 |
| pageSize | Int | ❌ | 每页数量 |
| keyword | String | ❌ | 标题/版本关键字搜索 |

#### ReleaseNoteCreateRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| version | String | ✅ | 版本号 |
| title | String | ✅ | 更新标题 |
| content | JSON | ❌ | 更新内容（编辑器 JSON） |
| releasedAt | DateTime | ✅ | 发布日期 |

---

## 接口详情（编号）

**[001] GET /items**
- 说明: 获取工作项列表
- 请求 Query: DevItemListQuery
- 响应 Data: PageResult<DevItem>
- 示例请求: `GET /items?page=1&pageSize=20&status=REVIEWED`
- 示例响应: `{ "success": true, "data": { "items": [], "pagination": { "page": 1, "pageSize": 20, "total": 0, "totalPages": 0 } }, "timestamp": "2026-01-20T00:00:00Z", "path": "/api/v1/devtracker/items" }`
- 状态码: 200, 401, 403

**[002] GET /items/:id**
- 说明: 获取工作项详情
- 请求 Path: id
- 响应 Data: DevItem
- 示例请求: `GET /items/uuid`
- 示例响应: `{ "success": true, "data": { "id": "uuid" }, "message": "success", "timestamp": "2026-01-20T00:00:00Z", "path": "/api/v1/devtracker/items/uuid" }`
- 状态码: 200, 401, 403, 404

**[003] POST /items**
- 说明: 创建工作项
- 请求 Body: DevItemCreateRequest
- 响应 Data: DevItem
- 示例请求: `POST /items`
- 示例响应: `{ "success": true, "data": { "id": "uuid" }, "message": "success", "timestamp": "2026-01-20T00:00:00Z", "path": "/api/v1/devtracker/items" }`
- 状态码: 201, 400, 401, 403

**[004] PUT /items/:id**
- 说明: 更新工作项
- 请求 Body: DevItemUpdateRequest
- 响应 Data: DevItem
- 示例请求: `PUT /items/uuid`
- 示例响应: `{ "success": true, "data": { "id": "uuid" }, "message": "success", "timestamp": "2026-01-20T00:00:00Z", "path": "/api/v1/devtracker/items/uuid" }`
- 状态码: 200, 400, 401, 403, 404

**[005] PATCH /items/:id/status**
- 说明: 更新工作项状态
- 请求 Body: DevItemStatusUpdateRequest
- 响应 Data: DevItem
- 示例请求: `PATCH /items/uuid/status`
- 示例响应: `{ "success": true, "data": { "id": "uuid", "status": "IN_DEVELOPMENT" }, "message": "success", "timestamp": "2026-01-20T00:00:00Z", "path": "/api/v1/devtracker/items/uuid/status" }`
- 状态码: 200, 400, 401, 403, 404, 409

**[006] DELETE /items/:id**
- 说明: 删除工作项（软删除）
- 请求 Path: id
- 响应 Data: DevItem

**[007] GET /release-notes**
- 说明: 获取更新记录列表
- 请求 Query: ReleaseNoteListQuery
- 响应 Data: PageResult<ReleaseNote>
- 示例请求: `GET /release-notes?page=1&pageSize=20`
- 示例响应: `{ "success": true, "data": { "items": [], "pagination": { "page": 1, "pageSize": 20, "total": 0, "totalPages": 0 } }, "timestamp": "2026-01-20T00:00:00Z", "path": "/api/v1/devtracker/release-notes" }`
- 状态码: 200, 401, 403

**[008] POST /release-notes**
- 说明: 创建更新记录
- 请求 Body: ReleaseNoteCreateRequest
- 响应 Data: ReleaseNote
- 示例请求: `POST /release-notes`
- 示例响应: `{ "success": true, "data": { "id": "uuid", "version": "v1.0.1" }, "message": "success", "timestamp": "2026-01-20T00:00:00Z", "path": "/api/v1/devtracker/release-notes" }`
- 状态码: 201, 400, 401, 403, 409
- 示例请求: `DELETE /items/uuid`
- 示例响应: `{ "success": true, "data": { "id": "uuid" }, "message": "success", "timestamp": "2026-01-20T00:00:00Z", "path": "/api/v1/devtracker/items/uuid" }`
- 状态码: 200, 401, 403, 404