leniu-dev 2.0.0

package/.claude/skills/leniu-report-scenario/references/amount-handling.md

@@ -0,0 +1,448 @@
+
+# leniu-tengyun-core 金额处理规范
+
+## 两种金额存储模式
+
+项目中存在两种金额存储模式，根据业务模块选择：
+
+### 模式 A：Long（分）→ BigDecimal（元）[钱包/账户模块]
+
+适用于余额、充值、补贴等精度要求高的模块：
+
+- **数据库**：存储为 Long（分）
+- **Entity**：使用 Long 类型
+- **VO**：使用 BigDecimal 类型（MyBatis 自动转换分→元）
+- **Excel 导出**：使用 `CustomNumberConverter` 转换器
+
+### 模式 B：BigDecimal（分）[订单/报表模块]
+
+适用于订单金额、报表汇总等复杂计算模块：
+
+- **数据库**：存储为 BigDecimal（值为分，如 10000 = 100.00元）
+- **Entity**：直接使用 BigDecimal 类型（以分为单位）
+- **VO**：同样使用 BigDecimal（字段注释需标注单位）
+- **SQL SUM**：直接 `SUM(amount)`，不需要 /100
+
+> 参考：`OrderInfo.payableAmount`（BigDecimal，以分为单位）
+
+## 金额类型速查
+
+| 类型 | 用途 | 示例 |
+|------|------|------|
+| `Long` | 钱包/账户存储（分） | `private Long orderAmount; // 10000 = 100.00元` |
+| `BigDecimal` | 订单/报表存储（分） | `private BigDecimal payableAmount; // 10000 = 100.00元` |
+| `BigDecimal` | VO 展示（元，模式A） | `private BigDecimal amount; // 100.00` |
+
+## Entity（模式A：Long存储）
+
+```java
+import com.baomidou.mybatisplus.annotation.*;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+
+@Data
+@TableName(value = "wallet_table", autoResultMap = true)
+public class WalletEntity {
+
+    @TableId
+    @ApiModelProperty(value = "钱包ID")
+    private Long id;
+
+    @ApiModelProperty(value = "余额（分）")
+    private Long balance;
+
+    @ApiModelProperty(value = "充值金额（分）")
+    private Long rechargeAmount;
+}
+```
+
+**要点**：
+- Entity 使用 `Long` 类型存储金额（分）
+- 字段注释明确标注"（分）"
+
+## Entity（模式B：BigDecimal存储，适用订单模块）
+
+```java
+@Data
+@TableName("order_info")
+public class OrderInfo {
+
+    @ApiModelProperty(value = "应付金额（分）")
+    private BigDecimal payableAmount;
+
+    @ApiModelProperty(value = "实付金额（分）")
+    private BigDecimal realAmount;
+
+    @ApiModelProperty(value = "优惠金额（分）")
+    private BigDecimal discountsAmount;
+}
+```
+
+**要点**：
+- 字段类型为 BigDecimal，但值以分为单位存储
+- 不需要 MyBatis 类型转换
+
+## VO（响应层）
+
+```java
+import com.alibaba.excel.annotation.ExcelProperty;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+import lombok.experimental.Accessors;
+import net.xnzn.core.common.export.converter.CustomNumberConverter;
+
+import java.math.BigDecimal;
+
+@Data
+@Accessors(chain = true)
+@ApiModel("订单信息")
+public class OrderVO {
+
+    @ApiModelProperty("订单ID")
+    private Long id;
+
+    @ApiModelProperty("订单金额（元）")
+    @ExcelProperty(value = "订单金额（元）", converter = CustomNumberConverter.class)
+    private BigDecimal orderAmount;
+
+    @ApiModelProperty("优惠金额（元）")
+    @ExcelProperty(value = "优惠金额（元）", converter = CustomNumberConverter.class)
+    private BigDecimal discountAmount;
+
+    @ApiModelProperty("实付金额（元）")
+    @ExcelProperty(value = "实付金额（元）", converter = CustomNumberConverter.class)
+    private BigDecimal payAmount;
+}
+```
+
+**要点**：
+- VO 使用 `BigDecimal` 类型（元）
+- Excel 导出必须使用 `converter = CustomNumberConverter.class`
+- MyBatis 会自动将 Long 分转换为 BigDecimal 元
+
+## MyBatis XML 查询
+
+### 列表查询
+
+```xml
+<select id="listOrders" resultType="OrderVO">
+    SELECT
+        order_id,
+        order_amount,      -- ❌ 不要 /100.0
+        discount_amount,    -- ❌ 不要 /100.0
+        pay_amount          -- ❌ 不要 /100.0
+    FROM order_table
+    <where>...</where>
+    ORDER BY crtime DESC
+</select>
+```
+
+### 合计查询
+
+```xml
+<select id="getOrderTotal" resultType="OrderVO">
+    SELECT
+        SUM(order_amount) AS order_amount,    -- ❌ 不要 /100.0
+        SUM(discount_amount) AS discount_amount,-- ❌ 不要 /100.0
+        SUM(pay_amount) AS pay_amount       -- ❌ 不要 /100.0
+    FROM order_table
+    <where>...</where>
+</select>
+```
+
+**重要**：
+- 永远不要在 SQL 中使用 `/100.0`
+- 合计查询只返回数值字段，不返回非数值字段（如日期、名称）
+
+## 金额工具类
+
+### AmountUtil（分转元）
+
+```java
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+
+/**
+ * 分与元金额转换
+ */
+public class AmountUtil {
+
+    /**
+     * 分转元（String）
+     */
+    public static String fen2YuanStr(Integer fen) {
+        if (fen == null) {
+            return "0.00";
+        }
+        BigDecimal amountFen = new BigDecimal(fen);
+        BigDecimal amountYuan = amountFen.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP);
+        return amountYuan.toPlainString();
+    }
+
+    /**
+     * 分转元（String 重载）
+     */
+    public static String fen2YuanStr(String fen) {
+        if (fen == null || fen.isEmpty()) {
+            return "0.00";
+        }
+        BigDecimal amountFen = new BigDecimal(fen);
+        BigDecimal amountYuan = amountFen.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP);
+        return amountYuan.toPlainString();
+    }
+
+    /**
+     * 分转元（BigDecimal）
+     */
+    public static BigDecimal fen2Yuan(Integer fen) {
+        if (fen == null) {
+            return BigDecimal.ZERO;
+        }
+        BigDecimal amountFen = new BigDecimal(fen);
+        return amountFen.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP);
+    }
+
+    /**
+     * 分转元（Long）
+     */
+    public static BigDecimal fen2Yuan(Long fen) {
+        if (fen == null) {
+            return BigDecimal.ZERO;
+        }
+        BigDecimal amountFen = new BigDecimal(fen);
+        return amountFen.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP);
+    }
+
+    /**
+     * 元转分
+     */
+    public static Integer yuan2Fen(String yuan) {
+        if (yuan == null || yuan.isEmpty()) {
+            return 0;
+        }
+        BigDecimal balance = new BigDecimal(yuan);
+        return Integer.parseInt(balance.multiply(new BigDecimal("100"))
+                                         .setScale(0, RoundingMode.HALF_UP)
+                                         .toPlainString());
+    }
+
+    /**
+     * 元转分（BigDecimal）
+     */
+    public static Integer yuan2Fen(BigDecimal yuan) {
+        if (yuan == null) {
+            return 0;
+        }
+        return yuan.multiply(new BigDecimal("100"))
+                  .setScale(0, RoundingMode.HALF_UP)
+                  .intValue();
+    }
+}
+```
+
+### 使用示例
+
+```java
+// 分转元
+Integer fenAmount = 10000;  // 10000分
+BigDecimal yuanAmount = AmountUtil.fen2Yuan(fenAmount);  // 100.00元
+
+// 元转分
+BigDecimal yuan = new BigDecimal("99.99");
+Integer fenAmount = AmountUtil.yuan2Fen(yuan);  // 9999分
+```
+
+## 常见场景
+
+### 场景1：订单报表 VO
+
+```java
+@Data
+@Accessors(chain = true)
+@ApiModel("订单报表")
+public class OrderReportVO {
+
+    @ExcelProperty(value = "月度", order = 1)
+    @ApiModelProperty("月度")
+    private String dateMonth;
+
+    @ExcelProperty(value = "订单总额（元）", order = 2, converter = CustomNumberConverter.class)
+    @ApiModelProperty("订单总额（元）")
+    private BigDecimal totalAmount;
+
+    @ExcelProperty(value = "订单数量", order = 3)
+    @ApiModelProperty("订单数量")
+    private Integer totalCount;
+
+    @ExcelProperty(value = "平均金额（元）", order = 4, converter = CustomNumberConverter.class)
+    @ApiModelProperty("平均金额（元）")
+    private BigDecimal avgAmount;
+}
+```
+
+### 场景2：工资汇总 VO
+
+```java
+@Data
+@Accessors(chain = true)
+@ApiModel("工资汇总")
+public class SalarySummaryVO {
+
+    @ExcelProperty(value = "月度", order = 1)
+    @ApiModelProperty("月度")
+    private String dateMonth;
+
+    @ExcelProperty(value = "基本工资（元）", order = 2, converter = CustomNumberConverter.class)
+    @ApiModelProperty("基本工资（元）")
+    private BigDecimal basicSalary;
+
+    @ExcelProperty(value = "绩效工资（元）", order = 3, converter = CustomNumberConverter.class)
+    @ApiModelProperty("绩效工资（元）")
+    private BigDecimal performanceSalary;
+
+    @ExcelProperty(value = "应发工资（元）", order = 4, converter = CustomNumberConverter.class)
+    @ApiModelProperty("应发工资（元）")
+    private BigDecimal totalSalary;
+}
+```
+
+### 场景3：合计行 SQL
+
+```xml
+<!-- 列表查询 -->
+<select id="pageSalary" resultType="SalarySummaryVO">
+    SELECT
+        date_month,
+        staff_count,
+        basic_salary,
+        performance_salary,
+        total_salary
+    FROM salary_summary
+    <where>...</where>
+    ORDER BY date_month DESC
+</select>
+
+<!-- 合计查询：只返回数值字段 -->
+<select id="getSalaryTotal" resultType="SalarySummaryVO">
+    SELECT
+        SUM(staff_count) AS staff_count,
+        SUM(basic_salary) AS basic_salary,
+        SUM(performance_salary) AS performance_salary,
+        SUM(total_salary) AS total_salary
+    FROM salary_summary
+    <where>...</where>
+</select>
+```
+
+### 场景4：平均值计算
+
+```xml
+<!-- 平均值计算（除零处理） -->
+CASE
+    WHEN SUM(staff_count) = 0 THEN 0
+    ELSE SUM(total_salary) / SUM(staff_count)
+END AS avgSalary
+
+<!-- 按维度平均 -->
+CASE
+    WHEN SUM(staff_count) = 0 THEN 0
+    ELSE SUM(total_salary) / COUNT(DISTINCT tenant_id)
+END AS avgSalary
+```
+
+## 数据流
+
+```
+数据库（Long/分） → MyBatis → VO（BigDecimal/元） → 前端（自动 /100）
+                                               ↓
+                                          Excel（converter /100）
+```
+
+## Excel 导出
+
+### 转换器
+
+```java
+@ExcelProperty(value = "订单金额（元）", converter = CustomNumberConverter.class)
+private BigDecimal orderAmount;
+```
+
+### 必要的导入
+
+```java
+import com.alibaba.excel.annotation.ExcelProperty;
+import net.xnzn.core.common.export.converter.CustomNumberConverter;
+```
+
+## 常见错误
+
+### 错误1：在 SQL 中使用 /100.0
+
+```xml
+<!-- ❌ 错误：在 SQL 中除以 100 -->
+SELECT
+    order_amount / 100.0 AS order_amount
+FROM order_table
+
+<!-- ✅ 正确：不进行除法，MyBatis 自动转换 -->
+SELECT
+    order_amount AS order_amount
+FROM order_table
+```
+
+### 错误2：钱包模块 Entity 使用 BigDecimal（模式A适用）
+
+```java
+// ❌ 错误：钱包/账户模块 Entity 使用 BigDecimal（应用 Long）
+@Data
+public class WalletEntity {
+    @ApiModelProperty("余额（元）")
+    private BigDecimal balance;
+}
+
+// ✅ 正确：钱包/账户模块 Entity 使用 Long（分）
+@Data
+public class WalletEntity {
+    @ApiModelProperty("余额（分）")
+    private Long balance;
+}
+```
+
+> **注意**：订单模块（OrderInfo）使用 BigDecimal 存储金额（以分为单位），这是模式B，属于正确用法，不是错误。
+
+### 错误3：VO 不使用转换器
+
+```java
+// ❌ 错误：Excel 导出不使用转换器
+@ExcelProperty(value = "订单金额（元）")
+private BigDecimal orderAmount;
+
+// ✅ 正确：使用 CustomNumberConverter
+@ExcelProperty(value = "订单金额（元）", converter = CustomNumberConverter.class)
+private BigDecimal orderAmount;
+```
+
+### 错误4：合计查询返回非数值字段
+
+```xml
+<!-- ❌ 错误：合计查询返回非数值字段 -->
+<select id="getOrderTotal" resultType="OrderVO">
+    SELECT
+        SUM(order_amount) AS order_amount,
+        order_date           -- ❌ 非数值字段
+    FROM order_table
+</select>
+
+<!-- ✅ 正确：只返回数值字段 -->
+<select id="getOrderTotal" resultType="OrderVO">
+    SELECT
+        SUM(order_amount) AS order_amount
+    FROM order_table
+</select>
+```
+
+## 参考文档
+
+详见：[leniu-tengyun-core 源码](/Users/xujiajun/Developer/gongsi_proj/core/leniu-tengyun-core)

