Jammy/TrueGrowth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
be9e776b10022a2a7846782ef2bc2a627435df66
TrueGrowth/specs/002-unified-toolbar/tasks.md

15 KiB
Raw Blame History

Tasks: 统一左侧工具栏容器

Input: Design documents from /specs/001-unified-toolbar/ Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md

Tests: Tests are included per technical plan requirements (component tests, E2E tests, visual regression tests)

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

  • [P]: Can run in parallel (different files, no dependencies)
  • [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
  • Include exact file paths in descriptions

Path Conventions

  • Monorepo structure: packages/drawnix/src/, packages/drawnix/tests/, apps/web/e2e/
  • Primary package: packages/drawnix (core whiteboard library)
  • Testing: Component tests in packages/drawnix/tests/, E2E in apps/web/e2e/

Phase 1: Setup (Shared Infrastructure)

Purpose: 项目结构准备和环境验证

  • T001 验证开发环境:检查 Node.js 18+, npm dependencies, TypeScript 编译通过 nx typecheck drawnix
  • T002 [P] 阅读现有工具栏实现:理解 app-toolbar.tsx, creation-toolbar.tsx, zoom-toolbar.tsx, theme-toolbar.tsx 的结构和依赖
  • T003 [P] 阅读主应用入口 packages/drawnix/src/drawnix.tsx,理解工具栏渲染逻辑和 DrawnixContext 使用

Phase 2: Foundational (Blocking Prerequisites)

Purpose: 为所有用户故事提供基础类型定义和样式变量

⚠️ CRITICAL: 所有用户故事必须等待此阶段完成后才能开始

  • T004 [P] 定义 TypeScript 类型:在 packages/drawnix/src/components/toolbar/toolbar.types.ts 创建 UnifiedToolbarProps 和 ToolbarSectionProps 接口
  • T005 [P] 添加 SCSS 变量和 mixin:在 packages/drawnix/src/styles/index.scss 添加工具栏相关 CSS 变量(border-color, spacing)和 BEM 基础结构

Checkpoint: 类型系统和样式基础就绪 - 用户故事实现可以并行开始

Phase 3: User Story 1 - 快速访问所有工具 (Priority: P1) 🎯 MVP

Goal: 在页面左侧创建统一垂直工具栏容器,包含四个工具分区,支持桌面端布局

Independent Test: 打开应用,验证左侧是否显示垂直工具栏,包含四个分区(应用工具、创作工具、缩放工具、主题选择),分区之间有 1px 分割线,移动端保持原有布局

Tests for User Story 1

NOTE: 先写测试,确保测试 FAIL 后再实现功能

  • T006 [P] [US1] 创建 UnifiedToolbar 组件测试骨架 packages/drawnix/tests/components/toolbar/unified-toolbar.test.tsx,测试四个分区是否正确渲染
  • T007 [P] [US1] 添加桌面/移动端条件渲染测试,验证 isMobile=false 时显示 UnifiedToolbar,isMobile=true 时显示独立工具栏

Implementation for User Story 1

  • T008 [US1] 创建 UnifiedToolbar 组件骨架 packages/drawnix/src/components/toolbar/unified-toolbar.tsx,包含基础 JSX 结构和类型定义(依赖 T004)
  • T009 [US1] 实现 UnifiedToolbar 容器布局:添加 ref、className 逻辑,渲染四个工具栏子组件(AppToolbar, CreationToolbar, ZoomToolbar, ThemeToolbar)
  • T010 [US1] 添加 UnifiedToolbar SCSS 样式 packages/drawnix/src/styles/index.scss:position absolute, left 36px, top 36px, flex column, 桌面端显示/移动端隐藏
  • T011 [P] [US1] 修改 AppToolbar 组件 packages/drawnix/src/components/toolbar/app-toolbar/app-toolbar.tsx:添加 embedded 和 iconMode props,条件应用样式
  • T012 [P] [US1] 修改 CreationToolbar 组件 packages/drawnix/src/components/toolbar/creation-toolbar.tsx:添加 embedded 和 iconMode props,条件应用样式
  • T013 [P] [US1] 修改 ZoomToolbar 组件 packages/drawnix/src/components/toolbar/zoom-toolbar.tsx:添加 embedded 和 iconMode props,条件应用样式
  • T014 [P] [US1] 修改 ThemeToolbar 组件 packages/drawnix/src/components/toolbar/theme-toolbar.tsx:添加 embedded 和 iconMode props,条件应用样式
  • T015 [US1] 集成 UnifiedToolbar 到主应用 packages/drawnix/src/drawnix.tsx:根据 appState.isMobile 条件渲染 UnifiedToolbar(桌面)或独立工具栏(移动端)
  • T016 [US1] 验证移动端布局不受影响:在 Chrome DevTools 移动设备模拟器测试,确认工具栏位置与改动前一致

Checkpoint: 此时桌面端应显示统一左侧工具栏,移动端保持原有布局,所有工具功能正常

Phase 4: User Story 2 - 清晰的工具分组 (Priority: P2)

Goal: 通过 1px 水平分割线清晰区分四个工具分区,提升视觉组织

Independent Test: 查看左侧工具栏,验证四个分区之间是否有明显的 1px 水平分割线,分区顺序从上到下为:应用工具、创作工具、缩放工具、主题选择

Tests for User Story 2

  • T017 [P] [US2] 添加视觉分隔测试 packages/drawnix/tests/components/toolbar/unified-toolbar.test.tsx:验证分区之间 border-top 样式正确应用
  • T018 [P] [US2] 添加分区顺序测试:验证四个分区按正确顺序渲染

Implementation for User Story 2

  • T019 [P] [US2] 添加 .unified-toolbar__section BEM 类名到每个嵌入的工具栏组件包装器 packages/drawnix/src/components/toolbar/unified-toolbar.tsx
  • T020 [US2] 实现分割线样式 packages/drawnix/src/styles/index.scss:为 .unified-toolbar__section:not(:first-child) 添加 border-top: 1px solid var(--color-border) 和 padding-top: 8px
  • T021 [US2] 验证分区分隔:手动测试四个分区之间是否显示 1px 分割线,颜色使用设计系统变量

Checkpoint: 工具栏分区之间应显示清晰的 1px 水平分割线,视觉层次清晰

Phase 5: User Story 3 - 移动端适配保持 (Priority: P3)

Goal: 确保移动设备工具栏布局保持现有行为,不受桌面端统一工具栏影响

Independent Test: 在移动设备或移动模拟器打开应用,验证工具栏位置与改动前完全一致(应用工具在底部,创作工具在顶部)

Tests for User Story 3

  • T022 [P] [US3] 创建移动端布局测试 packages/drawnix/tests/components/toolbar/mobile-toolbar.test.tsx:模拟 isMobile=true,验证独立工具栏渲染
  • T023 [P] [US3] 添加 E2E 移动端测试 apps/web/e2e/toolbar-mobile.spec.ts:使用 Playwright 移动视口测试工具栏位置 (注: E2E测试基础设施待补充)

Implementation for User Story 3

  • T024 [US3] 验证移动端 SCSS 样式不受影响 packages/drawnix/src/styles/index.scss:确认 @include isMobile mixin 样式仍然正确应用于独立工具栏
  • T025 [US3] 在多种移动设备模拟器测试:iPhone, iPad, Android 手机,验证工具栏布局和功能 (注: 需要手动测试验证)
  • T026 [US3] 验证桌面/移动切换:调整浏览器窗口大小,确认工具栏布局正确切换(注:实际应用中不会动态切换,isMobile 在初始化时确定)

Checkpoint: 移动端用户体验保持不变,桌面端和移动端布局互不影响

Phase 6: 响应式图标模式 (增强功能)

Goal: 当浏览器窗口高度不足时,工具栏自动切换到图标模式(隐藏文本标签),确保所有工具仍然可访问

Independent Test: 缩小浏览器窗口高度到约 500px 以下,验证工具栏是否自动隐藏文本标签,仅显示图标,恢复高度后恢复正常显示

Tests for Responsive Icon Mode

  • T027 [P] 添加响应式图标模式测试 packages/drawnix/tests/components/toolbar/unified-toolbar.test.tsx:模拟 ResizeObserver 触发,验证 isIconMode 状态切换
  • T028 [P] 添加图标模式样式测试:验证 unified-toolbar--icon-only 类名应用时文本标签隐藏

Implementation for Responsive Icon Mode

  • T029 实现 ResizeObserver 监听 packages/drawnix/src/components/toolbar/unified-toolbar.tsx:添加 useState(isIconMode), useEffect 监听容器高度变化,阈值约 460px
  • T030 传递 iconMode prop 到子工具栏:更新 AppToolbar, CreationToolbar, ZoomToolbar, ThemeToolbar 的 iconMode prop
  • T031 添加图标模式样式 packages/drawnix/src/styles/index.scss:在 .unified-toolbar--icon-only 修饰符下隐藏 .tool-icon__label
  • T032 优化响应式性能:使用 React.memo 包装 UnifiedToolbar,useCallback 包装 ResizeObserver 回调函数
  • T033 手动测试响应式切换:调整浏览器高度,验证工具栏平滑切换到图标模式,无布局抖动 (注: 需要手动测试验证)

Checkpoint: 工具栏支持响应式图标模式,小窗口下自动优化显示

Phase 7: Polish & Cross-Cutting Concerns

Purpose: 最终优化、测试和文档更新

  • T034 [P] 运行完整测试套件:nx test drawnix,确保所有组件测试通过 (注: 测试基础设施需完善,新增测试文件已创建)
  • T035 [P] 运行 E2E 测试:nx e2e web,验证工具栏功能和快捷键在实际应用中正常工作 (注: E2E测试需手动验证)
  • T036 [P] TypeScript 类型检查:nx typecheck drawnix,确保无新增类型错误 (预存在错误与本feature无关)
  • T037 [P] ESLint 检查:nx lint drawnix,修复所有 linting 错误 (新文件lint问题已修复)
  • T038 验证性能基准:使用 Chrome DevTools Performance tab 测试工具栏渲染 < 16ms,响应式切换 < 100ms (注: 需手动测试验证,已使用React.memo和useCallback优化)
  • T039 验证文件大小约束:确认所有文件 < 500行,UnifiedToolbar 组件约 85行 ✅
  • T040 [P] 视觉回归测试:截图对比桌面端和移动端工具栏布局,确认无意外变化 (注: 需手动测试验证)
  • T041 代码审查自检:按照宪章清单检查代码质量、命名约定、BEM 样式、可访问性属性(aria-label, title 保留) ✅
  • T042 清理调试代码:移除所有 console.log 和临时注释 ✅
  • T043 验证 quickstart.md 流程:按照 quickstart.md 步骤手动验证开发流程可行 (注: 开发流程已遵循)

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): 无依赖 - 可立即开始
  • Foundational (Phase 2): 依赖 Setup 完成 - 阻塞所有用户故事
  • User Stories (Phase 3-5): 所有依赖 Foundational 阶段完成
    • US1, US2, US3 可并行实现(如果有多个开发人员)
    • 或按优先级顺序(P1 → P2 → P3)
  • Responsive Icon Mode (Phase 6): 依赖 US1 完成(需要 UnifiedToolbar 组件存在)
  • Polish (Phase 7): 依赖所有功能实现完成

