6d2f6d8b9f
文档： - architecture.md - 整体架构、心智模型、关键设计原则 - decisions.md - 16条关键决策记录（含为什么） - workflow.md - 工作流程和协作偏好 - roadmap.md - V1/V2/V3 路线图和已完成清单 修复项目详情版本记录： 1. 状态胶囊数据联动（开发中分支也补传 stageProgress） 2. 日期数据联动： - 实际开始 = 取所有阶段最早 actualStartAt/startDate/startedAt - 实际截止 = 取所有阶段最晚 completedAt/closedAt - 数据完全和版本详情一致 VersionCard 的 versionData useMemo 增加 actualStart/actualEnd 派生字段， 两种状态分支（developing/released）都使用派生值，不再用静态 version.startDate Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
# 工作流程
|
||
|
||
记录用户的协作偏好和系统化流程，方便后续模型理解项目运作方式。
|
||
|
||
## 用户协作风格
|
||
|
||
- **直接修复明确 bug**，不强制走 brainstorming 流程
|
||
- **方案确认后立即执行**，不重复讨论
|
||
- **不喜欢自动 push**：commit 由模型完成，**push 需要用户明说"推/push"**
|
||
- **要求高级开发思维**：考虑数据联动、引擎层抽象，而不是分散写 ad-hoc 逻辑
|
||
- **重视一致性**：所有 Drawer 阴影、所有时间格式、所有状态计算都要统一
|
||
- **省略多余对话**：能直接做的不要问，只在真有歧义时用 AskUserQuestion 给选项
|
||
- **Brainstorming 适用于新功能**，bug fix 和已批准方案的延续不走 brainstorming
|
||
|
||
## 实际工时计算流程
|
||
|
||
所有"实际开始时间"和"实际完成时间"都是 ISO 时间戳：
|
||
|
||
```
|
||
状态变更时机：
|
||
- DevTask: todo → in_progress 时记 startDate
|
||
testing → submitted 时记 completedAt
|
||
- TestCase: pending → running 时记 startedAt
|
||
running → passed/failed/blocked 时记 completedAt
|
||
- VersionPlan: pending → in_progress 时记 actualStartAt
|
||
in_progress → completed 时记 completedAt
|
||
|
||
计算：
|
||
- 实际工时 = (completedAt - startDate) / 3600000，精确到 0.5h
|
||
- 阶段日历耗时 = min(start) → max(end) 跨度（项目维度，不重复）
|
||
- 个人耗时 = 每个任务独立累加（个人维度）
|
||
```
|
||
|
||
## 数据联动检查清单
|
||
|
||
新加模块或字段时，检查以下点：
|
||
|
||
- [ ] 是否需要在 `linkage-engine.ts` 加派生函数？
|
||
- [ ] 是否需要在 `workspace-engine.ts` 加聚合？
|
||
- [ ] 删除版本时是否需要清理这类数据？
|
||
- [ ] 工作台 / 版本详情 / 项目详情三处的统计是否同步？
|
||
- [ ] localStorage 旧数据是否需要兼容处理？
|
||
|
||
## Drawer（侧边详情）规范
|
||
|
||
所有侧边详情遵循：
|
||
|
||
- `fixed inset-0 z-50 flex justify-end`
|
||
- 背景 `bg-black/40`
|
||
- Drawer 容器 `w-full max-w-md h-full bg-[var(--bg)] border-l shadow-2xl flex flex-col`
|
||
- 顶部上下文条（可选）：`px-5 py-2 bg-[var(--bg-subtle)] text-[11px]`
|
||
- 顶栏：`h-14 border-b bg-[var(--bg-card)]`
|
||
- 操作按钮按颜色编码：blue=进行/转交、emerald=完成、red=删除/失败、orange=关闭/提BUG
|
||
|
||
## Modal（弹窗）规范
|
||
|
||
- 居中 `flex items-center justify-center bg-black/40`
|
||
- `rounded-2xl bg-[var(--bg-card)] border shadow-md`
|
||
- 提交 BUG 等图片密集型用 `max-w-2xl`，普通表单 `max-w-md` 或 `max-w-lg`
|
||
|
||
## 字段命名规范
|
||
|
||
- 实际开始：`startDate` (DevTask) / `startedAt` (TestCase) / `actualStartAt` (VersionPlan)
|
||
- 实际完成：`completedAt`（统一）
|
||
- 派生进度：在 lib 层提供函数，不存储
|
||
|
||
历史原因导致命名不完全一致（DevTask 用 startDate 是因为最早是日期字段），但行为一致。
|
||
|
||
## 提交信息规范
|
||
|
||
- 中文 commit message
|
||
- 格式：`类型(模块): 描述`
|
||
- feat / fix / refactor / docs / test
|
||
- 描述列出关键改动点，特别是跨模块影响
|
||
- Co-Authored-By 行带版本号
|
||
|
||
## 文档维护流程
|
||
|
||
- **新增/改动核心架构** → 更新 `architecture.md`
|
||
- **关键设计决策** → 追加到 `decisions.md`，包含"为什么"
|
||
- **新功能/路线图变更** → 更新 `roadmap.md`
|
||
- **不影响架构的功能性改动** → 不需要更新文档
|
||
|
||
## Bug 排查流程
|
||
|
||
朋友拉新代码出现"显示问题"时，按顺序排查：
|
||
|
||
1. 旧 localStorage 数据格式不兼容 → 让朋友清缓存
|
||
2. 类型定义和实际数据不一致（缺字段）
|
||
3. 列宽溢出导致裁切
|
||
4. 派生计算错误（filter 条件错）
|
||
5. 跨模块联动断了（store 的 store.getState() 调用时机）
|
||
|
||
## 测试 / 验证流程
|
||
|
||
- 改动后必须 `npx tsc --noEmit` 通过
|
||
- 涉及 UI 改动：`curl http://localhost:3000/<path>` 检查 200
|
||
- 不会自动跑 dev server，假定它已经运行
|
||
|
||
## 与我相关（Workspace）数据流
|
||
|
||
```
|
||
useProductStore → versions
|
||
useRequirementStore → requirements (with versionId)
|
||
useDevTaskStore → tasks (with requirementId)
|
||
useTestCaseStore → testCases (with versionId)
|
||
useBugStore → bugs (with versionId)
|
||
useVersionPlanStore → plans (with versionId, owner)
|
||
useAuthStore → user (filter by current user)
|
||
↓
|
||
workspace-engine.aggregateWorkItems(...)
|
||
↓
|
||
WorkItem[] (统一格式)
|
||
↓
|
||
Workspace 页面（树筛选 + tab 筛选 + 已完成开关）
|
||
```
|
||
|
||
新增模块时，只需在 `aggregateWorkItems` 中添加聚合逻辑，工作台自动展示。
|