feat: 实现统一错误处理系统 (003-error-handling)

- 新增统一错误码定义和管理 (pkg/errors/codes.go)
- 新增全局错误处理器和中间件 (pkg/errors/handler.go, internal/middleware/error_handler.go)
- 新增错误上下文管理 (pkg/errors/context.go)
- 增强 Panic 恢复中间件 (internal/middleware/recover.go)
- 新增完整的单元测试和集成测试
- 新增功能文档 (docs/003-error-handling/)
- 新增功能规范 (specs/003-error-handling/)
- 更新 CLAUDE.md 和 README.md

.specify/templates/plan-template.md

@@ -117,6 +117,22 @@
 - [ ] 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
 
+**Error Handling Standards** (Constitution Principle X):
+- [ ] All API error responses use unified JSON format (via pkg/errors/ global ErrorHandler)
+- [ ] Handler layer errors return error (not manual JSON responses)
+- [ ] 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 and 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)
+- [ ] No manual error response construction in Handler (c.Status().JSON())
+- [ ] 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
+
 ## Project Structure
 
 ### Documentation (this feature)

.specify/templates/spec-template.md

@@ -146,6 +146,21 @@
 - [ ] 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

.specify/templates/tasks-template.md

@@ -207,6 +207,18 @@ Foundational tasks for 君鸿卡管系统 tech stack:
 - [ ] TXXX Quality Gate: Verify logging via centralized Logger middleware (pkg/logger/Middleware())
 - [ ] TXXX Quality Gate: Verify no middleware bypasses logging (test auth failures, rate limits, etc.)
 - [ ] TXXX Quality Gate: Verify access log has all required fields (method, path, query, status, duration_ms, request_id, ip, user_agent, user_id, request_body, response_body)
+- [ ] TXXX Quality Gate: Verify all API errors use unified JSON format (pkg/errors/ ErrorHandler)
+- [ ] TXXX Quality Gate: Verify Handler layer returns errors (no manual c.Status().JSON() for errors)
+- [ ] TXXX Quality Gate: Verify business errors use pkg/errors.New() or pkg/errors.Wrap()
+- [ ] TXXX Quality Gate: Verify all error codes defined in pkg/errors/codes.go
+- [ ] TXXX Quality Gate: Verify Recover middleware catches all panics
+- [ ] TXXX Quality Gate: Verify error logs include request context (Request ID, path, method)
+- [ ] TXXX Quality Gate: Verify 5xx errors auto-sanitized (no sensitive info exposed)
+- [ ] TXXX Quality Gate: Verify no panic in business code (search for panic() calls)
+- [ ] TXXX Quality Gate: Verify error codes follow classification (0=success, 1xxx=4xx, 2xxx=5xx)
+- [ ] TXXX Quality Gate: Verify Recover middleware registered first in chain
+- [ ] TXXX Quality Gate: Test panic recovery logs complete stack trace
+- [ ] TXXX Quality Gate: Test single request panic doesn't affect other requests
 
 ---