pig-farm-controller/openspec/changes/archive/2025-10-31-refactor-business-logic-layering/tasks.md

1. 准备工作

• 1.1 阅读并理解 openspec/changes/refactor-business-logic-layering/proposal.md。
• 1.2 阅读并理解 openspec/changes/refactor-business-logic-layering/design.md。
• 1.3 阅读并理解 'AGENTS.md'

2. 统一服务层接口输入输出为 DTO

2.1 monitor 模块

• 2.1.1 修改 internal/app/service/monitor_service.go：
  • 将所有 List... 方法的 opts repository.ListOptions 参数替换为服务层自定义的查询 DTO 或一系列基本参数。
  • 将所有 List... 方法的返回值 []models.Xxx 替换为 []dto.XxxResponse。
  • 调整 List... 方法的实现，在服务层内部将服务层查询 DTO 转换为 repository.ListOptions。
  • 调整 List... 方法的实现，在服务层内部将 repository 返回的 models 对象转换为 dto.XxxResponse。
• 2.1.2 修改 internal/app/controller/monitor/monitor_controller.go：
  • 移除控制器中构建 repository.ListOptions 的逻辑。
  • 移除控制器中将 models 转换为 dto.NewList...Response 的逻辑。
  • 移除控制器中直接使用 models 进行枚举类型转换的逻辑，将其下沉到服务层或 DTO 转换逻辑中。
  • 调整服务层方法的调用，使其接收新的服务层查询 DTO 或基本参数，并直接处理服务层返回的 dto.XxxResponse。

2.2 device 模块

• 2.2.1 创建并修改 internal/app/service/device_service.go：
  • 定义 DeviceService 接口，包含 CreateDevice, UpdateDevice, CreateAreaController, UpdateAreaController, CreateDeviceTemplate, UpdateDeviceTemplate, GetDevice, ListDevices, GetAreaController, ListAreaControllers, GetDeviceTemplate, ListDeviceTemplates, ManualControl 等方法。
  • 为 CreateDevice, UpdateDevice, CreateAreaController, UpdateAreaController, CreateDeviceTemplate, UpdateDeviceTemplate, ManualControl 方法定义并接收 DTO 作为输入。
  • 将 GetDevice, ListDevices, GetAreaController, ListAreaControllers, GetDeviceTemplate, ListDeviceTemplates 方法的返回值 models.Xxx 或 []models.Xxx 替换为 dto.XxxResponse 或 []dto.XxxResponse。
  • 实现 DeviceService 接口。
  • 在此服务层内部将输入 DTO 转换为 models 对象。
  • 在此服务层内部将 repository 或 domain 层返回的 models 对象转换为 dto.XxxResponse。
  • 将控制器中 SelfCheck() 验证逻辑移入此服务层。
  • 将控制器中 Properties, Commands, Values 的 JSON 序列化逻辑移入此服务层。
  • 将控制器中 ManualControl 的业务逻辑（如动作映射）移入此服务层。
  • 将控制器中直接调用 repository 方法的逻辑移入此服务层。
  • 将控制器中通过检查 repository 错误信息处理业务规则的逻辑移入此服务层。
  • 调整此服务层对 internal/domain/device.Service 的调用，确保传递的是 models 或领域对象，而不是 DTO。
• 2.2.2 修改 internal/app/controller/device/device_controller.go：
  • 引入并使用新创建的 internal/app/service.DeviceService。
  • 移除控制器中直接创建 models.Device, models.AreaController, models.DeviceTemplate 对象的逻辑。
  • 移除控制器中直接调用 SelfCheck() 的逻辑。
  • 移除控制器中直接调用 repository 方法的逻辑。
  • 移除控制器中通过检查 repository 错误信息处理业务规则的逻辑。
  • 移除控制器中 Properties, Commands, Values 的 JSON 序列化逻辑。
  • 调整服务层方法的调用，使其接收新的服务层输入 DTO 或基本参数，并直接处理服务层返回的 dto.XxxResponse。
• 2.2.3 修改 internal/core/component_initializers.go：创建并提供新的 DeviceService。
• 2.2.4 修改 internal/app/api/api.go：更新 DeviceController 的依赖注入。

2.3 pig-farm 模块

• 2.3.1 修改 internal/app/service/pig_farm_service.go：
  • 将 CreatePigHouse, GetPigHouseByID, ListPigHouses, UpdatePigHouse, CreatePen, GetPenByID, ListPens, UpdatePen, UpdatePenStatus 方法的返回值 models.Xxx 或 []models.Xxx 替换为 dto.XxxResponse 或 []dto.XxxResponse。
  • 在服务层内部将 repository 返回的 models 对象转换为 dto.XxxResponse。
  • 将控制器中处理服务层特定业务错误（如 service.ErrHouseNotFound）的逻辑移入服务层，服务层应返回更抽象的错误或直接返回 DTO。
