leniu-dev 2.0.0

package/.codex/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/.codex/skills/jenkins-deploy/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: jenkins-deploy
+description: |
+  Jenkins + Portainer 自动打包部署技能。通过 Python 脚本调用 Jenkins API 构建项目，并触发 Portainer Webhook/Update 完成容器更新。
+
+  触发场景：
+  - 需要将代码打包部署到 dev/test 环境
+  - 需要触发 Jenkins 构建 core 或 api 项目
+  - 需要更新 Portainer 容器服务
+  - 需要查看或修改构建配置（分支、环境、模式）
+  - 定制项目的打包部署
+
+  触发词：打包、部署、Jenkins、构建、Portainer、发布到dev、发布到test、更新环境、自动部署
+---
+
+# Jenkins + Portainer 自动打包部署
+
+## 架构
+
+```
+技能目录（随框架更新，不复制到项目）:
+  ~/.claude/skills/jenkins-deploy/assets/jk_build.py     ← 构建脚本
+
+全局配置（一次性配置，所有项目共享）:
+  ~/.claude/jenkins-config.json                           ← 凭证（Jenkins/Portainer）
+
+项目本地（自动生成）:
+  jenkins/last_cd_env.json                                ← 构建状态（环境、分支、模式）
+```
+
+脚本按 **本地 `.claude/` > 全局 `~/.claude/`** 优先级查找 `jenkins-config.json`。
+
+## 构建模式
+
+| 模式 | 说明 | 执行步骤 |
+|------|------|---------|
+| `0` | 只构建 | 构建 core + api，不更新 Portainer |
+| `1` | 全构建+更新 | 构建 core + api → 触发 Portainer 更新 |
+| `2` | 构建 api+更新 | 跳过 core，构建 api → 触发 Portainer 更新 |
+| `3` | 只更新 | 不构建，直接触发 Portainer 更新 |
+
+## 环境支持
+
+| 环境 | 前缀 | Portainer 更新方式 |
+|------|------|-------------------|
+| dev1~15 | `dev` | Webhook 触发 |
+| dev16~43 | `dev` | Force Update（xnzn-dev.xnzn.net） |
+| dev44+ | `dev` | 只支持模式 0（手动更新） |
+| test | `test` | Webhook 触发 |
+
+## 使用方式
+
+### 运行构建脚本
+
+```bash
+python ~/.claude/skills/jenkins-deploy/assets/jk_build.py
+```
+
+脚本交互式询问：模式 → 环境 → core 分支 → api 分支 → 定制工程文件夹
+
+### 通过 AI 辅助部署
+
+当用户说"打包到 devX"时：
+
+1. 读取 `jenkins/last_cd_env.json` 获取上次参数
+2. 确认参数：环境、分支、模式
+3. 修改 `jenkins/last_cd_env.json` 写入新参数
+4. 执行 `python ~/.claude/skills/jenkins-deploy/assets/jk_build.py`
+
+## 配置文件
+
+### jenkins-config.json（凭证，全局）
+
+位置：`~/.claude/jenkins-config.json`（或本地 `.claude/jenkins-config.json`）
+
+模板：`.claude/skills/jenkins-deploy/assets/env_param.template.json`
+
+> **注意**：此文件包含敏感凭证，不要将内容输出到对话中。
+
+### last_cd_env.json（构建状态，项目本地）
+
+位置：`jenkins/last_cd_env.json`（脚本自动创建，无需手动初始化）
+
+```json
+{
+  "build_mode": "1",
+  "cd_env": "dev1",
+  "core_param_branch": "master",
+  "api_param_branch": "master",
+  "api_param_folder": null
+}
+```
+
+## 定制项目
+
+指定 `api_param_folder` 后，Jenkins Job 路径变为：
+
+```
+{folder_name}/dev-后端-core
+{folder_name}/dev-后端-api
+```
+
+## 首次初始化（团队成员）
+
+只需一步：配置全局凭证文件。
+
+```bash
+# 方式 1：从团队成员拷贝
+cp /path/to/teammate/jenkins-config.json ~/.claude/jenkins-config.json
+
+# 方式 2：从模板创建，手动填写凭证
+cp ~/.claude/skills/jenkins-deploy/assets/env_param.template.json ~/.claude/jenkins-config.json
+# 然后替换 __JENKINS_*__ 和 __PORTAINER_*__ 占位符
+```
+
+### AI 初始化行为
+
+当技能被触发但 `jenkins-config.json` 不存在时：
+1. 提示"检测到尚未配置 Jenkins 凭证"
+2. 询问是否从模板创建
+3. 复制模板到 `~/.claude/jenkins-config.json`
+4. 提示用户填写凭证（或拷贝已有配置）
+
+## 依赖
+
+```bash
+pip install python-jenkins requests
+```
+
+## 注意
+
+- 本技能用于 dev/test 环境部署，**不涉及生产环境**
+- 如果是 Git 提交/分支管理，请使用 `git-workflow` 技能
+- 如果是代码构建错误排查，请使用 `bug-detective` 技能

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

