kai/ColaFlow

Fork 0

Files

Yaojia Wang 08b317e789

Code Coverage / Generate Coverage Report (push) Has been cancelled

Details

Tests / Run Tests (9.0.x) (push) Has been cancelled

Details

Tests / Docker Build Test (push) Has been cancelled

Details

Tests / Test Summary (push) Has been cancelled

Details

Add trace files.

2025-11-04 23:28:56 +01:00

64 KiB

Raw Blame History

ColaFlow 前端开发评估与规划报告

报告日期: 2025-11-05 (Day 15) 报告人: Product Manager Agent 项目阶段: M1 核心项目模块 (78% 完成) 目标: 评估前端开发状态,规划 M1 阶段前端开发任务

执行摘要

ColaFlow 前端开发目前处于早期阶段,仅完成了 Kanban Board 看板功能(15个文件,1134行代码)。基于 Day 14-15 架构决策(采用 ProjectManagement Module),前端需要重新开发 Epic/Story/Task 管理界面,并与后端 ProjectManagement API 集成。

关键发现

已完成功能: Kanban Board (拖拽功能 + 4列工作流 + 基础 UI)
技术栈: React 18 + TypeScript + Zustand + Ant Design + React Query(推测)
代码规模: 15个文件,1134行代码
关键问题:
- 前端仅对接 Issue Management API,需要切换到 ProjectManagement API
- 缺失 Epic/Story/Task 三层层级管理 UI
- 缺失项目管理、迭代管理、用户管理等核心功能

重大架构决策影响

基于 Day 14-15 后端架构决策(采用 ProjectManagement Module):

前端需要重新开发: Epic/Story/Task 管理 UI(预计 2-3 天)
Kanban Board 需要更新: 适配 ProjectManagement API(预计 1 天)
新增开发任务: 项目管理、Sprint 管理、用户管理等核心 UI

M1 前端完成度评估

当前完成度: 约 15-20% (仅 Kanban Board)
M1 目标完成度: 100% (Epic/Story/Task + Project + Sprint + User Management)
预计剩余工作量: 18-22 天
目标完成日期: 2025-11-27 (与后端 M1 完成日期对齐)

一、当前前端状态评估

1.1 已完成功能清单

Kanban Board 看板 (Day 13) - 需要更新

完成度: 100% (基于 Issue Management API) 代码规模: 15 文件, 1,134 行代码 技术栈: React 18 + TypeScript + Zustand + Ant Design + @dnd-kit

核心功能:

拖拽式任务卡片 (@dnd-kit/core + @dnd-kit/sortable)
4列工作流: Backlog → Todo → InProgress → Done
任务卡片显示: Title, Type, Priority, Assignee
拖拽更新任务状态
基础 UI 交互

API 集成状态:

已对接 Issue Management API (7 个端点)
需要更新为 ProjectManagement API (Day 18-20)

问题与待改进:

⚠️ 当前对接 Issue Management API,需要切换到 ProjectManagement API
⚠️ 未显示 Epic/Story 层级关系
⚠️ 未显示工时信息 (EstimatedHours/ActualHours)
⚠️ 实时更新功能未完全集成 (SignalR 集成不完整)

状态: ✅ 完成 (需要更新以支持 ProjectManagement)

认证系统 (Day 11) - 生产就绪

完成度: 100% 核心功能:

登录/注册页面
JWT Token 管理
受保护路由 (Protected Routes)
用户会话管理

状态: ✅ 完成

1.2 代码结构分析 (推测)

基于后端文档和前端最佳实践,推测当前前端项目结构如下:

colaflow-frontend/
├── src/
│   ├── api/                    # API Clients (推测)
│   │   ├── auth.api.ts
│   │   └── issue.api.ts        # 需要替换为 ProjectManagement API
│   ├── components/             # React 组件
│   │   ├── kanban/             # Kanban Board 组件 (15 文件)
│   │   ├── auth/               # 认证相关组件
│   │   └── common/             # 通用组件
│   ├── hooks/                  # React Hooks (推测)
│   │   └── useAuth.ts
│   ├── store/                  # Zustand Store (推测)
│   │   └── authStore.ts
│   ├── types/                  # TypeScript 类型定义
│   ├── utils/                  # 工具函数
│   └── App.tsx
├── package.json
└── tsconfig.json

技术栈验证:

React 18 (已确认)
TypeScript (已确认)
Zustand (状态管理,已确认)
Ant Design (UI 组件库,已确认)
@dnd-kit (拖拽库,已确认)
React Query / SWR (数据获取库,推测)
React Router (路由管理,推测)
SignalR Client (@microsoft/signalr,推测)

1.3 技术债务识别

1.3.1 架构迁移债务 (CRITICAL)

问题: 当前 Kanban Board 对接 Issue Management API,需要切换到 ProjectManagement API

影响:

Issue API → Epic/Story/Task API 切换
数据结构变化 (扁平结构 → 三层层级)
UI 需要显示层级关系

工作量: 6-8 小时 (Day 18-20)

1.3.2 缺失功能债务 (HIGH)

缺失的核心功能:

Epic/Story/Task 三层层级管理 UI (项目规划核心功能)
项目管理界面 (创建/编辑/列表)
Sprint 迭代管理界面 (Scrum 核心功能)
用户管理界面 (团队协作核心功能)
Dashboard 仪表盘 (项目概览)

影响: 用户无法使用完整的项目管理功能

工作量: 14-18 天

1.3.3 实时协作集成债务 (MEDIUM)

问题: SignalR 实时更新未完全集成

影响:

多用户协作时无法实时看到其他用户的操作
Kanban Board 拖拽不实时同步

工作量: 2-3 小时 (Day 20)

1.3.4 代码质量债务 (LOW)

问题:

缺少单元测试 (测试覆盖率未知,推测 < 20%)
缺少 E2E 测试
代码文档不足
可能存在重复代码

影响: 代码可维护性和质量保证不足

工作量: 2-3 天 (可延后到 M1.5)

二、M1 阶段前端待开发功能清单

2.1 功能优先级分级 (P0/P1/P2)

基于产品计划 (product.md) 和后端架构决策,M1 阶段前端功能优先级如下:

P0 (Must Have) - M1 必须完成

2.1.1 Epic/Story/Task 三层层级管理 UI (CRITICAL)

业务价值: 项目规划核心功能,支持 Epic 拆解为 Stories,Stories 拆解为 Tasks

核心页面:

Epic 列表页 (/projects/{projectId}/epics)
- Epic 卡片列表 (网格布局)
- 显示: Epic Title, Description, Status, Story 计数, Progress
- 操作: Create Epic, Edit Epic, Delete Epic, 点击进入 Story 列表
Story 列表页 (/epics/{epicId}/stories)
- Story 卡片列表
- 显示: Story Title, Description, Status, Task 计数, Assignee, Progress
- 操作: Create Story, Edit Story, Delete Story, 点击进入 Task 列表
- 面包屑导航: Project → Epic → Story
Task 列表页 (/stories/{storyId}/tasks)
- Task 卡片列表或表格视图
- 显示: Task Title, Status, Priority, Assignee, EstimatedHours, ActualHours
- 操作: Create Task, Edit Task, Delete Task, Update Status
- 面包屑导航: Project → Epic → Story → Task
Epic/Story/Task 创建/编辑对话框
- Form 表单组件 (Ant Design Form)
- 字段: Title, Description, Type, Priority, Assignee, EstimatedHours, Sprint
- 验证: Required fields, format validation

技术实现:

API Clients: epic.api.ts, story.api.ts, task.api.ts
React Query Hooks: useEpics, useStories, useTasks
Components: EpicCard, StoryCard, TaskCard, CreateEpicDialog, etc.
路由: React Router 路由配置

验收标准:

用户可以创建/编辑/删除 Epic/Story/Task
三层层级关系正确显示
面包屑导航正确
API 调用正确,数据持久化
UI 响应式设计 (Mobile + Desktop)

工作量: 8-12 小时 (Day 18-20)

依赖: ProjectManagement API 完成 (Day 15-17)

2.1.2 Kanban Board 更新 - 支持 ProjectManagement (CRITICAL)

业务价值: 更新现有 Kanban Board 以支持 ProjectManagement Module

更新内容:

API 切换: Issue API → WorkTask API
- 更新 API Client (task.api.ts)
- 更新 React Query Hooks (useTasks)
- 更新数据结构 (Issue → WorkTask)
UI 增强: 显示层级信息
- TaskCard 显示所属 Epic/Story 信息
- TaskCard 显示工时信息 (EstimatedHours/ActualHours)
- 点击 Task 可跳转到所属 Story/Epic
拖拽更新: 适配 WorkTask 状态更新 API
- 拖拽更新 WorkTask 状态
- 拖拽时显示确认提示 (可选)

验收标准:

Kanban Board 正常显示 WorkTasks
拖拽更新状态正常工作
显示 Epic/Story 层级信息
显示工时信息
API 调用正确

工作量: 4-6 小时 (Day 19)

