diff --git a/bmad/bmm-workflow-status.yaml b/bmad/bmm-workflow-status.yaml index 0c17e21..f643253 100644 --- a/bmad/bmm-workflow-status.yaml +++ b/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 -" \ No newline at end of file + +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 \ No newline at end of file diff --git a/bmad/core/config.yaml b/bmad/core/config.yaml index ea6e9e7..04f96ed 100644 --- a/bmad/core/config.yaml +++ b/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' diff --git a/bmad/stories/story-delete-usage-check.md b/bmad/stories/story-delete-usage-check.md new file mode 100644 index 0000000..748d322 --- /dev/null +++ b/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 + + + +### Agent Model Used + + + +### Debug Log References + + + +### Completion Notes List + + + +### File List + + diff --git a/bmad/tech-spec.md b/bmad/tech-spec.md new file mode 100644 index 0000000..8d27eb7 --- /dev/null +++ b/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 流程进行自动化测试和部署。 +* **灰度发布：** 如果可能，采用灰度发布策略，逐步将更改部署到生产环境，监控系统行为。 +* **回滚计划：** 制定详细且经过测试的回滚计划，以防出现意外问题，**确保在紧急情况下能够快速恢复。**