leniu-dev 2.0.0

package/.cursor/skills/leniu-report-scenario/references/standard-customization.md

@@ -0,0 +1,112 @@
+
+# leniu 标准版定制报表开发指南
+
+> 详细字段说明见 `references/table-fields.md`，经营分析详情见 `references/analysis-module.md`
+
+## 版本识别（必读）
+
+**本 skill 仅适用于标准版（core-report 独立模块）**。
+
+| 判断方式 | 标准版（本指南） | v5.29 版本 |
+|---------|--------------|-----------|
+| 目录结构 | `core-report/` 独立模块 | `sys-canteen/` 内嵌 |
+| 退款存储 | 独立 `report_refund` 表（**正数**） | 合并入 `report_order_info`（`consumeType=2`，**负数**） |
+| 第二阶段 | `fix()` 按日重算 | `batchConsume()` 增量累加 |
+| consumeType | **无此字段** | 1=消费，2=退款 |
+
+> v5.29 报表请使用 `leniu-report-customization`。钱包/交易类型枚举同 v5.29，参见该 skill。
+
+
+## 二、核心基础表概要
+
+### 2.1 report_order_info（仅存正向订单，无 consumeType）
+
+关键字段：`orderId`(主键), `canteenId/stallId`, `mealtimeType`, `orderType`, `payableAmount/realAmount/refundAmount`(分), `accPayAmount/outPayAmount`, `payTime/orderDate`, `orderRefundState`(1未退/2全退/3部分退), `status`(0未消费/1已消费), `nuClearMode`, `psnType`, `ageType/holidayType`
+
+### 2.2 report_order_detail（菜品明细）
+
+关键字段：`detailId`, `orderId`, `goodsDishesId/goodsDishesName`, `price/totalAmount/realAmount`(分), `quantity`, `salesMode`(1按份/2称重), `detailState`(1正常/2全退/3部分退), `goodsRefundNum`, `refundAmount`, `detailType`
+
+### 2.3 report_refund / report_refund_detail（标准版特有，退款为正数）
+
+**report_refund**：`orderRefundId`(主键), `orderId`(原订单), `realRefundAmount`(**正数**), `applyType`(1退单/2纠错), `checkTime`
+
+**report_refund_detail**：`orderRefundId`, `detailId`, `realQuantity`, `realRefundAmount`(**正数**)
+
+### 2.4 其他基础表
+
+- **report_order_pay**：`orderId`, `payType/payChannel`, `payAmount/refundAmount`
+- **report_order_discount**：`orderId`, `changeAmount`, `changeType`(1上浮/2优惠), `changeDetailType`
+- **report_order_info_snapshot**：订单交易快照
+
+
+## 四、账户流水报表
+
+### 4.1 report_account_flow（流水主表）
+
+核心字段：`flowId`, `custId/orgId`, `payTime`, `flowType`(AccTradeTypeEnum), `flowRealAmount/flowAmount`, `manageCost`, `accTotalBal/accAllBal`, `status`
+
+### 4.2 report_account_summary（用户账户日结表）
+
+联合主键：`statisticDate` + `custId`。期末余额 = 期初 + 充值 - 撤销充值 + 补贴 - 撤销补贴 + 红包 + 赠送 - 消费 - 补扣 + 退款 - 提现 - 清空 - 管理费
+
+### 4.3 AccountConsumeService 实现
+
+| ORDER | 类 | 汇总表 |
+|-------|---|-------|
+| 1/2 | Flow/FlowDetail | 基础表 |
+| 13 | AccountSummary | 日结 |
+| 14 | AccountOperator | 操作员 |
+| 15-17 | ConsumeSummary/Org/Type | 消费维度 |
+| 18 | WalletConsume | 钱包 |
+| 19 | SumRechargeMer | 商户充值 |
+
+
+## 六、汇总模型速查
+
+| 表 | 维度 | 金额 |
+|----|------|------|
+| report_sum_mealtime | date/canteen/stall/org/age/mealtime/psn/machine/source | custNum/consumeNum/realAmount/refundAmount |
+| report_sum_pay | date/mealtime/canteen/stall/org/age/payChannel/payType | payNum/realAmount/refundAmount |
+| report_sum_dishes | date/area/canteen/stall/reportOrderType/mealtime/cook/device/dishes/salesMode/detailType | quantity/realAmount |
+| report_sum_pay_mer | tenantId/date/payChannel/payType | custNum/payNum/realAmount/refundAmount |
+
+
+## 八、公共模块
+
+- **报表错误日志**（report_error_log）：`reportErrorType`(1账户/2订单), `reportErrorState`(1已创建/2已处理)。定时任务 `@XxlJob("reportExceptionHandle")` 自动修复。
+- **金额范围设置**：`POST /report/alloc/amount-scope/save`
+- **数据修复**：`POST /summary/fix/order|account`（限31天，Redisson 锁 120 分钟）
+
+### 核心枚举
+
+| 枚举 | 值 |
+|------|---|
+| ReportClassifyEnum | 1组织/2类别/3食堂/4设备/5收入/6渠道/7餐次 |
+| ReportPayTypeEnum | 1微信/2支付宝/3系统账户/9现金/20其他 |
+
+
+## 十、开发检查清单
+
+### 建表
+- [ ] 分组维度 + 金额汇总 + 审计字段（crby/crtime/upby/uptime/del_flag），无 tenant_id
+
+### 实现
+- [ ] 实现 `ReportOrderConsumeService`，设 `getOrder()`
+- [ ] `fix()` 先删后插（**标准版核心模式**），`consume()` 留空
+
+### 退款（标准版特有）
+- [ ] 退款在独立 `report_refund` 表（**正数金额**）
+- [ ] 净消费 = `real_amount - IFNULL(refund_amount, 0)`
+- [ ] **不要使用 consumeType 字段**
+
+### 查询
+- [ ] ReportBaseTotalVO + CompletableFuture 并行 + MgrUserAuthPO 权限
+- [ ] GROUP BY / ORDER BY 表达式与 SELECT 完全一致（only_full_group_by）
+
+
+## 注意
+
+- 标准版退款为独立表（正数金额），**不要使用 consumeType 字段**
+- 标准版第二阶段用 `fix()` 按日重算，**不要使用 batchConsume() 增量模式**
+- CRUD 用 `leniu-crud-development`，MyBatis 用 `leniu-java-mybatis`，入参用 `leniu-java-report-query-param`，合计行用 `leniu-java-total-line`，餐次用 `leniu-mealtime`

