ai-engineering-init 1.4.2 → 1.5.0

package/.claude/skills/leniu-java-export/SKILL.md

@@ -8,65 +8,81 @@ description: |
   - 实现异步导出（数据量大时）
   - 实现分页导出（防内存溢出）
   - 导出API接口设计（@PostMapping("/export")）
-  - 实现同步导出（EasyExcelUtil）
 
   适用项目：
   - leniu-tengyun-core：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun-core
   - leniu-yunshitang：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun/leniu-yunshitang
 
-  触发词：导出、Excel导出、异步导出、分页导出、@ExcelProperty、exportApi、数据导出、EasyExcelUtil、导出列
+  触发词：导出、Excel导出、异步导出、分页导出、@ExcelProperty、exportApi、数据导出
 ---
 
-# leniu 数据导出规范
+# leniu-tengyun-core 数据导出规范
 
-## 核心组件
+## 项目特征
 
-| 组件 | 用途 |
+| 特征 | 说明 |
 |------|------|
-| `ExportApi` | 异步分页导出 |
-| `EasyExcelUtil` | 同步导出（直接返回文件流） |
-| `I18n.getMessage()` | 文件名国际化 |
-| `ReportBaseParam` | 基类（含 exportCols、page） |
-| `ReportConstant` | 报表常量（工作表名称等） |
+| 包名 | `net.xnzn.*` |
+| 异常类 | `LeException` |
+| 导出工具 | `ExportApi.startExcelExportTaskByPage()` |
+| 国际化 | `I18n.getMessage()` |
+| 工具类 | Hutool（CollUtil、BeanUtil 等） |
+| 请求包装 | `LeRequest<T>` |
+
+## 核心组件
+
+- **ExportApi**: 导出API接口
+- **EasyExcelUtil**: 同步导出工具（报表 Controller 直接使用）
+- **I18n**: 国际化工具
+- **PageDTO**: 分页参数
+- **ReportConstant**: 报表常量（工作表名称等）
 
 ## 两种导出模式
 
 | 模式 | 工具 | 适用场景 |
 |------|------|---------|
-| **同步导出** | `EasyExcelUtil.writeExcelByDownLoadIncludeWrite()` | 数据量不大，直接返回文件流 |
+| **同步导出** | `EasyExcelUtil.writeExcelByDownLoadIncludeWrite()` | 报表 Controller 直接返回文件流，数据量不大 |
 | **异步分页导出** | `exportApi.startExcelExportTaskByPage()` | 大数据量，任务队列方式 |
-| **异步(Feign)** | `orderClients.export().startExcelExportTaskByPage()` | 跨模块导出 |
+| **异步分页导出（Feign）** | `orderClients.export().startExcelExportTaskByPage()` | 跨模块导出，通过 Feign 客户端 |
 
----
-
-## 同步导出模板
+## 同步导出（EasyExcelUtil）
 
 ```java
 @ApiOperation(value = "流水汇总-同步导出")
 @PostMapping("/export")
-@SneakyThrows  // 必须加，EasyExcelUtil 抛受检异常
+@SneakyThrows
 public void export(@RequestBody LeRequest<ReportAnalysisTurnoverParam> request,
                    HttpServletResponse response) {
     ReportAnalysisTurnoverParam param = request.getContent();
+
+    // 1. 查询数据
     ReportBaseTotalVO<TurnoverVO> result = reportService.pageSummary(param);
 
+    // 2. 将列表 + 合计行合并（合计行追加到列表末尾）
     List<TurnoverVO> records = result.getResultPage().getRecords();
-    CollUtil.addAll(records, result.getTotalLine());  // 合计行追加到末尾
+    CollUtil.addAll(records, result.getTotalLine());  // 合计行是单个 VO 或 List
 
+    // 3. 直接写出文件流
     EasyExcelUtil.writeExcelByDownLoadIncludeWrite(
         response,
-        I18n.getMessage("report.turnover.title"),
-        TurnoverVO.class,
-        I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS),
-        records,
-        param.getExportCols()
+        I18n.getMessage("report.turnover.title"),  // 文件名（国际化）
+        TurnoverVO.class,                           // VO 类型
+        I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS), // 工作表名
+        records,                                    // 数据列表（含合计行）
+        param.getExportCols()                       // 导出列
     );
 }
 ```
 
