aigroup-workflow 2.2.2 → 2.2.3

package/.codex/config.toml

@@ -1,23 +1,6 @@
-#:schema https://developers.openai.com/codex/config-schema.json
-
-# aiGroup — Codex 本地配置
-#
-# 用法：
-# - 拷贝到 ~/.codex/config.toml 作为全局默认
-# - 或保留在项目根 .codex/config.toml 作为项目级配置
-#
-# 文档参考：
-# - https://developers.openai.com/codex/config-reference
-# - https://developers.openai.com/codex/multi-agent
-
-# ---------- Runtime ----------
-# model / model_provider 留空，使用 Codex CLI 当前默认，除非明确要固定版本
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 web_search = "live"
-
-# ---------- Persistent Instructions ----------
-# 持久指令在每次 prompt 后追加（与 model_instructions_file 替换不同）
 persistent_instructions = """
 Follow project AGENTS.md as the source of truth.
 Load skills by task intent, not by role ownership.
@@ -25,44 +8,41 @@ aiGroup has retired the legacy three-role model (ella/jarvis/kyle) — do not de
 Use the multi-agent roles declared below for exploration, planning, implementation, review, build fixing, and docs research.
 """
 
-# ---------- MCP Servers ----------
-# aiGroup 项目级精简基线。遵守 docs/rules/performance.md：
-# 单项目启用 MCP < 10，活跃工具 < 80；重型服务器放到用户级配置按需叠加。
 [mcp_servers.github]
 command = "npx"
-args = ["-y", "@modelcontextprotocol/server-github"]
+args = [
+    "-y",
+    "@modelcontextprotocol/server-github",
+]
 startup_timeout_sec = 30
 
 [mcp_servers.context7]
 command = "npx"
-args = ["-y", "@upstash/context7-mcp@latest"]
+args = [
+    "-y",
+    "@upstash/context7-mcp@latest",
+]
 startup_timeout_sec = 30
 
 [mcp_servers.memory]
 command = "npx"
-args = ["-y", "@modelcontextprotocol/server-memory"]
+args = [
+    "-y",
+    "@modelcontextprotocol/server-memory",
+]
 startup_timeout_sec = 30
 
 [mcp_servers.sequential-thinking]
 command = "npx"
-args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+args = [
+    "-y",
+    "@modelcontextprotocol/server-sequential-thinking",
+]
 startup_timeout_sec = 30
 
-# 按需取消注释：
-# [mcp_servers.playwright]
-# command = "npx"
-# args = ["-y", "@playwright/mcp@latest", "--extension"]
-# startup_timeout_sec = 30
-#
-# [mcp_servers.exa]
-# url = "https://mcp.exa.ai/mcp"
-
-# ---------- Features ----------
 [features]
 multi_agent = true
 
-# ---------- Profiles ----------
-# 切换：codex -p <name>
 [profiles.strict]
 approval_policy = "on-request"
 sandbox_mode = "read-only"
@@ -73,9 +53,6 @@ approval_policy = "never"
 sandbox_mode = "workspace-write"
 web_search = "live"
 
-# ---------- Codex 原生 Persona ----------
-# 仅保留 Codex 自身需要"切换 persona"的 3 个场景。
-# 其他工作（planning / implementation / build-fixing）由 Codex 主对话 + 加载对应 skill 完成。
 [agents]
 max_threads = 3
 max_depth = 1
@@ -91,3 +68,9 @@ config_file = "agents/reviewer.toml"
 [agents.docs_researcher]
 description = "API, framework, and release-note verification via documentation sources."
 config_file = "agents/docs-researcher.toml"
+
+[shell_environment_policy]
+inherit = "core"
+
+[shell_environment_policy.set]
+CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"

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`）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aigroup-workflow",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "AI 团队协作框架 — 通过角色派遣、工作流管道和 Harness 传感器驱动 AI 协作开发",
   "type": "module",
   "bin": {

package/skills/java/spring-boot-engineer/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: spring-boot-engineer
-description: Generates Spring Boot 3.x configurations, creates REST controllers, implements Spring Security 6 authentication flows, sets up Spring Data JPA repositories, and configures reactive WebFlux endpoints. Use when building Spring Boot 3.x applications, microservices, or reactive Java applications; invoke for Spring Data JPA, Spring Security 6, WebFlux, Spring Cloud integration, Java REST API design, or Microservices Java architecture.
+description: Generates Spring Boot 3.x configurations, creates REST controllers, implements Spring Security 6 authentication flows, sets up Spring Data JPA or MyBatis-Plus data access, and configures reactive WebFlux endpoints. Use when building Spring Boot 3.x applications, microservices, or reactive Java applications; invoke for Spring Data JPA, MyBatis-Plus, Spring Security 6, WebFlux, Spring Cloud integration, Java REST API design, or Microservices Java architecture.
 license: MIT
 metadata:
   author: https://github.com/Jeffallan
   version: "1.1.0"
   domain: backend
-  triggers: Spring Boot, Spring Framework, Spring Cloud, Spring Security, Spring Data JPA, Spring WebFlux, Microservices Java, Java REST API, Reactive Java
+  triggers: Spring Boot, Spring Framework, Spring Cloud, Spring Security, Spring Data JPA, MyBatis-Plus, Spring WebFlux, Microservices Java, Java REST API, Reactive Java
   role: specialist
   scope: implementation
   output-format: code
@@ -32,6 +32,7 @@ Load detailed guidance based on context:
 |-------|-----------|-----------|
 | Web Layer | `references/web.md` | Controllers, REST APIs, validation, exception handling |
 | Data Access | `references/data.md` | Spring Data JPA, repositories, transactions, projections |
+| MyBatis-Plus | `references/mybatis-plus.md` | MyBatis-Plus, BaseMapper, XML mapper queries, wrappers |
 | Security | `references/security.md` | Spring Security 6, OAuth2, JWT, method security |
 | Cloud Native | `references/cloud.md` | Spring Cloud, Config, Discovery, Gateway, resilience |
 | Testing | `references/testing.md` | @SpringBootTest, MockMvc, Testcontainers, test slices |

package/skills/java/spring-boot-engineer/references/mybatis-plus.md

@@ -0,0 +1,592 @@
+# Data Access - MyBatis-Plus
+
+## Core Rule
+
+Use MyBatis-Plus to remove repetitive single-table SQL, not to hide business rules.
+
+| Scenario | Preferred Pattern |
+|----------|-------------------|
+| CRUD by id | `BaseMapper#selectById`, `insert`, `updateById`, `deleteById` |
+| Simple single-table filters | `LambdaQueryWrapper` / `LambdaUpdateWrapper` |
+| Simple paging | `BaseMapper#selectPage` with `Page<T>` |
+| Count / exists | `selectCount` with a lambda wrapper |
+| Complex joins | Mapper interface method + XML SQL |
+| Aggregation / reports | XML SQL with dedicated result DTO |
+| Dynamic SQL with many branches | XML SQL, not a huge Java wrapper chain |
+| Vendor-specific SQL | XML SQL, isolated in the mapper layer |
+
+Do not write XML for trivial `WHERE id = ?`, simple `LIKE`, simple status filters, or normal pagination. Do not force complex joins into wrapper chains. When a query needs `JOIN`, `GROUP BY`, window functions, `UNION`, CTE, or a hand-tuned execution plan, put it in XML.
+
+## Package Layout
+
+Keep MyBatis-Plus details inside the data/service boundary. Controllers should talk to services and DTOs, not mappers or persistence objects.
+
+```text
+src/main/java/com/example/user/
+  controller/
+    UserController.java
+  dto/
+    UserCreateRequest.java
+    UserResponse.java
+    UserSearchCriteria.java
+    UserOrderSummary.java
+  entity/
+    UserDO.java
+  mapper/
+    UserMapper.java
+  service/
+    UserService.java
+
+src/main/resources/
+  mapper/
+    UserMapper.xml
+```
+
+If the project already uses `Entity`, `PO`, or another suffix, follow the project. In new MyBatis-Plus code, prefer `DO` for database objects so they do not look like API DTOs or domain responses.
+
+## Dependency and Configuration
+
+Use the project-managed MyBatis-Plus version. For MyBatis-Plus `3.5.9+`, add `mybatis-plus-jsqlparser` when using `PaginationInnerInterceptor`.
+
+```xml
+<dependency>
+    <groupId>com.baomidou</groupId>
+    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
+</dependency>
+
+<dependency>
+    <groupId>com.baomidou</groupId>
+    <artifactId>mybatis-plus-jsqlparser</artifactId>
+</dependency>
+```
+
+```yaml
+mybatis-plus:
+  mapper-locations: classpath*:mapper/**/*.xml
+  type-aliases-package: com.example.user.entity
+  configuration:
+    map-underscore-to-camel-case: true
+  global-config:
+    db-config:
+      id-type: auto
+      logic-delete-field: deleted
+      logic-delete-value: 1
+      logic-not-delete-value: 0
+```
+
+Keep SQL logging in local/test profiles only. Do not enable verbose SQL logs with bind values in production when the query may contain PII.
+
+## MyBatis-Plus Configuration
+
+```java
+@Configuration
+@MapperScan("com.example.user.mapper")
+public class MybatisPlusConfig {
+
+    @Bean
+    public MybatisPlusInterceptor mybatisPlusInterceptor() {
+        var interceptor = new MybatisPlusInterceptor();
+        interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
+        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
+        interceptor.addInnerInterceptor(new BlockAttackInnerInterceptor());
+        return interceptor;
+    }
+}
+```
+
+Adjust `DbType` to the actual database. Add tenant or dynamic-table interceptors only when the project really needs them.
+
+## Entity Pattern
+
+Entities are mutable persistence objects. Keep API validation and response shaping in DTOs, not in `DO` classes.
+
+```java
+@TableName("sys_user")
+@Getter
+@Setter
+@NoArgsConstructor
+public class UserDO {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    private Long tenantId;
+
+    private String email;
+
+    private String username;
+
+    private UserStatus status;
+
+    @TableField(fill = FieldFill.INSERT)
+    private LocalDateTime createdAt;
+
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime updatedAt;
+
+    @TableLogic
+    private Integer deleted;
+
+    @Version
+    private Integer version;
+
+    @TableField(exist = false)
+    private List<String> roleNames;
+}
+```
+
+Prefer `@Getter` / `@Setter` over `@Data` for persistence objects. `@Data` generates `equals`, `hashCode`, and `toString`, which can accidentally include large or sensitive fields.
+
+## Auto Fill
+
+Use MyBatis-Plus auto-fill for audit fields, but keep user-specific audit data explicit when it depends on security context.
+
+```java
+@Component
+public class AuditMetaObjectHandler implements MetaObjectHandler {
+
+    @Override
+    public void insertFill(MetaObject metaObject) {
+        var now = LocalDateTime.now();
+        strictInsertFill(metaObject, "createdAt", LocalDateTime.class, now);
+        strictInsertFill(metaObject, "updatedAt", LocalDateTime.class, now);
+    }
+
+    @Override
+    public void updateFill(MetaObject metaObject) {
+        strictUpdateFill(metaObject, "updatedAt", LocalDateTime.class, LocalDateTime.now());
+    }
+}
+```
+
+Auto-fill runs when MyBatis-Plus receives an entity. If you call `update(Wrapper<T>)` without an entity, update fill will not run. Prefer `updateById(entity)` or `update(entity, wrapper)` when `updatedAt` must be maintained automatically.
+
+## Mapper Pattern
+
+Simple mappers extend `BaseMapper` and stay empty until a real custom query is needed.
+
+```java
+public interface UserMapper extends BaseMapper<UserDO> {
+
+    IPage<UserOrderSummary> selectOrderSummaries(
+        Page<UserOrderSummary> page,
+        @Param("criteria") UserOrderSearchCriteria criteria
+    );
+}
+```
+
+Use `@MapperScan` at configuration level. Add `@Mapper` only if the project does not use scanner configuration.
+
+## BaseMapper and IService
+
+Both `BaseMapper` and `IService` are MyBatis-Plus built-in capabilities. This guide defaults to explicit constructor injection of mapper interfaces because it matches the service-layer style used by this skill.
+
+If an existing project already extends `ServiceImpl<UserMapper, UserDO>`, keep that convention. Use built-in methods such as `getById`, `list`, `page`, `save`, and `updateById` for simple operations, but do not let service classes become CRUD pass-through wrappers with no business meaning.
+
+Avoid the static `Db` kit in normal service code. It makes dependencies implicit and is harder to test than constructor-injected mappers or services.
+
+## Simple Queries
+
+For simple reads, build lambda wrappers in the service layer. Use method references so refactors fail at compile time instead of becoming broken SQL column strings.
+
+```java
+@Service
+@RequiredArgsConstructor
+@Transactional(readOnly = true)
+public class UserService {
+
+    private static final long MAX_PAGE_SIZE = 100;
+
+    private final UserMapper userMapper;
+
+    public Optional<UserResponse> findById(Long id) {
+        return Optional.ofNullable(userMapper.selectById(id))
+            .map(UserResponse::from);
+    }
+
+    public IPage<UserResponse> search(UserSearchCriteria criteria) {
+        var page = Page.<UserDO>of(
+            criteria.pageNo(),
+            Math.min(criteria.pageSize(), MAX_PAGE_SIZE)
+        );
+
+        var query = Wrappers.lambdaQuery(UserDO.class)
+            .eq(UserDO::getTenantId, criteria.tenantId())
+            .eq(criteria.status() != null, UserDO::getStatus, criteria.status())
+            .like(StringUtils.hasText(criteria.keyword()), UserDO::getUsername, criteria.keyword())
+            .orderByDesc(UserDO::getCreatedAt);
+
+        return userMapper.selectPage(page, query)
+            .convert(UserResponse::from);
+    }
+
+    public boolean existsByEmail(Long tenantId, String email) {
+        var query = Wrappers.lambdaQuery(UserDO.class)
+            .eq(UserDO::getTenantId, tenantId)
+            .eq(UserDO::getEmail, email);
+
+        return userMapper.selectCount(query) > 0;
+    }
+}
+```
+
+Do not return unbounded `List<T>` from public APIs. Use pagination unless the result set is naturally tiny and bounded by business rules.
+
+## Simple Writes
+
+Keep transaction boundaries on services. Check affected rows for updates and deletes that must touch exactly one row.
+
+```java
+@Service
+@RequiredArgsConstructor
+public class UserCommandService {
+
+    private final UserMapper userMapper;
+
+    @Transactional
+    public UserResponse create(UserCreateRequest request) {
+        var user = new UserDO();
+        user.setTenantId(request.tenantId());
+        user.setEmail(request.email());
+        user.setUsername(request.username());
+        user.setStatus(UserStatus.ACTIVE);
+
+        userMapper.insert(user);
+        return UserResponse.from(user);
+    }
+
+    @Transactional
+    public void disable(Long tenantId, Long userId) {
+        var update = new UserDO();
+        update.setStatus(UserStatus.DISABLED);
+
+        var condition = Wrappers.lambdaUpdate(UserDO.class)
+            .eq(UserDO::getTenantId, tenantId)
+            .eq(UserDO::getId, userId)
+            .eq(UserDO::getStatus, UserStatus.ACTIVE);
+
+        int rows = userMapper.update(update, condition);
+        if (rows != 1) {
+            throw new UserNotFoundException(userId);
+        }
+    }
+}
+```
+
+Avoid `update(null, wrapper)` when audit auto-fill or optimistic locking matters. Avoid `remove` / `delete` operations without a business condition.
+
+## Complex XML Queries
+
+Use XML when the query is a real SQL artifact. Keep the Java interface small and make parameters explicit with `@Param`.
+
+```java
+public record UserOrderSearchCriteria(
+    Long tenantId,
+    String keyword,
+    LocalDateTime startAt,
+    LocalDateTime endAt,
+    OrderStatus orderStatus,
+    long pageNo,
+    long pageSize
+) {}
+
+public record UserOrderSummary(
+    Long userId,
+    String username,
+    String email,
+    Long orderCount,
+    BigDecimal totalAmount,
+    LocalDateTime lastOrderAt
+) {}
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE mapper
+    PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
+    "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
+
+<mapper namespace="com.example.user.mapper.UserMapper">
+
+    <resultMap id="UserOrderSummaryMap" type="com.example.user.dto.UserOrderSummary">
+        <constructor>
+            <arg column="user_id" javaType="java.lang.Long" />
+            <arg column="username" javaType="java.lang.String" />
+            <arg column="email" javaType="java.lang.String" />
+            <arg column="order_count" javaType="java.lang.Long" />
+            <arg column="total_amount" javaType="java.math.BigDecimal" />
+            <arg column="last_order_at" javaType="java.time.LocalDateTime" />
+        </constructor>
+    </resultMap>
+
+    <select id="selectOrderSummaries" resultMap="UserOrderSummaryMap">
+        SELECT
+            u.id AS user_id,
+            u.username,
+            u.email,
+            COUNT(o.id) AS order_count,
+            COALESCE(SUM(o.total_amount), 0) AS total_amount,
+            MAX(o.created_at) AS last_order_at
+        FROM sys_user u
+        INNER JOIN orders o
+            ON o.user_id = u.id
+            AND o.deleted = 0
+        WHERE u.deleted = 0
+          AND u.tenant_id = #{criteria.tenantId}
+        <if test="criteria.keyword != null and criteria.keyword != ''">
+          AND (
+              u.username LIKE CONCAT('%', #{criteria.keyword}, '%')
+              OR u.email LIKE CONCAT('%', #{criteria.keyword}, '%')
+          )
+        </if>
+        <if test="criteria.startAt != null">
+          AND o.created_at &gt;= #{criteria.startAt}
+        </if>
+        <if test="criteria.endAt != null">
+          AND o.created_at &lt; #{criteria.endAt}
+        </if>
+        <if test="criteria.orderStatus != null">
+          AND o.status = #{criteria.orderStatus}
+        </if>
+        GROUP BY u.id, u.username, u.email
+        ORDER BY last_order_at DESC
+    </select>
+
+</mapper>
+```
+
+Let the pagination interceptor add paging SQL. Do not add manual `LIMIT` / `OFFSET` to a paged XML method unless the interceptor is intentionally not used.
+
+## XML Pagination Usage
+
+```java
+@Transactional(readOnly = true)
+public IPage<UserOrderSummary> searchOrderSummaries(UserOrderSearchCriteria criteria) {
+    var page = Page.<UserOrderSummary>of(
+        criteria.pageNo(),
+        Math.min(criteria.pageSize(), MAX_PAGE_SIZE)
+    );
+
+    return userMapper.selectOrderSummaries(page, criteria);
+}
+```
+
+If a grouped XML page query has an expensive generated count SQL, define a dedicated count statement or split the count query from the data query.
+
+## DTO Mapping
+
+Use records for request/response DTOs when the project is on Java 16+.
+
+```java
+public record UserResponse(
+    Long id,
+    String email,
+    String username,
+    UserStatus status,
+    LocalDateTime createdAt
+) {
+    public static UserResponse from(UserDO user) {
+        return new UserResponse(
+            user.getId(),
+            user.getEmail(),
+            user.getUsername(),
+            user.getStatus(),
+            user.getCreatedAt()
+        );
+    }
+}
+```
+
+Do not expose `UserDO` from controllers. Persistence objects often contain internal fields such as `tenantId`, `deleted`, `version`, or audit metadata.
+
+## SQL Safety
+
+Use `#{}` for all runtime values.
+
+```xml
+WHERE u.email = #{email}
+```
+
+Avoid `${}`. It performs string substitution and can become SQL injection. The only acceptable cases are whitelisted identifiers such as sort columns or dynamic table names after strict validation.
+
+```java
+private static final Map<String, SFunction<UserDO, ?>> SORT_FIELDS = Map.of(
+    "createdAt", UserDO::getCreatedAt,
+    "username", UserDO::getUsername
+);
+```
+
+Avoid `wrapper.last(...)`, `apply(...)`, or raw SQL fragments with user input. If a fragment is unavoidable, keep user input bound with parameters and whitelist all identifiers.
+
+## Transactions
+
+Put `@Transactional` on service methods, not controllers or mappers.
+
+| Operation | Transaction Pattern |
+|-----------|---------------------|
+| Read-only query | `@Transactional(readOnly = true)` |
+| Single insert/update with side effects | `@Transactional` |
+| Multi-step write | One service method with one transaction boundary |
+| XML report query | `readOnly = true`, no state mutation |
+
+Avoid self-invocation traps. A `@Transactional` method called from another method in the same class will not pass through Spring's proxy.
+
+## Logical Delete and Optimistic Locking
+
+Use `@TableLogic` for soft delete when records must be retained. Remember that XML SQL does not automatically add every business rule you forget to write. In XML, explicitly filter `deleted = 0`.
+
+Use `@Version` for rows that can be concurrently edited. Check the update row count and return a conflict/domain exception when the row was not updated.
+
+```java
+@Transactional
+public void rename(Long userId, String username, Integer version) {
+    var user = new UserDO();
+    user.setId(userId);
+    user.setUsername(username);
+    user.setVersion(version);
+
+    int rows = userMapper.updateById(user);
+    if (rows != 1) {
+        throw new ConcurrentUpdateException("User was modified: id=" + userId);
+    }
+}
+```
+
+## Performance Practices
+
+- Select only needed columns for list pages. Avoid `SELECT *` in XML.
+- Add indexes for equality filters, join keys, and common sort fields.
+- Keep large report queries in XML so they can be reviewed with `EXPLAIN`.
+- Prefer keyset pagination for very deep pages when the UI allows it.
+- Do not use `like '%keyword%'` on large tables without understanding index impact.
+- Keep batch writes chunked and transactional. Do not send a huge list in one statement by default.
+- Avoid N+1 lookup loops. If a list view needs derived data from another table, write one XML query or fetch in batches.
+- Keep result maps explicit for complex DTOs, enum columns, JSON columns, or fields with type handlers.
+
+## Testing
+
+Use mapper tests for XML SQL. Use a real database with Testcontainers when SQL depends on dialect behavior.
+
+```java
+@SpringBootTest
+@Testcontainers
+class UserMapperIT {
+
+    @Container
+    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.4");
+
+    @Autowired
+    private UserMapper userMapper;
+
+    @Test
+    void selectOrderSummaries_filtersByTenant() {
+        var criteria = new UserOrderSearchCriteria(
+            1L,
+            null,
+            null,
+            null,
+            null,
+            1,
+            20
+        );
+
+        var page = Page.<UserOrderSummary>of(1, 20);
+        var result = userMapper.selectOrderSummaries(page, criteria);
+
+        assertThat(result.getRecords())
+            .allSatisfy(row -> assertThat(row.userId()).isNotNull());
+    }
+}
+```
+
+Test at least these cases:
+
+- Simple wrapper query includes tenant / ownership filters.
+- XML query works with all optional criteria absent.
+- XML query works with each optional criterion present.
+- Pagination returns stable ordering.
+- Logical delete rows are hidden.
+- Update operations check affected row count.
+- Optimistic lock conflict is handled.
+
+## Database Migrations
+
+Keep table definitions aligned with entity annotations.
+
+```sql
+CREATE TABLE sys_user (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    tenant_id BIGINT NOT NULL,
+    email VARCHAR(100) NOT NULL,
+    username VARCHAR(100) NOT NULL,
+    status VARCHAR(32) NOT NULL,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    deleted TINYINT NOT NULL DEFAULT 0,
+    version INT NOT NULL DEFAULT 0,
+    UNIQUE KEY uk_user_tenant_email (tenant_id, email),
+    KEY idx_user_tenant_status_created (tenant_id, status, created_at),
+    KEY idx_user_username (username)
+);
+```
+
+Do not rely on MyBatis-Plus annotations as a replacement for Flyway/Liquibase migrations. The database schema is still the source of truth for production.
+
+## Code Generator
+
+Generated code is a starting point, not final code.
+
+- Rename generated entities to match the project suffix (`DO`, `Entity`, or existing convention).
+- Remove generated controllers unless they match the API design.
+- Replace field injection with constructor injection.
+- Replace broad `@Data` if the project prefers `@Getter` / `@Setter`.
+- Move complex generated SQL into reviewed XML files.
+- Add DTO mapping instead of returning persistence objects directly.
+
+## MUST DO
+
+| Rule | Correct Pattern |
+|------|-----------------|
+| Simple single-table query | `BaseMapper` + `LambdaQueryWrapper` |
+| Complex join query | Mapper method + XML |
+| Runtime values in SQL | `#{param}` |
+| Dynamic identifiers | Whitelist before using `${}` |
+| API response | Map `DO` to DTO/record |
+| Pagination | `Page<T>` with max page size |
+| Transactions | Service layer only |
+| Audit fields | `FieldFill` + `MetaObjectHandler` |
+| Safety plugin | `BlockAttackInnerInterceptor` |
+| Custom XML | Mapper test with real DB dialect when needed |
+
+## MUST NOT DO
+
+- Do not write XML for simple CRUD that MP already supports.
+- Do not force joins, reports, or aggregation queries into wrapper chains.
+- Do not inject mappers into controllers.
+- Do not return `DO` objects from REST APIs.
+- Do not concatenate SQL with user input.
+- Do not pass user input into `${}`, `last(...)`, or raw SQL fragments.
+- Do not run unbounded list queries from API endpoints.
+- Do not ignore affected row counts on important updates/deletes.
+- Do not rely on auto-fill when calling `update(Wrapper<T>)` without an entity.
+- Do not add global plugins or generator templates before the project needs them.
+
+## Quick Reference
+
+| API / Annotation | Purpose |
+|------------------|---------|
+| `BaseMapper<T>` | Built-in CRUD mapper |
+| `Wrappers.lambdaQuery` | Type-safe query conditions |
+| `Wrappers.lambdaUpdate` | Type-safe update conditions |
+| `Page<T>` / `IPage<T>` | MyBatis-Plus pagination |
+| `@TableName` | Table mapping |
+| `@TableId` | Primary key mapping |
+| `@TableField` | Field mapping, fill, type handler, non-table fields |
+| `FieldFill` | Insert/update auto-fill strategy |
+| `MetaObjectHandler` | Auto-fill implementation |
+| `@TableLogic` | Logical delete field |
+| `@Version` | Optimistic lock field |
+| `MybatisPlusInterceptor` | Plugin container |
+| `PaginationInnerInterceptor` | Pagination plugin |
+| `OptimisticLockerInnerInterceptor` | Optimistic lock plugin |
+| `BlockAttackInnerInterceptor` | Blocks full-table update/delete |

