@deepstorm/cli 0.1.0

package/dist/skills/reef-style-backend/fragments/java/api-spec/quick-reference.md

@@ -0,0 +1,148 @@
+# API 规范
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 资源路径 | 英文复数 kebab-case：`/api/v1/user-roles`，不是 `/api/v1/userRoles` 或 `/api/v1/user_role` |
+| 自定义动作 | AIP-136 冒号语法：`@PostMapping("/{id}:publish")` |
+| 查询参数 | `?status=active&page=0&size=20&sort=name,asc` |
+| 统一响应体 | `ApiResponse<T>` / `PageResponse<T>` / `ErrorResponse` |
+| 版本策略 | URL path 前缀 `/api/v1/`；非破坏性变更不升级，破坏性变更 +1 |
+| 错误响应 | AIP-193 兼容 `ErrorResponse`：`{ "code": "USER_001", "message": "...", "detail": {} }` |
+| 分页 | Spring `Pageable` → `PageResponse` |
+| OpenAPI | `@Operation(summary = "...")` + `@ApiResponse` + `@Tag(name = "users")` |
+
+## 核心规范
+
+### 资源命名
+
+- **资源用复数名词**：`/users`、`/orders`、`/line-items`
+- **嵌套资源**：`/apps/{appId}/users/{userId}`
+- **自定义方法用冒号**：`/users/{id}:activate`（AIP-136）
+- **查询参数用 snake_case**：`created_before`、`sort_by`
+
+### 统一响应体
+
+使用泛型包装所有响应：
+
+```java
+// ✅ 单资源响应
+@GetMapping("/{id}")
+public ResponseEntity<ApiResponse<UserResponse>> getUser(@PathVariable Long id) {
+    UserResponse user = userService.getUser(id);
+    return ResponseEntity.ok(ApiResponse.success(user));
+}
+
+// ✅ 分页响应
+@GetMapping
+public ResponseEntity<PageResponse<UserResponse>> listUsers(Pageable pageable) {
+    Page<UserResponse> page = userService.listUsers(pageable);
+    return ResponseEntity.ok(PageResponse.from(page));
+}
+
+// ❌ 坏：直接返回实体或裸 List
+@GetMapping
+public List<UserResponse> listUsers() { ... }  // ← 缺少分页和包装
+```
+
+响应体结构：
+
+```java
+// ApiResponse — 单资源或操作响应
+public record ApiResponse<T>(boolean success, T data, String message) {
+    public static <T> ApiResponse<T> success(T data) {
+        return new ApiResponse<>(true, data, null);
+    }
+    public static <T> ApiResponse<T> success(String message) {
+        return new ApiResponse<>(true, null, message);
+    }
+}
+
+// PageResponse — 分页响应
+public record PageResponse<T>(
+    List<T> content,
+    int page,
+    int size,
+    long totalElements,
+    int totalPages
+) {
+    public static <T> PageResponse<T> from(Page<T> page) {
+        return new PageResponse<>(
+            page.getContent(),
+            page.getNumber(),
+            page.getSize(),
+            page.getTotalElements(),
+            page.getTotalPages()
+        );
+    }
+}
+
+// ErrorResponse — 错误响应
+public record ErrorResponse(String code, String message, Map<String, Object> detail) {
+    public static ErrorResponse of(String code, String message) {
+        return new ErrorResponse(code, message, Map.of());
+    }
+}
+```
+
+### OpenAPI 文档
+
+```java
+@RestController
+@RequestMapping("/api/v1/users")
+@Tag(name = "users", description = "用户管理")
+public class UserController {
+
+    @Operation(summary = "获取用户列表")
+    @ApiResponse(responseCode = "200", description = "成功返回用户分页列表")
+    @GetMapping
+    public ResponseEntity<PageResponse<UserResponse>> listUsers(Pageable pageable) {
+        // ...
+    }
+
+    @Operation(summary = "创建用户")
+    @ApiResponse(responseCode = "201", description = "创建成功")
+    @PostMapping
+    public ResponseEntity<ApiResponse<UserResponse>> createUser(
+        @Valid @RequestBody CreateUserRequest request
+    ) {
+        // ...
+    }
+}
+```
+
+**规范：**
+- 每个 Controller 类加 `@Tag(name = "...", description = "...")`
+- 每个接口方法加 `@Operation(summary = "...")`
+- 非 200 响应（400/403/404）加 `@ApiResponse(responseCode = "4XX", description = "...")`
+- 避免在 `application.yml` 中暴露 OpenAPI 端点到生产环境
+
+### 版本策略
+
+- **非破坏性变更**（新增字段、新增可选参数）：停留在当前版本
+- **破坏性变更**（重命名字段、删除字段、改变类型）：创建新版本 `/api/v2/...`
+- **废弃端点**：保留旧版本，加 `@Deprecated` 注解，同时在类或方法 Javadoc 中注明废弃原因和迁移目标版本
+- **过渡期**：旧版本至少维护 2 个发布周期
+
+### 分页约定
+
+- 列表接口**必须**支持分页
+- 入参：Spring 自动解析 `?page=0&size=20&sort=name,asc`
+- `page` 从 0 开始
+- `size` 默认 20，最大值 200
+- 响应：`PageResponse<T>` 包含 `content`、`page`、`size`、`totalElements`、`totalPages`
+
+### 错误码命名
+
+```
+{MODULE}_{NNN}
+
+MODULE: 2-4 个大写字母标识模块
+示例：USER_001 / ORDER_002 / AUTH_003 / APP_004
+```
+
+- `_001`-`_099`：输入验证错误
+- `_100`-`_199`：资源状态错误（不存在、已存在、冲突）
+- `_200`-`_299`：权限错误
+- `_300`-`_399`：系统内部错误