package/.claude/skills/leniu-report-scenario/references/analysis-module.md

@@ -0,0 +1,64 @@
+# 经营分析模块详情
+
+## 分析类型总览
+
+| 分析类型 | Service | 接口数 | 路由前缀 |
+|---------|---------|-------|---------|
+| 营业额 | ReportAnalysisTurnoverService | 6 | `/summary/analysis/turnover/` |
+| 用户 | ReportAnalysisCustService (ORDER=50) | 8 | `/summary/analysis/cust/` |
+| 菜品 | ReportAnalysisDishesSaleService (ORDER=51) | 10 | `/summary/analysis/dishes/` |
+| 满意度 | ReportAnalysisEvaluateService | 2 | `/summary/analysis/evaluate/` |
+| 充值 | ReportAnalysisTurnoverService | 4 | `/summary/analysis/recharge/` |
+| 设备 | ReportAnalysisTurnoverService | 2 | `/summary/analysis/device/` |
+
+## 用户活跃度分析
+
+### 分段枚举
+
+- `AnalysisConsumeTimesEnum`：消费次数分段（1-10/10-20/20-30/30-40/40-50/>=50）
+- `AnalysisConsumeAmountEnum`：消费金额分段（<200/200-400/400-600/600-800/800-1000/>=1000元）
+- `AnalysisConsumeSlienceEnum`：沉默时长分段
+
+### 活跃度 VO
+
+```java
+// ReportAnalysisActiveVO
+activeNumber/activePercent   // 活跃用户（有消费记录）
+keepNumber/keepPercent       // 保留用户（持续消费）
+lossNumber/lossPercent       // 流失用户（不再消费）
+newNumber/newPercent         // 新增用户（首次消费）
+```
+
+## 公共参数类
+
+```java
+// ReportBaseParam（所有查询参数基类）
+PageDTO page;
+LocalDate startDate/endDate;
+LocalDate startOrderDate/endOrderDate;
+Integer sumType;           // 汇总类型（1按时段/2按日期）
+Integer sumDimension;      // 汇总维度
+List<Integer> ageTypes;
+List<Integer> holidayTypeList;
+List<String> exportCols;
+LocalDateTime startPayTime/endPayTime;
+
+// ReportNotConsumeDTO（未消费数据）
+String statisticDate;   // 统计日期（支付日期）
+String orderDate;       // 就餐日期（菜品统计专用）
+Long relationId;
+
+// 支付信息编码: "支付方式-支付渠道-支付金额" 如 "1-1-1200;2-4-1200"
+// 优惠信息编码: "变动类型,详情类型,金额" 如 "1,1,100;2,11,200"
+```
+
+## API 路由总览
+
+| 模块 | 前缀 | 核心接口 |
+|------|------|---------|
+| 营业收入明细 | `/summary/basic/` | flow/page, cust/page, remote/detail/page, remote/summary/page |
+| 订单汇总 | `/summary/order/` | organization/pay/type/classify/mealtime/dishes |
+| 账户流水 | `/summary/account/` | flow/cust/psn/organization/operator/consume/recharge/wallet/data |
+| 经营分析 | `/summary/analysis/` | turnover(6)/cust(8)/dishes(10)/recharge(4)/device(2)/evaluate(2) |
+| 数据修复 | `/summary/fix/` | order, account (限31天) |
+| 商户 | `/report/merchant/summary/` | consume, recharge |

