# 工作流程

记录用户的协作偏好和系统化流程，方便后续模型理解项目运作方式。

## 用户协作风格

- **直接修复明确 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` 加聚合？
- [ ] 删除版本时是否需要清理这类数据？
- [ ] 工作台 / 版本详情 / 项目详情三处的统计是否同步？
- [ ] 是否需要新增 `app_data` key（后端 `data-keys.ts` + 前端 `server-data.ts`）？
- [ ] 是否需要从旧浏览器数据做一次性迁移？（当前不做本地导入导出）

## 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. 后端是否启动：`GET http://localhost:3001/api/v1/config/ai` 应返回 200
2. 数据库是否启动并完成 Prisma 同步：`app_data` 表必须存在
3. 对应 `app_data.key` 是否有值，例如 `products-overview` / `requirements` / `dev-tasks`
4. 前端 store 是否已经调用对应 `fetch*` 方法
5. 类型定义和实际 JSON 数据不一致（缺字段）
6. 列宽溢出导致裁切
7. 派生计算错误（filter 条件错）
8. 跨模块联动断了（store 的 store.getState() 调用时机）

## 测试 / 验证流程

- 改动后必须 `npx tsc --noEmit` 通过
- 涉及服务端数据持久化：`pnpm --filter server exec prisma validate --schema prisma/schema.prisma`
- 涉及 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` 中添加聚合逻辑，工作台自动展示。

## AI 拆解工作流（V3.1）

详细 Agent 规范见 `agent-spec.md`。这里是用户视角的工作流：

```
1. 创建版本（不需要单独填原型链接）
   ↓
2. 在版本详情 → 产品方案 Tab 创建一条 product 计划
   ↓
3. 完成产品方案计划，提交「成果」（成果链接即原型链接，附成果标题）
   ↓
4. 从当前项目已采纳需求中关联需求到本版本
   ↓
5. 点击「AI 拆解任务和用例」按钮（位于产品方案 Tab）
   ↓
6. Agent 从 product 类型的 completed 计划取 resultUrl 作为原型，
   抓取原型 + 关联需求 + 版本成员，输出对账报告 + 任务/用例草案
   ↓
7. 用户审核对账报告
   ├─ 报告全 ✅：直接确认写入
   ├─ 报告有 ⚠️/❓：选择性放弃部分草案 / 补充信息后重跑
   └─ 报告全 ❓：放弃 AI 拆解，人工创建
   ↓
8. 确认后，DevTask / TestCase 草案写入对应 Tab，标记 aiDraft: true
   ↓
9. 团队成员在 DevTask Tab 看到紫色边的 AI 草案任务
   ↓
10. 任意成员编辑任务（改标题/描述/负责人/优先级/时间/分类），保存后 aiDraft 自动清除
    （changeStatus / setBlocked 等用户主动操作也会清除）
```

**触发条件**（AI 拆解按钮可点）：
- 至少有 1 条 type=product 的产品方案计划处于 completed 且 resultUrl 非空
- 至少 1 条需求关联到本版本

**人工创建任务/用例的引用要求**：
- 创建 DevTask 时已选「关联需求」自动作为 reference 写入
- 创建表单加「原型批注」字段（手填，逗号或空格分隔，如 `QY0007, QY0023`）
- 至少一类引用非空才能保存（V3.1 暂未做强校验，靠 UI 引导）

## 高级开发约束：规则先归位

涉及以下任意类型的改动时，先判断规则应该放在哪一层，不允许直接在页面组件里散写临时判断：

- 跨模块联动：例如 Requirement、VersionPlan、DevTask、TestCase、Bug 互相派生状态。
- 状态流转：例如 `pending -> in_progress -> completed`、`todo -> testing -> submitted`。
- 完成条件：例如子任务是否完成、是否提交成果、是否允许点击完成。
- 候选数据来源：例如关联需求只能来自当前项目已采纳需求，不能从全量需求池随手取。
- AI 写入契约：例如 AI 输出任务类型、引用来源、草案标记。

默认落点：

- 可派生数据进 `*-engine.ts` 或纯函数 helper。
- 有状态流转的实体要有状态机或 workflow helper。
- 多个组件共用的候选筛选规则进 selector/helper。
- AI 输入输出字段先更新 `agent-spec.md` 和 shared type，再改 prompt/schema。

版本模块新增规则：

- `version-plan-workflow.ts` 是调研/产品方案/UI 设计完成条件的唯一入口。
- `requirement-selector.ts` 是版本内关联需求候选的唯一入口。
- `TaskCategory.code` 是 AI 和系统任务类型的稳定映射锚点，`id` 只作为存储主键。