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 个主规范文件

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

openspec/changes/archive/2026-01-30-code-cleanup-docs-update/proposal.md

@@ -0,0 +1,191 @@
+# Change: 代码清理和规范文档更新
+
+## Why
+
+清理临时代码和不一致的注释，更新项目规范文档，完善 CI 检查，确保代码质量和规范一致性。
+
+**当前问题**：
+
+1. **任务模块占位代码**：
+   - `internal/routes/task.go` 包含占位路由
+   - `internal/handler/admin/task.go` 未接入真实业务
+   - 存在鉴权不一致风险
+
+2. **注释路径不一致**：
+   - Handler 层注释中残留 `/api/v1/...` 路径
+   - 真实路由为 `/api/admin`、`/api/h5`、`/api/c/v1`
+
+3. **规范文档缺失**：
+   - `openspec/specs/error-handling/spec.md` 缺少"错误报错规范"
+   - `AGENTS.md` 未包含错误处理检查清单
+   - `docs/003-error-handling/使用指南.md` 缺少实际案例
+
+4. **CI 检查不完善**：
+   - 无自动检查 Service 层禁止 `fmt.Errorf`
+   - 无自动检查注释路径一致性
+
+## What Changes
+
+### 5.1 移除任务模块占位代码
+
+删除以下文件和引用：
+
+```bash
+# 删除文件
+rm internal/routes/task.go
+rm internal/handler/admin/task.go
+
+# 更新 routes.go
+# 移除 registerTaskRoutes(...) 调用
+```
+
+### 5.2 清理注释一致性
+
+扫描并修复 Handler 层注释：
+
+```bash
+# 查找残留的 /api/v1 注释
+grep -r "/api/v1" internal/handler/ | grep -v "_test.go"
+
+# 修复为真实路径
+/api/v1/users → /api/admin/users
+/api/v1/shops → /api/admin/shops
+```
+
+### 5.3 更新规范文档
+
+#### 错误处理规范
+- 更新 `openspec/specs/error-handling/spec.md`
+- 补充 Purpose 说明
+- 新增"错误报错规范"条款：
+  - Handler 层禁止直接返回底层错误
+  - Service 层禁止使用 `fmt.Errorf` 对外返回
+  - 参数校验失败统一返回 `CodeInvalidParam`
+
+#### 开发规范
+- 更新 `AGENTS.md`
+- 增加"错误报错规范"摘要
+- 补充 Code Review 检查清单
+
+#### 使用指南
+- 更新 `docs/003-error-handling/使用指南.md`
+- 补充 Service 层错误处理实际案例
+- 补充 Handler 层参数校验案例
+- 补充单元测试示例
+
+### 5.4 CI 检查增强
+
+创建脚本检查规范遵守：
+
+```bash
+#!/bin/bash
+# scripts/check-service-errors.sh
+
+FILES=$(find internal/service -name "*.go" -type f)
+VIOLATIONS=$(grep -n "fmt\.Errorf" $FILES | grep -v "// whitelist:")
+
+if [ -n "$VIOLATIONS" ]; then
+    echo "❌ 发现 Service 层使用 fmt.Errorf："
+    echo "$VIOLATIONS"
+    exit 1
+fi
+
+echo "✅ Service 层错误处理检查通过"
+```
+
+## Decisions
+
+### 任务模块处理
+
+- 完全移除占位代码（不保留注释或 TODO）
+- 如需任务功能，后续单独设计实现
+
+### 注释清理规则
+
+- 注释路径必须与真实路由一致
+- 不使用已弃用的路径（如 `/api/v1`）
+- API 文档路径以 OpenAPI 生成为准
+
+### CI 检查范围
+
+- Service 层：禁止 `fmt.Errorf` 对外返回
+- Handler 层：建议检查但不强制（可选）
+- 测试文件：跳过检查
+
+## Impact
+
+### Breaking Changes
+
+无（仅清理未使用代码）
+
+### Documentation Updates
+
+- 错误处理规范文档完善
+- 开发规范检查清单更新
+- 使用指南补充实际案例
+
+### CI Integration
+
+可选集成到 GitHub Actions：
+
+```yaml
+# .github/workflows/lint.yml
+- name: Check Service Layer Errors
+  run: bash scripts/check-service-errors.sh
+```
+
+## Affected Specs
+
+- **UPDATE**: `openspec/specs/error-handling/spec.md`
+- **UPDATE**: `AGENTS.md`
+- **UPDATE**: `docs/003-error-handling/使用指南.md`
+
+## Verification Checklist
+
+### 代码清理验证
+```bash
+# 确认文件已删除
+ls internal/routes/task.go  # 应返回 No such file
+ls internal/handler/admin/task.go  # 应返回 No such file
+
+# 确认引用已移除
+grep -r "registerTaskRoutes" internal/  # 应无结果
+grep -r "TaskHandler" internal/  # 应无结果（除测试文件）
+```
+
+### 注释清理验证
+```bash
+# 确认无残留 /api/v1 注释
+grep -r "/api/v1" internal/handler/ | grep -v "_test.go"  # 应无结果
+```
+
+### CI 检查验证
+```bash
+# 运行检查脚本
+bash scripts/check-service-errors.sh  # 应返回 ✅
+
+# 测试脚本能检测到违规
+echo 'return fmt.Errorf("test")' >> internal/service/test.go
+bash scripts/check-service-errors.sh  # 应返回 ❌
+rm internal/service/test.go
+```
+
+### 文档完整性检查
+```bash
+# 确认文档已更新
+grep "错误报错规范" openspec/specs/error-handling/spec.md
+grep "错误报错规范" AGENTS.md
+grep "Service 层错误处理" docs/003-error-handling/使用指南.md
+```
+
+## Estimated Effort
+
+| 任务 | 预估时间 |
+|-----|---------|
+| 5.1 移除任务模块 | 0.5h |
+| 5.2 清理注释一致性 | 0.5h |
+| 5.3 更新规范文档 | 1h |
+| 5.4 CI 检查增强 | 0.5h |
+| 验证 | 0.5h |
+
+**总计**：约 3 小时