From 740e14e6cc713ee11dee7b46fdb150d1823bdd5e Mon Sep 17 00:00:00 2001 From: huang <1724659546@qq.com> Date: Sat, 4 Oct 2025 01:31:35 +0800 Subject: [PATCH] swag --- docs/docs.go | 102 ++++++++++++++++-- docs/swagger.json | 102 ++++++++++++++++-- docs/swagger.yaml | 66 ++++++++++-- .../management/pig_batch_controller.go | 2 +- internal/app/dto/pig_farm_dto.go | 4 +- internal/app/service/pig_batch_service.go | 10 +- internal/app/service/pig_farm_service.go | 12 +-- internal/core/application.go | 2 +- internal/infra/models/farm_asset.go | 2 +- 9 files changed, 264 insertions(+), 38 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 82ab941..12ddeb1 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -807,6 +807,59 @@ const docTemplate = `{ } } }, + "/api/v1/pens/{id}/status": { + "put": { + "description": "更新指定猪栏的当前状态", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "猪场管理" + ], + "summary": "更新猪栏状态", + "parameters": [ + { + "type": "integer", + "description": "猪栏ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "新的猪栏状态", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.UpdatePenStatusRequest" + } + } + ], + "responses": { + "200": { + "description": "更新成功", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/controller.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/dto.PenResponse" + } + } + } + ] + } + } + } + } + }, "/api/v1/pig-batches": { "get": { "description": "获取所有猪批次的列表，支持按活跃状态筛选", @@ -1136,7 +1189,7 @@ const docTemplate = `{ } }, "409": { - "description": "业务逻辑冲突 (如猪栏已被占用)", + "description": "业务逻辑冲突 (如猪栏已被使用)", "schema": { "$ref": "#/definitions/controller.Response" } @@ -1937,8 +1990,7 @@ const docTemplate = `{ "required": [ "capacity", "house_id", - "pen_number", - "status" + "pen_number" ], "properties": { "capacity": { @@ -1949,9 +2001,6 @@ const docTemplate = `{ }, "pen_number": { "type": "string" - }, - "status": { - "$ref": "#/definitions/models.PenStatus" } } }, @@ -2616,7 +2665,44 @@ const docTemplate = `{ "type": "string" }, "status": { - "$ref": "#/definitions/models.PenStatus" + "description": "添加oneof校验", + "enum": [ + "空闲", + "使用中", + "病猪栏", + "康复栏", + "清洗消毒", + "维修中" + ], + "allOf": [ + { + "$ref": "#/definitions/models.PenStatus" + } + ] + } + } + }, + "dto.UpdatePenStatusRequest": { + "type": "object", + "required": [ + "status" + ], + "properties": { + "status": { + "enum": [ + "空闲", + "使用中", + "病猪栏", + "康复栏", + "清洗消毒", + "维修中" + ], + "allOf": [ + { + "$ref": "#/definitions/models.PenStatus" + } + ], + "example": "病猪栏" } } }, @@ -2693,7 +2779,7 @@ const docTemplate = `{ "type": "string", "enum": [ "空闲", - "占用", + "使用中", "病猪栏", "康复栏", "清洗消毒", diff --git a/docs/swagger.json b/docs/swagger.json index 44ea4f2..349588d 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -796,6 +796,59 @@ } } }, + "/api/v1/pens/{id}/status": { + "put": { + "description": "更新指定猪栏的当前状态", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "猪场管理" + ], + "summary": "更新猪栏状态", + "parameters": [ + { + "type": "integer", + "description": "猪栏ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "新的猪栏状态", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/dto.UpdatePenStatusRequest" + } + } + ], + "responses": { + "200": { + "description": "更新成功", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/controller.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/dto.PenResponse" + } + } + } + ] + } + } + } + } + }, "/api/v1/pig-batches": { "get": { "description": "获取所有猪批次的列表，支持按活跃状态筛选", @@ -1125,7 +1178,7 @@ } }, "409": { - "description": "业务逻辑冲突 (如猪栏已被占用)", + "description": "业务逻辑冲突 (如猪栏已被使用)", "schema": { "$ref": "#/definitions/controller.Response" } @@ -1926,8 +1979,7 @@ "required": [ "capacity", "house_id", - "pen_number", - "status" + "pen_number" ], "properties": { "capacity": { @@ -1938,9 +1990,6 @@ }, "pen_number": { "type": "string" - }, - "status": { - "$ref": "#/definitions/models.PenStatus" } } }, @@ -2605,7 +2654,44 @@ "type": "string" }, "status": { - "$ref": "#/definitions/models.PenStatus" + "description": "添加oneof校验", + "enum": [ + "空闲", + "使用中", + "病猪栏", + "康复栏", + "清洗消毒", + "维修中" + ], + "allOf": [ + { + "$ref": "#/definitions/models.PenStatus" + } + ] + } + } + }, + "dto.UpdatePenStatusRequest": { + "type": "object", + "required": [ + "status" + ], + "properties": { + "status": { + "enum": [ + "空闲", + "使用中", + "病猪栏", + "康复栏", + "清洗消毒", + "维修中" + ], + "allOf": [ + { + "$ref": "#/definitions/models.PenStatus" + } + ], + "example": "病猪栏" } } }, @@ -2682,7 +2768,7 @@ "type": "string", "enum": [ "空闲", - "占用", + "使用中", "病猪栏", "康复栏", "清洗消毒", diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 0292e48..b74f124 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -132,13 +132,10 @@ definitions: type: integer pen_number: type: string - status: - $ref: '#/definitions/models.PenStatus' required: - capacity - house_id - pen_number - - status type: object dto.CreatePigHouseRequest: properties: @@ -578,13 +575,38 @@ definitions: pen_number: type: string status: - $ref: '#/definitions/models.PenStatus' + allOf: + - $ref: '#/definitions/models.PenStatus' + description: 添加oneof校验 + enum: + - 空闲 + - 使用中 + - 病猪栏 + - 康复栏 + - 清洗消毒 + - 维修中 required: - capacity - house_id - pen_number - status type: object + dto.UpdatePenStatusRequest: + properties: + status: + allOf: + - $ref: '#/definitions/models.PenStatus' + enum: + - 空闲 + - 使用中 + - 病猪栏 + - 康复栏 + - 清洗消毒 + - 维修中 + example: 病猪栏 + required: + - status + type: object dto.UpdatePigHouseRequest: properties: description: @@ -634,7 +656,7 @@ definitions: models.PenStatus: enum: - 空闲 - - 占用 + - 使用中 - 病猪栏 - 康复栏 - 清洗消毒 @@ -1268,6 +1290,38 @@ paths: summary: 更新猪栏 tags: - 猪场管理 + /api/v1/pens/{id}/status: + put: + consumes: + - application/json + description: 更新指定猪栏的当前状态 + parameters: + - description: 猪栏ID + in: path + name: id + required: true + type: integer + - description: 新的猪栏状态 + in: body + name: body + required: true + schema: + $ref: '#/definitions/dto.UpdatePenStatusRequest' + produces: + - application/json + responses: + "200": + description: 更新成功 + schema: + allOf: + - $ref: '#/definitions/controller.Response' + - properties: + data: + $ref: '#/definitions/dto.PenResponse' + type: object + summary: 更新猪栏状态 + tags: + - 猪场管理 /api/v1/pig-batches: get: description: 获取所有猪批次的列表，支持按活跃状态筛选 @@ -1473,7 +1527,7 @@ paths: schema: $ref: '#/definitions/controller.Response' "409": - description: 业务逻辑冲突 (如猪栏已被占用) + description: 业务逻辑冲突 (如猪栏已被使用) schema: $ref: '#/definitions/controller.Response' "500": diff --git a/internal/app/controller/management/pig_batch_controller.go b/internal/app/controller/management/pig_batch_controller.go index 5965c49..46199b6 100644 --- a/internal/app/controller/management/pig_batch_controller.go +++ b/internal/app/controller/management/pig_batch_controller.go @@ -200,7 +200,7 @@ func (c *PigBatchController) ListPigBatches(ctx *gin.Context) { // @Success 200 {object} controller.Response "更新成功" // @Failure 400 {object} controller.Response "请求参数错误或无效的ID格式" // @Failure 404 {object} controller.Response "猪批次或猪栏不存在" -// @Failure 409 {object} controller.Response "业务逻辑冲突 (如猪栏已被占用)" +// @Failure 409 {object} controller.Response "业务逻辑冲突 (如猪栏已被使用)" // @Failure 500 {object} controller.Response "内部服务器错误" // @Router /api/v1/pig-batches/{id}/pens [put] func (c *PigBatchController) UpdatePigBatchPens(ctx *gin.Context) { diff --git a/internal/app/dto/pig_farm_dto.go b/internal/app/dto/pig_farm_dto.go index b10e274..09f450a 100644 --- a/internal/app/dto/pig_farm_dto.go +++ b/internal/app/dto/pig_farm_dto.go @@ -43,10 +43,10 @@ type UpdatePenRequest struct { PenNumber string `json:"pen_number" binding:"required"` HouseID uint `json:"house_id" binding:"required"` Capacity int `json:"capacity" binding:"required"` - Status models.PenStatus `json:"status" binding:"required,oneof=空闲 占用 病猪栏 康复栏 清洗消毒 维修中"` // 添加oneof校验 + Status models.PenStatus `json:"status" binding:"required,oneof=空闲 使用中 病猪栏 康复栏 清洗消毒 维修中"` // 添加oneof校验 } // UpdatePenStatusRequest 定义了更新猪栏状态的请求结构 type UpdatePenStatusRequest struct { - Status models.PenStatus `json:"status" binding:"required,oneof=空闲 占用 病猪栏 康复栏 清洗消毒 维修中" example:"病猪栏"` + Status models.PenStatus `json:"status" binding:"required,oneof=空闲 使用中 病猪栏 康复栏 清洗消毒 维修中" example:"病猪栏"` } diff --git a/internal/app/service/pig_batch_service.go b/internal/app/service/pig_batch_service.go index 3879c0d..c6c45d3 100644 --- a/internal/app/service/pig_batch_service.go +++ b/internal/app/service/pig_batch_service.go @@ -16,7 +16,7 @@ var ( ErrPigBatchNotFound = errors.New("指定的猪批次不存在") ErrPigBatchActive = errors.New("活跃的猪批次不能被删除") ErrPigBatchNotActive = errors.New("猪批次不处于活跃状态，无法修改关联猪栏") - ErrPenOccupiedByOtherBatch = errors.New("猪栏已被其他批次占用") + ErrPenOccupiedByOtherBatch = errors.New("猪栏已被其他批次使用") ErrPenStatusInvalidForAllocation = errors.New("猪栏状态不允许分配") ErrPenNotAssociatedWithBatch = errors.New("猪栏未与该批次关联") ) @@ -257,7 +257,7 @@ func (s *pigBatchService) UpdatePigBatchPens(batchID uint, desiredPenIDs []uint) updates := make(map[string]interface{}) updates["pig_batch_id"] = nil // 总是将 PigBatchID 设为 nil - // 只有当猪栏当前状态是“占用”时，才将其状态改回“空闲” + // 只有当猪栏当前状态是“使用中”时，才将其状态改回“空闲” if currentPen.Status == models.PenStatusOccupied { updates["status"] = models.PenStatusEmpty } @@ -279,17 +279,17 @@ func (s *pigBatchService) UpdatePigBatchPens(batchID uint, desiredPenIDs []uint) return fmt.Errorf("获取猪栏 %d 信息失败: %w", penID, err) } - // 验证：猪栏必须是“空闲”状态且未被任何批次占用，才能被分配 + // 验证：猪栏必须是“空闲”状态且未被任何批次使用，才能被分配 if actualPen.Status != models.PenStatusEmpty { return fmt.Errorf("猪栏 %s 状态为 %s，无法分配: %w", actualPen.PenNumber, actualPen.Status, ErrPenStatusInvalidForAllocation) } if actualPen.PigBatchID != nil { - return fmt.Errorf("猪栏 %s 已被其他批次 %d 占用，无法分配: %w", actualPen.PenNumber, *actualPen.PigBatchID, ErrPenOccupiedByOtherBatch) + return fmt.Errorf("猪栏 %s 已被其他批次 %d 使用，无法分配: %w", actualPen.PenNumber, *actualPen.PigBatchID, ErrPenOccupiedByOtherBatch) } updates := map[string]interface{}{ "pig_batch_id": &batchID, // 将 PigBatchID 设为当前批次ID的指针 - "status": models.PenStatusOccupied, // 分配后，状态变为“占用” + "status": models.PenStatusOccupied, // 分配后，状态变为“使用中” } if err := s.pigFarmRepo.UpdatePenFields(tx, penID, updates); err != nil { s.logger.Errorf("更新猪批次猪栏失败: 添加猪栏 %d 失败: %v", penID, err) diff --git a/internal/app/service/pig_farm_service.go b/internal/app/service/pig_farm_service.go index d59347c..e4166c2 100644 --- a/internal/app/service/pig_farm_service.go +++ b/internal/app/service/pig_farm_service.go @@ -16,8 +16,8 @@ var ( ErrHouseNotFound = errors.New("指定的猪舍不存在") ErrPenInUse = errors.New("猪栏正在被活跃批次使用，无法删除") ErrPenNotFound = errors.New("指定的猪栏不存在") - ErrPenStatusInvalidForOccupiedPen = errors.New("猪栏已被批次占用，无法设置为非占用状态") - ErrPenStatusInvalidForUnoccupiedPen = errors.New("猪栏未被批次占用，无法设置为占用状态") + ErrPenStatusInvalidForOccupiedPen = errors.New("猪栏已被批次使用，无法设置为非使用中状态") + ErrPenStatusInvalidForUnoccupiedPen = errors.New("猪栏未被批次使用，无法设置为使用中状态") ) // PigFarmService 提供了猪场资产管理的业务逻辑 @@ -217,12 +217,12 @@ func (s *pigFarmService) UpdatePenStatus(id uint, newStatus models.PenStatus) (* } // 业务逻辑：根据猪栏的 PigBatchID 和当前状态，判断是否允许设置为 newStatus - if pen.PigBatchID != nil && *pen.PigBatchID != 0 { // 猪栏已被批次占用 - if newStatus == models.PenStatusEmpty { // 猪栏已被批次占用，不能直接设置为空闲 + if pen.PigBatchID != nil && *pen.PigBatchID != 0 { // 猪栏已被批次使用 + if newStatus == models.PenStatusEmpty { // 猪栏已被批次使用，不能直接设置为空闲 return ErrPenStatusInvalidForOccupiedPen } - } else { // 猪栏未被批次占用 (PigBatchID == nil) - if newStatus == models.PenStatusOccupied { // 猪栏未被批次占用，不能设置为占用 + } else { // 猪栏未被批次使用 (PigBatchID == nil) + if newStatus == models.PenStatusOccupied { // 猪栏未被批次使用，不能设置为使用中 return ErrPenStatusInvalidForUnoccupiedPen } } diff --git a/internal/core/application.go b/internal/core/application.go index ce85f66..ef9b7bc 100644 --- a/internal/core/application.go +++ b/internal/core/application.go @@ -78,7 +78,7 @@ func NewApplication(configPath string) (*Application, error) { unitOfWork := repository.NewGormUnitOfWork(storage.GetDB(), logger) // --- 业务逻辑处理器初始化 --- - pigFarmService := service.NewPigFarmService(pigFarmRepo, logger) + pigFarmService := service.NewPigFarmService(pigFarmRepo, unitOfWork, logger) pigBatchService := service.NewPigBatchService(pigBatchRepo, pigFarmRepo, unitOfWork, logger) // 初始化审计服务 diff --git a/internal/infra/models/farm_asset.go b/internal/infra/models/farm_asset.go index 28e7c05..7d5731c 100644 --- a/internal/infra/models/farm_asset.go +++ b/internal/infra/models/farm_asset.go @@ -21,7 +21,7 @@ type PenStatus string const ( PenStatusEmpty PenStatus = "空闲" - PenStatusOccupied PenStatus = "占用" + PenStatusOccupied PenStatus = "使用中" PenStatusSickPen PenStatus = "病猪栏" PenStatusRecovering PenStatus = "康复栏" PenStatusCleaning PenStatus = "清洗消毒"