bmad 架构师工作

bmad/bmm-workflow-status.yaml

@@ -28,16 +28,24 @@ project_level: "0"
 field_type: "brownfield"
 workflow_path: "brownfield-level-0.yaml"
 
-workflow_status: "
+workflow_status:
   # Prerequisite: Documentation
   document-project: bmad/deep-dive-deletion-logic.md
 
   # Phase 1: Analysis
-  brainstorm-project: optional
+  brainstorm-project: skipped
 
   # Phase 2: Planning
-  tech-spec: required
+  tech-spec: C:\Users\divano\Desktop\work\AA-Pig\pig-farm-controller\bmad\tech-spec.md
 
   # Phase 4: Implementation
   sprint-planning: required
-"
+
+STORIES_SEQUENCE: [delete-usage-check]
+TODO_STORY: delete-usage-check
+TODO_TITLE: 为删除操作添加使用状态检查
+IN_PROGRESS_STORY: (empty)
+STORIES_DONE: []
+
+current_workflow: "tech-spec (Level 0 - generating tech spec)"
+progress_percentage: 40

bmad/core/config.yaml

@@ -3,7 +3,7 @@
 # Version: 6.0.0-alpha.3
 # Date: 2025-11-01T09:44:39.652Z
 
-user_name: 主人
+user_name: huang
 communication_language: 中文
 document_output_language: 中文
 output_folder: '{project-root}/bmad'

bmad/stories/story-delete-usage-check.md

@@ -0,0 +1,72 @@
+# Story: 为删除操作添加使用状态检查
+
+Status: Draft
+
+## Story
+
+As a 开发者,
+I want 在删除设备、设备模板和区域主控时，系统能自动检查它们是否处于被使用状态,
+so that 避免误删除正在使用的关键数据，确保系统数据完整性和稳定性.
+
+## Acceptance Criteria
+
+*   **单元测试：**
+    *   针对 `device_service.go`、`device_template_service.go` 和 `region_service.go` 中的检查逻辑编写单元测试。
+    *   模拟有依赖和无依赖的场景，验证删除操作的行为。
+*   **集成测试：**
+    *   编写 API 集成测试，模拟删除设备、设备模板和区域主控的请求。
+    *   测试在有依赖和无依赖情况下的 API 响应（HTTP 状态码和错误信息）。
+    *   同时，验证数据库中的数据状态是否符合预期（例如，被依赖的实体未被删除）。
+*   **手动测试：**
+    *   在开发环境中，手动创建依赖关系，然后尝试删除被使用的实体，验证系统行为。
+    *   手动创建无依赖的实体，验证可以正常删除。
+
+## Tasks / Subtasks
+
+*   定位删除逻辑：找到 `device_service.go`、`device_template_service.go` 和 `region_service.go` 中对应的删除方法。
+*   添加依赖检查函数：在每个删除方法内部或其调用的辅助函数中，实现检查逻辑。
+*   集成错误处理：在检查失败时，返回自定义错误或使用现有错误处理机制。
+*   编写单元测试：为新的检查逻辑编写单元测试，覆盖删除成功和删除失败（因被使用）的场景。
+*   编写集成测试：编写集成测试，模拟删除操作，验证端到端的行为。
+
+## Dev Notes
+
+### Technical Summary
+
+在删除设备、设备模板和区域主控的 API 接口和业务逻辑层中，引入使用状态检查。
+识别依赖关系，实现检查逻辑，返回明确的错误信息，阻止删除操作。
+确保检查和删除操作的原子性。
+使用 Echo 框架和 PostgreSQL with TimescaleDB。
+
+### Project Structure Notes
+
+- Files to modify: 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
+- Expected test locations: internal/app/service/device_service_test.go (假设), internal/app/service/device_template_service_test.go (假设), internal/app/service/region_service_test.go (假设), API 集成测试文件 (假设)
+- Estimated effort: 2 story points (2 天)
+
+### References
+
+- **Tech Spec:** See tech-spec.md for detailed implementation
+- **Architecture:** tech-spec.md
+
+## Dev Agent Record
+
+### Context Reference
+
+<!-- Path(s) to story context XML will be added here by context workflow -->
+
+### Agent Model Used
+
+<!-- Will be populated during dev-story execution -->
+
+### Debug Log References
+
+<!-- Will be populated during dev-story execution -->
+
+### Completion Notes List
+
+<!-- Will be populated during dev-story execution -->
+
+### File List
+
+<!-- Will be populated during dev-story execution -->

bmad/tech-spec.md

