spec.md 12 KB
商家前端账单功能需求
背景
平台管理后台已有账单管理页面（Billing/billing/index），但商家前端（foodie-store）缺少账单功能。需要为商家前端新增"财务管理"模块，包含账单查询功能。
用户类型与权限
| userType | 角色 | 账单可见范围 |
|---|---|---|
| 1 | 商家 | 自己名下所有门店的账单（user_id 查询，可选按 mdId 筛选） |
| 4 | 摊位主/门店 | 仅自己关联门店的账单（md_id 过滤） |
| 5 | 商家分管账号 | 所属主账号下当前授权门店的账单，列表与汇总范围一致 |
数据模型
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})
前端功能
新增菜单目录：财务管理
财务管理
└── 账单管理
账单管理页面
筛选条件
- 门店选择（下拉框，商家可切换门店，摊位主只显示自己门店）
- 账单类型（分成、充值、提现、消费、冻结、解冻、抽成返还）
- 时间范围选择器
汇总区域
- 显示筛选范围内的总金额、总抽成、净收入
账单列表表格
- 列：订单号、账单类型、金额、抽成、净收入、门店名称、状态、时间、说明
- 支持分页
权限区分
- 商家（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的业务含义。本增量仅提供共用接口，不改商家页面或字典数据。
2026-11-04 分管账号账单查询修复
GET /Billing/billing/storeBillingList和/storeBillingSummary支持商家分管账号userType=5，token 和请求/响应字段不变。- 每次请求复用
MerchantStoreAccessService.resolve校验分管账号、主账号状态及当前门店授权；账单限定user_id=ownerUserId且md_id在授权门店内。传入mdId必须属于授权集合；未传时仅汇总/查询授权门店。 - 无授权门店时列表为空、汇总为零，不能省略门店过滤而查出主账号全量账单；指定未授权门店则返回已有国际化权限错误。
- 原商家/夜市主及摊位账号范围保持，用户和骑手继续拒绝。日期筛选使用绑定参数，避免筛选值改变权限条件。
- 本次只开放授权门店账单查询，不开放提现、结算、收款配置或主账号全局财务；无数据库和前端变更。
2026-11-04 旧日/周/月账单分管兼容
getzddaylist/getzdmeeklist/getzdmatlist 对 userType=5 解析主账号及实时授权门店；不传 mdId 查询全部授权门店，指定未授权门店拒绝。明细、金额/商品汇总、取消订单列表及数量使用相同范围，空授权查询零行。原普通商家/夜市/摊主/骑手路径不变，无数据库迁移。
2026-11-04 整数新台币与汇总显示精度
新订单及运费以整数新台币元计价。闪送、多店及新版外卖报价沿用已有整数计算；用户、商家创建入口对传入运费增加非负、有限、整数校验。保留原字段类型和未传运费兼容，不静默取整改变应付。账单汇总使用十进制运算消除二进制尾差，整数以整数数字返回。用户明确历史数据不处理，历史分角账单保留，不改钱包、不补差、不迁移。
接入变化：POST /system/userOrder/createOrder和 POST /system/orderShOprate/createOrder 保留原入参结构；已有运费字段如传入必须是非负整数（40或40.0均可，40.5拒绝），未传时维持原处理。订单总额字段已有Integer/Long类型。storeBillingSummary 三个金额字段仍返回JSON数字，消除浮点尾差、整数不附带小数部分；历史真实分角仍保留。本轮不修改App及商家PC代码，前端由用户安排人员调整。
2026-11-04 账单收入展示口径（以用户最终确认为准）
- 不返回原订单金额，不新增
orderAmount，不关联订单表；列表响应结构保持不变。 amount保持实际账单入账金额，divvy保持历史抽成记录。前端由用户安排人员将“订单金额”改为“收入”，直接使用amount，不再减divvy；本轮撤回所有前端代码及语言文件改动。storeBillingSummary.totalAmount保持账单金额合计，totalDivvy保留抽成合计，netIncome等于已入账金额合计，不再次减抽成；使用十进制消除浮点尾差。- 只读核对订单991793757396125：原订单135、账单114.75、历史抽成20.25；991793757103637及991793756962244：原订单95、账单80.75、抽成14.25。小数来自账单被错当订单展示。历史数据库、钱包均不回写，无SQL迁移。
- 旧
POST /system/order/addorder按用户要求彻底删除，不保留转发或兼容创建逻辑；用户及商家现有 createOrder 保持。
2026-11-05 骑手收入账单改版（最终范围：前端日期，后端范围查询）
用户故事与验收
- 前端计算日期切换条：天展示本周一至周日七天默认今天；周展示含本周的最近五周默认本周；月展示含本月的最近五个月默认本月。选项由旧到新排列，日期与星期文案由前端国际化。
- 后端仅接收 startTime/endTime（yyyy-MM-dd HH:mm:ss，起止时刻都包含），不接收 period/date，不计算周期、默认日期、最近几周/几月，不返回 periodOptions。两个日期均不传查询全部历史；仅传一个、无效日期或起点晚于终点拒绝。
- 顶部固定显示范围内收入合计、收入订单数、外卖订单数、闪送订单数。订单类型仅筛选下方分页明细；汇总不受分类或页码影响。
- 小费已包含在收入内，不另列小费；无钱包余额、提现、待结算或已收款标签。代收款独立返回，不计收入。
- 按有效收入账单产生时间统计，读取历史保存金额，不重算当前价格、不重复扣历史抽成/税、不因取消状态擅自调整历史账单。
- 仅启用且未删除的骑手查看本人记录。详情不存在、越权、非收入使用统一错误。账单直接返回保存的订单号 orderNo（来源 dd_id），不查询订单表或返回订单主键。点击原订单时按 orderSource 调用既有骑手详情接口；原订单不可访问不影响历史收入。
技术边界
- 新接口
/Billing/billing/riderIncome与/Billing/billing/riderIncome/{billId}，旧共用账单接口保持不变。 - 本人 user_type=2,type=0,state=0 且有订单号的账单；null/空来源作为 FOOD，FLASH 明确区分，其他来源不纳入。
- 按 UTC+8 业务时间解释范围，数据库使用 cretim >= startTime AND cretim <= endTime，原样绑定传入的完整时分秒，不补零点或增加一天；支持任意日期范围与跨年，不局限自然周/月。
- 逐笔金额按保存的两位精度返回与求和；零元记录计单。保留入账防重逻辑，不擅自合并历史记录。
- 本次只做后端与接入文档；不改 App、真实支付、钱包写入、账单生成或历史数据库，不创建分支，不自动提交推送。