Claude Code × Spec Kit 实战：五步构建番茄钟待办 Web 应用

uv tool install specify-cli

specify init focus-todo --integration claude --ai-skills
cd focus-todo

## 硬性规则
 
- 所有与时间相关的计算必须放在 `src/domain/timer.ts` 的纯函数里；
  组件中禁止出现 `Date.now()` 参与算术，只允许读取纯函数的返回值。

# Focus-Todo Constitution
 
## Core Principles
 
### I. 代码质量（不可妥协）
 
- MUST 通过 ESLint + Prettier + `tsc --noEmit`，三者任一失败则禁止合并。
- MUST 开启 TypeScript `strict`，禁止使用 `any` 逃逸类型检查。
- MUST 公共组件与领域函数具备类型签名与最小示例；破坏性变更需变更记录。
 
### II. 测试标准与覆盖率
 
- MUST 测试优先（Red-Green-Refactor）：先写测试、确保失败，再实现。
- MUST `src/domain/` 与 `src/storage/` 行覆盖率 ≥ 90%，全局 ≥ 80%。
- MUST CI 中执行测试并作为合并门禁。
- MUST 每个 Edge Case 至少对应一条测试用例。
 
### III. 时间与状态正确性（本项目特有）
 
- MUST 剩余时间以绝对结束时间戳计算，禁止用定时器累减。
- MUST 计时状态只能是有限状态机的合法状态，禁止出现非法中间态。
- MUST 时钟回拨、页面休眠、跨天等场景的剩余时间不得为负、不得凭空增加。
 
### IV. 性能预算
 
- MUST 在 plan.md 中声明可衡量目标（首屏可交互 < 1s；gzip < 150 kB）。
- MUST 计时每秒只更新计时组件，不得触发任务列表整体重渲染。
- MUST 提供构建产物体积检查并纳入 CI。
 
### V. 数据可迁移性
 
- MUST 持久化数据带 `schemaVersion`，读取时按版本迁移，不得直接崩溃。
- MUST 导入备份先校验再写入，校验失败必须保留原有数据。
- MUST 导出文件为人类可读 JSON，便于手工排查。
 
## 质量门禁与度量
 
- 门禁项：Lint / Typecheck 全通过；测试通过且覆盖率达标；构建产物体积不超标；
  **Edge Case 清单逐条有对应测试**。
- 失败则禁止合并；豁免需在 PR 描述记录、关联后续任务并标注影响范围与期限。

# Feature Specification: Focus Todo 番茄钟 + 待办
 
**Feature Branch**: `001-focus-todo`
**Status**: Draft
 
## User Scenarios & Testing
 
### User Story 1 - 管理任务清单 (Priority: P1)
 
用户新建待办、设定预估番茄数、标记完成，并在开始计时前挑选当前任务。
 
**Why this priority**: 没有任务清单，番茄钟只是一个计时器，这是应用的主线。
**Independent Test**: 仅实现任务的增删改查与持久化，即可独立完成"建任务—刷新—仍在"。
 
**Acceptance Scenarios**:
 
1. Given 输入框有内容，When 点击新增，Then 列表出现该任务，输入框清空且焦点保留。
2. Given 任务未完成，When 勾选完成，Then 任务置为完成态并沉底，但不从列表消失。
3. Given 存在未完成任务，When 刷新页面，Then 任务列表与完成状态保持不变。
4. Given 任务标题为空或仅空格，When 提交，Then 拒绝创建并给出提示。
 
### User Story 2 - 运行番茄钟并与任务联动 (Priority: P1)
 
用户启动一个专注番茄，倒计时结束后自动进入休息，并把完成的番茄记到当前任务上。
 
**Why this priority**: 这是应用存在的核心理由，也是计时正确性的主要风险点。
**Independent Test**: 仅实现计时与状态恢复，即可独立完成"开始—刷新—剩余时间不变"。
 
**Acceptance Scenarios**:
 
