ai-engineering-init 1.1.0

package/.cursor/skills/git-workflow/SKILL.md

@@ -0,0 +1,375 @@
+---
+name: git-workflow
+description: |
+  当需要进行 Git 版本控制操作时自动使用此 Skill。
+
+  触发场景：
+  - 提交代码
+  - 创建/合并分支
+  - 查看提交历史
+  - 解决冲突
+  - 回滚代码
+
+  触发词：git、提交、commit、分支、合并、push、pull、冲突、回滚、版本、历史
+---
+
+# Git 工作流指南
+
+## ⚠️ 本项目提交规范（必须遵守）
+
+### 核心原则
+
+1. **只提交当前会话的改动**：只 `git add` 当前聊天中修改或新增的文件
+2. **不提交配置文件**：排除 `.env*`、`application*.yml` 等配置
+3. **默认只提交到本地**：执行 `git add` + `git commit`，**不自动 push**
+4. **明确指定才推送**：只有用户明确说"推送"、"push"、"提交到远程"时才执行 `git push`
+
+### 提交信息格式
+
+```
+<type>(<scope>): <subject>
+```
+
+> **注意**：本项目是纯后端项目，无需平台前缀。
+
+### 提交示例
+
+```bash
+# 新功能
+feat(system): 新增用户反馈功能
+
+# 修复 Bug
+fix(demo): 修复订单状态显示错误
+
+# 文档更新
+docs(readme): 更新安装说明
+
+# 重构
+refactor(common): 重构分页查询工具类
+
+# 性能优化
+perf(system): 优化用户列表查询性能
+
+# 测试
+test(demo): 添加单元测试
+```
+
+### 提交流程
+
+```bash
+# 1. 查看当前改动
+git status
+
+# 2. 只添加当前会话修改的业务文件（排除配置）
+git add ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/xxx/
+# 或者添加具体文件
+git add path/to/file1.java path/to/file2.java
+
+# 3. 提交到本地（不 push！）
+git commit -m "feat(system): 新增xxx功能"
+
+# 4. 只有用户明确要求时才推送
+# git push  # ← 用户说"推送"时才执行
+```
+
+### 不要提交的文件
+
+```bash
+# ❌ 配置文件（绝对不提交）
+ruoyi-admin/src/main/resources/application.yml
+ruoyi-admin/src/main/resources/application-*.yml
+ruoyi-common/**/resources/*.yml
+
+# ❌ IDE 配置
+.idea/
+.vscode/
+*.iml
+
+# ❌ 本地临时文件
+*.log
+target/
+logs/
+```
+
+---
+
+## 提交类型说明
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| feat | 新功能 | `feat(system): 新增用户反馈功能` |
+| fix | 修复Bug | `fix(demo): 修复订单状态显示错误` |
+| docs | 文档更新 | `docs(readme): 更新安装说明` |
+| style | 代码格式 | `style(system): 格式化代码` |
+| refactor | 重构 | `refactor(common): 重构用户模块` |
+| perf | 性能优化 | `perf(system): 优化查询性能` |
+| test | 测试 | `test(demo): 添加单元测试` |
+| chore | 构建/工具 | `chore: 更新依赖` |
+
+### scope 常用范围
+
+| scope | 说明 | 对应模块 |
+|-------|------|----------|
+| system | 系统管理 | `ruoyi-modules/ruoyi-system/` |
+| demo | 演示模块 | `ruoyi-modules/ruoyi-demo/` |
+| workflow | 工作流 | `ruoyi-modules/ruoyi-workflow/` |
+| job | 定时任务 | `ruoyi-modules/ruoyi-job/` |
+| generator | 代码生成 | `ruoyi-modules/ruoyi-generator/` |
+| common | 通用模块 | `ruoyi-common/` |
+| admin | 启动模块 | `ruoyi-admin/` |
+
+---
+
+## 常用命令
+
+### 基础操作
+
+```bash
+# 查看状态
+git status
+
+# 查看改动
+git diff
+git diff --staged  # 已暂存的改动
+
+# 添加文件
+git add .          # 添加所有（谨慎使用！）
+git add <file>     # 添加指定文件（推荐）
+
+# 提交
+git commit -m "提交信息"
+
+# 推送（需用户明确要求）
+git push
+git push -u origin <branch>  # 首次推送并设置上游
+```
+
+### 分支操作
+
+```bash
+# 查看分支
+git branch         # 本地分支
+git branch -r      # 远程分支
+git branch -a      # 所有分支
+
+# 创建分支
+git branch <name>
+git checkout -b <name>  # 创建并切换
+
+# 切换分支
+git checkout <name>
+git switch <name>
+
+# 合并分支
+git merge <name>
+
+# 删除分支
+git branch -d <name>     # 删除本地
+git push origin -d <name>  # 删除远程
+```
+
+### 历史查看
+
+```bash
+# 查看提交历史
+git log
+git log --oneline
+git log --oneline -10  # 最近10条
+
+# 查看某文件历史
+git log --follow <file>
+
+# 查看某次提交的内容
+git show <commit-id>
+```
+
+### 撤销操作
+
+```bash
+# 撤销工作区修改
+git checkout -- <file>
+git restore <file>
+
+# 撤销暂存
+git reset HEAD <file>
+git restore --staged <file>
+
+# 撤销提交（保留修改）
+git reset --soft HEAD^
+
+# 撤销提交（丢弃修改）
+git reset --hard HEAD^
+
+# 回滚到某个提交
+git reset --hard <commit-id>
+```
+
+---
+
+## 分支策略
+
+### 主要分支
+
+| 分支 | 用途 | 说明 |
+|------|------|------|
+| 5.X | 主分支 | 生产/发布代码（本项目主分支） |
+| dev | 开发分支 | 日常开发代码 |
+| feature/* | 功能分支 | 新功能开发 |
+| fix/* | 修复分支 | Bug修复 |
+| release/* | 发布分支 | 版本发布 |
+
+### 工作流程
+
+```bash
+# 1. 从 dev 创建功能分支
+git checkout dev
+git pull
+git checkout -b feature/user-feedback
+
+# 2. 开发并提交（只提交当前会话改动的业务文件）
+git add ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/feedback/
+git commit -m "feat(system): 新增用户反馈功能"
+
+# 3. 用户明确要求时才推送到远程
+git push -u origin feature/user-feedback
+
+# 4. 创建 Pull Request 合并到 dev
+
+# 5. 合并后删除功能分支
+git checkout dev
+git pull
+git branch -d feature/user-feedback
+```
+
+---
+
+## 冲突解决
+
+### 合并冲突
+
+```bash
+# 1. 拉取最新代码
+git pull
+
+# 2. 如果有冲突，Git 会提示
+# Auto-merging xxx.java
+# CONFLICT (content): Merge conflict in xxx.java
+
+# 3. 打开冲突文件，手动解决
+# <<<<<<< HEAD
+# 当前分支的代码
+# =======
+# 要合并的代码
+# >>>>>>> feature/xxx
+
+# 4. 解决后添加并提交
+git add .
+git commit -m "fix: 解决合并冲突"
+```
+
+### 变基冲突
+
+```bash
+# 1. 变基
+git rebase dev
+
+# 2. 如果有冲突，解决后
+git add .
+git rebase --continue
+
+# 3. 放弃变基
+git rebase --abort
+```
+
+---
+
+## 实用技巧
+
+### 暂存修改
+
+```bash
+# 暂存当前修改
+git stash
+
+# 查看暂存列表
+git stash list
+
+# 恢复暂存
+git stash pop        # 恢复并删除
+git stash apply      # 恢复但保留
+
+# 删除暂存
+git stash drop
+git stash clear      # 清空所有
+```
+
+### 修改提交
+
+```bash
+# 修改最后一次提交信息
+git commit --amend -m "新的提交信息"
+
+# 追加到最后一次提交
+git add .
+git commit --amend --no-edit
+```
+
+### Cherry-pick
+
+```bash
+# 把某个提交应用到当前分支
+git cherry-pick <commit-id>
+```
+
+### 查看某人的提交
+
+```bash
+git log --author="作者名"
+```
+
+---
+
+## 注意事项
+
+### 禁止操作
+
+1. **不要强制推送到主分支**
+   ```bash
+   # ❌ 禁止
+   git push --force origin 5.X
+   ```
+
+2. **不要在主分支直接开发**
+   ```bash
+   # ❌ 禁止
+   git checkout 5.X
+   # 直接修改代码...
+   ```
+
+3. **不要提交敏感信息和配置文件**
+   ```bash
+   # ❌ 禁止提交
+   application.yml
+   application-dev.yml
+   application-prod.yml
+   credentials.json
+   password.txt
+   ```
+
+4. **不要自动 push（除非用户明确要求）**
+   ```bash
+   # ❌ 默认不执行
+   git push
+
+   # ✅ 只有用户说"推送到远程"时才执行
+   git push
+   ```
+
+### 最佳实践
+
+1. **只提交当前会话改动**：不要 `git add .`，精确添加修改的文件
+2. **排除配置文件**：配置文件包含本地环境信息，不应提交
+3. **清晰的提交信息**：包含类型 + 范围 + 描述
+4. **默认只本地提交**：`git add` + `git commit`，不自动 push
+5. **频繁小步提交**：便于追踪和回滚
+6. **Code Review**：通过 PR 合并代码

package/.cursor/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>>(){});
+```