package/dist/skills/reef-style-backend/fragments/java/db-migration/liquibase/examples/database-migration.md

@@ -0,0 +1,131 @@
+# 数据库迁移（Liquibase）
+
+## ChangeSet 格式
+
+- ID：`YYYYMMDDHHMM-NNN`（如 `202405231200-001`）
+- 添加新变更：在 `changelogs/` 目录创建新 XML 文件，无需修改 master changelog（`<includeAll>` 自动扫描）
+- 文件按时间命名排序以控制执行顺序
+
+## 属性替换
+
+主 changelog 定义了数据库类型变量以支持多数据库（H2 开发/测试，MySQL/PG/MSSQL 生产）：
+
+| 变量 | 用途 |
+|------|------|
+| `${boolean.type}` | 布尔类型 |
+| `${string.type}(255)` | 字符串 VARCHAR/NVARCHAR |
+| `${date.time.type}` | 日期时间 TIMESTAMP/DATETIME/DATETIME2 |
+| `${clob.type}` | 大文本 CLOB/LONGTEXT/TEXT/NVARCHAR(MAX) |
+| `${enum.ordinal.type}` | 枚举序号类型 |
+
+枚举类型在不同数据库中处理方式不同：H2/MySQL 用 `ENUM(...)` 原生枚举，PG/MSSQL 用 `${string.type}(255)`。枚举属性命名规则：`${<module>.<enum-name>.type}`。
+
+## 完整示例
+
+### 建表（序列 + 表 + 外键，省略 XML namespace）
+
+```xml
+<!-- 序列（H2/PG/MSSQL 用序列，MySQL 用序列表模拟） -->
+<changeSet author="lgong" id="202604062320-004" dbms="h2,postgresql,mssql">
+  <createSequence sequenceName="my_entity_seq" startValue="1" incrementBy="50" />
+</changeSet>
+<changeSet author="lgong" id="202604062320-004" dbms="mysql">
+  <createTable tableName="my_entity_seq">
+    <column name="next_val" type="BIGINT" />
+  </createTable>
+  <insert tableName="my_entity_seq"><column name="next_val" value="1" /></insert>
+</changeSet>
+
+<changeSet author="developer" id="202604062320-005">
+  <createTable tableName="my_entity">
+    <column name="id" type="BIGINT"><constraints nullable="false" primaryKey="true" primaryKeyName="myEntityPK" /></column>
+    <column name="created_at" type="${date.time.type}" />
+    <column name="name" type="${string.type}(255)"><constraints nullable="false" /></column>
+    <column name="enabled" type="${boolean.type}"><constraints nullable="false" /></column>
+    <column name="dtype" type="${string.type}(31)"><constraints nullable="false" /></column>
+  </createTable>
+</changeSet>
+
+<changeSet author="developer" id="202604062320-006">
+  <addColumn tableName="my_entity"><column name="app_id" type="BIGINT" /></addColumn>
+</changeSet>
+<changeSet author="developer" id="202604062320-007">
+  <addForeignKeyConstraint constraintName="FKmyentity_app"
+    baseTableName="my_entity" baseColumnNames="app_id"
+    referencedTableName="application" referencedColumnNames="id" />
+</changeSet>
+```
+
+### 新增字段 / 修改字段类型
+
+```xml
+<changeSet author="developer" id="202605111000-01">
+  <addColumn tableName="my_entity"><column name="new_field" type="${string.type}(255)" /></addColumn>
+</changeSet>
+<!-- 可空→非空需先填充数据 -->
+<changeSet author="developer" id="202605111000-02">
+  <addNotNullConstraint tableName="my_entity" columnName="new_field"
+    columnDataType="${string.type}(255)" defaultNullValue="默认值" />
+</changeSet>
+<changeSet author="developer" id="202604281406">
+  <modifyDataType tableName="my_entity" columnName="choices" newDataType="${string.list.type}" />
+</changeSet>
+```
+
+### 索引 / 唯一约束 / 外键
+
+```xml
+<changeSet author="developer" id="202605081601">
+  <createIndex indexName="IDXm64b01r9rj9aco9it9puvg9tb" tableName="my_entity">
+    <column name="app_id" />
+  </createIndex>
+</changeSet>
+
+<changeSet author="developer" id="202604062320-028" dbms="h2,mysql,postgresql">
+  <addUniqueConstraint constraintName="UC_MYENTITYSLUG_COL"
+    tableName="my_entity" columnNames="slug" />
+</changeSet>
+
+<changeSet author="developer" id="202604211125-10">
+  <addForeignKeyConstraint constraintName="FKhoumjjymjhbu0oiwh6ynyio6u"
+    baseTableName="my_entity" baseColumnNames="app_id"
+    referencedTableName="application" referencedColumnNames="id" />
+</changeSet>
+```
+
+### 删除操作 / 自定义 SQL
+
+```xml
+<changeSet author="developer" id="202604211125-03">
+  <dropColumn tableName="my_entity" columnName="old_column" />
+</changeSet>
+<changeSet author="developer" id="202604211125-02">
+  <dropUniqueConstraint constraintName="UC_APPLICATIONNAVIGATION_MENU_ID_COL" tableName="application" />
+</changeSet>
+<changeSet author="developer" id="202605081101">
+  <dropForeignKeyConstraint constraintName="FKjr9mly7obkthhxdr0hk29r88t" baseTableName="my_entity" />
+</changeSet>
+<changeSet author="developer" id="202605210012-03">
+  <sql>UPDATE form_revision SET revisions_order = (SELECT COUNT(*) FROM (SELECT id, form_id FROM form_revision) AS fr2 WHERE fr2.form_id = form_revision.form_id AND fr2.id &lt; form_revision.id)</sql>
+</changeSet>
+```
+
+## SQL Server 特殊处理
+
+可空列的唯一约束使用过滤索引：
+
+```xml
+<changeSet author="developer" id="..." dbms="mssql">
+  <createIndex indexName="UC_TABLENAME_COL" tableName="table" unique="true">
+    <column name="column_name" />
+  </createIndex>
+  <modifySql><append value=" WHERE column_name IS NOT NULL" /></modifySql>
+</changeSet>
+```
+
+## 最佳实践
+
+- 新增字段必须设为可空（默认），若需非空则先填充数据再 `addNotNullConstraint`
+- 序列命名 `<table_name>_seq`，`startValue=1, incrementBy=50`（匹配 Hibernate 默认序列优化）
+- 同一 table 的多次 `addColumn` 合并到一个 changeset
+- 先 `dropForeignKeyConstraint` 再 `createIndex` 是常见模式

package/dist/skills/reef-style-backend/fragments/java/db-migration/liquibase/quick-reference.md

@@ -0,0 +1,103 @@
+# Liquibase 数据库迁移规范
+
+## 概述
+
+使用 Liquibase 进行数据库版本管理，所有 Schema 变更通过 changelog 文件管理。
+
+## 文件结构
+
+```
+src/main/resources/db/changelog/
+  db.changelog-master.yaml     // 主入口文件
+  v1.0.0/
+    v1.0.0-001-create-users.yaml
+    v1.0.0-002-create-orders.yaml
+    v1.0.0-003-add-email-index.yaml
+  v1.1.0/
+    v1.1.0-001-add-profile-table.yaml
+```
+
+## 主入口文件
+
+```yaml
+# db.changelog-master.yaml
+databaseChangeLog:
+  - include:
+      file: db/changelog/v1.0.0/v1.0.0-001-create-users.yaml
+  - include:
+      file: db/changelog/v1.0.0/v1.0.0-002-create-orders.yaml
+  - include:
+      file: db/changelog/v1.1.0/v1.1.0-001-add-profile-table.yaml
+```
+
+## Changeset 示例
+
+```yaml
+# v1.0.0-001-create-users.yaml
+databaseChangeLog:
+  - changeSet:
+      id: v1.0.0-001
+      author: developer
+      changes:
+        - createTable:
+            tableName: users
+            columns:
+              - column:
+                  name: id
+                  type: BIGINT
+                  autoIncrement: true
+                  constraints:
+                    primaryKey: true
+                    nullable: false
+              - column:
+                  name: name
+                  type: VARCHAR(100)
+                  constraints:
+                    nullable: false
+              - column:
+                  name: email
+                  type: VARCHAR(255)
+                  constraints:
+                    unique: true
+                    nullable: false
+              - column:
+                  name: created_at
+                  type: TIMESTAMP
+                  defaultValueComputed: CURRENT_TIMESTAMP
+```
+
+## changeset 命名
+
+```
+格式: {version}-{seq}-{description}
+示例: v1.0.0-003-add-email-index
+```
+
+## 回滚
+
+```yaml
+# 每个 changeset 应可回滚
+- changeSet:
+    id: v1.2.0-001
+    author: developer
+    changes:
+      - addColumn:
+          tableName: users
+          columns:
+            - column:
+                name: phone
+                type: VARCHAR(20)
+    rollback:
+      - dropColumn:
+          tableName: users
+          columnName: phone
+```
+
+## 最佳实践
+
+- ✅ 每个 changeset 有唯一 ID
+- ✅ 每个 changeset 只做单一变更（创建表、加索引、加字段）
+- ✅ 变更不可修改已发布的 changeset（追加新 changeset）
+- ✅ 生产环境使用 `context` 标签控制不同环境数据
+- ❌ 不在 changeset 中使用存储过程
+- ❌ 不修改已合并到主干的 changeset