User Story Dependencies

  • User Story 1 (P1): Foundational 完成后可开始 - 无其他故事依赖
  • User Story 2 (P2): Foundational 完成后可开始 - 依赖 US1 的 UnifiedToolbar 组件,但可独立测试视觉分隔
  • User Story 3 (P3): Foundational 完成后可开始 - 完全独立,验证移动端不受影响

Within Each User Story

  • 测试必须先写,确保 FAIL 后再实现
  • T008(组件骨架) 必须在 T009(容器布局) 之前
  • T011-T014(修改子工具栏) 可并行,但必须在 T015(集成到主应用) 之前
  • T019(添加 BEM 类名) 必须在 T020(实现分割线样式) 之前

Parallel Opportunities

  • Phase 1: T002 和 T003 可并行(阅读不同文件)
  • Phase 2: T004 和 T005 可并行(类型定义和样式变量独立)
  • Phase 3: T006 和 T007 可并行(测试文件独立)
  • Phase 3: T011, T012, T013, T014 可并行(修改不同工具栏组件)
  • Phase 4: T017 和 T018 可并行(测试文件内不同测试用例)
  • Phase 5: T022 和 T023 可并行(组件测试和 E2E 测试独立)
  • Phase 6: T027 和 T028 可并行(测试文件内不同测试用例)
  • Phase 7: T034, T035, T036, T037, T040 可并行(不同类型的验证)

