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

Feature Specification: [FEATURE NAME]

Feature Branch: [###-feature-name]
Created: [DATE]
Status: Draft
Input: User description: "$ARGUMENTS"

User Scenarios & Testing (mandatory)

User Story 1 - [Brief Title] (Priority: P1)

[Describe this user journey in plain language]

Why this priority: [Explain the value and why it has this priority level]

Independent Test: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]

Acceptance Scenarios:

1. Given [initial state], When [action], Then [expected outcome]
2. Given [initial state], When [action], Then [expected outcome]

---

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

[Describe this user journey in plain language]

Why this priority: [Explain the value and why it has this priority level]

Independent Test: [Describe how this can be tested independently]

Acceptance Scenarios:

1. Given [initial state], When [action], Then [expected outcome]

---

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

[Describe this user journey in plain language]

Why this priority: [Explain the value and why it has this priority level]

Independent Test: [Describe how this can be tested independently]

Acceptance Scenarios:

1. Given [initial state], When [action], Then [expected outcome]

---

[Add more user stories as needed, each with an assigned priority]

Edge Cases

• What happens when [boundary condition]?
• How does system handle [error scenario]?

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST [specific capability, e.g., "allow users to create accounts"]
• FR-002: System MUST [specific capability, e.g., "validate email addresses"]
• FR-003: Users MUST be able to [key interaction, e.g., "reset their password"]
• FR-004: System MUST [data requirement, e.g., "persist user preferences"]
• FR-005: System MUST [behavior, e.g., "log all security events"]

Example of marking unclear requirements:

• FR-006: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
• FR-007: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]

Technical Requirements (Constitution-Driven)

Tech Stack Compliance:

• All HTTP operations use Fiber framework (no net/http shortcuts)
• All database operations use GORM (no database/sql direct calls)
• All JSON operations use sonic (no encoding/json usage)
• All async tasks use Asynq
• All logging uses Zap + Lumberjack.v2
• All configuration uses Viper
• Uses Go official toolchain: go fmt, go vet, golangci-lint

Architecture Requirements:

• Implementation follows Handler → Service → Store → Model layers
• Dependencies injected via struct fields (not constructor patterns)
• Unified error codes defined in pkg/errors/
• Unified API responses via pkg/response/
• All constants defined in pkg/constants/ (no magic numbers/strings)
• No hardcoded values: 3+ identical literals must become constants
• Defined constants must be used (no duplicate hardcoding)
• Code comments prefer Chinese (implementation comments in Chinese)
• Log messages use Chinese (logger.Info/Warn/Error/Debug in Chinese)
• Error messages support Chinese (user-facing errors have Chinese text)
• All Redis keys managed via pkg/constants/ key generation functions
• Package structure is flat, organized by feature (not by layer)

Go Idiomatic Design Requirements:

• No Java-style patterns: no getter/setter methods, no I-prefix interfaces, no Impl-suffix
• Interfaces are small (1-3 methods), defined where used
• Error handling is explicit (return errors, not panic)
• Uses composition (struct embedding) not inheritance
• Uses goroutines and channels for concurrency
• Naming follows Go conventions: UserID not userId, HTTPServer not HttpServer
• No Hungarian notation or type prefixes
• Simple and direct code structure

API Design Requirements:

• All APIs follow RESTful principles
• All responses use unified JSON format with code/message/data/timestamp
• All error messages include error codes and bilingual descriptions
• All pagination uses standard parameters (page, page_size, total)
• All time fields use ISO 8601 format (RFC3339)
• All currency amounts use integers (cents)

Performance Requirements:

• API response time (P95) < 200ms
• Database queries < 50ms
• Batch operations use bulk queries
• List queries implement pagination (default 20, max 100)
• Non-realtime operations delegated to async tasks
• Uses context.Context for timeouts and cancellation

Error Handling Requirements (Constitution Principle X):

• All API errors use unified JSON format (via pkg/errors/ global ErrorHandler)
• Handler layer returns errors (no manual c.Status().JSON() for errors)
• Business errors use pkg/errors.New() or pkg/errors.Wrap() with error codes
• All error codes defined in pkg/errors/codes.go
• All panics caught by Recover middleware, converted to 500 responses
• Error logs include complete request context (Request ID, path, method, params)
• 5xx server errors auto-sanitized (generic message to client, full error in logs)
• 4xx client errors may return specific business messages
• No panic in business code (except unrecoverable programming errors)
• Error codes follow classification: 0=success, 1xxx=client (4xx), 2xxx=server (5xx)
• Recover middleware registered first in middleware chain
• Panic recovery logs complete stack trace
• Single request panic does not affect other requests

Testing Requirements:

• Unit tests for all Service layer business logic
• Integration tests for all API endpoints
• Tests use Go standard testing framework with *_test.go files
• Table-driven tests for multiple test cases
• Tests are independent and use mocks/testcontainers
• Target coverage: 70%+ overall, 90%+ for core business logic

Key Entities (include if feature involves data)

• [Entity 1]: [What it represents, key attributes without implementation]
• [Entity 2]: [What it represents, relationships to other entities]

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
• SC-002: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
• SC-003: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
• SC-004: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]