依赖: Epic/Story/Task API Clients 完成

2.1.3 Project Management UI (项目管理界面)

业务价值: 用户可以创建/管理项目,是所有功能的入口

核心页面:

项目列表页 (/projects)
- 项目卡片网格布局
- 显示: Project Name, Description, Team 人数, Issue 计数, Progress
- 操作: Create Project, Edit Project, Delete Project, 进入项目详情
项目详情页 (/projects/{projectId})
- 项目信息展示
- Tab 切换: Overview, Epics, Board, Sprints, Team, Settings
- 操作: Edit Project, Add Member, Remove Member
项目创建/编辑对话框
- Form 表单: Name, Description, Start Date, End Date
- 验证: Required fields

技术实现:

API Client: project.api.ts
React Query Hooks: useProjects, useProject, useCreateProject, etc.
Components: ProjectCard, ProjectDetail, CreateProjectDialog

验收标准:

用户可以创建/编辑/删除项目
项目列表正确显示
项目详情页 Tab 切换正常
API 调用正确

工作量: 6-8 小时 (Day 16-17)

依赖: Project API 完成 (Day 14-15 后端开发)

2.1.4 Sprint Management UI (迭代管理界面)

业务价值: Scrum 敏捷开发核心功能,支持迭代规划和跟踪

核心页面:

Sprint 列表页 (/projects/{projectId}/sprints)
- Sprint 卡片列表
- 显示: Sprint Name, Goal, Date Range, Status, Task 计数, Progress
- 操作: Create Sprint, Start Sprint, Complete Sprint, Close Sprint
Sprint 详情页 (/sprints/{sprintId})
- Sprint 信息展示
- Sprint Backlog (任务列表)
- Burndown Chart (燃尽图,基础版)
- 操作: Add Task to Sprint, Remove Task, Update Sprint
Sprint 创建/编辑对话框
- Form 表单: Name, Goal, Start Date, End Date
- 验证: Start Date < End Date

技术实现:

API Client: sprint.api.ts
React Query Hooks: useSprints, useSprint, useCreateSprint, etc.
Components: SprintCard, SprintDetail, CreateSprintDialog, BurndownChart

验收标准:

用户可以创建/启动/完成/关闭 Sprint
Sprint Backlog 正确显示
可以添加/移除 Task 到 Sprint
Burndown Chart 基础版显示
API 调用正确

工作量: 8-10 小时 (Day 21-22)

依赖: Sprint API 完成 (Day 31-34 后端开发)

2.1.5 User Management UI (用户管理界面)

业务价值: 团队协作核心功能,管理项目成员和权限

核心页面:

用户列表页 (/projects/{projectId}/team)
- 用户卡片或表格视图
- 显示: User Name, Email, Role, Assigned Tasks 计数
- 操作: Invite User, Update Role, Remove User
用户邀请对话框
- Form 表单: Email, Role (Owner/Admin/Member/Viewer/Guest)
- 验证: Email format
用户详情页 (/users/{userId}) (可选)
- 用户信息展示
- 用户负责的任务列表
- 用户活动历史

技术实现:

复用 Identity Module API (已完成)
API Client: user.api.ts, role.api.ts
React Query Hooks: useUsers, useInviteUser, useUpdateRole
Components: UserCard, InviteUserDialog, UserDetail

验收标准:

用户可以邀请新成员
用户可以更新成员角色
用户可以移除成员
权限控制正确 (只有 Owner/Admin 可以操作)
API 调用正确

工作量: 4-6 小时 (Day 17-18)

依赖: Identity API (已完成)

2.1.6 SignalR 实时更新集成 (CRITICAL)

业务价值: 多用户协作实时同步,提升用户体验

实时更新场景:

Kanban Board: 其他用户拖拽任务时实时更新
Epic/Story/Task 列表: 其他用户创建/更新/删除时实时更新
Sprint Backlog: 其他用户添加/移除任务时实时更新
Project 信息: 其他用户更新项目信息时实时更新

技术实现:

SignalR Client 配置 (@microsoft/signalr)
SignalR Connection 管理 (全局单例)
Event Listeners: 监听 ProjectHub/NotificationHub 事件
React Query Invalidation: 接收到事件时刷新数据
Toast 通知: 显示实时操作提示

事件监听:

ProjectCreated, ProjectUpdated, ProjectDeleted
EpicCreated, EpicUpdated, EpicDeleted
StoryCreated, StoryUpdated, StoryDeleted
TaskCreated, TaskStatusChanged, TaskDeleted
SprintStarted, SprintCompleted, TaskAddedToSprint

验收标准:

SignalR 连接正常建立
实时事件正确接收
UI 自动刷新 (React Query invalidation)
Toast 通知正常显示
多用户测试通过 (2+ users)

工作量: 4-6 小时 (Day 20)

依赖: SignalR Infrastructure 完成 (已完成)

P1 (Should Have) - M1 重要但非阻塞

2.1.7 Dashboard 仪表盘 (项目概览)

业务价值: 项目健康度可视化,帮助团队了解项目状态

核心内容:

项目统计卡片
- Total Epics, Stories, Tasks
- Completed Tasks, In Progress Tasks
- Team Members 计数
任务状态分布图 (饼图或柱状图)
- Backlog, Todo, InProgress, Done 数量
Sprint 进度条 (当前 Sprint)
- Sprint 名称, 剩余天数
- 完成度百分比
最近活动流 (Activity Stream)
- 最近创建/更新的任务
- 最近分配的任务

技术实现:

Chart 库: recharts or chart.js
API: 复用现有 API + 聚合数据
Components: Dashboard, StatCard, TaskChart, ActivityFeed

验收标准:

Dashboard 正确显示统计数据
图表渲染正常
数据自动刷新 (定时 or 实时)

工作量: 6-8 小时 (Day 23-24)

依赖: Epic/Story/Task/Sprint API 完成

2.1.8 高级搜索与过滤

业务价值: 提高任务查找效率

核心功能:

快速过滤器 (Quick Filters)
- My Tasks (我的任务)
- Unassigned (未分配)
- Overdue (逾期)
- High Priority (高优先级)
高级搜索表单
- 字段: Title, Assignee, Status, Priority, Type, Date Range
- 保存过滤条件 (可选)
搜索结果页
- 表格或卡片视图
- 分页 + 排序

技术实现:

Search API: 复用 List API with filters
Components: SearchBar, AdvancedFilter, SearchResults
URL Query Params: 保存过滤条件到 URL

验收标准:

快速过滤器正常工作
高级搜索返回正确结果
URL 可分享 (带过滤条件)

工作量: 4-6 小时 (Day 25-26)

依赖: Issue/Task List API with filters

P2 (Nice to Have) - M1 可延后到 M1.5 或 M2

2.1.9 任务详情页 (全屏模式)

业务价值: 深度查看和编辑任务详情

核心内容:

Task 完整信息展示
描述 (富文本编辑器)
评论系统 (Comments)
附件上传 (Attachments)
活动历史 (Activity Log)
子任务 (Sub-tasks)

工作量: 8-10 小时

优先级: P2 (可延后到 M2)

2.1.10 Gantt Chart 甘特图

业务价值: 项目时间线可视化

核心内容:

任务时间轴
依赖关系
里程碑

工作量: 10-12 小时

优先级: P2 (可延后到 M2)

2.1.11 通知系统

业务价值: 及时提醒用户任务变更

核心内容:

In-app Notifications
通知列表
标记为已读

工作量: 6-8 小时

优先级: P2 (可延后到 M2)

三、前端开发任务分解与工时估算

3.1 任务分解树 (Task Breakdown Structure)

