junhong_cmp_fiber/specs/002-gorm-postgres-asynq/plan.md

Implementation Plan: 数据持久化与异步任务处理集成

Branch: 002-gorm-postgres-asynq | Date: 2025-11-13 | Spec: spec.md Input: Feature specification from /specs/002-gorm-postgres-asynq/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

本功能集成 GORM + PostgreSQL + Asynq，实现可靠的数据持久化和异步任务处理能力。系统支持标准 CRUD 操作、事务处理、数据库迁移管理、异步任务队列（支持重试、优先级、定时任务）、健康检查和优雅关闭。技术选型基于项目 Constitution 要求，使用 golang-migrate 管理数据库迁移（不使用 GORM AutoMigrate），通过 Redis 持久化任务状态确保故障恢复，所有任务处理逻辑设计为幂等操作。

Technical Context

Language/Version: Go 1.25.4
Primary Dependencies: Fiber (HTTP 框架), GORM (ORM), Asynq (任务队列), Viper (配置), Zap (日志), golang-migrate (数据库迁移)
Storage: PostgreSQL 14+（主数据库）, Redis 6.0+（任务队列存储）
Testing: Go 标准 testing 框架, testcontainers (集成测试)
Target Platform: Linux/macOS 服务器
Project Type: Backend API + Worker 服务（双进程架构）
Performance Goals: API 响应时间 P95 < 200ms, 数据库查询 < 50ms, 任务队列处理速率 100 tasks/s
Constraints: 数据库连接池最大 25 连接, Worker 默认并发 10, 任务超时 10 分钟, 慢查询阈值 100ms
Scale/Scope: 支持 1000+ 并发连接, 10000+ 待处理任务队列, 水平扩展 Worker 进程

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Tech Stack Adherence:

• Feature uses Fiber + GORM + Viper + Zap + Lumberjack.v2 + Validator + sonic JSON + Asynq + PostgreSQL
• No native calls bypass framework (no database/sql, net/http, encoding/json direct use)
• All HTTP operations use Fiber framework
• All database operations use GORM
• All async tasks use Asynq
• Uses Go official toolchain: go fmt, go vet, golangci-lint
• Uses Go Modules for dependency management

Code Quality Standards:

• Follows Handler → Service → Store → Model architecture
• Handler layer only handles HTTP, no business logic
• Service layer contains business logic with cross-module support
• Store layer manages all data access with transaction support
• Uses dependency injection via struct fields (not constructor patterns)
• Unified error codes in pkg/errors/
• Unified API responses via pkg/response/
• All constants defined in pkg/constants/
• All Redis keys managed via key generation functions (no hardcoded strings)
• No hardcoded magic numbers or strings (3+ occurrences must be constants)
• Defined constants are used instead of hardcoding duplicate values
• Code comments prefer Chinese for readability (implementation comments in Chinese)
• Log messages use Chinese (Info/Warn/Error/Debug logs in Chinese)
• Error messages support Chinese (user-facing errors have Chinese messages)
• All exported functions/types have Go-style doc comments
• Code formatted with gofmt
• Follows Effective Go and Go Code Review Comments

Documentation Standards (Constitution Principle VII):

• Feature summary docs placed in docs/{feature-id}/ mirroring specs/{feature-id}/
• Summary doc filenames use Chinese (功能总结.md, 使用指南.md, etc.)
• Summary doc content uses Chinese
• README.md updated with brief Chinese summary (2-3 sentences)
• Documentation is concise for first-time contributors

Go Idiomatic Design:

• Package structure is flat (max 2-3 levels), organized by feature
• Interfaces are small (1-3 methods), defined at use site
• No Java-style patterns: no I-prefix, no Impl-suffix, no getters/setters
• Error handling is explicit (return errors, no panic/recover abuse)
• Uses composition over inheritance
• Uses goroutines and channels (not thread pools)
• Uses context.Context for cancellation and timeouts
• Naming follows Go conventions: short receivers, consistent abbreviations (URL, ID, HTTP)
• No Hungarian notation or type prefixes
• Simple constructors (New/NewXxx), no Builder pattern unless necessary

Testing Standards:

• Unit tests for all core business logic (Service layer)
• Integration tests for all API endpoints
• Tests use Go standard testing framework
• Test files named *_test.go in same directory
• Test functions use Test prefix, benchmarks use Benchmark prefix
• Table-driven tests for multiple test cases
• Test helpers marked with t.Helper()
• Tests are independent (no external service dependencies)
• Target coverage: 70%+ overall, 90%+ for core business

User Experience Consistency:

• All APIs use unified JSON response format
• Error responses include clear error codes and bilingual messages
• RESTful design principles followed
• Unified pagination parameters (page, page_size, total)
• Time fields use ISO 8601 format (RFC3339)
• Currency amounts use integers (cents) to avoid float precision issues

Performance Requirements:

• API response time (P95) < 200ms, (P99) < 500ms
• Batch operations use bulk queries/inserts
• All database queries have appropriate indexes
• List queries implement pagination (default 20, max 100)
• Non-realtime operations use async tasks
• Database and Redis connection pools properly configured
• Uses goroutines/channels for concurrency (not thread pools)
• Uses context.Context for timeout control
• Uses sync.Pool for frequently allocated objects

Access Logging Standards (Constitution Principle VIII):

• ALL HTTP requests logged to access.log without exception
• Request parameters (query + body) logged (limited to 50KB)
• Response parameters (body) logged (limited to 50KB)
• Logging happens via centralized Logger middleware (pkg/logger/Middleware())
• No middleware bypasses access logging (including auth failures, rate limits)
• Body truncation indicates "... (truncated)" when over 50KB limit
• Access log includes all required fields: method, path, query, status, duration_ms, request_id, ip, user_agent, user_id, request_body, response_body

Project Structure

Documentation (this feature)

设计文档（specs/ 目录）：开发前的规划和设计

specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

总结文档（docs/ 目录）：开发完成后的总结和使用指南（遵循 Constitution Principle VII）

docs/[###-feature]/
├── 功能总结.md          # 功能概述、核心实现、技术要点（MUST 使用中文命名和内容）
├── 使用指南.md          # 如何使用该功能的详细说明（MUST 使用中文命名和内容）
└── 架构说明.md          # 架构设计和技术决策（可选，MUST 使用中文命名和内容）

README.md 更新：每次完成功能后 MUST 在 README.md 添加简短描述（2-3 句话，中文）

Source Code (repository root)

# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/

tests/
├── contract/
├── integration/
└── unit/

# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
backend/
├── src/
│   ├── models/
│   ├── services/
│   └── api/
└── tests/

frontend/
├── src/
│   ├── components/
│   ├── pages/
│   └── services/
└── tests/

# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
api/
└── [same as backend above]

ios/ or android/
└── [platform-specific structure: feature modules, UI flows, platform tests]

Structure Decision: 采用 Backend API + Worker 双进程架构。项目已存在完整的 Fiber 后端结构（cmd/api/, internal/handler/, internal/service/, internal/store/, internal/model/），本次功能在此基础上添加：

• cmd/worker/: Worker 进程入口
• pkg/database/: PostgreSQL 连接初始化
• pkg/queue/: Asynq 客户端和服务端封装
• internal/task/: 异步任务处理器
• internal/store/postgres/: 数据访问层（基于 GORM）
• migrations/: 数据库迁移文件（SQL）

现有目录结构已符合 Constitution 分层架构要求（Handler → Service → Store → Model），本功能遵循该架构。

Complexity Tracking

无宪法违规 - 本功能完全符合项目 Constitution 要求，无需例外说明。