pig-farm-controller/openspec/changes/refactor-migrate-gin-to-echo/tasks.md

## 任务清单：Gin 到 Echo 迁移

- [x] **1. 配置文件 (无代码依赖)**
    - [x] 修改 `config.yml` 中 `mode` 配置项的注释，将 "Gin 运行模式" 改为 "服务运行模式"。
    - [x] 修改 `config.example.yml` 中 `mode` 配置项的注释，保持与 `config.yml` 一致。

- [x] **2. 控制器辅助函数 (最基础的依赖)**
    - [x] **`internal/infra/models/execution.go`**
        - [x] 添加 `ContextAuditStatus` 和 `ContextAuditResultDetails` 常量。
    - [x] **`internal/app/controller/response.go`**
        - [x] 将 `*gin.Context` 参数全部替换为 `echo.Context`。
        - [x] 修改响应函数，使其返回 `error`。
        - [x] **新增 `SendErrorWithStatus` 函数**，用于在中间件等场景下发送带有特定HTTP状态码的错误响应。
        - [x] **重构 `setAuditDetails` 函数**，使其成为统一设置所有审计信息（包括操作状态和结果详情）的唯一入口。
        - [x] 更新 `SendSuccessWithAudit` 和 `SendErrorWithAudit` 以调用重构后的 `setAuditDetails`。
    - [x] **`internal/app/controller/auth_utils.go`**
        - [x] 将 `*gin.Context` 参数全部替换为 `echo.Context`。
        - [x] 适配 `Get...FromContext` 系列函数，使用 `c.Get("key")` 提取数据。

- [x] **3. 中间件 (`internal/app/middleware`)**
    - [x] **`auth.go`**
        - [x] 迁移到 Echo 中间件格式。
        - [x] **使用 `controller.SendErrorWithStatus`** 在认证失败时返回 `401` 或 `500` HTTP状态码。
    - [x] **`audit.go`**
        - [x] **极大简化并迁移到 Echo 中间件格式**。
        - [x] **移除所有响应体捕获和解析的逻辑** (`bodyLogWriter`, `auditResponse` 等)。
        - [x] 在 `next(c)` 调用后，**直接从 `echo.Context` 中获取**由 `response.go` 设置好的最终审计状态和结果详情。

- [x] **4. 控制器 (`internal/app/controller/...`)**
    - [x] **通用修改**：对所有控制器文件执行以下操作：
        - [x] 将 `import "github.com/gin-gonic/gin"` 替换为 `import "github.com/labstack/echo/v4"`。
        - [x] 将所有处理函数签名从 `func(c *gin.Context)` 修改为 `func(c echo.Context) error`。
        - [x] 将 `c.ShouldBindJSON(&req)` 或 `c.ShouldBindQuery(&req)` 替换为
          `if err := c.Bind(&req); err != nil { ... }`。
        - [x] 将 `c.Param("id")` 替换为 `c.Param("id")` (用法相同，检查返回值即可)。
        - [x] 将 `controller.SendResponse(c, ...)` 和 `controller.SendErrorResponse(c, ...)` 调用修改为
          `return controller.SendResponse(c, ...)` 和 `return controller.SendErrorResponse(c, ...)`。
    - [x] **文件清单** (按依赖顺序建议):
        - [x] `internal/app/controller/management/controller_helpers.go` (注意：其中的泛型辅助函数也需要修改为返回
          `error`)
        - [x] `internal/app/controller/device/device_controller.go`
        - [x] `internal/app/controller/management/pig_farm_controller.go`
        - [x] `internal/app/controller/management/pig_batch_controller.go`
        - [x] `internal/app/controller/management/pig_batch_health_controller.go`
        - [x] `internal/app/controller/management/pig_batch_trade_controller.go`
        - [x] `internal/app/controller/management/pig_batch_transfer_controller.go`
        - [x] `internal/app/controller/monitor/monitor_controller.go`
        - [x] `internal/app/controller/plan/plan_controller.go`
        - [x] `internal/app/controller/user/user_controller.go`

- [ ] **5. DTO 结构体注解**
    - [ ] 检查并修改 `internal/app/dto` 包下所有结构体的注解。将所有 Gin 相关的注解（例如 `binding:"..."`）替换为 Echo
      兼容的注解（例如 `validate:"..."`）。`json:"..."` 标签通常保持不变。

- [ ] **6. 核心 API 层 (`internal/app/api`)**
    - [ ] **`router.go`**
        - [ ] 将所有 `router.GET`, `router.POST` 等 Gin 路由注册方法替换为 Echo 的 `e.GET`, `e.POST` 等方法。
        - [ ] 将 Swagger 路由 `router.GET("/swagger/*", ginSwagger.WrapHandler(swaggerFiles.Handler))` 替换为
          `e.GET("/swagger/*", echoSwagger.WrapHandler)`。
        - [ ] 将 pprof 路由的 `gin.WrapH` 和 `gin.WrapF` 调用替换为 `echo.WrapHandler` 和 `echo.WrapFunc`。
    - [ ] **`api.go`**
        - [ ] 将 `engine *gin.Engine` 替换为 `engine *echo.Echo`。
        - [ ] 更新 `NewAPI` 函数：
            - [ ] 将 `gin.SetMode(cfg.Mode)` 替换为 `e.Debug = (cfg.Mode == "debug")`。
            - [ ] 将 `gin.New()` 替换为 `echo.New()`。
            - [ ] 将 `engine.Use(gin.Recovery())` 替换为 `e.Use(middleware.Recover())`。

- [ ] **7. 依赖管理**
    - [ ] 在 `go.mod` 中移除 `github.com/gin-gonic/gin`。
    - [ ] 在 `go.mod` 中移除 `github.com/swaggo/gin-swagger`。
    - [ ] 在 `go.mod` 中添加 `github.com/labstack/echo/v4`。
    - [ ] 在 `go.mod` 中添加 `github.com/swaggo/echo-swagger`。
    - [ ] 执行 `go mod tidy` 清理依赖项。

- [ ] **8. 验证**
    - [ ] 运行 `go build ./...` 确保项目能够成功编译。
    - [ ] 启动服务，手动测试所有 API 端点，验证功能是否与迁移前一致。
    - [ ] 访问 `/swagger/index.html`，确认 Swagger UI 是否正常工作。
    - [ ] (可选) 访问 `/debug/pprof/`，确认 pprof 路由是否正常。