package/skills/java/spring-boot-engineer_zn/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: spring-boot-engineer_zn
+description: 中文版 Java / Spring Boot 工程规约与代码 Review 标准。覆盖 Jakarta Validation 参数校验、空安全工具类、常量与枚举、Lombok/POJO、异常与日志、安全、MySQL/ORM、并发、单元测试、工程分层与 Review 清单。当用中文进行 Java/Spring Boot 代码生成、改造或 Review 时加载。
+license: MIT
+metadata:
+  version: "1.0.0"
+  domain: backend
+  triggers: Java 代码规约, Spring Boot 规约, Jakarta Validation, Lombok, MyBatis, 阿里巴巴 Java 开发手册, 代码 Review, 工程分层
+  role: specialist
+  scope: standards
+  output-format: code
+  related-skills: spring-boot-engineer, java-architect
+  language: zh-CN
+---
+
+# Spring Boot 工程规约（中文）
+
+## 适用范围
+
+本 skill 以《Java 开发手册》为基准，适用于 Java / Spring / Spring Boot 项目的代码生成、修改和 Review，强制遵守命名、格式、异常日志、安全、数据库、分层与设计规约。
+
+加载时机：当用中文进行 Java / Spring Boot 代码生成、改造或 Review，且需要超出纯编码风格（见 `docs/rules/java_zn/coding-style.md`）的工程规约时，加载本 skill。生成代码时优先遵守项目现有约定；项目无明确约定时按本 skill 执行。
+
+## 参考指南
+
+按上下文加载对应参考文件：
+
+| 主题 | 参考文件 | 何时加载 |
+|------|----------|----------|
+| DTO 与参数校验 | `references/validation.md` | Jakarta Validation 注解、`@Valid`/`@Validated`、跨字段与业务校验 |
+| OOP / POJO / Lombok | `references/pojo-lombok.md` | POJO 设计、Lombok 注解组合、Builder、`@Data` 取舍 |
+| 异常与日志 | `references/exception-logging.md` | 异常处理完整规则、SLF4J 日志、脱敏 |
+| 安全 | `references/security.md` | 参数校验、权限、脱敏、SQL 注入、CSRF、幂等防刷 |
+| MySQL 与 ORM | `references/persistence.md` | 表结构规约、MyBatis、分页、事务 |
+| 并发 | `references/concurrency.md` | 线程池、`ThreadLocal`、锁、并发更新 |
+| 单元测试 | `references/testing.md` | 测试编写、覆盖范围、独立可重复 |
+| 工程结构与设计 | `references/architecture.md` | 重复代码抽象、分层依赖、单一职责、设计原则 |
+
+## 核心规约
+
+以下为高频内联规约，完整迁移自原规则。
+
+### 值判断与工具类使用
+
+- 字符串、包装类型、对象、集合、数组等值判断，应优先使用空安全工具类或 JDK 工具方法，避免直接使用 `==` / `!=` 做相等判断。
+- 字符串空白判断优先使用 `org.apache.commons.lang3.StringUtils.isBlank` / `isNotBlank`，或项目已有的 `org.springframework.util.StringUtils.hasText`。
+- 字符串相等优先使用 `org.apache.commons.lang3.StringUtils.equals` / `equalsIgnoreCase`。
+- 对象相等优先使用 `java.util.Objects.equals`。
+- Boolean 包装类型判断优先使用 `org.apache.commons.lang3.BooleanUtils.isTrue` / `isFalse`。
+- 集合或 Map 判空优先使用 `org.springframework.util.CollectionUtils.isEmpty`。
+- 数组、对象整体判空可使用 `org.springframework.util.ObjectUtils.isEmpty`。
+- 枚举相等在明确非空语义下可以使用 `EnumConstant == value`；如果枚举变量可能为 null，优先使用 `Objects.equals(value, EnumConstant)` 或将常量放左侧。
+- 基本类型大小比较仍使用 `>`、`<`、`>=`、`<=`。
+
+禁止写法：
+
+```java
+if (userName == "") {
+    return;
+}
+
+if (status == 1) {
+    return;
+}
+
+if (enabled == true) {
+    return;
+}
+```
+
+推荐写法：
+
+```java
+if (StringUtils.isBlank(userName)) {
+    return;
+}
+
+if (Objects.equals(status, ENABLED_STATUS)) {
+    return;
+}
+
+if (BooleanUtils.isTrue(enabled)) {
+    return;
+}
+
+if (CollectionUtils.isEmpty(userList)) {
+    return;
+}
+```
+
+### 常量与枚举
+
+- 禁止魔法值直接出现在代码中，应定义为常量或枚举。
+- `Long` 字面量使用大写 `L`，例如 `1L`。
+- 固定范围的状态、类型、渠道、来源等优先使用枚举。
+- 常量按功能归类，不要维护一个“大而全”的常量类。
+- 枚举类建议以 `Enum` 结尾，枚举项全大写并使用下划线分隔。
+
+### DTO 与参数校验要点
+
+- DTO 字段校验优先使用 `jakarta.validation` 注解，Controller 入参用 `@Valid` / `@Validated` 触发，嵌套对象与集合元素用 `@Valid` 级联。
+- 禁止使用 `javax.validation` 包；Spring Boot 3+ 统一 Jakarta Validation。
+- 简单字段校验交给 DTO 注解，不在 Service 中重复写 `if`；跨字段、依赖外部数据、权限幂等等复杂校验才用代码校验。
+
+> 完整规则与示例见 `references/validation.md`。
+
+### Lombok 与 POJO 要点
+
+- 创建 DO / DTO / VO / BO / Query / Command 等数据承载对象时，优先使用 Lombok 注解生成 getter、setter、构造器、`toString`、Builder 等样板代码。
+- 字段较多或可选参数较多时优先 `@Builder` + `Xxx.builder().field(value).build()`；框架反射创建对象时保留无参构造器。
+- 谨慎使用 `@Data`：涉及继承、实体、缓存 key、集合元素去重或需精确控制 `equals` / `hashCode` 的类，改用更明确的 `@Getter`、`@Setter`、`@ToString`、`@EqualsAndHashCode`。
+
+> 完整规则与示例见 `references/pojo-lombok.md`。
+
+## Review 检查清单
+
+Review Java 代码时至少检查：
+
+- DTO 字段校验是否优先使用 `jakarta.validation` 注解。
+- 是否误用了 `javax.validation`。
+- 字符串、包装类型、对象、集合判断是否使用空安全工具类。
+- 是否存在 `==` 比较字符串、包装类型或业务值对象。
+- 数据承载对象是否优先使用 Lombok 注解，字段较多的对象创建是否优先使用 Builder。
+- 是否出现魔法值。
+- 同类或跨类重复代码是否出现 3 次及以上。
+- 是否存在过深嵌套、超长方法或复杂条件表达式。
+- 异常是否被吞掉，日志是否重复打印或泄露敏感信息。
+- SQL 是否显式列字段、使用参数绑定并命中必要索引。
+- 新增核心逻辑是否有单元测试覆盖。

package/skills/java/spring-boot-engineer_zn/references/architecture.md

@@ -0,0 +1,23 @@
+# 工程结构与设计
+
+## 重复代码与抽象
+
+- 同一段或高度相似代码出现 3 次及以上，必须评估抽取。
+- 简单业务复用优先抽为 `private` 方法或领域服务方法。
+- 跨类复用优先抽为公共组件、工具类、模板方法或策略类。
+- 跨层、横切关注点优先考虑 AOP、Filter、Interceptor、注解驱动组件，例如：
+  - 登录态、权限、租户、审计、幂等、限流、防重放。
+  - 统一日志、埋点、异常转换、接口耗时统计。
+  - 重复的通用参数校验逻辑。
+- DTO 简单字段校验重复出现时，不要抽 `checkXxx` 方法，应优先回到 DTO 上加 Jakarta Validation 注解。
+
+## 工程结构与设计
+
+- 上层可以依赖下层，下层不要反向依赖上层。
+- Web 层负责协议适配、基础参数校验和转发，不承载复杂业务。
+- Service / Manager 层承载业务编排和领域逻辑。
+- DAO 层只处理持久化，不写业务逻辑。
+- 类应遵守单一职责。
+- 优先组合 / 聚合，谨慎使用继承。
+- 依赖抽象而非具体实现，保持扩展开放、修改封闭。
+- 状态超过 3 个、对象协作复杂、调用链涉及对象超过 3 个时，应考虑补充状态图、时序图或类图辅助设计。