package/.cursor/skills/leniu-report-scenario/references/standard-table-fields.md

@@ -0,0 +1,113 @@
+# 标准版报表基础表完整字段说明
+
+## report_order_info（报表订单主表，仅正向订单）
+
+> 标准版中此表**仅存正向订单**，退款数据在独立的 `report_refund` 表中。无 `consumeType` 字段。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `orderId` | Long | 主键（雪花 ID） |
+| `machineSn` | String | 设备 SN |
+| `orgId` | Long | 组织 ID |
+| `custId` | Long | 人员 ID |
+| `nuClearMode` | Integer | 核身方式（1刷卡/2刷脸/3扫码） |
+| `sourceType` | Integer | 来源类型 |
+| `ifOnline` | Integer | 是否在线（1是/2否） |
+| `canteenId/canteenName` | Long/String | 食堂 |
+| `stallId/stallName` | Long/String | 档口 |
+| `mealtimeType` | Integer | 餐次（1早/2午/3下午茶/4晚/5夜宵） |
+| `psnType` | Integer | 人员类别 |
+| `payableAmount` | BigDecimal | 应付金额（分） |
+| `discountsAmount` | BigDecimal | 优惠金额（分，取负数） |
+| `deliveryAmount` | BigDecimal | 配送费（分） |
+| `packingAmount` | BigDecimal | 包装费（分） |
+| `realAmount` | BigDecimal | 实付金额（分） |
+| `accPayAmount` | BigDecimal | 账户支付金额（分） |
+| `outPayAmount` | BigDecimal | 外部支付金额（分） |
+| `refundAmount` | BigDecimal | 累计退款金额（分） |
+| `orderTime` | LocalDateTime | 下单时间 |
+| `orderDate` | LocalDate | 就餐日期 |
+| `orderType` | Integer | 订单类型（1当餐/2预订/3报餐/4扫码/5餐桌/6自助/11商城/12超市/21补扣/22外部） |
+| `orderRefundState` | Integer | 退款状态（1未退/2已退/3部分退） |
+| `payTime` | LocalDateTime | 支付时间 |
+| `payType` | Integer | 支付方式 |
+| `payChannel` | Integer | 支付渠道 |
+| `ageType` | Integer | 年龄段 |
+| `holidayType` | Integer | 节假日类型 |
+| `status` | Integer | 消费状态（0未消费/1已消费） |
+
+## report_order_detail（订单菜品明细表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `detailId` | Long | 明细主键 |
+| `orderId` | Long | 关联订单 ID |
+| `goodsDishesId` | Long | 菜品 ID |
+| `goodsDishesName` | String | 菜品名称 |
+| `salePrice` | BigDecimal | 售卖价格（分） |
+| `prefPrice` | BigDecimal | 优惠价格（分） |
+| `price` | BigDecimal | 最终价格（分） |
+| `weightUnit` | BigDecimal | 每份重量（g） |
+| `quantity` | Integer | 数量/重量 |
+| `salesMode` | Integer | 销售方式（1按份/2称重） |
+| `detailType` | Integer | 类别（1菜品/2套餐/3商品/4按键/5补扣/6报餐） |
+| `totalAmount` | BigDecimal | 总金额（分） |
+| `realAmount` | BigDecimal | 实付金额（分） |
+| `detailState` | Integer | 状态（1正常/2已退菜/3部分退菜） |
+| `goodsRefundNum` | Integer | 已退数量 |
+| `refundAmount` | BigDecimal | 退款金额（分） |
+
+## report_refund（退款主表，标准版特有）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `orderRefundId` | Long | 退款单主键 |
+| `orderId` | Long | 原始订单 ID |
+| `realRefundAmount` | BigDecimal | 退款金额（**正数**） |
+| `applyTime` | LocalDateTime | 申请时间 |
+| `applyType` | Integer | 申请类型（1退单/2纠错） |
+| `checkTime` | LocalDateTime | 审核时间 |
+
+## report_refund_detail（退款明细表，标准版特有）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `orderRefundId` | Long | 退款单 ID |
+| `detailId` | Long | 菜品详情 ID |
+| `realQuantity` | Integer | 退单数量 |
+| `realRefundAmount` | BigDecimal | 退款金额（**正数**） |
+
+## report_account_flow（账户流水主表）
+
+核心字段：`flowId`(主键), `custId`, `orgId`, `payTime`, `flowType`(AccTradeTypeEnum), `flowRealAmount`, `flowAmount`, `manageCost`, `accTotalBal`(可用余额), `accAllBal`(含冻结), `rechargeSource`, `payChannel/payType`, `status`(0未消费/1已消费)
+
+附加字段：`rechargeOperate`(1单人/2批量/3导入/4赠送), `withdrawSource`(1小程序/2web/3openapi/4注销), `operateSource`(1手动清空/2批量/3定时/4注销)
+
+## report_account_flow_detail（流水钱包明细）
+
+字段：`flowId`, `walletId`(1个人/2补贴/4红包), `amount`(转出取负值), `walletBal`, `flowType`, `frozenBalance`, `allWalletBal`
+
+## report_account_summary（用户账户日结表）
+
+联合主键：`statisticDate` + `custId`
+
+**期末余额公式**：
+```
+endAmount = beginAmount
+    + rechargeAmount - rechargeRevokeAmount
+    + subsidyAmount - subsidyRevokeAmount
+    + luckAmount + giftAmount
+    - consumeAmount - consumeRepairAmount
+    + consumeRefundAmount
+    - withdrawAmount - clearAmount - manageCostAmount
+```
+
+附加维度：充值渠道详分（微信/支付宝/现金/银行/第三方）、提现渠道详分、各钱包余额及冻结金额
+
+## report_order_pay（订单支付表）
+
+字段：`orderId`, `payType`, `payChannel`, `outTradeNo`, `payAmount`, `refundAmount`, `payableAmount`
+
+## report_order_discount（订单优惠表）
+
+字段：`orderId`, `changeAmount`, `changeType`(1上浮/2优惠), `changeDetailType`(1上浮/11菜品优惠/12打折/13累计减免/14固定减免)

