Add trace files.

2025-11-04 23:28:56 +01:00
parent 25d30295ec
commit 08b317e789
75 changed files with 26456 additions and 37017 deletions
--- a/docs/architecture/ARCHITECTURE-DECISION-PROJECTMANAGEMENT.md
+++ b/docs/architecture/ARCHITECTURE-DECISION-PROJECTMANAGEMENT.md
@@ -0,0 +1,498 @@
+# 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)