package/.claude/skills/leniu-report-scenario/references/customization-table-fields.md

@@ -0,0 +1,93 @@
+# 报表基础表完整字段说明
+
+## report_order_info（报表订单主表）
+
+> v5.29 后，正向下单和逆向退款**都存在这张表中**，通过 `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 | 餐次类型 |
+| `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其他，医院版） |
+
+## report_order_detail（报表订单菜品明细表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `detailId` | Long | 明细主键 |
+| `orderId` | Long | 关联订单ID |
+| `goodsDishesId/goodsDishesName` | Long/String | 菜品信息 |
+| `salePrice` | BigDecimal | 售卖价格（分） |
+| `prefPrice` | BigDecimal | 优惠价格（分） |
+| `price` | BigDecimal | 计算价格（分，最终价格） |
+| `quantity` | Integer | 数量/重量 |
+| `totalAmount` | BigDecimal | 订单详情总金额（分） |
+| `realAmount` | BigDecimal | 实际付款金额（分） |
+| `detailState` | Integer | **1=正常，2=已退菜（全退），3=部分退菜** |
+| `goodsRefundNum` | Integer | 商品已退数量 |
+| `refundAmount` | BigDecimal | 商品退款金额（分） |
+| `detailType` | Integer | 明细类别（1菜品/2套餐/3商品/4按键/5补扣/6报餐） |
+| `costPrice` | BigDecimal | 成本价格 |
+
+## report_account_flow（账户变动流水主表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `flowId` | Long | 主键（雪花ID） |
+| `custId` | Long | 人员ID |
+| `flowType` | Integer | 交易类型（AccTradeTypeEnum） |
+| `flowRealAmount` | BigDecimal | 实际交易金额 |
+| `flowAmount` | BigDecimal | 交易金额 |
+| `accTotalBal` | BigDecimal | 所有钱包可用余额之和（不含冻结） |
+| `accAllBal` | BigDecimal | 所有钱包总余额（含冻结） |
+| `payTime` | LocalDateTime | 支付时间 |
+| `ordTime` | LocalDateTime | 订单时间 |
+| `status` | Integer | 消费状态：0=未消费，1=已消费 |
+| `manageCost` | BigDecimal | 管理费 |
+| `rechargeSource` | Integer | 充值来源 |
+| `payChannel` | Integer | 支付渠道 |
+| `payType` | Integer | 支付方式 |
+
+> 注意：`custName`、`mobile`、`mobileSuffix` 使用 SM4 加密存储。
+
+## report_account_flow_detail（账户流水钱包明细表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | Long | 自增主键 |
+| `flowId` | Long | 关联主流水 |
+| `walletId` | Long | 钱包类型（AccWalletIdEnum） |
+| `flowType` | Integer | 交易类型 |
+| `amount` | BigDecimal | 本钱包支付金额（转出类型取负值） |
+| `walletBal` | BigDecimal | 本钱包可用余额 |
+| `allWalletBal` | BigDecimal | 本钱包总余额（含冻结） |
+| `frozenBalance` | BigDecimal | 冻结余额 |
+| `payTime` | LocalDateTime | 支付时间 |