leniu-dev 2.0.0

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

package/src/skills/leniu-api-development/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: leniu-api-development
+description: |
+  leniu-yunshitang-core 项目 API 接口开发规范。基于四层架构的 API 开发指南。
+
+  触发场景：
+  - 设计 leniu 项目 API 接口
+  - 编写 leniu Controller 层代码
+  - 配置接口权限和参数校验
+  - 接口返回值类型选择
+  - 多端路由规划（Web/Mobile/Android）
+
+  适用项目：leniu-tengyun-core（云食堂项目）
+
+  触发词：API接口、Controller、LeResult、LeResponse、LeRequest、接口开发、路由前缀、分页查询、接口权限
+---
+
+# leniu API 接口开发规范
+
+## HTTP 方法与路径规范
+
+| 操作 | HTTP 方法 | 路径示例 | 返回类型 |
+|------|---------|---------|---------|
+| 分页查询 | POST | `/query`, `/page-*` | `Page<VO>` / `PageVO<VO>` |
+| 获取详情 | POST/GET | `/{id}`, `/get-*`, `/info` | VO |
+| 新增 | POST | `/add` | `void` |
+| 修改 | POST/PUT | `/update`, `/modify-*` | `void` |
+| 删除 | DELETE/POST | `/delete`, `/batch/delete` | `void` |
+| 列表（不分页） | POST | `/list-all`, `/type-list` | `List<VO>` |
+| 导出 | POST | `/export`, `/export-async/*` | `void` |
+| 导入 | POST | `/import-excel` | `void` |
+| 树形查询 | POST | `/tree` | `List<Tree<Long>>` |
+
+---
+
+## Controller 标准模板
+
+```java
+@Api(tags = "模块-功能描述")
+@RestController
+@RequiresAuthentication
+@RequestMapping("/api/v2/web/module")
+public class XxxWebController {
+
+    @Autowired
+    private XxxBusiness xxxBusiness;
+
+    @PostMapping("/add")
+    @ApiOperation(value = "功能-新增")
+    public void add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {
+        xxxBusiness.add(request.getContent());
+    }
+
+    @PostMapping("/update")
+    @ApiOperation(value = "功能-修改")
+    public void update(@Validated(UpdateGroup.class) @RequestBody LeRequest<XxxDTO> request) {
+        xxxBusiness.update(request.getContent());
+    }
+
+    @PostMapping("/query")
+    @ApiOperation(value = "功能-分页查询")
+    public Page<XxxVO> query(@Validated @RequestBody LeRequest<XxxQueryParam> request) {
+        return xxxBusiness.page(request.getContent());
+    }
+
+    @PostMapping("/delete")
+    @ApiOperation(value = "功能-删除")
+    public void delete(@RequestBody LeRequest<Long> request) {
+        xxxBusiness.delete(request.getContent());
+    }
+}
+```
+
+---
+
+## 请求/响应封装
+
+### 请求：LeRequest<T>
+
+所有接口入参统一用 `LeRequest<T>` 包装，通过 `request.getContent()` 获取实际参数。
+
+```java
+@PostMapping("/query")
+public Page<XxxVO> query(@RequestBody LeRequest<XxxQueryParam> request) {
+    return xxxService.page(request.getContent());
+}
+```
+
+### 响应类型选择
+
+| 场景 | 返回类型 | 示例 |
+|------|---------|------|
+| 分页 | `Page<VO>` / `PageVO<VO>` | `return xxxService.page(param);` |
+| 单值包装 | `LeResponse<T>` | `return LeResponse.succ(value);` |
+| 复杂对象 | 直接返回 VO | `return xxxService.getDetail(id);` |
+| 报表+合计行 | `ReportBaseTotalVO<VO>` | `return service.pageSummary(param);` |
+| 写操作 | `void` | 无返回值 |
+
+```java
+// LeResponse 用法
+@PostMapping("/get-config")
+public LeResponse<String> getConfig(@RequestBody LeRequest<Long> request) {
+    return LeResponse.succ(xxxService.getConfig(request.getContent()));
+}
+```
+
+---
+
+## 参数校验
+
+### 分组校验（新增/修改区分）
+
+```java
+// 分组接口定义
+public interface InsertGroup {}
+public interface UpdateGroup {}
+
+// Controller 使用
+@PostMapping("/add")
+public void add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {}
+
+@PostMapping("/update")
+public void update(@Validated(UpdateGroup.class) @RequestBody LeRequest<XxxDTO> request) {}
+```
+
+### DTO 校验示例
+
+```java
+// 必须用 jakarta.validation（JDK 21）
+import jakarta.validation.constraints.*;
+
+@Data
+public class XxxDTO {
+    @NotNull(message = "ID不能为空", groups = {UpdateGroup.class})
+    private Long id;
+
+    @NotBlank(message = "名称不能为空", groups = {InsertGroup.class, UpdateGroup.class})
+    @Size(max = 100, message = "名称长度不能超过100个字符")
+    private String name;
+}
+```
+
+### 简单校验（无分组）
+
+```java
+@PostMapping("/query")
+public Page<XxxVO> query(@Validated @RequestBody LeRequest<XxxQueryParam> request) {}
+
+@PostMapping("/check")
+public LeResponse<Boolean> check(@Valid @RequestBody LeRequest<XxxDTO> request) {}
+```
+
+---
+
+## 认证注解
+
+| 注解 | 用途 | 包路径 |
+|------|------|--------|
+| `@RequiresAuthentication` | 需要登录（类/方法级） | `net.xnzn.framework.secure.filter.annotation` |
+| `@RequiresGuest` | 允许游客访问（方法级覆盖） | `net.xnzn.framework.secure.filter.annotation` |
+
+```java
+@RequiresAuthentication   // 类级别：所有方法默认需登录
+public class XxxController {
+
+    @RequiresGuest        // 方法级别覆盖：此接口游客可访问
+    @PostMapping("/public-list")
+    public List<XxxVO> publicList() {}
+}
+```
+
+---
+
+## 常见场景
+
+### 带 Redisson 分布式锁的导入
+
+```java
+@PostMapping("/import-excel")
+@ApiOperation(value = "Excel导入")
+public void importExcel(@RequestParam(value = "file") MultipartFile file) {
+    RLock lock = redissonClient.getLock("import:lock:" + TenantContextHolder.getTenantId());
+    if (!lock.tryLock(5, 60, TimeUnit.SECONDS)) {
+        throw new LeException("正在处理中，请稍后再试");
+    }
+    try {
+        xxxService.importExcel(file);
+    } finally {
+        if (lock.isLocked() && lock.isHeldByCurrentThread()) {
+            lock.unlock();
+        }
+    }
+}
+```
+
+### 批量删除
+
+```java
+@PutMapping("/batch/delete")
+@ApiOperation(value = "批量删除")
+public void batchDelete(@RequestBody LeRequest<List<Long>> request) {
+    xxxService.batchDelete(request.getContent());
+}
+```
+
+### 树形结构查询
+
+```java
+@PostMapping("/tree")
+@ApiOperation(value = "树形结构查询")
+public List<Tree<Long>> getTree(@RequestBody LeRequest<XxxQueryParam> request) {
+    return xxxService.getTree(request.getContent());
+}
+```
+
+### 同步导出
+
+```java
+@SneakyThrows
+@PostMapping("/export")
+@ApiOperation(value = "导出")
+public void export(@RequestBody LeRequest<XxxParam> request, HttpServletResponse response) {
+    XxxParam param = request.getContent();
+    List<XxxVO> list = xxxService.listAll(param);
+    EasyExcelUtil.writeExcelByDownLoadIncludeWrite(response, "文件名",
+            XxxVO.class, "标题", list, param.getExportCols());
+}
+```
+
+### 异步导出（大数据量）
+
+```java
+@PostMapping("/export-async/xxx")
+@ApiOperation(value = "异步导出")
+public void exportAsync(@RequestBody LeRequest<XxxParam> request) {
+    XxxParam param = request.getContent();
+    exportApi.startExcelExportTaskByPage(
+            "文件名", I18n.getMessage("title.key"),
+            XxxVO.class, param.getExportCols(), param.getPage(), null,
+            () -> PageVO.of(xxxService.listAll(param)));
+}
+```
+
+---
+
+## 路径命名规范
+
+| 模式 | 示例 | 说明 |
+|------|------|------|
+| 标准前缀 | `/api/v2/web/module` | 按端区分 |
+| 报表前缀 | `/summary/xxx` | 报表/统计类 |
+| 查询接口 | `/page/detail`, `/query` | 分页查询 |
+| 枚举接口 | `/type-list`, `/state-list` | 枚举数据 |
+| 导出接口 | `/export`, `/export-async/xxx` | 同步/异步 |
+| 导出 Controller 独立 | `XxxExportWebController` | 与查询分离 |
+
+---
+
+## 检查清单
+
+- [ ] 认证注解：`@RequiresAuthentication` 或 `@RequiresGuest`
+- [ ] 文档注解：`@Api` + `@ApiOperation`
+- [ ] 参数校验：`@Validated(InsertGroup/UpdateGroup.class)` 或 `@Valid`
+- [ ] 请求封装：`LeRequest<T>`
+- [ ] 返回类型：分页 `Page<VO>`、单值 `LeResponse<T>`、写操作 `void`
+- [ ] 路径命名：`/add`、`/update`、`/query`、`/delete`
+- [ ] 敏感操作加分布式锁
+- [ ] 跨模块依赖用 `@Lazy` 避免循环依赖
+
+---
+
+## 错误对比
+
+```java
+// ❌ 不使用参数封装
+public Long add(@RequestBody XxxDTO dto) {}
+// ✅ 使用 LeRequest
+public void add(@RequestBody LeRequest<XxxDTO> request) { xxxService.add(request.getContent()); }
+
+// ❌ 不使用分组校验
+public void add(@Valid @RequestBody LeRequest<XxxDTO> request) {}
+// ✅ 使用分组
+public void add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {}
+
+// ❌ javax.validation（JDK 21 必须 jakarta）
+import javax.validation.constraints.NotNull;
+// ✅
+import jakarta.validation.constraints.NotNull;
+
+// ❌ 缺少认证注解
+@RestController
+public class XxxController {}
+// ✅
+@RestController @RequiresAuthentication
+public class XxxController {}
+```
+
+---
+
+## 真实代码示例
+
+详见 `references/real-examples.md`，包含：
+- ReportAnalysisController（报表模块）
+- OrderInfoExportWebController（订单导出）
+- OrderInfoWebController（订单查询）
+- AttendanceLeaveInfoController（考勤请假）
+- AllocCanteenController（食堂档口）
+- MgrMenuController（菜单权限）
+
+---
+
+## 相关技能
+
+| 需要了解 | Skill |
+|---------|-------|
+| Service 层 | `leniu-service-development` |
+| Entity 设计 | `leniu-entity-design` |
+| 数据库设计 | `leniu-database-ops` |
+| CRUD 开发 | `leniu-crud-development` |