@llryiop/avatar-boot-cli 1.0.0

package/templates/.claude/skills/troubleshooting/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: troubleshooting
+description: |
+  异常排查与故障定位技能。当用户提到以下关键词时触发：
+  异常排查, error analysis, 报错, 故障定位, debug, 排错,
+  Exception, 启动失败, 运行异常, 问题诊断
+
+  本技能提供 Avatar Boot 框架下常见异常的分类识别、根因分析流程、
+  常见问题修复方案和排查最佳实践。
+---
+
+# 异常排查与故障定位技能
+
+> **与 incident-analysis 的区别**：本 Skill 用于**正在发生的问题的实时排查和修复**。如需**已解决故障的事后复盘和报告**（时间线重建、影响评估、5-Why 分析、预防措施），请使用 [incident-analysis](../incident-analysis/) Skill。
+
+## 适用场景
+
+- 应用启动失败排查
+- 运行时异常诊断
+- 配置错误识别
+- 网络/连接问题排查
+- 数据层异常分析
+
+## 错误分类体系
+
+### 1. 编译期错误
+
+| 错误类型                    | 常见原因                          | 排查方向                     |
+|---------------------------|----------------------------------|------------------------------|
+| 符号找不到                  | 依赖缺失、包名错误                | 检查 pom.xml 依赖和 import   |
+| 类型不兼容                  | 泛型擦除、版本升级 API 变更        | 检查方法签名和返回值类型       |
+| 注解处理器错误              | Lombok 版本不匹配                 | 检查 lombok 版本和 IDE 插件   |
+
+### 2. 运行时错误
+
+| 错误类型                    | 常见原因                          | 排查方向                     |
+|---------------------------|----------------------------------|------------------------------|
+| `NullPointerException`     | 未初始化对象、数据库返回 null      | 检查空值判断和 Optional 使用  |
+| `ClassCastException`       | 类型转换错误                      | 检查泛型和强制转换             |
+| `StackOverflowError`       | 递归无终止、循环依赖               | 检查递归逻辑和 Bean 依赖关系  |
+
+### 3. 配置错误
+
+| 错误类型                    | 常见原因                          | 排查方向                     |
+|---------------------------|----------------------------------|------------------------------|
+| 属性绑定失败                | YAML 格式错误、类型不匹配          | 检查 application.yml 缩进    |
+| Profile 未激活              | 环境变量缺失                      | 检查 spring.profiles.active  |
+| Bean 创建失败               | 条件注解不满足、依赖缺失           | 检查 @Conditional 和依赖注入  |
+
+### 4. 网络错误
+
+| 错误类型                    | 常见原因                          | 排查方向                     |
+|---------------------------|----------------------------------|------------------------------|
+| 连接超时                    | 服务不可达、防火墙                 | 检查网络连通性和端口           |
+| 连接被拒绝                  | 目标服务未启动                    | 检查目标服务状态               |
+| DNS 解析失败                | 域名配置错误                      | 检查 hosts 和 DNS 配置        |
+
+### 5. 数据层错误
+
+| 错误类型                    | 常见原因                          | 排查方向                     |
+|---------------------------|----------------------------------|------------------------------|
+| SQL 语法错误                | MyBatis XML 映射错误              | 检查 Mapper XML 语法          |
+| 数据截断                    | 字段长度超限                      | 检查表结构和输入数据           |
+| 死锁                       | 事务范围过大、锁顺序不一致          | 检查事务边界和加锁顺序         |
+
+## 根因分析工作流
+
+```
+1. 收集信息
+   ├── 完整的异常堆栈（Stack Trace）
+   ├── 触发操作和时间点
+   ├── 环境信息（开发/测试/生产）
+   └── 最近的代码/配置变更
+
+2. 定位异常源
+   ├── 从堆栈底部找到 Caused by 根因
+   ├── 定位到项目代码行（非框架代码）
+   └── 确认是业务代码还是框架/配置问题
+
+3. 分析原因
+   ├── 复现问题（构造最小复现场景）
+   ├── 检查相关代码逻辑
+   ├── 检查配置文件
+   └── 检查依赖版本
+
+4. 修复验证
+   ├── 制定修复方案
+   ├── 编写/补充测试用例
+   ├── 回归测试
+   └── 记录修复过程
+```
+
+## Avatar Boot 常见异常及修复
+
+### Bean 创建失败
+
+```
+错误信息: BeanCreationException: Error creating bean with name 'xxxService'
+```
+
+**常见原因与修复：**
+
+```java
+// 原因1：循环依赖
+// 修复：使用 @Lazy 延迟注入
+@Service
+public class OrderService {
+    @Lazy
+    @Autowired
+    private UserService userService;
+}
+
+// 原因2：条件 Bean 缺失
+// 修复：检查 @ConditionalOnProperty 配置
+// 确保 application.yml 中有对应配置项
+
+// 原因3：构造器参数无法注入
+// 修复：确认依赖 Bean 是否存在，检查包扫描路径
+```
+
+### Nacos 连接失败
+
+```
+错误信息: NacosException: Client not connected, current status: STARTING
+```
+
+**修复步骤：**
+
+1. 检查 Nacos 服务是否启动：`curl http://nacos-host:8848/nacos/actuator/health`
+2. 检查配置文件：
+   ```yaml
+   spring:
+     cloud:
+       nacos:
+         discovery:
+           server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
+           namespace: ${NACOS_NAMESPACE:}
+         config:
+           server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
+           file-extension: yml
+   ```
+3. 检查网络连通性和命名空间配置
+
+### Feign 调用超时
+
+```
+错误信息: SocketTimeoutException: Read timed out
+```
+
+**修复方案：**
+
+```yaml
+# application.yml 调整超时配置
+spring:
+  cloud:
+    openfeign:
+      client:
+        config:
+          default:
+            connect-timeout: 5000
+            read-timeout: 10000
+          # 针对特定服务
+          user-service:
+            connect-timeout: 3000
+            read-timeout: 30000
+```
+
+### MyBatis 映射错误
+
+```
+错误信息: BindingException: Invalid bound statement (not found)
+```
+
+**排查清单：**
+
+1. 检查 Mapper 接口的 `@Mapper` 注解或 `@MapperScan` 配置
+2. 检查 XML 文件路径是否与配置匹配：
+   ```yaml
+   mybatis-plus:
+     mapper-locations: classpath*:/mapper/**/*.xml
+   ```
+3. 检查 XML 中 namespace 是否与 Mapper 接口全限定名一致
+4. 检查方法名是否与 XML 中 id 一致
+
+### 数据库连接池耗尽
+
+```
+错误信息: HikariPool - Connection is not available, request timed out
+```
+
+**修复方案：**
+
+```yaml
+spring:
+  datasource:
+    hikari:
+      maximum-pool-size: 20
+      minimum-idle: 5
+      idle-timeout: 300000
+      max-lifetime: 1800000
+      connection-timeout: 30000
+      leak-detection-threshold: 60000  # 开启连接泄漏检测
+```
+
+同时排查：是否有未关闭的数据库连接、事务范围是否过大。
+
+## 修复建议输出格式
+
+排查完成后，按以下格式输出结论：
+
+```
+## 异常诊断报告
+
+### 异常摘要
+[一句话描述异常现象]
+
+### 根本原因
+[具体原因分析]
+
+### 影响范围
+[受影响的功能/模块]
+
+### 修复方案
+1. [具体修复步骤1]
+2. [具体修复步骤2]
+
+### 预防措施
+[如何避免类似问题再次发生]
+```
+
+## 最佳实践
+
+1. **日志优先** — 先查日志，再看代码；关注 `ERROR` 和 `WARN` 级别日志
+2. **最小复现** — 构造最简场景复现问题，排除干扰因素
+3. **二分法** — 对于难以定位的问题，使用二分法缩小范围
+4. **版本对比** — 与上一个正常版本对比，找出变更点
+5. **工具辅助** — 善用 Arthas、JStack、JMap 等诊断工具
+6. **知识沉淀** — 将排查过程和结论记录到团队知识库
+7. **监控预警** — 排查后评估是否需要增加监控告警
+8. **根因修复** — 不要只修复表象，要解决根本原因

