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)*

<!--
  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
  you should still have a viable MVP (Minimum Viable Product) that delivers value.
  
  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
  Think of each story as a standalone slice of functionality that can be:
  - Developed independently
  - Tested independently
  - Deployed independently
  - Demonstrated to users independently
-->

### 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

<!--
  ACTION REQUIRED: The content in this section represents placeholders.
  Fill them out with the right edge cases.
-->

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

## Requirements *(mandatory)*

<!--
  ACTION REQUIRED: The content in this section represents placeholders.
  Fill them out with the right functional requirements.
-->

### 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)*

<!--
  ACTION REQUIRED: Define measurable success criteria.
  These must be technology-agnostic and measurable.
-->

### 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%"]