1. Given 处于空闲状态，When 点击开始，Then 计时器显示剩余时间并按秒更新。
2. Given 专注进行中，When 刷新页面，Then 剩余时间与刷新前一致（误差 ≤ 1 秒），
   且阶段未被重置。
3. Given 专注计时结束，When 阶段切换，Then 进入休息阶段并弹出提示。
4. Given 绑定了任务，When 一个番茄正常结束，Then 该任务完成数 +1，今日统计同步更新。
5. Given 绑定的任务在计时中被删除，When 番茄结束，Then 计时正常结束但不累加到任何任务。
 
### User Story 3 - 查看统计并备份数据 (Priority: P2)
 
用户查看今日专注时长与完成数，导出一份 JSON 备份，换设备时导入恢复。
 
**Why this priority**: 统计是留存用户的钩子，备份是数据不丢的兜底，都不影响主线跑通。
**Independent Test**: 预置一份备份文件即可独立运行导入导出。
 
**Acceptance Scenarios**:
 
1. Given 今天已完成 3 个番茄，When 打开统计面板，Then 显示番茄数 3 与专注时长 75 分钟。
2. Given 点击导出，When 文件保存，Then 得到符合 schemaVersion 约定的 JSON 文件。
3. Given 导入文件格式非法，When 选择导入，Then 报错并保持现有数据不变。
 
### Edge Cases
 
- **页面关闭或系统休眠**：计时以绝对时间戳为准，重新打开后按真实时间计算剩余时间，
  不做累加。
- **超过 12 小时未完成的番茄**：视为中断，不计入统计，状态回到空闲并提示。
- **localStorage 不可用**（隐私模式、配额满）：应用必须仍可运行，降级为内存存储并
  显示提示，不得白屏。
- **多标签页同时打开**：状态通过 storage 事件同步，冲突时以最后写入为准，
  且不得同时跑两个番茄。
- **导入备份的 schemaVersion 高于当前应用**：拒绝导入并提示版本过新。
- **系统时钟被手动回拨**：剩余时间不得为负，也不得凭空增加。
 
## Requirements
 
### Functional Requirements
 
- **FR-001**: 系统 MUST 支持任务的创建、完成、编辑、删除。
- **FR-002**: 系统 MUST 将任务、计时状态、统计数据持久化到 localStorage。
- **FR-003**: 系统 MUST 支持专注 / 短休 / 长休三阶段，长休每 4 个番茄出现一次。
- **FR-004**: 计时 MUST 以绝对结束时间戳计算剩余时间，不得依赖定时器累加。
- **FR-005**: 系统 MUST 将完成的番茄累加到当前绑定任务，并更新今日统计。
- **FR-006**: 系统 MUST 支持导出 / 导入 JSON 备份，文件带 schemaVersion 字段。
- **FR-007**: localStorage 不可用时系统 MUST 降级运行并提示，不得抛出未捕获异常。
- **FR-008**: 核心操作 MUST 有键盘快捷键，交互元素可聚焦且有可见焦点样式。
 
### Key Entities
 
- **Task**: 待办项，含 id、标题、预估番茄数、已完成番茄数、状态（todo/done）、创建时间。
- **TimerState**: 计时状态，含阶段（focus/shortBreak/longBreak）、阶段结束时间戳、
  绑定任务 id、是否运行中。
- **Stats**: 按日期聚合的番茄数与专注时长。
- **Backup**: 导出文件，含 schemaVersion 与 tasks / timer / stats 快照。
 
## Success Criteria
 
- **SC-001**: 计时核心纯函数（剩余时间、阶段推进、统计累加）行覆盖率 ≥ 90%。
- **SC-002**: 刷新页面后剩余时间误差 ≤ 1 秒；休眠 1 小时后恢复，误差 ≤ 1 秒。
- **SC-003**: 首屏可交互时间 < 1s，构建产物 gzip 后 < 150 kB。
- **SC-004**: 键盘可完成新增任务、开始/暂停计时、切换任务、导出备份全部核心操作。
- **SC-005**: localStorage 被禁用时应用不崩溃，且有可见提示。

