aigroup-workflow 2.2.1 → 2.2.3

package/docs/rules/java/testing.md

@@ -1,131 +1,131 @@
----
-paths:
-  - "**/*.java"
----
-# Java Testing
-
-> This file extends [common/testing.md](../common/testing.md) with Java-specific content.
-
-## Test Framework
-
-- **JUnit 5** (`@Test`, `@ParameterizedTest`, `@Nested`, `@DisplayName`)
-- **AssertJ** for fluent assertions (`assertThat(result).isEqualTo(expected)`)
-- **Mockito** for mocking dependencies
-- **Testcontainers** for integration tests requiring databases or services
-
-## Test Organization
-
-```
-src/test/java/com/example/app/
-  service/           # Unit tests for service layer
-  controller/        # Web layer / API tests
-  repository/        # Data access tests
-  integration/       # Cross-layer integration tests
-```
-
-Mirror the `src/main/java` package structure in `src/test/java`.
-
-## Unit Test Pattern
-
-```java
-@ExtendWith(MockitoExtension.class)
-class OrderServiceTest {
-
-    @Mock
-    private OrderRepository orderRepository;
-
-    private OrderService orderService;
-
-    @BeforeEach
-    void setUp() {
-        orderService = new OrderService(orderRepository);
-    }
-
-    @Test
-    @DisplayName("findById returns order when exists")
-    void findById_existingOrder_returnsOrder() {
-        var order = new Order(1L, "Alice", BigDecimal.TEN);
-        when(orderRepository.findById(1L)).thenReturn(Optional.of(order));
-
-        var result = orderService.findById(1L);
-
-        assertThat(result.customerName()).isEqualTo("Alice");
-        verify(orderRepository).findById(1L);
-    }
-
-    @Test
-    @DisplayName("findById throws when order not found")
-    void findById_missingOrder_throws() {
-        when(orderRepository.findById(99L)).thenReturn(Optional.empty());
-
-        assertThatThrownBy(() -> orderService.findById(99L))
-            .isInstanceOf(OrderNotFoundException.class)
-            .hasMessageContaining("99");
-    }
-}
-```
-
-## Parameterized Tests
-
-```java
-@ParameterizedTest
-@CsvSource({
-    "100.00, 10, 90.00",
-    "50.00, 0, 50.00",
-    "200.00, 25, 150.00"
-})
-@DisplayName("discount applied correctly")
-void applyDiscount(BigDecimal price, int pct, BigDecimal expected) {
-    assertThat(PricingUtils.discount(price, pct)).isEqualByComparingTo(expected);
-}
-```
-
-## Integration Tests
-
-Use Testcontainers for real database integration:
-
-```java
-@Testcontainers
-class OrderRepositoryIT {
-
-    @Container
-    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");
-
-    private OrderRepository repository;
-
-    @BeforeEach
-    void setUp() {
-        var dataSource = new PGSimpleDataSource();
-        dataSource.setUrl(postgres.getJdbcUrl());
-        dataSource.setUser(postgres.getUsername());
-        dataSource.setPassword(postgres.getPassword());
-        repository = new JdbcOrderRepository(dataSource);
-    }
-
-    @Test
-    void save_and_findById() {
-        var saved = repository.save(new Order(null, "Bob", BigDecimal.ONE));
-        var found = repository.findById(saved.getId());
-        assertThat(found).isPresent();
-    }
-}
-```
-
-For Spring Boot integration tests, see skill: `springboot-tdd`.
-
-## Test Naming
-
-Use descriptive names with `@DisplayName`:
-- `methodName_scenario_expectedBehavior()` for method names
-- `@DisplayName("human-readable description")` for reports
-
-## Coverage
-
-- Target 80%+ line coverage
-- Use JaCoCo for coverage reporting
-- Focus on service and domain logic — skip trivial getters/config classes
-
-## References
-
-See skill: `springboot-tdd` for Spring Boot TDD patterns with MockMvc and Testcontainers.
-See skill: `java-coding-standards` for testing expectations.
+---
+paths:
+  - "**/*.java"
+---
+# Java Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Java-specific content.
+
+## Test Framework
+
+- **JUnit 5** (`@Test`, `@ParameterizedTest`, `@Nested`, `@DisplayName`)
+- **AssertJ** for fluent assertions (`assertThat(result).isEqualTo(expected)`)
+- **Mockito** for mocking dependencies
+- **Testcontainers** for integration tests requiring databases or services
+
+## Test Organization
+
+```
+src/test/java/com/example/app/
+  service/           # Unit tests for service layer
+  controller/        # Web layer / API tests
+  repository/        # Data access tests
+  integration/       # Cross-layer integration tests
+```
+
+Mirror the `src/main/java` package structure in `src/test/java`.
+
+## Unit Test Pattern
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock
+    private OrderRepository orderRepository;
+
+    private OrderService orderService;
+
+    @BeforeEach
+    void setUp() {
+        orderService = new OrderService(orderRepository);
+    }
+
+    @Test
+    @DisplayName("findById returns order when exists")
+    void findById_existingOrder_returnsOrder() {
+        var order = new Order(1L, "Alice", BigDecimal.TEN);
+        when(orderRepository.findById(1L)).thenReturn(Optional.of(order));
+
+        var result = orderService.findById(1L);
+
+        assertThat(result.customerName()).isEqualTo("Alice");
+        verify(orderRepository).findById(1L);
+    }
+
+    @Test
+    @DisplayName("findById throws when order not found")
+    void findById_missingOrder_throws() {
+        when(orderRepository.findById(99L)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> orderService.findById(99L))
+            .isInstanceOf(OrderNotFoundException.class)
+            .hasMessageContaining("99");
+    }
+}
+```
+
+## Parameterized Tests
+
+```java
+@ParameterizedTest
+@CsvSource({
+    "100.00, 10, 90.00",
+    "50.00, 0, 50.00",
+    "200.00, 25, 150.00"
+})
+@DisplayName("discount applied correctly")
+void applyDiscount(BigDecimal price, int pct, BigDecimal expected) {
+    assertThat(PricingUtils.discount(price, pct)).isEqualByComparingTo(expected);
+}
+```
+
+## Integration Tests
+
+Use Testcontainers for real database integration:
+
+```java
+@Testcontainers
+class OrderRepositoryIT {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");
+
+    private OrderRepository repository;
+
+    @BeforeEach
+    void setUp() {
+        var dataSource = new PGSimpleDataSource();
+        dataSource.setUrl(postgres.getJdbcUrl());
+        dataSource.setUser(postgres.getUsername());
+        dataSource.setPassword(postgres.getPassword());
+        repository = new JdbcOrderRepository(dataSource);
+    }
+
+    @Test
+    void save_and_findById() {
+        var saved = repository.save(new Order(null, "Bob", BigDecimal.ONE));
+        var found = repository.findById(saved.getId());
+        assertThat(found).isPresent();
+    }
+}
+```
+
+For Spring Boot integration tests, see skill: `springboot-tdd`.
+
+## Test Naming
+
+Use descriptive names with `@DisplayName`:
+- `methodName_scenario_expectedBehavior()` for method names
+- `@DisplayName("human-readable description")` for reports
+
+## Coverage
+
+- Target 80%+ line coverage
+- Use JaCoCo for coverage reporting
+- Focus on service and domain logic — skip trivial getters/config classes
+
+## References
+
+See skill: `springboot-tdd` for Spring Boot TDD patterns with MockMvc and Testcontainers.
+See skill: `java-coding-standards` for testing expectations.

package/docs/rules/java_zn/coding-style.md

@@ -0,0 +1,169 @@
+---
+paths:
+  - "**/*.java"
+---
+
+# Java 代码风格 Rule
+
+本规则以《Java 开发手册》为基准，覆盖 Java / Spring / Spring Boot 项目的**纯编码风格**。生成代码时优先遵守项目现有约定；项目无明确约定时按本规则执行。
+
+完整工程规约（DTO 校验、Lombok、异常与日志、安全、MySQL/ORM、并发、单元测试、工程分层、Review 清单）见结尾「参考」节。
+
+## 1. 总体原则
+
+- 代码应清晰、稳定、可维护，命名表达完整业务含义，不为追求简短牺牲可读性。
+- 强制遵守命名、格式、不可变性、错误处理等编码规约。
+- 不引入无必要的新依赖；项目已使用 Spring Utils、Apache Commons Lang3、Jakarta Validation 时优先复用。
+- 修改代码时同步补充或调整必要的单元测试。
+
+## 2. 命名规则
+
+- 类名使用 `UpperCamelCase`。
+- 方法名、参数名、成员变量、局部变量使用 `lowerCamelCase`。
+- 常量使用全大写，下划线分隔，如 `MAX_STOCK_COUNT`。
+- 包名全小写，使用单数语义，避免拼音、中文、随意缩写。
+- 抽象类以 `Abstract` 或 `Base` 开头；异常类以 `Exception` 结尾；测试类以被测类名开头并以 `Test` 结尾。
+- 领域模型命名遵守：
+  - 数据对象：`xxxDO`
+  - 数据传输对象：`xxxDTO`
+  - 展示对象：`xxxVO`
+  - 业务对象：`xxxBO`
+  - 禁止命名为 `xxxPOJO`
+- Service / DAO 暴露接口，实现类使用 `Impl` 后缀。
+- 获取单个对象用 `get` 前缀，获取集合用 `list` 前缀，统计用 `count` 前缀，新增用 `save` / `insert`，删除用 `remove` / `delete`，修改用 `update`。
+
+## 3. 格式规则
+
+- 使用 4 个空格缩进，禁止 tab。
+- 单行代码建议不超过 120 字符，超出需按语义换行。
+- `if` / `for` / `while` / `switch` / `do` 与左括号之间必须有空格。
+- 二目、三目运算符两侧必须有空格。
+- 非空代码块左大括号不换行，右大括号独占一行；`else` 等连续结构紧跟右大括号。
+- 所有 `if` / `else` / `for` / `while` / `do` 语句必须使用大括号。
+- 单个方法建议不超过 80 行。超过时优先拆分为语义明确的私有方法或独立组件。
+- 不同逻辑、不同语义、不同业务代码之间用空行分隔。
+- 每个文件只放一个 public 顶层类型；成员顺序建议：常量、字段、构造器、public 方法、protected 方法、private 方法。
+
+## 4. 不可变性
+
+- 值类型优先使用 `record`（Java 16+）。
+- 字段默认声明为 `final`，仅在确有需要时才使用可变状态。
+- 公共 API 返回防御性拷贝：`List.copyOf()`、`Map.copyOf()`、`Set.copyOf()`。
+- Copy-on-write：返回新实例而不是就地修改已有对象。
+
+```java
+// 推荐 —— 不可变值类型
+public record OrderSummary(Long id, String customerName, BigDecimal total) {}
+
+// 推荐 —— final 字段，无 setter
+public class Order {
+    private final Long id;
+    private final List<LineItem> items;
+
+    public List<LineItem> getItems() {
+        return List.copyOf(items);
+    }
+}
+```
+
+## 5. 现代 Java 特性
+
+在能提升清晰度的场景使用现代语言特性：
+
+- **Record** 用于 DTO 和值类型（Java 16+）。
+- **Sealed 类**用于封闭类型层次（Java 17+）。
+- **`instanceof` 模式匹配** —— 无需显式强转（Java 16+）。
+- **文本块**用于多行字符串 —— SQL、JSON 模板（Java 15+）。
+- **Switch 表达式**使用箭头语法（Java 14+）。
+- **Switch 模式匹配** —— 对 sealed 类型做穷尽处理（Java 21+）。
+
+```java
+// instanceof 模式匹配
+if (shape instanceof Circle c) {
+    return Math.PI * c.radius() * c.radius();
+}
+
+// sealed 类型层次
+public sealed interface PaymentMethod permits CreditCard, BankTransfer, Wallet {}
+
+// switch 表达式
+String label = switch (status) {
+    case ACTIVE -> "Active";
+    case SUSPENDED -> "Suspended";
+    case CLOSED -> "Closed";
+};
+```
+
+## 6. Optional 使用
+
+- finder 方法可能无结果时返回 `Optional<T>`。
+- 使用 `map()`、`flatMap()`、`orElseThrow()`；不要在未 `isPresent()` 判断时裸调 `get()`。
+- 不要把 `Optional` 作为字段类型或方法参数类型。
+
+```java
+// 推荐
+return repository.findById(id)
+    .map(ResponseDto::from)
+    .orElseThrow(() -> new OrderNotFoundException(id));
+
+// 禁止 —— Optional 作参数
+public void process(Optional<String> name) {}
+```
+
+## 7. 错误处理（核心）
+
+- 领域错误优先使用非受检异常。
+- 自定义领域异常继承 `RuntimeException`。
+- 避免宽泛的 `catch (Exception e)`，仅顶层处理器例外。
+- 异常消息必须带上下文信息。
+- 流和资源使用 `try-with-resources`。
+- 禁止空 catch；`finally` 中禁止 `return`。
+
+```java
+public class OrderNotFoundException extends RuntimeException {
+    public OrderNotFoundException(Long id) {
+        super("Order not found: id=" + id);
+    }
+}
+```
+
+> 完整异常处理与日志规则见 skill：`spring-boot-engineer_zn` 的 `references/exception-logging.md`。
+
+## 8. 集合与 Streams
+
+集合处理：
+
+- `Set` 中对象必须正确实现 `equals` 和 `hashCode`。
+- 不要在 `foreach` 中对集合执行 `add` / `remove`，删除时使用 `Iterator`。
+- 集合转数组必须使用 `toArray(T[] array)`。
+- `Arrays.asList` 返回的集合不可直接增删。
+- `subList` 结果不可强转为 `ArrayList`，且要注意原集合修改带来的影响。
+- `Map` 遍历优先使用 `entrySet`。
+- 集合初始化时尽量指定容量。
+- 调用 `addAll` 前应对入参集合做空判断。
+
+Streams：
+
+- 使用 stream 做转换，管道保持简短（最多 3–4 个操作）。
+- 可读时优先使用方法引用：`.map(Order::getTotal)`。
+- 避免在 stream 操作中产生副作用。
+- 逻辑复杂时优先使用循环，而不是写出晦涩的 stream 管道。
+
+## 9. 控制语句
+
+- 表达异常分支时优先使用卫语句，减少嵌套。
+- `if ... else if ... else` 嵌套不要超过 3 层；超过时应拆分方法、使用策略模式、状态模式或表驱动。
+- 条件表达式中不要执行复杂逻辑，先赋值给语义明确的变量。
+- 不要在条件表达式中插入赋值语句。
+- 循环体内尽量避免重复创建对象、重复查询数据库、重复执行正则编译等高成本操作。
+
+## 10. 注释规则
+
+- 类、类属性、类方法按项目要求使用 Javadoc，接口和抽象方法必须说明参数、返回值、异常和语义。
+- 注释应解释业务语义、边界条件、设计意图，不要复述代码。
+- 修改代码时同步更新注释。
+- 不要长期保留无用的注释代码；确需保留时说明原因、负责人和时间。
+
+## 参考
+
+完整 Java / Spring Boot 工程规约（DTO 校验、Lombok、异常与日志、安全、MySQL/ORM、并发、单元测试、工程分层、Review 清单）见 skill：`spring-boot-engineer_zn`。

package/docs/rules/java_zn/mybatis.md

@@ -0,0 +1,102 @@
+---
+paths:
+  - "**/*.java"
+  - "**/*Mapper.xml"
+  - "**/mapper/**/*.xml"
+---
+
+# MyBatis 数据访问与分层 Rule
+
+本规则约定 MyBatis(-Plus) 项目的数据访问方式与 Service / Mapper 分层依赖方向。生成或修改数据访问相关代码时遵守本规则；完整 MySQL/ORM 与工程分层规约见结尾「参考」节。
+
+## 1. 分层与依赖方向
+
+- **Mapper 在底层**：只负责持久化与数据查询，不写业务逻辑。
+- **Service 在上层**：承载业务编排、结果组装与事务边界。
+- **依赖只能自上而下**：`Service → Mapper`；Mapper 不得反向依赖 Service。
+
+```
+上层   Service  ──依赖──▶  底层   Mapper（接口 + XML）
+```
+
+## 2. 简单查询用 IService，复杂联查走 Mapper XML 原生 SQL
+
+- **简单**（单表 CRUD、简单条件查询、分页）：Service 接口继承 MyBatis-Plus `IService<T>`、实现类继承 `ServiceImpl<Mapper, T>`，**直接使用继承得到的现成接口**（`getById`、`getOne`、`list`、`listByIds`、`save`、`saveBatch`、`updateById`、`removeById`、`page`、`lambdaQuery()` / `lambdaUpdate()` 等），不写 XML、不重复封装。
+- **复杂多表联查**（多表 JOIN、聚合、分组、子查询等）用 `IService` / Wrapper 表达不便或可读性差时：在 **Mapper 接口声明方法**，在 **XML 中写原生 SQL** 完成查询，由 Service 调用该 Mapper 方法（`ServiceImpl` 中通过 `baseMapper` 访问）。
+- XML 原生 SQL 要求：参数一律用 `#{}` 绑定（禁止 `${}` 拼接用户输入）、显式列出字段（禁止 `select *`）、结果用 `resultMap` 或 DTO 映射、命中必要索引；分页 `count` 为 0 时直接返回。
+
+示例：
+
+```java
+// Mapper 接口：仅声明复杂联查方法；简单 CRUD 由 BaseMapper 提供，无需声明
+public interface OrderMapper extends BaseMapper<OrderDO> {
+
+    List<OrderDetailDTO> listOrderDetail(@Param("query") OrderQuery query);
+}
+```
+
+```xml
+<!-- OrderMapper.xml：原生 SQL 写复杂联查 -->
+<select id="listOrderDetail" resultType="com.example.order.dto.OrderDetailDTO">
+    SELECT o.id, o.order_no, u.user_name, p.product_name, oi.quantity
+    FROM t_order o
+    JOIN t_user u ON u.id = o.user_id
+    JOIN t_order_item oi ON oi.order_id = o.id
+    JOIN t_product p ON p.id = oi.product_id
+    WHERE o.org_id = #{query.orgId}
+    <if test="query.status != null">
+        AND o.status = #{query.status}
+    </if>
+</select>
+```
+
+```java
+// Service 接口：继承 IService，获得现成 CRUD / 简单查询能力
+public interface OrderService extends IService<OrderDO> {
+
+    List<OrderDetailDTO> listDetail(OrderQuery query);   // 复杂联查单独声明
+}
+
+// 实现类：继承 ServiceImpl 并绑定对应 Mapper
+@Service
+public class OrderServiceImpl extends ServiceImpl<OrderMapper, OrderDO> implements OrderService {
+
+    // 简单查询直接用继承自 IService 的方法，无需另写：
+    //   getById(id) / list(wrapper) / save(entity) / page(page, wrapper) / lambdaQuery()...
+
+    // 复杂联查：调用 Mapper 的原生 SQL 方法（baseMapper 即 OrderMapper）
+    @Override
+    @Transactional(readOnly = true)
+    public List<OrderDetailDTO> listDetail(OrderQuery query) {
+        return baseMapper.listOrderDetail(query);
+    }
+}
+```
+
+## 3. 跨 Service 复用：依赖 Service，不要越层调 Mapper
+
+- 其他 Service 需要这块数据或能力时，**依赖这个 Service**（`Service → Service`），由它对外暴露方法。
+- **禁止**跨模块直接调用别人的 Mapper 越过其 Service 层——绕过 Service 会丢失业务规则、事务与权限控制。
+- Service 之间避免循环依赖；出现循环依赖时，把公共逻辑下沉到更底层的 Service / Manager 或独立组件。
+
+```java
+// 其他 Service 依赖 OrderService，而不是直接用 OrderMapper
+@Service
+public class FulfillmentService {
+
+    private final OrderService orderService;   // 依赖上层暴露的 Service
+
+    public FulfillmentService(OrderService orderService) {
+        this.orderService = orderService;
+    }
+
+    public void fulfill(OrderQuery query) {
+        List<OrderDetailDTO> details = orderService.listDetail(query);
+        // ... 履约业务编排，不直接接触 OrderMapper
+    }
+}
+```
+
+## 参考
+
+完整数据访问规约（MySQL/ORM、`#{}` 参数绑定、索引、分页、事务）与工程分层、依赖方向见 skill：`spring-boot-engineer_zn`（`references/persistence.md`、`references/architecture.md`）。