----
+**注意事项**：
+- 方法签名必须加 `@SneakyThrows`（`EasyExcelUtil` 抛出受检异常）
+- `HttpServletResponse response` 作为方法参数接收
+- 合计行用 `CollUtil.addAll(records, totalLine)` 追加到列表末尾
+- 若合计行是单个 VO：`records.add(totalLine)` 即可
 
-## 异步分页导出模板
+## 异步分页导出
+
+### 基础导出模板
 
 ```java
 @ApiOperation(value = "xxx导出")
@@ -74,62 +90,105 @@ public void export(@RequestBody LeRequest<ReportAnalysisTurnoverParam> request,
 public void export(@RequestBody LeRequest<XxxPageParam> request) {
     XxxPageParam param = request.getContent();
 
-    // 合计行（可选）
+    // 获取合计行（可选）
     XxxVO totalLine = xxxService.getSummaryTotal(param);
 
+    // 启动异步导出任务
     exportApi.startExcelExportTaskByPage(
-        I18n.getMessage("report.xxx.title"),                  // 文件名（国际化）
-        I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS), // 工作表名
-        XxxVO.class,                                           // 数据类型
-        param.getExportCols(),                                // 导出列
-        param.getPage(),                                      // 分页参数
-        totalLine,                                            // 合计行（可为null）
-        () -> xxxService.pageList(param).getResultPage()      // 数据提供者
+        I18n.getMessage("report.xxx.title"),                          // 文件名（国际化）
+        I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS),         // 工作表名
+        XxxVO.class,                                                   // 数据类型
+        param.getExportCols(),                                        // 导出列
+        param.getPage(),                                              // 分页参数
+        totalLine,                                                    // 合计行（可为null）
+        () -> xxxService.pageList(param).getResultPage()              // 数据提供者
     );
 }
 ```
 
----
+### 实际项目示例
+
+```java
+@PostMapping("/purchase/order/export")
+@ApiOperation(value = "采购-采购订单汇总-导出")
+public void exportPurchaseOrder(@RequestBody LeRequest<MonitorPageParam> param) {
+    MonitorPageParam content = param.getContent();
+
+    // 1. 获取合计行
+    PurchaseOrderSummaryVO totalLine = monitorSafetyPurchaseService.getPurchaseOrderSummaryTotal(content);
+
+    // 2. 启动导出任务
+    exportApi.startExcelExportTaskByPage(
+        I18n.getMessage("school.purchase-order-summary"),              // 文件名（国际化）
+        I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS),         // 工作表名
+        PurchaseOrderSummaryVO.class,                                  // VO类型
+        content.getExportCols(),                                      // 导出列
+        content.getPage(),                                            // 分页参数
+        totalLine,                                                    // 合计行
+        () -> monitorSafetyPurchaseService.getPurchaseOrderSummary(content).getResultPage()
+    );
+}
+```
 
-## 跨模块导出（Feign 客户端）
+## 异步分页导出（Feign 客户端模式）
+
+跨模块导出时，通过 Feign 客户端调用目标模块的导出接口。订单模块导出是典型示例：
 
 ```java
+/**
+ * 订单导出 Controller（独立拆分，避免与主 Controller 耦合）
+ */
 @Slf4j
 @Api(tags = "订单导出")
 @RestController
 @RequestMapping("/web/order/export")
 public class OrderInfoExportWebController {
 
-    @Autowired @Lazy  // @Lazy 防循环依赖
+    // ✅ 跨模块依赖：通过 Feign 客户端调用，@Lazy 避免循环依赖
+    @Autowired
+    @Lazy
     private OrderClients orderClients;
 
     @ApiOperation(value = "订单导出")
     @PostMapping("/start")
     public void export(@RequestBody LeRequest<OrderDetailWebDTO> request) {
         OrderDetailWebDTO dto = request.getContent();
+
+        // 转换为内部查询参数
         OrderSearchParam searchParam = dto.convertToOrderSearchParam();
 
+        // 通过 Feign 客户端启动异步导出任务
         orderClients.export().startExcelExportTaskByPage(
-            I18n.getMessage("order.export.title"),
-            I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS),
-            OrderDetailVO.class,
-            dto.getExportCols(),
-            dto.getPage(),
-            null,
-            () -> orderClients.order().pageOrder(searchParam)
+            I18n.getMessage("order.export.title"),                      // 文件名
+            I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS),       // 工作表名
+            OrderDetailVO.class,                                        // VO 类型
+            dto.getExportCols(),                                        // 导出列
+            dto.getPage(),                                              // 分页参数
+            null,                                                       // 无合计行
+            () -> orderClients.order().pageOrder(searchParam)           // Lambda 提供数据
         );
     }
 }
 ```
 
