# 开发管理 - UI 交互规范

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

> **参考标准**: [设计系统（权威）](../../../.agents/skills/frontend-main/references/design-system-standards.md)

---

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

### 页面清单

| 页面 | 路由 | 说明 | 状态 |
|------|------|------|------|
| 总览看板 | `/devtracker` | 甘特图 + 需求卡片 | ✅ |
| 需求列表页 | `/devtracker/items` | 需求列表与过滤 | ✅ |
| 需求详情页 | `/devtracker/items/:id` | 需求详情与阶段确认 | ✅ |
| 需求新建/编辑 | `/devtracker/items/new` | 需求表单与文档编辑器 | ✅ |
| 甘特图 | `/devtracker/gantt` | 需求排期与进度 | ✅ |
| 更新记录 | `/devtracker/updates` | 版本更新记录展示与新增 | ✅ |

### 元素清单（最小）

| 元素 | 类型 | 说明 |
|------|------|------|
| 页面标题 | 文本 | 开发管理 |
| 看板卡片 | 卡片 | 甘特图/阶段需求 |
| 需求表格 | 表格 | 展示需求列表 |
| 状态标签 | 标签 | 需求状态 |
| 需求编号 | 文本 | 可读编号展示 |
| 新建按钮 | 按钮 | 新建需求 |
| 过滤器 | 表单 | 类型/状态/负责人/优先级 |
| 甘特图视图 | 图表 | 按需求 startAt/etaAt 展示排期 |
| 文档编辑器 | 富文本 | 需求新建/详情记录需求说明 |
| 更新记录列表 | 列表 | 展示版本、标题、日期与内容 |
| 更新记录表单 | 表单 | 有权限用户新增版本记录 |

### 交互清单（最小）

| 交互 | 触发 | API | 结果 |
|------|------|-----|------|
| 需求列表加载 | 进入需求页 | GET /devtracker/items | 渲染需求列表 |
| 创建需求 | 提交表单 | POST /devtracker/items | 需求列表刷新 |
| 更新需求 | 编辑操作 | PUT /devtracker/items/:id | 详情与列表更新 |
| 更新需求状态 | 状态操作 | PATCH /devtracker/items/:id/status | 状态进入下一阶段 |
| 查看需求详情 | 点击需求 | GET /devtracker/items/:id | 打开详情页 |
| 保存需求文档 | 文档编辑器保存 | PUT /devtracker/items/:id | 文档内容更新 |
| 调整预计时间 | 详情页时间线点击 | PUT /devtracker/items/:id | 更新 startAt/devEtaAt/testEtaAt/etaAt |
| 拖拽甘特条 | 甘特图拖拽/缩放 | PUT /devtracker/items/:id | 更新 startAt/etaAt |
| 甘特图加载 | 进入甘特图 | GET /devtracker/items | 渲染时间轴 |
| 更新记录加载 | 进入更新记录页 | GET /devtracker/release-notes | 渲染更新记录 |
| 新增更新记录 | 提交更新记录 | POST /devtracker/release-notes | 记录新增成功 |

### 国际化与文案规范

- 所有用户可见文案必须使用 i18n key，不允许硬编码
- 动态内容使用插值，不拼接字符串
- 日期/数字必须本地化格式化

---

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

### 交互流程

- 进入需求列表 → 选择过滤条件 → 查看需求详情
- 评审通过进入开发 → 开发完成进入测试 → 用户测试通过完成需求
- 进入开发时自动填充预计开发完成时间（默认 +7 天），后续可在时间线调整（含开始时间）
- 甘特图以需求为粒度展示计划区间（startAt/etaAt），支持拖动条形调整开始/结束时间

### 流程图

```mermaid
flowchart TD
    A[进入需求列表] --> B[加载需求数据]
    B --> C[渲染表格]
    C --> D[更新状态]
```