@@ -0,0 +1,341 @@
+---
+name: json-serialization
+description: |
+  当需要处理 JSON 序列化、反序列化、数据类型转换、日期处理、大数字精度保护时自动使用此 Skill。
+
+  触发场景：
+  - JSON 序列化/反序列化操作
+  - 大数字精度问题（Long/BigInteger/BigDecimal）
+  - 日期时间格式化与转换
+  - 复杂泛型类型转换
+  - JSON 格式验证
+  - 数据类型映射与转换
+
+  触发词：JSON、序列化、反序列化、JsonUtils、日期格式、精度、BigDecimal、Long、类型转换、JSON验证、ObjectMapper、Jackson
+---
+
+# JSON 序列化与数据转换指南
+
+> 基于 Jackson（Spring Boot 默认 JSON 处理库）
+
+## 快速索引
+
+| 功能 | 方法/类 | 说明 |
+|------|---------|------|
+| 对象转 JSON | `JsonUtils.toJsonString()` | null 返回 null |
+| JSON 转对象 | `JsonUtils.parseObject()` | 空返回 null |
+| JSON 转 List | `JsonUtils.parseArray()` | 空返回空 ArrayList |
+| JSON 转 Map | `JsonUtils.parseMap()` | 非 JSON 返回 null |
+| 复杂类型转换 | `JsonUtils.parseObject(text, TypeReference)` | 支持泛型 |
+| JSON 验证 | `JsonUtils.isJson()` / `isJsonObject()` / `isJsonArray()` | |
+
+---
+
+## 核心工具类 JsonUtils（通用实现）
+
+> 推荐封装一个项目级的 `JsonUtils`，内部使用 Jackson `ObjectMapper` 单例。
+
+```java
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.core.type.TypeReference;
+
+public class JsonUtils {
+
+    private static final ObjectMapper MAPPER = SpringUtil.getBean(ObjectMapper.class);
+    // 或者：private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    public static String toJsonString(Object obj) {
+        if (obj == null) return null;
+        try {
+            return MAPPER.writeValueAsString(obj);
+        } catch (Exception e) {
+            throw new RuntimeException("JSON序列化失败", e);
+        }
+    }
+
+    public static <T> T parseObject(String json, Class<T> clazz) {
+        if (json == null || json.isBlank()) return null;
+        try {
+            return MAPPER.readValue(json, clazz);
+        } catch (Exception e) {
+            throw new RuntimeException("JSON反序列化失败", e);
+        }
+    }
+
+    public static <T> T parseObject(String json, TypeReference<T> typeRef) {
+        if (json == null || json.isBlank()) return null;
+        try {
+            return MAPPER.readValue(json, typeRef);
+        } catch (Exception e) {
+            throw new RuntimeException("JSON反序列化失败", e);
+        }
+    }
+
+    public static <T> List<T> parseArray(String json, Class<T> clazz) {
+        if (json == null || json.isBlank()) return new ArrayList<>();
+        try {
+            return MAPPER.readValue(json,
+                MAPPER.getTypeFactory().constructCollectionType(ArrayList.class, clazz));
+        } catch (Exception e) {
+            throw new RuntimeException("JSON反序列化失败", e);
+        }
+    }
+
+    public static boolean isJson(String str) {
+        return isJsonObject(str) || isJsonArray(str);
+    }
+
+    public static boolean isJsonObject(String str) {
+        if (str == null || str.isBlank()) return false;
+        return str.trim().startsWith("{") && str.trim().endsWith("}");
+    }
+
+    public static boolean isJsonArray(String str) {
+        if (str == null || str.isBlank()) return false;
+        return str.trim().startsWith("[") && str.trim().endsWith("]");
+    }
+
+    public static ObjectMapper getObjectMapper() {
+        return MAPPER;
+    }
+}
+```
+
+---
+
+## 序列化与反序列化
+
+### 基本用法
+
+```java
+// 对象转 JSON 字符串
+String json = JsonUtils.toJsonString(user);
+
+// JSON 转简单对象
+User user = JsonUtils.parseObject(json, User.class);
+
+// JSON 数组转 List
+List<User> users = JsonUtils.parseArray(json, User.class);
+```
+
+### 复杂泛型类型
+
+```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
+JsonUtils.isJson("{\"name\":\"test\"}");   // true
+JsonUtils.isJson("[1,2,3]");               // true
+JsonUtils.isJson("not json");              // false
+
+JsonUtils.isJsonObject("{\"a\":1}");       // true
+JsonUtils.isJsonArray("[1,2,3]");          // true
+```
+
+---
+
+## Jackson 自动配置
+
+### 推荐配置类
+
+```java
+@Configuration
+public class JacksonConfig {
+
+    @Bean
+    public Jackson2ObjectMapperBuilderCustomizer customizer() {
+        return builder -> {
+            // LocalDateTime 格式化
+            builder.simpleDateFormat("yyyy-MM-dd HH:mm:ss");
+            builder.serializers(new LocalDateTimeSerializer(
+                DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
+            builder.deserializers(new LocalDateTimeDeserializer(
+                DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
+
+            // 大数字精度保护
+            SimpleModule module = new SimpleModule();
+            module.addSerializer(Long.class, new BigNumberSerializer());
+            module.addSerializer(Long.TYPE, new BigNumberSerializer());
+            module.addSerializer(BigInteger.class, new BigNumberSerializer());
+            module.addSerializer(BigDecimal.class, ToStringSerializer.instance);
+            builder.modules(module);
+        };
+    }
+}
+```
+
+### 大数字处理（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"
+```
+
+---
+
+## 使用示例
+
+### Service 中的 JSON 操作
+
+```java
+@Service
+@RequiredArgsConstructor
+public class ConfigServiceImpl {
+
+    private final ConfigMapper configMapper;
+
+    /**
+     * 获取配置为对象
+     */
+    public <T> T getConfig(String configKey, Class<T> clazz) {
+        Config config = configMapper.selectOne(
+            Wrappers.<Config>lambdaQuery()
+                .eq(Config::getConfigKey, configKey));
+        if (config == null) {
+            return null;
+        }
+        return JsonUtils.parseObject(config.getConfigValue(), clazz);
+    }
+
+    /**
+     * 保存配置
+     */
+    public void saveConfig(String configKey, Object value) {
+        Config config = new Config();
+        config.setConfigKey(configKey);
+        config.setConfigValue(JsonUtils.toJsonString(value));
+        configMapper.insert(config);
+    }
+
+    /**
+     * 导入 JSON 数据
+     */
+    public void importData(String jsonData) {
+        if (!JsonUtils.isJsonArray(jsonData)) {
+            throw new [你的异常类]("数据格式不正确，应为 JSON 数组");
+        }
+        List<DataBo> list = JsonUtils.parseArray(jsonData, DataBo.class);
+        // 处理数据...
+    }
+}
+```
+
+---
+
+## 常见问题
+
+### 1. 什么时候用 parseObject vs parseArray？
+
+```java
+// JSON 对象 -> parseObject
+String json = "{\"name\":\"test\"}";
+User user = JsonUtils.parseObject(json, User.class);
+
+// JSON 数组 -> parseArray
+String json = "[{\"name\":\"test1\"},{\"name\":\"test2\"}]";
+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
+
+// parseObject
+JsonUtils.parseObject(null, User.class);   // 返回 null
+JsonUtils.parseObject("", User.class);     // 返回 null
+
+// parseArray
+JsonUtils.parseArray(null, User.class);    // 返回空 ArrayList
+JsonUtils.parseArray("", User.class);      // 返回空 ArrayList
+```
+
+---
+
+## 禁止事项
+
+```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>>(){});
+```