huang
2b1754728f
新增 Principle VII: Documentation Standards（文档规范）
主要变更：
- 规定功能总结文档必须放在 docs/{feature-id}/ 目录，对应 specs/{feature-id}/
- 要求总结文档使用中文命名（功能总结.md、使用指南.md、架构说明.md）
- 要求总结文档内容使用中文编写，方便中文团队阅读
- 强制要求每次完成功能后更新 README.md，添加 2-3 句简短描述
- 目标：让首次接触项目的开发者能快速了解功能
模板同步更新：
- plan-template.md: 添加文档结构说明和 Documentation Standards 检查项
- tasks-template.md: 新增文档任务模板和文档相关质量检查项
版本升级理由：
MINOR 版本升级（2.1.1 → 2.2.0），因为新增了影响开发工作流程的强制性原则，
要求所有功能完成后必须创建中文总结文档并更新 README.md
297 lines
13 KiB
Markdown
297 lines
13 KiB
Markdown
---
|
|
|
|
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
|
|
|
|
<!--
|
|
============================================================================
|
|
IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
|
|
|
|
The /speckit.tasks command MUST replace these with actual tasks based on:
|
|
- User stories from spec.md (with their priorities P1, P2, P3...)
|
|
- Feature requirements from plan.md
|
|
- Entities from data-model.md
|
|
- Endpoints from contracts/
|
|
|
|
Tasks MUST be organized by user story so each story can be:
|
|
- Implemented independently
|
|
- Tested independently
|
|
- Delivered as an MVP increment
|
|
|
|
DO NOT keep these sample tasks in the generated tasks.md file.
|
|
============================================================================
|
|
-->
|
|
|
|
## 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)
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```bash
|
|
# 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
|