----
+**独立 Export Controller 的优点**：
+- 将导出逻辑与查询逻辑解耦
+- 避免单个 Controller 过于庞大
+- `@Autowired @Lazy` 防止 Spring 循环依赖
+
+## VO类导出注解
 
-## VO 类导出注解
+### 使用@ExcelProperty
+
+> ⚠️ **金额字段必须使用 `converter = CustomNumberConverter.class`，禁止用 `@NumberFormat`！**
 
 ```java
+import net.xnzn.core.common.export.converter.CustomNumberConverter;
+
 @Data
 @ApiModel("xxx导出VO")
 public class XxxVO {
+
     @ExcelProperty(value = "ID", index = 0)
     @ApiModelProperty("ID")
     private Long id;
@@ -138,139 +197,374 @@ public class XxxVO {
     @ApiModelProperty("名称")
     private String name;
 
-    @ExcelProperty(value = "金额（元）", index = 2)
-    @NumberFormat("#,##0.00")
+    @ExcelProperty(value = "状态", index = 2)
+    @ApiModelProperty("状态")
+    private String statusDesc;
+
+    // ✅ 金额字段：必须用 CustomNumberConverter，框架自动完成分→元转换
+    @ExcelProperty(value = "金额（元）", index = 3, converter = CustomNumberConverter.class)
+    @ApiModelProperty("金额（分）")
     private BigDecimal amount;
 
-    @ExcelProperty(value = "创建时间", index = 3)
+    @ExcelProperty(value = "创建时间", index = 4)
+    @ApiModelProperty("创建时间")
     @DateTimeFormat("yyyy-MM-dd HH:mm:ss")
     private LocalDateTime createTime;
 }
 ```
 
----
+## 导出参数类
+
+### PageParam包含导出列
+
+```java
+@Data
+@ApiModel("xxx分页查询参数")
+public class XxxPageParam extends ReportBaseParam {
+
+    @ApiModelProperty(value = "查询条件")
+    private String keyword;
 
-## Service 层：导出时不分页
+    // 其他查询条件...
+    // 导出列 exportCols 和分页 page 已在 ReportBaseParam 基类中定义
+}
+```
+
+## Service层导出逻辑
+
+### 导出时不分页
 
 ```java
 public PageVO<XxxVO> pageList(XxxPageParam param) {
+    // 导出时不分页，查询全部数据
     if (CollUtil.isNotEmpty(param.getExportCols())) {
-        // 导出时不分页，不调用 PageMethod.startPage()
+        // 不调用 PageMethod.startPage()
         List<XxxEntity> records = mapper.selectList(param);
-        return PageVO.of(BeanUtil.copyToList(records, XxxVO.class));
+        List<XxxVO> voList = BeanUtil.copyToList(records, XxxVO.class);
+        return PageVO.of(voList);
     }
-    // 正常分页
+
+    // 正常分页查询
     PageMethod.startPage(param);
     List<XxxEntity> records = mapper.pageList(param);
-    return PageVO.of(BeanUtil.copyToList(records, XxxVO.class));
+    List<XxxVO> voList = BeanUtil.copyToList(records, XxxVO.class);
+    return PageVO.of(voList);
 }
 ```
 