# Implementation Plan: Focus Todo
 
## Summary
 
- 纯前端单页应用：Vite + React + TypeScript + Tailwind CSS，无后端、无网络请求。
- 核心设计：时间与统计计算抽成纯函数（domain/），UI 只负责渲染与派发；
  持久化集中在 storage/ 层并带版本迁移。
- 测试强制：Vitest 单元测试覆盖 domain/ 与 storage/，组件测试用 Testing Library，
  端到端用 Playwright 跑一条冒烟。
 
## Technical Context
 
**Language/Version**: TypeScript 5.x（strict）
**Primary Dependencies**: react、react-dom、tailwindcss、vite、vitest、
@testing-library/react、playwright
**Package Management**: pnpm（lockfile 必须提交）
**Storage**: localStorage，key `focus-todo/v1`，带 schemaVersion
**Testing**: Vitest（单元）+ Testing Library（组件）+ Playwright（端到端冒烟）
**Target Platform**: 现代浏览器（Chrome / Safari / Firefox 最近两个大版本）
**Project Type**: 单页应用
**Performance Goals**: 首屏可交互 < 1s；gzip < 150 kB；计时 tick 不重渲染任务列表
**Constraints**: 不引入状态管理库；domain 层零依赖、零副作用、100% 可单测
 
## Constitution Check
 
_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
 
- Code Quality: ESLint + Prettier + `tsc --noEmit`，pre-commit 钩子。[PLANNED]
- Testing: Vitest 单元 + 组件测试；domain/ 覆盖率 ≥ 90%。[PLANNED]
- Time Correctness: 时间计算集中在 domain/timer.ts 纯函数，组件禁止参与时间算术。[PLANNED]
- Performance: 计时每秒只更新计时组件；构建体积纳入 CI 检查。[PLANNED]
- Data Portability: 备份带 schemaVersion，导入先校验后写入。[PLANNED]
  Status: PASS (planned). Re-check after Phase 1 and adjust if any violations arise.
 
## Project Structure
 
### Documentation (this feature)
 
specs/001-focus-todo/
├── plan.md # 本文件
├── research.md # Phase 0 输出
├── data-model.md # Phase 1 输出（Task / TimerState / Stats / Backup）
├── quickstart.md # Phase 1 输出
├── contracts/ # Phase 1 输出
└── tasks.md # Phase 2 输出
 
### Source Code
 
src/
├── domain/
│ ├── types.ts # Task / TimerState / Stats / Backup 类型定义
│ ├── timer.ts # 纯函数：remainingMs、nextPhase、advance
│ ├── tasks.ts # 纯函数：创建、完成、排序、过滤
│ └── stats.ts # 纯函数：累加、按日聚合
├── storage/
│ ├── persist.ts # 读写 + 版本迁移 + 降级为内存存储
│ └── backup.ts # 导出 / 导入 + schemaVersion 校验
├── state/
│ ├── reducer.ts # 唯一状态机（useReducer）
│ └── AppContext.tsx
├── hooks/
│ ├── useTimer.ts # 每秒 tick + 阶段推进
│ └── useStorageSync.ts # 多标签页同步
├── components/
│ ├── TaskList.tsx
│ ├── TaskItem.tsx
│ ├── TimerPanel.tsx
│ ├── StatsPanel.tsx
│ └── Shortcuts.tsx
└── App.tsx
tests/
├── unit/ # domain 与 storage
├── component/ # Testing Library
└── e2e/ # Playwright 冒烟

## Phase 1: Setup
 
- [ ] T001 初始化 Vite + React + TypeScript 项目，接入 pnpm 与 Tailwind
- [ ] T002 [P] 配置 ESLint / Prettier / `tsc --noEmit` 与 pre-commit
- [ ] T003 [P] 配置 Vitest + Testing Library + Playwright
- [ ] T004 编写 CLAUDE.md：技术栈、目录约定、常用命令、硬性规则
 