package/dist/skills/reef-style-backend/fragments/java/dependency-management/quick-reference.md

@@ -0,0 +1,119 @@
+# 依赖管理规范
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 声明依赖 | 全部在 `gradle/libs.versions.toml` 的 `[libraries]` 中声明 |
+| 版本声明 | 全部在 `gradle/libs.versions.toml` 的 `[versions]` 中声明 |
+| 引入新依赖 | 先查 version catalog 是否已有，无则按模块 + 版本号格式添加 |
+| 临时排除 | 在 catalog 中使用 `exclude` 而非 `build.gradle.kts` 中排除 |
+| 版本升级 | 同步升级相关依赖（如 Liquibase + Spring Boot 一起升级） |
+| CVE 检查 | 配合 Dependabot / Renovate + Gradle Versions Plugin |
+| 许可限制 | 禁止引入 AGPL / 需商业许可的依赖 |
+
+## 核心规范
+
+### Gradle Version Catalog 结构
+
+```toml
+# gradle/libs.versions.toml
+[versions]
+spring-boot = "3.5.0"
+spring-dependency-management = "1.1.7"
+mapstruct = "1.6.3"
+liquibase = "4.31.0"
+testcontainers = "1.20.6"
+
+[libraries]
+spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
+spring-boot-starter-data-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa" }
+mapstruct = { module = "org.mapstruct:mapstruct", version.ref = "mapstruct" }
+mapstruct-processor = { module = "org.mapstruct:mapstruct-processor", version.ref = "mapstruct" }
+
+[bundles]
+spring-web = ["spring-boot-starter-web", "spring-boot-starter-validation"]
+
+[plugins]
+spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }
+```
+
+**规范：**
+- 所有依赖的**版本号**必须声明在 `[versions]` 中，不得在 `[libraries]` 中使用 `version = "1.0.0"` 字面量
+- `[libraries]` 中使用 `version.ref` 引用版本
+- 同一生态的依赖使用同一个版本变量（如所有 Spring Boot starter 共享 `spring-boot` 版本）
+- 多个 artifact 共享版本的依赖组（如 mapstruct + mapstruct-processor）用同一 `version.ref`
+- 关联依赖使用 `[bundles]` 分组
+
+### 禁止硬编码版本号
+
+```kotlin
+// ✅ 好：build.gradle.kts
+dependencies {
+    implementation(libs.spring.boot.starter.web)
+    implementation(libs.mapstruct)
+    annotationProcessor(libs.mapstruct.processor)
+}
+
+// ❌ 坏：build.gradle.kts — 硬编码版本号
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-web:3.5.0")  // ← 硬编码
+    implementation("org.mapstruct:mapstruct:1.6.3")                           // ← 硬编码
+}
+```
+
+### 版本一致性规则
+
+升级一个依赖时，检查同一生态链的其他依赖是否需要同步升级：
+
+| 升级场景 | 需同步升级的关联依赖 |
+|---------|-------------------|
+| Spring Boot 升级 | Spring Cloud、spring-dependency-management、相关 starter |
+| Liquibase 升级 | 验证与 Spring Boot 版本兼容性 |
+| MapStruct 升级 | mapstruct-processor 必须保持同一版本 |
+| Hibernate 升级 | Spring Boot 提供的 Hibernate 版本（随 Boot 版本） |
+| Testcontainers 升级 | 验证与 JUnit 5 兼容性 |
+
+### Gradle Versions Plugin
+
+```kotlin
+// build.gradle.kts
+plugins {
+    id("com.github.ben-manes.versions") version "0.52.0"
+}
+```
+
+```bash
+# 检查可用升级
+./gradlew dependencyUpdates -Drevision=release
+
+# 输出示例：
+# The following dependencies have newer versions:
+#   com.google.guava:guava [32.1.3 -> 33.4.0]
+```
+
+**规范：**
+- 每个 Major 版本升级前先在本地验证兼容性
+- 升级依赖必须作为独立 PR/commit，附 changelog 摘要
+- Minor/Patch 升级可随功能 PR 一起提交
+
+### 已知 CVE 管理
+
+```bash
+# 配合 Gradle Versions Plugin 使用 OWASP Dependency Check（可选）
+./gradlew dependencyCheckAnalyze
+```
+
+**规范：**
+- Dependabot 或 Renovate 的 CVE PR 在 7 天内处理
+- 紧急 CVE（CVSS >= 7.0）：1 天内升级并验证
+- 无法立即升级时，记录在安全看板中，加 `@SuppressWarnings("CVE-XXXX")` 并附缓解说明
+
+### 禁止使用的依赖
+
+| 依赖 | 禁止原因 | 替代方案 |
+|------|---------|---------|
+| Apache Commons Lang 2 | 有已知 CVE，已被 lang3 取代 | `org.apache.commons:commons-lang3` |
+| Log4j 1.x | EOL，有已知 CVE | Spring Boot 内置 Logback 或 Log4j 2 |
+| Guava 旧版 < 30.0 | 已知 CVE | 最低 32.x |
+| Joda-Time | 已被 java.time 取代 | `java.time.*` / `ThreeTen-Extra`（如需要） |

