@llryiop/avatar-boot-cli 1.0.0

package/README.md

@@ -0,0 +1,309 @@
+# Avatar Boot CLI 操作手册
+
+## 简介
+
+`avatar-boot-cli` 是 AvatarBoot Java 微服务项目的脚手架工具。通过交互式命令行，快速创建一个标准化的 AvatarBoot 微服务项目，包含 API + Service 双模块结构、Maven 配置、环境配置及可选的 AI Agent 配置。
+
+## 环境要求
+
+| 工具 | 版本要求 | 用途 |
+|------|---------|------|
+| Node.js | >= 18 | 运行 CLI 工具 |
+| Git | >= 2.0 | 克隆模板仓库 |
+| Maven | >= 3.8.6 | 构建生成的项目 |
+| JDK | 21 | 编译运行项目 |
+
+## 安装与使用
+
+### 方式一：npx 直接运行（推荐）
+
+无需安装，直接运行：
+
+```bash
+npx avatar-boot-cli init
+```
+
+或指定项目名：
+
+```bash
+npx avatar-boot-cli init my-order-service
+```
+
+### 方式二：全局安装
+
+```bash
+npm install -g avatar-boot-cli
+avatar-boot-cli init
+```
+
+### 方式三：本地运行（开发调试）
+
+```bash
+git clone <本仓库地址>
+cd npx
+npm install
+node bin/cli.js init
+```
+
+## 交互式配置说明
+
+运行 `init` 命令后，工具会依次提示以下配置项。**所有配置都可以直接回车跳过，使用默认值。**
+
+### 1. 项目名称
+
+```
+? 项目名称: (my-avatar-service)
+```
+
+- **默认值：** `my-avatar-service`
+- **命名规则：** 小写字母开头，只能包含小写字母、数字和连字符
+- **示例：** `avatar-order-service`、`avatar-user-center`
+- **影响范围：**
+  - 项目根目录名
+  - Maven artifactId
+  - 子模块目录名（`{项目名}-api`、`{项目名}-service`）
+  - `spring.application.name`
+
+### 2. Maven groupId
+
+```
+? Maven groupId: (com.iflytek.avatar)
+```
+
+- **默认值：** `com.iflytek.avatar`
+- **命名规则：** 小写字母开头，只能包含小写字母、数字和点号
+- **示例：** `com.iflytek.avatar.order`
+- **影响范围：**
+  - pom.xml 中的 `<groupId>`
+  - Java 源码的 package 声明和 import 路径
+  - 源码目录结构（如 `src/main/java/com/iflytek/avatar/order/`）
+
+### 3. Avatar Boot 版本
+
+```
+? Avatar Boot 版本: (Use arrow keys)
+❯ v1.0.0
+  v1.1.0
+  latest (main branch)
+```
+
+- **默认值：** 列表中第一个（最新 tag）
+- **说明：** 工具会自动从 Git 仓库获取可用的版本 tag。如果无法连接仓库，则只显示 `latest (main branch)` 选项
+- **影响范围：** 克隆的模板版本
+
+### 4. Starter 模块选择
+
+```
+? 选择 Starter 模块: (Press <space> to select, <a> to toggle all)
+ ◉ avatar-boot-starter-web (Web 基础设施)
+ ◉ avatar-boot-starter-nacos (服务注册与配置)
+ ◯ avatar-boot-starter-feign (服务间调用)
+ ◯ avatar-boot-starter-mysql (MySQL 数据库)
+ ◯ avatar-boot-starter-redis (Redis 缓存)
+ ◯ avatar-boot-starter-kafka (Kafka 消息队列)
+ ◯ avatar-boot-starter-rocketmq (RocketMQ 消息队列)
+ ◯ avatar-boot-starter-job (XXL-Job 任务调度)
+ ◯ avatar-boot-starter-oss (对象存储)
+```
+
+- **默认选中：** `web`、`nacos`
+- **操作方式：**
+  - `空格键` 选中/取消单个模块
+  - `a` 全选/全不选
+  - `回车` 确认选择
+- **影响范围：** service 模块 pom.xml 中的依赖（选中的取消注释，未选中的注释掉）
+
+**各 Starter 功能说明：**
+
+| Starter | 说明 | 典型场景 |
+|---------|------|---------|
+| `web` | Web 基础设施，含统一返回格式、全局异常处理 | 所有 Web 服务必选 |
+| `nacos` | Nacos 服务注册与配置中心 | 微服务环境必选 |
+| `feign` | 基于 OpenFeign 的服务间调用 | 需要调用其他微服务 |
+| `mysql` | MySQL 数据库 + MyBatis Plus | 需要持久化存储 |
+| `redis` | Redis 缓存 | 需要缓存、分布式锁 |
+| `kafka` | Kafka 消息队列 | 异步消息、事件驱动 |
+| `rocketmq` | RocketMQ 消息队列 | 异步消息（阿里系） |
+| `job` | XXL-Job 分布式任务调度 | 定时任务、批处理 |
+| `oss` | 对象存储 | 文件上传下载 |
+
+### 5. 示例代码
+
+```
+? 是否生成示例代码 (login 模块): (Y/n)
+```
+
+- **默认值：** 是（Y）
+- **说明：** 生成一个完整的 login 示例模块，包含 Controller、Service、Mapper、DTO、Feign Client 等标准分层代码，可作为业务开发参考
+- **影响范围：**
+  - `{项目名}-api/src/main/java/.../login/` — Feign 接口、DTO、常量、枚举、异常
+  - `{项目名}-service/src/main/java/.../login/` — Controller、Service、Mapper、Entity、Converter、Utils
+
+### 6. Nacos 地址（选了 nacos 模块时出现）
+
+```
+? Nacos 地址: (127.0.0.1:8848)
+```
+
+- **默认值：** `127.0.0.1:8848`
+- **示例：** `172.29.242.247:8848`
+- **影响范围：** `application-dev.yaml` 中的 `spring.cloud.nacos.server-addr`
+
+### 7. 数据库地址（选了 mysql 模块时出现）
+
+```
+? 数据库地址 (host:port/dbname): (localhost:3306/avatar)
+```
+
+- **默认值：** `localhost:3306/avatar`
+- **示例：** `192.168.1.100:3306/order_db`
+- **影响范围：** `application-dev.yaml` 中的数据库连接配置
+
+### 8. AI Agent 配置
+
+```
+? 是否生成 .claude/ AI Agent 配置: (Y/n)
+```
+
+- **默认值：** 是（Y）
+- **说明：** 生成 `.claude/` 目录和 `CLAUDE.md`，包含项目规则（架构规范、编码标准、技术栈约束等）和技能定义，让 Claude 等 AI 编程助手更好地理解项目
+- **影响范围：**
+  - `.claude/rules/` — 8 个规则文件（架构红线、编码规范、分层架构等）
+  - `.claude/skills/` — 24 个技能定义（模块创建、CRUD 生成、API 设计等）
+  - `CLAUDE.md` — 项目总览文档
+
+### 9. 服务端口
+
+```
+? 服务端口: (8888)
+```
+
+- **默认值：** `8888`
+- **影响范围：** `application.yaml` 中的 `server.port`
+
+## 完整使用示例
+
+### 示例 1：快速创建（全部默认值）
+
+```bash
+npx avatar-boot-cli init my-order-service
+# 然后一路回车
+```
+
+生成结果：
+
+```
+my-order-service/
+├── my-order-service-api/          # API 模块
+│   ├── pom.xml
+│   └── src/main/java/com/iflytek/avatar/
+│       └── login/                 # 示例模块
+│           ├── api/               # Feign 接口
+│           ├── dto/               # 请求/响应对象
+│           ├── constant/          # 常量
+│           ├── enums/             # 枚举
+│           └── exception/         # 自定义异常
+├── my-order-service-service/      # Service 模块
+│   ├── pom.xml
+│   └── src/main/java/com/iflytek/avatar/
+│       ├── Application.java       # 启动类
+│       └── login/                 # 示例模块
+│           ├── controller/        # REST 接口
+│           ├── service/           # 业务逻辑
+│           ├── repository/        # 数据访问 (Mapper + Entity)
+│           ├── converter/         # 对象转换
+│           ├── config/            # 模块配置
+│           ├── feign/             # Feign 调用
+│           └── utils/             # 工具类
+├── .claude/                       # AI Agent 配置
+├── CLAUDE.md
+└── pom.xml                        # 父 POM
+```
+
+### 示例 2：自定义配置
+
+```bash
+npx avatar-boot-cli init
+
+? 项目名称: avatar-user-center
+? Maven groupId: com.iflytek.avatar.user
+? Avatar Boot 版本: v1.0.0
+? 选择 Starter 模块: web, nacos, feign, mysql, redis
+? 是否生成示例代码 (login 模块): No
+? Nacos 地址: 172.29.242.247:8848
+? 数据库地址 (host:port/dbname): 172.29.242.247:3306/user_center
+? 是否生成 .claude/ AI Agent 配置: Yes
+? 服务端口: 9090
+```
+
+## 项目创建后
+
+### 1. 进入项目目录
+
+```bash
+cd my-order-service
+```
+
+### 2. 初始化 Git 仓库
+
+```bash
+git init
+git add .
+git commit -m "init: 初始化项目"
+```
+
+### 3. 编译项目
+
+```bash
+mvn clean compile
+```
+
+### 4. 本地启动（需要 Nacos）
+
+```bash
+cd my-order-service-service
+mvn spring-boot:run -Dspring-boot.run.profiles=dev
+```
+
+### 5. 创建新业务模块
+
+参考 login 示例模块的结构，在对应目录下创建新的业务包：
+
+```
+# API 模块中创建
+{项目名}-api/src/main/java/{groupId路径}/{模块名}/
+├── api/                    # Feign 接口
+├── dto/request/            # 请求 DTO
+├── dto/response/           # 响应 DTO
+├── constant/               # 常量
+├── enums/                  # 枚举
+└── exception/              # 异常
+
+# Service 模块中创建
+{项目名}-service/src/main/java/{groupId路径}/{模块名}/
+├── controller/             # Controller
+├── service/                # Service 接口
+├── service/impl/           # Service 实现
+├── repository/mapper/      # MyBatis Mapper
+├── repository/entity/      # 数据库实体
+├── converter/              # 对象转换器
+└── config/                 # 配置类
+```
+
+## 常见问题
+
+### Q: 克隆模板失败？
+
+检查网络连接是否能访问 `code.iflytek.com`，确保 Git 已配置正确的凭据。
+
+### Q: 目录已存在？
+
+工具不会覆盖已有目录。删除同名目录后重新运行，或使用其他项目名。
+
+### Q: 版本列表为空？
+
+如果无法连接 Git 仓库获取 tag，工具会显示 `latest (main branch)` 选项，使用主分支最新代码。
+
+### Q: 如何添加新的 Starter 依赖？
+
+项目创建后，手动编辑 `{项目名}-service/pom.xml`，取消注释或添加对应的 `avatar-boot-starter-*` 依赖即可。

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+run();

