ai-engineering-init 1.4.3 → 1.5.0

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` |

package/src/skills/leniu-api-development/references/real-examples.md

@@ -0,0 +1,273 @@
+# leniu API 真实代码示例
+
+## 示例1：ReportAnalysisController（报表模块典型 Controller）
+
+```java
+@RestController
+@RequestMapping("/summary/analysis")
+@Api(value = "报表中心/经营分析", tags = "报表/经营分析-新")
+public class ReportAnalysisController {
+
+    @Autowired
+    @Lazy
+    protected ExportApi exportApi;             // 跨模块依赖用 @Lazy 避免循环依赖
+    @Autowired
+    private ReportAnalysisTurnoverService reportAnalysisTurnoverService;
+
+    // 报表查询：返回直接 VO 对象
+    @ApiOperation(value = "营业分析-总营业额")
+    @PostMapping("/turnover/total")
+    public ReportTurnoverPO getTurnoverTotal(@RequestBody LeRequest<ReportAnalysisTurnoverParam> request) {
+        return reportAnalysisTurnoverService.getTurnoverTotal(request.getContent());
+    }
+
+    // 报表分页：返回 ReportBaseTotalVO（含合计行）
+    @ApiOperation(value = "营业分析-营业额报表")
+    @PostMapping("/turnover/detail")
+    public ReportBaseTotalVO<ReportAnalysisTurnoverDetailVO> getTurnoverDetail(
+            @RequestBody LeRequest<ReportAnalysisTurnoverParam> request) {
+        return reportAnalysisTurnoverService.getTurnoverDetail(request.getContent());
+    }
+
+    // 同步导出（小数据量）
+    @SneakyThrows
+    @ApiOperation(value = "食堂满意度统计导出")
+    @PostMapping("/evaluate/export")
+    public void exportEvaluateSummary(@RequestBody LeRequest<ReportAnalysisEvaluateParam> request,
+                                       HttpServletResponse response) {
+        ReportAnalysisEvaluateParam param = request.getContent();
+        ReportBaseTotalVO<ReportAnalysisEvaluateVO> result = reportAnalysisEvaluateService.pageSummary(param);
+        List<ReportAnalysisEvaluateVO> list = (List<ReportAnalysisEvaluateVO>)
+                CollUtil.addAll(result.getResultPage().getRecords(), result.getTotalLine());
+        EasyExcelUtil.writeExcelByDownLoadIncludeWrite(response, "文件",
+                ReportAnalysisEvaluateVO.class, ReportConstant.REPORT_TITLE_DETAILS, list, param.getExportCols());
+    }
+
+    // 异步导出（大数据量）
+    @ApiOperation(value = "异步导出菜品销售排行")
+    @PostMapping("/export-async/dishes/sale/export")
+    public void exportDishesSaleSummary(@RequestBody LeRequest<ReportAnalysisDishesSaleParam> request) {
+        ReportAnalysisDishesSaleParam param = request.getContent();
+        ReportBaseTotalVO<ReportAnalysisDishesSaleVO> result = reportAnalysisDishesSaleService.pageSummary(param);
+        List<ReportAnalysisDishesSaleVO> list = (List<ReportAnalysisDishesSaleVO>)
+                CollUtil.addAll(result.getResultPage().getRecords(), result.getTotalLine());
+        exportApi.startExcelExportTaskByPage(
+                "菜品销售排行",
+                I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS),
+                ReportAnalysisDishesSaleVO.class,
+                param.getExportCols(),
+                param.getPage(),
+                null,
+                () -> PageVO.of(list));
+    }
+}
+```
+
+---
+
+## 示例2：OrderInfoExportWebController（订单导出 Controller）
+
+```java
+// 导出功能独立到单独的 Controller，与查询 Controller 分离
+@Slf4j
+@RestController
+@RequestMapping(value = "/api/v2/web/order/export")
+public class OrderInfoExportWebController {
+
+    @Autowired
+    @Lazy
+    protected OrderWebBusiness orderWebBusiness;
+    @Autowired
+    @Lazy
+    protected OrderClients orderClients;
+
+    // 使用 orderClients.export() 启动异步导出（通过 client 代理）
+    @PostMapping(value = "/detail")
+    public void exportOrderDetail(@RequestBody LeRequest<OrderDetailWebDTO> request) {
+        OrderDetailWebDTO orderDetailDTO = request.getContent();
+        orderClients.export().startExcelExportTaskByPage(
+                I18n.getMessage("order.title.order-detail"),   // 文件名（国际化）
+                orderSheetName(),                              // 工作表名
+                OrderListWebVO.class,                          // 数据类
+                orderDetailDTO.getExportCols(),                // 导出列
+                orderDetailDTO,                                // 分页参数
+                null,                                          // 合计行（可选）
+                () -> orderWebBusiness.queryOrderInfoWebByPage(orderDetailDTO, orderDetailDTO));
+    }
+}
+```
+
+---
+
+## 示例3：OrderInfoWebController（订单查询 Controller）
+
+```java
+@Validated
+@RestController
+@RequestMapping(value = "/api/v2/web/order")
+public class OrderInfoWebController {
+
+    @Autowired
+    private OrderWebBusiness orderWebBusiness;
+
+    // 详情查询
+    @PostMapping(value = "/info")
+    public OrderInfoWebVO info(@Valid @RequestBody LeRequest<OrderInfoWebDTO> request) {
+        return orderWebBusiness.getOrderInfo(request.getContent().getOrderId());
+    }
+
+    // 分页查询：返回 PageVO
+    @PostMapping(value = "/page/detail")
+    public PageVO<OrderListWebVO> pageOrderDetail(@RequestBody LeRequest<OrderDetailWebDTO> request) {
+        OrderDetailWebDTO content = request.getContent();
+        return orderWebBusiness.queryOrderInfoWebByPage(PageDTO.of(content.getCurrent(), content.getSize()), content);
+    }
+
+    // 业务失败抛出 LeException
+    @PostMapping(value = "/refund")
+    public OrderRefundResultVO orderRefundWeb(@RequestBody LeRequest<OrderRefundSubmitWebDTO> request) throws LeCheckedException {
+        OrderRefundResultVO result = orderRefundBusiness.orderRefund(
+                request.getContent().convertToOrderRefundParam(), OrderRefundBizEnum.WEB);
+        if (!result.ifSuccess()) {
+            throw new LeException(result.getResultCode(), result.getResultMsg());
+        }
+        return result;
+    }
+}
+```
+
+---
+
+## 示例4：AttendanceLeaveInfoController（完整 CRUD）
+
+```java
+package net.xnzn.core.attendance.leave.controller;
+
+@Api(tags = "zjl-考勤-请假信息")
+@RestController
+@RequiresAuthentication
+@RequestMapping("/attendance/leave-info")
+public class AttendanceLeaveInfoController {
+
+    @Autowired
+    AttendanceLeaveInfoService attendanceLeaveInfoService;
+    @Autowired
+    RedissonClient redissonClient;
+
+    @PostMapping("/add")
+    @ApiOperation(value = "请假信息-新增")
+    public void add(@RequestBody LeRequest<AddOrUpdateAttendanceLeaveInfoDTO> request) {
+        attendanceLeaveInfoService.add(request.getContent());
+    }
+
+    @PutMapping("/batch/delete")
+    @ApiOperation(value = "请假信息-批量删除")
+    public void batchDelete(@RequestBody LeRequest<List<Long>> request) {
+        attendanceLeaveInfoService.batchDelete(request.getContent());
+    }
+
+    @PutMapping("/update")
+    @ApiOperation(value = "请假信息-修改")
+    public void update(@RequestBody LeRequest<AddOrUpdateAttendanceLeaveInfoDTO> request) {
+        attendanceLeaveInfoService.update(request.getContent());
+    }
+
+    @PostMapping("/query")
+    @ApiOperation(value = "请假信息-分页查询")
+    public Page<QueryAttendanceLeaveInfoVO> query(@RequestBody LeRequest<QueryAttendanceLeaveInfoDTO> request) {
+        return attendanceLeaveInfoService.page(request.getContent());
+    }
+
+    @PostMapping("/import-excel")
+    @ApiOperation(value = "请假信息-excel导入")
+    public void importExcel(@RequestParam(value = "leaveInfoExcel") MultipartFile leaveInfoExcel) throws Exception {
+        RLock lock = redissonClient.getLock("import:lock:" + TenantContextHolder.getTenantId());
+        if (!lock.tryLock(5, TimeUnit.SECONDS)) {
+            throw new LeException("考勤-请假数据导入中，请等待...");
+        }
+        try {
+            attendanceLeaveInfoService.importExcel(new ImportLeaveInfoExcelDTO().setLeaveInfoExcel(leaveInfoExcel));
+        } finally {
+            if (lock.isLocked() && lock.isHeldByCurrentThread()) {
+                lock.unlock();
+            }
+        }
+    }
+}
+```
+
+---
+
+## 示例5：AllocCanteenController（食堂档口，混合认证）
+
+```java
+package net.xnzn.core.allocation.canteen.controller;
+
+@Slf4j
+@RestController
+@RequestMapping("/api/v2/alloc/canteen")
+@Api(tags = "lsh_食堂档口相关控制器")
+public class AllocCanteenController {
+
+    @Autowired
+    @Lazy
+    private AllocCanteenService allocCanteenService;
+
+    @ApiOperation("分页查询食堂列表")
+    @PostMapping("/page-canteen")
+    public Page<AllocCanteenVO> pageCanteen(@RequestBody LeRequest<AllocCanteenStallPageParam> request) {
+        return allocCanteenService.pageCanteen(request.getContent());
+    }
+
+    @ApiOperation("查询区域食堂档口餐线编号")
+    @PostMapping("/get-canteen-num")
+    public LeResponse<String> getCanteenNum(@Valid @RequestBody LeRequest<AllocCanteenNumParam> request) {
+        return LeResponse.succ(allocCanteenBusiness.getCanteenNum(request.getContent()));
+    }
+
+    @ApiOperation("新增食堂")
+    @PostMapping("/add-canteen")
+    @RequiresGuest
+    public void addCanteen(@Valid @RequestBody LeRequest<AllocCanteenModel> request) {
+        allocCanteenBusiness.addCanteen(request.getContent());
+    }
+}
+```
+
+---
+
+## 示例6：MgrMenuController（菜单权限，方法级认证）
+
+```java
+package net.xnzn.core.auth.menu.controller;
+
+@RestController
+@RequestMapping("/api/v1/mgrmenu")
+@Api(value = "mgrmenu", tags = "菜单权限表管理")
+public class MgrMenuController {
+
+    @Autowired
+    private MgrMenuService mgrMenuService;
+
+    @ApiOperation(value = "新增菜单")
+    @PostMapping("/add")
+    @RequiresAuthentication
+    public void saveMenu(@Valid @RequestBody LeRequest<MgrMenuVO> request) {
+        mgrMenuService.saveMenu(request.getContent());
+    }
+
+    @ApiOperation(value = "更新菜单")
+    @PostMapping("/update")
+    @RequiresAuthentication
+    public boolean updateMenu(@Valid @RequestBody LeRequest<MgrMenuVO> request) {
+        return mgrMenuService.updateMenu(request.getContent());
+    }
+
+    @ApiOperation(value = "删除菜单")
+    @DeleteMapping("/{id}")
+    @RequiresGuest
+    public boolean removeById(@PathVariable Long id) {
+        return mgrMenuService.removeById(id);
+    }
+}
+```