package/.cursor/skills/leniu-report-scenario/references/total-line.md

@@ -0,0 +1,179 @@
+
+# leniu-tengyun-core 合计行(Total Line)规范
+
+## 项目特征
+
+| 特征 | 说明 |
+|------|------|
+| **包名前缀** | `net.xnzn.core.*` |
+| **JDK 版本** | 21 |
+| **双库切换** | 默认商户库，`Executors.doInSystem()` 切换系统库 |
+| **分页工具** | `PageMethod.startPage()` |
+| **结果封装** | `ReportBaseTotalVO<T>` |
+| **分页封装** | `PageVO.of()` |
+
+## 核心原则
+
+**合计行SQL只返回需要合计的数值字段**，不返回非数值字段（如日期、名称、ID等）。
+
+## Service层实现
+
+### 带合计行的分页查询
+
+```java
+import net.xnzn.core.common.page.PageMethod;
+import net.xnzn.core.common.page.PageVO;
+import net.xnzn.core.common.vo.ReportBaseTotalVO;
+import cn.hutool.core.collection.CollUtil;
+
+// ⚠️ 系统默认在商户库执行，业务查询无需 Executors.readInSystem()
+// Executors.readInSystem() 仅用于需要访问系统库的场景（如全局配置、商户管理）
+
+public ReportBaseTotalVO<XxxVO> pageWithTotal(XxxPageParam param) {
+    ReportBaseTotalVO<XxxVO> result = new ReportBaseTotalVO<>();
+
+    // 1. 导出时不查询合计行(避免不必要的性能开销)
+    if (CollUtil.isEmpty(param.getExportCols())) {
+        XxxVO totalLine = mapper.getSummaryTotal(param);
+        result.setTotalLine(totalLine);
+    }
+
+    // 2. 开启分页
+    PageMethod.startPage(param.getPage());
+
+    // 3. 查询数据
+    List<XxxVO> list = mapper.getSummaryList(param);
+
+    // 4. 封装分页结果
+    result.setResultPage(PageVO.of(list));
+    return result;
+}
+```
+
+### 单独的合计行查询方法
+
+```java
+public XxxVO getSummaryTotal(XxxPageParam param) {
+    // 默认在商户库执行，无需 Executors 包装
+    return mapper.getSummaryTotal(param);
+}
+```
+
+## Mapper XML规范
+
+### 错误示例：返回非数值字段
+
+```xml
+<!-- ❌ 不要这样做 -->
+<select id="getSummaryTotal" resultType="XxxVO">
+    SELECT
+        '合计' AS dateMonth,        <!-- ❌ 不要返回字符串 -->
+        NULL AS schoolId,            <!-- ❌ 不要返回ID -->
+        NULL AS schoolName,          <!-- ❌ 不要返回名称 -->
+        SUM(staffCount) AS staffCount,
+        SUM(amount) AS amount
+    FROM xxx_table
+</select>
+```
+
+### 正确示例：只返回数值字段
+
+```xml
+<!-- ✅ 正确做法 -->
+<select id="getSummaryTotal" resultType="XxxVO">
+    SELECT
+        SUM(staff_count) AS staffCount,
+        SUM(basic_salary) AS basicSalary,
+        SUM(overtime_salary) AS overtimeSalary,
+        SUM(personal_actual_amount) AS personalActualAmount,
+        CASE
+            WHEN SUM(staff_count) = 0 THEN 0
+            ELSE SUM(avg_salary) / COUNT(DISTINCT tenant_id)
+        END AS avgSalary
+    FROM xxx_table
+    <where>
+        del_flag = 2
+        <if test="startDate != null">
+            AND crtime >= #{startDate}
+        </if>
+        <if test="endDate != null">
+            AND crtime &lt;= #{endDate}
+        </if>
+    </where>
+</select>
+```
+
+## 常见合计字段类型
+
+| 字段类型 | 示例 | 合计方式 |
+|---------|------|---------|
+| 数量 | `staff_count`, `order_count` | `SUM()` |
+| 金额 | `amount`, `salary` | `SUM()` |
+| 百分比 | `discount_rate` | `AVG()` 或 `SUM() / COUNT()` |
+| 计数 | `COUNT(DISTINCT id)` | 直接使用 |
+
+## 特殊处理：平均值
+
+```xml
+<!-- 简单平均值 -->
+SELECT AVG(amount) AS avgAmount
+
+<!-- 加权平均值 -->
+SELECT
+    CASE
+        WHEN SUM(count) = 0 THEN 0
+        ELSE SUM(amount * count) / SUM(count)
+    END AS weightedAvgAmount
+
+<!-- 按维度平均 -->
+SELECT
+    CASE
+        WHEN COUNT(DISTINCT tenant_id) = 0 THEN 0
+        ELSE SUM(total_amount) / COUNT(DISTINCT tenant_id)
+    END AS avgByTenant
+```
+
+## Controller层实现
+
+```java
+@PostMapping("/page")
+@ApiOperation("分页查询（带合计）")
+@RequiresAuthentication
+public ReportBaseTotalVO<XxxVO> page(@RequestBody LeRequest<XxxParam> request) {
+    XxxParam param = request.getContent();
+    return xxxService.pageWithTotal(param);
+}
+
+@GetMapping("/total")
+@ApiOperation("单独查询合计行")
+@RequiresAuthentication
+public XxxVO getTotal(XxxParam param) {
+    return xxxService.getSummaryTotal(param);
+}
+```
+
+## 导出时合计行处理
+
+```java
+public void exportExcel(XxxParam param, HttpServletResponse response) {
+    // 导出时需要查询合计行
+    XxxVO totalLine = mapper.getSummaryTotal(param);
+
+    // 分页查询所有数据（不分页）
+    param.getPage().setSize(Integer.MAX_VALUE);
+    List<XxxVO> list = mapper.getSummaryList(param);
+
+    // 将合计行添加到列表末尾
+    list.add(totalLine);
+
+    // 导出
+    exportService.export(list, response);
+}
+```
+
+## 注意事项
+
+- 合计SQL只返回数值字段，不返回字符串、ID、名称等
+- 业务查询默认在商户库执行，无需 `Executors` 包装；仅访问系统库数据时才使用 `Executors.doInSystem()`
+- 导出时通过 `exportCols` 判断是否需要合计行
+- 金额字段类型与 Entity 保持一致：订单模块用 `BigDecimal`，钱包模块用 `Long`（详见 leniu-java-amount-handling）