@xulthekl/team-flow 0.33.0 → 0.34.0

package/skills/test-strategy/references/integration-test-isolation.md

@@ -0,0 +1,346 @@
+# Integration Test Isolation（集成测试隔离分级）
+
+> 来源：glaf4-test h2-rabbitmq-redis.md 的隔离策略（v0.13 §59）
+> 用途：集成测试的分层策略，write-integration-worker 参考
+
+---
+
+## 一、核心原则
+
+**测试隔离**：每个测试独立运行，不依赖其他测试的状态，不污染共享资源。
+
+**隔离级别**：
+- **L1：进程内隔离**（最严格）：H2、embedded-redis、rabbitmq-mock
+- **L2：事务隔离**：@Transactional 自动回滚
+- **L3：手动清理**：@AfterEach 手动清理资源
+- **L4：无隔离**（最宽松）：共享真实基础设施（仅限开发环境）
+
+---
+
+## 二、基础设施隔离策略
+
+### 1. 数据库（MySQL/PostgreSQL）
+
+| 策略 | 适用场景 | 实现方式 | 优缺点 |
+|------|---------|---------|--------|
+| **H2 内存库** | Repository 层测试 | `@DataJpaTest` + H2 依赖 | ✅ 快速、隔离 ❌ SQL 兼容性差异 |
+| **@Transactional** | Service 层测试 | 测试类加 `@Transactional` | ✅ 自动回滚 ❌ 异步操作不适用 |
+| **Testcontainers** | 需要真实数据库 | Docker 容器 | ✅ 真实环境 ❌ 慢、需要 Docker |
+
+**推荐**：
+- Repository 层：H2 内存库
+- Service 层：@Transactional（同步操作）
+- API 层：@Transactional 或 Testcontainers
+
+**H2 配置示例**：
+```yaml
+# application-test.yml
+spring:
+  datasource:
+    url: jdbc:h2:mem:testdb;MODE=MySQL;DATABASE_TO_UPPER=false
+    driver-class-name: org.h2.Driver
+  jpa:
+    hibernate:
+      ddl-auto: create-drop
+```
+
+### 2. 消息队列（RabbitMQ/Kafka）
+
+| 策略 | 适用场景 | 实现方式 | 优缺点 |
+|------|---------|---------|--------|
+| **rabbitmq-mock** | MQ 生产者测试 | `MockConnectionFactory` | ✅ 快速、隔离 ❌ 不测试真实 MQ |
+| **embedded broker** | MQ 消费者测试 | embedded-rabbitmq | ✅ 真实协议 ❌ 慢、资源占用 |
+| **Testcontainers** | 端到端测试 | Docker 容器 | ✅ 真实环境 ❌ 慢、需要 Docker |
+
+**推荐**：
+- 生产者：rabbitmq-mock
+- 消费者：embedded broker 或 Testcontainers
+
+**rabbitmq-mock 配置示例**：
+```java
+@Configuration
+public class RabbitMockConfig {
+    @Bean
+    public ConnectionFactory connectionFactory() {
+        return new MockConnectionFactory();
+    }
+}
+```
+
+### 3. 缓存（Redis）
+
+| 策略 | 适用场景 | 实现方式 | 优缺点 |
+|------|---------|---------|--------|
+| **embedded-redis** | 缓存测试 | embedded-redis（port 6378） | ✅ 真实协议 ❌ ARM64 兼容问题 |
+| **mock** | 简单缓存逻辑 | Mockito mock | ✅ 快速 ❌ 不测试真实 Redis |
+| **Testcontainers** | 端到端测试 | Docker 容器 | ✅ 真实环境 ❌ 慢、需要 Docker |
+
+**推荐**：
+- 简单缓存逻辑：mock
+- 复杂缓存逻辑：embedded-redis
+
+**embedded-redis 配置示例**：
+```java
+@Configuration
+public class RedisTestConfig {
+    @Bean
+    public RedisServer redisServer() throws IOException {
+        RedisServer server = new RedisServer(6378);
+        server.start();
+        return server;
+    }
+}
+```
+
+### 4. 外部 HTTP（第三方 API）
+
+| 策略 | 适用场景 | 实现方式 | 优缺点 |
+|------|---------|---------|--------|
+| **MockWebServer** | HTTP 客户端测试 | OkHttp MockWebServer | ✅ 真实 HTTP 协议 ❌ 只测试客户端 |
+| **WireMock** | 复杂 API 模拟 | WireMock | ✅ 强大的模拟能力 ❌ 学习成本 |
+| **@MockBean** | Spring Cloud Feign | Mockito mock | ✅ 简单 ❌ 不测试真实 HTTP |
+
+**推荐**：
+- 简单 HTTP 客户端：MockWebServer
+- 复杂 API 模拟：WireMock
+- Feign 客户端：@MockBean
+
+**MockWebServer 配置示例**：
+```java
+@Test
+void testCallExternalApi() throws Exception {
+    MockWebServer server = new MockWebServer();
+    server.enqueue(new MockResponse()
+        .setBody("{\"status\":\"ok\"}")
+        .setHeader("Content-Type", "application/json"));
+
+    // 调用被测方法
+    String result = externalService.callApi();
+
+    // 验证请求
+    RecordedRequest request = server.takeRequest();
+    assertEquals("/api/data", request.getPath());
+    assertEquals("ok", result);
+
+    server.shutdown();
+}
+```
+
+---
+
+## 三、分层隔离策略
+
+### Repository 层
+
+**策略**：H2 内存库 + @Transactional
+
+**理由**：
+- Repository 层只测试 SQL 和映射逻辑
+- H2 内存库提供快速、隔离的测试环境
+- @Transactional 确保测试后数据回滚
+
+**示例**：
+```java
+@DataJpaTest
+@Transactional
+class UserRepositoryTest {
+    @Autowired
+    private UserRepository userRepository;
+
+    @Test
+    void testFindByEmail() {
+        // Arrange
+        User user = new User("John", "john@example.com");
+        userRepository.save(user);
+
+        // Act
+        Optional<User> found = userRepository.findByEmail("john@example.com");
+
+        // Assert
+        assertTrue(found.isPresent());
+        assertEquals("John", found.get().getName());
+    }
+    // 测试结束后自动回滚
+}
+```
+
+### Service 层
+
+**策略**：@Transactional（同步操作）或手动清理（异步操作）
+
+**理由**：
+- Service 层测试业务逻辑，需要真实依赖
+- 同步操作用 @Transactional 自动回滚
+- 异步操作需要手动清理（消息队列、缓存）
+
+**示例（同步）**：
+```java
+@SpringBootTest
+@Transactional
+class UserServiceTest {
+    @Autowired
+    private UserService userService;
+
+    @Autowired
+    private UserRepository userRepository;
+
+    @Test
+    void testCreateUser() {
+        // Arrange
+        CreateUserRequest request = new CreateUserRequest("John", "john@example.com");
+
+        // Act
+        User user = userService.createUser(request);
+
+        // Assert
+        assertNotNull(user.getId());
+        assertEquals("John", user.getName());
+    }
+    // 测试结束后自动回滚
+}
+```
+
+**示例（异步）**：
+```java
+@SpringBootTest
+class UserServiceAsyncTest {
+    @Autowired
+    private UserService userService;
+
+    @Autowired
+    private RabbitTemplate rabbitTemplate;
+
+    @AfterEach
+    void cleanup() {
+        // 手动清空消息队列
+        rabbitTemplate.execute(channel -> {
+            channel.queuePurge("user-events");
+            return null;
+        });
+    }
+
+    @Test
+    void testCreateUserSendsEvent() {
+        // Arrange
+        CreateUserRequest request = new CreateUserRequest("John", "john@example.com");
+
+        // Act
+        User user = userService.createUser(request);
+
+        // Assert
+        assertNotNull(user.getId());
+
+        // 验证消息发送
+        Message message = rabbitTemplate.receive("user-events", 1000);
+        assertNotNull(message);
+    }
+}
+```
+
+### API 层
+
+**策略**：MockMvc + @Transactional 或 Testcontainers
+
+**理由**：
+- API 层测试 HTTP 请求和响应
+- 使用 MockMvc 模拟 HTTP 请求
+- 数据库用 @Transactional 或 Testcontainers
+
+**示例**：
+```java
+@WebMvcTest(UserController.class)
+@Transactional
+class UserControllerTest {
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private UserService userService;
+
+    @Test
+    void testCreateUser() throws Exception {
+        // Arrange
+        User user = new User(1L, "John", "john@example.com");
+        when(userService.createUser(any())).thenReturn(user);
+
+        // Act & Assert
+        mockMvc.perform(post("/api/users")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{\"name\":\"John\",\"email\":\"john@example.com\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.name").value("John"));
+    }
+}
+```
+
+---
+
+## 四、隔离级别选择指南
+
+| 测试类型 | 隔离级别 | 推荐策略 |
+|---------|---------|---------|
+| **Repository 层** | L1 | H2 内存库 |
+| **Service 层（同步）** | L2 | @Transactional |
+| **Service 层（异步）** | L3 | 手动清理 |
+| **API 层（简单）** | L2 | MockMvc + @Transactional |
+| **API 层（复杂）** | L1 | MockMvc + H2 |
+| **端到端** | L1 | Testcontainers |
+
+---
+
+## 五、常见问题和解决方案
+
+### 1. 异步操作测试
+
+**问题**：@Transactional 不适用于异步操作（消息队列、异步方法）
+
+**解决方案**：
+- 使用 @AfterEach 手动清理
+- 使用 Awaitility 等待异步操作完成
+- 使用 embedded broker 替代 mock
+
+### 2. 外部依赖测试
+
+**问题**：外部 API 不可用或不稳定
+
+**解决方案**：
+- 使用 MockWebServer/WireMock 模拟外部 API
+- 使用 @MockBean mock Feign 客户端
+- 使用 Testcontainers 运行真实服务
+
+### 3. 测试数据污染
+
+**问题**：测试数据泄漏到其他测试
+
+**解决方案**：
+- 每个测试独立数据（Builder 模式）
+- 使用 @Transactional 自动回滚
+- 使用 @DirtContexts 标记需要重新加载上下文的测试
+
+### 4. 测试速度慢
+
+**问题**：Testcontainers 启动慢
+
+**解决方案**：
+- 使用 @Testcontainers 的 reuse 模式
+- 使用 H2 替代真实数据库（Repository 层）
+- 使用 mock 替代真实外部服务
+
+---
+
+## 六、与 glaf4-test 的关系
+
+本隔离策略参考了 glaf4-test 的以下规范：
+- **H2 替代 MySQL**：`MERGE INTO ... KEY(id)` 幂等写法、`MODE=MySQL;DATABASE_TO_UPPER=false`
+- **rabbitmq-mock**：`MockConnectionFactory → CachingConnectionFactory → firstRabbitTemplate`
+- **embedded-redis**：端口 6378、`@AutoConfigureBefore` Redisson config
+
+**注意**：glaf4-test 的部分配置是 GLAF4 框架专用的（如 `gtmc.glaf4.*` 配置键），本规范已抽象为通用模式。
+
+---
+
+## 变更记录
+
+| 日期 | 版本 | 变更内容 |
+|------|------|---------|
+| 2026-08-04 | v1.0 | 从 glaf4-test h2-rabbitmq-redis.md 抽取通用隔离策略 |

