# 账务管理 — 财务与订单关联说明

> **范围：** 当前已实现的后端财务模块（`com.ruoyi.web.modules.finance`）与 **订单模块** 的协作关系。  
> **关联文档：** 《资金概览功能需求.md》v1.0、《提现管理功能需求.md》v1.0、《提现审核功能需求.md》v1.0、《提现审核技术方案.md》v1.0、《关联需求分析.md》v1.6。  
> **说明：** 本文档描述 **现状设计口径** 与 **代码挂点**；退款/关单冲正等 **非本期** 能力单独标注。

---

## 1. 总体关系

财务与订单是 **单向、时点触发** 的协作：**订单提供资金来源，提现消耗已结算余额**；二者 **没有** 表级外键或「某笔提现绑定某笔订单」的设计。

```text
C 端支付成功
    → 订单：待发货(1) / 已发货(2)
    → 不计入「可用余额」，仅计入「待结算」（实时查订单表）

买家确认收货（O7）
    → 订单：已完成(3)
    → settleOrder() → 可用余额 +实付，写入「订单收支」流水

商家提现
    → 仅扣减「可用余额」，与具体订单无绑定
```

| 维度 | 订单 | 财务 |
|------|------|------|
| 角色 | 资金来源 | 虚拟账（余额 / 冻结 / 流水） |
| 写入时机 | 支付、发货、确认收货等 | **仅确认收货** 写余额；提现写冻结 |
| 关联方式 | — | 流水 `biz_no` = 订单号；`ref_type=ORDER` + `ref_id=order_id` |

---

## 2. 代码挂点

### 2.1 确认收货 → 结算入账（唯一写余额的订单入口）

**触发路径：** C 端 `OrderAppServiceImpl.confirmReceive` → `IShopFundService.settleOrder(order)`。

**执行顺序：**

1. 更新 `biz_order` 为 **已完成(3)**；
2. 插入物流轨迹；
3. 调用 `shopFundService.settleOrder(order)`；
4. 刷新会员累计消费。

**`settleOrder` 规则：**

| 项 | 规则 |
|----|------|
| 结算金额 | `biz_order.pay_amount`（实付） |
| 店铺隔离 | `order.shop_id` |
| 幂等 | `biz_shop_fund_log` 中已存在 `ref_type=ORDER` 且 `ref_id=order_id` 则跳过 |
| 钱包 | `biz_shop_wallet.available_balance += pay_amount` |
| 流水 | 变动原因 **订单收支**；`biz_no = order_no`；`ref_type=ORDER`，`ref_id=order_id` |

**实现位置：**

- 订单侧：`baqing-shop/.../order/service/impl/OrderAppServiceImpl.java`（`confirmReceive`）
- 财务侧：`baqing-shop/.../finance/service/impl/ShopFundServiceImpl.java`（`settleOrder`）

> **注意：** 目前 **仅 C 端买家确认收货** 会调用 `settleOrder`。商家发货、平台改单等路径 **尚未** 接入财务结算。

### 2.2 待结算 → 实时汇总订单（不落库）

**资金概览** 中的「待结算金额」 **不写入** `biz_shop_wallet`，每次查询 `biz_order` 汇总：

```sql
SELECT IFNULL(SUM(pay_amount), 0)
FROM biz_order
WHERE shop_id = #{shopId}
  AND pay_status = '1'
  AND order_status IN ('1', '2')   -- 待发货、已发货
  AND del_flag = '0'
```

**实现位置：** `BizOrderMapper.sumPendingSettleByShopId` → `ShopFundServiceImpl.getPendingSettleAmount` / `getOverviewSummary`。

---

## 3. 订单状态与资金口径对照

| 订单状态 | 代码值 | 待结算 | 可用余额 | 资金流水 |
|----------|--------|--------|----------|----------|
| 待支付 | `0` | 否 | 不变 | 无 |
| 待发货 | `1` | **计入** | 不变 | 无 |
| 已发货 | `2` | **计入** | 不变 | 无 |
| 已完成 | `3` | 不再计入 | **+实付** | **订单收支** |
| 已关闭 | `4` | 视是否曾支付 | 不变* | 无 |

