junhong_cmp_fiber/.specify/templates/tasks-template.md

description

description
Task list template for feature implementation

Tasks: [FEATURE NAME]

Input: Design documents from /specs/[###-feature-name]/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

Tests: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.

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

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

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

Path Conventions

• Single project: src/, tests/ at repository root
• Web app: backend/src/, frontend/src/
• Mobile: api/src/, ios/src/ or android/src/
• Paths shown below assume single project - adjust based on plan.md structure

Phase 1: Setup (Shared Infrastructure)

Purpose: Project initialization and basic structure

• T001 Create project structure per implementation plan (internal/, pkg/, cmd/)
• T002 Initialize Go project with Fiber + GORM + Viper + Zap + Asynq dependencies
• T003 [P] Configure linting (golangci-lint) and formatting tools (gofmt/goimports)
• T004 [P] Setup unified error codes in pkg/errors/
• T005 [P] Setup unified API response in pkg/response/
• T006 [P] Setup constants management in pkg/constants/ (business constants and Redis key functions)

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core infrastructure that MUST be complete before ANY user story can be implemented

⚠️ CRITICAL: No user story work can begin until this phase is complete

Foundational tasks for 君鸿卡管系统 tech stack:

• T007 Setup PostgreSQL database connection via GORM with connection pool (MaxOpenConns=25, MaxIdleConns=10)
• T008 Setup Redis connection with connection pool (PoolSize=10, MinIdleConns=5)
• T009 [P] Setup database migrations framework (golang-migrate or GORM AutoMigrate)
• T010 [P] Implement Fiber routing structure in internal/router/
• T011 [P] Implement Fiber middleware (authentication, logging, recovery, validation) in internal/handler/middleware/
• T012 [P] Setup Zap logger with Lumberjack rotation in pkg/logger/
• T013 [P] Setup Viper configuration management in pkg/config/
• T014 [P] Setup Asynq task queue client and server in pkg/queue/
• T015 [P] Setup Validator integration in pkg/validator/
• T016 Create base Store structure with transaction support in internal/store/
• T017 Create base Service structure with dependency injection in internal/service/
• T018 Setup sonic JSON as default serializer for Fiber

Checkpoint: Foundation ready - user story implementation can now begin in parallel

---

Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP

Goal: [Brief description of what this story delivers]

Independent Test: [How to verify this story works on its own]

Tests for User Story 1 (REQUIRED per Constitution - Testing Standards) ⚠️

NOTE: Write these tests FIRST, ensure they FAIL before implementation

• T020 [P] [US1] Unit tests for Service layer business logic in internal/service/[service]_test.go
• T021 [P] [US1] Integration tests for API endpoints in internal/handler/[handler]_test.go
• T022 [P] [US1] Transaction rollback tests for Store layer in internal/store/[store]_test.go

Implementation for User Story 1

• T023 [P] [US1] Create [Entity1] model with GORM tags in internal/model/[entity1].go
• T024 [P] [US1] Create [Entity2] model with GORM tags in internal/model/[entity2].go
• T025 [P] [US1] Create DTOs and request/response structs in internal/model/dto/[feature].go
• T026 [US1] Implement Store methods with GORM in internal/store/postgres/[store].go (depends on T023, T024)
• T027 [US1] Implement Service business logic in internal/service/[service].go (depends on T026)
• T028 [US1] Implement Fiber Handler in internal/handler/[handler].go (depends on T027)
• T029 [US1] Register routes in internal/router/router.go
• T030 [US1] Add validation rules using Validator in Handler
• T031 [US1] Add unified error handling using pkg/errors/ and pkg/response/
• T032 [US1] Add Zap logging with structured fields
• T033 [US1] Add database indexes for queries (if needed)
• T034 [US1] Create Asynq tasks for async operations (if needed) in internal/task/[task].go

Checkpoint: At this point, User Story 1 should be fully functional and testable independently

---

Phase 4: User Story 2 - [Title] (Priority: P2)

Goal: [Brief description of what this story delivers]

Independent Test: [How to verify this story works on its own]

Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️

• T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
• T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py

Implementation for User Story 2

• T020 [P] [US2] Create [Entity] model in src/models/[entity].py
• T021 [US2] Implement [Service] in src/services/[service].py
• T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
• T023 [US2] Integrate with User Story 1 components (if needed)

Checkpoint: At this point, User Stories 1 AND 2 should both work independently

---

Phase 5: User Story 3 - [Title] (Priority: P3)

Goal: [Brief description of what this story delivers]

Independent Test: [How to verify this story works on its own]

Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️

• T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
• T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py

Implementation for User Story 3

• T026 [P] [US3] Create [Entity] model in src/models/[entity].py
• T027 [US3] Implement [Service] in src/services/[service].py
• T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py

Checkpoint: All user stories should now be independently functional

---

[Add more user story phases as needed, following the same pattern]

---

Phase N: Polish & Quality Gates

Purpose: Improvements that affect multiple user stories and final quality checks

Documentation (Constitution Principle VII - REQUIRED)

• TXXX [P] Create feature summary doc in docs/{feature-id}/功能总结.md (Chinese filename and content)
• TXXX [P] Create usage guide in docs/{feature-id}/使用指南.md (Chinese filename and content)
• TXXX [P] Create architecture doc in docs/{feature-id}/架构说明.md (optional, Chinese filename and content)
• TXXX Update README.md with brief feature description (2-3 sentences in Chinese)

Code Quality

• TXXX Code cleanup and refactoring
• TXXX Performance optimization and load testing (verify P95 < 200ms, P99 < 500ms)
• TXXX [P] Additional unit tests to reach 70%+ coverage (90%+ for core business)
• TXXX Security audit (SQL injection, XSS, command injection prevention)
• TXXX Run quickstart.md validation
• TXXX Quality Gate: Run go test ./... (all tests pass)
• TXXX Quality Gate: Run gofmt -l . (no formatting issues)
• TXXX Quality Gate: Run go vet ./... (no issues)
• TXXX Quality Gate: Run golangci-lint run (no issues)
• TXXX Quality Gate: Verify test coverage with go test -cover ./...
• TXXX Quality Gate: Check no TODO/FIXME remains (or documented in issues)
• TXXX Quality Gate: Verify database migrations work correctly
• TXXX Quality Gate: Verify API documentation updated (if API changes)
• TXXX Quality Gate: Verify no hardcoded constants or Redis keys (all use pkg/constants/)
• TXXX Quality Gate: Verify no duplicate hardcoded values (3+ identical literals must be constants)
• TXXX Quality Gate: Verify defined constants are used (no duplicate hardcoding of constant values)
• TXXX Quality Gate: Verify code comments use Chinese (implementation comments in Chinese)
• TXXX Quality Gate: Verify log messages use Chinese (logger Info/Warn/Error/Debug in Chinese)
• TXXX Quality Gate: Verify error messages support Chinese (user-facing errors have Chinese text)
• TXXX Quality Gate: Verify no Java-style anti-patterns (no getter/setter, no I-prefix, no Impl-suffix)
• TXXX Quality Gate: Verify Go naming conventions (UserID not userId, HTTPServer not HttpServer)
• TXXX Quality Gate: Verify error handling is explicit (no panic/recover abuse)
• TXXX Quality Gate: Verify uses goroutines/channels (not thread pool patterns)
• TXXX Quality Gate: Verify feature summary docs created in docs/{feature-id}/ with Chinese filenames
• TXXX Quality Gate: Verify summary doc content uses Chinese
• TXXX Quality Gate: Verify README.md updated with brief feature description (2-3 sentences)
• TXXX Quality Gate: Verify ALL HTTP requests logged to access.log (no exceptions)
• TXXX Quality Gate: Verify access log includes request parameters (query + body, limited to 50KB)
• TXXX Quality Gate: Verify access log includes response parameters (body, limited to 50KB)
• TXXX Quality Gate: Verify logging via centralized Logger middleware (pkg/logger/Middleware())
• TXXX Quality Gate: Verify no middleware bypasses logging (test auth failures, rate limits, etc.)
• TXXX Quality Gate: Verify access log has all required fields (method, path, query, status, duration_ms, request_id, ip, user_agent, user_id, request_body, response_body)
• TXXX Quality Gate: Verify all API errors use unified JSON format (pkg/errors/ ErrorHandler)
• TXXX Quality Gate: Verify Handler layer returns errors (no manual c.Status().JSON() for errors)
• TXXX Quality Gate: Verify business errors use pkg/errors.New() or pkg/errors.Wrap()
• TXXX Quality Gate: Verify all error codes defined in pkg/errors/codes.go
• TXXX Quality Gate: Verify Recover middleware catches all panics
• TXXX Quality Gate: Verify error logs include request context (Request ID, path, method)
• TXXX Quality Gate: Verify 5xx errors auto-sanitized (no sensitive info exposed)
• TXXX Quality Gate: Verify no panic in business code (search for panic() calls)
• TXXX Quality Gate: Verify error codes follow classification (0=success, 1xxx=4xx, 2xxx=5xx)
• TXXX Quality Gate: Verify Recover middleware registered first in chain
• TXXX Quality Gate: Test panic recovery logs complete stack trace
• TXXX Quality Gate: Test single request panic doesn't affect other requests

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies - can start immediately
• Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
• User Stories (Phase 3+): All depend on Foundational phase completion
  • User stories can then proceed in parallel (if staffed)
  • Or sequentially in priority order (P1 → P2 → P3)
• Polish (Final Phase): Depends on all desired user stories being complete

User Story Dependencies

• User Story 1 (P1): Can start after Foundational (Phase 2) - No dependencies on other stories
• User Story 2 (P2): Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
• User Story 3 (P3): Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable

Within Each User Story

• Tests (if included) MUST be written and FAIL before implementation
• Models before services
• Services before endpoints
• Core implementation before integration
• Story complete before moving to next priority

Parallel Opportunities

• All Setup tasks marked [P] can run in parallel
• All Foundational tasks marked [P] can run in parallel (within Phase 2)
• Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
• All tests for a user story marked [P] can run in parallel
• Models within a story marked [P] can run in parallel
• Different user stories can be worked on in parallel by different team members

---

Parallel Example: User Story 1

# Launch all tests for User Story 1 together (if tests requested):
Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
Task: "Integration test for [user journey] in tests/integration/test_[name].py"

# Launch all models for User Story 1 together:
Task: "Create [Entity1] model in src/models/[entity1].py"
Task: "Create [Entity2] model in src/models/[entity2].py"

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
3. Complete Phase 3: User Story 1
4. STOP and VALIDATE: Test User Story 1 independently
5. Deploy/demo if ready

Incremental Delivery

1. Complete Setup + Foundational → Foundation ready
2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
3. Add User Story 2 → Test independently → Deploy/Demo
4. Add User Story 3 → Test independently → Deploy/Demo
5. Each story adds value without breaking previous stories

Parallel Team Strategy

With multiple developers:

1. Team completes Setup + Foundational together
2. Once Foundational is done:
   • Developer A: User Story 1
   • Developer B: User Story 2
   • Developer C: User Story 3
3. Stories complete and integrate independently

---

Notes

• [P] tasks = different files, no dependencies
• [Story] label maps task to specific user story for traceability
• Each user story should be independently completable and testable
• Verify tests fail before implementing
• Commit after each task or logical group
• Stop at any checkpoint to validate story independently
• Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence