@ifrankwang/openspec-agents 0.118.0

package/assets/skills/ddd-architecture/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: ddd-architecture
+description: DDD 架构规范——四层分层与六边形（Hexagonal）两种包组织风格、层间依赖、各层职责、风格判定、CQRS、聚合设计、Repository 语义、领域事件、值对象、Port/Adapter。方法论本身语言无关。
+capabilities: ["architecture"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+
+## 包结构（概念层）
+
+同一套依赖原则有两种包组织方式，均属合法实现，采用哪种由项目声明（见"架构风格判定"）。两者不是互斥架构，而是同一依赖方向的两种包组织视角。
+
+**方式一：四层分层**
+
+```
+{basePackage}
+├── domain          ← 核心领域逻辑（聚合根、实体、值对象、领域服务、Repository 接口）
+│   ├── model       ← 聚合根、实体、值对象（纯业务对象，零外部依赖）
+│   ├── service     ← Domain Service
+│   ├── repository  ← Repository 接口
+│   └── exception   ← 领域异常
+├── application     ← 用例编排（Command/Query 入口、应用层服务）
+│   ├── command     ← 写操作命令
+│   ├── query       ← 读操作查询
+│   ├── service     ← Application Service
+│   └── dto         ← 模块间传输 DTO
+├── infrastructure  ← 技术实现（持久化、外部集成、ACL 适配）
+└── interfaces      ← 外部访问入口（Controller、API 网关、消息监听）
+```
+
+**方式二：六边形（Hexagonal）**
+
+六边形按"内核 ↔ 适配器"组织，内核承载全部领域与应用逻辑，外部依赖以适配器形式接入：
+
+```
+{basePackage}
+├── domain            ← 内核组成：核心领域逻辑、driven port 接口
+├── application       ← 内核组成：用例编排、driving port 接口
+├── driving adapter   ← 入站适配器：外部访问入口，调用 application 定义的 driving port
+└── driven adapter    ← 出站适配器：技术实现，实现 domain 定义的 driven port
+```
+
+- **内核** = domain + application：domain 承载核心领域逻辑（聚合根、实体、值对象、领域服务）并定义 driven port（持久化、外部集成等能力契约）；application 承载用例编排（Command/Query 入口、应用层服务）并定义 driving port（外部用例入口契约）
+- **driving adapter（入站）** 对应外部访问入口（API 网关、消息监听等），把外部调用翻译为内核用例
+- **driven adapter（出站）** 对应技术实现（持久化、外部集成、ACL 适配），把内核契约翻译为具体技术调用
+
+四层与六边形的对应关系见"两种风格的双向映射"。
+
+## 层间依赖
+
+**四层分层**：
+
+```
+interfaces → application → domain ← infrastructure
+```
+
+箭头方向即依赖方向：interfaces 依赖 application，application 依赖 domain，infrastructure 实现 domain 定义的 Port/Repository 接口。infrastructure 不依赖 interfaces，interfaces 不直接依赖 infrastructure。
+
+**六边形**：
+
+```
+driving adapter → application → domain ← driven adapter
+```
+
+依赖一律指向内核（domain + application）：driving adapter 依赖 application 定义的 driving port（入站端口），driven adapter 实现 domain 定义的 driven port（出站端口）并依赖该接口。adapter 之间无依赖，内核不依赖任何 adapter。依赖倒置只发生在 driven 方向——driven adapter 依赖内核定义的 Port 接口，而非反向。
+
+## 两种风格的双向映射
+
+四层分层与六边形是同一套依赖原则（依赖一律指向内核）的两种包组织视角，对应关系如下：
+
+| 四层分层 | 六边形 | 说明 |
+|---------|--------|------|
+| domain + application | 应用内核 | 内核由领域与应用逻辑共同构成，domain 是内核的一部分 |
+| interfaces | driving adapter（入站适配器） | 外部访问入口，调用内核 |
+| infrastructure | driven adapter（出站适配器） | 技术实现，依赖内核定义的 Port 接口 |
+
+依赖方向在两种视角下完全一致：外部入口（interfaces / driving adapter）→ 内核（application → domain）← 技术实现（infrastructure / driven adapter）。
+
+## 架构风格判定
+
+两种风格不是互斥选择，判定项目采用哪种包组织视角，依据以下特征对照：
+
+| 识别特征 | 四层分层 | 六边形 |
+|---------|---------|--------|
+| 包组织方式 | 显式 interfaces / application / domain / infrastructure 四层 | 显式内核与适配器边界（adapter/in、adapter/out，或 interfaces/infrastructure 承担 adapter 语义） |
+| Port 接口定义位置 | domain 层 | 内核（domain 定义 driven port，application 定义 driving port） |
+| 外部访问入口定位 | interfaces 层 | driving adapter（入站） |
+| 技术实现定位 | infrastructure 层 | driven adapter（出站） |
+
+混杂场景兜底：项目 design/架构文档已声明架构风格的，以声明为准；未声明时按四层分层认定。Port 定义位置差异（domain 或 application）不单独构成问题；四层风格项目以 interfaces/infrastructure 承担 adapter 语义的组织方式不视为违规。
+
+## 各层职责
+
+| 层 | 职责 | 禁止 |
+|----|------|------|
+| interfaces | 参数校验、调用 application、DTO 转换 | 写业务逻辑、直接访问 infrastructure/domain 实体 |
+| application | 编排业务用例、事务边界、协调 domain service | 技术实现细节（SQL、HTTP、LLM 调用） |
+| domain | 核心领域逻辑、聚合根行为、领域服务 | 任何框架依赖 |
+| infrastructure | 技术实现：持久化、外部集成、ACL 转换 | 业务规则判断 |
+
+六边形视角下，interfaces 即 driving adapter（入站适配器），infrastructure 即 driven adapter（出站适配器），职责与禁止项对应不变。
+
+## 通用语言（Ubiquitous Language）
+
+每个 Bounded Context 必须维护一份术语表，记录业务名词及其含义。开发、产品、业务方统一使用此表沟通，代码命名以此为基准。
+
+### 术语表位置
+
+```
+{basePackage}/domain/language.md
+```
+
+### 术语表格式
+
+```
+# {Bounded Context} — 通用语言
+
+| 术语 | 英文名 | 含义 | 代码位置 |
+|------|--------|------|---------|
+| ... | ... | ... | ... |
+```
+
+### 命名规则
+
+- 代码类名、方法名、字段名必须与术语表一致，禁止翻译/缩写
+- 值对象用不可变类型，枚举用枚举类型，实体用引用类型——类型选择本身就是语言表达
+- 跨 Bounded Context 的同一术语含义必须一致
+
+### 命名合理性判据
+
+命名规则与判据分工互补：命名规则定义静态一致性约束——代码命名必须与术语表一致；命名合理性判据是判定标准，识别命名是否体现意图、是否造成混淆、是否出现漂移，修正动作即对一致性约束的执行。
+
+- 命名须实际体现概念意图，禁止用泛化命名（如 process/handle/data/info）掩盖真实语义
+- 同义概念全库统一命名，禁止同名不同义或近义不同名造成场景混淆
+- 代码命名偏离术语表即为漂移信号，识别后回溯术语表修正，回归一致性约束
+
+## CQRS 读写分离
+
+Command（写）和 Query（读）走不同路径，互不混淆：
+
+```
+Command 路径: Controller → ApplicationCommandService → Domain Model → Repository（写）
+Query 路径:   Controller → ApplicationQueryService → 直接查询投影（DTO）
+```
+
+- Command 走 domain 层：调用聚合根行为 → Repository 持久化
+- Query 不走 domain 层：直接映射到查询投影（DTO），禁止加载 domain 实体再转换
+- Command 方法返回简单结果（仅 ID/成功/失败），不返回 domain 实体
+- Query 方法返回值必须是 DTO，禁止返回 Entity 或 PO
+- 同一用例中禁止混用 Command 和 Query 逻辑
+
+## 充血模型
+
+Domain 实体必须是充血模型——行为封装在实体内部，禁止仅 getter/setter 的贫血模型。
+
+- 业务逻辑不得在 Service 中操作实体状态后再调用 save——改实体自身方法
+- 判定：删掉所有 setter 后业务逻辑是否还能运转？能 → 充血；不能 → 贫血
+
+## 聚合设计
+
+| 原则 | 说明 |
+|------|------|
+| 聚合边界 = 事务边界 | 一个事务只修改一个聚合，跨聚合用最终一致性 |
+| 聚合根是唯一入口 | 外部只能通过聚合根方法访问聚合内部 |
+| 跨聚合引用仅 ID | 聚合 A 引用聚合 B 时只存 B 的 ID，不存对象引用 |
+| 聚合内一致性 | 聚合根负责子实体一致性校验，禁止外部直接修改子实体 |
+
+## Repository 领域语义
+
+Repository 语义与架构风格无关，四层与六边形均适用：契约（接口）定义在核心（domain），实现落在基础设施/出站侧。
+
+Repository 对 domain 层暴露集合语义，不暴露持久化语义：
+
+- `findById` 返回 domain 实体，不存在则抛异常——领域层决定不存在语义
+- 查询方法名具领域语义（`findActiveOrdersByCustomerId`），不暴露技术细节
+- 领域查询接口在 domain 层定义，具体实现（含 SQL）在 infrastructure 层
+- 纯查询投影（非 domain 实体）走 CQRS Query 路径，不经过 Repository
+
+## Domain Event
+
+Domain Event 语义与架构风格无关，四层与六边形均适用：事件契约定义在 domain/内核，事件处理实现落在 infrastructure/出站侧。
+
+- 领域事件定义在 domain 层，事件处理在 infrastructure 层
+- 事件定义为不可变值对象，命名 `{Entity}{PastParticiple}Event`
+- Application Service 在事务提交后发布事件
+- 事件处理类在 infrastructure 层，使用事件总线或消息队列
+
+## Factory
+
+- 复杂领域对象创建逻辑归 Factory，不放在构造函数中
+- 简单对象用静态工厂方法
+- 复杂组装用 Domain Factory（domain 层），不依赖外部技术
+- 涉及外部数据/技术实现的创建用 Application Factory（application 层）
+
+## Specification
+
+Specification 将业务规则封装为可组合的谓词对象，用于判定候选对象是否满足特定条件：
+
+- 接口定义 `isSatisfiedBy(T candidate)` + `and/or/not` 组合方法
+- 原子规则类以 `Spec` 后缀命名
+- 组合通过链式调用，无需额外工厂
+- 入参为领域实体或值对象，不在 Specification 中引入基础设施依赖
+
+## Anti-Corruption Layer
+
+防腐层（ACL）隔离外部模型与领域模型：
+
+- ACL 位于 infrastructure 层
+- 输入方向：ACL 将外部模型（第三方 API、遗留系统）转换为领域模型
+- 输出方向：ACL 将领域模型转换为外部模型
+- 约束：领域模型不依赖外部模型，ACL 转换方向仅为 infrastructure → domain
+
+六边形视角下，ACL 属 driven adapter（出站适配器）中的转换组件，方向约束同"adapter → 内核"。
+
+## 外部系统命名隔离
+
+命名基准是领域术语表（见「通用语言」章节），外部系统名不属于领域语言。外部系统（第三方 API、遗留系统、中间件）的命名与模型只允许出现在 infrastructure 层（四层）/ driven adapter（六边形），禁止通过接口契约上浮到内核与外部访问入口。
+
+- 接口/方法命名用领域语义：Port 接口名与方法名（如 CustomerQueryPort.queryCustomer）禁止出现外部系统名（如 SapQueryPort、queryFromErp）
+- DTO 命名用领域语义：application/interfaces 层 DTO 类名与字段名（如 CustomerDetailResponse）禁止出现外部系统名（如 SapCustomerResponse、字段 sapOrderNo）
+- 跨层传输的数据须经 ACL/assembler 转换为领域语义对象，外部模型类型禁止出现在内核与 interfaces 层的接口签名中
+- 外部系统名仅限 infrastructure 层实现类、ACL 转换类与配置（如 SapClient、ErpOrderConverter）
+
+六边形视角下，外部系统名仅限 driven adapter（出站适配器）实现类与配置。
+
+## Port / Adapter 模式
+
+Port 接口是内核（domain + application）定义的纯业务契约，Adapter 是实现契约的技术适配组件，按方向分两类：
+
+- **driving port / driving adapter（入站）**：driving port 由 application 定义（外部用例入口契约），由 application 层应用服务实现；driving adapter 在外部访问入口调用该端口。依赖方向：外部入口 → application。
+- **driven port / driven adapter（出站）**：driven port 由 domain 定义（持久化、外部集成等能力契约），driven adapter 在基础设施/出站侧实现。依赖方向：infrastructure 依赖 domain 的 Port 接口（依赖倒置）。
+
+四层分层下两类分别落在 interfaces 与 infrastructure；六边形下即 adapter/in 与 adapter/out（或由 interfaces/infrastructure 承担 adapter 角色）。
+
+## 共性能力基础设施化
+
+应统一拦截/封装到 Infrastructure 层或框架级能力的横向逻辑，不得分散在各 Controller/Service 中逐点调用。
+
+### 适用场景
+
+| 类别 | 示例 | 上收方式 |
+|------|------|---------|
+| 横切关注点 | 鉴权·审计·日志·限流·幂等·事务 | 拦截器 / 过滤器 / AOP |
+| 重复集成封装 | 外部 API 调用、序列化/转换 | 公共 Client/Adapter 基类 |
+| 散落的全局配置 | 超时·重试·线程池·白名单 | 统一配置文件集中管理 |
+
+### 判据
+
+同一逻辑在 ≥2 处独立实现、属横向共性需求（非单点业务上下文特有）、新增场景漏调度即失效 → 必须基础设施化。
+
+## 方案复用与平行实现
+
+同类能力已有既有实现时，新方案须复用或扩展现有实现，禁止另起一套逻辑——引入与既有实现功能重叠的新实现且不改动原实现，导致同类能力多套方案并存。
+
+### 适用场景
+
+已有手工实现的限流基础框架，新方案引入新限流框架且不动原代码——同类能力多套方案并存，维护与认知成本翻倍。
+
+### 判据
+
+同类能力已有既有实现 → 优先复用或扩展既有实现。确需平行引入（新旧并存）时，方案须附带既有实现的迁移方案。

package/assets/skills/environment-cleanup/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: environment-cleanup
+description: 隔离环境清理通用规范——停止残留服务、清理隔离容器/数据库、删除隔离扫描分析项目。技术栈无关。
+capabilities: ["cleanup"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 清理以幂等为原则：无残留即通过，不因重复执行报错或产生副作用。
+
+## 停止残留的服务实例
+
+按项目的启动方式反向停止本次变更启动的服务实例：
+
+- 经进程启动的服务：定位本次启动的进程并停止（如按启动命令/端口反查 PID），禁止误杀其他变更或他人启动的进程
+- 经容器编排启动的服务：按本变更的隔离标识停止对应 compose 项目
+
+停止后确认端口监听已释放：监听端口不再有进程响应即视为已停止。
+
+## 清理隔离环境
+
+按本变更的隔离标识确认无残留的隔离资源后再清理：
+
+- 隔离容器：按隔离标识确认存在性后停止并移除（无残留容器即通过，不因重复清理报错）
+- 隔离数据库：确认无残留的隔离数据库实例/数据卷后清理；无残留即通过
+
+幂等判据：隔离标识下无残留容器、无残留隔离数据库即为清理完成，重复执行不产生副作用。
+
+## 删除隔离扫描分析项目
+
+本变更的隔离扫描分析项目（如按隔离标识命名的分析项目）在变更结束时删除：
+
+1. 先查询确认项目存在（按隔离标识查询），不存在视为已删除，跳过删除动作
+2. 确认存在后调用删除接口删除该项目（如平台管理接口的 delete 操作）
+3. 删除接口返回「不存在」错误视为已删除（幂等：删除动作可重复执行）
+
+删除后如需重新扫描，由「先查询后创建」的逻辑自动重建（创建前先查存在性，不存在才创建，避免重复创建报错），无需人工干预。
+
+## 清理后自检
+
+清理完成后自检以下各项，全部无残留即通过：
+
+- 无残留的服务进程（本次启动的进程已停止，端口监听已释放）
+- 无残留的隔离容器（隔离标识下 compose ps 为空）
+- 无残留的隔离扫描分析项目（按隔离标识查询不存在）

package/assets/skills/java-api-conventions/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: java-api-conventions
+description: 仅限 Java 后端开发场景。接口层 Java/Spring 实现规范——Spring 注解、Swagger/SpringDoc 注解、R<T> 统一返回、@RestControllerAdvice 异常处理。通用 REST 设计原则见 api-conventions。适用场景同前。
+capabilities: ["api-design", "architecture", "tech-stack-java"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本 skill 是 api-conventions 的 Java 实现配套，仅含 Java/Spring 特有实现细节。通用 REST 设计原则见 api-conventions。调用本 skill 须同时加载 api-conventions。
+
+## Controller 层规范
+
+| # | 规则 | 说明 |
+|---|------|------|
+| 1 | 必须用 `@RestController` | |
+| 2 | `@Validated` + `jakarta.validation` 校验参数 | 注解加在 DTO 字段上，入口触发校验 |
+| 3 | 统一返回 `R<T>` | 除文件下载等特殊场景外 |
+
+## 统一返回 R<T>
+
+所有接口统一返回 `R<T>` 包装，成功用 `R.success(data)`，失败携带业务错误码与消息。结构约定：
+
+- `code`：业务错误码（数字），成功时为 0 或约定成功值
+- `message`：错误描述，支持 `{}` 动态占位参数
+- `data`：业务数据泛型
+
+## 异常响应体系
+
+Controller 层不直接处理异常，由全局 `@RestControllerAdvice` 处理器按异常类型映射 HTTP 状态码。
+
+业务错误码作为 `R<T>` 响应体中独立数字字段，与 HTTP 状态码解耦：HTTP 码供客户端/网关判断大类，业务错误码供前端精确分支处理。

package/assets/skills/java-code-maintainability/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: java-code-maintainability
+description: Java 代码可维护性规范——方法长度、类职责、异常处理、MapStruct 转换、魔法数提取、DRY 禁止、死代码、构建忽略项。仅在 Java 后端项目使用。
+capabilities: ["maintainability", "tech-stack-java"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本文列出**最低审查基线**，不限于所列维度。AI 审查时必须结合自身可维护性知识做拓展覆盖，下列任何可能遗漏的可维护性问题均须纳入审查。
+
+## 方法长度
+
+- 单方法不超过 50 行（含空行和注释，不含花括号单独行）
+- 超过且逻辑难以理解 → Medium 级别 issue
+- 超过但逻辑清晰可读（如配置方法）→ Low 级别 issue
+
+## 类单一职责
+
+- 一个类不超过一个变更原因
+- 明显多职责场景（如同时处理持久化 + 业务逻辑 + 序列化）→ Medium 级别 issue
+
+## 异常处理
+
+- 禁止吞掉异常（空 catch 块）→ High 级别 issue
+- 禁止 `catch (Exception e)` 不加区分——优先捕获具体异常类型，多个异常类型分别处理或用多 catch 块 → Medium
+- 使用 try-with-resources 确保资源自动关闭 → High 级别 issue（未关闭资源）
+
+## MapStruct 转换
+
+```java
+@Mapper(componentModel = "spring")
+public interface OrderConverter {
+    Order toDomain(OrderPO po);
+    OrderPO toPO(Order domain);
+}
+```
+
+- 必须 `componentModel = "spring"`；字段映射用 `@Mapping(source, target)`
+- 禁止手写 PO ↔ Domain 转换逻辑，必须用 MapStruct
+
+## 魔法数提取常量
+
+- 业务含义数字须提取为命名常量（`private static final ...`）
+- 数字 0/1/-1 等通用值可不提取，但业务相关值如 `50000000`（高额订单阈值）必须提取
+
+## DRY 违规
+
+- 相同语义的代码段在 ≥3 处复用时必须提取为共享函数
+- 违反 → Low+ 级别 issue
+
+## 构建忽略项
+
+- 构建产物目录（`target/`、`node_modules/`、`dist/`）不得提交仓库
+- 已在 .gitignore 中配置即可
+
+## 死代码
+
+- 未使用的 import / 私有方法 / 字段 / 局部变量 → Low 级别 issue
+- 注释掉的代码：零散行 → Low 级别 issue；注释掉的整段逻辑 → Medium 级别 issue（历史追溯依赖版本控制，注释掉的代码应删除而非保留）
+- 不可达分支 / 失效条件判断 → Medium 级别 issue
+- 未被引用的类 / 接口 → Medium 级别 issue
+- 未使用的依赖 → Low 级别 issue
+- 识别未使用字段/方法时排除框架反射与代码生成场景（如 MapStruct、MyBatis、Lombok）

package/assets/skills/java-code-performance/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: java-code-performance
+description: Java 性能规范——N+1 查询防范、外部调用超时与重试、大文件流式读取、循环优化、对象创建优化、缓存策略、异步处理。仅在 Java 后端项目使用。
+capabilities: ["performance", "tech-stack-java"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本文列出**最低审查基线**，不限于所列维度。AI 审查时必须结合自身性能知识做拓展覆盖，下列任何可能遗漏的性能问题均须纳入审查。
+
+## N+1 查询防范
+
+- 列表查询必须用 MyBatis `collection`/`association` 嵌套映射或手动批量查询
+- 禁止循环内逐条查询数据库 → Medium 级别 issue
+
+## 外部调用超时与重试
+
+- RestTemplate：通过 `SimpleClientHttpRequestFactory` 设 connectTimeout / readTimeout
+- WebClient：通过 `HttpClient.responseTimeout()` / `.option()` 设超时
+- Spring Cloud OpenFeign：`feign.client.config.<service>.connect-timeout` / `read-timeout`
+- LLM 调用：默认超时 120s
+- 所有外部调用必须有重试策略（含退避与熔断），禁止无限重试
+- 所有超时值 > 0，普通 HTTP 建议 10-30s
+
+## 大文件处理
+
+- Excel 读取用 SXSSFWorkbook：`new SXSSFWorkbook(new XSSFWorkbook(inputStream), 100)`
+- 禁止直接用 `XSSFWorkbook` 加载全量数据（OOM 风险）
+- 大列表数据用分页查询 + Stream API 处理
+
+## 循环优化
+
+- 禁止循环内同步 I/O 调用（数据库、HTTP、LLM）→ High 级别 issue（循环内无超时的同步调用 → Critical）
+- 循环内外部调用应在循环层级之上做批量聚合或异步并发
+
+## 对象创建优化
+
+- 避免循环内不必要的对象创建（在循环外创建可复用的对象）
+- 使用 StringBuilder 替代循环内字符串拼接字符串 `s += ...` 模式
+
+## 缓存策略
+
+- 频繁访问且变化不频繁的数据应使用缓存（Spring Cache / Caffeine / Redis）
+- 缓存粒度：按业务维度拆分而非全量缓存
+- 注意缓存失效策略与数据一致性约束
+
+## 异步处理
+
+- 队列消费：确保线程池大小合理，不超过外部服务承载能力
+- 异步任务须有超时保护和失败处理

package/assets/skills/java-code-style/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: java-code-style
+description: Java 代码风格规范——Lombok 注解优先、日志约定、Swagger/SpringDoc 注解、.gitignore 必须项、命名约定。仅在 Java 后端项目使用。
+capabilities: ["style", "tech-stack-java"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本文列出**最低审查基线**，不限于所列维度。AI 审查时必须结合自身代码风格知识做拓展覆盖，下列任何可能遗漏的代码风格维度均须纳入审查。
+
+## 日志规范
+
+- Lombok 存在（pom.xml 中检测到 lombok 依赖）时必须用 `@Slf4j` 替代手动 `LoggerFactory.getLogger()`
+- 检测方法：逐文件扫描 pom.xml 中是否含 `lombok` 依赖，若存在则该项目中所有新写/修改的类须使用 `@Slf4j` 生成 Logger 字段
+- 范围控制：首轮审查仅对 diff 内新增/修改的类提出 issue（Low+ 阻塞），已存在的手动 Logger 按原严重级别正常提交
+- Logger 字段名统一用 `log`
+- 参数化日志：`log.info("order {} status {}", orderId, status)`，禁止字符串拼接构造日志消息
+- 敏感数据（密码、Token、身份证号等）禁止出现在日志输出中
+
+## Lombok 注解使用约束
+
+项目引入 Lombok 时，如下场景必须优先使用 Lombok 注解而非手写等价代码：
+- `@Getter` / `@Setter` — 替代手写 getter/setter（非贫血模型中业务行为不在此限）
+- `@Builder` / `@Data` — 替代手写 builder / 值对象全部模板代码
+- `@Slf4j` / `@Log4j2` — 替代手动 Logger 字段声明
+- `@RequiredArgsConstructor` — 替代构造器注入的手动构造器（已有 DDD 构造器注入约束，此为补充方案）
+
+异常情况：getter/setter 有额外业务逻辑时（如校验、计算），不强制用 `@Getter`/`@Setter`，须手写
+
+## Swagger/SpringDoc 注解
+
+引入 SpringDoc OpenAPI（`springdoc-openapi-starter-webmvc-ui`）后：
+- Controller 类：`@Tag(name = "xxx相关接口")`
+- 接口方法：`@Operation(summary = "xxx")`
+- DTO 字段：`@Schema(description = "xxx")`
+
+## .gitignore
+
+必须包含：
+```
+target/
+*.log
+.idea/
+*.iml
+.env
+```
+
+## 命名规范
+
+- 类名：PascalCase，业务领域名词
+- 方法名：camelCase，动宾短语
+- 常量：UPPER_SNAKE_CASE（static final 字段）
+- 变量：camelCase，有业务含义
+- 测试类：`{ClassName}Test`
+- 测试方法：`test{MethodName}`

package/assets/skills/java-db-conventions/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: java-db-conventions
+description: 仅限 Java 后端开发场景。数据库规范——MyBatisPlus 持久化用法、审计字段自动填充、Flyway 迁移。通用 DB 设计约定见 db-conventions。适用场景同前。
+capabilities: ["db-design", "architecture", "tech-stack-java"]
+---
+
+> **项目规范优先**：本 skill 所列约定为推荐标准。若项目已有明确规范且与本 skill 不一致，以项目规范为准。
+> 本 skill 是 db-conventions 的 Java 实现配套，仅含 Java/Spring 特有实现细节。通用 DB 约定见 db-conventions。调用本 skill 须同时加载 db-conventions。
+
+## 操作人来源
+
+操作人标识从 JWT 还原：`OncePerRequestFilter` 校验 JWT 并将身份写入 SecurityContext，持久化层从中提取填充审计字段 `creator`/`updater`。
+
+## MyBatisPlus 持久化用法
+
+| 项 | 约定 |
+|----|------|
+| Mapper 包路径 | `{basePackage}.infrastructure.persistence`（由 `@MapperScan` 显式指定） |
+| Mapper 注解 | 建议标注 `@Mapper` |
+| PO 基类 | infrastructure 层定义 PO 基类统一审计字段，PO 继承之（注意：domain 实体按 DDD 包结构约定，独立于 PO，不继承该基类） |
+| 查询方式 | 优先 `LambdaQueryWrapper` 面向对象方法；仅复杂多表关联/方言特性/Wrapper 难以表达时才写 XML SQL |
+| 避免 | `select *`，防止映射不稳定 |
+| Mapper XML | 语句间保持空行提升可读性 |
+| 枚举映射 | 状态/类别等确定性字段在 DAO 层映射为枚举，经框架层统一枚举处理管道映射 DB TINYINT，业务代码禁止直接判断数值 |
+| JSONB 映射 | 用具体 Java 类型 + typeHandler（需验证 MyBatisPlus 对 PG JSONB 适配，可能需自定义 typeHandler） |
+
+使用 MyBatisPlus 标准 `BaseMapper` + `LambdaQueryWrapper`，不依赖第三方增强框架的自研 Wrapper。
+
+## 审计字段自动填充
+
+`creator`/`updater` 由 MyBatisPlus `MetaObjectHandler` 自动填充，业务代码不手动设值：
+
+- PO 审计字段标注：`creator` 用 `@TableField(fill = FieldFill.INSERT)`，`updater` 用 `@TableField(fill = FieldFill.INSERT_UPDATE)`
+- 实现 `MetaObjectHandler`，在 `insertFill`/`updateFill` 中从鉴权上下文取操作人标识注入
+- 鉴权上下文由拦截器从 SecurityContext（JWT 还原的身份）提取操作人标识，请求级作用域
+- `created_at`/`updated_at` 同理用 `MetaObjectHandler` 填充，或依赖 DB `DEFAULT now()` / `ON UPDATE`
+- domain 实体不含审计字段，无 MyBatisPlus 注解（零框架依赖）；自动填充仅作用于 infrastructure 层 PO
+
+## Flyway 迁移
+
+- 脚本命名：`V{version}__{description}.sql`（如 `V1__init_schema.sql`）
+- 脚本位置：`src/main/resources/db/migration/`
+- 表结构变更由 Flyway 版本化管理，迁移脚本即变更记录，不另建 SQL 变更目录
+- test profile 下 Flyway 禁用，测试用 H2（`MODE=PostgreSQL`）