package/dist/skills/reef-style-backend/fragments/java/exception-handling/examples/error-code-enum.md

@@ -0,0 +1,101 @@
+# 错误码枚举示例
+
+## 完整 ErrorCode 枚举
+
+```java
+package com.example.app.common;
+
+/**
+ * 全局错误码枚举。
+ *
+ * 编码规则：{MODULE}_{NNN}
+ *   MODULE = 2-4 个大写字母
+ *   NNN   = 三位数字
+ *     001-099 输入验证
+ *     100-199 资源状态
+ *     200-299 权限
+ *     300-399 系统内部
+ */
+public enum ErrorCode {
+
+    // ── User ──────────────────────────────────────────────
+    USER_001("USER_001", "用户名已存在"),
+    USER_002("USER_002", "邮箱格式无效"),
+    USER_003("USER_003", "手机号格式无效"),
+    USER_004("USER_004", "密码不符合安全策略"),
+
+    USER_100("USER_100", "用户不存在"),
+    USER_101("USER_101", "用户已禁用"),
+    USER_102("USER_102", "用户邮箱未验证"),
+    USER_103("USER_103", "用户已删除"),
+
+    USER_200("USER_200", "无权操作该用户"),
+    USER_201("USER_201", "不能操作自身账号"),
+
+    // ── Order / App ──────────────────────────────────────
+    APP_001("APP_001", "应用名称为空"),
+    APP_002("APP_002", "应用名称超长"),
+    APP_100("APP_100", "应用不存在"),
+    APP_101("APP_101", "应用已下架"),
+    APP_200("APP_200", "无权操作该应用"),
+
+    // ── Auth ──────────────────────────────────────────────
+    AUTH_001("AUTH_001", "Token 已过期"),
+    AUTH_002("AUTH_002", "Token 无效"),
+    AUTH_003("AUTH_003", "Token 签名验证失败"),
+    AUTH_004("AUTH_004", "Refresh Token 无效"),
+    AUTH_201("AUTH_201", "无权限访问"),
+    AUTH_202("AUTH_202", "角色权限不足"),
+    AUTH_203("AUTH_203", "需要 Root Tenant 权限"),
+
+    // ── Validating ────────────────────────────────────────
+    VALIDATION_001("VALIDATION_001", "参数校验失败"),
+    VALIDATION_002("VALIDATION_002", "请求体格式无效"),
+
+    // ── Generic ───────────────────────────────────────────
+    GENERIC_001("GENERIC_001", "系统内部错误"),
+    GENERIC_002("GENERIC_002", "服务暂时不可用"),
+    GENERIC_404("GENERIC_404", "接口不存在"),
+    GENERIC_429("GENERIC_429", "请求频率过高");
+
+    private final String code;
+    private final String defaultMessage;
+
+    ErrorCode(String code, String defaultMessage) {
+        this.code = code;
+        this.defaultMessage = defaultMessage;
+    }
+
+    public String code() { return code; }
+    public String defaultMessage() { return defaultMessage; }
+
+    @Override
+    public String toString() { return code + ": " + defaultMessage; }
+}
+```
+
+## 异常 + 错误码对照表
+
+| 异常类 | HTTP | 错误码示例 | 典型场景 |
+|--------|------|-----------|---------|
+| `ResourceNotFoundException` | 404 | `USER_100` | 用户不存在 |
+| `AlreadyExistsException` | 409 | `USER_001` | 用户名重复 |
+| `InvalidArgumentException` | 400 | `ORDER_001` | 金额无效 |
+| `PermissionDeniedException` | 403 | `AUTH_201` | 无权操作 |
+| `FailedPreconditionException` | 400 | `ORDER_101` | 订单状态不允许 |
+
+## 映射逻辑
+
+```java
+// 推荐：在子类构造时注入 ErrorCode，GlobalExceptionHandler 从异常中读取
+public class ResourceNotFoundException extends BusinessException {
+    public ResourceNotFoundException(ErrorCode errorCode, Object... args) {
+        super(errorCode.code(), HttpStatus.NOT_FOUND,
+              String.format(errorCode.defaultMessage(), args));
+    }
+}
+
+// Service 使用
+throw new ResourceNotFoundException(ErrorCode.USER_100);
+throw new ResourceNotFoundException(ErrorCode.USER_100, userId);
+```