leniu-dev 2.0.0

package/.claude/skills/leniu-report-scenario/references/mealtime.md

@@ -0,0 +1,197 @@
+
+# leniu-tengyun-core 餐次处理规范
+
+## 餐次枚举定义
+
+### AllocMealtimeTypeEnum
+
+餐次类型枚举 `AllocMealtimeTypeEnum` 定义了5种餐次：
+
+| 枚举值 | key | 显示名称 | 说明 |
+|--------|-----|----------|------|
+| MEALTIME_BREAKFAST | 1 | 早餐 | 早餐 |
+| MEALTIME_LUNCH | 2 | 午餐 | 午餐 |
+| MEALTIME_AFTERNOON_TEA | 3 | 下午茶 | 下午茶 |
+| MEALTIME_DINNER | 4 | 晚餐 | 晚餐 |
+| MEALTIME_MIDNIGHT_SNACK | 5 | 夜宵 | 夜宵 |
+
+### 常用方法
+
+```java
+// 根据key获取枚举
+AllocMealtimeTypeEnum typeEnum = AllocMealtimeTypeEnum.getTypeEnum(1);
+
+// 根据key获取显示名称
+String desc = AllocMealtimeTypeEnum.getValueByKey(1); // 返回 "早餐"
+
+// 获取所有餐次key列表
+List<Integer> allTypes = AllocMealtimeTypeEnum.allTypeList(); // [1, 2, 3, 4, 5]
+
+// 获取正餐类型列表
+List<Integer> normalTypes = AllocMealtimeTypeEnum.normalTypeList(); // [1, 2, 4]
+```
+
+### 餐次分类
+
+- **正餐**：早餐(1)、午餐(2)、晚餐(4)
+- **非正餐**：下午茶(3)、夜宵(5)
+
+## 查询参数中的餐次处理
+
+### Param类定义
+
+在报表查询Param类中添加餐次筛选字段：
+
+```java
+@ApiModelProperty(value = "餐次集合")
+private List<Integer> mealtimeTypes;
+```
+
+### 完整示例
+
+```java
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+@EqualsAndHashCode(callSuper = true)
+@ApiModel(value = "XXX查询入参")
+public class XxxParam extends ReportBaseParam {
+
+    @ApiModelProperty(value = "餐次集合")
+    private List<Integer> mealtimeTypes;
+
+    // 其他查询字段...
+}
+```
+
+## 返回VO中的餐次处理
+
+### VO字段定义
+
+在报表返回VO类中定义餐次字段：
+
+```java
+@Data
+@Accessors(chain = true)
+@ApiModel(value = "XXX报表")
+public class XxxVO {
+
+    @ExcelProperty(value = "餐次", order = 5, converter = MealtimeTypeConverter.class)
+    @ApiModelProperty(value = "餐次")
+    private Integer mealtimeType;
+
+    // 其他字段...
+}
+```
+
+### 必要的导入
+
+```java
+import com.alibaba.excel.annotation.ExcelProperty;
+import net.xnzn.core.common.export.converter.MealtimeTypeConverter;
+```
+
+### 字段说明
+
+- `mealtimeType`: 存储餐次的整数key值（1-5）
+- `@ExcelProperty`: 配置EasyExcel导出，使用`MealtimeTypeConverter`进行转换
+- `converter = MealtimeTypeConverter.class`: 自动将整数转换为可读的餐次名称
+
+## MyBatis XML中的餐次查询
+
+### 基本IN查询
+
+```xml
+<!-- 餐次筛选 -->
+<if test="mealtimeTypes != null and mealtimeTypes.size() > 0">
+    AND mealtime_type IN
+    <foreach collection="mealtimeTypes" item="type" open="(" separator="," close=")">
+        #{type}
+    </foreach>
+</if>
+```
+
+### 正餐筛选
+
+```xml
+<!-- 仅查询正餐（早餐、午餐、晚餐） -->
+AND mealtime_type IN (1, 2, 4)
+```
+
+### 完整示例
+
+```xml
+<select id="pageXxx" resultType="net.xnzn.core.xxx.vo.XxxVO">
+    SELECT
+        id,
+        order_date,
+        mealtime_type,
+        cust_name,
+        real_amount
+    FROM order_table
+    WHERE del_flag = 2
+    <if test="startDate != null">
+        AND order_date >= #{startDate}
+    </if>
+    <if test="endDate != null">
+        AND order_date &lt;= #{endDate}
+    </if>
+    <if test="mealtimeTypes != null and mealtimeTypes.size() > 0">
+        AND mealtime_type IN
+        <foreach collection="mealtimeTypes" item="type" open="(" separator="," close=")">
+            #{type}
+        </foreach>
+    </if>
+    <if test="canteenId != null">
+        AND canteen_id = #{canteenId}
+    </if>
+    ORDER BY order_date DESC
+</select>
+```
+
+## 常见使用场景
+
+### 场景1：查询指定餐次的订单
+
+```java
+// Param定义
+@ApiModelProperty(value = "餐次集合")
+private List<Integer> mealtimeTypes;
+
+// Service调用
+List<Integer> mealtimeTypes = Arrays.asList(1, 2); // 查询早餐和午餐
+param.setMealtimeTypes(mealtimeTypes);
+```
+
+### 场景2：仅查询正餐
+
+```java
+// 方式1：直接在XML中硬编码
+AND mealtime_type IN (1, 2, 4)
+
+// 方式2：使用枚举工具类
+param.setMealtimeTypes(AllocMealtimeTypeEnum.normalTypeList());
+```
+
+### 场景3：导出时餐次列显示中文名称
+
+```java
+// VO定义
+@ExcelProperty(value = "餐次", order = 5, converter = MealtimeTypeConverter.class)
+@ApiModelProperty(value = "餐次")
+private Integer mealtimeType;
+
+// 导出时自动转换：1 -> "早餐"，2 -> "午餐" 等
+```
+
+## 注意事项
+
+1. **字段命名**：统一使用 `mealtimeType` (驼峰) 或 `mealtime_type` (下划线)
+2. **类型**：数据库和Java代码中均使用 `Integer` 类型
+3. **转换器**：导出时必须使用 `MealtimeTypeConverter` 进行转换
+4. **国际化的影响**：显示名称根据项目配置可能使用中文或国际化key
+5. **正餐判断**：需要区分正餐时使用 `AllocMealtimeTypeEnum.normalTypeList()` 方法
+
+## 参考文档
+
+详见：[leniu-tengyun-core 源码](/Users/xujiajun/Developer/gongsi_proj/core/leniu-tengyun-core)