-## 带合计行的导出 Service
+### 带合计行的导出
 
 ```java
+// ⚠️ 系统默认在商户库执行，业务查询无需 Executors.readInSystem()
+// Executors.readInSystem() 仅用于需要访问系统库的场景（如全局配置、商户管理）
+
 public ReportBaseTotalVO<XxxVO> pageWithTotal(XxxPageParam param) {
     ReportBaseTotalVO<XxxVO> result = new ReportBaseTotalVO<>();
 
-    // 导出时不查合计行（避免性能开销）
+    // 1. 导出时不查询合计行（避免不必要的性能开销）
     if (CollUtil.isEmpty(param.getExportCols())) {
-        result.setTotalLine(mapper.getSummaryTotal(param));
+        XxxVO totalLine = mapper.getSummaryTotal(param);
+        result.setTotalLine(totalLine);
     }
 
+    // 2. 导出时不分页
     if (CollUtil.isNotEmpty(param.getExportCols())) {
-        result.setResultPage(PageVO.of(mapper.getSummaryList(param)));
+        List<XxxVO> list = mapper.getSummaryList(param);
+        result.setResultPage(PageVO.of(list));
     } else {
+        // 正常分页查询
         PageMethod.startPage(param);
-        result.setResultPage(PageVO.of(mapper.getSummaryList(param)));
+        List<XxxVO> list = mapper.getSummaryList(param);
+        result.setResultPage(PageVO.of(list));
     }
+
     return result;
 }
 ```
 
----
-
 ## 导出文件名国际化
 
-```properties
-# resources/message_zh.properties
+### 使用I18n
+
+```java
+// 在 resources/message_zh.properties 中定义
 report.order.title=订单报表
-# resources/message_en.properties
+report.order.sheet=订单明细
+
+// 在 resources/message_en.properties 中定义
 report.order.title=Order Report
+report.order.sheet=Order Details
+
+// 在代码中使用
+exportApi.startExcelExportTaskByPage(
+    I18n.getMessage("report.order.title"),   // 订单报表
+    I18n.getMessage("report.order.sheet"),   // 订单明细
+    OrderVO.class,
+    param.getExportCols(),
+    param.getPage(),
+    totalLine,
+    () -> orderService.pageList(param).getResultPage()
+);
+```
+
+## 导出列控制
+
+### 前端传递导出列
+
+```json
+{
+  "page": {
+    "current": 1,
+    "size": 10
+  },
+  "exportCols": ["id", "name", "status", "amount", "createTime"],
+  "keyword": "test"
+}
 ```
 
+### 后端处理导出列
+
 ```java
-I18n.getMessage("report.order.title")  // 根据当前语言自动返回
+@PostMapping("/export")
+public void export(@RequestBody LeRequest<XxxPageParam> request) {
+    XxxPageParam param = request.getContent();
+
+    // 校验导出列
+    if (CollUtil.isEmpty(param.getExportCols())) {
+        throw new LeException("导出列不能为空");
+    }
+
+    // 启动导出任务
+    exportApi.startExcelExportTaskByPage(
+        I18n.getMessage("report.xxx.title"),
+        I18n.getMessage("report.xxx.sheet"),
+        XxxVO.class,
+        param.getExportCols(),   // 传递导出列
+        param.getPage(),
+        null,
+        () -> xxxService.pageList(param).getResultPage()
+    );
+}
 ```
 
----
+## 导出数据转换
 
-## 导出列控制
+### 状态码转换为描述（使用BeanUtil）
 
-前端传递：
-```json
-{ "exportCols": ["id", "name", "status", "amount"], "page": { "current": 1, "size": 10 } }
+```java
+public PageVO<XxxVO> pageList(XxxPageParam param) {
+    PageMethod.startPage(param);
+    List<XxxEntity> records = mapper.pageList(param);
+
+    // 转换为VO并处理状态描述（leniu 使用 BeanUtil，不用 MapstructUtils）
+    List<XxxVO> voList = records.stream()
+            .map(entity -> {
+                XxxVO vo = new XxxVO();
+                BeanUtil.copyProperties(entity, vo);
+
+                // 状态码转换为描述
+                vo.setStatusDesc(StatusEnum.getByCode(entity.getStatus()).getDesc());
+
+                return vo;
+            })
+            .collect(Collectors.toList());
+
+    return PageVO.of(voList);
+}
 ```
 
