Files

Script Generator 6d2f6d8b9f docs+fix: 4份核心文档 + 项目模块版本记录数据全联动

文档：
- 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>

2026-06-16 12:40:10 +08:00

4.4 KiB

Raw Blame History

工作流程

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

用户协作风格

直接修复明确 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 排查流程

朋友拉新代码出现"显示问题"时，按顺序排查：

旧 localStorage 数据格式不兼容 → 让朋友清缓存
类型定义和实际数据不一致（缺字段）
列宽溢出导致裁切
派生计算错误（filter 条件错）
跨模块联动断了（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 中添加聚合逻辑，工作台自动展示。

4.4 KiB Raw Blame History Unescape Escape