@llryiop/avatar-boot-cli 1.0.0

package/templates/.claude/rules/version.md

@@ -0,0 +1,467 @@
+# 依赖版本使用规则
+
+> 本规则适用于所有上游服务
+>
+> **强制执行级别**: 🔴 必须遵守 | 🟡 强烈建议 | 🟢 推荐
+
+---
+
+## 零、Avatar Boot 组件使用规则（架构基础）
+
+### 🔴 核心原则：禁止直接引用 Spring Boot 原生组件
+
+**强制规则：**
+1. ❌ **禁止**直接引用 Spring Boot、Spring Cloud 原生 starter
+2. ✅ **必须**使用 Avatar Boot 封装的 starter 组件
+3. ✅ **必须**配置 iFlytek Maven 仓库
+
+### 🔴 可用的 Avatar Boot 组件清单
+
+项目中**必须且只能**使用以下 Avatar Boot 组件：
+
+| 组件名称 | 用途 | 说明 |
+|---------|------|------|
+| `avatar-boot-dependency` | 版本管理 BOM | 统一管理所有依赖版本 |
+| `avatar-boot-parent` | 父 POM | 提供构建配置和插件管理 |
+| `avatar-boot-core` | 核心功能 | 提供基础工具类和通用功能 |
+| `avatar-boot-starter-web` | Web 服务 | 替代 `spring-boot-starter-web` |
+| `avatar-boot-starter-nacos` | 服务注册与配置 | Nacos 集成 |
+| `avatar-boot-starter-redis` | Redis 缓存 | 替代 `spring-boot-starter-data-redis` |
+| `avatar-boot-starter-mysql` | MySQL 数据库 | 替代 `spring-boot-starter-data-jpa` |
+| `avatar-boot-starter-kafka` | Kafka 消息队列 | 替代 `spring-boot-starter-kafka` |
+| `avatar-boot-starter-oss` | 对象存储 | OSS 文件存储集成 |
+| `avatar-boot-starter-feign` | HTTP 客户端 | 替代 `spring-cloud-starter-openfeign` |
+| `avatar-boot-ai` | AI 能力 | Spring AI 集成 |
+| `avatar-boot-starter-rocketmq` | RocketMQ 消息队列 | RocketMQ 集成 |
+
+### 🔴 必须配置的 Maven 仓库
+
+在项目根 `pom.xml` 或 `settings.xml` 中**必须**配置以下仓库：
+
+```xml
+<repositories>
+    <repository>
+        <id>mvn-repo</id>
+        <name>iFlytek Maven Repository</name>
+        <url>https://artifacts.iflytek.com/artifactory/mvn-repo/</url>
+        <layout>default</layout>
+    </repository>
+</repositories>
+
+<pluginRepositories>
+    <pluginRepository>
+        <id>mvn-repo</id>
+        <name>iFlytek Maven Repository</name>
+        <url>https://artifacts.iflytek.com/artifactory/mvn-repo/</url>
+    </pluginRepository>
+</pluginRepositories>
+```
+
+### ❌ 禁止的依赖声明
+
+```xml
+<!-- ❌ 错误：直接引用 Spring Boot 原生 starter -->
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-web</artifactId>
+</dependency>
+
+<!-- ❌ 错误：直接引用 Spring Cloud starter -->
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-openfeign</artifactId>
+</dependency>
+
+<!-- ❌ 错误：直接引用 Spring Data Redis -->
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-data-redis</artifactId>
+</dependency>
+```
+
+### ✅ 正确的依赖声明
+
+```xml
+<!-- ✅ 正确：使用 Avatar Boot 封装的 starter -->
+<dependency>
+    <groupId>com.iflytek.springboot</groupId>
+    <artifactId>avatar-boot-starter-web</artifactId>
+</dependency>
+
+<dependency>
+    <groupId>com.iflytek.springboot</groupId>
+    <artifactId>avatar-boot-starter-feign</artifactId>
+</dependency>
+
+<dependency>
+    <groupId>com.iflytek.springboot</groupId>
+    <artifactId>avatar-boot-starter-redis</artifactId>
+</dependency>
+```
+
+### 🟡 架构层次说明
+
+Avatar Boot 采用三层架构：
+
+```
+avatar-boot (聚合 POM)
+├── avatar-boot-dependency (BOM - 版本管理)
+│   └── 定义所有依赖的版本号
+├── avatar-boot-parent (父 POM - 构建配置)
+│   └── 导入 avatar-boot-dependency BOM
+│   └── 定义构建插件和编译配置
+└── avatar-boot-starter-* (功能模块)
+    └── 继承 avatar-boot (聚合 POM)
+    └── 封装 Spring Boot 原生功能
+    └── 添加企业级增强功能
+```
+
+**关键规则：**
+- 业务服务模块**必须**继承 `avatar-boot` 或 `avatar-boot-parent`
+- 业务服务模块**禁止**直接继承 `spring-boot-starter-parent`
+- 所有依赖版本**必须**由 `avatar-boot-dependency` 统一管理
+
+### 🔴 违规检查命令
+
+```bash
+# 检查是否直接引用了 Spring Boot 原生 starter
+find . -name "pom.xml" -exec grep -l "spring-boot-starter-web\|spring-boot-starter-data-redis\|spring-cloud-starter-openfeign" {} \;
+
+# 检查是否配置了 iFlytek 仓库
+grep -r "artifacts.iflytek.com" pom.xml settings.xml
+```
+
+---
+
+## 一、基础环境要求
+
+### 🔴 必须使用的版本
+
+| 组件 | 版本 | 原因 |
+|------|------|------|
+| Java | 21 | Spring Boot 3.5.3 要求 Java 17+，使用 Java 21 获得最新特性和性能优化 |
+| Maven | 3.8.6+ | 支持 Java 21 和现代 Maven 特性 |
+| Maven Compiler Plugin | 3.13.0 | 支持 Java 21 编译 |
+
+### ❌ 禁止使用的版本
+
+- Java 8, 11, 17（Spring Boot 3.x 虽然支持 17，但项目统一使用 21）
+- Maven 3.6.x 及以下（不完全支持 Java 21）
+
+---
+
+## 二、包命名空间规则
+
+### 🔴 必须使用 Jakarta 命名空间
+
+Spring Boot 3.x 已全面迁移到 Jakarta EE 9+，必须使用 `jakarta.*` 包：
+
+```java
+// ✅ 正确
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.validation.constraints.NotNull;
+import jakarta.persistence.Entity;
+
+// ❌ 错误
+import javax.servlet.http.HttpServletRequest;
+import javax.validation.constraints.NotNull;
+import javax.persistence.Entity;
+```
+
+### 🟡 迁移检查清单
+
+- [ ] `javax.servlet.*` → `jakarta.servlet.*`
+- [ ] `javax.validation.*` → `jakarta.validation.*`
+- [ ] `javax.persistence.*` → `jakarta.persistence.*`
+- [ ] `javax.annotation.*` → `jakarta.annotation.*`
+
+---
+
+## 三、依赖声明规则
+
+### 🔴 版本管理规则
+
+1. **在 avatar-boot-dependency 中定义版本**
+   ```xml
+   <!-- ✅ 正确：在 BOM 中定义 -->
+   <properties>
+       <hutool.version>5.8.34</hutool.version>
+   </properties>
+
+   <dependencyManagement>
+       <dependencies>
+           <dependency>
+               <groupId>cn.hutool</groupId>
+               <artifactId>hutool-all</artifactId>
+               <version>${hutool.version}</version>
+           </dependency>
+       </dependencies>
+   </dependencyManagement>
+   ```
+
+2. **在子模块中不指定版本**
+   ```xml
+   <!-- ✅ 正确：不指定版本 -->
+   <dependency>
+       <groupId>cn.hutool</groupId>
+       <artifactId>hutool-all</artifactId>
+   </dependency>
+
+   <!-- ❌ 错误：不应指定版本 -->
+   <dependency>
+       <groupId>cn.hutool</groupId>
+       <artifactId>hutool-all</artifactId>
+       <version>5.8.34</version> <!-- 删除此行 -->
+   </dependency>
+   ```
+
+3. **例外情况：optional 依赖**
+   ```xml
+   <!-- ✅ 允许：编译时依赖可以标记为 optional -->
+   <dependency>
+       <groupId>org.projectlombok</groupId>
+       <artifactId>lombok</artifactId>
+       <optional>true</optional>
+   </dependency>
+   ```
+
+---
+
+## 四、测试框架规则
+
+### 🔴 必须使用的测试框架
+
+| 组件 | 版本 | 说明 |
+|------|------|------|
+| JUnit Jupiter | 5.x | Spring Boot BOM 管理 |
+| Mockito | 5.x | Spring Boot BOM 管理 |
+| AssertJ | 3.x | Spring Boot BOM 管理 |
+| Spring Boot Starter Test | 3.5.3 | 包含上述所有框架 |
+
+### ❌ 禁止使用
+
+- JUnit 4（使用 JUnit 5）
+- TestNG（项目统一使用 JUnit 5）
+- Hamcrest（使用 AssertJ）
+
+### ✅ 推荐的测试注解
+
+```java
+// ✅ JUnit 5 注解
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+
+// ❌ JUnit 4 注解（不要使用）
+import org.junit.Test;
+import org.junit.Before;
+```
+
+---
+
+## 五、构建插件规则
+
+### 🔴 必须使用的插件版本
+
+| 插件 | 版本 | 说明 |
+|------|------|------|
+| maven-compiler-plugin | 3.13.0 | 支持 Java 21 |
+| maven-resources-plugin | 3.3.1 | 资源处理 |
+| spring-boot-maven-plugin | 3.5.3 | Spring Boot 打包 |
+
+### 🟡 推荐配置
+
+```xml
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.13.0</version>
+            <configuration>
+                <source>21</source>
+                <target>21</target>
+                <encoding>UTF-8</encoding>
+                <parameters>true</parameters> <!-- 保留参数名 -->
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+```
+
+---
+
+## 六、版本升级流程
+
+### 🔴 强制流程
+
+1. **只在 avatar-boot-dependency 中修改版本**
+   ```bash
+   # 修改 avatar-boot-dependency/pom.xml
+   vim avatar-boot-dependency/pom.xml
+   ```
+
+2. **验证构建**
+   ```bash
+   mvn clean install -DskipTests
+   ```
+
+3. **运行测试**
+   ```bash
+   mvn clean test
+   ```
+
+4. **检查依赖树**
+   ```bash
+   mvn dependency:tree > dependency-tree.txt
+   ```
+
+5. **提交变更**
+   ```bash
+   git add avatar-boot-dependency/pom.xml
+   git commit -m "chore: upgrade xxx from x.x.x to y.y.y"
+   ```
+
+### ❌ 禁止的操作
+
+- ❌ 在子模块中直接修改版本
+- ❌ 跳过测试直接升级生产环境
+- ❌ 同时升级多个主版本依赖
+
+---
+
+## 十四、安全漏洞检查
+
+### 🔴 必须定期检查
+
+使用以下命令检查已知漏洞：
+
+```bash
+# Maven 依赖检查
+mvn org.owasp:dependency-check-maven:check
+
+# 或使用 Snyk
+snyk test
+```
+
+### 🟡 高危漏洞立即修复
+
+发现以下漏洞必须立即修复：
+
+- CVE 评分 >= 7.0
+- 反序列化漏洞
+- SQL 注入漏洞
+- 远程代码执行漏洞
+
+---
+
+## 十五、违规处理
+
+### 🔴 自动检查
+
+在 CI/CD 流程中添加以下检查：
+
+```bash
+# 检查是否使用禁止的依赖
+mvn dependency:tree | grep -E "commons-collections:commons-collections:3|javax.validation:validation-api|javax.servlet:javax.servlet-api"
+
+# 检查是否有显式版本声明（除了 avatar-boot-dependency）
+find . -name "pom.xml" -not -path "*/avatar-boot-dependency/*" -exec grep -l "<version>" {} \;
+```
+
+### 🟡 人工审查
+
+每次 PR 必须检查：
+- [ ] 是否引入了禁止的依赖
+- [ ] 是否在子模块中指定了版本
+- [ ] 是否使用了正确的 GroupId/ArtifactId
+- [ ] 是否使用了 jakarta 命名空间
+
+---
+
+## 七、快速参考
+
+### ✅ 正确示例
+
+```xml
+<project>
+    <parent>
+        <groupId>com.iflytek.springboot</groupId>
+        <artifactId>avatar-boot-parent</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+
+    <dependencies>
+        <!-- ✅ 不指定版本 -->
+        <dependency>
+            <groupId>cn.hutool</groupId>
+            <artifactId>hutool-all</artifactId>
+        </dependency>
+
+        <!-- ✅ 使用正确的坐标 -->
+        <dependency>
+            <groupId>com.mysql</groupId>
+            <artifactId>mysql-connector-j</artifactId>
+        </dependency>
+
+        <!-- ✅ 使用 Jakarta 命名空间 -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-validation</artifactId>
+        </dependency>
+    </dependencies>
+</project>
+```
+
+### ❌ 错误示例
+
+```xml
+<project>
+    <dependencies>
+        <!-- ❌ 指定了版本 -->
+        <dependency>
+            <groupId>cn.hutool</groupId>
+            <artifactId>hutool-all</artifactId>
+            <version>5.8.34</version>
+        </dependency>
+
+        <!-- ❌ 使用旧坐标 -->
+        <dependency>
+            <groupId>mysql</groupId>
+            <artifactId>mysql-connector-java</artifactId>
+        </dependency>
+
+        <!-- ❌ 使用禁止的依赖 -->
+        <dependency>
+            <groupId>commons-collections</groupId>
+            <artifactId>commons-collections</artifactId>
+            <version>3.2.2</version>
+        </dependency>
+    </dependencies>
+</project>
+```
+
+---
+
+## 附录：版本速查表
+
+| 类别 | 组件 | 版本 | 管理方式 |
+|------|------|------|---------|
+| 基础 | Java | 21 | 环境要求 |
+| 基础 | Maven | 3.8.6+ | 环境要求 |
+| Spring | Spring Boot | 3.5.3 | BOM 显式声明 |
+| Spring | Spring Cloud | 2025.0.0 | BOM 显式声明 |
+| Spring | Spring Cloud Alibaba | 2023.0.3.2 | BOM 显式声明 |
+| Spring | Spring AI | 1.1.2 | BOM 显式声明 |
+| 数据库 | MySQL Connector | 9.1.0 | BOM 管理 |
+| 数据库 | Druid | 1.2.24 | BOM 管理 |
+| 数据库 | MyBatis Plus | 3.5.15 | BOM 管理 |
+| 缓存 | Redisson | 3.40.2 | BOM 管理 |
+| 缓存 | JetCache | 2.7.8 | BOM 管理 |
+| 工具 | Lombok | 1.18.36 | BOM 管理 |
+| 工具 | Hutool | 5.8.34 | BOM 管理 |
+| 工具 | Fastjson2 | 2.0.54 | BOM 管理 |
+| 工具 | Commons Lang3 | 3.17.0 | BOM 管理 |
+| 工具 | Commons Collections4 | 4.4 | BOM 管理 |
+| 安全 | BouncyCastle | 1.79 | BOM 管理 |
+| 日志 | Logstash Logback | 8.0 | BOM 管理 |

package/templates/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(git ls-tree:*)",
+      "WebSearch",
+      "Bash(grep:*)",
+      "Bash(jar tf:*)",
+      "Bash(mvn clean:*)",
+      "Bash(jar xf:*)",
+      "Bash(mvn spring-boot:run:*)",
+      "Bash(netstat:*)",
+      "Bash(taskkill:*)",
+      "Bash(java:*)",
+      "Bash(curl:*)"
+    ]
+  }
+}