feat: OpenAPI 契约对齐与框架优化

主要变更：
1. OpenAPI 文档契约对齐
   - 统一错误响应字段名为 msg（非 message）
   - 规范 envelope 响应结构（code, msg, data, timestamp）
   - 个人客户路由纳入文档体系（使用 Register 机制）
   - 新增 BuildDocHandlers() 统一管理 handler 构造
   - 确保文档生成的幂等性

2. Service 层错误处理统一
   - 全面替换 fmt.Errorf 为 errors.New/Wrap
   - 统一错误码使用规范
   - Handler 层参数校验不泄露底层细节
   - 新增错误码验证集成测试

3. 代码质量提升
   - 删除未使用的 Task handler 和路由
   - 新增代码规范检查脚本（check-service-errors.sh）
   - 新增注释路径一致性检查（check-comment-paths.sh）
   - 更新 API 文档生成指南

4. OpenSpec 归档
   - 归档 openapi-contract-alignment 变更（63 tasks）
   - 归档 service-error-unify-core 变更
   - 归档 service-error-unify-support 变更
   - 归档 code-cleanup-docs-update 变更
   - 归档 handler-validation-security 变更
   - 同步 delta specs 到主规范文件

影响范围：
- pkg/openapi: 新增 handlers.go，优化 generator.go
- internal/service/*: 48 个 service 文件错误处理统一
- internal/handler/admin: 优化参数校验错误提示
- internal/routes: 个人客户路由改造，删除 task 路由
- scripts: 新增 3 个代码检查脚本
- docs: 更新 OpenAPI 文档（15750+ 行）
- openspec/specs: 同步 3 个主规范文件

破坏性变更：无
向后兼容：是

docs/api-documentation-guide.md

@@ -355,6 +355,65 @@ type ShopPageResult struct {
 }
 ```
 
+### 7. 响应 Envelope 格式
+
+**所有 API 响应都会被自动包裹在统一的 envelope 结构中。**
+
+OpenAPI 文档会自动为成功响应生成以下结构:
+
+```yaml
+responses:
+  "200":
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            code:
+              type: integer
+              example: 0
+              description: 响应码
+            msg:
+              type: string
+              example: success
+              description: 响应消息
+            data:
+              $ref: '#/components/schemas/YourDTO'  # 你定义的 DTO
+            timestamp:
+              type: string
+              format: date-time
+              description: 时间戳
+```
+
+**注意事项**:
+- DTO 中只需定义 `data` 字段的内容，无需定义 envelope 字段
+- 错误响应使用 `msg` 字段（不是 `message`）
+- 删除操作等无返回数据的接口，`data` 字段为 `null`
+
+**示例**:
+
+```go
+// DTO 定义（只定义 data 部分）
+type LoginResponse struct {
+    Token    string `json:"token" description:"访问令牌"`
+    Customer *PersonalCustomerDTO `json:"customer" description:"客户信息"`
+}
+
+// 实际 API 响应（自动包裹 envelope）
+{
+    "code": 0,
+    "msg": "success",
+    "data": {
+        "token": "eyJhbGciOiJI...",
+        "customer": {
+            "id": 1,
+            "phone": "13800000000"
+        }
+    },
+    "timestamp": "2026-01-30T10:00:00Z"
+}
+```
+
 ---
 
 ## 文档生成流程
@@ -544,7 +603,68 @@ Register(router, doc, basePath, "PUT", "/:id", handler.Update, RouteSpec{
    grep "/api/admin/xxx" docs/admin-openapi.yaml
    ```
 
-### Q5: 如何调试文档生成？
+### Q5: 如何为个人客户路由（/api/c/v1）添加文档？
+
+个人客户路由需要在独立的路由文件中注册，并使用 `Register()` 函数以纳入 OpenAPI 文档。
+
+**示例**：`internal/routes/personal.go`
+
+```go
+func RegisterPersonalCustomerRoutes(router fiber.Router, doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers, personalAuthMiddleware *middleware.PersonalAuthMiddleware) {
+    // 公开路由（不需要认证）
+    publicGroup := router.Group("")
+    
+    Register(publicGroup, doc, basePath, "POST", "/login/send-code", handlers.PersonalCustomer.SendCode, RouteSpec{
+        Summary:     "发送验证码",
+        Description: "向指定手机号发送登录验证码",
+        Tags:        []string{"个人客户 - 认证"},
+        Auth:        false,
+        Input:       &apphandler.SendCodeRequest{},
+        Output:      nil,
+    })
+
+    Register(publicGroup, doc, basePath, "POST", "/login", handlers.PersonalCustomer.Login, RouteSpec{
+        Summary:     "手机号登录",
+        Description: "使用手机号和验证码登录",
+        Tags:        []string{"个人客户 - 认证"},
+        Auth:        false,
+        Input:       &apphandler.LoginRequest{},
+        Output:      &apphandler.LoginResponse{},
+    })
+
+    // 需要认证的路由
+    authGroup := router.Group("")
+    authGroup.Use(personalAuthMiddleware.Authenticate())
+
+    Register(authGroup, doc, basePath, "GET", "/profile", handlers.PersonalCustomer.GetProfile, RouteSpec{
+        Summary:     "获取个人资料",
+        Description: "获取当前登录客户的个人资料",
+        Tags:        []string{"个人客户 - 账户"},
+        Auth:        true,
+        Input:       nil,
+        Output:      &apphandler.PersonalCustomerDTO{},
+    })
+}
+```
+
+**在 `routes.go` 中调用**：
+
+```go
+func RegisterRoutesWithDoc(app *fiber.App, handlers *bootstrap.Handlers, middlewares *bootstrap.Middlewares, doc *openapi.Generator) {
+    // ... 其他路由
+    
+    // 个人客户路由 (挂载在 /api/c/v1)
+    personalGroup := app.Group("/api/c/v1")
+    RegisterPersonalCustomerRoutes(personalGroup, doc, "/api/c/v1", handlers, middlewares.PersonalAuth)
+}
+```
+
+**关键点**：
+- basePath 必须是完整路径（如 `/api/c/v1`）
+- 需要传入 `personalAuthMiddleware` 以支持认证路由组
+- Tags 使用中文并包含模块前缀（如 "个人客户 - 认证"）
+
+### Q6: 如何调试文档生成？
 
 ```bash
 # 1. 查看生成的 YAML 文件