package/skills/java/spring-boot-engineer_zn/references/concurrency.md

@@ -0,0 +1,9 @@
+# 并发规则
+
+- 线程资源必须通过线程池提供，不允许随意 `new Thread`。
+- 线程池不使用 `Executors` 快捷方法，应通过 `ThreadPoolExecutor` 明确核心参数。
+- 线程和线程池必须有可识别的业务名称。
+- `ThreadLocal` 使用后必须在 `finally` 中清理。
+- 多资源加锁必须保持一致顺序，避免死锁。
+- 并发更新同一记录必须考虑锁、版本号、幂等或唯一约束。
+- `SimpleDateFormat` 不得作为共享静态变量；优先使用 `java.time`。

package/skills/java/spring-boot-engineer_zn/references/exception-logging.md

@@ -0,0 +1,31 @@
+# 异常处理与日志
+
+## 异常处理
+
+- 异常不得用于流程控制。
+- 能通过预检查避免的 RuntimeException，不应依赖 catch 兜底。
+- catch 后必须处理、转换或记录，不允许空 catch。
+- 事务代码中 catch 后如果需要回滚，必须显式处理回滚或继续抛出异常。
+- `finally` 中禁止 `return`。
+- 流和资源优先使用 `try-with-resources`。
+- 对外接口使用统一错误码或统一响应结构；应用内部优先通过明确的业务异常表达失败。
+- 方法返回值允许为 null 时，必须通过注释、Optional 或调用约定说明清楚。
+
+## 日志规则
+
+- 使用 SLF4J 等统一日志门面，不直接依赖具体日志实现 API。
+- 日志变量拼接使用占位符，不使用字符串拼接。
+- `trace` / `debug` / 大量 `info` 日志输出前必须判断日志级别。
+- 不要重复打印同一个异常；上层已记录时下层不要重复记录完整堆栈。
+- 异常日志必须包含现场信息和异常堆栈。
+- 生产环境禁止输出敏感数据，用户敏感信息必须脱敏。
+
+示例：
+
+```java
+if (log.isDebugEnabled()) {
+    log.debug("Create user request, orgId={}, userName={}", orgId, userName);
+}
+
+log.error("Create user failed, orgId={}, userName={}", orgId, userName, exception);
+```

