Sync

2025-11-08 18:13:48 +01:00
parent 48a8431e4f
commit b11c6447b5
48 changed files with 15754 additions and 10133 deletions
--- a/docs/sprints/sprint_4.md
+++ b/docs/sprints/sprint_4.md
@@ -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)