\* **已支付后关单、退款、售后** 在本期 **未** 接入财务，不会自动冲减余额或写负向流水。

---

## 4. 与提现模块的关系

- **提现** 仅校验 `available_balance`，与订单 **无直接外键**。
- **订单流水** 与 **提现流水** 均记在 `biz_shop_fund_log`，通过 **业务编号** 区分：
  - 订单：`biz_no` = **订单编号**
  - 提现：`biz_no` = **提现编号**
- `biz_shop_withdraw` **不含** `order_id` 字段；提现与订单为 **间接关系**（先订单入账 → 再提现出账）。

**提现相关流水（与订单独立）：**

| 动作 | 变动原因 | 余额 | 冻结 |
|------|----------|------|------|
| 商家提交提现 | 余额提现 | − | + |
| 平台审核通过 | 提现完成 | 不变 | − |
| 平台审核驳回 | 提现驳回 | + | − |

---

## 5. 数据表协作一览

| 表 | 与订单关系 |
|----|------------|
| `biz_order` | 待结算汇总源；`pay_amount` 为结算金额 |
| `biz_shop_wallet` | 按 `shop_id` 存可用余额、冻结；**不存待结算** |
| `biz_shop_fund_log` | 订单结算：`ref_type=ORDER`，`ref_id=order_id`，`biz_no=order_no` |
| `biz_shop_withdraw` | 与订单 **无字段关联** |

---

## 6. 端到端资金流（含订单）

```text
【用户链 · 订单】
    下单 → 支付成功 → 待发货/已发货
        → 待结算 ↑（查订单，不写流水）
    → 买家确认收货 → 已完成
        → 订单收支流水；可用余额 ↑；待结算 ↓（该单从汇总中移除）

【商家 · 财务】
    可用余额 > 0 → 提现管理提交
        → 余额提现流水；余额 ↓；冻结 ↑
    → 平台提现审核
        → 通过：提现完成，冻结 ↓
        → 驳回：提现驳回，余额 ↑，冻结 ↓
```

---

## 7. 本期未关联的订单场景

以下场景在需求中标注为 **非本期** 或 **尚未实现**，当前 **不影响** 或 **不完整影响** 店铺虚拟账：

| 场景 | 现状 |
|------|------|
| 支付成功 | 不写流水；仅通过订单状态进入「待结算」汇总 |
| 待支付超时关单 | 无资金影响 |
| 已支付关单 | 不回滚待结算外的余额；无冲正流水 |
| C 端 / 渠道退款 | 不扣减可用余额；无负向流水 |
| 售后完结 | 不自动写收支概况 |
| 平台 / 商家代确认收货 | 若不走 C 端 `confirmReceive`，则 **不会** 触发 `settleOrder` |

---

## 8. 业务规则摘要

| 编号 | 规则 |
|------|------|
| **ACCT-O1** | **订单收支** 仅在 **买家确认收货 → 已完成** 时产生 |
| **ACCT-O2** | 结算金额 = 订单 **实付**（`pay_amount`） |
| **ACCT-O3** | **待结算** = 已支付且 **待发货 + 已发货** 订单实付合计（实时查 `biz_order`） |
| **ACCT-O4** | 支付成功 **不** 直接增加可用余额 |
| **ACCT-O5** | 同一订单 **至多一条** 订单收支流水（`ref_type=ORDER` 幂等） |
| **ACCT-O6** | 提现 **不绑定** 订单；仅消费 **可用余额** |
| **ACCT-O7** | 退款 / 关单 / 售后与余额 **联动规则非本期** |

---

## 9. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：整理财务模块与订单的关联口径、代码挂点、状态对照及非本期边界 |

---

*文档版本：v1.0 · 依据当前后端实现（finance 包 + OrderAppServiceImpl.confirmReceive）*