package/skills/java/spring-boot-engineer_zn/references/persistence.md

@@ -0,0 +1,13 @@
+# MySQL 与 ORM
+
+- 表名、字段名使用小写字母、数字和下划线，禁止保留字。
+- 表名不使用复数。
+- 表必须包含 `id`、`create_time`、`update_time` 等基础字段，除非项目规范另有说明。
+- 表达是与否的数据库字段使用 `is_xxx`，Java POJO 字段不要使用 `is` 前缀，并在映射中处理。
+- 小数类型使用 `decimal`，禁止用 `float` / `double` 存储精确金额。
+- 具备唯一业务语义的字段必须建立唯一索引。
+- 查询字段必须显式列出，禁止 `select *`。
+- MyBatis 参数使用 `#{}`，禁止 `${}` 拼接用户输入。
+- 分页查询时如果 `count` 为 0，应直接返回，不继续执行分页查询。
+- 更新记录时必须维护更新时间字段。
+- `@Transactional` 不要滥用，事务范围应尽量小且语义明确。

package/skills/java/spring-boot-engineer_zn/references/pojo-lombok.md

@@ -0,0 +1,48 @@
+# OOP 与 POJO
+
+## OOP 与 POJO 通用规则
+
+- 所有覆写方法必须添加 `@Override`。
+- 禁止使用过时类或过时方法。
+- DO / DTO / VO 等 POJO 字段必须使用包装类型，局部变量可使用基本类型。
+- POJO 类必须提供可读的 `toString`，避免遗漏关键字段；优先使用 Lombok `@ToString` 生成。
+- POJO 布尔字段不要以 `is` 开头，避免序列化和反序列化歧义。
+- 构造方法中禁止写业务逻辑；初始化逻辑放到明确的初始化方法或工厂方法。
+- `BigDecimal` 禁止使用 `new BigDecimal(double)`，应使用字符串或 `BigDecimal.valueOf`。
+- 循环体内字符串拼接优先使用 `StringBuilder`。
+- 访问控制从严，能 `private` 不 `protected`，能包内可见不 `public`。
+
+## Lombok 使用规则
+
+- 创建 DO / DTO / VO / BO / Query / Command 等数据承载对象时，优先使用 Lombok 注解生成 getter、setter、构造器、`toString`、Builder 等样板代码。
+- 常用组合：
+  - 可变 DTO / VO：`@Getter`、`@Setter`、`@ToString`、`@NoArgsConstructor`
+  - 需要全参构造：增加 `@AllArgsConstructor`
+  - 字段较多或可选参数较多：增加 `@Builder`，创建对象时优先使用 `Xxx.builder().field(value).build()`
+  - 继承结构下的 Builder：使用 `@SuperBuilder`
+  - 不可变值对象：优先使用 `@Value` 或 `@Getter` + `final` 字段，按项目约定选择
+- Jackson、MyBatis、JPA 等框架需要反射创建对象时，应保留无参构造器，例如 `@NoArgsConstructor`。
+- DTO 字段不要为了 Lombok `@Builder.Default` 设置默认值；确有业务默认值时，应在业务层、工厂方法或明确的初始化流程中处理。
+- 谨慎使用 `@Data`：纯 DTO / VO 可按项目约定使用；涉及继承、实体、缓存 key、集合元素去重或需要精确控制 `equals` / `hashCode` 的类，应改用更明确的 `@Getter`、`@Setter`、`@ToString`、`@EqualsAndHashCode`。
+
+推荐写法：
+
+```java
+@Getter
+@Setter
+@ToString
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class UserDTO {
+
+    private Long id;
+
+    private String userName;
+}
+
+UserDTO user = UserDTO.builder()
+    .id(userId)
+    .userName(userName)
+    .build();
+```

