kai/ColaFlow
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Sync
Some checks failed
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

Browse Source
This commit is contained in:
Yaojia Wang
2025-11-08 18:13:48 +01:00
parent 48a8431e4f
commit b11c6447b5
48 changed files with 15754 additions and 10133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2395
docs/M2-MCP-SERVER-ARCHITECTURE.md
View File

File diff suppressed because it is too large Load Diff

498
docs/architecture/ARCHITECTURE-DECISION-PROJECTMANAGEMENT.md
View File

@@ -1,498 +0,0 @@
# Architecture Decision Record: ProjectManagement Module Adoption
**Decision ID**: ADR-036
**Date**: 2025-11-04 (Day 14 Evening / Day 15 Morning)
**Status**: ACCEPTED
**Decision Makers**: Backend Team + Product Manager + Main Coordinator
**Impact**: HIGH - Core architecture change for M1 milestone
---
## Context
During Day 13-14 of ColaFlow development, we discovered that the project contains **two different task management implementations**:
1. **Issue Management Module** - Implemented on Day 13, fully tested, integrated with frontend Kanban board
2. **ProjectManagement Module** - Pre-existing implementation, more complete but未测试, not integrated with frontend
This duplication creates confusion about which module should be used as the primary architecture for task management in ColaFlow.
### Background
**Issue Management Module (Day 13)**:
- Complete CRUD implementation (59 files, 1,630 lines of code)
- Clean Architecture + CQRS + DDD
- 100% multi-tenant security (8/8 integration tests passing, Day 14 security fix)
- Frontend integration complete (Kanban board with drag-drop)
- SignalR real-time notifications (5 domain events)
- Flat issue tracking structure (Project → Issue)
**ProjectManagement Module (Pre-existing)**:
- More extensive implementation (111 files, 2x code volume)
- Complete three-tier hierarchy (Project → Epic → Story → Task)
- Better DDD design (strong聚合根设计)
- 工时跟踪 (EstimatedHours, ActualHours)
- Better test coverage (10 test files vs 4)
- **BUT**: Multi-tenant security incomplete (only Project has TenantId)
- **BUT**: Not integrated with frontend (APIs unused)
### Problem Statement
**Key Questions**:
1. Should we use Issue Management (simpler, tested, integrated) or ProjectManagement (richer, hierarchical)?
2. How do we handle the existing implementation duplication?
3. What is the migration path?
4. What is the risk and effort?
---
## Decision
**We have decided to adopt ProjectManagement Module** as the primary task management architecture for ColaFlow.
**Rationale**:
### 1. Strategic Alignment
**Product Vision**: ColaFlow aims to be a "Jira-like" agile project management system
- ProjectManagement's Epic → Story → Task hierarchy aligns with Jira's structure
- Issue Management's flat structure is more Kanban-like, not Scrum-compatible
- Our product.md explicitly states: "Epic / Story / Task / Sprint / Workflow"
**M1 Goals (from product.md)**:
> "M1 (1–2月): 核心项目模块 - Epic/Story 结构、看板、审计日志"
ProjectManagement Module is the **natural fit** for M1's stated goals.
### 2. Technical Superiority
**Feature Completeness (85% vs 70%)**:
| Feature | ProjectManagement | Issue Management |
|---------|-------------------|------------------|
| Epic Management | ✅ Complete | ❌ Missing |
| Story Management | ✅ Complete | ✅ (as Issue) |
| Task Management | ✅ Complete | ✅ (as Issue) |
| Parent-Child Hierarchy | ✅ Native | ❌ Flat |
| Time Tracking | ✅ EstimatedHours/ActualHours | ❌ Missing |
| Test Coverage | ✅ 10 test files | ⚠️ 4 test files |
| Code Maturity | ✅ 111 files | ⚠️ 51 files |
**Architecture Quality**:
- Both use Clean Architecture + CQRS + DDD ✅
- ProjectManagement has superior聚合根设计 (Project as aggregate root for Epic/Story/Task)
- ProjectManagement has richer domain events
- ProjectManagement has better value object modeling (ProjectKey, strong IDs)
### 3. Long-Term Scalability
**Epic → Story → Task hierarchy**:
- Supports complex projects with multiple epics
- Aligns with SAFe/Scrum frameworks
- Enables story points and burndown charts
- Supports sprint planning with story-level estimation
- Allows epic-level roadmap views
**Flat Issue structure limitations**:
- Cannot represent epic-story relationships
- Difficult to organize large projects
- Limited sprint planning capabilities
- No natural hierarchy for reporting
### 4. Evaluation Report Validation
On Day 14, the Backend Team conducted a **comprehensive evaluation** of ProjectManagement Module:
- Document: `docs/evaluations/ProjectManagement-Module-Evaluation-2025-11-04.md`
- Conclusion: 85/100 completeness score
- Recommendation: "Should use ProjectManagement Module, but must complete multi-tenant security first"
### 5. Risk Mitigation
**Critical Gaps Identified**:
1. ❌ Epic/Story/WorkTask lack TenantId (security risk)
2. ❌ No Global Query Filters on Epic/Story/WorkTask
3. ❌ Frontend not integrated (APIs unused)
4. ❌ Missing authorization on Epics/Stories/Tasks Controllers
**But**: These gaps are **fixable** (2-3 days effort), and the fix follows the **exact same pattern** as Day 14's Issue Management security fix.
---
## Consequences
### Positive Consequences
1. **Alignment with Product Vision**
- ✅ Jira-like experience for users
- ✅ Full agile workflow support (Epic → Story → Task)
- ✅ Better positioning for M2-M6 features (MCP, AI integration)
2. **Superior Feature Set**
- ✅ Time tracking (EstimatedHours/ActualHours)
- ✅ Natural hierarchy for complex projects
- ✅ Richer reporting capabilities (burndown, velocity)
- ✅ Scalable to enterprise projects (100+ epics, 1000+ stories)
3. **Code Quality**
- ✅ More mature implementation (111 vs 51 files)
- ✅ Better test coverage (10 vs 4 test files)
- ✅ Superior DDD design
4. **Future-Proof**
- ✅ Supports planned M1 features (Sprint Management)
- ✅ Supports planned M2 features (AI-generated epics)
- ✅ Supports planned M3 features (PRD → Epic decomposition)
### Negative Consequences (Mitigated)
1. **Multi-Tenant Security Gap** (CRITICAL)
- Risk: Epic/Story/Task accessible across tenants
- Mitigation: Apply Day 14 security fix pattern (2-3 days effort)
- Plan: Phase 1 of implementation roadmap
2. **Frontend Integration Gap** (HIGH)
- Risk: Frontend currently uses Issue Management APIs
- Mitigation: Create API clients, replace API calls (2-3 days effort)
- Plan: Phase 2 of implementation roadmap
3. **Data Migration** (MEDIUM)
- Risk: Existing Issue data may need migration
- Mitigation: If demo environment, no migration needed; if production data exists, write migration script
- Plan: Assess data state before migration
4. **Learning Curve** (LOW)
- Risk: Users need to understand Epic/Story/Task concepts
- Mitigation: In-app guidance, documentation, tooltips
- Plan: UX documentation in parallel with implementation
### Risks
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| Multi-tenant security not fixed properly | Critical | Low | Follow Day 14 fix pattern + 100% test coverage |
| Frontend integration takes longer than 2-3 days | Medium | Medium | Reuse existing Issue Management UI logic |
| Data migration issues | Medium | Low | Test migration script in dev environment first |
| User confusion about Epic vs Story vs Task | Low | Medium | In-app guidance + documentation |
| Performance degradation due to complex queries | Medium | Low | Use EF Core navigation property optimization + caching |
---
## Implementation Plan
### Phase 1: Multi-Tenant Security Hardening (2-3 days, Day 15-17)
**Goal**: Apply Day 14 security fix pattern to ProjectManagement Module
**Tasks**:
1. **Day 15 Morning**: Database migration design
- Add TenantId to Epic, Story, WorkTask entities
- Create migration: `AddTenantIdToEpicStoryTask`
- Add indexes: `IX_Epics_TenantId`, `IX_Stories_TenantId`, `IX_WorkTasks_TenantId`
2. **Day 15 Afternoon**: TenantContext service implementation
- Reuse TenantContextAccessor from Issue Management
- Register service in Program.cs
- Update PMDbContext constructor to inject ITenantContextAccessor
3. **Day 16 All Day**: Repository and Global Query Filter updates
- Add Global Query Filters in PMDbContext.OnModelCreating:
```csharp
modelBuilder.Entity<Epic>()
.HasQueryFilter(e => e.TenantId == _tenantContextAccessor.GetCurrentTenantId());
modelBuilder.Entity<Story>()
.HasQueryFilter(s => s.TenantId == _tenantContextAccessor.GetCurrentTenantId());
modelBuilder.Entity<WorkTask>()
.HasQueryFilter(t => t.TenantId == _tenantContextAccessor.GetCurrentTenantId());
```
- Update ProjectRepository to verify tenant ownership
- Update聚合工厂方法 to propagate TenantId from Project → Epic → Story → Task
4. **Day 17 All Day**: Multi-tenant security testing
- Write 8+ integration tests (mirroring Issue Management tests):
* CrossTenantEpicAccess_ShouldReturn404
* CrossTenantStoryAccess_ShouldReturn404
* CrossTenantTaskAccess_ShouldReturn404
* TenantAUser_CannotModify_TenantBData
* EpicCreate_AutoSetsTenantId
* StoryCreate_InheritsTenantIdFromEpic
* TaskCreate_InheritsTenantIdFromStory
* MultiTenantIsolation_100%_Verified
- Run all tests, ensure 100% pass rate
- Verify EF Core Query Filters working correctly
**Deliverables**:
- ✅ Epic, Story, WorkTask entities have TenantId
- ✅ Global Query Filters applied
- ✅ TenantContext service integrated
- ✅ 8+ integration tests passing (100%)
- ✅ CRITICAL security gap closed
**Acceptance Criteria**:
- All multi-tenant isolation tests passing
- No cross-tenant data leakage possible
- Security audit confirms defense-in-depth layers working
---
### Phase 2: Frontend Integration (2-3 days, Day 18-20)
**Goal**: Replace Issue Management APIs with ProjectManagement APIs in frontend
**Tasks**:
1. **Day 18**: API Client creation
- Create `lib/api/epics.ts` (7 methods: list, get, create, update, delete, etc.)
- Create `lib/api/stories.ts` (9 methods: list by epic, list by project, create, update, delete, assign, etc.)
- Create `lib/api/tasks.ts` (11 methods: list by story, list by project, create, update, delete, assign, update status, etc.)
- Define TypeScript types: EpicDto, StoryDto, TaskDto, WorkItemStatus, TaskPriority
2. **Day 19**: UI components development
- Epic list page (`/projects/[id]/epics`)
- Epic detail page (`/epics/[id]`)
- Story Kanban board (reuse existing Kanban component logic)
- Task card component (similar to IssueCard)
- Create/Edit Epic dialog
- Create/Edit Story dialog
- Create/Edit Task dialog
3. **Day 20**: Integration and testing
- Replace `/api/issues` calls with `/api/v1/epics|stories|tasks`
- Update Zustand store to handle Epic/Story/Task state
- Update React Query hooks
- End-to-end testing (create epic → create story → create task → drag task in kanban)
- Bug fixes and UI polish
**Deliverables**:
- ✅ API clients for Epics, Stories, Tasks
- ✅ UI pages for Epic/Story/Task management
- ✅ Kanban board working with ProjectManagement APIs
- ✅ Frontend fully migrated from Issue Management
**Acceptance Criteria**:
- User can create Epic → Story → Task hierarchy
- Kanban board displays tasks grouped by status
- Drag-drop updates task status via API
- Real-time updates working (SignalR integration)
---
### Phase 3: Supplementary Features (1-2 days, Day 21-22)
**Goal**: Add missing features to match Issue Management parity
**Tasks**:
1. **Day 21**: Authorization and SignalR
- Add `[Authorize]` to Epics/Stories/Tasks Controllers
- Add SignalR event publishing:
* EpicCreatedEvent → ProjectHub
* StoryCreatedEvent → ProjectHub
* TaskStatusChangedEvent → ProjectHub (for real-time Kanban updates)
- Test real-time Kanban updates with 2+ users
2. **Day 22**: Documentation and acceptance testing
- Update API documentation (Swagger annotations)
- Write user guide (How to use Epic/Story/Task)
- Final acceptance testing (full workflow end-to-end)
- Performance testing (100+ tasks on Kanban board)
**Deliverables**:
- ✅ Authorization protection on all endpoints
- ✅ Real-time notifications working
- ✅ API documentation updated
- ✅ User guide complete
**Acceptance Criteria**:
- Authorization prevents unauthorized access
- Real-time updates < 1s latency
- API documentation complete and accurate
- All acceptance tests passing
---
## Alternative Considered
### Alternative 1: Keep Issue Management as Primary
**Pros**:
- Already tested (100% integration tests passing)
- Frontend integration complete
- Multi-tenant security verified (Day 14 fix)
- No migration needed
**Cons**:
- Flat structure does not align with product vision ("Epic/Story" in product.md)
- Missing Epic/Story hierarchy (would need to be rebuilt)
- Missing time tracking (would need to be added)
- Smaller codebase (less mature, 51 files vs 111 files)
- Rebuilding Epic/Story in Issue Management would take 2-3 weeks (more effort than fixing ProjectManagement)
**Why Rejected**: Rebuilding Epic/Story hierarchy in Issue Management would duplicate effort already present in ProjectManagement Module. It's more efficient to fix ProjectManagement's security gaps (2-3 days) than rebuild ProjectManagement's features in Issue Management (2-3 weeks).
---
### Alternative 2: Coexistence of Both Modules
**Pros**:
- Issue Management for simple Kanban workflows
- ProjectManagement for complex Scrum projects
- Users choose which module to use per project
**Cons**:
- Doubles maintenance burden (2x codebase to maintain)
- User confusion (which module to use when?)
- Data inconsistency (Project in both modules)
- Frontend complexity (2 sets of APIs)
- Testing complexity (2x test coverage needed)
- Technical debt accumulation
**Why Rejected**: Coexistence creates long-term technical debt and user confusion. It's better to choose one primary architecture and commit to it.
---
### Alternative 3: Hybrid Approach (Issue Management with Epic/Story extension)
**Pros**:
- Keeps existing Issue Management implementation
- Extends Issue with ParentIssueId to create hierarchy
- Minimal frontend changes
**Cons**:
- Issue becomes overloaded entity (Epic, Story, Task all as "Issue")
- Loses semantic clarity (Epic is not just a "big Issue")
- Difficult to enforce Epic → Story → Task hierarchy rules
- No time tracking at Story level (EstimatedHours)
- Complex UI logic to handle different "Issue types"
**Why Rejected**: This approach is technically feasible but semantically confusing. It sacrifices code clarity for short-term convenience. ProjectManagement's explicit Epic/Story/Task entities are clearer and more maintainable.
---
## Validation
### Validation Method
1. **Day 14 Evening**: Backend Team completed comprehensive evaluation
- Document: `ProjectManagement-Module-Evaluation-2025-11-04.md`
- Scoring: 85/100 completeness
- Conclusion: "Should use ProjectManagement, but fix security first"
2. **Day 15 Morning**: Architecture review meeting
- Participants: Main Coordinator, Backend Team, Product Manager
- Discussed evaluation findings
- Reviewed risks and mitigation strategies
- **Decision**: ADOPT ProjectManagement Module
3. **Day 15 Morning**: Product Manager validation
- Verified alignment with product.md goals
- Confirmed M1 milestone requirements (Epic/Story structure)
- Approved 5-8 day implementation timeline
- **Decision**: ACCEPTED
### Success Metrics
**Short-Term (Week 1-2, Day 15-22)**:
- ✅ Multi-tenant security hardening complete
- ✅ 100% integration test pass rate
- ✅ Frontend integration complete
- ✅ Kanban board working with ProjectManagement APIs
- ✅ Zero CRITICAL security vulnerabilities
**Mid-Term (Month 2-3, M2)**:
- ✅ Sprint Management integrated with Epic/Story/Task
- ✅ MCP Server can read/write Epic/Story hierarchy
- ✅ AI generates Epics and decomposes into Stories
- ✅ Performance targets met (< 200ms API response)
**Long-Term (Month 6-12, M3-M6)**:
- ✅ ChatGPT generates PRD → Epic → Story decomposition
- ✅ Enterprise customers use Epic/Story/Task for complex projects
- ✅ User satisfaction ≥ 85% (product goal)
- ✅ AI automated tasks ≥ 50% (product goal)
---
## Communication Plan
### Internal Communication
**Day 15 Morning (2025-11-04)**:
- ✅ Update progress.md with architecture decision
- ✅ Create this ADR document (ARCHITECTURE-DECISION-PROJECTMANAGEMENT.md)
- ✅ Update M1_REMAINING_TASKS.md with new task breakdown
- ✅ Update BACKEND_PROGRESS_REPORT.md with architecture decision section
**Day 15 Afternoon (2025-11-04)**:
- ✅ Create DAY15-22-PROJECTMANAGEMENT-ROADMAP.md (detailed implementation plan)
- ✅ Update product.md M1 timeline (add 5-8 days for ProjectManagement work)
- ✅ Brief all agents (Backend, Frontend, QA, UX) on new architecture
### External Communication (if applicable)
**Stakeholders**:
- N/A (internal project, no external stakeholders yet)
**Users**:
- N/A (no production users yet, still in M1 development)
**Future Communication**:
- When M1 completes: Release notes mention Epic/Story/Task feature
- User guide: Explain Epic → Story → Task hierarchy
- Migration guide (if needed): How to organize existing issues into epics/stories
---
## References
1. **ProjectManagement Module Evaluation Report**
- File: `docs/evaluations/ProjectManagement-Module-Evaluation-2025-11-04.md`
- Date: 2025-11-04
- Conclusion: 85/100 score, recommended adoption
2. **Product Vision Document**
- File: `product.md`
- Section: "核心模块" - Epic / Story / Task / Sprint
3. **M1 Milestone Definition**
- File: `product.md`, Section: "M1 阶段完成情况"
- Goal: "Epic/Story 结构、看板、审计日志"
4. **Day 14 Security Fix**
- Commit: 810fbeb
- Description: Multi-tenant security fix for Issue Management
- Pattern: Add TenantId + Global Query Filters + TenantContext service
5. **Issue Management Implementation**
- Files: 51 files, 1,630 lines of code
- Tests: 8 integration tests (100% passing)
- Status: Production-ready, but superseded by ProjectManagement
---
## Decision History
| Version | Date | Change | Author |
|---------|------|--------|--------|
| 1.0 | 2025-11-04 | Initial decision: Adopt ProjectManagement Module | Main Coordinator + Backend Team + Product Manager |
---
## Approval
**Decision Approved By**:
- Main Coordinator: ✅ APPROVED (2025-11-04)
- Backend Team Lead: ✅ APPROVED (2025-11-04)
- Product Manager: ✅ APPROVED (2025-11-04)
- Architect: ✅ APPROVED (2025-11-04)
**Status**: ✅ **ACCEPTED AND ACTIVE**
**Next Steps**:
1. Implement Phase 1 (Multi-tenant security hardening) - Day 15-17
2. Implement Phase 2 (Frontend integration) - Day 18-20
3. Implement Phase 3 (Supplementary features) - Day 21-22
4. M1 Milestone completion - Day 23+
---
**Document Maintained By**: Product Manager Agent
**Last Updated**: 2025-11-04
**Next Review**: 2025-11-22 (after Phase 3 completion)

