# 商家前端账单功能需求

## 背景

平台管理后台已有账单管理页面（`Billing/billing/index`），但商家前端（foodie-store）缺少账单功能。需要为商家前端新增"财务管理"模块，包含账单查询功能。

## 用户类型与权限

| userType | 角色 | 账单可见范围 |
|----------|------|-------------|
| 1 | 商家 | 自己名下所有门店的账单（user_id 查询，可选按 mdId 筛选） |
| 4 | 摊位主/门店 | 仅自己关联门店的账单（md_id 过滤） |

## 数据模型

### UserBilling 表（已有，无需变更）

已有 `md_id` 字段，账单记录创建时会写入门店 ID。

### 账单类型

| type | 含义 |
|------|------|
| 0 | 分成（收入） |
| 1 | 充值 |
| 2 | 提现 |
| 3 | 消费 |
| 4 | 金额冻结 |
| 5 | 金额解冻 |
| 6 | 抽成返还 |

### 账单状态

| state | 含义 |
|-------|------|
| 0 | 完成 |
| 1 | 退回 |
| 2 | 作废 |
| 3 | 未支付 |

## 后端接口

### 新增接口

#### 1. GET /billing/storeBillingList — 商家端账单列表

参数：
- `mdId`（可选）— 按门店筛选
- `type`（可选）— 账单类型
- `startDate` / `endDate`（可选）— 时间范围
- `pageNum` / `pageSize` — 分页

权限逻辑：
- userType=1（商家）：查 `user_billing WHERE user_id = 当前用户`，可选按 mdId 筛选
- userType=4（摊位主）：查 `info_user.store_id` 获取门店 → 查 `user_billing WHERE md_id = 门店ID`

返回：分页账单列表 + 门店信息

#### 2. GET /billing/storeBillingSummary — 商家端账单汇总

参数同上。

返回：`{ totalAmount, totalDivvy, netIncome }`

### 修改接口

现有 `getzddaylist`、`getzdmeeklist`、`getzdmatlist` 查询需增加 `mdId` 可选过滤条件。

#### GET /billing/getzddaylist（修改）

新增参数：
- `mdId`（可选）— 按门店筛选

影响范围：
- `UserBillingMapper.getdaylist` — SQL 增加 `(#{mdId} IS NULL OR md_id = #{mdId})`
- `UserBillingMapper.getdaysum` — SQL 增加 `(#{mdId} IS NULL OR md_id = #{mdId})`
- `UserBillingMapper.getShDaysum` — SQL 增加 `(#{mdId} IS NULL OR b.md_id = #{mdId})`

#### GET /billing/getzdmeeklist（修改）

新增参数：
- `mdId`（可选）— 按门店筛选

影响范围：
- `UserBillingMapper.getmeeklist` — SQL 增加 `(#{mdId} IS NULL OR md_id = #{mdId})`
- `UserBillingMapper.getmeeksum` — SQL 增加 `(#{mdId} IS NULL OR md_id = #{mdId})`
- `UserBillingMapper.getShMeeksum` — SQL 增加 `(#{mdId} IS NULL OR b.md_id = #{mdId})`

#### GET /billing/getzdmatlist（修改）

新增参数：
- `mdId`（可选）— 按门店筛选

影响范围：
- `UserBillingMapper.getmatlist` — SQL 增加 `(#{mdId} IS NULL OR md_id = #{mdId})`
- `UserBillingMapper.getmatsum` — SQL 增加 `(#{mdId} IS NULL OR md_id = #{mdId})`
- `UserBillingMapper.getshMonthsum` — SQL 增加 `(#{mdId} IS NULL OR b.md_id = #{mdId})`

## 前端功能

### 新增菜单目录：财务管理

```
财务管理
  └── 账单管理
```

### 账单管理页面

1. **筛选条件**
   - 门店选择（下拉框，商家可切换门店，摊位主只显示自己门店）
   - 账单类型（分成、充值、提现、消费、冻结、解冻、抽成返还）
   - 时间范围选择器

2. **汇总区域**
   - 显示筛选范围内的总金额、总抽成、净收入

3. **账单列表表格**
   - 列：订单号、账单类型、金额、抽成、净收入、门店名称、状态、时间、说明
   - 支持分页

4. **权限区分**
   - 商家（userType=1）：顶部显示门店选择下拉框，可切换查看不同门店
   - 摊位主/门店（userType=4）：无门店选择，自动只显示自己门店数据

## 相关路径

- 商家前端页面：`E:\QtwCode\foodie\foodie-store`
- 管理后台账单页面（参考）：`E:\QtwCode\foodie\foodie-admin-vue\src\views\Billing\billing\index.vue`

## 后端实现状态

| 接口 | 状态 | 说明 |
|------|------|------|
| `GET /billing/storeBillingList` | 已完成 | 商家端账单列表，分页、筛选、权限逻辑 |
| `GET /billing/storeBillingSummary` | 已完成 | 账单汇总，返回 totalAmount/totalDivvy/netIncome |
| `GET /billing/getzddaylist` | 已完成 | 日账单，支持 mdId 可选过滤 |
| `GET /billing/getzdmeeklist` | 已完成 | 周账单，支持 mdId 可选过滤 |
| `GET /billing/getzdmatlist` | 已完成 | 月账单，支持 mdId 可选过滤 |

### 涉及文件

- `ruoyi-admin/src/main/java/com/ruoyi/app/pay/UserBillingController.java` — 控制器
- `ruoyi-system/src/main/java/com/ruoyi/system/mapper/UserBillingMapper.java` — Mapper SQL

### 实现说明

mdId 过滤采用 `(#{mdId} IS NULL OR md_id = #{mdId})` 模式，mdId 不传时查询全部数据，传入时按门店过滤。涉及 join 查询的方法使用表别名前缀 `b.md_id`。