ai-engineering-init 1.14.0 → 1.14.2

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

@@ -0,0 +1,356 @@
+# 汇总表定制开发指南
+
+> 本文件按需加载：当需要新建汇总表（实现 MQ 消费 + fix 重算）时读取。
+
+---
+
+## 一、报表系统架构
+
+### 两阶段消费模型
+
+```
+MQ 消息到达（下单/退款）
+    ↓
+第一阶段（ORDER < 10，同步写基础表）
+    ├── ORDER=1  ReportOrderInfoService     → report_order_info
+    ├── ORDER=3  ReportOrderDetailService   → report_order_detail
+    └── ORDER=5  ReportRefundService        → report_refund / report_refund_detail
+    ↓
+第二阶段（ORDER >= 10，汇总表处理）
+    ├── ORDER=10 ReportSumOrganizationService → 组织汇总
+    ├── ORDER=11 ReportSumCanteenService      → 食堂汇总
+    ├── ORDER=12 ReportSumTypeService         → 用户类别汇总
+    ├── ORDER=13 ReportSumPayService          → 支付汇总
+    ├── ORDER=14 ReportSumMealtimeService     → 餐次汇总
+    ├── ORDER=30 ReportSumDishesService       → 菜品销售汇总
+    ├── ORDER=50 ReportAnalysisCustService    → 用户分析
+    └── ORDER=51 ReportAnalysisDishesSaleService → 菜品销售分析
+```
+
+### v5.29 vs 标准版的第二阶段差异
+
+| 版本 | 第二阶段模式 | 核心方法 |
+|------|-------------|---------|
+| v5.29 | `batchConsume()` 增量累加 | 分组 → 查存量 → 累加/新建 |
+| 标准版 | `fix()` 按日重算 | 先删后插，从基础表重新聚合 |
+
+---
+
+## 二、ReportOrderConsumeService 接口
+
+```java
+public interface ReportOrderConsumeService extends Ordered {
+
+    // 单笔消费（第一阶段基础表使用）
+    void consume(OrderChangePO payload, ReportOrderInfoDTO baseInfo);
+
+    // 批量消费（第二阶段汇总表使用）
+    default void batchConsume(List<ReportOrderConsumeDTO> consumeList) { }
+
+    // 批量菜品消费
+    default void batchDishesConsume(List<ReportOrderDishesConsumeDTO> consumeList) { }
+
+    // 数据修复：删除时间段内数据并重新聚合
+    void fix(ReportBaseParam param);
+}
+```
+
+---
+
+## 三、实现汇总 Service（v5.29 batchConsume 模式）
+
+```java
+@Service
+@Slf4j
+public class ReportSumXxxService implements ReportOrderConsumeService {
+
+    @Autowired
+    private ReportSumXxxMapper reportSumXxxMapper;
+
+    @Override
+    public int getOrder() { return 15; } // 10-29普通, 30+菜品, 50+分析
+
+    @Override
+    public void consume(OrderChangePO payload, ReportOrderInfoDTO baseInfo) {
+        // 汇总表通常留空
+    }
+
+    @Override
+    public void batchConsume(List<ReportOrderConsumeDTO> list) {
+        // 1. 按维度分组（使用 KEY_SPLIT = "~~~~"）
+        Map<String, List<ReportOrderConsumeDTO>> grouped = list.stream()
+            .collect(Collectors.groupingBy(o ->
+                o.getPayTime().toLocalDate() + CommonConstants.KEY_SPLIT +
+                o.getCanteenId() + CommonConstants.KEY_SPLIT +
+                o.getStallId() + CommonConstants.KEY_SPLIT +
+                o.getMealtimeType()
+            ));
+
+        List<ReportSumXxx> insertList = new ArrayList<>();
+        List<ReportSumXxx> updateList = new ArrayList<>();
+
+        for (Map.Entry<String, List<ReportOrderConsumeDTO>> entry : grouped.entrySet()) {
+            String[] keys = entry.getKey().split(CommonConstants.KEY_SPLIT, -1);
+            LocalDate statisticDate = SafeTypeConvertUtil.parseLocalDateSafe(keys[0]);
+            Long canteenId = SafeTypeConvertUtil.parseLongSafe(keys[1]);
+            Long stallId = SafeTypeConvertUtil.parseLongSafe(keys[2]);
+            Integer mealtimeType = SafeTypeConvertUtil.parseIntSafe(keys[3]);
+
+            // 2. 查询是否存在
+            ReportSumXxx existing = reportSumXxxMapper.selectOne(
+                Wrappers.<ReportSumXxx>lambdaQuery()
+                    .eq(ReportSumXxx::getStatisticDate, statisticDate)
+                    .eq(ReportSumXxx::getCanteenId, canteenId)
+                    .eq(ReportSumXxx::getStallId, stallId)
+                    .eq(ReportSumXxx::getMealtimeType, mealtimeType)
+            );
+
+            ReportSumXxx record;
+            if (existing == null) {
+                record = new ReportSumXxx();
+                record.setId(Id.next());
+                record.setStatisticDate(statisticDate);
+                record.setCanteenId(canteenId);
+                record.setStallId(stallId);
+                record.setMealtimeType(mealtimeType);
+                insertList.add(record);
+            } else {
+                record = existing;
+                updateList.add(record);
+            }
+
+            // 3. 累加金额（参考 ReportSumCanteen.generateSummary）
+            for (ReportOrderConsumeDTO dto : entry.getValue()) {
+                record.setConsumeNum(dto.getCancelFlag() == 1
+                    ? record.getConsumeNum() - 1
+                    : record.getConsumeNum() + 1);
+                record.setRealAmount(record.getRealAmount().add(dto.getRealAmount()));
+                record.setRefundAmount(record.getRefundAmount().add(dto.getRealRefundAmount()));
+            }
+        }
+
+        // 4. 批量写入
+        if (CollUtil.isNotEmpty(insertList)) {
+            reportSumXxxMapper.insert(insertList);
+        }
+        if (CollUtil.isNotEmpty(updateList)) {
+            reportSumXxxMapper.updateById(updateList);
+        }
+    }
+
+    @Override
+    public void fix(ReportBaseParam param) {
+        // 先删后插
+        reportSumXxxMapper.delete(Wrappers.<ReportSumXxx>lambdaQuery()
+            .between(ReportSumXxx::getStatisticDate,
+                param.getStartDate(), param.getEndDate()));
+        reportSumXxxMapper.initFix(param.getStartDate(), param.getEndDate());
+    }
+}
+```
+
+---
+
+## 四、实现汇总 Service（标准版 fix 模式）
+
+```java
+@Service
+@Slf4j
+public class ReportSumXxxService implements ReportOrderConsumeService {
+
+    @Override
+    public int getOrder() { return 15; }
+
+    @Override
+    public void consume(OrderChangePO payload, ReportOrderInfoDTO baseInfo) {
+        // 标准版留空，由 fix() 统一处理
+    }
+
+    @Override
+    public void fix(ReportBaseParam param) {
+        LocalDateTime start = param.getStartPayTime();
+        LocalDateTime end = param.getEndPayTime();
+        reportSumXxxMapper.delete(Wrappers.<ReportSumXxx>lambdaQuery()
+            .between(ReportSumXxx::getStatisticDate,
+                start.toLocalDate(), end.toLocalDate()));
+        reportSumXxxMapper.initFix(start, end);
+    }
+}
+```
+
+---
+
+## 五、fix SQL 模板（initFix）
+
+```xml
+<insert id="initFix">
+    INSERT INTO report_sum_xxx (id, statistic_date, canteen_id, canteen_name,
+        stall_id, stall_name, order_count, consume_amount, refund_amount, net_amount,
+        crby, crtime, upby, uptime, del_flag)
+    SELECT
+        #{id},
+        DATE(a.pay_time),
+        a.canteen_id,
+        a.canteen_name,
+        a.stall_id,
+        a.stall_name,
+        COUNT(*),
+        SUM(CASE WHEN a.consume_type = 1 THEN a.real_amount ELSE 0 END),
+        SUM(CASE WHEN a.consume_type = 2 THEN ABS(a.real_refund_amount) ELSE 0 END),
+        SUM(a.real_amount) + SUM(IFNULL(a.real_refund_amount, 0)),
+        'system', NOW(), 'system', NOW(), 2
+    FROM report_order_info a
+    WHERE a.pay_time BETWEEN #{startTime} AND #{endTime}
+    GROUP BY DATE(a.pay_time), a.canteen_id, a.canteen_name, a.stall_id, a.stall_name
+</insert>
+```
+
+**标准版 initFix**（无 consumeType，退款用 refundAmount）：
+```xml
+<insert id="initFix">
+    INSERT INTO report_sum_xxx (...)
+    SELECT
+        #{id}, DATE(a.pay_time), a.canteen_id, a.canteen_name,
+        COUNT(*),
+        SUM(a.real_amount),
+        SUM(IFNULL(a.refund_amount, 0)),
+        SUM(a.real_amount - IFNULL(a.refund_amount, 0))
+    FROM report_order_info a
+    WHERE a.pay_time BETWEEN #{startTime} AND #{endTime}
+    GROUP BY DATE(a.pay_time), a.canteen_id, a.canteen_name
+</insert>
+```
+
+---
+
+## 六、消费调度器（ReportConsumerService）
+
+```
+POST /summary/fix/order → ReportFixController
+  ├─ 校验日期范围（≤31天）
+  └─ Executors.doInTenant(tenantId, () → ReportFixService.fix(param))
+      → 遍历所有 ReportOrderConsumeService 实现类
+      → 按 ORDER 排序，逐个调用 fix()
+
+MQ 消费触发 → ReportConsumerService.consumeOrderReport()
+  ├─ 获取所有正常商户
+  ├─ 对每个商户获取 Redisson 分布式锁
+  ├─ 分片查询待消费数据（每批 1000 条）
+  └─ 按 ORDER 排序，调用 batchConsume()
+```
+
+---
+
+## 七、汇总 Entity 模板
+
+```java
+@Data
+@TableName("report_sum_xxx")
+@ApiModel("XXX汇总表")
+public class ReportSumXxx {
+
+    @TableId
+    private Long id;
+
+    // 维度字段
+    private LocalDate statisticDate;
+    private Long areaId, canteenId, stallId, orgId;
+    private String areaName, canteenName, stallName, orgFullId, orgFullName;
+    private Integer mealtimeType;
+
+    // 统计字段（单位：分，初始值 ZERO）
+    private Integer custNum = 0;
+    private Integer consumeNum = 0;
+    private BigDecimal payableAmount = BigDecimal.ZERO;
+    private BigDecimal realAmount = BigDecimal.ZERO;
+    private BigDecimal refundAmount = BigDecimal.ZERO;
+    private BigDecimal totalAmount = BigDecimal.ZERO;
+
+    // 审计字段
+    private String crby, upby;
+    private LocalDateTime crtime, uptime;
+    private Integer delFlag;
+}
+```
+
+---
+
+## 八、建表模板
+
+```sql
+CREATE TABLE report_sum_xxx (
+    id               BIGINT       NOT NULL COMMENT '主键（雪花ID）',
+    statistic_date   DATE                  COMMENT '统计日期',
+    area_id          BIGINT                COMMENT '区域ID',
+    area_name        VARCHAR(128)          COMMENT '区域名称',
+    canteen_id       BIGINT                COMMENT '食堂ID',
+    canteen_name     VARCHAR(128)          COMMENT '食堂名称',
+    stall_id         BIGINT                COMMENT '档口ID',
+    stall_name       VARCHAR(128)          COMMENT '档口名称',
+    org_id           BIGINT                COMMENT '组织ID',
+    org_full_name    VARCHAR(512)          COMMENT '组织全名',
+    mealtime_type    INT                   COMMENT '餐次类型',
+    cust_num         INT         DEFAULT 0 COMMENT '消费人数',
+    consume_num      INT         DEFAULT 0 COMMENT '消费次数',
+    payable_amount   DECIMAL(18,2) DEFAULT 0 COMMENT '应付金额（分）',
+    real_amount      DECIMAL(18,2) DEFAULT 0 COMMENT '实付金额（分）',
+    refund_amount    DECIMAL(18,2) DEFAULT 0 COMMENT '退款金额（分）',
+    total_amount     DECIMAL(18,2) DEFAULT 0 COMMENT '合计金额（分）',
+    crby             VARCHAR(64)           COMMENT '创建人',
+    crtime           DATETIME              COMMENT '创建时间',
+    upby             VARCHAR(64)           COMMENT '更新人',
+    uptime           DATETIME              COMMENT '更新时间',
+    del_flag         INT         DEFAULT 2 COMMENT '删除标识(1-删除,2-正常)',
+    PRIMARY KEY (id),
+    INDEX idx_statistic_date (statistic_date),
+    INDEX idx_canteen (canteen_id, stall_id)
+) COMMENT='XXX汇总表';
+```
+
+---
+
+## 九、账户流水汇总
+
+实现 `ReportAccountConsumeService` 接口（类似订单版），数据源为 `report_account_flow`。
+
+```sql
+SELECT d.wallet_id,
+    SUM(CASE WHEN d.flow_type = 110 THEN ABS(d.amount) ELSE 0 END) AS consumeAmount,
+    SUM(CASE WHEN d.flow_type = 130 THEN d.amount ELSE 0 END) AS refundAmount
+FROM report_account_flow f
+JOIN report_account_flow_detail d ON f.flow_id = d.flow_id
+WHERE f.pay_time BETWEEN #{startTime} AND #{endTime}
+GROUP BY d.wallet_id
+```
+
+---
+
+## 十、开发检查清单
+
+### 建表
+- [ ] 维度字段 + 金额汇总字段 + 审计字段（crby/crtime/upby/uptime/del_flag），无 tenant_id
+
+### 实现
+- [ ] 实现 `ReportOrderConsumeService`，设置 `getOrder()` 值
+- [ ] v5.29：实现 `batchConsume()`（分组 → 查存量 → 累加/新建）
+- [ ] 标准版：实现 `fix()`（先删后插）
+- [ ] 两个版本都实现 `fix()` 方法
+
+### 退款
+- [ ] v5.29：`consumeType=2` 退款金额为负数，直接 SUM
+- [ ] 标准版：`report_refund` 独立表，退款金额为正数
+
+### SQL 合规（only_full_group_by）
+- [ ] SELECT 非聚合字段全部在 GROUP BY 中
+- [ ] GROUP BY 表达式与 SELECT 完全一致
+
+### 关键代码位置（标准版 core-report）
+
+| 类型 | 路径前缀 `core-report/.../statistics/` |
+|------|------|
+| MQ 监听器 | `config/mq/ReportOrderMQListener.java` |
+| 消费调度 | `config/mq/service/ReportConsumerService.java` |
+| ConsumeService 接口 | `config/mq/ReportOrderConsumeService.java` |
+| 食堂汇总 | `order/summary/service/ReportSumCanteenService.java` |
+| 餐次汇总 | `order/summary/service/ReportSumMealtimeService.java` |
+| Fix Controller | `order/fix/controller/ReportFixController.java` |