package/docs/plans/2026-03-12-avatar-boot-cli-design.md

@@ -0,0 +1,73 @@
+# Avatar Boot CLI 设计文档
+
+## 概述
+
+`avatar-boot-cli` 是一个 Node.js CLI 工具，用于初始化 AvatarBoot Java 微服务项目。通过 `npx avatar-boot-cli init` 交互式创建项目，从 Git 仓库克隆 avatar-scaffold-project 模板，根据用户配置替换项目内容。
+
+## 核心决策
+
+- **技术栈**: Node.js CLI（npx 风格）
+- **模板来源**: 从 Git 仓库克隆 avatar-scaffold-project
+- **替换策略**: 字符串替换（方案 A），模板项目本身可运行
+- **配置方式**: 全部可选，支持跳过走默认值
+- **AI 配置**: 保持 `.claude/` 目录结构（rules + skills）
+- **子命令**: 仅 `init`，支持选择版本
+
+## 项目结构
+
+```
+npx/
+├── package.json              # npm 包，bin: avatar-boot-cli
+├── bin/
+│   └── cli.js                # 入口 #!/usr/bin/env node
+├── src/
+│   ├── index.js              # 主逻辑
+│   ├── prompts.js            # 交互式问答
+│   ├── clone.js              # Git 克隆
+│   ├── transform.js          # 字符串替换
+│   └── utils.js              # 工具函数
+```
+
+## 交互流程
+
+```
+npx avatar-boot-cli init [project-name]
+  → 项目名称（默认: my-avatar-service）
+  → groupId（默认: com.iflytek.avatar）
+  → Avatar Boot 版本（从 Git tag 列表选择）
+  → Starter 模块多选（web✓, nacos✓, feign, mysql, redis, kafka, rocketmq, job, oss）
+  → 是否生成示例代码（默认: 是）
+  → Nacos 地址（默认: 127.0.0.1:8848）
+  → 数据库连接（如选了 mysql，默认: localhost:3306/avatar）
+  → 是否生成 .claude/ AI 配置（默认: 是）
+  → 克隆 → 替换 → 清理 .git → 完成
+```
+
+## 替换规则
+
+| 目标 | 替换内容 |
+|------|---------|
+| pom.xml `<artifactId>` | `avatar-template` → 项目名 |
+| pom.xml `<groupId>` | `com.iflytek.avatar` → 用户 groupId |
+| pom.xml starter 依赖 | 根据选择注释/取消注释 |
+| 模块目录名 | `avatar-scaffold-api/` → `{project}-api/` |
+| 模块目录名 | `avatar-scaffold-service/` → `{project}-service/` |
+| Java 包路径 | `com/iflytek/avatar` → groupId 对应路径 |
+| package 声明 | 替换 Java 文件中 package 语句 |
+| import 声明 | 替换 Java 文件中 import 语句 |
+| application.yaml | 替换 spring.application.name、nacos 地址等 |
+| 示例代码 | 如不需要，删除 login 模块 |
+| .claude/ 目录 | 如不需要，删除 |
+| .git/ 目录 | 始终删除 |
+
+## 版本选择
+
+通过 `git ls-remote --tags` 获取仓库 tag 列表，用户选择版本后用 `git clone --branch <tag>` 克隆。
+
+## 依赖
+
+- `commander` — CLI 命令解析
+- `inquirer` — 交互式问答
+- `chalk` — 终端彩色输出
+- `ora` — 加载动画
+- `glob` — 文件匹配