退费与日对账（口径设计稿）

状态：已实装（2026-10-11）。与定稿口径的三处落地注记：① 充值段只算真实充值（正数流水且非退单 note）——储值支付扣减归收款侧、退款补回归退款侧，定稿未排负数行，按语义收窄；② settlements.order_id 唯一索引随「退款后重收产生新结算单」移除（新库不建、老库 SettlementIndexMigration 启动 DROP），防重复收款改判「最近一张结算单未退款」；③ 退款流水与对账明细行联出 payTypeText/customerName/staffName 展示字段。测试落点与第五节一致（RefundReconciliationTest 6 例 + RefundHttpTest 2 例）。 关联：服务端接口 结算组、数据模型 settlements/recharges/card_usages、月度收费报表 GET /api/v1/settlement/report/month、药房与发药流转、对齐清单 P1-33。

一、现状与缺口

收费链路已实装：结算台收款（payType 1 储值 / 2 微信 / 3 支付宝 / 4 现金 / 5 次卡抵扣，一单一结算）、储值充值流水（recharges，含储值支付的负数流水）、次卡核销流水（card_usages）、小票套打、月度收费报表（按结算时间聚合）。

缺口：

环节	现状
收错款/退单	无——结算落定后没有任何回退动作，储值错扣也回不来
日对账	无——月报按月聚合，收银员当班/当日对不平账

二、口径（定稿）

1. 退款对象 = 已完成的一笔结算。一单一结算（order_id 唯一），故一次退款 = 退整单，不做部分退。
2. 退款原路退回（按原 payType）：
   • 储值（1）：补回余额——recharges 落一条正数流水，note 记「退单 #结算id」；
   • 次卡（5）：作废该订单对应核销流水（card_usages 按订单删除、持卡余次回补），退款金额记 0；演示口径无留痕，与库存流水删除同口径；
   • 微信/支付宝/现金（2/3/4）：演示口径无真实支付通道，仅落退款记录，不再真转。
3. 订单回退：已完成(2) → 已接单(1)，可重新走结算台收款；重新收款产生新的结算单，原退款记录保留。
4. 一笔结算只能退一次：refund_logs.settlement_id 唯一索引兜底；已退款再退报 400「该结算已退款」。
5. 日对账 = 按自然日（结算/充值/退款时间）出对账单，不做班次时段交接：
   • 收款侧：单数、实收合计（次卡实收 0 计单数）、payTypes[] 构成；
   • 充值侧：充值笔数、金额（单列，不计入营收——与月报口径一致）；
   • 退款侧：笔数、金额、按原支付方式构成；
   • 净额：netMoney = 实收 - 退款；现金净额 = 现金收款 - 现金退款（收银钱箱核对用）。
6. 退款金额 = 原结算 money 等额回退（次卡为 0）；理由 ≤100 字必填（审计口径，退款必须能答"为什么"）。

数据

refund_logs（退款流水）：
  settlement_id     非空，唯一索引
  order_id          非空，索引
  money             退款金额（元，= 原结算实收；次卡为 0）
  pay_type          原支付方式冗余（1-5）
  staff_id          操作人
  reason            退款理由，≤100 字，非空
  create_time / update_time

无软删（演示口径无留痕）；退回储值的正数流水随 recharges 天然留痕。

接口（需登录）

方法	路径	功能
POST	/api/v1/settlement/{id}/refund	退单：reason 必填 ≤100 字；校验结算存在/已退款/订单已完成；回退订单状态、原路退回、落退款流水
GET	/api/v1/settlement/reconciliation?date=	日对账单：date=yyyy-MM-dd 必填（格式非法报 400）；收款/充值/退款三段 + 净额与现金净额

三、非目标（本稿明确不做）

• 不做部分退款、按行退款（收费以卡项订单结算为准，整单口径足够）。
• 不做跨日冲正与改账（退了重收即可）。
• 不做发票、医保结算、在线支付真实退款通道。
• 不做班次交接/钱箱班报（按自然日对账先行）。
• 不做储值账户注销/清零。

四、web 落点

• 新增页 /billing/reconciliation（日对账，仅登录）：日期选择（默认今天）+ 统计卡（实收/退款/净额/现金净额）+ 收款构成表 + 充值、退款两张明细表。
• 结算台待结算队列不区分「曾退款」，重新收款即正常结算；订单分页支付方式列维持现状。

五、测试落点

• RefundReconciliationTest：储值退款补余额、次卡退款回补次数、微信/现金仅落记录、重复退款 400、订单回退后可重收、日对账三段聚合与现金净额、充值不计营收。
• RefundHttpTest：退款 → 对账单读取 → 重复退款 400；date 缺失/非法 400；未登录 401。