M1 前端开发 (18-22 天)
├── Phase 1: ProjectManagement 前端集成 (Day 16-20, 5 天)
│   ├── 1.1 API Clients 创建 (2-3h)
│   │   ├── epic.api.ts (Create, Read, Update, Delete, List, GetWithStories)
│   │   ├── story.api.ts (Create, Read, Update, Delete, List, GetWithTasks)
│   │   └── task.api.ts (Create, Read, Update, Delete, List, UpdateStatus)
│   ├── 1.2 React Query Hooks (2-3h)
│   │   ├── useEpics, useEpic, useCreateEpic, useUpdateEpic, useDeleteEpic
│   │   ├── useStories, useStory, useCreateStory, useUpdateStory, useDeleteStory
│   │   └── useTasks, useTask, useCreateTask, useUpdateTask, useDeleteTask
│   ├── 1.3 Epic/Story/Task 管理 UI (8-12h)
│   │   ├── Epic 列表页 + EpicCard + CreateEpicDialog (3-4h)
│   │   ├── Story 列表页 + StoryCard + CreateStoryDialog (3-4h)
│   │   ├── Task 列表页 + TaskCard + CreateTaskDialog (2-4h)
│   │   └── 面包屑导航 + 路由配置 (1h)
│   ├── 1.4 Kanban Board 更新 (4-6h)
│   │   ├── API Client 切换 (Issue → WorkTask) (2h)
│   │   ├── TaskCard 增强 (显示层级 + 工时) (2h)
│   │   └── 拖拽状态更新适配 (1-2h)
│   └── 1.5 SignalR 实时更新集成 (4-6h)
│       ├── SignalR Client 配置 (1h)
│       ├── Event Listeners 实现 (2-3h)
│       └── React Query Invalidation (1-2h)
│
├── Phase 2: 项目管理与用户管理 (Day 17-18, 2 天)
│   ├── 2.1 Project Management UI (6-8h)
│   │   ├── API Client: project.api.ts (1h)
│   │   ├── React Query Hooks (1h)
│   │   ├── 项目列表页 + ProjectCard (2-3h)
│   │   ├── 项目详情页 (Tab 切换) (2-3h)
│   │   └── 创建/编辑对话框 (1h)
│   └── 2.2 User Management UI (4-6h)
│       ├── API Client: user.api.ts, role.api.ts (1h)
│       ├── React Query Hooks (1h)
│       ├── 用户列表页 + UserCard (2-3h)
│       └── 邀请用户对话框 (1h)
│
├── Phase 3: Sprint 管理与 Dashboard (Day 21-24, 4 天)
│   ├── 3.1 Sprint Management UI (8-10h)
│   │   ├── API Client: sprint.api.ts (1h)
│   │   ├── React Query Hooks (1h)
│   │   ├── Sprint 列表页 + SprintCard (2-3h)
│   │   ├── Sprint 详情页 + Backlog (3-4h)
│   │   └── Burndown Chart 基础版 (2h)
│   └── 3.2 Dashboard 仪表盘 (6-8h)
│       ├── 统计卡片 (2h)
│       ├── 任务状态分布图 (2-3h)
│       ├── Sprint 进度条 (1h)
│       └── 最近活动流 (2h)
│
├── Phase 4: 高级功能与优化 (Day 25-27, 3 天)
│   ├── 4.1 高级搜索与过滤 (4-6h)
│   │   ├── 快速过滤器 (2h)
│   │   ├── 高级搜索表单 (2h)
│   │   └── 搜索结果页 (1-2h)
│   ├── 4.2 UI/UX 优化 (4-6h)
│   │   ├── 响应式设计优化 (2h)
│   │   ├── Loading 状态优化 (1h)
│   │   ├── Error Handling 优化 (1h)
│   │   └── 动画与过渡效果 (1-2h)
│   └── 4.3 性能优化 (2-4h)
│       ├── React.memo 应用 (1h)
│       ├── 虚拟滚动 (可选) (2h)
│       └── 代码分割 (Code Splitting) (1h)
│
└── Phase 5: 测试与文档 (Day 28-30, 3 天)
    ├── 5.1 E2E 测试 (8-10h)
    │   ├── Cypress/Playwright 配置 (2h)
    │   ├── 核心流程测试 (5+ scenarios) (5-7h)
    │   └── CI/CD 集成 (1h)
    ├── 5.2 单元测试 (可选) (4-6h)
    │   ├── Component 测试 (2-3h)
    │   └── Hooks 测试 (2-3h)
    └── 5.3 文档编写 (2-3h)
        ├── 前端开发指南 (1h)
        ├── 组件文档 (Storybook,可选) (1h)
        └── 部署指南 (1h)

3.2 工时估算汇总表

Phase	任务	预计工时	依赖	优先级
Phase 1	ProjectManagement 前端集成	18-28h (2.5-3.5天)	后端 ProjectManagement API	P0
1.1	API Clients 创建	2-3h	后端 API	P0
1.2	React Query Hooks	2-3h	1.1	P0
1.3	Epic/Story/Task 管理 UI	8-12h	1.2	P0
1.4	Kanban Board 更新	4-6h	1.3	P0
1.5	SignalR 实时更新集成	4-6h	1.4	P0
Phase 2	项目管理与用户管理	10-14h (1.5-2天)	后端 Project/User API	P0
2.1	Project Management UI	6-8h	后端 Project API	P0
2.2	User Management UI	4-6h	后端 Identity API	P0
Phase 3	Sprint 管理与 Dashboard	14-18h (2-2.5天)	后端 Sprint API	P0
3.1	Sprint Management UI	8-10h	后端 Sprint API	P0
3.2	Dashboard 仪表盘	6-8h	Phase 1-2	P1
Phase 4	高级功能与优化	10-16h (1.5-2天)	Phase 1-3	P1
4.1	高级搜索与过滤	4-6h	Phase 1	P1
4.2	UI/UX 优化	4-6h	Phase 1-3	P1
4.3	性能优化	2-4h	Phase 1-3	P1
Phase 5	测试与文档	14-19h (2-2.5天)	Phase 1-4	P1
5.1	E2E 测试	8-10h	Phase 1-3	P1
5.2	单元测试 (可选)	4-6h	Phase 1-3	P2
5.3	文档编写	2-3h	All	P1
总计		66-95h (9-13天)

考虑缓冲时间 + Bug 修复 + 返工: 18-22天 (每天 5-6 小时有效工作时间)

3.3 依赖关系图

后端 ProjectManagement API (Day 15-17) 完成
  ↓
前端 Phase 1: ProjectManagement 前端集成 (Day 18-20)
  ↓
前端 Phase 2: 项目管理与用户管理 (Day 21-22)
  ↓ (并行)
后端 Sprint API (Day 31-34) 完成
  ↓
前端 Phase 3: Sprint 管理与 Dashboard (Day 23-24)
  ↓
前端 Phase 4: 高级功能与优化 (Day 25-27)
  ↓
前端 Phase 5: 测试与文档 (Day 28-30)

关键依赖:

✅ 后端 Identity API - 已完成
✅ 后端 SignalR Infrastructure - 已完成
⏳ 后端 ProjectManagement API - Day 15-17 (阻塞 Phase 1)
⏳ 后端 Project API - Day 14-15 (阻塞 Phase 2)
⏳ 后端 Sprint API - Day 31-34 (阻塞 Phase 3)

四、前端技术规范与最佳实践

4.1 项目结构规范

colaflow-frontend/
├── public/                     # 静态资源
├── src/
│   ├── api/                    # API Clients (Axios 封装)
│   │   ├── client.ts           # Axios 实例配置 (baseURL, interceptors)
│   │   ├── auth.api.ts         # 认证 API
│   │   ├── project.api.ts      # 项目管理 API
│   │   ├── epic.api.ts         # Epic API
│   │   ├── story.api.ts        # Story API
│   │   ├── task.api.ts         # Task API
│   │   ├── sprint.api.ts       # Sprint API
│   │   └── user.api.ts         # 用户管理 API
│   ├── components/             # React 组件 (原子设计模式)
│   │   ├── atoms/              # 原子组件 (Button, Input, Card)
│   │   ├── molecules/          # 分子组件 (SearchBar, TaskCard)
│   │   ├── organisms/          # 有机组件 (Kanban, EpicList)
│   │   └── templates/          # 模板组件 (PageLayout)
│   ├── pages/                  # 页面组件 (路由页面)
│   │   ├── LoginPage.tsx
│   │   ├── ProjectsPage.tsx
│   │   ├── EpicsPage.tsx
│   │   ├── KanbanPage.tsx
│   │   └── DashboardPage.tsx
│   ├── hooks/                  # 自定义 Hooks
│   │   ├── useAuth.ts          # 认证 Hook
│   │   ├── useProjects.ts      # 项目管理 Hooks (React Query)
│   │   ├── useEpics.ts         # Epic Hooks
│   │   ├── useStories.ts       # Story Hooks
│   │   ├── useTasks.ts         # Task Hooks
│   │   ├── useSprints.ts       # Sprint Hooks
│   │   └── useSignalR.ts       # SignalR Hook
│   ├── store/                  # Zustand Store (全局状态)
│   │   ├── authStore.ts        # 认证状态
│   │   ├── uiStore.ts          # UI 状态 (sidebar, theme)
│   │   └── index.ts
│   ├── types/                  # TypeScript 类型定义
│   │   ├── api.types.ts        # API 请求/响应类型
│   │   ├── domain.types.ts     # 领域模型类型 (Epic, Story, Task)
│   │   └── index.ts
│   ├── utils/                  # 工具函数
│   │   ├── formatters.ts       # 格式化函数 (date, number)
│   │   ├── validators.ts       # 验证函数
│   │   └── constants.ts        # 常量定义
│   ├── styles/                 # 全局样式
│   │   ├── global.css          # 全局 CSS
│   │   └── antd-theme.ts       # Ant Design 主题配置
│   ├── App.tsx                 # 应用根组件
│   ├── main.tsx                # 应用入口
│   └── router.tsx              # 路由配置 (React Router)
├── tests/                      # 测试文件
│   ├── e2e/                    # E2E 测试 (Cypress/Playwright)
│   └── unit/                   # 单元测试 (Vitest)
├── .env.example                # 环境变量示例
├── package.json
├── tsconfig.json
└── vite.config.ts              # Vite 配置

4.2 技术栈规范

4.2.1 核心技术栈

