@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-test-case/references/guide.md

@@ -0,0 +1,290 @@
+# 测试用例基础指南（test-case）
+
+> 测试用例设计原则 + 覆盖率要求。
+
+---
+
+## 1. 测试类型
+
+| 类型 | 范围 | 工具 |
+|------|------|------|
+| 单元测试 | 方法 / 类 | JUnit 5 + Mockito |
+| 集成测试 | Controller / Repository / Feign | @SpringBootTest + Testcontainers |
+| E2E 测试 | 完整流程 | Playwright / Cypress |
+| 性能测试 | 压力 / 负载 | JMeter / k6 |
+
+## 2. 覆盖率要求
+
+| 层级 | 覆盖率 | 说明 |
+|------|--------|------|
+| Service 层 | ≥ 80% | 业务核心 |
+| Controller 层 | ≥ 70% | 接口验证 |
+| Util | ≥ 90% | 工具方法 |
+| Repository 层 | ≥ 60% | 自定义查询方法 |
+
+CI 门禁：覆盖率 < 80% 阻断合并。
+
+## 3. 测试用例结构
+
+```java
+// AAA 模式：Arrange / Act / Assert
+@Test
+void createOrder_success() {
+    // Arrange（准备）
+    OrderRequest req = new OrderRequest("ORD001", new BigDecimal("1000"), "10001");
+
+    // Act（执行）
+    OrderDTO result = orderService.create(req);
+
+    // Assert（断言）
+    assertNotNull(result);
+    assertEquals("ORD001", result.getOrderNo());
+    assertEquals(OrderStatus.PENDING, result.getStatus());
+}
+```
+
+## 4. 命名规范
+
+```
+{方法名}_{场景}_{预期}
+```
+
+例：
+- `createOrder_success`
+- `createOrder_invalidAmount_throwsException`
+- `approveOrder_alreadyApproved_throwsException`
+- `findByUserId_emptyResult`
+
+## 5. 边界值测试
+
+### 5.1 数字字段
+
+```java
+@Test void amount_negative() { ... }     // 负数
+@Test void amount_zero() { ... }            // 零
+@Test void amount_max() { ... }           // 最大值
+@Test void amount_overflow() { ... }      // 溢出
+@Test void amount_decimal() { ... }       // 小数
+```
+
+### 5.2 字符串字段
+
+```java
+@Test void name_null() { ... }
+@Test void name_empty() { ... }
+@Test void name_blank() { ... }            // 全空格
+@Test void name_maxLength() { ... }
+@Test void name_specialChar() { ... }     // 特殊字符
+@Test void name_sqlInjection() { ... }   // ' " ; -- 等
+```
+
+### 5.3 日期字段
+
+```java
+@Test void date_null() { ... }
+@Test void date_invalid() { ... }        // 不合理日期
+@Test void date_future() { ... }
+@Test void date_format() { ... }
+```
+
+### 5.4 集合字段
+
+```java
+@Test void list_null() { ... }
+@Test void list_empty() { ... }
+@Test void list_single() { ... }
+@Test void list_huge() { ... }            // 性能
+```
+
+## 6. 异常路径测试
+
+```java
+@Test
+void createOrder_invalidAmount_throwsException() {
+    OrderRequest req = new OrderRequest("ORD001", new BigDecimal("-100"), "10001");
+
+    assertThrows(BizException.class, () -> {
+        orderService.create(req);
+    });
+
+    // 验证：订单未被创建
+    verify(orderRepository, never()).save(any(Order.class));
+}
+```
+
+## 7. Mock 使用
+
+### 7.1 Mock Repository
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock
+    private OrderRepository orderRepository;
+
+    @InjectMocks
+    private OrderServiceImpl orderService;
+
+    @Test
+    void getById_exists() {
+        Order order = new Order();
+        order.setId("ORD001");
+        when(orderRepository.findById("ORD001")).thenReturn(Optional.of(order));
+
+        OrderDTO result = orderService.getById("ORD001");
+
+        assertEquals("ORD001", result.getId());
+    }
+}
+```
+
+### 7.2 Mock Feign
+
+```java
+@MockBean
+private IUserClient userClient;
+
+@Test
+void listOrders() {
+    when(userClient.listByIds(any())).thenReturn(List.of(
+        new UserDTO("10001", "张三")
+    ));
+
+    // ...
+}
+```
+
+## 8. 数据准备
+
+### 8.1 @BeforeEach
+
+```java
+@BeforeEach
+void setUp() {
+    // 每个测试前执行
+    order = new Order();
+    order.setId("ORD001");
+    order.setStatus(OrderStatus.PENDING);
+}
+```
+
+### 8.2 Test Data Builder
+
+```java
+public class OrderBuilder {
+    private String orderNo = "ORD001";
+    private BigDecimal amount = new BigDecimal("1000");
+    private String userId = "10001";
+
+    public OrderBuilder withAmount(BigDecimal amount) {
+        this.amount = amount;
+        return this;
+    }
+
+    public Order build() {
+        Order order = new Order();
+        order.setOrderNo(orderNo);
+        order.setAmount(amount);
+        order.setUserId(userId);
+        return order;
+    }
+}
+
+// 用法
+Order order = new OrderBuilder().withAmount(new BigDecimal("5000")).build();
+```
+
+## 9. 软删除实体特殊用例
+
+详见 [code-dev-rules §八](../../rules/code-dev-rules.md)。
+
+```java
+// GEN-SOFT-DELETE：编号生成器跳过软删除
+@Test
+void generateNo_skipSoftDeleted() {
+    Project soft = new Project();
+    soft.setProjectNo("P001");
+    soft.setDeleted(true);
+    projectRepo.save(soft);
+
+    String next = generator.generateNext("P");
+    assertEquals("P002", next);
+}
+
+// DUP-SOFT-DELETE：service 校验拒软删除
+@Test
+void validateProjectNo_softDeleted_duplicate() {
+    Project soft = new Project();
+    soft.setProjectNo("P001");
+    soft.setDeleted(true);
+    projectRepo.save(soft);
+
+    assertThrows(ProjectNoDuplicateException.class, () -> {
+        service.createProject("P001");
+    });
+}
+```
+
+## 10. ❌ 反模式
+
+### 10.1 ❌ 测试方法无断言
+
+```java
+@Test
+void testCreate() {
+    orderService.create(req);  // 没断言
+}
+
+// ✅ 正确
+@Test
+void testCreate() {
+    OrderDTO result = orderService.create(req);
+    assertNotNull(result);
+    assertEquals("ORD001", result.getOrderNo());
+}
+```
+
+### 10.2 ❌ 测试互相依赖
+
+```java
+// ❌ 错：测试顺序依赖
+@Test
+void testA() { /* 创建数据 */ }
+
+@Test
+void testB() { /* 依赖 testA 创建的数据 */ }
+
+// ✅ 正确：每个测试独立
+@BeforeEach
+void setUp() { /* 创建数据 */ }
+```
+
+### 10.3 ❌ Mock 所有东西
+
+```java
+// ❌ 错：全 Mock，测的是 mock 行为
+when(userRepo.findById(any())).thenReturn(user);
+when(orderRepo.save(any())).thenReturn(order);
+when(notification.send(any())).thenReturn(true);
+orderService.create(req);  // 测的是 Mockito，不是业务
+
+// ✅ 正确：Mock 边界（外部依赖）
+when(userRepo.findById(any())).thenReturn(user);  // 外部
+orderService.create(req);  // 真业务
+```
+
+### 10.4 ❌ 只测正常路径
+
+```java
+// ❌ 错：只测正常
+@Test void createOrder() { ... }
+// 缺：异常路径、边界值
+```
+
+## 11. 关联阅读
+
+- [unit-test.md](unit-test.md) — 单元测试
+- [integration-test.md](integration-test.md) — 集成测试
+- [rules/test-case-dev-rules.md](../../rules/test-case-dev-rules.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-test-case/references/integration-test.md

@@ -0,0 +1,352 @@
+# 集成测试（test-case）
+
+> Controller / Repository / Feign 集成测试。
+
+---
+
+## 1. Controller 集成测试
+
+### 1.1 @WebMvcTest
+
+```java
+@WebMvcTest(OrderController.class)
+class OrderControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private IOrderService orderService;
+
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    @Test
+    void createOrder_success() throws Exception {
+        OrderDTO result = new OrderDTO();
+        result.setOrderNo("ORD001");
+        when(orderService.create(any())).thenReturn(result);
+
+        mockMvc.perform(post("/api/v1/orders")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(objectMapper.writeValueAsString(newOrderRequest())))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.data.orderNo").value("ORD001"));
+    }
+
+    @Test
+    void createOrder_invalidParams_badRequest() throws Exception {
+        mockMvc.perform(post("/api/v1/orders")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{}"))  // 缺必填
+            .andExpect(status().isBadRequest());
+    }
+}
+```
+
+### 1.2 @SpringBootTest（完整集成）
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+class OrderControllerIntegrationTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Autowired
+    private OrderRepository orderRepository;
+
+    @BeforeEach
+    void setUp() {
+        orderRepository.deleteAll();  // 清理
+    }
+
+    @Test
+    void fullFlow() throws Exception {
+        // 1. 创建
+        mockMvc.perform(post("/api/v1/orders")
+                .header("Authorization", "Bearer " + getTestToken())
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("..."))
+            .andExpect(status().isOk());
+
+        // 2. 验证 DB
+        List<Order> orders = orderRepository.findAll();
+        assertEquals(1, orders.size());
+    }
+}
+```
+
+## 2. Repository 集成测试
+
+### 2.1 @DataJpaTest
+
+```java
+@DataJpaTest
+class OrderRepositoryTest {
+
+    @Autowired
+    private OrderRepository orderRepository;
+
+    @Autowired
+    private TestEntityManager entityManager;
+
+    @Test
+    void findByOrderNo_businessQuery() {
+        // 业务查询（受 @Where 过滤）
+        Order order = new Order();
+        order.setOrderNo("ORD001");
+        entityManager.persist(order);
+        entityManager.flush();
+
+        Optional<Order> found = orderRepository.findByOrderNo("ORD001");
+        assertTrue(found.isPresent());
+    }
+
+    @Test
+    void findByOrderNoIncludingDeleted() {
+        // 准备软删除数据
+        Order order = new Order();
+        order.setOrderNo("ORD001");
+        order.setDeleted(true);
+        entityManager.persist(order);
+        entityManager.flush();
+
+        // 业务查询看不到
+        assertFalse(orderRepository.findByOrderNo("ORD001").isPresent());
+
+        // 全量查询能看到
+        assertTrue(orderRepository.findByOrderNoIncludingDeleted("ORD001").isPresent());
+    }
+}
+```
+
+### 2.2 Testcontainers（真实 DB）
+
+```java
+@SpringBootTest
+@Testcontainers
+class OrderRepositoryIntegrationTest {
+
+    @Container
+    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
+        .withDatabaseName("test")
+        .withUsername("test")
+        .withPassword("test");
+
+    @DynamicPropertySource
+    static void configure(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", mysql::getJdbcUrl);
+        registry.add("spring.datasource.username", mysql::getUsername);
+        registry.add("spring.datasource.password", mysql::getPassword);
+    }
+
+    @Autowired
+    private OrderRepository orderRepository;
+
+    @Test
+    void complexQuery() {
+        // ...真实 MySQL 测试
+    }
+}
+```
+
+## 3. Feign 集成测试
+
+### 3.1 @MockBean Feign Client
+
+```java
+@SpringBootTest
+class OrderServiceFeignIntegrationTest {
+
+    @MockBean
+    private IUserClient userClient;
+
+    @Autowired
+    private OrderService orderService;
+
+    @Test
+    void listOrders_batchLoadUsers() {
+        when(userClient.listByIds(any())).thenReturn(List.of(
+            new UserDTO("10001", "张三"),
+            new UserDTO("10002", "李四")
+        ));
+
+        List<OrderDTO> orders = orderService.list();
+
+        // 验证 Feign 被调用一次（批量）
+        verify(userClient, times(1)).listByIds(any());
+    }
+}
+```
+
+### 3.2 WireMock（真实 HTTP）
+
+```java
+@SpringBootTest
+@AutoConfigureWireMock(port = 0)
+class OrderServiceWireMockTest {
+
+    @Autowired
+    private OrderService orderService;
+
+    @Test
+    void listOrders_realHttp() {
+        // 模拟平台用户服务响应
+        stubFor(get(urlEqualTo("/api/v1/users"))
+            .willReturn(aResponse()
+                .withStatus(200)
+                .withHeader("Content-Type", "application/json")
+                .withBody("[{\"userId\":\"10001\",\"realName\":\"张三\"}]")));
+
+        List<OrderDTO> orders = orderService.list();
+
+        assertEquals(1, orders.size());
+        verify(getRequestedFor(urlEqualTo("/api/v1/users")));
+    }
+}
+```
+
+## 4. 测试配置
+
+### 4.1 application-test.yml
+
+```yaml
+spring:
+  datasource:
+    url: jdbc:h2:mem:test
+    username: sa
+    password: ""
+  jpa:
+    hibernate:
+      ddl-auto: create-drop
+
+nacos:
+  server-addr: localhost:8848
+  discovery:
+    enabled: false
+
+# 关闭不需要的服务
+feign:
+  hystrix:
+    enabled: false
+```
+
+### 4.2 测试 Profile
+
+```java
+@ActiveProfiles("test")
+@SpringBootTest
+class IntegrationTest { ... }
+```
+
+## 5. 测试用例隔离
+
+### 5.1 @Transactional（自动回滚）
+
+```java
+@SpringBootTest
+@Transactional   // 每个测试回滚
+class OrderServiceIntegrationTest {
+
+    @Test
+    void createOrder() {
+        orderService.create(req);
+        // 测试结束自动回滚
+    }
+}
+```
+
+### 5.2 手动清理
+
+```java
+@AfterEach
+void cleanUp() {
+    orderRepository.deleteAll();
+    userRepository.deleteAll();
+}
+```
+
+### 5.3 测试数据隔离
+
+```java
+// 用 @Sql 加载测试数据
+@Sql(scripts = "/sql/test-data.sql")
+@Test
+void listOrders() { ... }
+
+// 用 @Sql 清空
+@Sql(scripts = "/sql/clean-data.sql", executionPhase = AFTER_TEST_METHOD)
+@Test
+void test() { ... }
+```
+
+## 6. 异步 / MQ 测试
+
+```java
+@SpringBootTest
+class MessagePublishTest {
+
+    @Autowired
+    private MessagePublisher publisher;
+
+    @MockBean
+    private KafkaTemplate<String, String> kafkaTemplate;
+
+    @Test
+    void publishMessage() {
+        publisher.publish("test-topic", "test-message");
+
+        verify(kafkaTemplate).send(eq("test-topic"), eq("test-message"));
+    }
+}
+```
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ 集成测试当单元测试写
+
+```java
+// ❌ 错：起整个 Spring 测一个简单方法
+@SpringBootTest
+class CalculatorTest {
+    @Test
+    void add() {
+        assertEquals(4, calculator.add(2, 2));
+    }
+}
+
+// ✅ 正确：单元测试
+class CalculatorTest {
+    Calculator calculator = new Calculator();
+    @Test void add() { assertEquals(4, calculator.add(2, 2)); }
+}
+```
+
+### 7.2 ❌ 测试间数据污染
+
+```java
+// ❌ 错：不清理
+@Test void testA() { repo.save(user); }
+@Test void testB() {  // testA 的 user 残留
+    List<User> all = repo.findAll();  // 含 testA 的 user
+}
+```
+
+✅ @Transactional 回滚 / @AfterEach 清理。
+
+### 7.3 ❌ 集成测试用真实外部服务
+
+```java
+// ❌ 错
+@FeignClient(url = "https://api.real-platform.com")  // 真实环境
+```
+
+✅ WireMock / @MockBean。
+
+## 8. 关联阅读
+
+- [guide.md](guide.md) — 测试用例基础
+- [unit-test.md](unit-test.md) — 单元测试
+- [SKILL.md](../SKILL.md)