Parallel Example: User Story 1

# 并行启动 User Story 1 的测试任务:
Task: "创建 UnifiedToolbar 组件测试骨架 packages/drawnix/tests/components/toolbar/unified-toolbar.test.tsx"
Task: "添加桌面/移动端条件渲染测试"

# 并行启动 User Story 1 的子工具栏修改:
Task: "修改 AppToolbar 组件添加 embedded 和 iconMode props"
Task: "修改 CreationToolbar 组件添加 embedded 和 iconMode props"
Task: "修改 ZoomToolbar 组件添加 embedded 和 iconMode props"
Task: "修改 ThemeToolbar 组件添加 embedded 和 iconMode props"

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup (T001-T003) → ~15分钟
  2. Complete Phase 2: Foundational (T004-T005) → ~20分钟
  3. Complete Phase 3: User Story 1 (T006-T016) → ~1.5小时
  4. STOP and VALIDATE: 测试 User Story 1 独立运行,验证桌面端统一工具栏和移动端布局
  5. 如果就绪,可部署/演示 MVP

MVP 完成标志: 桌面端显示统一左侧工具栏,包含四个分区,移动端保持原有布局

Incremental Delivery

  1. Complete Setup + Foundational (T001-T005) → 基础就绪
  2. Add User Story 1 (T006-T016) → 独立测试 → 部署/演示 (MVP!)
  3. Add User Story 2 (T017-T021) → 独立测试 → 部署/演示 (视觉分隔增强)
  4. Add User Story 3 (T022-T026) → 独立测试 → 部署/演示 (移动端验证)
  5. Add Responsive Icon Mode (T027-T033) → 独立测试 → 部署/演示 (响应式增强)
  6. Polish (T034-T043) → 最终验证 → 生产部署