• 2.3.2 修改 internal/app/controller/management/pig_farm_controller.go：
  • 移除控制器中手动将领域实体转换为 DTO 的逻辑。
  • 移除控制器中直接处理服务层特定业务错误类型的逻辑。
  • 调整服务层方法的调用，使其直接处理服务层返回的 dto.XxxResponse。

2.4 plan 模块

• 2.4.1 创建并修改 internal/app/service/plan_service.go：
  • 定义 PlanService 接口，包含 CreatePlan, GetPlanByID, ListPlans, UpdatePlan, DeletePlan, StartPlan, StopPlan 等方法。
  • 为 CreatePlan, UpdatePlan 方法定义并接收 DTO 作为输入。
  • 将 GetPlanByID, ListPlans 方法的返回值 models.Plan 或 []models.Plan 替换为 dto.PlanResponse 或 []dto.PlanResponse。
  • 调整 ListPlans 方法的 opts repository.ListPlansOptions 参数替换为服务层自定义的查询 DTO 或一系列基本参数。
  • 调整 DeletePlan, StartPlan, StopPlan 方法，使其接收 DTO 或基本参数，并封装所有业务逻辑。
  • 实现 PlanService 接口。
  • 在服务层内部将输入 DTO 转换为 models 对象。
  • 在服务层内部将 repository 返回的 models 对象转换为 dto.XxxResponse。
  • 将 internal/app/controller/plan/plan_controller.go 中所有的业务规则判断（计划类型检查、状态检查、执行计数器重置、ContentType 自动判断）移入服务层。
  • 将 internal/app/controller/plan/plan_controller.go 中对 repository 方法的直接调用移入服务层。
  • 将 internal/app/controller/plan/plan_controller.go 中对 analysisPlanTaskManager 的协调移入服务层。
  • 将 internal/app/controller/plan/plan_controller.go 中处理仓库层特有错误（gorm.ErrRecordNotFound）的逻辑移入服务层。
• 2.4.2 修改 internal/app/controller/plan/plan_controller.go：
  • 引入并使用新创建的 plan_service。
  • 移除控制器中直接创建 models.Plan 对象和 repository.ListPlansOptions 的逻辑。
  • 移除控制器中所有的业务规则判断。
  • 移除控制器中直接调用 repository 方法的逻辑。
  • 移除控制器中直接协调 analysisPlanTaskManager 的逻辑。
  • 移除控制器中直接处理仓库层特有错误的逻辑。
  • 调整服务层方法的调用，使其接收新的服务层输入 DTO 或基本参数，并直接处理服务层返回的 dto.XxxResponse。
• 2.4.3 修改 internal/core/component_initializers.go：创建并提供新的 PlanService。
• 2.4.4 修改 internal/app/api/api.go：更新 PlanController 的依赖注入。

2.5 user 模块

• 2.5.1 创建并修改 internal/app/service/user_service.go：
  • 定义 UserService 接口，包含 CreateUser, Login, SendTestNotification 等方法。
  • 为 CreateUser, Login 方法定义并接收 DTO 作为输入。
  • 将 CreateUser, Login 方法的返回值 models.User 替换为 dto.CreateUserResponse 或 dto.LoginResponse。
  • 调整 SendTestNotification 方法，使其接收 DTO 或基本参数，并封装所有业务逻辑。
  • 实现 UserService 接口。
  • 在服务层内部将输入 DTO 转换为 models 对象。
  • 在服务层内部将 repository 返回的 models 对象转换为 dto.XxxResponse。
  • 将 CreateUser 中处理用户名重复的业务逻辑从控制器移入服务层。
  • 将 Login 中进行密码验证的业务逻辑和协调 tokenService 的逻辑从控制器移入服务层。
  • 将 SendTestNotification 中调用 domain_notify.Service 的逻辑移入服务层。
  • 将控制器中通过检查底层（仓库层或服务层）的特定错误类型或错误信息来执行业务判断的逻辑移入服务层。
• 2.5.2 修改 internal/app/controller/user/user_controller.go：
  • 引入并使用新创建的 user_service。
  • 移除控制器中直接创建 models.User 对象的逻辑。
  • 移除控制器中处理用户名重复的业务逻辑。
  • 移除控制器中进行密码验证的业务逻辑和协调 tokenService 的逻辑。
  • 移除控制器中通过检查底层（仓库层或服务层）的特定错误类型或错误信息来执行业务判断的逻辑。
  • 调整服务层方法的调用，使其接收新的服务层输入 DTO 或基本参数，并直接处理服务层返回的 dto.XxxResponse。
• 2.5.2 修改 internal/core/component_initializers.go：创建并提供新的 UserService。
• 2.5.3 修改 internal/app/api/api.go：更新 UserController 的依赖注入。

3. 验证与测试

• 3.1 运行所有单元测试和集成测试，确保重构没有引入新的问题。
• 3.2 针对受影响的 API 接口进行手动测试，验证功能是否正常。
• 3.3 确保日志输出和审计记录仍然准确无误.