-后端校验：
+## 常见场景
+
+### 场景1：订单导出
+
 ```java
-if (CollUtil.isEmpty(param.getExportCols())) {
-    throw new LeException("导出列不能为空");
+@ApiOperation(value = "订单导出")
+@PostMapping("/export")
+public void export(@RequestBody LeRequest<OrderPageParam> request) {
+    OrderPageParam param = request.getContent();
+
+    log.info("【导出】订单导出，条件:{}", param);
+
+    // 获取合计行
+    OrderVO totalLine = orderService.getSummaryTotal(param);
+
+    // 启动导出任务
+    exportApi.startExcelExportTaskByPage(
+        I18n.getMessage("report.order.title"),
+        I18n.getMessage("report.order.sheet"),
+        OrderVO.class,
+        param.getExportCols(),
+        param.getPage(),
+        totalLine,
+        () -> orderService.pageList(param).getResultPage()
+    );
 }
 ```
 
----
+### 场景2：报表导出
 
-## 带权限过滤的导出
+```java
+@ApiOperation(value = "销售报表导出")
+@PostMapping("/export")
+public void export(@RequestBody LeRequest<SalesReportParam> request) {
+    SalesReportParam param = request.getContent();
+
+    log.info("【导出】销售报表导出，日期范围:{} - {}",
+             param.getStartDate(), param.getEndDate());
+
+    // 获取合计行
+    SalesReportVO totalLine = reportService.getSummaryTotal(param);
+
+    // 启动导出任务
+    exportApi.startExcelExportTaskByPage(
+        I18n.getMessage("report.sales.title"),
+        I18n.getMessage("report.sales.sheet"),
+        SalesReportVO.class,
+        param.getExportCols(),
+        param.getPage(),
+        totalLine,
+        () -> reportService.getSummary(param).getResultPage()
+    );
+}
+```
+
+### 场景3：带权限过滤的导出
 
 ```java
+@ApiOperation(value = "数据导出")
 @PostMapping("/export")
 public void export(@RequestBody LeRequest<DataPageParam> request) {
     DataPageParam param = request.getContent();
+
+    // 获取用户权限
     MgrUserAuthPO authPO = mgrAuthApi.getUserAuthPO();
     ReportDataPermissionParam dataPermission =
         reportDataPermissionService.getDataPermission(authPO);
 
+    log.info("【导出】数据导出，用户:{}, 权限范围:{}",
+             authPO.getUserId(), dataPermission.getCanteenIds());
+
+    // 启动导出任务（权限过滤在Service层处理）
     exportApi.startExcelExportTaskByPage(
         I18n.getMessage("report.data.title"),
         I18n.getMessage("report.data.sheet"),
-        DataVO.class, param.getExportCols(), param.getPage(), null,
+        DataVO.class,
+        param.getExportCols(),
+        param.getPage(),
+        null,
         () -> dataService.pageList(param).getResultPage()
     );
 }
 ```
 
----
+## 导出性能优化
 
-## 导出数据脱敏
+### 1. 限制导出数量
 
 ```java
-// 在 VO 转换时处理
-if (CollUtil.isNotEmpty(param.getExportCols())) {
-    vo.setMobile(maskMobile(user.getMobile()));
-    vo.setIdCard(maskIdCard(user.getIdCard()));
+@PostMapping("/export")
+public void export(@RequestBody LeRequest<XxxPageParam> request) {
+    XxxPageParam param = request.getContent();
+
+    // 查询总数
+    long total = xxxService.count(param);
+
+    // 限制导出数量
+    if (total > 100000) {
+        throw new LeException("导出数据量过大，请缩小查询范围");
+    }
+
+    // 启动导出任务
+    exportApi.startExcelExportTaskByPage(
+        I18n.getMessage("report.xxx.title"),
+        I18n.getMessage("report.xxx.sheet"),
+        XxxVO.class,
+        param.getExportCols(),
+        param.getPage(),
+        null,
+        () -> xxxService.pageList(param).getResultPage()
+    );
 }
 ```
 
