# 商家前端账单功能需求

## 背景

平台管理后台已有账单管理页面（`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`。

## 2026-11-04 取消订单账单抽成及骑手税费

- 平台不再从新生成的商家和骑手订单收入账单扣除抽成；骑手也不再按 `sys_qs_freight_bl` 扣税费。旧的用户抽成比例、商家分成配置和骑手税率配置不参与本次结算。
- 商家商品收入保留现有商品优惠和运费划分：版本2按 `amount - customerDeliveryFee`；旧订单按原商品金额及商家优惠口径。该金额全额入账，摊位仍入摊位钱包。
- 骑手按订单 `freight` 全额入账，到付代收金额和账单防重复规则保持。闪送含小费全额收入、自配送运费全额收入沿用现有实现。
- 新账单 `divvy=0`、`divvyRate=0`；骑手另记 `tax=0`、`taxRate="0"`。商家账单响应当前 `commissionRate=0`，骑手响应当前 `taxRate="0"`。历史明细及汇总仍读取原账单，不抹除历史扣款事实。
- 仅改变新账单生成及当前费率展示，不修改历史账单/钱包，不新增SQL，不调整支付渠道、真实收款和运费交接，不改App或平台页面。

## 2026-11-04 客户端共用字典查询

新增 `GET /app/dict/data?dictType=sys_billing_type`，商家及用户端共用 `token` 请求头，使用现有客户端会话认证。用户明确确认允许已登录客户端查询任意字典类型，不增加类型白名单。只返回启用项，复用现有缓存及排序；返回 `dictLabel`、`dictValue`、`dictSort`、`isDefault`，不返回后台审计字段。缺失、空白或超过100字符的类型返回国际化业务错误；不存在或无启用项返回空数组。标签使用后台维护原文，不自动翻译或改写类型5的业务含义。本增量仅提供共用接口，不改商家页面或字典数据。