技术	版本	用途	备注
React	18.x	UI 框架	使用 Hooks,禁用 Class Components
TypeScript	5.x	类型系统	严格模式 (strict: true)
Vite	5.x	构建工具	快速开发,HMR
React Router	6.x	路由管理	使用 Data Router (createBrowserRouter)
Ant Design	5.x	UI 组件库	按需导入,自定义主题
Zustand	4.x	状态管理	轻量级,替代 Redux
React Query	5.x	数据获取与缓存	Server State 管理
Axios	1.x	HTTP Client	统一封装,拦截器
@dnd-kit	6.x	拖拽库	Kanban Board 拖拽
@microsoft/signalr	8.x	SignalR Client	实时通信
Zod	3.x	数据验证	API 响应验证,Form 验证
date-fns	3.x	日期处理	替代 moment.js (更轻量)
recharts	2.x	图表库	Dashboard 图表

4.2.2 开发工具

工具	用途
ESLint	代码规范检查
Prettier	代码格式化
Husky	Git Hooks (pre-commit, pre-push)
lint-staged	只检查暂存文件
Vitest	单元测试 (Vite 原生支持)
Cypress/Playwright	E2E 测试
Storybook (可选)	组件文档

4.3 代码规范

4.3.1 组件设计规范

1. 使用函数组件 + Hooks

// ✅ Good
const TaskCard: React.FC<TaskCardProps> = ({ task }) => {
  const { mutate } = useUpdateTask();
  // ...
};

// ❌ Bad
class TaskCard extends React.Component { }

2. Props 类型定义

interface TaskCardProps {
  task: Task;
  onEdit?: (task: Task) => void;
  onDelete?: (taskId: string) => void;
  className?: string;
}

3. 组件拆分原则

单一职责原则 (SRP): 一个组件只做一件事
组件行数 < 200 行 (超过则拆分)
复杂逻辑提取到自定义 Hook

4. 命名规范

组件: PascalCase (TaskCard, EpicList)
函数/变量: camelCase (fetchTasks, isLoading)
常量: UPPER_SNAKE_CASE (API_BASE_URL)
文件名: kebab-case (task-card.tsx, use-tasks.ts)

4.3.2 状态管理规范

1. Zustand Store (Client State)

用途: 全局 UI 状态 (sidebar 开关, theme, 当前用户等)

// authStore.ts
import { create } from 'zustand';

interface AuthState {
  user: User | null;
  token: string | null;
  setUser: (user: User) => void;
  logout: () => void;
}

export const useAuthStore = create<AuthState>((set) => ({
  user: null,
  token: null,
  setUser: (user) => set({ user }),
  logout: () => set({ user: null, token: null }),
}));

2. React Query (Server State)

用途: 服务端数据获取、缓存、同步

// useTasks.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { taskApi } from '@/api/task.api';

export const useTasks = (storyId: string) => {
  return useQuery({
    queryKey: ['tasks', storyId],
    queryFn: () => taskApi.listTasks(storyId),
    staleTime: 5 * 60 * 1000, // 5分钟
  });
};

export const useCreateTask = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: taskApi.createTask,
    onSuccess: (data) => {
      queryClient.invalidateQueries({ queryKey: ['tasks', data.storyId] });
    },
  });
};

3. 状态选择原则

Client State (Zustand): 全局 UI 状态, 用户登录状态
Server State (React Query): API 数据, 缓存数据
Component State (useState): 局部 UI 状态 (modal open, form input)

4.3.3 API 调用规范

1. Axios 实例配置

// api/client.ts
import axios from 'axios';
import { useAuthStore } from '@/store/authStore';

export const apiClient = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL || 'http://localhost:5000/api',
  timeout: 10000,
});

