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