@@ -0,0 +1,121 @@
+# 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 接口和业务逻辑层中，引入使用状态检查。
+1.  **识别依赖关系：** 确定哪些实体依赖于设备、设备模板和区域主控。例如，设备可能依赖于设备模板，区域主控可能包含多个设备。
+2.  **实现检查逻辑：** 在执行删除操作之前，查询相关数据表，检查待删除实体是否被其他实体引用。
+3.  **返回错误信息：：** 如果发现实体正在被使用，则返回明确的错误信息，阻止删除操作。
+4.  **事务性操作：** 确保检查和删除操作的原子性，防止并发问题。
+
+---
+
+## Implementation Stack
+
+*   **Go**: 核心编程语言
+*   **GORM**: ORM 框架，用于数据库操作
+*   **Echo**: Web 框架，用于处理 HTTP 请求
+*   **PostgreSQL with TimescaleDB**: 数据库 (通过 TimescaleDB 进行时序表加强)
+
+---
+
+## Technical Details
+
+1.  **设备删除检查：**
+    *   在 `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` 状态码。**确保错误信息清晰、具体，并能指导用户采取下一步行动。**
+
+2.  **设备模板删除检查：**
+    *   在 `internal/app/service/device_template_service.go` 的 `DeleteDeviceTemplate` 方法中实现。
+    *   **依赖关系识别：**
+        *   **设备引用：** 检查 `device` 表中是否存在 `template_id` 关联的设备实例。
+        *   **历史配置：** 检查是否有历史配置或归档数据仍引用此模板。
+    *   **检查逻辑：**
+        *   查询 `device` 表，计算使用该模板的设备数量。
+    *   **错误处理：** 如果存在设备正在使用该模板，返回业务错误码（例如 `ERR_TEMPLATE_IN_USE`）和错误信息，通过 API 返回 `409 Conflict` 状态码。**错误信息应明确指出哪些设备正在使用该模板。**
+
+3.  **区域主控删除检查：**
+    *   在 `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` 状态码。**错误信息应明确指出哪些设备或子区域正在使用该区域主控。**
+
+4.  **错误处理统一化：**
+    *   定义一个中心化的错误处理机制，例如使用一个 `errors` 包来封装自定义错误类型（`UsageConflictError`）和错误码。
+    *   API 层 (`internal/app/controller`) 捕获这些业务错误，并将其转换为适当的 HTTP 响应，例如 `http.StatusConflict (409)`。
+    *   确保错误信息清晰、用户友好，并可供前端进行翻译或展示。**错误信息应尽可能提供解决问题的建议。**
+
+---
+
+## Development Setup
+
+无需特殊开发环境设置，遵循现有项目 Go 开发规范。
+
+---
+
+## Implementation Guide
+
+1.  **定位删除逻辑：** 找到 `device_service.go`、`device_template_service.go` 和 `region_service.go` 中对应的删除方法。
+2.  **添加依赖检查函数：** 在每个删除方法内部或其调用的辅助函数中，实现检查逻辑。
+3.  **集成错误处理：** 在检查失败时，返回自定义错误或使用现有错误处理机制。
+4.  **编写单元测试：** 为新的检查逻辑编写单元测试，覆盖删除成功和删除失败（因被使用）的场景。
+5.  **编写集成测试：** 编写集成测试，模拟删除操作，验证端到端的行为。
+
+---
+
+## Testing Approach
+
+*   **单元测试：**
+    *   针对 `device_service.go`、`device_template_service.go` 和 `region_service.go` 中的检查逻辑编写单元测试。
+    *   模拟有依赖和无依赖的场景，验证删除操作的行为。
+*   **集成测试：**
+    *   编写 API 集成测试，模拟删除设备、设备模板和区域主控的请求。
+    *   测试在有依赖和无依赖情况下的 API 响应（HTTP 状态码和错误信息）。
+*   **手动测试：**
+    *   在开发环境中，手动创建依赖关系，然后尝试删除被使用的实体，验证系统行为。
+    *   手动创建无依赖的实体，验证可以正常删除。
+
+---
+
+## Deployment Strategy
+
+*   **代码审查：** 提交代码进行严格的代码审查。
+*   **CI/CD 流程：** 通过现有的 CI/CD 流程进行自动化测试和部署。
+*   **灰度发布：** 如果可能，采用灰度发布策略，逐步将更改部署到生产环境，监控系统行为。
+*   **回滚计划：** 制定详细且经过测试的回滚计划，以防出现意外问题，**确保在紧急情况下能够快速恢复。**