----
+### 2. 导出数据脱敏
+
+```java
+public PageVO<UserVO> pageList(UserPageParam param) {
+    PageMethod.startPage(param);
+    List<User> records = mapper.pageList(param);
 
-## 导出数量限制
+    List<UserVO> voList = records.stream()
+            .map(user -> {
+                UserVO vo = new UserVO();
+                BeanUtil.copyProperties(user, vo);
+
+                // 导出时脱敏
+                if (CollUtil.isNotEmpty(param.getExportCols())) {
+                    vo.setMobile(maskMobile(user.getMobile()));
+                    vo.setIdCard(maskIdCard(user.getIdCard()));
+                }
+
+                return vo;
+            })
+            .collect(Collectors.toList());
+
+    return PageVO.of(voList);
+}
+```
+
+## 最佳实践
+
+### 1. 导出日志
 
 ```java
-long total = xxxService.count(param);
-if (total > 100000) {
-    throw new LeException("导出数据量过大，请缩小查询范围");
+@PostMapping("/export")
+public void export(@RequestBody LeRequest<XxxPageParam> request) {
+    XxxPageParam param = request.getContent();
+
+    log.info("【导出】开始导出，文件名:{}, 条件:{}",
+             I18n.getMessage("report.xxx.title"), param);
+
+    exportApi.startExcelExportTaskByPage(
+        I18n.getMessage("report.xxx.title"),
+        I18n.getMessage("report.xxx.sheet"),
+        XxxVO.class,
+        param.getExportCols(),
+        param.getPage(),
+        null,
+        () -> xxxService.pageList(param).getResultPage()
+    );
+
+    log.info("【导出】导出任务已启动");
 }
 ```
 
----
+### 2. 导出权限校验
+
+```java
+@PostMapping("/export")
+public void export(@RequestBody LeRequest<XxxPageParam> request) {
+    // 校验导出权限
+    if (!hasExportPermission()) {
+        throw new LeException("无导出权限");
+    }
+
+    // 启动导出任务
+    exportApi.startExcelExportTaskByPage(...);
+}
+```
 
 ## 常见错误
 
-| 错误写法 | 正确写法 |
-|---------|---------|
-| `throw new ServiceException("msg")` | `throw new LeException("msg")` |
-| `MapstructUtils.convert(a, B.class)` | `BeanUtil.copyProperties(a, b)` |
-| `@RequestParam` 接收请求 | `@RequestBody LeRequest<T>` |
-| `import javax.validation.*` | `import jakarta.validation.*` |
-| 不写导出日志 | `log.info("【导出】开始导出...")` |
-| 同步导出不加 `@SneakyThrows` | 必须加（受检异常） |
+| 错误写法 | 正确写法 | 说明 |
+|---------|---------|------|
+| `throw new ServiceException("msg")` | `throw new LeException("msg")` | leniu 项目异常类 |
+| `MapstructUtils.convert(a, B.class)` | `BeanUtil.copyProperties(a, b)` | leniu 使用 Hutool |
+| `@RequestParam` 接收请求 | `@RequestBody LeRequest<T>` | leniu 接口使用 LeRequest 包装 |
+| `import javax.validation.*` | `import jakarta.validation.*` | JDK 21 + Spring Boot 3.x |
+| 不写导出日志 | 写 log.info 记录导出参数 | 便于排查导出问题 |
+| ⛔ `@NumberFormat("#,##0.00")` 用于金额字段 | ✅ `@ExcelProperty(converter = CustomNumberConverter.class)` | `@NumberFormat` 无法完成分→元转换，框架的 `CustomNumberConverter` 才能自动处理 |
+| ⛔ `mapFunc` 参数手动做分→元转换 | ✅ VO 字段加 `converter = CustomNumberConverter.class` | 金额转换在 VO 注解层处理，不在 `startExcelExportTaskByPage` 的 mapFunc 里做 |
+| ⛔ 手写 `EasyExcel.write()` + `List<List<Object>>` | ✅ 使用 `exportApi.startExcelExportTaskByPage()` | 禁止手动拼接行列数据 |
+| ⛔ Service 里手动创建临时 File + `exportApi.createRecord()` | ✅ 使用 `exportApi.startExcelExportTaskByPage()` | 统一使用标准异步分页导出接口 |
+| ⛔ VO 无 `@ExcelProperty` 注解 | ✅ 每个导出字段必须加 `@ExcelProperty("列头")` | 无注解字段不会被导出 |