pig-farm-controller - Technical Specification

Author: 主人 Date: 2025年11月1日星期六 Project Level: 0 Project Type: software Development Context: Brownfield Level 0 - Single Atomic Change: Implementing usage checks before deleting devices, device templates, and regional controllers to prevent data inconsistency and errors.

Source Tree Structure

# 涉及文件（初步判断，**请在实际开发中根据代码结构进行确认**）：
# internal/app/controller/device_controller.go (处理设备删除请求)
# internal/app/controller/device_template_controller.go (处理设备模板删除请求)
# internal/app/controller/region_controller.go (处理区域主控删除请求)
# internal/app/service/device_service.go (设备业务逻辑，可能包含删除操作)
# internal/app/service/device_template_service.go (设备模板业务逻辑，可能包含删除操作)
# internal/app/service/region_service.go (区域主控业务逻辑，可能包含删除操作)
# internal/infra/repository/device_repository.go (设备数据访问层)
# internal/infra/repository/device_template_repository.go (设备模板数据访问层)
# internal/infra/repository/region_repository.go (区域主控数据访问层)

Technical Approach

在删除设备、设备模板和区域主控的 API 接口和业务逻辑层中，引入使用状态检查。

识别依赖关系： 确定哪些实体依赖于设备、设备模板和区域主控。例如，设备可能依赖于设备模板，区域主控可能包含多个设备。
实现检查逻辑： 在执行删除操作之前，查询相关数据表，检查待删除实体是否被其他实体引用。
返回错误信息：： 如果发现实体正在被使用，则返回明确的错误信息，阻止删除操作。
事务性操作： 确保检查和删除操作的原子性，防止并发问题。

Implementation Stack

Go: 核心编程语言
GORM: ORM 框架，用于数据库操作
Echo: Web 框架，用于处理 HTTP 请求
PostgreSQL with TimescaleDB: 数据库 (通过 TimescaleDB 进行时序表加强)

Technical Details

设备删除检查：
- 在 internal/app/service/device_service.go 的 DeleteDevice 方法中实现。
- 依赖关系识别：
  - 任务关联： 检查 task 表中是否存在 device_id 关联的活跃任务（例如 running 或 pending 状态）。
  - 数据点（历史记录）： 检查 data_point 表或其他相关历史数据表中是否存在与该设备关联的数据。特别注意 TimescaleDB 的时序表特性，确保查询效率。
  - 告警/事件： 检查 alert 或 event 表中是否存在与该设备相关的未关闭记录。
  - 配置引用： 检查其他配置表（例如 schedule 表的特定设备配置）是否引用该设备。
- 检查逻辑：
  - 通过数据库查询或调用其他服务接口，检查上述依赖。
- 错误处理： 如果发现任何依赖，返回自定义业务错误码（例如 ERR_DEVICE_IN_USE）和描述性错误信息，通过 API 返回 409 Conflict 状态码。确保错误信息清晰、具体，并能指导用户采取下一步行动。
设备模板删除检查：
- 在 internal/app/service/device_template_service.go 的 DeleteDeviceTemplate 方法中实现。
- 依赖关系识别：
  - 设备引用： 检查 device 表中是否存在 template_id 关联的设备实例。
  - 历史配置： 检查是否有历史配置或归档数据仍引用此模板。
- 检查逻辑：
  - 查询 device 表，计算使用该模板的设备数量。
- 错误处理： 如果存在设备正在使用该模板，返回业务错误码（例如 ERR_TEMPLATE_IN_USE）和错误信息，通过 API 返回 409 Conflict 状态码。错误信息应明确指出哪些设备正在使用该模板。
区域主控删除检查：
- 在 internal/app/service/region_service.go 的 DeleteRegion 方法中实现。
- 依赖关系识别：
  - 设备关联： 检查 device 表中是否存在 region_id 关联的设备实例。
  - 子区域嵌套： 检查 region 表中是否存在 parent_region_id 关联的子区域。
  - 用户/权限关联： 检查 user_region_access 或类似权限表中是否存在与该区域关联的访问权限配置。
- 检查逻辑：
  - 查询 device 表和 region 表，计算关联的设备和子区域数量。
- 错误处理： 如果存在关联实体，返回业务错误码（例如 ERR_REGION_IN_USE）和错误信息，通过 API 返回 409 Conflict 状态码。错误信息应明确指出哪些设备或子区域正在使用该区域主控。
错误处理统一化：
- 定义一个中心化的错误处理机制，例如使用一个 errors 包来封装自定义错误类型（UsageConflictError）和错误码。
- API 层 (internal/app/controller) 捕获这些业务错误，并将其转换为适当的 HTTP 响应，例如 http.StatusConflict (409)。
- 确保错误信息清晰、用户友好，并可供前端进行翻译或展示。错误信息应尽可能提供解决问题的建议。

Development Setup

无需特殊开发环境设置，遵循现有项目 Go 开发规范。

Implementation Guide

定位删除逻辑： 找到 device_service.go、device_template_service.go 和 region_service.go 中对应的删除方法。
添加依赖检查函数： 在每个删除方法内部或其调用的辅助函数中，实现检查逻辑。
集成错误处理： 在检查失败时，返回自定义错误或使用现有错误处理机制。
编写单元测试： 为新的检查逻辑编写单元测试，覆盖删除成功和删除失败（因被使用）的场景。
编写集成测试： 编写集成测试，模拟删除操作，验证端到端的行为。

Testing Approach

单元测试：
- 针对 device_service.go、device_template_service.go 和 region_service.go 中的检查逻辑编写单元测试。
- 模拟有依赖和无依赖的场景，验证删除操作的行为。
集成测试：
- 编写 API 集成测试，模拟删除设备、设备模板和区域主控的请求。
- 测试在有依赖和无依赖情况下的 API 响应（HTTP 状态码和错误信息）。
手动测试：
- 在开发环境中，手动创建依赖关系，然后尝试删除被使用的实体，验证系统行为。
- 手动创建无依赖的实体，验证可以正常删除。

Deployment Strategy

代码审查： 提交代码进行严格的代码审查。
CI/CD 流程： 通过现有的 CI/CD 流程进行自动化测试和部署。
灰度发布： 如果可能，采用灰度发布策略，逐步将更改部署到生产环境，监控系统行为。
回滚计划： 制定详细且经过测试的回滚计划，以防出现意外问题，确保在紧急情况下能够快速恢复。

7.2 KiB Raw Blame History Unescape Escape