package/.claude/skills/leniu-report-scenario/references/query-param.md

@@ -0,0 +1,274 @@
+
+# leniu-tengyun-core 报表查询入参规范
+
+## 项目特征
+
+| 特征 | 说明 |
+|------|------|
+| **包名前缀** | `net.xnzn.core.*` |
+| **JDK 版本** | 21 |
+| **请求封装** | `LeRequest<T>` |
+| **分页参数** | `PageDTO` |
+| **基类** | `ReportBaseParam` |
+| **校验框架** | Jakarta Validation |
+
+## 核心结构
+
+### 1. Controller层接收入参
+
+```java
+import com.pig4cloud.pigx.common.core.util.LeRequest;
+
+@PostMapping("/page")
+public ReportBaseTotalVO<XxxVO> pageXxxSummary(@RequestBody LeRequest<XxxParam> request) {
+    XxxParam param = request.getContent();
+    return xxxService.pageSummary(param);
+}
+```
+
+### 2. Param类基类继承
+
+报表查询Param类**必须继承** `ReportBaseParam`：
+
+```java
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import net.xnzn.core.common.page.PageDTO;
+import net.xnzn.core.common.param.ReportBaseParam;
+
+import java.time.LocalDate;
+import java.util.List;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel(value = "XXX查询入参")
+public class XxxParam extends ReportBaseParam {
+
+    @ApiModelProperty("关键字")
+    private String keyword;
+
+    @ApiModelProperty("状态")
+    private Integer status;
+}
+```
+
+### 3. ReportBaseParam 提供的通用字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| `page` | `PageDTO` | 分页参数 |
+| `startDate` | `LocalDate` | 开始时间 |
+| `endDate` | `LocalDate` | 结束时间 |
+| `exportCols` | `List<String>` | 需要导出的列 |
+| `sumType` | `Integer` | 汇总类型 |
+| `sumDimension` | `Integer` | 统计维度 |
+
+## 常用查询字段模式
+
+### 时间范围查询
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("订单报表查询参数")
+public class OrderReportParam extends ReportBaseParam {
+
+    // 基类已有 startDate, endDate
+
+    @ApiModelProperty("开始时间（精确到秒）")
+    private LocalDateTime startTime;
+
+    @ApiModelProperty("结束时间（精确到秒）")
+    private LocalDateTime endTime;
+}
+```
+
+### 组织筛选
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("组织报表查询参数")
+public class OrgReportParam extends ReportBaseParam {
+
+    @ApiModelProperty("组织ID")
+    private Long orgId;
+
+    @ApiModelProperty("组织ID列表")
+    private List<Long> orgIds;
+
+    @ApiModelProperty("食堂ID")
+    private Long canteenId;
+
+    @ApiModelProperty("食堂ID列表")
+    private List<Long> canteenIds;
+}
+```
+
+### 餐次筛选
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("餐次报表查询参数")
+public class MealtimeReportParam extends ReportBaseParam {
+
+    @ApiModelProperty("餐次类型列表")
+    private List<Integer> mealtimeTypes;
+
+    @ApiModelProperty("是否只查正餐")
+    private Boolean onlyMainMeal;
+}
+```
+
+### 金额范围
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("金额报表查询参数")
+public class AmountReportParam extends ReportBaseParam {
+
+    @ApiModelProperty("最小金额（分）")
+    private Long minAmount;
+
+    @ApiModelProperty("最大金额（分）")
+    private Long maxAmount;
+}
+```
+
+## PageDTO 结构
+
+```java
+@Data
+@ApiModel("分页参数")
+public class PageDTO {
+
+    @ApiModelProperty("当前页码")
+    private Integer current = 1;
+
+    @ApiModelProperty("每页条数")
+    private Integer size = 10;
+
+    @ApiModelProperty("是否查询总数")
+    private Boolean ifCount = true;
+
+    @ApiModelProperty("页数为0时的处理")
+    private Boolean ifPageSizeZero = false;
+}
+```
+
+## 完整示例
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("销售报表查询参数")
+public class SalesReportParam extends ReportBaseParam {
+
+    @ApiModelProperty(value = "关键字")
+    private String keyword;
+
+    @ApiModelProperty(value = "组织ID列表")
+    private List<Long> orgIds;
+
+    @ApiModelProperty(value = "食堂ID列表")
+    private List<Long> canteenIds;
+
+    @ApiModelProperty(value = "餐次类型列表")
+    private List<Integer> mealtimeTypes;
+
+    @ApiModelProperty(value = "支付方式列表")
+    private List<Integer> payTypes;
+
+    @ApiModelProperty(value = "最小金额（分）")
+    private Long minAmount;
+
+    @ApiModelProperty(value = "最大金额（分）")
+    private Long maxAmount;
+
+    @ApiModelProperty(value = "是否查询合计行")
+    private Boolean ifQueryTotal = true;
+}
+```
+
+## 两层继承结构（实际生产代码模式）
+
+报表 Param 存在两层继承结构，以订单分析报表为例：
+
+```
+ReportAnalysisParam（大类基类：订单分析类报表通用字段）
+    └── ReportAnalysisTurnoverParam（具体报表 Param，加业务字段）
+```
+
+### ReportAnalysisParam（中间基类）
+
+```java
+import lombok.Data;
+import net.xnzn.core.common.page.PageDTO;
+
+import java.time.LocalDate;
+import java.util.List;
+
+@Data
+public class ReportAnalysisParam {
+
+    /** 分页参数 */
+    private PageDTO page;
+
+    /** 开始日期 */
+    private LocalDate startDate;
+
+    /** 结束日期 */
+    private LocalDate endDate;
+
+    /** 日期维度：1=按月 2=按日 */
+    private Integer dateType;
+
+    /** 食堂摊位ID列表（多选） */
+    private List<Long> canteenStallIds;
+}
+```
+
+### ReportAnalysisTurnoverParam（具体 Param，继承中间基类）
+
+```java
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+import java.util.List;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ReportAnalysisTurnoverParam extends ReportAnalysisParam {
+
+    /** 餐次类型（单选） */
+    private Integer mealtimeType;
+
+    /** 餐次类型列表（多选） */
+    private List<Integer> mealtimeTypeList;
+
+    /** 排序类型：1=按金额降序（默认） */
+    private Integer sortType = 1;
+
+    /** 食堂ID（单选） */
+    private Long canteenId;
+
+    /** 摊位ID（单选） */
+    private Long stallId;
+}
+```
+
+**选择继承层级的判断依据**：
+- 若报表是"订单分析"大类报表 → 继承 `ReportAnalysisParam`（含 `dateType`）
+- 若是通用报表 → 直接继承 `ReportBaseParam`（含 `page/startDate/endDate/exportCols`）
+
+## 注意事项
+
+- 报表Param类必须继承 `ReportBaseParam` 或其子类（如 `ReportAnalysisParam`）
+- 时间字段使用 `LocalDate` 或 `LocalDateTime`
+- `dateType` 字段含义：1=按月汇总，2=按日汇总
+- 金额查询参数类型与业务域保持一致：钱包/账户用 `Long`（分），订单用 `BigDecimal`（分）；见 leniu-java-amount-handling
+- 导出时通过 `exportCols` 控制导出列

package/.claude/skills/leniu-report-scenario/references/report-tables.md

@@ -0,0 +1,162 @@
+# 报表基础表完整字段说明
+
+> 本文件按需加载：当报表基于 report_order_info / report_account_flow 开发时读取。
+
+---
+
+## report_order_info（报表订单主表）
+
+### v5.29 版本（sys-canteen 模块）
+
+> 正向下单和逆向退款**都存在这张表中**，通过 `consumeType` 区分。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `orderId` | Long | 主键。正向=订单ID，退款=退款单ID |
+| `relationOrderId` | Long | 关联订单ID（退款记录指向原始订单） |
+| `consumeType` | Integer | **1=消费，2=退款** |
+| `orderRefundState` | Integer | **1=未退单，2=已退单（全退），3=部分退单** |
+| `payableAmount` | BigDecimal | 应付金额（分） |
+| `realAmount` | BigDecimal | 实付金额（分） |
+| `refundAmount` | BigDecimal | 累计退款金额（分） |
+| `realRefundAmount` | BigDecimal | 实际退款金额（分，退款记录为负数） |
+| `walletAmount` | BigDecimal | 个人钱包支付金额（分） |
+| `subsidyAmount` | BigDecimal | 补贴钱包支付金额（分） |
+| `redEnvelopeAmount` | BigDecimal | 红包支付金额（分） |
+| `accPayAmount` | BigDecimal | 账户支付金额（分） |
+| `outPayAmount` | BigDecimal | 外部支付金额（分） |
+| `payTime` | LocalDateTime | 支付时间（退款=审核时间） |
+| `orderTime` | LocalDateTime | 下单时间 |
+| `orderDate` | LocalDate | 就餐日期 |
+| `status` | Integer | 消费状态：0=未消费，1=已消费 |
+| `mealtimeType` | Integer | 餐次类型（1早/2午/3下午茶/4晚/5夜宵/-1其他） |
+| `orderType` | Integer | 订单类型（1当餐/2预订/3报餐/4扫码/5餐桌/6自助/11商城/12超市/21补扣/22外部） |
+| `canteenId/canteenName` | Long/String | 食堂 |
+| `stallId/stallName` | Long/String | 档口 |
+| `areaId/areaName` | Long/String | 区域 |
+| `custId/custName/custNum` | - | 用户信息 |
+| `orgId/orgFullId/orgName/orgFullName` | - | 组织信息 |
+| `payType` | Integer | 支付方式 |
+| `payChannel` | Integer | 支付渠道 |
+| `nuClearMode` | Integer | 核身方式（1刷卡/2刷脸/3扫码） |
+| `sourceType` | Integer | 来源类型 |
+| `ifOnline` | Integer | 是否在线订单（1是/2否） |
+| `psnType/psnTypeName` | Integer/String | 用户类别 |
+| `personType` | Integer | 人员归类（1职工/2患者/3陪护/4其他，医院版） |
+
+### 标准版（core-report 模块）
+
+> 仅存正向订单，**无 consumeType 字段**。退款数据在独立 `report_refund` 表。
+
+与 v5.29 版本相比，额外字段：
+- `discountsAmount`（优惠金额，取负数）
+- `deliveryAmount/packingAmount`（配送费/包装费）
+- `ageType/holidayType`（年龄段/节假日类型）
+- `machineSn`（设备SN）
+
+---
+
+## report_order_detail（菜品明细表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `detailId` | Long | 明细主键 |
+| `orderId` | Long | 关联订单ID |
+| `goodsDishesId/goodsDishesName` | Long/String | 菜品信息 |
+| `salePrice` | BigDecimal | 售卖价格（分） |
+| `price` | BigDecimal | 最终价格（分） |
+| `quantity` | Integer | 数量/重量 |
+| `salesMode` | Integer | 销售方式（1按份/2称重） |
+| `totalAmount` | BigDecimal | 总金额（分） |
+| `realAmount` | BigDecimal | 实付金额（分） |
+| `detailState` | Integer | **1=正常，2=已退菜（全退），3=部分退菜** |
+| `goodsRefundNum` | Integer | 已退数量 |
+| `refundAmount` | BigDecimal | 退款金额（分） |
+| `detailType` | Integer | 类别（1菜品/2套餐/3商品/4按键/5补扣/6报餐） |
+| `costPrice` | BigDecimal | 成本价格 |
+
+---
+
+## report_refund / report_refund_detail（标准版特有）
+
+**report_refund**（退款主表，金额为**正数**）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `orderRefundId` | Long | 退款单主键 |
+| `orderId` | Long | 原始订单ID |
+| `realRefundAmount` | BigDecimal | 退款金额（**正数**） |
+| `applyType` | Integer | 申请类型（1退单/2纠错） |
+| `checkTime` | LocalDateTime | 审核时间 |
+
+**report_refund_detail**：`orderRefundId`, `detailId`, `realQuantity`, `realRefundAmount`（**正数**）
+
+---
+
+## report_account_flow（账户流水主表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `flowId` | Long | 主键（雪花ID） |
+| `custId` | Long | 人员ID |
+| `flowType` | Integer | 交易类型（AccTradeTypeEnum） |
+| `flowRealAmount` | BigDecimal | 实际交易金额 |
+| `flowAmount` | BigDecimal | 交易金额 |
+| `accTotalBal` | BigDecimal | 可用余额之和（不含冻结） |
+| `accAllBal` | BigDecimal | 总余额（含冻结） |
+| `payTime` | LocalDateTime | 支付时间 |
+| `status` | Integer | 消费状态：0=未消费，1=已消费 |
+| `manageCost` | BigDecimal | 管理费 |
+
+> `custName`、`mobile` 使用 SM4 加密存储。
+
+## report_account_flow_detail（流水钱包明细）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `flowId` | Long | 关联主流水 |
+| `walletId` | Long | 钱包类型（1个人/2补贴/4红包） |
+| `amount` | BigDecimal | 金额（转出取负值） |
+| `walletBal` | BigDecimal | 钱包可用余额 |
+| `frozenBalance` | BigDecimal | 冻结余额 |
+
+---
+
+## 枚举速查
+
+### AccWalletIdEnum（钱包类型）
+
+| key | 枚举 | 含义 |
+|-----|------|------|
+| 1 | WALLET | 个人钱包 |
+| 2 | SUBSIDY | 补贴钱包 |
+| 4 | LUCK_MONEY | 红包 |
+
+### AccTradeTypeEnum（交易类型）
+
+| key | 枚举 | 金额方向 |
+|-----|------|---------|
+| 10/11 | RECHARGE/RECHARGE_GIFT | 正 |
+| 12/40/50 | 撤销赠送/撤销充值/撤销补贴 | **负** |
+| 20 | SUBSIDY 补贴 | 正 |
+| 30 | WITHDRAW 提现 | **负** |
+| 60/80/100 | 转出/冻结/补贴清空 | **负** |
+| 70/90 | 转入/解冻 | 正 |
+| 110/120 | CONSUME/CONSUME_REPAIR | **负** |
+| 130 | CONSUME_REFUND 退款 | 正 |
+| 140/141/142 | 红包/撤销红包/红包清空 | 正/**负**/**负** |
+
+### 账户流水常用过滤
+
+```sql
+-- 净消费额：消费为负，退款为正 → SUM 即为净消费额（负值）
+WHERE wallet_id = #{walletId} AND flow_type IN (110, 130)
+```
+
+---
+
+## 其他基础表
+
+- **report_order_pay**：`orderId`, `payType/payChannel`, `payAmount/refundAmount`
+- **report_order_discount**：`orderId`, `changeAmount`, `changeType`(1上浮/2优惠), `changeDetailType`
+- **report_account_summary**（日结表）：联合主键 `statisticDate + custId`，期末余额 = 期初 + 充值 - 撤销 + 补贴 - 消费 + 退款 - 提现