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

任务清单：Gin 到 Echo 迁移

• 1. 配置文件 (无代码依赖)

  • 修改 config.yml 中 mode 配置项的注释，将 "Gin 运行模式" 改为 "服务运行模式"。
  • 修改 config.example.yml 中 mode 配置项的注释，保持与 config.yml 一致。

• 2. 控制器辅助函数 (最基础的依赖)

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

• 3. 中间件 (internal/app/middleware)

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

• 4. 控制器 (internal/app/controller/...)

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