ai-engineering-init 1.4.3 → 1.6.0

package/src/skills/init-docs/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: init-docs
+description: |
+  当需要为项目初始化文档体系、创建项目文档时自动使用此 Skill。
+
+  触发场景：
+  - 新项目第一次初始化文档体系
+  - 现有文档丢失或需要重新组织
+  - 新成员加入，需要统一文档格式
+  - 根据最新代码重新生成文档
+
+  触发词：初始化文档、init-docs、文档初始化、创建文档、项目文档、文档体系
+---
+
+# /init-docs - 项目文档初始化
+
+为纯后端 RuoYi-Vue-Plus 项目初始化完整的项目文档体系。支持空白模板或基于现有代码智能生成。
+
+---
+
+## 🎯 适用场景
+
+| 场景 | 说明 |
+|------|------|
+| **项目启动** | 新项目第一次初始化文档体系 |
+| **文档重建** | 现有文档丢失或需要重新组织 |
+| **团队协作** | 新成员加入，需要统一文档格式 |
+| **定期整理** | 根据最新代码重新生成文档 |
+
+---
+
+## 📋 执行模式
+
+### 模式 1：空白模板（默认）
+
+```bash
+/init-docs
+```
+
+创建空白文档结构，适合新项目或想从零开始规划的项目。
+
+### 模式 2：智能扫描
+
+```bash
+/init-docs --scan
+```
+
+扫描现有代码并智能生成文档，自动分析项目结构和代码完整度。
+
+---
+
+## 🚀 执行流程
+
+### 第一步：确认初始化模式
+
+```
+请选择初始化方式：
+1. 空白模板（推荐新项目）
+2. 扫描现有代码（推荐已有代码）
+```
+
+### 第二步：创建目录结构
+
+```bash
+mkdir -p docs
+```
+
+**生成的目录结构**：
+```
+项目根目录/
+└── docs/
+    ├── README.md                 # 项目简介
+    ├── ARCHITECTURE.md           # 架构说明
+    ├── PROJECT_STATUS.md         # 项目进度
+    ├── TODO.md                   # 待办清单
+    └── CHANGELOG.md              # 变更日志
+```
+
+### 第三步：扫描代码（仅在 --scan 模式）
+
+```bash
+# 查找所有业务模块
+Glob pattern: "ruoyi-modules/ruoyi-*/src/main/java/**/controller/*Controller.java"
+```
+
+### 第四步：生成文档内容
+
+根据扫描或手动输入的信息生成文档。
+
+---
+
+## 生成的文档模板
+
+### docs/README.md
+
+```markdown
+# 项目名称
+
+## 📋 项目简介
+
+**项目名**：RuoYi-Vue-Plus 纯后端版
+**技术栈**：
+- **后端框架**：Spring Boot 3.x
+- **ORM框架**：MyBatis-Plus 3.x
+- **权限框架**：Sa-Token
+- **数据库**：MySQL 8.0+
+
+## 🚀 快速开始
+
+1. 克隆项目
+2. 导入数据库
+3. 修改数据库配置
+4. 运行后端服务
+
+## 📖 文档导航
+
+- [📊 项目进度](./PROJECT_STATUS.md)
+- [🏗️ 架构说明](./ARCHITECTURE.md)
+- [📝 待办清单](./TODO.md)
+- [📝 变更日志](./CHANGELOG.md)
+```
+
+### docs/PROJECT_STATUS.md
+
+```markdown
+# 📊 项目进度报告
+
+**报告生成时间**：YYYY-MM-DD
+**项目状态**：🟢 开发中
+
+## 概览
+
+| 指标 | 值 | 说明 |
+|------|-----|------|
+| 总功能数 | X | 规划的功能总数 |
+| 已完成 | X | 100% 完成的功能 |
+| 进行中 | X | 50-99% 的功能 |
+| 待开发 | X | 0% 的功能 |
+```
+
+### docs/TODO.md
+
+```markdown
+# 📝 待办清单
+
+**最后更新**：YYYY-MM-DD
+
+## 🔴 高优先级（本周必做）
+
+- [ ] [任务描述]
+
+## 🟡 中优先级（本月完成）
+
+- [ ] [任务描述]
+
+## 🟢 低优先级（有时间做）
+
+- [ ] [任务描述]
+
+## ✅ 已完成
+
+- [x] [任务描述] - 完成于 YYYY-MM-DD
+```
+
+---
+
+## 第五步：输出初始化报告
+
+```markdown
+# ✅ 项目文档初始化完成！
+
+**初始化时间**：YYYY-MM-DD HH:mm
+
+## 📂 已创建的文件
+
+| 文件 | 说明 | 位置 |
+|------|------|------|
+| README.md | 项目简介 | docs/README.md |
+| PROJECT_STATUS.md | 项目进度 | docs/PROJECT_STATUS.md |
+| ARCHITECTURE.md | 架构说明 | docs/ARCHITECTURE.md |
+| TODO.md | 待办清单 | docs/TODO.md |
+| CHANGELOG.md | 变更日志 | docs/CHANGELOG.md |
+
+## 🎯 下一步建议
+
+### 1️⃣ 快速了解项目
+\`/start\`
+
+### 2️⃣ 查看详细进度
+\`/progress\`
+
+### 3️⃣ 检查代码规范
+\`/check\`
+```