每个故事都增加价值,不破坏已有功能

Parallel Team Strategy

如果有多个开发人员:

  1. 团队一起完成 Setup + Foundational (T001-T005)
  2. Foundational 完成后:
    • Developer A: User Story 1 (T006-T016)
    • Developer B: User Story 2 (T017-T021) - 等待 T008-T010 完成后开始
    • Developer C: User Story 3 (T022-T026) - 可立即开始,完全独立
  3. 故事独立完成并集成

建议: 单人开发按优先级顺序实现,2-3人团队可并行 US2 和 US3

Notes

  • [P] 任务 = 不同文件,无依赖,可并行
  • [Story] 标签将任务映射到具体用户故事,便于追踪
  • 每个用户故事应该可独立完成和测试
  • 测试先行:确保测试 FAIL 后再实现功能
  • 每个任务或逻辑组完成后提交
  • 在每个 Checkpoint 停下来独立验证故事
  • 避免:模糊任务、文件冲突、跨故事依赖导致独立性被破坏

Task Checklist Summary

Total Tasks: 43

By Phase:

  • Phase 1 (Setup): 3 tasks
  • Phase 2 (Foundational): 2 tasks
  • Phase 3 (US1 - MVP): 11 tasks (2 tests + 9 implementation)
  • Phase 4 (US2): 5 tasks (2 tests + 3 implementation)
  • Phase 5 (US3): 5 tasks (2 tests + 3 implementation)
  • Phase 6 (Responsive): 7 tasks (2 tests + 5 implementation)
  • Phase 7 (Polish): 10 tasks

Parallel Opportunities: 18 tasks marked [P] can run concurrently

MVP Scope: Phase 1-3 (16 tasks, estimated 2-2.5 hours)

Full Feature: All phases (43 tasks, estimated 3-4 hours)

Format Validation

✅ All tasks follow checklist format: - [ ] [ID] [P?] [Story?] Description ✅ Sequential task IDs: T001-T043 ✅ Story labels applied to user story phases: [US1], [US2], [US3] ✅ File paths included in all implementation tasks ✅ Parallel markers [P] applied to independent tasks ✅ Tests precede implementation within each user story

Reference in New Issue View Git Blame Copy Permalink