package/.claude/skills/leniu-report-scenario/references/data-permission.md

@@ -0,0 +1,182 @@
+# 报表数据权限集成
+
+> 本文件按需加载：当报表需要数据权限过滤时读取。默认不加载。
+
+---
+
+## 一、权限模型
+
+### ReportDataPermissionParam
+
+```java
+@Data
+public class ReportDataPermissionParam {
+    private List<Long> areaIdList;      // 区域权限
+    private List<Long> orgIdList;       // 机构权限
+    private List<Long> canteenIdList;   // 食堂权限
+    private List<Long> stallIdList;     // 档口权限
+    private Integer roleType;           // 权限类型
+}
+```
+
+### 权限类型
+
+| roleType | 含义 | 过滤维度 |
+|----------|------|---------|
+| -1 | 超级管理员 | 不过滤 |
+| 1 | 区域权限 | areaIdList |
+| 2 | 机构权限 | orgIdList |
+| 3 | 食堂权限 | canteenIdList |
+| 4 | 档口权限 | stallIdList |
+| 5 | 食堂+档口权限 | canteenIdList + stallIdList |
+
+---
+
+## 二、Service 层集成
+
+```java
+@Service
+@Slf4j
+public class XxxReportService {
+
+    @Autowired
+    private MgrAuthV2Api mgrAuthApi;
+    @Autowired
+    private ReportDataPermissionService reportDataPermissionService;
+    @Autowired
+    private AsyncTaskExecutor asyncTaskExecutor;
+
+    public ReportBaseTotalVO<XxxVO> pageWithTotal(XxxParam param) {
+        // 1. 获取用户权限
+        MgrUserAuthPO authPO = mgrAuthApi.getUserAuthPO();
+        ReportDataPermissionParam permission =
+            reportDataPermissionService.getDataPermission(authPO);
+
+        // 2. 并行查询（携带权限参数）
+        CompletableFuture<Long> countF = CompletableFuture.supplyAsync(
+            () -> mapper.listSummary_COUNT(param, authPO, permission), asyncTaskExecutor);
+        CompletableFuture<List<XxxVO>> listF = CompletableFuture.supplyAsync(() -> {
+            PageMethod.startPage(param.getPage());
+            return mapper.listSummaryPage(param, authPO, permission);
+        }, asyncTaskExecutor);
+        CompletableFuture<XxxVO> totalF = CompletableFuture.supplyAsync(
+            () -> mapper.getSummaryTotal(param, authPO, permission), asyncTaskExecutor);
+        CompletableFuture.allOf(countF, listF, totalF).join();
+
+        PageVO<XxxVO> pageVO = PageVO.of(listF.join());
+        pageVO.setTotal(countF.join());
+        return new ReportBaseTotalVO<XxxVO>()
+            .setResultPage(pageVO)
+            .setTotalLine(totalF.join());
+    }
+}
+```
+
+---
+
+## 三、Mapper 签名
+
+```java
+public interface XxxReportMapper extends BaseMapper<ReportSumXxx> {
+
+    List<XxxVO> listSummaryPage(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+
+    XxxVO getSummaryTotal(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+
+    Long listSummary_COUNT(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+}
+```
+
+---
+
+## 四、XML 权限 SQL
+
+### 方式一：引用公共权限片段
+
+```xml
+<sql id="baseWhere">
+    WHERE a.del_flag = 2
+    <if test="param.startDate != null">
+        AND a.statistic_date >= #{param.startDate}
+    </if>
+    <if test="param.endDate != null">
+        AND a.statistic_date &lt;= #{param.endDate}
+    </if>
+    <!-- 引入数据权限 -->
+    <include refid="net.xnzn.core.report.statistics.common.mapper.ReportDataPermissionMapper.dataPermission"/>
+</sql>
+```
+
+### 方式二：内联权限判断
+
+```xml
+<!-- 超级管理员不过滤 -->
+<if test="'-1'.toString() != authPO.roleType.toString()">
+    AND EXISTS (
+        SELECT null FROM mgr_role_org it1
+        WHERE a.org_id = it1.org_id
+        AND it1.role_id = #{authPO.roleId}
+    )
+</if>
+
+<!-- 食堂权限过滤 -->
+<if test="dataPermission.canteenIdList != null and dataPermission.canteenIdList.size() > 0">
+    AND a.canteen_id IN
+    <foreach collection="dataPermission.canteenIdList" item="id" open="(" separator="," close=")">
+        #{id}
+    </foreach>
+</if>
+
+<!-- 档口权限过滤 -->
+<if test="dataPermission.stallIdList != null and dataPermission.stallIdList.size() > 0">
+    AND a.stall_id IN
+    <foreach collection="dataPermission.stallIdList" item="id" open="(" separator="," close=")">
+        #{id}
+    </foreach>
+</if>
+```
+
+---
+
+## 五、Controller 层（带权限的导出）
+
+```java
+@PostMapping("/export")
+@ApiOperation("导出（含权限）")
+public void export(@RequestBody LeRequest<XxxParam> request) {
+    XxxParam param = request.getContent();
+
+    // 获取权限（导出也需要权限过滤）
+    MgrUserAuthPO authPO = mgrAuthApi.getUserAuthPO();
+    ReportDataPermissionParam permission =
+        reportDataPermissionService.getDataPermission(authPO);
+
+    XxxVO totalLine = mapper.getSummaryTotal(param, authPO, permission);
+
+    exportApi.startExcelExportTaskByPage(
+        I18n.getMessage("report.xxx.title"),
+        I18n.getMessage(ReportConstant.REPORT_TITLE_DETAILS),
+        XxxVO.class,
+        param.getExportCols(),
+        param.getPage(),
+        totalLine,
+        () -> {
+            PageMethod.startPage(param.getPage());
+            List<XxxVO> list = mapper.listSummaryPage(param, authPO, permission);
+            return PageVO.of(list);
+        }
+    );
+}
+```

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`，期末余额 = 期初 + 充值 - 撤销 + 补贴 - 消费 + 退款 - 提现