// 请求拦截器: 添加 JWT Token
apiClient.interceptors.request.use((config) => {
  const token = useAuthStore.getState().token;
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 响应拦截器: 处理错误
apiClient.interceptors.response.use(
  (response) => response.data,
  (error) => {
    if (error.response?.status === 401) {
      useAuthStore.getState().logout();
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

2. API Client 模块化

// api/task.api.ts
import { apiClient } from './client';
import type { Task, CreateTaskRequest, UpdateTaskRequest } from '@/types';

export const taskApi = {
  createTask: (data: CreateTaskRequest): Promise<Task> =>
    apiClient.post('/tasks', data),

  getTask: (id: string): Promise<Task> =>
    apiClient.get(`/tasks/${id}`),

  listTasks: (storyId: string): Promise<Task[]> =>
    apiClient.get('/tasks', { params: { storyId } }),

  updateTask: (id: string, data: UpdateTaskRequest): Promise<Task> =>
    apiClient.put(`/tasks/${id}`, data),

  updateTaskStatus: (id: string, status: string): Promise<Task> =>
    apiClient.patch(`/tasks/${id}/status`, { status }),

  deleteTask: (id: string): Promise<void> =>
    apiClient.delete(`/tasks/${id}`),
};

3. TypeScript 类型定义

// types/domain.types.ts
export interface Task {
  id: string;
  title: string;
  description?: string;
  status: TaskStatus;
  priority: TaskPriority;
  assigneeId?: string;
  storyId: string;
  epicId?: string;
  estimatedHours?: number;
  actualHours?: number;
  createdAt: string;
  updatedAt: string;
}

export enum TaskStatus {
  Backlog = 'Backlog',
  Todo = 'Todo',
  InProgress = 'InProgress',
  Done = 'Done',
}

export enum TaskPriority {
  Low = 'Low',
  Medium = 'Medium',
  High = 'High',
  Critical = 'Critical',
}

export interface CreateTaskRequest {
  title: string;
  description?: string;
  storyId: string;
  priority?: TaskPriority;
  assigneeId?: string;
  estimatedHours?: number;
}

4.3.4 路由管理规范

1. React Router 配置 (Data Router)

// router.tsx
import { createBrowserRouter, Navigate } from 'react-router-dom';
import { ProtectedRoute } from '@/components/ProtectedRoute';

export const router = createBrowserRouter([
  {
    path: '/login',
    element: <LoginPage />,
  },
  {
    path: '/',
    element: <ProtectedRoute><AppLayout /></ProtectedRoute>,
    children: [
      { index: true, element: <Navigate to="/projects" replace /> },
      { path: 'projects', element: <ProjectsPage /> },
      { path: 'projects/:projectId', element: <ProjectDetailPage /> },
      { path: 'projects/:projectId/epics', element: <EpicsPage /> },
      { path: 'epics/:epicId/stories', element: <StoriesPage /> },
      { path: 'stories/:storyId/tasks', element: <TasksPage /> },
      { path: 'projects/:projectId/board', element: <KanbanPage /> },
      { path: 'projects/:projectId/sprints', element: <SprintsPage /> },
      { path: 'dashboard', element: <DashboardPage /> },
    ],
  },
]);

2. 受保护路由

// components/ProtectedRoute.tsx
import { Navigate } from 'react-router-dom';
import { useAuthStore } from '@/store/authStore';

export const ProtectedRoute: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const token = useAuthStore((state) => state.token);
  if (!token) {
    return <Navigate to="/login" replace />;
  }
  return <>{children}</>;
};

4.3.5 表单处理规范

推荐使用 Ant Design Form + React Hook Form (可选)

1. Ant Design Form 示例

// CreateTaskDialog.tsx
import { Form, Input, Select, Modal } from 'antd';
import { useCreateTask } from '@/hooks/useTasks';

export const CreateTaskDialog: React.FC<Props> = ({ open, onClose, storyId }) => {
  const [form] = Form.useForm();
  const { mutate: createTask, isPending } = useCreateTask();

  const handleSubmit = async () => {
    const values = await form.validateFields();
    createTask({ ...values, storyId }, {
      onSuccess: () => {
        form.resetFields();
        onClose();
      },
    });
  };

  return (
    <Modal
      title="Create Task"
      open={open}
      onOk={handleSubmit}
      onCancel={onClose}
      confirmLoading={isPending}
    >
      <Form form={form} layout="vertical">
        <Form.Item
          name="title"
          label="Title"
          rules={[{ required: true, message: 'Please input task title' }]}
        >
          <Input placeholder="Task title" />
        </Form.Item>
        <Form.Item name="description" label="Description">
          <Input.TextArea rows={4} />
        </Form.Item>
        <Form.Item name="priority" label="Priority" initialValue="Medium">
          <Select>
            <Select.Option value="Low">Low</Select.Option>
            <Select.Option value="Medium">Medium</Select.Option>
            <Select.Option value="High">High</Select.Option>
            <Select.Option value="Critical">Critical</Select.Option>
          </Select>
        </Form.Item>
      </Form>
    </Modal>
  );
};

4.3.6 错误处理规范

1. API 错误处理

// hooks/useTasks.ts
export const useCreateTask = () => {
  return useMutation({
    mutationFn: taskApi.createTask,
    onError: (error: AxiosError<{ message: string }>) => {
      const message = error.response?.data?.message || 'Failed to create task';
      notification.error({ message: 'Error', description: message });
    },
  });
};

2. ErrorBoundary 组件

// components/ErrorBoundary.tsx
import { Component, ReactNode } from 'react';
import { Result, Button } from 'antd';

interface Props {
  children: ReactNode;
}

interface State {
  hasError: boolean;
  error?: Error;
}

export class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  render() {
    if (this.state.hasError) {
      return (
        <Result
          status="500"
          title="Something went wrong"
          subTitle={this.state.error?.message}
          extra={<Button onClick={() => window.location.reload()}>Reload</Button>}
        />
      );
    }
    return this.props.children;
  }
}

4.3.7 SignalR 集成规范

1. SignalR Connection 管理

// hooks/useSignalR.ts
import { useEffect, useRef } from 'react';
import { HubConnection, HubConnectionBuilder } from '@microsoft/signalr';
import { useAuthStore } from '@/store/authStore';
import { useQueryClient } from '@tanstack/react-query';

export const useSignalR = () => {
  const connectionRef = useRef<HubConnection | null>(null);
  const token = useAuthStore((state) => state.token);
  const queryClient = useQueryClient();

  useEffect(() => {
    if (!token) return;

    const connection = new HubConnectionBuilder()
      .withUrl(`${import.meta.env.VITE_API_BASE_URL}/hubs/project`, {
        accessTokenFactory: () => token,
      })
      .withAutomaticReconnect()
      .build();

    connection.start().then(() => {
      console.log('SignalR connected');
    });

    // 监听事件
    connection.on('TaskStatusChanged', (taskId: string, status: string) => {
      queryClient.invalidateQueries({ queryKey: ['tasks'] });
      notification.info({ message: `Task ${taskId} status changed to ${status}` });
    });

    connection.on('EpicCreated', (epic: Epic) => {
      queryClient.invalidateQueries({ queryKey: ['epics'] });
      notification.success({ message: `Epic "${epic.title}" created` });
    });

    connectionRef.current = connection;

    return () => {
      connection.stop();
    };
  }, [token, queryClient]);

  return connectionRef.current;
};

2. 在 App 级别使用 SignalR Hook

// App.tsx
import { useSignalR } from '@/hooks/useSignalR';

export const App: React.FC = () => {
  useSignalR(); // 全局启动 SignalR 连接

  return (
    <QueryClientProvider client={queryClient}>
      <ErrorBoundary>
        <RouterProvider router={router} />
      </ErrorBoundary>
    </QueryClientProvider>
  );
};

4.3.8 性能优化规范

1. React.memo 应用

// TaskCard.tsx
export const TaskCard = React.memo<TaskCardProps>(({ task, onEdit, onDelete }) => {
  // ...
}, (prevProps, nextProps) => {
  return prevProps.task.id === nextProps.task.id &&
         prevProps.task.updatedAt === nextProps.task.updatedAt;
});

2. useMemo 和 useCallback

const TaskList: React.FC<Props> = ({ tasks, onTaskClick }) => {
  const sortedTasks = useMemo(() => {
    return tasks.sort((a, b) => a.priority - b.priority);
  }, [tasks]);

  const handleTaskClick = useCallback((taskId: string) => {
    onTaskClick(taskId);
  }, [onTaskClick]);

  return (
    <>
      {sortedTasks.map(task => (
        <TaskCard key={task.id} task={task} onClick={handleTaskClick} />
      ))}
    </>
  );
};

3. 代码分割 (Code Splitting)

// Lazy load heavy components
const KanbanPage = lazy(() => import('@/pages/KanbanPage'));
const DashboardPage = lazy(() => import('@/pages/DashboardPage'));

// In router
{
  path: 'board',
  element: <Suspense fallback={<Spin />}><KanbanPage /></Suspense>
}

4. 虚拟滚动 (可选,长列表优化)

import { FixedSizeList } from 'react-window';

const TaskList: React.FC<Props> = ({ tasks }) => {
  return (
    <FixedSizeList
      height={600}
      itemCount={tasks.length}
      itemSize={80}
      width="100%"
    >
      {({ index, style }) => (
        <div style={style}>
          <TaskCard task={tasks[index]} />
        </div>
      )}
    </FixedSizeList>
  );
};

4.4 国际化 (i18n) 建议

M1 阶段暂不实施,M2 考虑引入

推荐技术: react-i18next or next-intl

五、前端开发时间计划 (4周内完成 M1 前端)

5.1 总体时间线

周次	日期	Phase	主要任务	工作量	状态
Week 1	Day 16-20	Phase 1	ProjectManagement 前端集成	3.5-4天	⏳ 计划中
Day 16	2025-11-08	Phase 1.1-1.2	API Clients + React Query Hooks	4-6h	⏳
Day 17	2025-11-09	Phase 1.3	Epic/Story 列表页	6-8h	⏳
Day 18	2025-11-10	Phase 1.3	Task 列表页 + 面包屑导航	6-8h	⏳
Day 19	2025-11-11	Phase 1.4	Kanban Board 更新	4-6h	⏳
Day 20	2025-11-12	Phase 1.5	SignalR 实时更新集成	4-6h	⏳
Week 2	Day 21-25	Phase 2-3	项目/用户/Sprint 管理	5天	⏳ 计划中
Day 21	2025-11-13	Phase 2.1	Project Management UI	6-8h	⏳
Day 22	2025-11-14	Phase 2.2	User Management UI	4-6h	⏳
Day 23	2025-11-15	Phase 3.1	Sprint Management UI (Part 1)	4-5h	⏳
Day 24	2025-11-16	Phase 3.1	Sprint Management UI (Part 2) + Burndown	4-5h	⏳
Day 25	2025-11-17	Phase 3.2	Dashboard 仪表盘	6-8h	⏳
Week 3	Day 26-30	Phase 4-5	高级功能 + 测试	5天	⏳ 计划中
Day 26	2025-11-18	Phase 4.1	高级搜索与过滤	4-6h	⏳
Day 27	2025-11-19	Phase 4.2-4.3	UI/UX 优化 + 性能优化	6-10h	⏳
Day 28	2025-11-20	Phase 5.1	E2E 测试 (Part 1)	4-5h	⏳
Day 29	2025-11-21	Phase 5.1	E2E 测试 (Part 2)	4-5h	⏳
Day 30	2025-11-22	Phase 5.3	文档编写	2-3h	⏳
Week 4	Day 31-35	缓冲 + 集成	Bug 修复 + 集成测试	5天	⏳ 计划中
Day 31-35	2025-11-23至27	缓冲	Bug 修复, 返工, 集成测试, M1 验收	40h	⏳

目标完成日期: 2025-11-27 (与后端 M1 完成日期对齐)

5.2 详细每日任务分解

Week 1: ProjectManagement 前端集成 (Day 16-20)

Day 16 (2025-11-08) - API Clients + React Query Hooks

时间: 4-6 小时

08:00-10:00: API Clients 创建
- epic.api.ts (6个方法)
- story.api.ts (6个方法)
- task.api.ts (6个方法)
10:00-12:00: React Query Hooks 创建
- useEpics, useEpic, useCreateEpic, useUpdateEpic, useDeleteEpic
- useStories, useStory, useCreateStory, useUpdateStory, useDeleteStory
- useTasks, useTask, useCreateTask, useUpdateTask, useDeleteTask
13:00-14:00: TypeScript 类型定义
- Epic, Story, WorkTask 类型
- CreateEpicRequest, UpdateEpicRequest 等
14:00-15:00: API 集成测试 (手动测试 API 调用)

交付物:

✅ API Clients (epic.api.ts, story.api.ts, task.api.ts)
✅ React Query Hooks (useEpics, useStories, useTasks)
✅ TypeScript 类型定义

Day 17 (2025-11-09) - Epic/Story 列表页

时间: 6-8 小时

08:00-11:00: Epic 列表页
- EpicCard 组件 (显示 Epic 信息 + Story 计数)
- EpicsPage 页面布局
- CreateEpicDialog 组件
- 路由配置 (/projects/{id}/epics)
11:00-12:00: Epic CRUD 功能测试
13:00-16:00: Story 列表页
- StoryCard 组件 (显示 Story 信息 + Task 计数)
- StoriesPage 页面布局
- CreateStoryDialog 组件
- 路由配置 (/epics/{id}/stories)
- 面包屑导航 (Project → Epic → Story)

交付物:

✅ Epic 列表页 + CRUD 功能
✅ Story 列表页 + CRUD 功能
✅ 面包屑导航

Day 18 (2025-11-10) - Task 列表页 + 面包屑导航

时间: 6-8 小时

08:00-11:00: Task 列表页
- TaskCard 组件 (显示 Task 信息 + 状态)
- TasksPage 页面布局
- CreateTaskDialog 组件
- 路由配置 (/stories/{id}/tasks)
- 面包屑导航 (Project → Epic → Story → Task)
11:00-12:00: Task CRUD 功能测试
13:00-15:00: 三层层级导航优化
- 点击 Task 可跳转到所属 Story/Epic
- 显示完整层级路径
15:00-16:00: UI/UX 细节优化

交付物:

✅ Task 列表页 + CRUD 功能
✅ 完整三层层级导航

Day 19 (2025-11-11) - Kanban Board 更新

时间: 4-6 小时

08:00-10:00: API Client 切换
- 更新 Kanban API Client (Issue → WorkTask)
- 更新 React Query Hooks
- 更新数据结构 (Issue → WorkTask)
10:00-12:00: TaskCard 增强
- 显示 Epic/Story 层级信息
- 显示工时信息 (EstimatedHours/ActualHours)
- 点击 Task 跳转到所属 Story/Epic
13:00-14:00: 拖拽状态更新适配
- 拖拽更新 WorkTask 状态
- 拖拽时显示确认提示 (可选)
14:00-15:00: Kanban Board 功能测试

交付物:

✅ Kanban Board 支持 ProjectManagement
✅ 显示层级信息和工时信息

Day 20 (2025-11-12) - SignalR 实时更新集成

时间: 4-6 小时

08:00-09:00: SignalR Client 配置
- useSignalR Hook 实现
- SignalR Connection 管理
09:00-12:00: Event Listeners 实现
- EpicCreated, EpicUpdated, EpicDeleted
- StoryCreated, StoryUpdated, StoryDeleted
- TaskCreated, TaskStatusChanged, TaskDeleted
- SprintStarted, SprintCompleted, TaskAddedToSprint
13:00-15:00: React Query Invalidation
- 接收到事件时刷新对应数据
- Toast 通知显示
15:00-16:00: 多用户实时测试 (2+ users)

交付物:

✅ SignalR 实时更新正常工作
✅ 多用户协作测试通过

Week 2: 项目/用户/Sprint 管理 (Day 21-25)

Day 21 (2025-11-13) - Project Management UI

时间: 6-8 小时

08:00-10:00: API Client + Hooks
- project.api.ts
- useProjects, useProject, useCreateProject, etc.
10:00-12:00: 项目列表页
- ProjectCard 组件
- ProjectsPage 页面布局
- 路由配置 (/projects)
13:00-16:00: 项目详情页
- ProjectDetail 组件
- Tab 切换 (Overview, Epics, Board, Sprints, Team, Settings)
- CreateProjectDialog 组件

交付物:

✅ 项目列表页 + 详情页
✅ 项目 CRUD 功能

Day 22 (2025-11-14) - User Management UI

时间: 4-6 小时

08:00-09:00: API Client + Hooks
- user.api.ts, role.api.ts
- useUsers, useInviteUser, useUpdateRole
09:00-12:00: 用户列表页
- UserCard 组件 (或表格视图)
- TeamPage 页面布局
- InviteUserDialog 组件
- 路由配置 (/projects/{id}/team)
13:00-14:00: 权限控制
- 只有 Owner/Admin 可以邀请/移除用户
- UI 根据用户角色显示/隐藏操作按钮

交付物:

✅ 用户列表页 + 邀请/移除功能
✅ 权限控制正确

Day 23-24 (2025-11-15至16) - Sprint Management UI

时间: 8-10 小时 (2天)

Day 23 08:00-09:00: API Client + Hooks
- sprint.api.ts
- useSprints, useSprint, useCreateSprint, etc.
Day 23 09:00-12:00: Sprint 列表页
- SprintCard 组件
- SprintsPage 页面布局
- 路由配置 (/projects/{id}/sprints)
Day 23 13:00-17:00: Sprint 详情页 (Part 1)
- SprintDetail 组件
- Sprint Backlog (任务列表)
- Add/Remove Task to Sprint
Day 24 08:00-12:00: Sprint 详情页 (Part 2)
- Sprint 状态流转 (Start/Complete/Close)
- CreateSprintDialog 组件
Day 24 13:00-15:00: Burndown Chart 基础版
- recharts 集成
- 显示每日剩余任务数

交付物:

✅ Sprint 列表页 + 详情页
✅ Sprint CRUD + 状态流转
✅ Burndown Chart 基础版

Day 25 (2025-11-17) - Dashboard 仪表盘

时间: 6-8 小时

08:00-10:00: 统计卡片
- Total Epics, Stories, Tasks
- Completed Tasks, In Progress Tasks
10:00-12:00: 任务状态分布图
- 饼图或柱状图 (recharts)
- Backlog, Todo, InProgress, Done 数量
13:00-14:00: Sprint 进度条
- 当前 Sprint 名称, 剩余天数
- 完成度百分比
14:00-16:00: 最近活动流
- 最近创建/更新的任务
- 最近分配的任务

交付物:

✅ Dashboard 仪表盘完整功能

Week 3: 高级功能 + 测试 (Day 26-30)

Day 26 (2025-11-18) - 高级搜索与过滤

时间: 4-6 小时

08:00-10:00: 快速过滤器
- My Tasks, Unassigned, Overdue, High Priority
10:00-12:00: 高级搜索表单
- 字段: Title, Assignee, Status, Priority, Type, Date Range
13:00-14:00: 搜索结果页
- 表格或卡片视图
- 分页 + 排序
14:00-15:00: URL Query Params (保存过滤条件)

交付物:

✅ 高级搜索与过滤功能

Day 27 (2025-11-19) - UI/UX 优化 + 性能优化

时间: 6-10 小时

08:00-10:00: 响应式设计优化
- Mobile 适配 (< 768px)
- Tablet 适配 (768px - 1024px)
10:00-11:00: Loading 状态优化
- Skeleton Screens
- Loading Spinners
11:00-12:00: Error Handling 优化
- Error Messages 优化
- Retry 机制
13:00-15:00: 性能优化
- React.memo 应用
- useMemo, useCallback
- Code Splitting (Lazy loading)
15:00-16:00: 动画与过渡效果
- 页面切换动画
- 拖拽动画优化

交付物:

✅ UI/UX 优化完成
✅ 性能优化完成

Day 28-29 (2025-11-20至21) - E2E 测试

时间: 8-10 小时 (2天)

Day 28 08:00-10:00: Cypress/Playwright 配置
- 安装依赖
- 配置文件
- 基础测试用例模板
Day 28 10:00-12:00: 核心流程测试 (Part 1)
- 测试场景 1: 用户登录
- 测试场景 2: 创建项目
- 测试场景 3: 创建 Epic → Story → Task
Day 28 13:00-17:00: 核心流程测试 (Part 2)
- 测试场景 4: Kanban Board 拖拽
- 测试场景 5: Sprint 创建 + 启动
Day 29 08:00-12:00: 核心流程测试 (Part 3)
- 测试场景 6: 用户邀请
- 测试场景 7: Dashboard 显示
- 测试场景 8: 实时更新 (多用户)
Day 29 13:00-15:00: Bug 修复 (测试发现的问题)
Day 29 15:00-16:00: CI/CD 集成 (可选)

交付物:

✅ E2E 测试覆盖核心流程 (8+ scenarios)
✅ 测试通过率 ≥ 90%

Day 30 (2025-11-22) - 文档编写

时间: 2-3 小时

08:00-09:00: 前端开发指南
- 项目结构说明
- 技术栈说明
- 开发流程
09:00-10:00: 组件文档 (可选)
- Storybook 配置 (如果时间允许)
- 组件使用说明
10:00-11:00: 部署指南
- 环境变量配置
- 构建命令
- 部署步骤

交付物:

✅ 前端开发文档完整

Week 4: 缓冲 + 集成 (Day 31-35)

Day 31-35 (2025-11-23至27) - Bug 修复 + 集成测试 + M1 验收

时间: 40 小时 (5天)

Bug 修复 (测试阶段发现的问题)
返工 (架构调整或需求变更)
前后端集成测试 (端到端集成验证)
性能优化 (压测发现的问题)
M1 验收准备 (演示环境搭建, 演示数据准备)
M1 验收评审 (Product Manager 验收)

交付物:

✅ M1 前端功能 100% 完成
✅ 所有 P0 功能验收通过
✅ Bug 修复完成
✅ M1 Release Notes (前端部分)

5.3 并行开发建议

为了加快开发速度,建议前后端并行开发:

Week 1 (Day 16-20):

后端: ProjectManagement 安全加固 + 前端集成准备 (Day 15-20)
前端: API Clients + Epic/Story/Task UI + Kanban 更新 (Day 16-20)
并行: 后端完成 API 后,前端立即集成

Week 2 (Day 21-25):

后端: Audit Log MVP Phase 1-2 (Day 23-30, 不阻塞前端)
前端: Project/User/Sprint UI + Dashboard (Day 21-25)
并行: Sprint UI 可以先基于 Mock 数据开发,后端 Sprint API 完成后再集成

Week 3-4 (Day 26-35):

后端: Sprint Management + Audit Log 完成 (Day 31-34)
前端: 高级功能 + 测试 + Bug 修复 (Day 26-35)
并行: 前端测试期间,后端继续完成剩余功能

六、风险识别与应对措施

6.1 技术风险

风险 1: 后端 API 延期导致前端阻塞 (HIGH)

风险描述:

前端开发严重依赖后端 API 完成
如果后端 ProjectManagement API 延期 (Day 15-17),前端 Phase 1 无法启动
如果后端 Sprint API 延期 (Day 31-34),前端 Sprint UI 无法完成

影响:

M1 前端完成时间延后
M1 整体时间线延期

缓解措施:

Mock 数据开发: 前端先基于 Mock 数据开发 UI,后端 API 完成后再集成
- 使用 MSW (Mock Service Worker) 或 json-server
- 优势: 前后端完全解耦,前端不受后端影响
API Contract First: 后端先定义 API 接口文档 (OpenAPI),前端基于接口文档开发
并行开发: Sprint UI 可以先开发,后端 Sprint API 延后也不影响前端进度
每日 Standup: 前后端每日同步进度,及时发现阻塞

责任人: Frontend Lead + Backend Lead

风险 2: SignalR 实时更新集成复杂度 (MEDIUM)

风险描述:

SignalR 实时更新涉及多个事件监听和 React Query Invalidation
可能存在事件丢失、重复触发、性能问题等

影响:

多用户协作体验不佳
可能需要额外调试时间

缓解措施:

分阶段集成: 先实现基础实时更新 (TaskStatusChanged),再逐步增加其他事件
降级方案: 如果实时更新有问题,可以降级为定时轮询 (polling)
充分测试: 多用户测试 (2-4 users),验证实时更新正确性
性能监控: 监控 SignalR 连接数和消息延迟

责任人: Frontend Developer

风险 3: React Query 缓存策略不当 (MEDIUM)

风险描述:

React Query 缓存配置不当可能导致数据不一致 (stale data)
Invalidation 策略不合理可能导致过多 API 调用

影响:

用户看到过期数据
API 调用频繁,性能下降

缓解措施:

合理的 staleTime: 设置合理的缓存时间 (5-10分钟)
精确的 Invalidation: 只 invalidate 受影响的 queryKey,避免全局 invalidate
Optimistic Updates: 使用乐观更新,提升用户体验
充分测试: 测试数据一致性场景

责任人: Frontend Developer

6.2 进度风险

风险 4: 工时估算不准确,实际开发时间超出预期 (HIGH)

风险描述:

当前工时估算为 18-22 天,但实际开发可能遇到意外问题
可能的延期因素: Bug 修复、架构调整、需求变更、测试不通过

影响:

M1 前端完成时间延后至 12月初 (比目标晚 1-2 周)
M1 整体时间线延期

缓解措施:

预留缓冲时间: Week 4 (Day 31-35) 预留 5天缓冲时间
每日进度跟踪: 每日 Standup,及时发现进度偏差
优先级调整: 如果进度滞后,P1/P2 功能延后到 M1.5 或 M2
加班或增加人手: 关键时刻考虑加班或临时增加前端开发人员

责任人: Product Manager + Frontend Lead

风险 5: 前端开发人员不足 (MEDIUM)

风险描述:

当前假设 1名前端开发人员,工作量 18-22 天
如果前端人员请假、生病或其他项目占用时间,进度受影响

影响:

M1 前端完成时间延后

缓解措施:

增加前端人手: 考虑增加 1名前端开发人员,减少到 10-12 天完成
任务并行: 2名前端开发人员并行开发不同 Phase
外包或兼职: 考虑外包部分 P1/P2 功能 (如 Dashboard, 高级搜索)

责任人: Product Manager

6.3 质量风险

风险 6: 测试覆盖不足,上线后 Bug 较多 (MEDIUM)

风险描述:

E2E 测试覆盖有限 (8+ scenarios),可能遗漏边界情况
单元测试可选,代码质量保证不足

影响:

上线后用户发现 Bug,影响用户体验
需要紧急修复,影响 M2 开发

缓解措施:

增加测试场景: E2E 测试覆盖更多边界情况 (10-15 scenarios)
手动测试: QA 进行全面手动测试
内部试用: 团队内部先使用 1-2 周,发现问题
快速迭代: M1 上线后快速修复 Bug,发布 M1.1, M1.2 补丁版本

责任人: QA Lead + Frontend Developer

风险 7: 响应式设计不佳,Mobile 体验差 (LOW)

风险描述:

M1 阶段主要关注桌面端,Mobile 适配可能不完善

影响:

Mobile 用户体验差
需要额外优化时间

缓解措施:

优先桌面端: M1 先完成桌面端,Mobile 优化延后到 M1.5 或 M2
响应式框架: 使用 Ant Design 响应式组件,减少适配工作
基础适配: M1 至少保证 Mobile 可用 (不要求完美)

责任人: Frontend Developer

6.4 需求风险

风险 8: 需求变更或范围蔓延 (MEDIUM)

风险描述:

开发过程中可能出现新需求或需求变更
Scope 蔓延可能导致工作量增加

影响:

M1 完成时间延后
团队士气下降

缓解措施:

严格控制 Scope: M1 只做 P0 功能,P1/P2 延后到 M2
变更评审: 任何需求变更需要 Product Manager 评审,评估工作量和优先级
积压管理: 新需求加入 Backlog,不影响 M1 时间线
MVP 思维: M1 是 MVP,功能可以简化,后续迭代优化

责任人: Product Manager

七、验收标准

7.1 功能完整性验收标准

功能模块	验收标准	优先级
Epic/Story/Task 管理	用户可以创建/编辑/删除 Epic/Story/Task,三层层级关系正确显示	P0
Kanban Board	Kanban Board 正常显示 WorkTasks,拖拽更新状态正常,显示层级和工时信息	P0
Project Management	用户可以创建/编辑/删除项目,项目列表和详情页正常显示	P0
User Management	用户可以邀请/移除成员,权限控制正确	P0
Sprint Management	用户可以创建/启动/完成 Sprint,Sprint Backlog 正常显示,Burndown Chart 基础版显示	P0
SignalR 实时更新	多用户协作时实时更新正常,Toast 通知显示	P0
Dashboard	Dashboard 正确显示统计数据和图表	P1
高级搜索	快速过滤器和高级搜索正常工作	P1
响应式设计	桌面端 (1920x1080, 1366x768) 显示正常,Mobile 基础可用	P1

7.2 质量验收标准

质量指标	目标值	验收方法
E2E 测试覆盖	≥ 8 scenarios	Cypress/Playwright 测试报告
E2E 测试通过率	≥ 90%	测试报告
页面加载时间	< 2s (初次加载), < 500ms (后续导航)	Chrome DevTools Performance
API 调用成功率	≥ 99%	手动测试 + 日志监控
UI 响应时间	< 100ms (用户操作反馈)	手动测试
浏览器兼容性	Chrome 90+, Firefox 88+, Safari 14+, Edge 90+	手动测试
代码规范检查	0 ESLint errors	ESLint 报告
TypeScript 类型检查	0 type errors	tsc --noEmit 报告
Build 成功	无 build errors	npm run build 成功

7.3 用户体验验收标准

UX 指标	验收标准	验收方法
易用性	新用户 5分钟内可以创建项目并添加任务	用户测试
一致性	UI 风格统一,遵循 Ant Design 设计规范	设计审查
可访问性	基础可访问性 (Keyboard Navigation, Focus Management)	手动测试
错误提示	所有错误都有清晰的提示信息	手动测试
Loading 状态	所有异步操作都有 Loading 指示器	手动测试
实时反馈	用户操作后立即有视觉反馈 (Toast, Loading, etc.)	手动测试

八、成功标准与关键指标

8.1 M1 前端完成标准

M1 前端 100% 完成 需要满足以下条件:

✅ 所有 P0 功能开发完成 (Epic/Story/Task, Kanban, Project, User, Sprint, SignalR)
✅ E2E 测试覆盖核心流程 (8+ scenarios),通过率 ≥ 90%
✅ 前后端集成测试通过 (所有 API 调用成功)
✅ 质量指标达标 (页面加载 < 2s, UI 响应 < 100ms, 0 ESLint errors)
✅ 验收测试通过 (Product Manager 验收)
✅ 文档完整 (前端开发指南, 组件文档, 部署指南)
✅ 演示环境部署成功,可以对外演示

8.2 关键指标 (KPIs)

指标项	目标值	当前值	状态
M1 前端完成度	100%	15-20%	🔄 进行中
前端代码规模	5,000+ 行	1,134 行	🔄 进行中
前端文件数	80+ 文件	15 文件	🔄 进行中
React 组件数	50+ 组件	~10 组件	🔄 进行中
API Clients	7 clients	1 client (Issue API)	🔄 进行中
页面数	15+ 页面	~5 页面	🔄 进行中
E2E 测试覆盖	≥ 8 scenarios	0	⏳ 待开始
E2E 测试通过率	≥ 90%	N/A	⏳ 待开始
页面加载时间	< 2s	N/A	⏳ 待测试
UI 响应时间	< 100ms	N/A	⏳ 待测试
浏览器兼容性	4+ 浏览器	Chrome (推测)	⏳ 待测试

九、资源需求

9.1 人力资源需求

角色	工作量	人数	备注
Frontend Developer (核心)	18-22 天	1 人	全职开发
Frontend Developer (支持,可选)	10-12 天	1 人	并行开发,加速交付
UI/UX Designer (支持)	2-3 天	0.2 人	设计审查,UI 优化建议
QA Engineer	3-5 天	0.5 人	E2E 测试,手动测试
Backend Developer (协作)	N/A	N/A	提供 API,协助前后端联调

推荐配置:

选项 1 (单人): 1 名前端开发人员,22 天完成 (风险较高)
选项 2 (双人,推荐): 2 名前端开发人员并行开发,12 天完成 (更快,风险更低)

9.2 技术资源需求

资源	需求	备注
开发环境	Node.js 18+, npm/yarn, VS Code	标准前端开发环境
测试环境	后端 API 可访问,SignalR 可连接	依赖后端环境
CI/CD 环境	GitHub Actions / GitLab CI	自动化测试和部署
演示环境	Vercel / Netlify / Nginx	部署前端应用
设计资源	Figma / Sketch (可选)	UI 设计稿 (如果有)

十、总结与建议

10.1 总结

ColaFlow 前端开发目前处于早期阶段,仅完成了 Kanban Board 看板功能 (15个文件,1134行代码)。基于 Day 14-15 后端架构决策 (采用 ProjectManagement Module),前端需要重新开发 Epic/Story/Task 三层层级管理界面,并与后端 ProjectManagement API 集成。

M1 前端待开发功能:

Epic/Story/Task 三层层级管理 UI (P0)
Kanban Board 更新 - 支持 ProjectManagement (P0)
Project Management UI (P0)
User Management UI (P0)
Sprint Management UI (P0)
SignalR 实时更新集成 (P0)
Dashboard 仪表盘 (P1)
高级搜索与过滤 (P1)

预计剩余工作量: 18-22 天 (单人开发) 或 10-12 天 (双人并行开发)

目标完成日期: 2025-11-27 (与后端 M1 完成日期对齐)

10.2 关键建议

建议 1: 增加前端开发人员,加速交付 (HIGH PRIORITY)

理由:

当前工作量 18-22 天,单人开发风险较高
增加 1 名前端开发人员,可以减少到 10-12 天,降低延期风险

建议:

方案 1: 招聘 1 名全职前端开发人员
方案 2: 临时外包或兼职 1 名前端开发人员
方案 3: 从其他项目借调 1 名前端开发人员 (临时支援)

建议 2: 前端先基于 Mock 数据开发,降低对后端的依赖 (MEDIUM PRIORITY)

理由:

后端 API 开发进度不确定,可能延期
前端基于 Mock 数据开发,可以完全解耦,不受后端影响

建议:

使用 MSW (Mock Service Worker) 或 json-server
后端先定义 API 接口文档 (OpenAPI),前端基于接口开发
后端 API 完成后再切换到真实 API

建议 3: 优先完成 P0 功能,P1/P2 延后到 M1.5 或 M2 (HIGH PRIORITY)

理由:

M1 时间线紧张,需要严格控制 Scope
Dashboard 和高级搜索是 P1 功能,可以延后

建议:

M1 只做 P0 功能 (Epic/Story/Task, Kanban, Project, User, Sprint, SignalR)
Dashboard 和高级搜索延后到 M1.5 (12月初发布)
任务详情页、Gantt Chart、通知系统延后到 M2

建议 4: 增加 E2E 测试覆盖,提高质量保证 (MEDIUM PRIORITY)

理由:

前端功能复杂,手动测试覆盖不全
E2E 测试可以提高质量,减少上线后 Bug

建议:

E2E 测试覆盖核心流程 (10-15 scenarios)
集成到 CI/CD,每次提交自动运行测试
QA 进行全面手动测试,补充 E2E 测试未覆盖的边界情况

建议 5: 每日 Standup + 每周 Review,确保进度可控 (HIGH PRIORITY)

理由:

前端开发周期 4 周,需要严格的进度管理
每日 Standup 可以及时发现阻塞和风险

建议:

每日 Standup (15分钟): 昨天完成、今天计划、遇到的问题
每周 Review (1小时): Demo 本周完成的功能,Product Manager 验收
使用看板 (Kanban Board) 跟踪任务进度

建议 6: 预留缓冲时间,应对意外情况 (HIGH PRIORITY)

理由:

工时估算可能不准确,实际开发可能遇到意外问题
缓冲时间可以吸收风险,避免 M1 延期

建议:

Week 4 (Day 31-35) 预留 5 天缓冲时间
如果进度超前,可以提前完成 P1 功能或进行优化
如果进度滞后,缓冲时间用于 Bug 修复和返工

十一、附录

11.1 参考文档

c:\Users\yaoji\git\ColaCoder\product-master\product.md - 项目计划书
c:\Users\yaoji\git\ColaCoder\product-master\M1_REMAINING_TASKS.md - M1 剩余任务清单
c:\Users\yaoji\git\ColaCoder\product-master\BACKEND_PROGRESS_REPORT.md - 后端进度报告

11.2 联系人

Product Manager: Product Manager Agent
Tech Lead: Architect Agent
Backend Lead: Backend Agent
Frontend Lead: Frontend Agent (待指定)
QA Lead: QA Agent
Main Coordinator: Main Coordinator Agent

报告生成时间: 2025-11-05 (Day 15) 下次更新: 2025-11-12 (Day 22, Week 1 完成)

END OF DOCUMENT

64 KiB Raw Blame History

ColaFlow 前端开发评估与规划报告

执行摘要

关键发现

重大架构决策影响

M1 前端完成度评估

一、当前前端状态评估

1.1 已完成功能清单

Kanban Board 看板 (Day 13) - 需要更新

认证系统 (Day 11) - 生产就绪

1.2 代码结构分析 (推测)

1.3 技术债务识别

1.3.1 架构迁移债务 (CRITICAL)

1.3.2 缺失功能债务 (HIGH)

1.3.3 实时协作集成债务 (MEDIUM)

1.3.4 代码质量债务 (LOW)

二、M1 阶段前端待开发功能清单

2.1 功能优先级分级 (P0/P1/P2)

P0 (Must Have) - M1 必须完成

2.1.1 Epic/Story/Task 三层层级管理 UI (CRITICAL)

2.1.2 Kanban Board 更新 - 支持 ProjectManagement (CRITICAL)

2.1.3 Project Management UI (项目管理界面)

2.1.4 Sprint Management UI (迭代管理界面)

2.1.5 User Management UI (用户管理界面)

2.1.6 SignalR 实时更新集成 (CRITICAL)

P1 (Should Have) - M1 重要但非阻塞

2.1.7 Dashboard 仪表盘 (项目概览)

2.1.8 高级搜索与过滤

P2 (Nice to Have) - M1 可延后到 M1.5 或 M2

2.1.9 任务详情页 (全屏模式)

2.1.10 Gantt Chart 甘特图

2.1.11 通知系统

三、前端开发任务分解与工时估算

3.1 任务分解树 (Task Breakdown Structure)

3.2 工时估算汇总表

3.3 依赖关系图

四、前端技术规范与最佳实践

4.1 项目结构规范

4.2 技术栈规范

4.2.1 核心技术栈

4.2.2 开发工具

4.3 代码规范

4.3.1 组件设计规范

4.3.2 状态管理规范

4.3.3 API 调用规范

4.3.4 路由管理规范

4.3.5 表单处理规范

4.3.6 错误处理规范

4.3.7 SignalR 集成规范

4.3.8 性能优化规范

4.4 国际化 (i18n) 建议

五、前端开发时间计划 (4周内完成 M1 前端)

5.1 总体时间线

5.2 详细每日任务分解

Week 1: ProjectManagement 前端集成 (Day 16-20)

Week 2: 项目/用户/Sprint 管理 (Day 21-25)

Week 3: 高级功能 + 测试 (Day 26-30)

Week 4: 缓冲 + 集成 (Day 31-35)

5.3 并行开发建议

六、风险识别与应对措施

6.1 技术风险

风险 1: 后端 API 延期导致前端阻塞 (HIGH)

风险 2: SignalR 实时更新集成复杂度 (MEDIUM)

风险 3: React Query 缓存策略不当 (MEDIUM)

6.2 进度风险

风险 4: 工时估算不准确,实际开发时间超出预期 (HIGH)

风险 5: 前端开发人员不足 (MEDIUM)

6.3 质量风险

风险 6: 测试覆盖不足,上线后 Bug 较多 (MEDIUM)

风险 7: 响应式设计不佳,Mobile 体验差 (LOW)

6.4 需求风险

风险 8: 需求变更或范围蔓延 (MEDIUM)

七、验收标准

7.1 功能完整性验收标准

7.2 质量验收标准

7.3 用户体验验收标准

八、成功标准与关键指标

8.1 M1 前端完成标准

8.2 关键指标 (KPIs)

九、资源需求

64 KiB

Raw Blame History