package/skills/java/spring-boot-engineer_zn/references/security.md

@@ -0,0 +1,9 @@
+# 安全规则
+
+- 用户请求传入的任何参数必须做有效性验证。
+- 用户个人页面或功能必须做权限控制，避免越权访问。
+- 敏感数据展示、日志输出、接口返回必须脱敏。
+- SQL 参数必须使用参数绑定，禁止拼接用户输入。
+- HTML 输出用户数据必须正确转义或过滤。
+- 表单和 AJAX 提交按项目规范执行 CSRF 校验。
+- 下单、支付、短信、邮件等资源消耗型接口必须考虑幂等、防重放、防刷和频率限制。

package/skills/java/spring-boot-engineer_zn/references/testing.md

@@ -0,0 +1,7 @@
+# 单元测试
+
+- 单元测试应自动化、独立、可重复执行。
+- 测试代码放在 `src/test/java`。
+- 核心业务、核心模块和缺陷修复必须补充测试。
+- 测试不要依赖外部环境顺序、数据库已有数据或测试执行顺序。
+- 对复杂分支、边界条件、异常路径、参数校验规则应覆盖测试。

package/skills/java/spring-boot-engineer_zn/references/validation.md

@@ -0,0 +1,80 @@
+# DTO 与参数校验
+
+## Jakarta Validation 优先
+
+- DTO 字段非空、长度、范围、格式等校验，必须优先使用 `jakarta.validation` 包下的注解。
+- 禁止使用 `javax.validation` 包；Spring Boot 3+ 项目统一使用 Jakarta Validation。
+- Controller 入参 DTO 使用 `@Valid` 或 `@Validated` 触发校验。
+- 嵌套对象、集合元素需要级联校验时使用 `@Valid`。
+- DTO 字段不要设置默认值，避免框架反序列化和业务语义混淆。
+
+常用注解优先级：
+
+```java
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.AssertTrue;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Positive;
+import jakarta.validation.constraints.Size;
+```
+
+推荐写法：
+
+```java
+public class CreateUserDTO {
+
+    @NotBlank(message = "用户名不能为空")
+    @Size(max = 64, message = "用户名长度不能超过64")
+    private String userName;
+
+    @NotNull(message = "组织ID不能为空")
+    @Positive(message = "组织ID必须为正数")
+    private Long orgId;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+
+    @Valid
+    @NotEmpty(message = "明细不能为空")
+    private List<CreateUserItemDTO> items;
+}
+```
+
+Controller 示例：
+
+```java
+@PostMapping("/users")
+public Result<Void> createUser(@Valid @RequestBody CreateUserDTO request) {
+    userService.createUser(request);
+    return Result.success();
+}
+```
+
+## 代码校验只作为补充
+
+- 简单字段校验不得在 Service 中重复写 `if` 判断，应交给 DTO 注解。
+- 以下场景可以使用代码校验：
+  - 跨字段关系，例如 `startTime` 必须早于 `endTime`。
+  - 依赖数据库、缓存、外部服务的业务校验。
+  - 权限、幂等、防重放、防刷等上下文相关校验。
+  - 注解表达成本过高或会显著降低可读性的复杂条件。
+- 跨字段规则优先考虑 `@AssertTrue`、自定义约束注解或类级别 Validator；仍不适合时才写业务代码校验。
+- 方法参数校验可在类上使用 `@Validated`，并在 public 方法参数上使用 Jakarta Validation 注解。
+
+示例：
+
+```java
+@AssertTrue(message = "开始时间必须早于结束时间")
+public boolean isTimeRangeValid() {
+    if (startTime == null || endTime == null) {
+        return true;
+    }
+    return startTime.isBefore(endTime);
+}
+```