package/src/skills/json-serialization/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: json-serialization
+description: |
+  当需要处理 JSON 序列化、反序列化、数据类型转换、日期处理、大数字精度保护时自动使用此 Skill。
+
+  触发场景：
+  - JSON 序列化/反序列化操作
+  - 大数字精度问题（Long/BigInteger/BigDecimal）
+  - 日期时间格式化与转换
+  - 复杂泛型类型转换
+  - JSON 格式验证
+  - 数据类型映射与转换
+
+  触发词：JSON、序列化、反序列化、JsonUtils、日期格式、精度、BigDecimal、Long、类型转换、JSON验证
+---
+
+# JSON 序列化与数据转换指南
+
+> 模块位置：`ruoyi-common/ruoyi-common-json`
+
+## 快速索引
+
+| 功能 | 方法/类 | 说明 |
+|------|---------|------|
+| 对象转 JSON | `JsonUtils.toJsonString()` | null 返回 null |
+| JSON 转对象 | `JsonUtils.parseObject()` | 空返回 null |
+| JSON 转 List | `JsonUtils.parseArray()` | 空返回空 ArrayList |
+| JSON 转 Dict | `JsonUtils.parseMap()` | 非 JSON 返回 null |
+| JSON 数组转 Dict 列表 | `JsonUtils.parseArrayMap()` | 空返回 null |
+| 复杂类型转换 | `JsonUtils.parseObject(text, TypeReference)` | 支持泛型 |
+| JSON 验证 | `JsonUtils.isJson()` / `isJsonObject()` / `isJsonArray()` | |
+| 字段校验注解 | `@JsonPattern` | 支持 OBJECT/ARRAY/ANY |
+
+---
+
+## 核心工具类 JsonUtils
+
+```java
+import org.dromara.common.json.utils.JsonUtils;
+```
+
+### 序列化
+
+```java
+// 对象转 JSON 字符串（null 返回 null）
+String json = JsonUtils.toJsonString(user);
+```
+
+### 反序列化
+
+```java
+// JSON 转简单对象（空返回 null）
+User user = JsonUtils.parseObject(json, User.class);
+
+// 字节数组转对象
+User user = JsonUtils.parseObject(bytes, User.class);
+
+// JSON 数组转 List（空返回空 ArrayList）
+List<User> users = JsonUtils.parseArray(json, User.class);
+
+// JSON 转 Dict（非 JSON 返回 null）
+Dict dict = JsonUtils.parseMap(json);
+String name = dict.getStr("name");
+int age = dict.getInt("age");
+
+// JSON 数组转 Dict 列表
+List<Dict> dicts = JsonUtils.parseArrayMap(json);
+```
+
+### 复杂泛型类型
+
+```java
+import com.fasterxml.jackson.core.type.TypeReference;
+
+// Map 类型
+Map<String, User> map = JsonUtils.parseObject(json,
+    new TypeReference<Map<String, User>>(){});
+
+// 嵌套泛型
+Map<String, List<User>> data = JsonUtils.parseObject(json,
+    new TypeReference<Map<String, List<User>>>(){});
+
+// 性能优化：缓存 TypeReference
+private static final TypeReference<List<User>> USER_LIST_TYPE =
+    new TypeReference<List<User>>(){};
+List<User> users = JsonUtils.parseObject(json, USER_LIST_TYPE);
+```
+
+### JSON 验证
+
+```java
+// 判断是否为合法 JSON（对象或数组）
+JsonUtils.isJson("{\"name\":\"张三\"}");   // true
+JsonUtils.isJson("[1,2,3]");              // true
+JsonUtils.isJson("not json");             // false
+
+// 判断是否为 JSON 对象
+JsonUtils.isJsonObject("{\"a\":1}");      // true
+JsonUtils.isJsonObject("[1,2,3]");        // false
+
+// 判断是否为 JSON 数组
+JsonUtils.isJsonArray("[1,2,3]");         // true
+JsonUtils.isJsonArray("{\"a\":1}");       // false
+```
+
+### 获取 ObjectMapper
+
+```java
+ObjectMapper mapper = JsonUtils.getObjectMapper();
+JsonNode node = mapper.readTree(json);
+```
+
+---
+
+## @JsonPattern 校验注解
+
+用于 BO 类字段的 JSON 格式校验。
+
+```java
+import org.dromara.common.json.validate.JsonPattern;
+import org.dromara.common.json.validate.JsonType;
+
+public class ConfigBo {
+
+    // 任意 JSON 格式（对象或数组）
+    @JsonPattern
+    private String configValue;
+
+    // 必须是 JSON 对象
+    @JsonPattern(type = JsonType.OBJECT, message = "配置必须是 JSON 对象格式")
+    private String objectConfig;
+
+    // 必须是 JSON 数组
+    @JsonPattern(type = JsonType.ARRAY, message = "列表必须是 JSON 数组格式")
+    private String arrayConfig;
+}
+```
+
+**JsonType 枚举**：
+
+| 值 | 说明 | 示例 |
+|----|------|------|
+| `ANY` | 对象或数组都可以（默认） | `{}` 或 `[]` |
+| `OBJECT` | 必须是 JSON 对象 | `{"a":1}` |
+| `ARRAY` | 必须是 JSON 数组 | `[1,2,3]` |
+
+---
+
+## Jackson 自动配置
+
+配置类：`org.dromara.common.json.config.JacksonConfig`
+
+### 大数字处理（BigNumberSerializer）
+
+**问题**：JavaScript 最大安全整数为 `2^53 - 1`（9007199254740991），超出范围会丢失精度。
+
+**解决方案**：自动将超出 JS 安全范围的数字序列化为字符串。
+
+```java
+// 安全范围内 → 保持数字
+Long id = 123456L;
+// 序列化结果：{"id": 123456}
+
+// 超出安全范围 → 转为字符串
+Long id = 9007199254740992L;
+// 序列化结果：{"id": "9007199254740992"}
+
+// BigDecimal 始终转为字符串
+BigDecimal amount = new BigDecimal("123.45");
+// 序列化结果：{"amount": "123.45"}
+```
+
+**处理规则**：
+
+| 类型 | 范围内 | 超出范围 |
+|------|--------|----------|
+| `Long` | 数字 | 字符串 |
+| `long` | 数字 | 字符串 |
+| `BigInteger` | 数字 | 字符串 |
+| `BigDecimal` | 字符串 | 字符串 |
+
+> **安全范围**：`-9007199254740991` ~ `9007199254740991`
+
+### LocalDateTime 格式化
+
+统一格式：`yyyy-MM-dd HH:mm:ss`
+
+```java
+LocalDateTime now = LocalDateTime.now();
+String json = JsonUtils.toJsonString(now);
+// 输出："2026-02-06 14:30:45"
+
+LocalDateTime parsed = JsonUtils.parseObject("\"2026-02-06 14:30:45\"", LocalDateTime.class);
+```
+
+### Date 自动解析（CustomDateDeserializer）
+
+使用 Hutool 的 `DateUtil.parse()` 自动识别多种日期格式：
+
+```java
+// 支持的格式（自动识别）
+Date d1 = JsonUtils.parseObject("\"2026-02-06 14:30:45\"", Date.class);
+Date d2 = JsonUtils.parseObject("\"2026-02-06\"", Date.class);
+Date d3 = JsonUtils.parseObject("\"2026/02/06 14:30:45\"", Date.class);
+Date d4 = JsonUtils.parseObject("\"20260206143045\"", Date.class);
+```
+
+---
+
+## 使用示例
+
+### Service 中的 JSON 操作
+
+```java
+@Service
+@RequiredArgsConstructor
+public class ConfigServiceImpl implements IConfigService {
+
+    private final ConfigMapper baseMapper;
+
+    /**
+     * 获取配置为对象
+     */
+    public <T> T getConfig(String configKey, Class<T> clazz) {
+        SysConfig config = baseMapper.selectOne(
+            Wrappers.<SysConfig>lambdaQuery()
+                .eq(SysConfig::getConfigKey, configKey));
+        if (config == null) {
+            return null;
+        }
+        return JsonUtils.parseObject(config.getConfigValue(), clazz);
+    }
+
+    /**
+     * 保存配置
+     */
+    public void saveConfig(String configKey, Object value) {
+        SysConfig config = new SysConfig();
+        config.setConfigKey(configKey);
+        config.setConfigValue(JsonUtils.toJsonString(value));
+        baseMapper.insert(config);
+    }
+
+    /**
+     * 导入 JSON 数据
+     */
+    public void importData(String jsonData) {
+        if (!JsonUtils.isJsonArray(jsonData)) {
+            throw new ServiceException("数据格式不正确，应为 JSON 数组");
+        }
+        List<DataBo> list = JsonUtils.parseArray(jsonData, DataBo.class);
+        // 处理数据...
+    }
+}
+```
+
+### BO 中使用 JSON 校验
+
+```java
+@Data
+@AutoMapper(target = SysConfig.class, reverseConvertGenerate = false)
+public class SysConfigBo extends BaseEntity {
+
+    @NotNull(message = "ID不能为空", groups = EditGroup.class)
+    private Long id;
+
+    @NotBlank(message = "配置键不能为空")
+    private String configKey;
+
+    @NotBlank(message = "配置值不能为空")
+    @JsonPattern(type = JsonType.OBJECT, message = "配置值必须是有效的 JSON 对象")
+    private String configValue;
+}
+```
+
+---
+
+## 常见问题
+
+### 1. 什么时候用 parseObject vs parseArray？
+
+```java
+// JSON 对象 → parseObject
+String json = "{\"name\":\"张三\"}";
+User user = JsonUtils.parseObject(json, User.class);
+
+// JSON 数组 → parseArray
+String json = "[{\"name\":\"张三\"},{\"name\":\"李四\"}]";
+List<User> users = JsonUtils.parseArray(json, User.class);
+```
+
+### 2. 泛型类型怎么处理？
+
+```java
+// ❌ 错误：泛型擦除，无法正确转换
+Map<String, User> map = JsonUtils.parseObject(json, Map.class);
+
+// ✅ 正确：使用 TypeReference
+Map<String, User> map = JsonUtils.parseObject(json,
+    new TypeReference<Map<String, User>>(){});
+```
+
+### 3. null 和空字符串的处理？
+
+```java
+// toJsonString
+JsonUtils.toJsonString(null);     // 返回 null
+JsonUtils.toJsonString(user);     // 返回 JSON 字符串
+
+// parseObject
+JsonUtils.parseObject(null, User.class);   // 返回 null
+JsonUtils.parseObject("", User.class);     // 返回 null
+
+// parseArray
+JsonUtils.parseArray(null, User.class);    // 返回空 ArrayList
+JsonUtils.parseArray("", User.class);      // 返回空 ArrayList
+```
+
+### 4. 如何在解析前验证 JSON？
+
+```java
+public void processData(String data) {
+    // 先验证再解析
+    if (!JsonUtils.isJsonArray(data)) {
+        throw new ServiceException("数据格式不正确");
+    }
+    List<User> users = JsonUtils.parseArray(data, User.class);
+}
+```
+
+---
+
+## 禁止事项
+
+```java
+// ❌ 禁止：频繁创建 ObjectMapper
+ObjectMapper mapper = new ObjectMapper();
+String json = mapper.writeValueAsString(user);
+
+// ✅ 正确：使用 JsonUtils
+String json = JsonUtils.toJsonString(user);
+
+// ❌ 禁止：不验证直接解析（可能报错）
+List<User> users = JsonUtils.parseArray(data, User.class);
+
+// ✅ 正确：先验证再解析
+if (JsonUtils.isJsonArray(data)) {
+    List<User> users = JsonUtils.parseArray(data, User.class);
+}
+
+// ❌ 禁止：泛型不使用 TypeReference
+Map map = JsonUtils.parseObject(json, Map.class);
+
+// ✅ 正确：使用 TypeReference
+Map<String, User> map = JsonUtils.parseObject(json,
+    new TypeReference<Map<String, User>>(){});
+```