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