## Phase 2: Foundational（阻塞项）
 
- [ ] T005 定义领域类型 src/domain/types.ts（Task / TimerState / Stats / Backup）
- [ ] T006 [P] 实现计时纯函数 src/domain/timer.ts（remainingMs / nextPhase）
- [ ] T007 [P] 实现任务纯函数 src/domain/tasks.ts
- [ ] T008 [P] 实现统计纯函数 src/domain/stats.ts
- [ ] T009 实现持久化层 src/storage/persist.ts（版本迁移 + 降级）
- [ ] T010 实现备份导入导出 src/storage/backup.ts
- [ ] T011 实现全局 reducer 与 Context src/state/
      **Checkpoint**: Foundation ready
 
## Phase 3: User Story 1 - 任务清单 (P1) 🎯 MVP
 
### US1 测试（强制）
 
- [ ] T012 [P] [US1] 单元测试：任务纯函数 src/domain/tasks.ts
- [ ] T013 [P] [US1] 单元测试：持久化读写与版本迁移 src/storage/persist.ts
- [ ] T014 [P] [US1] 组件测试：新增 / 完成 / 删除任务
 
### 实现
 
- [ ] T015 [US1] 实现 TaskList / TaskItem 组件
- [ ] T016 [US1] 接入 reducer 的任务动作
      **Checkpoint**: US1 可独立演示
 
## Phase 4: User Story 2 - 番茄钟 (P1)
 
### US2 测试（强制）
 
- [ ] T017 [P] [US2] 单元测试：计时纯函数（刷新 / 休眠 / 时钟回拨）
- [ ] T018 [P] [US2] 单元测试：统计累加 src/domain/stats.ts
 
### 实现
 
- [ ] T019 [US2] 实现 TimerPanel 组件与 useTimer hook
- [ ] T020 [US2] 实现番茄与任务联动（含任务被删除的处理）
      **Checkpoint**: US2 可独立演示
 
## Phase 5: User Story 3 - 统计与备份 (P2)
 
### US3 测试（强制）
 
- [ ] T021 [P] [US3] 单元测试：备份序列化与非法导入 src/storage/backup.ts
 
### 实现
 
- [ ] T022 [US3] 实现 StatsPanel 与导入导出入口
      **Checkpoint**: US3 可独立验证
 
## Phase 6: Polish
 
- [ ] T023 [P] 实现键盘快捷键与可见焦点样式
- [ ] T024 [P] 实现多标签页 storage 同步
- [ ] T025 端到端冒烟：Playwright 跑通"建任务 → 开始番茄 → 刷新 → 剩余时间不变"
- [ ] T026 编写 quickstart.md 与 README
 
## Dependencies & Execution Order
 
- Setup(Phase 1): 无依赖，可立即开始
- Foundational(Phase 2): 依赖 Setup，阻塞所有用户故事
- User Stories(Phase 3+): 均依赖 Foundational；US1 / US2 / US3 可并行
- Polish: 依赖所有目标用户故事完成

# 会话 1：Setup + Foundational
claude --resume   # 完成后新开会话
 
# 会话 2：US1
# 会话 3：US2
# 会话 4：US3 + Polish

claude --allowedTools "Bash(pnpm:*),Bash(pnpm run:*),Read,Edit,Write,Grep,Glob"

const [remaining, setRemaining] = useState(25 * 60 * 1000)
useEffect(() => {
  const id = setInterval(() => setRemaining((r) => r - 1000), 1000)
  return () => clearInterval(id)
}, [])

// domain/timer.ts —— 纯函数，输入状态与当前时间，输出剩余毫秒
export function remainingMs(state: TimerState, now: number): number {
  return Math.max(0, state.endsAt - now)
}

export function isStorageAvailable(): boolean {
  try {
    const probe = '__focus_todo_probe__'
    localStorage.setItem(probe, '1')
    localStorage.removeItem(probe)
    return true
  } catch {
    return false
  }
}