@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

package/docs/exam-question-generate-api.md

@@ -0,0 +1,163 @@
+# 试题生成 API 接口协议
+
+## 1. 按要求生成试题
+
+**POST** `/api/exam/questions/generate-by-requirement`
+
+**Content-Type:** `application/json`
+
+### 请求参数
+
+```json
+{
+  "examName": "考题名称",
+  "requirement": "请用自然语言描述考题要求，不超过1000字",
+  "questionType": "SINGLE_CHOICE",
+  "count": 5,
+  "example": "可提供示例作为参考（选填）"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| examName | String | 是 | 考题名称 |
+| requirement | String | 是 | 考题要求，最大1000字 |
+| questionType | String(enum) | 是 | 出题类型，见枚举定义 |
+| count | Integer | 是 | 题量，>=1 |
+| example | String | 否 | 示例参考 |
+
+### 响应
+
+见 [统一响应格式](#4-统一响应格式)
+
+---
+
+## 2. 上传文件生成试题
+
+**POST** `/api/exam/questions/generate-by-file`
+
+**Content-Type:** `multipart/form-data`
+
+### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| examName | String | 是 | 考题名称 |
+| file | MultipartFile | 是 | 上传文件，支持 doc/docx/ppt/pptx/md/txt/pdf，单文件不超过50MB，总量不超过100MB |
+| questionType | String(enum) | 是 | 出题类型，见枚举定义 |
+| count | Integer | 是 | 题量，>=1 |
+| example | String | 否 | 示例参考 |
+
+### 响应
+
+见 [统一响应格式](#4-统一响应格式)
+
+---
+
+## 3. 枚举定义
+
+### QuestionTypeEnum 出题类型
+
+| 枚举值 | 说明 |
+|--------|------|
+| SINGLE_CHOICE | 单选题 |
+| MULTIPLE_CHOICE | 多选题 |
+| FILL_BLANK | 填空题 |
+| TRUE_FALSE | 判断题 |
+| SHORT_ANSWER | 简答题 |
+
+> 注意：每次请求只能指定一种出题类型，支持生成单个或多个题目。
+
+---
+
+## 4. 统一响应格式
+
+所有接口统一使用 `Result<ExamGenerateResponse>` 包装。
+
+### 响应结构
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "examName": "考题名称",
+    "questionType": "SINGLE_CHOICE",
+    "questions": [
+      {
+        "index": 1,
+        "stem": "题干内容",
+        "options": [
+          { "key": "A", "value": "选项A" },
+          { "key": "B", "value": "选项B" },
+          { "key": "C", "value": "选项C" },
+          { "key": "D", "value": "选项D" }
+        ],
+        "answer": "A",
+        "analysis": "解析说明"
+      }
+    ]
+  }
+}
+```
+
+### 响应字段说明
+
+#### ExamGenerateResponse
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| examName | String | 考题名称 |
+| questionType | String(enum) | 出题类型 |
+| questions | List\<QuestionItem\> | 题目列表 |
+
+#### QuestionItem
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| index | Integer | 题目序号，从1开始 |
+| stem | String | 题干内容 |
+| options | List\<Option\> | 选项列表，仅单选题/多选题有值，其他题型为 null |
+| answer | String | 正确答案 |
+| analysis | String | 答案解析 |
+
+#### Option
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| key | String | 选项标识，如 A、B、C、D |
+| value | String | 选项内容 |
+
+### 各题型 answer 格式差异
+
+| 题型 | options | answer 格式 | 示例 |
+|------|---------|-------------|------|
+| 单选题(SINGLE_CHOICE) | A/B/C/D 选项列表 | 单个字母 | `"A"` |
+| 多选题(MULTIPLE_CHOICE) | A/B/C/D/E 选项列表 | 多个字母，逗号分隔 | `"A,B,D"` |
+| 填空题(FILL_BLANK) | null | 填空答案，多空用 `\|\|` 分隔 | `"答案1\|\|答案2"` |
+| 判断题(TRUE_FALSE) | null | TRUE 或 FALSE | `"TRUE"` |
+| 简答题(SHORT_ANSWER) | null | 参考答案文本 | `"参考答案内容..."` |
+
+> 填空题题干中使用 `___` 表示填空位置。
+
+---
+
+## 5. 错误码
+
+| code | message | 说明 |
+|------|---------|------|
+| 200 | success | 成功 |
+| 400 | 参数校验失败 | 必填字段缺失或格式错误 |
+| 413 | 文件大小超出限制 | 单文件超过50MB或总量超过100MB |
+| 415 | 不支持的文件格式 | 文件类型不在支持列表中 |
+| 500 | 生成失败 | 服务端异常 |
+
+### 错误响应示例
+
+```json
+{
+  "code": 400,
+  "message": "考题名称不能为空",
+  "data": null
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llryiop/avatar-boot-cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI tool for scaffolding AvatarBoot Java microservice projects",
   "main": "src/index.js",
   "bin": {

package/src/prompts.js

@@ -32,7 +32,7 @@ export async function collectConfig(initialName) {
       type: 'input',
       name: 'avatarBootVersion',
       message: 'Avatar Boot 版本:',
-      default: '1.0.0-SNAPSHOT',
+      default: '1.0.1',
     },
     {
       type: 'checkbox',
@@ -50,14 +50,14 @@ export async function collectConfig(initialName) {
       type: 'input',
       name: 'nacosAddr',
       message: 'Nacos 地址:',
-      default: '127.0.0.1:8848',
+      default: '172.31.250.98:8848',
       when: (answers) => answers.starters.includes('nacos'),
     },
     {
       type: 'input',
       name: 'dbUrl',
       message: '数据库地址 (host:port/dbname):',
-      default: 'localhost:3306/avatar',
+      default: 'mysql1_23306_test.xfyousheng.com:23306/avatar_zhizuo',
       when: (answers) => answers.starters.includes('mysql'),
     },
     {

package/src/transform.js

@@ -14,7 +14,7 @@ export function transformProject(projectDir, config) {
   const {
     projectName,
     groupId = DEFAULT_GROUP_ID,
-    avatarBootVersion = '1.0.0',
+    avatarBootVersion = '1.0.1',
     starters = ['web', 'nacos'],
     includeExample = true,
     nacosAddr = '127.0.0.1:8848',

package/templates/.claude/skills/avatar-boot-starter-feign/README.md

@@ -0,0 +1,243 @@
+---
+name: avatar-boot-starter-feign
+description: 当使用 avatar-boot-starter-feign 模块时使用此技能 - 为 Spring Boot 3.5.3 应用提供全面的 openfeign开发，包括自动配置、TraceId 传播、日志配置、指标集成。
+---
+
+Avatar Boot 的 OpenFeign 客户端集成模块，提供开箱即用的 openfeign功能，包含自动日志记录和性能指标监控。
+
+## 功能特性
+
+- ✅ **自动配置** - 基于 Spring Boot 自动配置机制，零配置即可使用
+- ✅ **请求日志** - 自动记录 Feign 客户端的请求参数和响应数据
+- ✅ **TraceId 传播** - 自动传播分布式追踪 ID 到下游服务
+- ✅ **性能指标** - 集成 Micrometer，记录调用次数、执行时间、成功/失败率
+- ✅ **慢请求检测** - 自动检测并警告超过阈值的慢请求
+- ✅ **灵活配置** - 支持细粒度的功能开关和参数配置
+
+## 快速开始
+
+### 1. 添加依赖
+
+在项目的 `pom.xml` 中添加依赖：
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-feign</artifactId>
+</dependency>
+```
+
+### 2. 定义 Feign 客户端
+
+在 Spring Boot 应用主类上添加 `@EnableFeignClients` 注解：
+
+```java
+@SpringBootApplication
+@EnableFeignClients
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}
+```
+
+然后定义 Feign 客户端接口：
+
+```java
+import com.iflytek.avatar.boot.config.FeignLoggingConfiguration;
+
+// 使用 FeignLoggingConfiguration 启用详细日志记录
+@FeignClient(name = "user-service", url = "http://localhost:8080",
+             configuration = FeignLoggingConfiguration.class)
+public interface UserServiceClient {
+
+    @GetMapping("/api/users/{id}")
+    User getUserById(@PathVariable("id") Long id);
+
+    @PostMapping("/api/users")
+    User createUser(@RequestBody User user);
+}
+```
+
+**重要说明：**
+- `FeignLoggingConfiguration` 不是默认启用的，需要在 `@FeignClient` 的 `configuration` 属性中显式指定
+- 如果不指定 `configuration`，则只会启用 TraceId 传播功能，不会打印详细日志
+- 这样设计是为了让你可以灵活控制哪些 Feign 客户端需要详细日志
+
+### 3. 使用 Feign 客户端
+
+```java
+@Service
+@RequiredArgsConstructor
+public class UserService {
+
+    private final UserServiceClient userServiceClient;
+
+    public User getUser(Long id) {
+        return userServiceClient.getUserById(id);
+    }
+}
+```
+
+## 配置说明
+
+### 基础配置
+
+```yaml
+avatar:
+  feign:
+    logging:
+      enabled: true                      # 启用日志拦截器（TraceId 传播）
+      request-enabled: true              # 记录请求参数
+      response-enabled: true             # 记录响应数据
+      print-request-details: true        # 打印请求详情（URI、Method、Params）
+      print-response-details: true       # 打印响应详情（包含响应体）
+      print-stack-trace: true            # 打印异常堆栈信息
+      slow-request-threshold: 3000       # 慢请求阈值（毫秒）
+      max-body-length: 1000              # 最大请求体长度
+      trace-id-header: X-Trace-Id        # TraceId 请求头名称
+    metrics:
+      enabled: true                      # 启用指标记录
+```
+
+### 完整配置示例
+
+参考 `src/main/resources/application-example.yml` 查看完整配置示例。
+
+## 功能详解
+
+### 1. 详细日志记录
+
+当在 FeignClient 中配置 `FeignLoggingConfiguration` 后，会自动记录详细的请求和响应信息：
+
+**成功请求日志：**
+```
+Feign Request => URI: http://localhost:8080/api/users/1, Method: GET, Params: N/A
+Feign Response => Method: getUserById, URI: http://localhost:8080/api/users/1, Params: N/A, Response: {"id":1,"name":"John"}, Status: 200, Time: 125ms
+```
+
+**失败请求日志：**
+```
+Feign Error => Method: getUserById, URI: http://localhost:8080/api/users/1, Params: N/A, Error: Connection refused, Time: 50ms, StackTrace:
+java.net.ConnectException: Connection refused
+    at ...
+```
+
+**配置控制：**
+- `print-request-details: false` - 不打印请求详情
+- `print-response-details: false` - 不打印响应体（只打印状态和耗时）
+- `print-stack-trace: false` - 不打印异常堆栈信息
+- `max-body-length: 500` - 限制请求体/响应体的最大长度
+
+### 2. TraceId 传播
+
+自动从 `ContextManager` 获取 TraceId 并添加到请求头，实现分布式追踪：
+
+```java
+// 在上游服务中设置 TraceId
+ContextManager.get().setTraceId("trace-123");
+
+// Feign 客户端会自动将 TraceId 添加到请求头
+// X-Trace-Id: trace-123
+```
+
+**注意：** TraceId 传播是全局启用的，不需要在 FeignClient 中配置 `FeignLoggingConfiguration`。
+
+### 3. 性能指标
+
+集成 Micrometer，自动记录以下指标：
+
+- `feign.client.invocation.count` - 调用次数（标签：client, method, status）
+- `feign.client.execution.time` - 执行时间（标签：client, method, status）
+
+查看指标：
+
+```bash
+# 访问 Actuator 端
+curl http://localhost:8080/actuator/metrics/feign.client.invocation.count
+curl http://localhost:8080/actuator/metrics/feign.client.execution.time
+```
+
+### 4. 慢请求检测
+
+当请求执行时间超过配置的阈值时，自动记录警告日志：
+
+```
+WARN: Slow Feign Request Detected: getUserById took 3500ms (threshold: 3000ms)
+```
+
+## 使用场景
+
+### 场景 1：只需要 TraceId 传播，不需要详细日志
+
+```java
+// 不指定 configuration，只会启用 TraceId 传播
+@FeignClient(name = "simple-service", url = "http://localhost:8080")
+public interface SimpleServiceClient {
+    @GetMapping("/api/data")
+    String getData();
+}
+```
+
+### 场景 2：需要详细日志记录和性能监控
+
+```java
+// 指定 FeignLoggingConfiguration，启用详细日志
+@FeignClient(name = "important-service", url = "http://localhost:8080",
+             configuration = FeignLoggingConfiguration.class)
+public interface ImportantServiceClient {
+    @PostMapping("/api/process")
+    Result processData(@RequestBody Data data);
+}
+```
+
+### 场景 3：自定义日志配置
+
+```yaml
+avatar:
+  feign:
+    logging:
+      # 只打印错误日志，不打印成功请求
+      print-request-details: false
+      print-response-details: false
+      # 但保留异常堆栈信息
+      print-stack-trace: true
+      # 降低慢请求阈值
+      slow-request-threshold: 1000
+```
+
+## 高级配置
+
+### 针对特定客户端的配置
+
+```yaml
+feign:
+  client:
+    config:
+      user-service:
+        connectTimeout: 3000
+        readTimeout: 5000
+        loggerLevel: FULL
+```
+
+### 禁用日志或指标
+
+```yaml
+avatar:
+  feign:
+    logging:
+      enabled: false  # 禁用日志
+    metrics:
+      enabled: false  # 禁用指标
+```
+
+## 依赖版本
+
+- Spring Boot: 3.5.3
+- Spring Cloud: 2025.0.0
+- Java: 21
+
+## 许可证
+
+Copyright © 2024 iFLYTEK Co., Ltd.
+