package/templates/CLAUDE.md

@@ -0,0 +1,173 @@
+# 项目 - 开发规范
+
+## 一、项目概述
+
+本项目是一个基于 Avatar Boot 框架的微服务脚手架项目，用于快速构建企业级虚拟人（Avatar）应用。
+
+- **核心功能**: 提供标准化的 API + Service 双模块结构，支持服务注册发现、配置管理、服务间调用
+- **核心用户**: 企业内部开发团队，用于快速启动新的微服务项目
+- **主要解决的问题**: 统一技术栈、规范项目结构、简化微服务开发流程
+
+---
+
+## 二、整体架构图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Nacos 注册中心 & 配置中心                  │
+└────────────────────────┬────────────────────────────────────┘
+                         │ 服务注册/配置拉取
+┌────────────────────────┴────────────────────────────────────┐
+│                   Avatar Boot 微服务实例                      │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │              avatar-scaffold-service                  │  │
+│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐     │  │
+│  │  │ Controller │  │  Service   │  │    DAO     │     │  │
+│  │  │ (REST API) │→ │  (业务逻辑) │→ │  (MyBatis) │     │  │
+│  │  └────────────┘  └────────────┘  └────────────┘     │  │
+│  │         ↓ 返回 Result<T>              ↓              │  │
+│  │  ┌────────────┐                 ┌────────────┐      │  │
+│  │  │  Response  │                 │   MySQL    │      │  │
+│  │  │    DTO     │                 │  Database  │      │  │
+│  │  └────────────┘                 └────────────┘      │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                         ↑ 依赖                              │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │               avatar-scaffold-api                     │  │
+│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐     │  │
+│  │  │    API     │  │  Request   │  │  Response  │     │  │
+│  │  │  接口定义   │  │    DTO     │  │    DTO     │     │  │
+│  │  └────────────┘  └────────────┘  └────────────┘     │  │
+│  │  ┌────────────┐  ┌────────────┐                     │  │
+│  │  │   Feign    │  │  Constant  │                     │  │
+│  │  │  客户端     │  │  / Enums   │                     │  │
+│  │  └────────────┘  └────────────┘                     │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                         ↓ 依赖                              │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │              avatar-boot-dependency                   │  │
+│  │         (统一版本管理 BOM)                              │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+
+服务间调用:
+┌──────────────┐   Feign Client    ┌──────────────┐
+│  Service A   │ ─────────────────→ │  Service B   │
+│  (调用方)     │   (HTTP + Nacos)   │  (提供方)     │
+└──────────────┘                    └──────────────┘
+```
+
+---
+
+## 三、规则和技能索引
+
+### 规则 (Rules) — `.claude/rules/`
+
+| 文件 | 内容 |
+|------|------|
+| [tech-stack.md](.claude/rules/tech-stack.md) | 技术栈约束、禁止依赖、Maven 仓库配置 |
+| [architecture-redlines.md](.claude/rules/architecture-redlines.md) | 架构红线、通信协议、目录规范、违规检查清单 |
+| [coding-standards.md](.claude/rules/coding-standards.md) | Java 编码规范、Maven 配置规范 |
+| [git-commit.md](.claude/rules/git-commit.md) | Git 提交格式、Type 类型、提交规则 |
+| [version.md](.claude/rules/version.md) | 依赖版本速查表、版本升级流程 |
+| [layered-architecture.md](.claude/rules/layered-architecture.md) | Spring Boot 分层架构规范（Controller/Service/Mapper 职责、Entity/DTO 区分） |
+| [mybatis-plus.md](.claude/rules/mybatis-plus.md) | MyBatis Plus 使用规范（Entity 注解、查询规范、性能反模式） |
+| [code-review-standards.md](.claude/rules/code-review-standards.md) | 代码审查标准（审查维度、严重级别、安全/性能审查项） |
+
+### 技能 (Skills) — `.claude/skills/`
+
+| 技能 | 触发场景 |
+|------|---------|
+| [api-service-module-creator](.claude/skills/api-service-module-creator/) | 创建新功能模块（API + Service 双模块结构） |
+| [avatar-boot-starter-web](.claude/skills/avatar-boot-starter-web/) | Web 接口开发、全局异常处理、请求上下文 |
+| [avatar-boot-starter-nacos](.claude/skills/avatar-boot-starter-nacos/) | Nacos 服务注册、配置中心集成 |
+| [avatar-boot-starter-feign](.claude/skills/avatar-boot-starter-feign/) | Feign 客户端、服务间调用 |
+| [avatar-boot-starter-job](.claude/skills/avatar-boot-starter-job/) | XXL-Job 分布式任务调度 |
+| [avatar-boot-starter-redis](.claude/skills/avatar-boot-starter-redis/) | Redis 缓存、Redisson 分布式锁、Spring Cache |
+| [avatar-boot-starter-mysql](.claude/skills/avatar-boot-starter-mysql/) | MySQL 数据源、Druid 连接池、MyBatis Plus 配置 |
+| [avatar-boot-starter-kafka](.claude/skills/avatar-boot-starter-kafka/) | Kafka 消息生产/消费、幂等消费、死信队列 |
+| [avatar-boot-starter-rocketmq](.claude/skills/avatar-boot-starter-rocketmq/) | RocketMQ 消息、延迟消息、事务消息、顺序消息 |
+| [avatar-boot-starter-oss](.claude/skills/avatar-boot-starter-oss/) | OSS 对象存储、文件上传/下载、客户端直传 |
+| [code-review](.claude/skills/code-review/) | 代码审查、CR、Review PR |
+| [crud-generator](.claude/skills/crud-generator/) | CRUD 代码生成、增删改查、Entity 创建 |
+| [database-design](.claude/skills/database-design/) | 数据库设计、DDL 生成、索引建议 |
+| [api-design](.claude/skills/api-design/) | RESTful API 接口设计、URL 规范 |
+| [troubleshooting](.claude/skills/troubleshooting/) | 异常排查、错误分析、故障定位 |
+| [security-audit](.claude/skills/security-audit/) | 安全审计、OWASP Top 10、SQL 注入检测 |
+| [test-case-design](.claude/skills/test-case-design/) | 测试用例设计、Given-When-Then、边界值分析 |
+| [integration-test-generator](.claude/skills/integration-test-generator/) | 集成测试生成、@SpringBootTest、MockMvc |
+| [incident-analysis](.claude/skills/incident-analysis/) | 故障分析、5Why 根因分析、事故复盘 |
+| [api-doc-generator](.claude/skills/api-doc-generator/) | API 文档生成、OpenAPI/Swagger 注解、SpringDoc |
+| [requirement-management](.claude/skills/requirement-management/) | 需求评审 + 技术方案设计（PRD 拆解、风险识别） |
+| [deployment-config](.claude/skills/deployment-config/) | Docker 多阶段构建、K8s Deployment/Service/Ingress |
+| [changelog-generator](.claude/skills/changelog-generator/) | 变更日志生成、Keep-a-Changelog 格式 |
+| [ai-tool-guide](.claude/skills/ai-tool-guide/) | AI 工具使用指南（Claude Code/Cursor 使用规范、上下文管理） |
+| [prompt-engineering](.claude/skills/prompt-engineering/) | Prompt 模板库（Java 各场景即用模板与上下文片段） |
+| [testing-workflow](.claude/skills/testing-workflow/) | 编写测试、覆盖率检查、测试命令 |
+
+---
+
+## 四、快速参考
+
+### 创建新功能模块
+
+1. 在 `avatar-scaffold-api` 中创建功能包（如 `order`）
+2. 创建 API 接口、DTO、Feign 客户端
+3. 在 `avatar-scaffold-service` 中创建对应包
+4. 实现 Controller、Service、DAO
+5. 编写单元测试
+6. 提交代码并创建 PR
+
+### 常用命令
+
+```bash
+# 编译项目
+mvn clean compile
+
+# 运行测试
+mvn clean test
+
+# 打包
+mvn clean package -DskipTests
+
+# 检查依赖
+mvn dependency:tree
+
+# 检查安全漏洞
+mvn org.owasp:dependency-check-maven:check
+
+# 启动服务（开发环境）
+mvn spring-boot:run -Dspring-boot.run.profiles=dev
+```
+
+### 环境配置
+
+```yaml
+# application.yml
+spring:
+  profiles:
+    active: ${SPRING_PROFILES_ACTIVE:dev}
+  application:
+    name: avatar-scaffold-service
+  cloud:
+    nacos:
+      discovery:
+        server-addr: ${NACOS_SERVER_ADDR:localhost:8848}
+      config:
+        server-addr: ${NACOS_SERVER_ADDR:localhost:8848}
+```
+
+---
+
+## 五、团队赋能
+
+| 文档 | 说明 | Skill 路径 |
+|------|------|-----------|
+| AI 工具使用指南 | Claude Code / Cursor 使用规范、上下文管理 | [ai-tool-guide](.claude/skills/ai-tool-guide/) |
+| Prompt 模板库 | Java 各场景即用 Prompt 模板与上下文片段 | [prompt-engineering](.claude/skills/prompt-engineering/) |
+
+---
+
+**最后更新**: 2026-03-10
+**维护者**: Avatar Boot 开发团队
+**联系方式**: 通过项目 Issue 反馈问题