foodie-server/specs/003-merchant-billing/spec.md

商家前端账单功能需求

背景

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