Merge remote-tracking branch 'origin/feature/environment-module' into feature/environment-module

docs/ops-architecture/part8-测试指南.md

@@ -0,0 +1,92 @@
+# Ops 模块测试指南
+
+本文档介绍了 Ops 模块（运维工单系统）的测试策略、核心测试类及执行方法。我们的测试重点在于验证业务逻辑的正确性和状态机转换的安全性。
+
+## 1. 测试策略概述
+
+Ops 模块的测试策略遵循 "金字塔模型"，侧重于 Service 层逻辑和状态机（FSM）的单元测试。
+
+*   **核心关注点**：
+    *   **状态机逻辑**：验证工单状态转换的合法性、非法转换拦截及幂等性。
+    *   **业务流程**：验证工单从创建、分配、接单到完成的标准流转（Happy Path）。
+    *   **边界情况**：验证特殊流程（如从排队中分配）及异常处理。
+*   **Mock 策略**：使用 Mockito 模拟数据库操作（Mapper）和外部依赖（如 Environment 模块、消息队列），确保测试聚焦于 Ops 模块自身的业务逻辑。
+
+## 2. 核心测试类
+
+我们主要通过以下两个测试类来保障核心功能的稳定性。
+
+### 2.1 OrderStateMachineTest
+位于：`viewsh-module-ops-biz/src/test/java/com/viewsh/module/ops/service/fsm/OrderStateMachineTest.java`
+
+*   **职责**：专门测试状态机 `OrderStateMachine` 的行为。
+*   **覆盖场景**：
+    *   **合法转换**：如 `PENDING` -> `DISPATCHED`，验证状态更新事件是否正确发布。
+    *   **非法转换**：如 `PENDING` -> `COMPLETED`，验证是否抛出 `IllegalStateException`。
+    *   **幂等性**：验证状态不变时（如 `PENDING` -> `PENDING`）是否跳过无用操作。
+    *   **状态查询**：验证 `getAllowedTransitions` 返回正确的允许目标状态列表。
+
+### 2.2 OpsOrderServiceTest
+位于：`viewsh-module-ops-biz/src/test/java/com/viewsh/module/ops/service/order/OpsOrderServiceTest.java`
+
+*   **职责**：测试工单服务 `OpsOrderService` 的业务方法。
+*   **覆盖场景**：
+    *   **CRUD**：验证 `createOrder`（含默认值填充）、`updateOrder`、`deleteOrder` 等基础操作。
+    *   **Happy Path**：模拟标准业务流：`assignOrder` (分配) -> `acceptOrder` (接单) -> `completeOrder` (完成)。
+    *   **Cleaning Flow**：验证保洁业务特有的流程，例如从 `QUEUED`（排队中）状态进行分配。
+    *   **生命周期委托**：验证 `pause`、`resume`、`cancel` 操作是否正确委托给 `OrderLifecycleManager`，确保与队列状态同步。
+
+## 3. 如何执行测试
+
+我们使用 Maven 来运行测试。
+
+### 运行所有 Ops 模块测试
+
+在项目根目录下执行：
+
+```bash
+mvn test -pl viewsh-module-ops/viewsh-module-ops-biz
+```
+
+### 运行特定测试类
+
+如果只想运行状态机的测试：
+
+```bash
+mvn test -Dtest=OrderStateMachineTest -pl viewsh-module-ops/viewsh-module-ops-biz
+```
+
+如果只想运行工单服务的测试：
+
+```bash
+mvn test -Dtest=OpsOrderServiceTest -pl viewsh-module-ops/viewsh-module-ops-biz
+```
+
+## 4. 测试覆盖范围说明
+
+*   **已覆盖**：
+    *   `OrderStateMachine` 的所有核心转换规则。
+    *   `OpsOrderServiceImpl` 的主要业务方法。
+    *   工单创建时的默认参数逻辑。
+    *   权限校验逻辑（如非执行人操作拦截）。
+*   **Mock / 未覆盖**：
+    *   **数据库交互**：Mapper 层被 Mock，不连接真实数据库。
+    *   **外部集成**：Environment 模块的交互、IoT 设备消息、Redis 队列操作均通过 Mock 处理。
+    *   **Controller 层**：目前仅测试 Service 层，API 接口测试不在本指南范围内。
+
+## 5. 既有规范回顾
+
+以下内容继承自原[Part 8: 测试指南]：
+
+### 5.1 依赖模拟 (Mocking)
+使用 `JUnit 5` 和 `Mockito`。
+- **核心原则**：Mock 掉 Mapper 层和外部 RPC 调用，专注验证 Service 层的状态转换逻辑。
+
+### 5.2 集成测试规范（未来计划）
+由于采用 Redis + MySQL 双写架构，未来的集成测试需重点验证：
+- 事务提交后，Redis 队列中的分数（Score）与优先级（Priority）是否匹配。
+- `QueueSyncHandler` 是否正确处理了缓存失效后的补偿逻辑。
+
+### 5.3 常用测试工具
+- **Podam**：用于快速生成填充了随机数据的 DO/DTO 对象。
+- **BaseDbAndRedisUnitTest**：支持 H2 内存数据库和内置 Redis 的集成测试基类。