package/skills/test-strategy/references/test-quality-rules.md

@@ -0,0 +1,292 @@
+# Test Quality Rules（测试质量规则）
+
+> 来源：glaf4-test scan-generated-tests.py 的通用规则（v0.13 §56）
+> 用途：code-reviewer 在测试审查时参考，build-executor 在生成测试后自检
+
+---
+
+## 一、断言质量规则
+
+### 1. missing-meaningful-assertion
+
+**描述**：测试没有有效断言
+
+**检查**：
+- 测试方法中没有 `assert*`、`verify*`、`expect*` 等断言语句
+- 只有被测方法调用，没有验证结果
+
+**示例（违规）**：
+```java
+@Test
+void testGetUser() {
+    userService.getUser(1L);  // 没有断言
+}
+```
+
+**修正**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    assertNotNull(user);
+    assertEquals("John", user.getName());
+}
+```
+
+### 2. weak-assertion-only
+
+**描述**：只有弱断言（assertNotNull/isNotNull）
+
+**检查**：
+- 只有 `assertNotNull`、`assertThat(x).isNotNull()`
+- 没有验证具体属性值
+
+**示例（违规）**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    assertNotNull(user);  // 只验证非空，不验证内容
+}
+```
+
+**修正**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    assertNotNull(user);
+    assertEquals("John", user.getName());
+    assertEquals(25, user.getAge());
+}
+```
+
+### 3. verify-only-without-assertion
+
+**描述**：只有 mock verify，没有状态断言
+
+**检查**：
+- 只有 `verify(mock).method()`
+- 没有验证返回值或状态变化
+
+**示例（违规）**：
+```java
+@Test
+void testCreateUser() {
+    userService.createUser("John");
+    verify(userRepository).save(any());  // 只验证调用，不验证结果
+}
+```
+
+**修正**：
+```java
+@Test
+void testCreateUser() {
+    User user = userService.createUser("John");
+    assertNotNull(user);
+    assertEquals("John", user.getName());
+    verify(userRepository).save(any());
+}
+```
+
+---
+
+## 二、调试代码残留规则
+
+### 4. system-out / print-stack-trace
+
+**描述**：测试中有调试代码残留
+
+**检查**：
+- `System.out.println`
+- `System.err.println`
+- `e.printStackTrace()`
+- `console.log`（JavaScript）
+- `print()`（Python，非断言）
+
+**示例（违规）**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    System.out.println("User: " + user);  // 调试代码
+    assertNotNull(user);
+}
+```
+
+**修正**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    assertNotNull(user);
+    // 如需调试，使用日志框架或断点
+}
+```
+
+---
+
+## 三、测试状态规则
+
+### 5. disabled-test / unfinished-test-todo
+
+**描述**：禁用或未完成的测试
+
+**检查**：
+- `@Disabled`、`@Ignore`
+- `// TODO`、`// FIXME`
+- `pending`、`skip`（JavaScript/Python）
+
+**处理**：
+- 禁用的测试必须有注释说明原因
+- 未完成的测试不应提交到主分支
+
+---
+
+## 四、测试数据规则
+
+### 6. hardcoded-sample-like-value
+
+**描述**：检测到样本数据
+
+**检查**：
+- 手机号：`13xxxxxxxxx`、`15xxxxxxxxx`
+- 身份证：`110101199001011234`
+- 邮箱：`test@example.com`、`xxx@test.com`
+- 姓名：`张三`、`李四`、`John`、`Doe`
+- 地址：`北京市朝阳区xxx`
+- 数字：`123456`、`111111`、`000000`
+
+**处理**：
+- 使用有意义的测试数据（如业务相关的名称）
+- 或使用测试数据工厂（Builder/Fixture）
+
+### 7. real-external-url
+
+**描述**：测试中包含真实外部 URL
+
+**检查**：
+- `http://api.example.com`
+- `https://third-party-service.com`
+- 任何非 localhost/127.0.0.1 的 URL
+
+**处理**：
+- 使用 mock/stub 替代真实外部服务
+- 或使用 `@MockBean` / `WireMock`
+
+---
+
+## 五、测试结构规则
+
+### 8. large-test-class
+
+**描述**：测试类过大
+
+**检查**：
+- 测试方法数 > 20
+- 测试类行数 > 500
+
+**处理**：
+- 按功能拆分测试类
+- 使用 `@Nested` 分组
+
+### 9. generic-test-class-name
+
+**描述**：类名过于泛化
+
+**检查**：
+- `Test`、`Tests`、`TestSuite`
+- `ServiceTest`、`ControllerTest`（无具体功能描述）
+
+**示例（违规）**：
+```java
+class ServiceTest { ... }
+```
+
+**修正**：
+```java
+class UserServiceGetUserTest { ... }
+class UserServiceCreateUserTest { ... }
+```
+
+---
+
+## 六、矩阵对账规则
+
+### 10. case-method-not-found
+
+**描述**：矩阵中的 case 引用了不存在的测试方法
+
+**检查**：
+- test-matrix.md 中声明的 `test_method_name` 在测试代码中不存在
+
+### 11. case-test-file-mismatch
+
+**描述**：矩阵中的 case 与测试文件不匹配
+
+**检查**：
+- case 声明的 `test_tier` 与实际测试文件不符（如 unit case 写到了集成测试文件）
+
+### 12. evidence-not-in-method
+
+**描述**：矩阵中的 evidence 在测试方法中找不到
+
+**检查**：
+- case 声明的 `design_method` 对应的代码模式在测试方法中不存在
+
+### 13. extra-test-methods
+
+**描述**：测试文件中有未在矩阵中声明的方法
+
+**检查**：
+- 测试文件中的方法数 > 矩阵中的 case 数
+
+---
+
+## 七、语言特定规则
+
+### 14. Java 特定
+
+- 禁止 `throws Exception`（应显式捕获和断言异常）
+- 禁止 `System.out.println` 替代断言
+- 单元测试禁止 `@SpringBootTest`
+- 集成测试禁止只 mock 不验证
+
+### 15. JavaScript 特定
+
+- 禁止 `console.log` 替代断言
+- 禁止 `expect(true).toBe(true)`（无意义断言）
+- async 测试必须 await
+
+### 16. Python 特定
+
+- 禁止 `print()` 替代断言
+- 禁止 `assert True`（无意义断言）
+- 测试函数必须以 `test_` 开头
+
+---
+
+## 八、使用方式
+
+### build-executor 自检
+
+implementer 子代理生成测试后，按此规则自检：
+1. 检查断言质量（规则 1-3）
+2. 检查调试代码残留（规则 4）
+3. 检查测试数据（规则 6-7）
+4. 检查测试结构（规则 8-9）
+
+### code-reviewer 审查
+
+code-reviewer 在审查测试代码时，按此规则检查：
+1. 矩阵对账（规则 10-13）
+2. 语言特定规则（规则 14-16）
+3. 测试状态（规则 5）
+
+---
+
+## 变更记录
+
+| 日期 | 版本 | 变更内容 |
+|------|------|---------|
+| 2026-08-04 | v1.0 | 从 glaf4-test scan-generated-tests.py 抽取 15 条通用规则 |

