增加注释

internal/app/api/api.go

@@ -48,7 +48,7 @@ type API struct {
 	deviceController    *device.Controller             // 设备控制器实例
 	planController      *plan.Controller               // 计划控制器实例
 	pigFarmController   *management.PigFarmController  // 猪场管理控制器实例
-	pigBatchController  *management.PigBatchController // 猪批次控制器实例
+	pigBatchController  *management.PigBatchController // 猪群控制器实例
 	listenHandler       webhook.ListenHandler          // 设备上行事件监听器
 	analysisTaskManager *task.AnalysisPlanTaskManager  // 计划触发器管理器实例
 }
@@ -63,7 +63,7 @@ func NewAPI(cfg config.ServerConfig,
 	deviceTemplateRepository repository.DeviceTemplateRepository, // 添加设备模板仓库
 	planRepository repository.PlanRepository,
 	pigFarmService service.PigFarmService,
-	pigBatchService service.PigBatchService, // 添加猪批次服务
+	pigBatchService service.PigBatchService, // 添加猪群服务
 	userActionLogRepository repository.UserActionLogRepository,
 	tokenService token.TokenService,
 	auditService audit.Service, // 注入审计服务
@@ -98,7 +98,7 @@ func NewAPI(cfg config.ServerConfig,
 		planController: plan.NewController(logger, planRepository, analysisTaskManager),
 		// 在 NewAPI 中初始化猪场管理控制器
 		pigFarmController: management.NewPigFarmController(logger, pigFarmService),
-		// 在 NewAPI 中初始化猪批次控制器
+		// 在 NewAPI 中初始化猪群控制器
 		pigBatchController: management.NewPigBatchController(logger, pigBatchService),
 	}
 
@@ -114,142 +114,142 @@ func (a *API) setupRoutes() {
 	// 这些路由不需要身份验证
 
 	// 用户注册和登录
-	a.engine.POST("/api/v1/users", a.userController.CreateUser)
+	a.engine.POST("/api/v1/users", a.userController.CreateUser)  // 注册新用户
-	a.engine.POST("/api/v1/users/login", a.userController.Login)
+	a.engine.POST("/api/v1/users/login", a.userController.Login) // 用户登录
 	a.logger.Info("公开接口注册成功：用户注册、登录")
 
 	// 注册 pprof 路由
 	pprofGroup := a.engine.Group("/debug/pprof")
 	{
-		pprofGroup.GET("/", gin.WrapF(pprof.Index))
+		pprofGroup.GET("/", gin.WrapF(pprof.Index))                   // pprof 索引页
-		pprofGroup.GET("/cmdline", gin.WrapF(pprof.Cmdline))
+		pprofGroup.GET("/cmdline", gin.WrapF(pprof.Cmdline))          // pprof 命令行参数
-		pprofGroup.GET("/profile", gin.WrapF(pprof.Profile))
+		pprofGroup.GET("/profile", gin.WrapF(pprof.Profile))          // pprof CPU profile
-		pprofGroup.POST("/symbol", gin.WrapF(pprof.Symbol))
+		pprofGroup.POST("/symbol", gin.WrapF(pprof.Symbol))           // pprof 符号查找 (POST)
-		pprofGroup.GET("/symbol", gin.WrapF(pprof.Symbol))
+		pprofGroup.GET("/symbol", gin.WrapF(pprof.Symbol))            // pprof 符号查找 (GET)
-		pprofGroup.GET("/trace", gin.WrapF(pprof.Trace))
+		pprofGroup.GET("/trace", gin.WrapF(pprof.Trace))              // pprof 跟踪
-		pprofGroup.GET("/allocs", gin.WrapH(pprof.Handler("allocs")))
+		pprofGroup.GET("/allocs", gin.WrapH(pprof.Handler("allocs"))) // pprof 内存分配
-		pprofGroup.GET("/block", gin.WrapH(pprof.Handler("block")))
+		pprofGroup.GET("/block", gin.WrapH(pprof.Handler("block")))   // pprof 阻塞
 		pprofGroup.GET("/goroutine", gin.WrapH(pprof.Handler("goroutine")))
-		pprofGroup.GET("/heap", gin.WrapH(pprof.Handler("heap")))
+		pprofGroup.GET("/heap", gin.WrapH(pprof.Handler("heap")))   // pprof 堆内存
-		pprofGroup.GET("/mutex", gin.WrapH(pprof.Handler("mutex")))
+		pprofGroup.GET("/mutex", gin.WrapH(pprof.Handler("mutex"))) // pprof 互斥锁
 		pprofGroup.GET("/threadcreate", gin.WrapH(pprof.Handler("threadcreate")))
 	}
 	a.logger.Info("pprof 接口注册成功")
 
 	// 上行事件监听路由
-	a.engine.POST("/upstream", gin.WrapH(a.listenHandler.Handler()))
+	a.engine.POST("/upstream", gin.WrapH(a.listenHandler.Handler())) // 处理设备上行事件
 	a.logger.Info("上行事件监听接口注册成功")
 
 	// 添加 Swagger UI 路由, Swagger UI可在 /swagger/index.html 上找到
-	a.engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+	a.engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) // Swagger UI 接口
 	a.logger.Info("Swagger UI 接口注册成功")
 
 	// --- Authenticated Routes ---
 	// 所有在此注册的路由都需要通过 JWT 身份验证
 	authGroup := a.engine.Group("/api/v1")
-	authGroup.Use(middleware.AuthMiddleware(a.tokenService, a.userRepo)) // 1. 身份认证
+	authGroup.Use(middleware.AuthMiddleware(a.tokenService, a.userRepo)) // 1. 身份认证中间件
-	authGroup.Use(middleware.AuditLogMiddleware(a.auditService))         // 2. 审计日志
+	authGroup.Use(middleware.AuditLogMiddleware(a.auditService))         // 2. 审计日志中间件
 	{
 		// 用户相关路由组
 		userGroup := authGroup.Group("/users")
 		{
-			userGroup.GET("/:id/history", a.userController.ListUserHistory)
+			userGroup.GET("/:id/history", a.userController.ListUserHistory) // 获取用户操作历史
 		}
 		a.logger.Info("用户相关接口注册成功 (需要认证和审计)")
 
 		// 设备相关路由组
 		deviceGroup := authGroup.Group("/devices")
 		{
-			deviceGroup.POST("", a.deviceController.CreateDevice)
+			deviceGroup.POST("", a.deviceController.CreateDevice)       // 创建设备
-			deviceGroup.GET("", a.deviceController.ListDevices)
+			deviceGroup.GET("", a.deviceController.ListDevices)         // 获取设备列表
-			deviceGroup.GET("/:id", a.deviceController.GetDevice)
+			deviceGroup.GET("/:id", a.deviceController.GetDevice)       // 获取单个设备
-			deviceGroup.PUT("/:id", a.deviceController.UpdateDevice)
+			deviceGroup.PUT("/:id", a.deviceController.UpdateDevice)    // 更新设备
-			deviceGroup.DELETE("/:id", a.deviceController.DeleteDevice)
+			deviceGroup.DELETE("/:id", a.deviceController.DeleteDevice) // 删除设备
 		}
 		a.logger.Info("设备相关接口注册成功 (需要认证和审计)")
 
 		// 区域主控相关路由组
 		areaControllerGroup := authGroup.Group("/area-controllers")
 		{
-			areaControllerGroup.POST("", a.deviceController.CreateAreaController)
+			areaControllerGroup.POST("", a.deviceController.CreateAreaController)       // 创建区域主控
-			areaControllerGroup.GET("", a.deviceController.ListAreaControllers)
+			areaControllerGroup.GET("", a.deviceController.ListAreaControllers)         // 获取区域主控列表
-			areaControllerGroup.GET("/:id", a.deviceController.GetAreaController)
+			areaControllerGroup.GET("/:id", a.deviceController.GetAreaController)       // 获取单个区域主控
-			areaControllerGroup.PUT("/:id", a.deviceController.UpdateAreaController)
+			areaControllerGroup.PUT("/:id", a.deviceController.UpdateAreaController)    // 更新区域主控
-			areaControllerGroup.DELETE("/:id", a.deviceController.DeleteAreaController)
+			areaControllerGroup.DELETE("/:id", a.deviceController.DeleteAreaController) // 删除区域主控
 		}
 		a.logger.Info("区域主控相关接口注册成功 (需要认证和审计)")
 
 		// 设备模板相关路由组
 		deviceTemplateGroup := authGroup.Group("/device-templates")
 		{
-			deviceTemplateGroup.POST("", a.deviceController.CreateDeviceTemplate)
+			deviceTemplateGroup.POST("", a.deviceController.CreateDeviceTemplate)       // 创建设备模板
-			deviceTemplateGroup.GET("", a.deviceController.ListDeviceTemplates)
+			deviceTemplateGroup.GET("", a.deviceController.ListDeviceTemplates)         // 获取设备模板列表
-			deviceTemplateGroup.GET("/:id", a.deviceController.GetDeviceTemplate)
+			deviceTemplateGroup.GET("/:id", a.deviceController.GetDeviceTemplate)       // 获取单个设备模板
-			deviceTemplateGroup.PUT("/:id", a.deviceController.UpdateDeviceTemplate)
+			deviceTemplateGroup.PUT("/:id", a.deviceController.UpdateDeviceTemplate)    // 更新设备模板
-			deviceTemplateGroup.DELETE("/:id", a.deviceController.DeleteDeviceTemplate)
+			deviceTemplateGroup.DELETE("/:id", a.deviceController.DeleteDeviceTemplate) // 删除设备模板
 		}
 		a.logger.Info("设备模板相关接口注册成功 (需要认证和审计)")
 
 		// 计划相关路由组
 		planGroup := authGroup.Group("/plans")
 		{
-			planGroup.POST("", a.planController.CreatePlan)
+			planGroup.POST("", a.planController.CreatePlan)          // 创建计划
-			planGroup.GET("", a.planController.ListPlans)
+			planGroup.GET("", a.planController.ListPlans)            // 获取计划列表
-			planGroup.GET("/:id", a.planController.GetPlan)
+			planGroup.GET("/:id", a.planController.GetPlan)          // 获取单个计划
-			planGroup.PUT("/:id", a.planController.UpdatePlan)
+			planGroup.PUT("/:id", a.planController.UpdatePlan)       // 更新计划
-			planGroup.DELETE("/:id", a.planController.DeletePlan)
+			planGroup.DELETE("/:id", a.planController.DeletePlan)    // 删除计划
-			planGroup.POST("/:id/start", a.planController.StartPlan)
+			planGroup.POST("/:id/start", a.planController.StartPlan) // 启动计划
-			planGroup.POST("/:id/stop", a.planController.StopPlan)
+			planGroup.POST("/:id/stop", a.planController.StopPlan)   // 停止计划
 		}
 		a.logger.Info("计划相关接口注册成功 (需要认证和审计)")
 
 		// 猪舍相关路由组
 		pigHouseGroup := authGroup.Group("/pig-houses")
 		{
-			pigHouseGroup.POST("", a.pigFarmController.CreatePigHouse)
+			pigHouseGroup.POST("", a.pigFarmController.CreatePigHouse)       // 创建猪舍
-			pigHouseGroup.GET("", a.pigFarmController.ListPigHouses)
+			pigHouseGroup.GET("", a.pigFarmController.ListPigHouses)         // 获取猪舍列表
-			pigHouseGroup.GET("/:id", a.pigFarmController.GetPigHouse)
+			pigHouseGroup.GET("/:id", a.pigFarmController.GetPigHouse)       // 获取单个猪舍
-			pigHouseGroup.PUT("/:id", a.pigFarmController.UpdatePigHouse)
+			pigHouseGroup.PUT("/:id", a.pigFarmController.UpdatePigHouse)    // 更新猪舍
-			pigHouseGroup.DELETE("/:id", a.pigFarmController.DeletePigHouse)
+			pigHouseGroup.DELETE("/:id", a.pigFarmController.DeletePigHouse) // 删除猪舍
 		}
 		a.logger.Info("猪舍相关接口注册成功 (需要认证和审计)")
 
 		// 猪圈相关路由组
 		penGroup := authGroup.Group("/pens")
 		{
-			penGroup.POST("", a.pigFarmController.CreatePen)
+			penGroup.POST("", a.pigFarmController.CreatePen)                 // 创建猪圈
-			penGroup.GET("", a.pigFarmController.ListPens)
+			penGroup.GET("", a.pigFarmController.ListPens)                   // 获取猪圈列表
-			penGroup.GET("/:id", a.pigFarmController.GetPen)
+			penGroup.GET("/:id", a.pigFarmController.GetPen)                 // 获取单个猪圈
-			penGroup.PUT("/:id", a.pigFarmController.UpdatePen)
+			penGroup.PUT("/:id", a.pigFarmController.UpdatePen)              // 更新猪圈
-			penGroup.DELETE("/:id", a.pigFarmController.DeletePen)
+			penGroup.DELETE("/:id", a.pigFarmController.DeletePen)           // 删除猪圈
-			penGroup.PUT("/:id/status", a.pigFarmController.UpdatePenStatus)
+			penGroup.PUT("/:id/status", a.pigFarmController.UpdatePenStatus) // 更新猪圈状态
 		}
 		a.logger.Info("猪圈相关接口注册成功 (需要认证和审计)")
 
 		// 猪群相关路由组
 		pigBatchGroup := authGroup.Group("/pig-batches")
 		{
-			pigBatchGroup.POST("", a.pigBatchController.CreatePigBatch)
+			pigBatchGroup.POST("", a.pigBatchController.CreatePigBatch)                                                   // 创建猪群
-			pigBatchGroup.GET("", a.pigBatchController.ListPigBatches)
+			pigBatchGroup.GET("", a.pigBatchController.ListPigBatches)                                                    // 获取猪群列表
-			pigBatchGroup.GET("/:id", a.pigBatchController.GetPigBatch)
+			pigBatchGroup.GET("/:id", a.pigBatchController.GetPigBatch)                                                   // 获取单个猪群
-			pigBatchGroup.PUT("/:id", a.pigBatchController.UpdatePigBatch)
+			pigBatchGroup.PUT("/:id", a.pigBatchController.UpdatePigBatch)                                                // 更新猪群
-			pigBatchGroup.DELETE("/:id", a.pigBatchController.DeletePigBatch)
+			pigBatchGroup.DELETE("/:id", a.pigBatchController.DeletePigBatch)                                             // 删除猪群
-			pigBatchGroup.POST("/:id/assign-pens", a.pigBatchController.AssignEmptyPensToBatch)
+			pigBatchGroup.POST("/:id/assign-pens", a.pigBatchController.AssignEmptyPensToBatch)                           // 为猪群分配空栏
-			pigBatchGroup.POST("/:fromBatchID/reclassify-pen", a.pigBatchController.ReclassifyPenToNewBatch)
+			pigBatchGroup.POST("/:fromBatchID/reclassify-pen", a.pigBatchController.ReclassifyPenToNewBatch)              // 将猪栏划拨到新群
-			pigBatchGroup.DELETE("/:batchID/remove-pen/:penID", a.pigBatchController.RemoveEmptyPenFromBatch)
+			pigBatchGroup.DELETE("/:batchID/remove-pen/:penID", a.pigBatchController.RemoveEmptyPenFromBatch)             // 从猪群移除空栏
-			pigBatchGroup.POST("/:id/move-pigs-into-pen", a.pigBatchController.MovePigsIntoPen)
+			pigBatchGroup.POST("/:id/move-pigs-into-pen", a.pigBatchController.MovePigsIntoPen)                           // 将猪只从“虚拟库存”移入指定猪栏
-			pigBatchGroup.POST("/:id/sell-pigs", a.pigBatchController.SellPigs)
+			pigBatchGroup.POST("/:id/sell-pigs", a.pigBatchController.SellPigs)                                           // 处理卖猪业务
-			pigBatchGroup.POST("/:id/buy-pigs", a.pigBatchController.BuyPigs)
+			pigBatchGroup.POST("/:id/buy-pigs", a.pigBatchController.BuyPigs)                                             // 处理买猪业务
-			pigBatchGroup.POST("/:sourceBatchID/transfer-across-batches", a.pigBatchController.TransferPigsAcrossBatches)
+			pigBatchGroup.POST("/:sourceBatchID/transfer-across-batches", a.pigBatchController.TransferPigsAcrossBatches) // 跨猪群调栏
-			pigBatchGroup.POST("/:id/transfer-within-batch", a.pigBatchController.TransferPigsWithinBatch)
+			pigBatchGroup.POST("/:id/transfer-within-batch", a.pigBatchController.TransferPigsWithinBatch)                // 群内调栏
-			pigBatchGroup.POST("/:id/record-sick-pigs", a.pigBatchController.RecordSickPigs)
+			pigBatchGroup.POST("/:id/record-sick-pigs", a.pigBatchController.RecordSickPigs)                              // 记录新增病猪事件
-			pigBatchGroup.POST("/:id/record-sick-pig-recovery", a.pigBatchController.RecordSickPigRecovery)
+			pigBatchGroup.POST("/:id/record-sick-pig-recovery", a.pigBatchController.RecordSickPigRecovery)               // 记录病猪康复事件
-			pigBatchGroup.POST("/:id/record-sick-pig-death", a.pigBatchController.RecordSickPigDeath)
+			pigBatchGroup.POST("/:id/record-sick-pig-death", a.pigBatchController.RecordSickPigDeath)                     // 记录病猪死亡事件
-			pigBatchGroup.POST("/:id/record-sick-pig-cull", a.pigBatchController.RecordSickPigCull)
+			pigBatchGroup.POST("/:id/record-sick-pig-cull", a.pigBatchController.RecordSickPigCull)                       // 记录病猪淘汰事件
-			pigBatchGroup.POST("/:id/record-death", a.pigBatchController.RecordDeath)
+			pigBatchGroup.POST("/:id/record-death", a.pigBatchController.RecordDeath)                                     // 记录正常猪只死亡事件
-			pigBatchGroup.POST("/:id/record-cull", a.pigBatchController.RecordCull)
+			pigBatchGroup.POST("/:id/record-cull", a.pigBatchController.RecordCull)                                       // 记录正常猪只淘汰事件
 		}
-		a.logger.Info("猪批次相关接口注册成功 (需要认证和审计)")
+		a.logger.Info("猪群相关接口注册成功 (需要认证和审计)")
 
 	}
 }