2819
docs/architecture/jwt-authentication-architecture.md
View File

File diff suppressed because it is too large Load Diff

1961
docs/architecture/mcp-authentication-architecture.md
View File

File diff suppressed because it is too large Load Diff

1866
docs/architecture/mcp-server-architecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

487
docs/designs/STORY_DESIGN_SUMMARY.md Normal file
View File

@@ -0,0 +1,487 @@
# Story Management UX/UI Design - Executive Summary
**Date:** 2025-11-05
**Designer:** ColaFlow UX/UI Team
**Status:** Ready for Implementation
---
## Overview
This document provides a concise summary of the Story management feature design. For full specifications, see [STORY_UX_UI_DESIGN.md](./STORY_UX_UI_DESIGN.md).
---
## Key Design Decisions
### 1. Story Detail Page Layout
**Decision:** Two-column layout with main content + metadata sidebar
**Rationale:**
- Consistent with Epic detail page design
- Separates core content from metadata
- Optimizes for 80% use case (reading details)
**Layout:**
```
┌────────────────────────────────────────────────┐
│ [Breadcrumb] [←] Story Title [Edit][Delete] │
├────────────────────────────────────────────────┤
│ ┌─────────────────────┐ ┌──────────────────┐ │
│ │ Story Details │ │ Metadata Sidebar │ │
│ │ - Description │ │ - Status │ │
│ │ - Acceptance Criteria│ │ - Priority │ │
│ │ - Tasks (8) │ │ - Assignee │ │
│ │ - Activity Timeline │ │ - Parent Epic │ │
│ └─────────────────────┘ └──────────────────┘ │
└────────────────────────────────────────────────┘
```
### 2. Story Creation Flow
**Decision:** Hybrid approach (Quick Add + Full Form)
**Quick Add (Inline):**
- For rapid Story creation
- Title + Priority only
- Inline form at top of Stories section
- Keyboard shortcut: `Cmd/Ctrl + N`
**Full Form (Dialog):**
- For detailed Stories
- All fields available (description, assignee, acceptance criteria)
- Accessed via [+ New Story] button
**Rationale:**
- Supports both quick workflows and detailed planning
- Reduces clicks for common case (simple Story)
- Maintains consistency with Epic creation pattern
### 3. Kanban Board Enhancements
**Decision:** Add contextual Story creation from Epic cards
**New Interaction:**
```
Hover over Epic card → [+ Add Story] button appears
Click → Inline Story form opens below Epic card
Create → Story appears in correct Kanban column
```
**Rationale:**
- Reduces navigation (no need to open Epic detail)
- Maintains context (Epic visible while creating)
- Faster workflow for batch Story creation
### 4. Task Management in Story Detail
**Decision:** Expandable Task list with inline creation
**Features:**
- Checkbox for quick status toggle
- Filters: Status, Priority, Assignee
- Sort: Priority, Status, Date, Assignee
- Drag to reorder
- Inline Quick Add Task
**Rationale:**
- Tasks are critical to Story completion
- Users need quick Task updates without navigation
- Aligns with "Flow" principle (minimize steps)
### 5. Activity Timeline
**Decision:** Show full change history with filtering
**Display:**
- Icon-based event types (status, assignment, comment)
- Relative timestamps ("2h ago")
- Filters: All, Changes, Comments, Assignments
- Infinite scroll / Load More
**Rationale:**
- Transparency: Users see all changes
- Collaboration: Track team activity
- Audit trail: Compliance requirement
---
## Component Architecture
### New Components
1. **Story Card Component**
- File: `components/projects/story-card.tsx`
- Variants: list, kanban, compact
- States: default, hover, selected, dragging
2. **Task List Component**
- File: `components/projects/task-list.tsx`
- Features: filter, sort, bulk operations, drag-reorder
3. **Activity Timeline Component**
- File: `components/shared/activity-timeline.tsx`
- Reusable for Epic, Story, Task
4. **Quick Add Story Component**
- File: `components/projects/quick-add-story.tsx`
- Inline form for rapid Story creation
### Enhanced Components
1. **Story Form Component** (existing)
- Add: Assignee selector
- Add: Acceptance criteria field
- Add: Tags/labels
- Add: Quick mode variant
2. **Kanban Board** (existing)
- Add: Story cards (currently shows Epics)
- Add: Quick Add from Epic cards
- Enhance: Drag Story to change status
---
## Design System Tokens
### Status Colors
```css
Backlog: #64748B (Slate) bg: #F1F5F9
Todo: #2196F3 (Blue) bg: #E3F2FD
InProgress: #FF9800 (Orange) bg: #FFF3E0
Done: #4CAF50 (Green) bg: #E8F5E9
```
### Priority Colors
```css
Low: #2196F3 (Blue) bg: #E3F2FD
Medium: #FFC107 (Yellow) bg: #FFF9C4
High: #FF9800 (Orange) bg: #FFE0B2
Critical: #F44336 (Red) bg: #FFEBEE
```
### Typography
```css
Story Title: 32px, Bold, Line-height: 1.2
Story Description: 16px, Regular, Line-height: 1.6
Metadata Label: 14px, Medium
Metadata Value: 14px, Regular
```
### Spacing
```css
Card Padding: 16px
Section Gap: 24px
Form Field Gap: 16px
Task Item Gap: 8px
```
---
## User Flows
### Critical User Journeys
**1. View Story Details:**
```
Epic Detail → Click Story → Story Detail → View Tasks → Check Activity
```
**Time Goal:** < 5 seconds
**2. Create Story (Quick):**
```
Epic Detail → Click [Quick Add] → Type Title → Select Priority → Press Enter
```
**Time Goal:** < 30 seconds
**3. Create Story (Full):**
```
Epic Detail → Click [+ New Story] → Fill Form → Create → Add Tasks
```
**Time Goal:** < 2 minutes
**4. Update Story Status:**
```
Story Detail → Click Status Dropdown → Select New Status → Confirm
```
**Time Goal:** < 10 seconds
**5. Add Tasks to Story:**
```
Story Detail → Click [+ Add Task] → Fill Title → Create → Repeat
```
**Time Goal:** < 20 seconds per task
---
## Keyboard Shortcuts
### Global
- `Cmd/Ctrl + N` - Quick Add Story
- `Cmd/Ctrl + E` - Edit Story
- `ESC` - Cancel / Close dialog
### Story Detail
- `1-4` - Change status (Backlog, Todo, InProgress, Done)
- `P` - Change priority
- `A` - Change assignee
- `T` - Add new Task
- `← / →` - Navigate to prev/next Story
### Story List
- `↑ / ↓` - Navigate Stories
- `Enter` - Open Story
- `Space` - Quick preview
- `Delete` - Delete Story
---
## Accessibility Highlights
### WCAG 2.1 Level AA Compliance
**Color Contrast:**
- All text passes 4.5:1 ratio
- Status badges: 3:1 minimum
**Keyboard Navigation:**
- 100% keyboard accessible
- Clear focus indicators
- Logical tab order
**Screen Reader Support:**
- ARIA labels on all interactive elements
- Status announcements for updates
- Descriptive button labels
**Focus Management:**
- Trap focus in dialogs
- Return focus on close
- Auto-focus on Story title
---
## Mobile Responsive Design
### Breakpoints
- Mobile: < 640px (Single column, tabs)
- Tablet: 640px - 1024px (Two columns)
- Desktop: > 1024px (Optimal layout)
### Mobile Optimizations
- Tabs instead of sidebar (Details | Tasks | Activity)
- Bottom sheets for forms
- Swipe gestures (Edit/Delete)
- Floating action button for Quick Add
- Pull to refresh
---
## Performance Targets
### Page Load
- Story Detail: < 1 second
- Task List: < 500ms
- Activity Timeline: < 500ms
### Interactions
- Status update: < 100ms
- Task checkbox toggle: < 100ms
- Form submission: < 2 seconds
### Real-time Updates
- SignalR message delivery: < 500ms
- UI update latency: < 100ms
---
## Implementation Roadmap
### Phase 1: Core Story Detail (Week 1)
**Goal:** Users can view Story details and Tasks
- [ ] Story detail page layout (2-column)
- [ ] Story metadata sidebar
- [ ] Story header with actions
- [ ] Basic Task list display
- [ ] Activity timeline (read-only)
**Deliverables:**
- Story detail page (`app/(dashboard)/stories/[id]/page.tsx`)
- Story metadata component
- Task list component (basic)
### Phase 2: Story Creation & Editing (Week 2)
**Goal:** Users can create and edit Stories efficiently
- [ ] Enhanced Story Form (assignee, acceptance criteria)
- [ ] Inline Quick Add Story
- [ ] Edit Story in dialog
- [ ] Delete Story with confirmation
- [ ] Form validation and error handling
**Deliverables:**
- Quick Add Story component
- Enhanced Story Form component
- Delete confirmation dialog
### Phase 3: Task Management (Week 3)
**Goal:** Users can manage Tasks within Stories
- [ ] Task list with filters and sorting
- [ ] Inline Task creation
- [ ] Task status update (checkbox)
- [ ] Task reordering (drag & drop)
- [ ] Task quick edit
**Deliverables:**
- Full-featured Task list component
- Task filters and sorting
- Drag-drop functionality
### Phase 4: Kanban Enhancements (Week 4)
**Goal:** Users can create Stories directly from Kanban
- [ ] Story cards in Kanban (replace Epic cards as option)
- [ ] Drag Story to change status
- [ ] Quick Add Story from Epic card
- [ ] Bulk operations (multi-select, batch update)
**Deliverables:**
- Enhanced Kanban Board component
- Story drag-drop
- Bulk operation UI
### Phase 5: Polish & Accessibility (Week 5)
**Goal:** Production-ready with full accessibility
- [ ] Keyboard shortcuts implementation
- [ ] Screen reader support (ARIA labels)
- [ ] Mobile responsive design
- [ ] Loading & error states
- [ ] Animation polish
- [ ] Performance optimization
**Deliverables:**
- Keyboard shortcut handler
- ARIA labels and screen reader support
- Mobile responsive CSS
- Loading skeletons
- Error boundaries
---
## Success Metrics
### Usability
- Task Completion Rate: > 95%
- Time to Create Story: < 30s (Quick Add)
- Navigation Efficiency: < 3 clicks (Epic → Task)
- Error Rate: < 5%
### Performance
- Page Load: < 1s
- Interaction Response: < 100ms
- Real-time Update: < 500ms
### Accessibility
- Keyboard Navigation: 100%
- WCAG 2.1 AA: 100% compliance
- Screen Reader Coverage: All critical paths
---
## Risk & Mitigation
### Risk 1: Complex Task Management
**Issue:** Task list with filters, sorting, drag-drop is complex
**Mitigation:**
- Start with basic Task list (Phase 1)
- Add features incrementally (Phase 3)
- Use proven library (@dnd-kit) for drag-drop
- Extensive testing with real users
### Risk 2: Real-time Update Conflicts
**Issue:** Multiple users editing same Story simultaneously
**Mitigation:**
- Optimistic UI updates with revert on conflict
- SignalR broadcasts changes to all users
- Show "Someone else is editing" indicator
- Auto-refresh on conflict detection
### Risk 3: Mobile UX Complexity
**Issue:** Story detail page has many sections for small screens
**Mitigation:**
- Use tabs on mobile (Details | Tasks | Activity)
- Bottom sheets for forms (not full dialogs)
- Progressive disclosure (collapse sections)
- Swipe gestures for common actions
### Risk 4: Performance with Large Task Lists
**Issue:** Stories with 50+ Tasks may be slow
**Mitigation:**
- Virtual scrolling for Task lists (react-window)
- Pagination or "Load More" for Activity Timeline
- Optimize SignalR payload size
- Backend pagination for Tasks API
---
## Design Review Checklist
Before implementation, verify:
- [ ] Layout matches existing Epic page consistency
- [ ] All interactive elements have hover/focus states
- [ ] Color contrast passes WCAG AA (4.5:1)
- [ ] Keyboard shortcuts don't conflict with browser
- [ ] Mobile design provides equivalent functionality
- [ ] Loading states defined for all async operations
- [ ] Error messages are user-friendly and actionable
- [ ] ARIA labels added to all interactive elements
- [ ] Design tokens match ColaFlow design system
- [ ] User flows tested with real scenarios
---
## Questions for Product Team
1. **Acceptance Criteria:** Should this be a simple checkbox list or rich text?
2. **Story Status Transitions:** Are all transitions allowed (e.g., Done → Backlog)?
3. **Task Limits:** Is there a maximum number of Tasks per Story?
4. **Batch Operations:** Priority for bulk Story creation/update?
5. **Integrations:** Will Stories sync with external tools (GitHub, Jira)?
6. **AI Features:** Should AI suggest Story breakdown or acceptance criteria?
---
## Next Steps
1. **Design Review:** Schedule with Product, Engineering, QA teams
2. **Prototype:** Create Figma interactive prototype (optional)
3. **User Testing:** Test flows with Lisa (PM) and David (Dev) personas
4. **Implementation:** Start Phase 1 (Core Story Detail)
5. **Iteration:** Gather feedback after each phase, adjust design
---
## Contact
**UX/UI Team:** ux-ui@colaflow.com
**Design Files:** [Figma Workspace](https://figma.com/colaflow)
**Questions:** Create issue in `colaflow/design-system` repo
---
**Document Version:** 1.0
**Last Updated:** 2025-11-05
**Next Review:** After Phase 1 implementation

1408
docs/designs/STORY_UX_UI_DESIGN.md Normal file
View File

File diff suppressed because it is too large Load Diff

119
docs/mcp-suggestion.md Normal file
View File

@@ -0,0 +1,119 @@
根据我的分析,您的项目已经有了非常完善的 MCP Server 架构设计文档!我来总结并提供我的专业建议:
## 现状分析
您已经有了一份**非常全面和专业**的 M2 MCP Server 架构设计文档(73KB,2,500+行),包含:
### ✅ 已完成的优秀设计
1. **完整的架构方案**
- 模块化单体架构 + Clean Architecture
- 自定义 .NET 9 MCP 实现
- 与 M1 现有模块的集成方案
2. **安全机制设计**
- API Key 认证 (BCrypt 哈希)
- Diff Preview 机制 (AI 写操作先预览,人工审批)
- 字段级权限控制
- 速率限制
3. **核心组件设计**
- 3个聚合根 (McpAgent, DiffPreview, TaskLock)
- 完整的 Domain 层设计
- Application Services 设计
- Infrastructure 层实现
4. **数据库设计**
- 4张表 + 10个索引
- PostgreSQL JSONB 存储 diff 数据
- 完整的 SQL schema
5. **实施路线图**
- 8周详细计划 (4个 Phase)
- 清晰的验收标准
- 风险评估和缓解措施
## 我的专业建议
虽然您的现有设计已经非常完善,但作为架构师,我建议从以下几个角度进行**细化和扩展**:
### 1. 安全架构深化
**建议增加**:
- **OAuth 2.0 集成**: 除了 API Key,支持 OAuth 2.0 授权流程
- **JWT Token 双重认证**: API Key + JWT Token 双重验证
- **审计日志加密**: 敏感操作审计日志加密存储
- **数据脱敏策略**: 更细粒度的数据脱敏规则
### 2. 性能优化架构
**建议增加**:
- **GraphQL 支持**: 除了 JSON-RPC,支持 GraphQL 查询
- **批量操作优化**: 支持批量 Resource 读取和 Tool 调用
- **流式响应**: 对于大数据集,支持 SSE 流式响应
- **缓存策略**: Redis 缓存热点 Resource 数据
### 3. 可观测性架构
**建议增加**:
- **OpenTelemetry 集成**: 分布式追踪
- **Prometheus 指标**: MCP 操作的关键指标
- **结构化日志**: 使用 Serilog 结构化日志
- **性能分析**: MCP 操作性能分析工具
### 4. 高可用架构
**建议增加**:
- **Redis Sentinel**: Redis 高可用方案
- **数据库读写分离**: PostgreSQL 主从复制
- **熔断降级**: Circuit Breaker 模式
- **健康检查**: MCP Server 健康检查端点
### 5. AI Agent 能力增强
**建议增加**:
- **Agent 协作模式**: 多 Agent 协同工作
- **任务优先级队列**: 基于优先级的任务调度
- **AI 反馈机制**: Agent 操作反馈和学习
- **智能风险评估**: 基于 ML 的风险评估
## 我的建议:补充架构文档
我建议创建以下补充架构文档:
1. **MCP Server 安全架构设计**
- OAuth 2.0 集成方案
- 双重认证流程
- 数据加密和脱敏策略
2. **MCP Server 性能优化方案**
- GraphQL 集成方案
- 批量操作设计
- 缓存策略
3. **MCP Server 可观测性方案**
- OpenTelemetry 集成
- 监控指标设计
- 告警策略
4. **MCP Server 高可用部署架构**
- 容器化部署方案
- Kubernetes 编排
- 灾难恢复方案
## 下一步行动
**选项 1**: 基于您现有的优秀设计,我可以为您创建以上4份**补充架构文档**,深化和扩展现有设计。
**选项 2**: 如果您对现有设计满意,我可以直接协助您开始 **M2 Phase 1 实施**,创建详细的实施计划和代码示例。
**选项 3**: 如果您希望我对现有架构进行**全面审查**,我可以从安全、性能、可扩展性等角度提供详细的审查报告和改进建议。
**您希望我做什么?**
1. 创建补充架构文档(推荐选项 1)
2. 开始 M2 Phase 1 实施计划(选项 2)
3. 全面架构审查和改进建议(选项 3)
4. 其他需求
请告诉我您的选择,我将立即为您开始工作! 🚀

1252
docs/plans/SPRINT_3_IMPLEMENTATION_GUIDE.md Normal file
View File

File diff suppressed because it is too large Load Diff

1835
docs/plans/STORY_FEATURE_IMPLEMENTATION_REPORT.md Normal file
View File

File diff suppressed because it is too large Load Diff

328
docs/plans/sprint_3.md Normal file
View File

@@ -0,0 +1,328 @@
---
sprint_id: sprint_3
milestone: M1
status: completed
created_date: 2025-11-05
start_date: 2025-11-05
target_end_date: 2025-11-19
completion_date: 2025-11-05
---
# Sprint 3: Frontend Code Quality Optimization
**Milestone**: M1 - Core Project Module (Quality Improvement)
**Goal**: Complete frontend code quality optimization based on code review findings to improve type safety, performance, and maintainability.
## Sprint Context
**Background**:
Following the completion of M1 core features (Sprint 1-2), a comprehensive frontend code review was conducted on 2025-11-05. The review identified several code quality issues that need to be addressed before moving to M2 MCP Server implementation.
**Review Report**: `FRONTEND_CODE_REVIEW_REPORT.md`
**Already Fixed (Git commit `ea67d90`)**:
- ✅ Eliminated all `any` types and type assertions
- ✅ Merged duplicate User type definitions
- ✅ Replaced console.log in core modules with logger utility
- ✅ Fixed hardcoded user IDs
- ✅ Added React.memo and useCallback optimizations
- ✅ IssueCard type safety improvements
## Sprint Objectives
1. **Complete Logging Utility Migration** - Replace all remaining console.log statements
2. **Optimize Component Performance** - Add React.memo to all list components
3. **Fix Next.js 15 Compatibility** - Update all pages to use async params pattern
4. **Improve Error Handling** - Add error boundaries and better error messages
5. **Enhance Accessibility** - Improve ARIA labels and keyboard navigation
6. **Enforce Code Quality** - Add ESLint rules and pre-commit hooks
## Implementation Guide
**Complete Implementation Guide**: [SPRINT_3_IMPLEMENTATION_GUIDE.md](SPRINT_3_IMPLEMENTATION_GUIDE.md)
The comprehensive implementation guide contains:
- All 6 Stories with detailed descriptions and acceptance criteria
- All 35 Tasks with step-by-step implementation instructions
- Code examples for each task
- Testing and verification procedures
- Timeline and resource planning
## Stories Summary
- [ ] [Story 1](sprint_3_story_1.md) - Complete Logging Utility Migration (6 tasks) - `not_started` - **P1 High** - 1-2 days
- [ ] [Story 2](SPRINT_3_IMPLEMENTATION_GUIDE.md#story-2-component-performance-optimization) - Component Performance Optimization (6 tasks) - `not_started` - **P1 High** - 2-3 days
- [ ] [Story 3](SPRINT_3_IMPLEMENTATION_GUIDE.md#story-3-nextjs-15-async-params-migration) - Next.js 15 Async Params Migration (5 tasks) - `not_started` - **P0 Critical** - 1 day
- [ ] [Story 4](SPRINT_3_IMPLEMENTATION_GUIDE.md#story-4-error-handling-improvements) - Error Handling Improvements (6 tasks) - `not_started` - **P1 High** - 2 days
- [ ] [Story 5](SPRINT_3_IMPLEMENTATION_GUIDE.md#story-5-accessibility-enhancements) - Accessibility Enhancements (6 tasks) - `not_started` - **P2 Medium** - 2-3 days
- [ ] [Story 6](SPRINT_3_IMPLEMENTATION_GUIDE.md#story-6-code-quality-tooling) - Code Quality Tooling (6 tasks) - `not_started` - **P2 Medium** - 1 day
**Progress**: 0/6 stories, 0/35 tasks completed (0%)
## Sprint Scope Summary
### Story 1: Complete Logging Utility Migration
**Priority**: P1 (High)
**Estimated**: 1-2 days
**Owner**: Frontend Team
**Scope**:
- Replace console.log in `lib/hooks/use-projects.ts`
- Replace console.log in `lib/hooks/use-stories.ts`
- Replace console.log in `lib/hooks/use-tasks.ts`
- Replace console.log in other React Query hooks
- Replace console.log in SignalR-related files
- Update all error logging to use structured logging
**Acceptance Criteria**:
- No console.log statements in React Query hooks
- No console.log statements in SignalR files
- All logging goes through logger utility
- Development logs are verbose, production logs are minimal
- Error logs are properly sent to error tracking service
### Story 2: Component Performance Optimization
**Priority**: P1 (High)
**Estimated**: 2-3 days
**Owner**: Frontend Team
**Scope**:
- Add React.memo to ProjectCard component
- Add React.memo to SprintCard component
- Add React.memo to TaskCard component
- Add React.memo to other list components
- Add useCallback to all event handlers in list components
- Performance testing and benchmarking
**Acceptance Criteria**:
- All list components wrapped with React.memo
- All event handlers use useCallback with proper dependencies
- Performance improvement verified (reduced re-renders)
- No performance regressions
- Lighthouse performance score >= 90
### Story 3: Next.js 15 Async Params Migration
**Priority**: P0 (Critical)
**Estimated**: 1 day
**Owner**: Frontend Team
**Scope**:
- Update `app/projects/[id]/page.tsx` to use async params
- Update all other dynamic route pages
- Verify Next.js 15 compatibility
- Update TypeScript types for page props
**Acceptance Criteria**:
- All dynamic pages use `await params` pattern
- No TypeScript errors in page components
- All routes work correctly in Next.js 15
- No hydration warnings
### Story 4: Error Handling Improvements
**Priority**: P1 (High)
**Estimated**: 2 days
**Owner**: Frontend Team
**Scope**:
- Create global Error Boundary component
- Add route-level error boundaries
- Improve error messages in forms
- Add loading state improvements
- Add empty state components
**Acceptance Criteria**:
- Error boundaries catch and display errors gracefully
- All forms show clear error messages
- All data fetching shows loading states
- Empty states provide helpful guidance
- Error tracking integration working
### Story 5: Accessibility Enhancements
**Priority**: P2 (Medium)
**Estimated**: 2-3 days
**Owner**: Frontend Team
**Scope**:
- Add ARIA labels to all interactive cards
- Improve keyboard navigation in kanban board
- Add focus management for dialogs
- Verify screen reader compatibility
- Add skip navigation links
**Acceptance Criteria**:
- All interactive elements have proper ARIA labels
- Keyboard navigation works for all features
- Tab order is logical
- Screen reader announces changes properly
- WCAG 2.1 Level AA compliance
### Story 6: Code Quality Tooling
**Priority**: P2 (Medium)
**Estimated**: 1 day
**Owner**: Frontend Team
**Scope**:
- Configure ESLint rules to forbid `any` type
- Add TypeScript strict mode checks
- Configure pre-commit hooks (Husky + lint-staged)
- Add Prettier format checking
- Configure VS Code recommended settings
**Acceptance Criteria**:
- ESLint fails on `any` type usage
- Pre-commit hooks prevent bad code
- Code is auto-formatted on commit
- TypeScript strict mode enforced
- Team has consistent VS Code settings
## Timeline
**Week 1 (Nov 5-8)**:
- Day 1: Story 1 - Logging Utility Migration (50%)
- Day 2: Story 1 - Complete (50%)
- Day 3: Story 3 - Next.js 15 Migration (100%)
**Week 2 (Nov 11-15)**:
- Day 4-5: Story 2 - Performance Optimization (Days 1-2)
- Day 6: Story 2 - Complete + Performance Testing (Day 3)
**Week 3 (Nov 18-19)**:
- Day 7-8: Story 4 - Error Handling
- Day 9-10: Story 5 - Accessibility
**Week 4 (Nov 19)**:
- Day 11: Story 6 - Code Quality Tooling
## Definition of Done
- [ ] All 6 stories completed with acceptance criteria met
- [ ] All TypeScript errors resolved
- [ ] ESLint passing with no warnings
- [ ] No console.log statements in production code
- [ ] Lighthouse performance score >= 90
- [ ] WCAG 2.1 Level AA compliance
- [ ] Code reviewed and approved
- [ ] Frontend tests passing (>= 80% coverage)
- [ ] No performance regressions
- [ ] Documentation updated
## Success Metrics
### Code Quality Metrics
- **Type Safety**: 6/10 → 9/10 (Target: eliminate all `any` types)
- **Performance**: 6/10 → 8/10 (Target: React.memo + useCallback everywhere)
- **Accessibility**: 7/10 → 9/10 (Target: WCAG 2.1 Level AA)
- **Overall Quality**: 7.1/10 → 9/10
### Performance Metrics
- **Lighthouse Performance**: Current unknown → Target >= 90
- **First Contentful Paint**: Target < 1.5s
- **Time to Interactive**: Target < 3s
- **React Re-renders**: Target 50% reduction
### Developer Experience
- **ESLint Warnings**: Current unknown → Target 0
- **TypeScript Errors**: Current 0 → Target 0 (maintain)
- **Pre-commit Hook Success Rate**: Target >= 95%
- **Code Review Turnaround**: Target < 4 hours
## Dependencies
**Prerequisites**:
- ✅ Sprint 1 completed (Frontend Integration)
- ✅ Sprint 2 completed (M1 Backend Features)
- ✅ Frontend code review completed (FRONTEND_CODE_REVIEW_REPORT.md)
- ✅ Initial fixes completed (Git commit `ea67d90`)
**Technical Requirements**:
- Next.js 15+ (already installed)
- React 19+ (already installed)
- TypeScript 5.0+ (already configured)
- ESLint 8.0+ (needs rule updates)
- Husky 8.0+ (needs installation)
- lint-staged (needs installation)
## Risks & Mitigation
### Risk Matrix
| Risk ID | Description | Impact | Probability | Mitigation | Owner |
|---------|-------------|--------|-------------|------------|-------|
| RISK-001 | React.memo breaks existing behavior | High | Low | Thorough testing before/after | Frontend Lead |
| RISK-002 | Performance optimization takes longer | Medium | Medium | Prioritize critical components first | Frontend Dev |
| RISK-003 | Next.js 15 migration breaks routes | High | Low | Test all routes thoroughly | Frontend Dev |
| RISK-004 | ESLint rules too strict | Low | Medium | Iteratively tune rules | Frontend Lead |
| RISK-005 | Pre-commit hooks slow down workflow | Low | Medium | Optimize hook performance | Frontend Dev |
## Related Documents
### Planning Documents
- [Product Roadmap](../../product.md)
- [Sprint 1 Plan](sprint_1.md)
- [Sprint 2 Plan](sprint_2.md)
### Code Review
- [Frontend Code Review Report](../../FRONTEND_CODE_REVIEW_REPORT.md)
- Git Commit: `ea67d90` (Initial fixes)
### Technical References
- [Next.js 15 Documentation](https://nextjs.org/docs)
- [React Performance Optimization](https://react.dev/learn/render-and-commit)
- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
## Notes
### Code Review Findings Summary
**Critical Issues Fixed** (Git commit `ea67d90`):
- ✅ Eliminated 60+ `any` types
- ✅ Fixed 15+ `as any` type assertions
- ✅ Merged duplicate User type definitions
- ✅ Fixed IssueCard type safety with discriminated unions
- ✅ Fixed API client type parameters
- ✅ Fixed SignalR event types
- ✅ Replaced console.log in core modules
**Remaining Work** (This Sprint):
- 🔲 Complete logging utility migration (Story 1)
- 🔲 Add React.memo to list components (Story 2)
- 🔲 Fix Next.js 15 async params (Story 3)
- 🔲 Add error boundaries (Story 4)
- 🔲 Improve accessibility (Story 5)
- 🔲 Configure code quality tools (Story 6)
### Why This Sprint Matters
**For Users**:
- Faster, more responsive UI (React.memo optimization)
- Better error messages (Error boundaries)
- Improved accessibility (ARIA labels, keyboard nav)
- More reliable application (Type safety)
**For Developers**:
- Safer refactoring (Type safety)
- Faster debugging (Structured logging)
- Consistent code style (ESLint + Prettier)
- Fewer bugs in production (Pre-commit hooks)
**For Product**:
- Higher quality codebase before M2
- Better foundation for AI integration
- Improved maintainability
- Reduced technical debt
### Story Creation
Frontend agent will create detailed Story and Task files for this Sprint based on:
- Frontend Code Review Report findings
- Initial fixes already completed
- Next.js 15 best practices
- React performance optimization patterns
- WCAG 2.1 accessibility guidelines
---
**Created**: 2025-11-05 by Product Manager Agent
**Next Review**: 2025-11-12 (mid-sprint checkpoint)
**Sprint Duration**: 2 weeks (10 working days)
**Target Completion**: 2025-11-19

109
docs/plans/sprint_3_story_1.md Normal file
View File

@@ -0,0 +1,109 @@
---
story_id: sprint_3_story_1
sprint: sprint_3
priority: P1
status: not_started
story_points: 3
estimated_days: 1-2
created_date: 2025-11-05
assignee: Frontend Team
---
# Story 1: Complete Logging Utility Migration
**Sprint**: Sprint 3
**Priority**: P1 (High)
**Estimated**: 1-2 days
**Owner**: Frontend Team
## Description
Replace all remaining console.log statements in the frontend codebase with the unified logger utility (`lib/utils/logger.ts`). This improves production code quality, reduces console spam, enables proper error tracking integration, and provides environment-aware logging.
## User Story
**As a** frontend developer,
**I want** all logging to go through a unified logger utility,
**So that** logs are properly managed in development and production environments.
## Acceptance Criteria
- [ ] No console.log statements remain in React Query hooks (`lib/hooks/`)
- [ ] No console.log statements remain in SignalR files (`lib/signalr/`)
- [ ] All logging uses `logger.debug()`, `logger.info()`, or `logger.error()`
- [ ] Development logs are verbose, production logs are minimal
- [ ] Error logs are properly structured for error tracking services
- [ ] No production console spam
## Technical Requirements
**Affected Files**:
- `lib/hooks/use-projects.ts` - React Query hook logging
- `lib/hooks/use-stories.ts` - React Query hook logging
- `lib/hooks/use-tasks.ts` - React Query hook logging
- `lib/hooks/use-epics.ts` - React Query hook logging (if console.log exists)
- `lib/signalr/ConnectionManager.ts` - SignalR connection logging
- Other hooks in `lib/hooks/` directory
**Logger Utility**: `lib/utils/logger.ts` (already exists)
## Tasks
- [ ] [Task 1](sprint_3_story_1_task_1.md) - Replace console.log in use-projects.ts
- [ ] [Task 2](sprint_3_story_1_task_2.md) - Replace console.log in use-stories.ts
- [ ] [Task 3](sprint_3_story_1_task_3.md) - Replace console.log in use-tasks.ts
- [ ] [Task 4](sprint_3_story_1_task_4.md) - Replace console.log in other React Query hooks
- [ ] [Task 5](sprint_3_story_1_task_5.md) - Replace console.log in SignalR files
- [ ] [Task 6](sprint_3_story_1_task_6.md) - Verify no console.log remains
**Progress**: 0/6 tasks completed
## Dependencies
**Prerequisites**:
- ✅ Logger utility already created (`lib/utils/logger.ts`)
- ✅ Code review completed with specific console.log locations identified
## Definition of Done
- All 6 tasks completed
- No console.log statements in production code (except dev tools)
- All React Query hooks use logger
- All SignalR files use logger
- Code reviewed and approved
- Git commit created
## Test Plan
**Manual Testing**:
1. Run application in development mode
2. Verify debug logs appear in console
3. Build for production: `npm run build`
4. Verify production build has minimal console output
5. Trigger errors and verify they're logged properly
**Verification Commands**:
```bash
# Search for remaining console.log
grep -r "console.log" lib/hooks/
grep -r "console.log" lib/signalr/
# Expected: No results (or only in test files)
```
## Notes
**Why This Matters**:
- Production console spam hurts performance
- Unstructured logs make debugging harder
- Missing error tracking integration
- Security: potential information leakage
**Quick Wins**:
- Simple find-and-replace in most cases
- Immediate production quality improvement
- Foundation for error tracking (Sentry/DataDog)
---
**Created**: 2025-11-05 by Frontend Agent

550
docs/plans/sprint_4.md Normal file
View File

@@ -0,0 +1,550 @@
---
sprint_id: sprint_4
milestone: M1
status: not_started
created_date: 2025-11-05
start_date: 2025-11-06
target_end_date: 2025-11-20
---
# Sprint 4: Story Feature Implementation - UX-Driven Development
**Milestone**: M1 - Core Project Module (User Experience Enhancement)
**Goal**: Implement Story detail page and enhanced Story creation workflows based on comprehensive UX design specifications to provide users with a seamless Epic → Story → Task experience.
## Sprint Context
**Background**:
Following the completion of M1 core backend features (Sprint 1-2) and frontend quality improvements (Sprint 3), UX team delivered comprehensive Story management design specifications on 2025-11-05. The design focuses on consistency with existing Epic pages while introducing innovative Quick Add and enhanced Kanban workflows.
**Current Problem**:
1. **Story detail page does not exist** - Clicking Story cards leads to 404 error
2. **No Story creation from Kanban** - Users cannot create Stories directly from Epic cards
3. **Limited Story form** - Missing acceptance criteria, assignee, and tags fields
**UX Design Documents**:
- Complete specification: `docs/designs/STORY_UX_UI_DESIGN.md` (1,409 lines)
- Summary: `docs/designs/STORY_DESIGN_SUMMARY.md` (488 lines)
- Design phase: 5 phases over 5 weeks
## Diagnosis Report
### Backend Status ✅
**Story API**: 100% Complete
- Controller: `StoriesController.cs` with 6 endpoints
- CQRS: Full Create/Update/Delete/Assign commands
- Queries: GetStoryById, GetStoriesByEpicId, GetStoriesByProjectId
- Multi-tenant: Security verified (Day 15-16)
- Authorization: `[Authorize]` attribute present
**Endpoints Available**:
```
GET /api/v1/stories/{id} - Get Story by ID
GET /api/v1/epics/{epicId}/stories - List Epic Stories
GET /api/v1/projects/{projectId}/stories - List Project Stories
POST /api/v1/stories - Create Story
POST /api/v1/epics/{epicId}/stories - Create Story (nested)
PUT /api/v1/stories/{id} - Update Story
DELETE /api/v1/stories/{id} - Delete Story
PUT /api/v1/stories/{id}/assign - Assign Story
```
### Frontend Status ⚠️ (Partial)
**✅ Already Implemented**:
1. **Story API Client** (`lib/api/pm.ts`)
- All CRUD operations: list, get, create, update, delete
- Status change and assign methods
- Fully typed with TypeScript
2. **Story Hooks** (`lib/hooks/use-stories.ts`)
- `useStories(epicId)` - List stories by epic
- `useProjectStories(projectId)` - List all project stories
- `useStory(id)` - Get single story
- `useCreateStory()`, `useUpdateStory()`, `useDeleteStory()`
- `useChangeStoryStatus()`, `useAssignStory()`
- Optimistic updates with React Query
3. **Story Form Component** (`components/projects/story-form.tsx`)
- Create and Edit modes
- Fields: epicId, title, description, priority, estimatedHours
- Form validation with Zod
- Parent Epic selector
- **Missing**: Acceptance criteria, assignee selector, tags
4. **Story Display in Epic Detail** (`app/(dashboard)/epics/[id]/page.tsx`)
- Stories list in Epic detail page
- Story cards with status and priority badges
- Edit and Delete buttons
- Create Story dialog
- **Working**: Story creation and editing from Epic page
5. **Story Types** (`types/project.ts`)
- Full Story interface defined
- CreateStoryDto and UpdateStoryDto types
- All fields properly typed
**❌ Missing Implementation**:
1. **Story Detail Page** - `app/(dashboard)/stories/[id]/page.tsx` does not exist
- No route configured
- No Story detail UI
- Cannot view Story details, Tasks, or Activity
2. **Task Management in Story** - No Task UI components
- No Task list component
- No Task creation from Story
- No Task status updates
3. **Story Quick Add** - No inline creation flow
- Only full dialog form exists
- Missing rapid Story creation workflow
4. **Kanban Story Creation** - No Epic card Story creation
- Cannot add Stories from Kanban
- Missing contextual creation
5. **Activity Timeline** - No change history component
- Missing audit log display
- No real-time activity feed
6. **Enhanced Story Form** - Missing UX fields
- No acceptance criteria field
- No assignee selector
- No tags/labels support
### Gap Analysis Summary
| Feature | Backend | Frontend | Gap |
|---------|---------|----------|-----|
| Story CRUD | ✅ 100% | ✅ 100% | None |
| Story Detail Page | ✅ API Ready | ❌ Missing | **CRITICAL** |
| Task Management | ✅ API Ready | ❌ Missing | **HIGH** |
| Quick Add Story | ✅ API Ready | ❌ Missing | **MEDIUM** |
| Kanban Story Create | ✅ API Ready | ❌ Missing | **MEDIUM** |
| Activity Timeline | ⚠️ Partial | ❌ Missing | **LOW** |
| Acceptance Criteria | ❌ No field | ❌ Missing | **MEDIUM** |
| Assignee Selector | ✅ API Ready | ❌ Missing | **MEDIUM** |
**Priority Assessment**:
- **P0 (Critical)**: Story Detail Page + Task List - Users cannot access Stories
- **P1 (High)**: Enhanced Story Form + Quick Add - Incomplete user experience
- **P2 (Medium)**: Kanban enhancements + Activity Timeline - Nice to have features
## Sprint Objectives
1. **Story Detail Page** - Enable users to view and manage Story details with full Task support
2. **Enhanced Story Form** - Add missing UX fields (acceptance criteria, assignee, tags)
3. **Quick Add Workflow** - Implement rapid Story creation inline form
4. **Task Management** - Build Task list, creation, and status update UI
5. **Kanban Enhancement** - Add contextual Story creation from Epic cards (optional)
## Implementation Strategy
### Phase-Based Approach (5 Phases from UX Design)
**Our Sprint**: Focus on **Phase 1 + Phase 2** (Weeks 1-2)
- Phase 1: Core Story Detail (Week 1) - P0 Critical
- Phase 2: Story Creation & Editing (Week 2) - P1 High
- Phase 3-5: Deferred to future sprints
**Rationale**:
- Deliver immediate value (fix Story page 404 error)
- Iterative approach reduces risk
- Align with UX design phasing
- Team can gather feedback before Phase 3-5
### Reuse Epic Pattern Strategy
**Key Insight**: Story detail page is 85% similar to Epic detail page
- Epic page: `app/(dashboard)/epics/[id]/page.tsx` (534 lines)
- Epic form: `components/epics/epic-form.tsx`
- Epic hooks: `lib/hooks/use-epics.ts`
**Reuse Plan**:
1. Copy Epic detail page structure → Story detail page
2. Adapt Epic form enhancements → Story form
3. Reuse Epic card patterns → Story card component
4. Copy Epic status/priority logic → Story metadata
**Benefits**:
- **Consistency**: Visual and interaction consistency
- **Speed**: 50-60% faster development (reuse code)
- **Quality**: Proven patterns, fewer bugs
- **Maintenance**: Shared components easier to maintain
## Stories
- [ ] [story_1](sprint_4_story_1.md) - Story Detail Page Foundation - `not_started` - **P0 Critical** - 3 days
- [ ] [story_2](sprint_4_story_2.md) - Task Management in Story Detail - `not_started` - **P0 Critical** - 2 days
- [ ] [story_3](sprint_4_story_3.md) - Enhanced Story Form - `not_started` - **P1 High** - 2 days
- [ ] [story_4](sprint_4_story_4.md) - Quick Add Story Workflow - `not_started` - **P1 High** - 2 days
- [ ] [story_5](sprint_4_story_5.md) - Story Card Component - `not_started` - **P2 Medium** - 1 day
- [ ] [story_6](sprint_4_story_6.md) - Kanban Story Creation Enhancement - `not_started` - **P2 Medium** - 2 days (Optional)
**Progress**: 0/6 stories, 0/30+ tasks completed (0%)
## Sprint Scope Summary
### Story 1: Story Detail Page Foundation ⭐ CRITICAL
**Estimated**: 3 days (Day 1-3)
**Owner**: Frontend Team
**Dependencies**: None (API ready)
**Scope**:
- Create `app/(dashboard)/stories/[id]/page.tsx` route
- Implement two-column layout (main content + metadata sidebar)
- Display Story header (title, status, priority badges)
- Show Story description and metadata (assignee, time, dates)
- Display parent Epic card in sidebar
- Add Edit and Delete actions
- Error handling (404, network errors)
- Loading states with skeleton loaders
**Acceptance Criteria**:
- Clicking Story card navigates to `/stories/{id}` page
- Page displays all Story information
- Layout matches Epic detail page consistency
- Responsive design works on mobile/tablet/desktop
- All actions (Edit, Delete) work correctly
- Loading and error states display properly
**Deliverables**:
- Story detail page component
- Story metadata sidebar component
- Story header component
- Route configuration
---
### Story 2: Task Management in Story Detail ⭐ CRITICAL
**Estimated**: 2 days (Day 3-4)
**Owner**: Frontend Team
**Dependencies**: Story 1 (Story detail page must exist)
**Scope**:
- Create Task list component with expandable Task cards
- Implement Task checkbox for quick status toggle
- Add "Add Task" button and inline creation form
- Display Task metadata (priority, assignee, estimated hours)
- Implement Task filtering (status, priority, assignee)
- Add Task sorting options
- Show Task count badge in header
- Empty state when no Tasks exist
**Acceptance Criteria**:
- Tasks display in Story detail page
- Users can create new Tasks inline
- Clicking Task checkbox updates status
- Task filters and sorting work correctly
- Task count updates in real-time
- Empty state shows helpful guidance
- Task creation form validates inputs
**Deliverables**:
- `components/projects/task-list.tsx`
- `components/projects/task-card.tsx`
- `components/projects/task-form.tsx` (inline variant)
- Task hooks integration
---
### Story 3: Enhanced Story Form
**Estimated**: 2 days (Day 5-6)
**Owner**: Frontend Team
**Dependencies**: None (independent enhancement)
**Scope**:
- Add Acceptance Criteria field (checkbox list)
- Implement Assignee selector (searchable dropdown)
- Add Tags/Labels field (multi-select)
- Add Story Points field (optional)
- Enhance form validation
- Add form field descriptions
- Improve form layout (two-column grid)
- Add "Save Draft" functionality (optional)
**Acceptance Criteria**:
- Form includes all new fields
- Assignee selector shows user list
- Acceptance criteria can be added/removed dynamically
- Tags support multi-select
- Form validation works for all fields
- Form saves correctly with new fields
- Backward compatible with existing Stories
**Deliverables**:
- Enhanced `components/projects/story-form.tsx`
- Assignee selector component
- Acceptance criteria editor component
- Tag selector component
---
### Story 4: Quick Add Story Workflow
**Estimated**: 2 days (Day 7-8)
**Owner**: Frontend Team
**Dependencies**: Story 3 (enhanced form patterns)
**Scope**:
- Create inline Story form component (Quick Add variant)
- Add "+ Quick Add" button at top of Stories list
- Implement minimal form (title + priority only)
- Add keyboard shortcut (Cmd/Ctrl + N)
- Auto-reset form after creation
- Add "Add & Create Tasks" button
- Implement form animations
- Show success toast notifications
**Acceptance Criteria**:
- Quick Add button appears in Epic detail Stories section
- Inline form shows with minimal fields
- Story creates on Enter key press
- Form resets and stays open for batch creation
- Keyboard shortcut works globally
- "Add & Create Tasks" navigates to Story detail
- Animations smooth and performant
**Deliverables**:
- `components/projects/quick-add-story.tsx`
- Story form "quick mode" variant
- Keyboard shortcut handler
- Batch creation workflow
---
### Story 5: Story Card Component
**Estimated**: 1 day (Day 9)
**Owner**: Frontend Team
**Dependencies**: Story 1, 2 (understand Story structure)
**Scope**:
- Create reusable Story card component
- Implement three variants (list, kanban, compact)
- Add visual states (hover, selected, dragging)
- Show Story metadata badges
- Add quick actions menu (Edit, Delete, Duplicate)
- Implement card hover effects
- Add Task count indicator
- Support drag-and-drop preparation
**Acceptance Criteria**:
- Story card works in all three variants
- Visual states display correctly
- Quick actions appear on hover
- Card shows all relevant metadata
- Component is reusable across views
- Performance optimized with React.memo
- TypeScript types fully defined
**Deliverables**:
- `components/projects/story-card.tsx`
- Story card Storybook stories (optional)
- Card visual state tests
---
### Story 6: Kanban Story Creation Enhancement (Optional)
**Estimated**: 2 days (Day 10-11)
**Owner**: Frontend Team
**Dependencies**: Story 1, 4 (Story detail + Quick Add patterns)
**Status**: Optional (stretch goal)
**Scope**:
- Add "+ Add Story" button to Epic cards on hover
- Implement inline Story form below Epic card
- Context-bound Story creation (Epic pre-selected)
- Add Story to correct Kanban column by status
- Implement form slide-in animation
- Add "Cancel" and outside-click close
- Update Epic Story count in real-time
**Acceptance Criteria**:
- Hover Epic card shows "+ Add Story" action
- Clicking opens inline Story form
- Form creates Story under correct Epic
- Story appears in appropriate Kanban column
- Epic Story count updates immediately
- Animation smooth and intuitive
- Can cancel or close form easily
**Deliverables**:
- Enhanced Kanban Epic card component
- Inline Story form integration
- Kanban Story creation workflow
- Real-time count updates
---
## Timeline
**Week 1 (Nov 6-8)**: Core Story Detail - P0 Critical
- Day 1-2: Story 1 - Story Detail Page Foundation (Tasks 1-4)
- Day 3: Story 2 - Task Management (Tasks 1-3)
**Week 2 (Nov 11-15)**: Enhanced Creation Workflows - P1 High
- Day 4: Story 2 - Task Management Complete (Tasks 4-6)
- Day 5-6: Story 3 - Enhanced Story Form (Tasks 1-6)
- Day 7-8: Story 4 - Quick Add Workflow (Tasks 1-5)
**Week 3 (Nov 18-20)**: Polish & Optional Features - P2 Medium
- Day 9: Story 5 - Story Card Component (Tasks 1-4)
- Day 10-11: Story 6 - Kanban Enhancement (Optional)
## Definition of Done
- [ ] All P0 and P1 stories completed (Stories 1-4)
- [ ] Story detail page accessible and fully functional
- [ ] Users can create and manage Tasks within Stories
- [ ] Enhanced Story form includes all UX-designed fields
- [ ] Quick Add workflow enables rapid Story creation
- [ ] All acceptance criteria met for completed stories
- [ ] TypeScript types updated for new fields
- [ ] No console errors or warnings
- [ ] Manual testing passed on Chrome/Firefox/Edge
- [ ] Mobile responsive design verified
- [ ] Code reviewed and approved
- [ ] Documentation updated
## Success Metrics
### User Experience Metrics
- **Story Page Load Time**: < 1 second (per UX design target)
- **Task Creation Time**: < 20 seconds (per UX design target)
- **Quick Add Speed**: < 30 seconds (per UX design target)
- **Navigation Clicks**: Epic → Task in < 3 clicks (per UX design)
- **Error Rate**: < 5% (per UX design)
### Code Quality Metrics
- **TypeScript Coverage**: 100% (no `any` types)
- **Component Reusability**: >= 80% (reuse Epic patterns)
- **Performance**: Lighthouse score >= 90 (per Sprint 3 standard)
- **Accessibility**: WCAG 2.1 Level AA compliance (per UX design)
### Completion Metrics
- **P0 Stories**: 2/2 completed (100%) - Story 1, 2
- **P1 Stories**: 2/2 completed (100%) - Story 3, 4
- **P2 Stories**: 1-2/2 completed (50-100%) - Story 5, 6 (optional)
- **Overall Sprint**: 4/6 stories minimum (67%), 6/6 ideal (100%)
## Dependencies
**Prerequisites**:
- ✅ Sprint 1 completed (Frontend Integration)
- ✅ Sprint 2 completed (M1 Backend Features)
- ✅ Sprint 3 completed (Frontend Code Quality)
- ✅ Story API 100% ready (StoriesController)
- ✅ Task API 100% ready (TasksController)
- ✅ UX design complete (STORY_UX_UI_DESIGN.md)
**Technical Requirements**:
- Next.js 15+ (already configured)
- React 19+ (already configured)
- React Query 4.0+ (already configured)
- shadcn/ui components (already available)
- @dnd-kit/core for drag-drop (already installed)
## Risks & Mitigation
### Risk Matrix
| Risk ID | Description | Impact | Probability | Mitigation | Owner |
|---------|-------------|--------|-------------|------------|-------|
| RISK-001 | Task API not fully tested | High | Medium | Backend team verify Task endpoints Day 1 | Backend Lead |
| RISK-002 | Story/Task relationship complexity | Medium | Medium | Reuse Epic/Story pattern, early testing | Frontend Dev |
| RISK-003 | UX design phase 1-2 scope too large | High | Low | Focus on P0/P1 only, defer P2 | Product Manager |
| RISK-004 | Acceptance criteria backend missing | Medium | High | Defer to future sprint if needed | Product Manager |
| RISK-005 | Mobile responsive layout challenging | Medium | Medium | Test early and often on mobile devices | Frontend Dev |
## Related Documents
### UX Design Documents
- [Story UX/UI Design Specification](../designs/STORY_UX_UI_DESIGN.md)
- [Story Design Summary](../designs/STORY_DESIGN_SUMMARY.md)
### Planning Documents
- [Product Roadmap](../../product.md)
- [Sprint 1 Plan](sprint_1.md) - Frontend Integration
- [Sprint 2 Plan](sprint_2.md) - M1 Backend Features
- [Sprint 3 Plan](sprint_3.md) - Frontend Code Quality
### Technical References
- [ProjectManagement Module](../../colaflow-api/src/ColaFlow.Modules.ProjectManagement/)
- [Epic Detail Page](../../colaflow-web/app/(dashboard)/epics/[id]/page.tsx)
- [Story Types](../../colaflow-web/types/project.ts)
## Notes
### Why This Sprint Matters
**For Users**:
- **Fix Critical Bug**: Story links currently lead to 404 errors
- **Complete User Journey**: Epic → Story → Task navigation works end-to-end
- **Faster Workflows**: Quick Add enables rapid Story creation
- **Better Planning**: Acceptance criteria and assignee tracking
**For Product**:
- **UX Design Implementation**: Deliver on comprehensive UX specification
- **Feature Parity**: Story management on par with Epic management
- **User Satisfaction**: Fix reported user complaints about Story access
- **M1 Enhancement**: Improve core project management experience
**For Development**:
- **Reuse Patterns**: 60% code reuse from Epic implementation
- **Consistency**: Maintain design system consistency
- **Quality**: Build on Sprint 3 quality improvements
- **Foundation**: Enable future Phase 3-5 UX enhancements
### Story vs Epic Differences
**Key Distinctions**:
1. **Stories have Tasks**, Epics have Stories
2. **Stories are smaller**, typically 1-2 week effort
3. **Stories have acceptance criteria**, Epics have high-level goals
4. **Stories assignable to individuals**, Epics to teams
5. **Stories more granular tracking**, Epics high-level progress
**Implementation Impact**:
- Story detail shows **Task list** (not Story list)
- Story form includes **acceptance criteria** field
- Story cards show **Task count** (not Story count)
- Story hierarchy: Epic → **Story** → Task
### Backend API Verification Checklist
Frontend team should verify these before Day 1:
- [ ] GET /api/v1/stories/{id} returns Story with all fields
- [ ] GET /api/v1/stories/{id}/tasks returns Task list
- [ ] POST /api/v1/tasks with storyId creates Task correctly
- [ ] PUT /api/v1/stories/{id} accepts all fields (title, description, priority, etc.)
- [ ] DELETE /api/v1/stories/{id} cascades to Tasks
- [ ] Multi-tenant isolation works (cannot access other tenant Stories)
### Future Enhancements (Post-Sprint 4)
**Phase 3 (Future Sprint)**: Task Management Enhancements
- Task drag-and-drop reordering
- Task bulk operations (multi-select)
- Task filters advanced (custom queries)
- Task due dates and reminders
**Phase 4 (Future Sprint)**: Kanban Full Integration
- Story cards in Kanban (alongside Epic cards)
- Story drag-and-drop to change status
- Story grouping options
- Story swimlanes
**Phase 5 (Future Sprint)**: Polish & Accessibility
- Keyboard shortcuts (Cmd/Ctrl + N, 1-4 for status, etc.)
- Screen reader ARIA labels
- Mobile swipe gestures
- Activity timeline component
- Performance optimization
---
**Created**: 2025-11-05 by Product Manager Agent
**Next Review**: 2025-11-13 (mid-sprint checkpoint)
**Sprint Duration**: 3 weeks (15 working days)
**Target Completion**: 2025-11-20
**Minimum Viable**: 2025-11-15 (P0/P1 only, 10 days)

1117
docs/plans/sprint_5.md Normal file
View File

File diff suppressed because it is too large Load Diff

456
docs/sprints/sprint_4.md Normal file
View File

@@ -0,0 +1,456 @@
---
sprint_id: sprint_4
milestone: M1
status: not_started
created_date: 2025-11-05
start_date: 2025-11-06
target_end_date: 2025-11-20
---
# Sprint 4: Story Management & UX Enhancement
**Milestone**: M1 - Core Project Module (User Experience Enhancement)
**Goal**: Implement Story detail page and Task management to enable seamless Epic → Story → Task navigation and fix critical Story page 404 error.
## Sprint Objectives
1. **Fix Critical Bug**: Story detail page returns 404 error - Users cannot access Story information
2. **Complete User Journey**: Enable full Epic → Story → Task navigation in less than 3 clicks
3. **Task Management**: Implement Task list, creation, and status updates within Story context
4. **Enhanced UX**: Improve Story creation workflow with Quick Add and enhanced form fields
## Stories
### Frontend Stories (P0/P1)
- [ ] [story_1](../plans/sprint_4_story_1.md) - Story Detail Page Foundation - `not_started` - **P0 Critical**
- [ ] [story_2](../plans/sprint_4_story_2.md) - Task Management in Story Detail - `not_started` - **P0 Critical**
- [ ] [story_3](../plans/sprint_4_story_3.md) - Enhanced Story Form - `not_started` - **P1 High**
- [ ] [story_4](../plans/sprint_4_story_4.md) - Quick Add Story Workflow - `not_started` - **P1 High**
- [ ] [story_5](../plans/sprint_4_story_5.md) - Story Card Component - `not_started` - **P2 Medium**
- [ ] [story_6](../plans/sprint_4_story_6.md) - Kanban Story Creation Enhancement - `not_started` - **P2 Optional**
### Backend Stories (Optional)
- [ ] [story_0](../plans/sprint_4_story_0.md) - Backend API Enhancements (AcceptanceCriteria, Tags, StoryPoints, Task Order) - `not_started` - **P2 Optional**
**Progress**: 0/7 completed (0%)
## Sprint Context
### Current Problem
**Critical Issue**: Story detail page does not exist
- Clicking Story cards from Epic detail page results in 404 error
- Users cannot view Story information or manage Tasks
- Incomplete user experience for core project management flow
**Gap Analysis**:
| Feature | Backend Status | Frontend Status | Priority |
|---------|----------------|-----------------|----------|
| Story CRUD | ✅ 100% Ready | ✅ 100% Ready | - |
| Story Detail Page | ✅ API Ready | ❌ Missing | **P0 Critical** |
| Task Management | ✅ API Ready | ❌ Missing | **P0 Critical** |
| Enhanced Story Form | ⚠️ Partial | ❌ Missing | **P1 High** |
| Quick Add Workflow | ✅ API Ready | ❌ Missing | **P1 High** |
| Story Card Component | ✅ API Ready | ⚠️ Partial | **P2 Medium** |
### Backend API Status ✅
**Verification Report**: See [Backend API Verification](sprint_4/backend_api_verification.md) for detailed analysis
**Story API**: 100% Complete (StoriesController.cs)
Available Endpoints:
- `GET /api/v1/stories/{id}` - Get Story by ID
- `GET /api/v1/epics/{epicId}/stories` - List Stories by Epic
- `GET /api/v1/projects/{projectId}/stories` - List Stories by Project
- `POST /api/v1/stories` - Create Story
- `POST /api/v1/epics/{epicId}/stories` - Create Story (nested)
- `PUT /api/v1/stories/{id}` - Update Story
- `DELETE /api/v1/stories/{id}` - Delete Story
- `PUT /api/v1/stories/{id}/assign` - Assign Story
**Task API**: 100% Complete (TasksController.cs)
- `GET /api/v1/tasks/{id}` - Get Task by ID
- `GET /api/v1/stories/{storyId}/tasks` - List Tasks by Story
- `POST /api/v1/stories/{storyId}/tasks` - Create Task
- `PUT /api/v1/tasks/{id}` - Update Task
- `PUT /api/v1/tasks/{id}/status` - Quick status toggle
- `DELETE /api/v1/tasks/{id}` - Delete Task
**Security**: Multi-tenant isolation verified, `[Authorize]` attribute present
**Optional Enhancements**: AcceptanceCriteria, Tags, StoryPoints, Task Order fields can be added via [Story 0](../plans/sprint_4_story_0.md) if needed
### Frontend Status ⚠️
**Already Implemented**:
- ✅ Story API Client (`lib/api/pm.ts`)
- ✅ Story Hooks (`lib/hooks/use-stories.ts`)
- ✅ Basic Story Form (`components/projects/story-form.tsx`)
- ✅ Story display in Epic detail page
- ✅ Story types defined (`types/project.ts`)
**Missing Implementation**:
- ❌ Story Detail Page (`app/(dashboard)/stories/[id]/page.tsx`)
- ❌ Task Management UI components
- ❌ Enhanced Story Form fields (acceptance criteria, assignee, tags)
- ❌ Quick Add Story workflow
- ❌ Story Card Component (reusable variants)
## Sprint Scope Summary
### Story 1: Story Detail Page Foundation ⭐ P0 CRITICAL
**Estimated**: 3 days (Day 1-3)
**Owner**: Frontend Team
**Scope**:
- Create Story detail page route (`/stories/[id]`)
- Implement two-column layout (content + metadata sidebar)
- Display Story header, description, and metadata
- Show parent Epic card in sidebar
- Add Edit and Delete actions
- Error handling (404, network errors) and loading states
**Acceptance Criteria**:
- Clicking Story card navigates to `/stories/{id}` page
- Page displays all Story information
- Layout matches Epic detail page consistency
- Responsive design works on mobile/tablet/desktop
- All actions (Edit, Delete) work correctly
**Deliverables**:
- `app/(dashboard)/stories/[id]/page.tsx`
- Story metadata sidebar component
- Story header component
- Route configuration
---
### Story 2: Task Management in Story Detail ⭐ P0 CRITICAL
**Estimated**: 2 days (Day 3-4)
**Owner**: Frontend Team
**Dependencies**: Story 1 (Story detail page must exist)
**Scope**:
- Create Task list component with expandable cards
- Implement Task checkbox for quick status toggle
- Add "Add Task" button and inline creation form
- Display Task metadata (priority, assignee, estimated hours)
- Implement Task filtering and sorting
- Show Task count badge in header
- Empty state when no Tasks exist
**Acceptance Criteria**:
- Tasks display in Story detail page
- Users can create new Tasks inline
- Clicking Task checkbox updates status
- Task filters and sorting work correctly
- Task count updates in real-time
- Empty state shows helpful guidance
**Deliverables**:
- `components/projects/task-list.tsx`
- `components/projects/task-card.tsx`
- `components/projects/task-form.tsx` (inline variant)
- Task hooks integration
---
### Story 3: Enhanced Story Form
**Estimated**: 2 days (Day 5-6)
**Owner**: Frontend Team
**Scope**:
- Add Acceptance Criteria field (checkbox list)
- Implement Assignee selector (searchable dropdown)
- Add Tags/Labels field (multi-select)
- Add Story Points field
- Enhance form validation
- Improve form layout (two-column grid)
**Acceptance Criteria**:
- Form includes all new fields
- Assignee selector shows user list
- Acceptance criteria can be added/removed dynamically
- Tags support multi-select
- Form validation works for all fields
- Backward compatible with existing Stories
**Deliverables**:
- Enhanced `components/projects/story-form.tsx`
- Assignee selector component
- Acceptance criteria editor component
- Tag selector component
---
### Story 4: Quick Add Story Workflow
**Estimated**: 2 days (Day 7-8)
**Owner**: Frontend Team
**Dependencies**: Story 3 (enhanced form patterns)
**Scope**:
- Create inline Story form component (Quick Add variant)
- Add "+ Quick Add" button at top of Stories list
- Implement minimal form (title + priority only)
- Add keyboard shortcut (Cmd/Ctrl + N)
- Auto-reset form after creation
- Show success toast notifications
**Acceptance Criteria**:
- Quick Add button appears in Epic detail Stories section
- Inline form shows with minimal fields
- Story creates on Enter key press
- Form resets and stays open for batch creation
- Keyboard shortcut works globally
- Animations smooth and performant
**Deliverables**:
- `components/projects/quick-add-story.tsx`
- Story form "quick mode" variant
- Keyboard shortcut handler
- Batch creation workflow
---
### Story 5: Story Card Component
**Estimated**: 1 day (Day 9)
**Owner**: Frontend Team
**Dependencies**: Story 1, 2 (understand Story structure)
**Scope**:
- Create reusable Story card component
- Implement three variants (list, kanban, compact)
- Add visual states (hover, selected, dragging)
- Show Story metadata badges
- Add quick actions menu (Edit, Delete, Duplicate)
- Add Task count indicator
- Support drag-and-drop preparation
**Acceptance Criteria**:
- Story card works in all three variants
- Visual states display correctly
- Quick actions appear on hover
- Card shows all relevant metadata
- Component is reusable across views
- Performance optimized with React.memo
**Deliverables**:
- `components/projects/story-card.tsx`
- Card visual state tests
---
### Story 6: Kanban Story Creation Enhancement (Optional)
**Estimated**: 2 days (Day 10-11)
**Owner**: Frontend Team
**Dependencies**: Story 1, 4
**Status**: Optional (stretch goal)
**Scope**:
- Add "+ Add Story" button to Epic cards on hover
- Implement inline Story form below Epic card
- Context-bound Story creation (Epic pre-selected)
- Add Story to correct Kanban column by status
- Update Epic Story count in real-time
**Acceptance Criteria**:
- Hover Epic card shows "+ Add Story" action
- Clicking opens inline Story form
- Form creates Story under correct Epic
- Story appears in appropriate Kanban column
- Epic Story count updates immediately
**Deliverables**:
- Enhanced Kanban Epic card component
- Inline Story form integration
- Real-time count updates
## Timeline
**Week 1 (Nov 6-8)**: Core Story Detail - P0 Critical
- Day 1-2: Story 1 - Story Detail Page Foundation
- Day 3: Story 2 - Task Management (start)
**Week 2 (Nov 11-15)**: Task Management & Enhanced Creation - P0 + P1
- Day 4: Story 2 - Task Management Complete
- Day 5-6: Story 3 - Enhanced Story Form
- Day 7-8: Story 4 - Quick Add Workflow
**Week 3 (Nov 18-20)**: Polish & Optional Features - P2
- Day 9: Story 5 - Story Card Component
- Day 10-11: Story 6 - Kanban Enhancement (Optional)
## Implementation Strategy
### Reuse Epic Pattern Strategy
**Key Insight**: Story detail page is 85% similar to Epic detail page
Reuse Plan:
1. Copy Epic detail page structure → Story detail page
2. Adapt Epic form enhancements → Story form
3. Reuse Epic card patterns → Story card component
4. Copy Epic status/priority logic → Story metadata
**Benefits**:
- **Consistency**: Visual and interaction consistency across the app
- **Speed**: 50-60% faster development through code reuse
- **Quality**: Proven patterns, fewer bugs
- **Maintenance**: Shared components easier to maintain
### Story vs Epic Differences
**Key Distinctions**:
1. **Stories have Tasks**, Epics have Stories
2. **Stories are smaller**, typically 1-2 week effort
3. **Stories have acceptance criteria**, Epics have high-level goals
4. **Stories assignable to individuals**, Epics to teams
5. **Stories more granular tracking**, Epics high-level progress
**Implementation Impact**:
- Story detail shows **Task list** (not Story list)
- Story form includes **acceptance criteria** field
- Story cards show **Task count** (not Story count)
- Story hierarchy: Epic → **Story** → Task
## Definition of Done
- [ ] All P0 and P1 stories completed (Stories 1-4)
- [ ] Story detail page accessible and fully functional
- [ ] Users can create and manage Tasks within Stories
- [ ] Enhanced Story form includes all UX-designed fields
- [ ] Quick Add workflow enables rapid Story creation
- [ ] All acceptance criteria met for completed stories
- [ ] TypeScript types updated for new fields
- [ ] No console errors or warnings
- [ ] Manual testing passed on Chrome/Firefox/Edge
- [ ] Mobile responsive design verified
- [ ] Code reviewed and approved
- [ ] Documentation updated
## Success Metrics
### User Experience Metrics
- **Story Page Load Time**: < 1 second
- **Task Creation Time**: < 20 seconds
- **Quick Add Speed**: < 30 seconds (from idea to created Story)
- **Navigation Clicks**: Epic → Task in < 3 clicks
- **Error Rate**: < 5%
### Code Quality Metrics
- **TypeScript Coverage**: 100% (no `any` types)
- **Component Reusability**: >= 80% (reuse Epic patterns)
- **Performance**: Lighthouse score >= 90 (per Sprint 3 standard)
- **Accessibility**: WCAG 2.1 Level AA compliance
### Completion Metrics
- **P0 Stories**: 2/2 completed (100%) - Story 1, 2
- **P1 Stories**: 2/2 completed (100%) - Story 3, 4
- **P2 Stories**: 1-2/2 completed (50-100%) - Story 5, 6 (optional)
- **Overall Sprint**: 4/6 stories minimum (67%), 6/6 ideal (100%)
## Dependencies
**Prerequisites**:
- ✅ Sprint 1 completed (Frontend Integration)
- ✅ Sprint 2 completed (M1 Backend Features)
- ✅ Sprint 3 completed (Frontend Code Quality)
- ✅ Story API 100% ready (StoriesController)
- ✅ Task API 100% ready (TasksController)
**Technical Requirements**:
- Next.js 15+ (already configured)
- React 19+ (already configured)
- React Query 4.0+ (already configured)
- shadcn/ui components (already available)
- @dnd-kit/core for drag-drop (already installed)
## Risks & Mitigation
| Risk ID | Description | Impact | Probability | Mitigation | Owner |
|---------|-------------|--------|-------------|------------|-------|
| RISK-001 | Task API not fully tested | High | Medium | Backend team verify Task endpoints Day 1 | Backend Lead |
| RISK-002 | Story/Task relationship complexity | Medium | Medium | Reuse Epic/Story pattern, early testing | Frontend Dev |
| RISK-003 | UX design scope too large | High | Low | Focus on P0/P1 only, defer P2 | Product Manager |
| RISK-004 | Acceptance criteria backend missing | Medium | High | Defer to future sprint if needed | Product Manager |
| RISK-005 | Mobile responsive layout challenging | Medium | Medium | Test early and often on mobile devices | Frontend Dev |
## Related Documents
### UX Design Documents
- [Story UX/UI Design Specification](../designs/STORY_UX_UI_DESIGN.md) (1,409 lines)
- [Story Design Summary](../designs/STORY_DESIGN_SUMMARY.md) (488 lines)
### Planning Documents
- [Product Roadmap](../../product.md)
- [Sprint 1 Plan](../plans/sprint_1.md) - Frontend Integration
- [Sprint 2 Plan](../plans/sprint_2.md) - M1 Backend Features
- [Sprint 3 Plan](../plans/sprint_3.md) - Frontend Code Quality
### Technical References
- [ProjectManagement Module](../../colaflow-api/src/ColaFlow.Modules.ProjectManagement/)
- [Epic Detail Page](../../colaflow-web/app/(dashboard)/epics/[id]/page.tsx) (534 lines - reference implementation)
- [Story Types](../../colaflow-web/types/project.ts)
## Backend API Verification Checklist
Frontend team should verify these before Day 1:
- [ ] GET /api/v1/stories/{id} returns Story with all fields
- [ ] GET /api/v1/stories/{id}/tasks returns Task list
- [ ] POST /api/v1/tasks with storyId creates Task correctly
- [ ] PUT /api/v1/stories/{id} accepts all fields
- [ ] DELETE /api/v1/stories/{id} cascades to Tasks
- [ ] Multi-tenant isolation works (cannot access other tenant Stories)
## Notes
### Why This Sprint Matters
**For Users**:
- **Fix Critical Bug**: Story links currently lead to 404 errors
- **Complete User Journey**: Epic → Story → Task navigation works end-to-end
- **Faster Workflows**: Quick Add enables rapid Story creation
- **Better Planning**: Acceptance criteria and assignee tracking
**For Product**:
- **UX Design Implementation**: Deliver on comprehensive UX specification
- **Feature Parity**: Story management on par with Epic management
- **User Satisfaction**: Fix reported user complaints about Story access
- **M1 Enhancement**: Improve core project management experience
**For Development**:
- **Reuse Patterns**: 60% code reuse from Epic implementation
- **Consistency**: Maintain design system consistency
- **Quality**: Build on Sprint 3 quality improvements
- **Foundation**: Enable future Phase 3-5 UX enhancements
### Future Enhancements (Post-Sprint 4)
**Phase 3**: Task Management Enhancements
- Task drag-and-drop reordering
- Task bulk operations (multi-select)
- Task filters advanced (custom queries)
- Task due dates and reminders
**Phase 4**: Kanban Full Integration
- Story cards in Kanban (alongside Epic cards)
- Story drag-and-drop to change status
- Story grouping options
- Story swimlanes
**Phase 5**: Polish & Accessibility
- Keyboard shortcuts (Cmd/Ctrl + N, 1-4 for status)
- Screen reader ARIA labels
- Mobile swipe gestures
- Activity timeline component
- Performance optimization
---
**Created**: 2025-11-05 by Product Manager Agent
**Next Review**: 2025-11-13 (mid-sprint checkpoint)
**Sprint Duration**: 3 weeks (15 working days)
**Target Completion**: 2025-11-20
**Minimum Viable**: 2025-11-15 (P0/P1 only, 10 days)