package/skills/workflow-bootstrap/SKILL.md

@@ -62,6 +62,43 @@ Do NOT invoke for:
 
 详细流程（脚本采集项、子代理维度表、侦察内容树、已有文档处理）见 `references/b1-reconnaissance.md`。
 
+### B1.5: Conventions Generator（测试规范生成，v0.34.0 新增）
+
+> 来源：test-capability-enhancement-design v1.0 §四
+> 目的：根据项目技术栈自动生成测试规范 conventions，符合 glaf4-test 要求
+
+**触发条件**：B1 侦察完成后，检查 `.team-flow/conventions/` 是否存在
+
+**存量项目路径**：
+1. 读取 B1 侦察结果中的技术栈信息（从 baseline.md 提取）
+2. 根据技术栈选择 conventions 模板
+3. 复制到项目 `.team-flow/conventions/` 目录
+4. 更新 `.team-flow/conventions/.versions.json`
+5. 更新 `team-flow.config.json` 的 conventions 字段
+
+**全新项目路径**（未检测到技术栈特征）：
+1. 交互式引导用户选择技术栈
+   - 编程语言：Java / JavaScript / Python
+   - 构建工具：Maven / Gradle / npm / yarn / pip / poetry
+   - 测试框架：JUnit 5 + Mockito / Jest / Pytest
+   - 应用框架：Spring Boot / Express / Django / 无框架
+2. 根据用户选择选择 conventions 模板
+3. （可选）生成项目骨架（pom.xml / package.json / requirements.txt）
+4. 生成 conventions 文件
+
+**conventions 模板来源**：
+- plugin 内置模板：`${CLAUDE_PLUGIN_ROOT}/templates/conventions/`
+- 符合 glaf4-test 要求的模板：`${CLAUDE_PLUGIN_ROOT}/templates/conventions/glaf4-compliant/`
+
+**产出**：
+- `.team-flow/conventions/*.md` — 测试规范文件
+- `.team-flow/conventions/.versions.json` — 版本信息
+- `.team-flow/team-flow.config.json` — conventions 路径映射（更新）
+
+**跳过条件**：
+- `.team-flow/conventions/` 已存在 → 提示用户"conventions 已存在，是否更新？"
+- 用户拒绝 → 跳过
+
 ### B2: Architecture Baseline（架构基线文档化）
 
 **条件**：如果 B1 侦察发现项目有一定复杂度（≥5 个模块或 ≥10 个源文件），执行此阶段。否则跳过。
@@ -173,10 +210,10 @@ Step 2: 确定性提取（兜底）
 ## Output Standard
 
 每次交互结束时说明：
-1. 已完成的阶段（B1-B5）
-2. 已产出的制品（baseline.md / ARCHITECTURE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / CONCEPTS.md / 目录结构）
+1. 已完成的阶段（B1-B1.5-B2-B3-B4-B5）
+2. 已产出的制品（baseline.md / conventions / ARCHITECTURE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / CONCEPTS.md / 目录结构）
 3. 下一步建议（调用哪个 skill）
 
 ## Success Output
 
-接入结束时输出：侦察模式、产出清单（baseline.md / ARCHITECTURE.md / DATABASE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / docs/architecture/CONCEPTS.md / 目录结构）、关键发现（技术栈/模块数/架构模式/测试覆盖）、下一步建议。完整模板见 `references/b1-reconnaissance.md`「Success Output 模板」。
+接入结束时输出：侦察模式、产出清单（baseline.md / conventions / ARCHITECTURE.md / DATABASE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / docs/architecture/CONCEPTS.md / 目录结构）、关键发现（技术栈/模块数/架构模式/测试覆盖）、下一步建议。完整模板见 `references/b1-reconnaissance.md`「Success Output 模板」。