技术设计
数据模型、接口与工程实现
这一页面向客户的技术负责人：说明规则在代码里长什么样、需要哪些数据表与接口、以及靠什么保证钱不会算错。本方案的规则引擎已经是可运行代码，不是伪代码。
规则引擎的代码结构
规则集中在一处，参数与逻辑分离，运营调参不需要动业务代码。
| 文件 | 职责 |
|---|---|
| src/lib/engine/config.ts | 全部业务参数：让利区间、各层分配比例、系数档次、券规则、触发阈值、安全阀 |
| src/lib/engine/split.ts | 单笔订单分账，输出完整分账树与 70% 科目明细 |
| src/lib/engine/weights.ts | 商家三系数、消费者双系数、有效商家判定、让利额度落级 |
| src/lib/engine/payout.ts | 待发池触发判定与按权重分配，含单次封顶与流动性保护 |
| src/lib/engine/coupons.ts | 券发放、门槛与叠加校验、核销、过期回流结算 |
| src/lib/engine/unfreeze.ts | 商家解冻账户推进、月度上限顺延、烧伤分摊 |
| src/lib/engine/dividend.ts | 大盘分红按 Y1~Y7 切池、运营中心按部门让利加权 |
| src/lib/engine/simulate.ts | 多日闭环模拟，含资金守恒断言 |
| src/lib/engine/money.ts | 整数分运算与最大余数法分配，保证分账不丢分 |
核心数据模型
资金相关的表都保留比例与来源字段，任何一笔钱都能回溯到订单与规则版本。
主要接口
所有写操作都要求幂等键，重试不会造成重复入账或重复发券。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/orders | 下单并实时分账，返回完整分账树与消费者立减金额 |
| GET | /api/merchants/:id/unfreeze | 商家解冻进度、月度上限、顺延金额与加速项 |
| POST | /api/merchants/:id/discount-rate | 调整让利率，返回健康系数与生效时间 |
| GET | /api/consumers/:id/wallet | 现金余额、待领取、持有券与权重明细 |
| POST | /api/coupons/:id/redeem | 券核销，校验门槛、归属与叠加上限 |
| POST | /api/payouts/trigger | 待发池触发发放，幂等键防重复 |
| GET | /api/reconciliation/daily | 日终资金守恒对账单 |
| GET | /api/config/rules | 读取当前生效的全部规则参数 |
金额精度与对账
分红系统最怕的不是算得慢，而是算错了没人发现。方案里用三层机制兜住这件事。
日终校验清单
- 让利额 = 70% 收益分配 + 30% 补贴（逐笔与日汇总两级校验）
- 补贴流出 ≤ 补贴池累计 + 券过期回流 + 烧伤分摊
- 每个商家累计解冻 ≤ 其累计让利额 × 2
- 待发池余额 = 累计入池 − 累计发放
- 分账明细金额之和 = 订单让利额（按科目逐项核对）
这五条已经写成自动化测试，在闭环模拟页每次运行都会执行一遍。
测试覆盖
规则类系统的正确性必须靠测试固定下来，改参数不能悄悄改变结果。
金额拆分
最大余数法不丢分、权重为零时不分配
分账层级
1%~18% 全区间下父子金额恒等，科目合计等于 70%
权重系数
三系数相乘、套利降权、有效商家判定、冻结与恢复
触发条件
工作日 100 元、周末 150 元、满 7 天、流动性保护
券生命周期
门槛校验、限店、叠加上限、两种过期分配
解冻与烧伤
双倍上限、月度 20% 顺延、烧伤 50% 分摊
分红池
大盘 Y 级切池、运营中心按部门加权
闭环模拟
资金守恒断言、解冻不越限、同种子结果可复现
在项目根目录执行 npm test 可运行全部规则测试。
待客户确认后才能定稿的部分
下列问题会直接改变金额计算结果，已按默认值实现且集中在配置层，确认后改配置即可。
| 编号 | 问题 | 当前实现与影响 |
|---|---|---|
| Q0 | 「让利额双倍返还」的资金来源（优先级最高） | 每 100 元让利只有 12 元稳定回流商家解冻账户，加上定向券全部过期的极端情况上限为 14.52 元，与 200 元的解冻目标相差 185.48 元。当前代码按「双倍为解冻上限」实现，不会超发。待确认：请确认双倍的口径：由平台留存补贴、计入券核销营业额、或定义为解冻上限 |
| Q1 | 券有效期口径不一致 | 《消费者端》表一写定向券 7 天、万向券 3 天，表二写两者均为 10 天。程序已做成可配置，默认取 7 天与 3 天。待确认：请确认最终有效期 |
| Q2 | 商家锁客 1% 的计算基数 | 资料同时写「1%」与「商家流水的万 1」。按让利额 1% 与按流水 0.01% 相差约 10 倍（以 10% 让利率计）。待确认：请确认按让利额还是按流水计算 |
| Q3 | 协作创收 10% 与业务经理 10% + 推广员 7% 的关系 | 图中「协作创收 10%」下挂业务经理 10% 与推广员 7%，两者相加超过父级 10%。当前实现按各自独立占让利额比例落账，合计 17%。待确认：请确认父子关系与实际比例 |
| Q4 | 70% 中的预留科目④⑤ | 资料标注为预留，暂按 0% 实现，接口已预埋。已明确科目合计 25.6%，其余 44.4% 计入平台留存。待确认：请确认预留科目的用途与比例 |
| Q5 | 好评率奖励规则 | 《商家端》写「好评率 > 95%，端口预留」，未给出具体奖励值。待确认：请给出奖励形式与数值 |
| Q6 | 解冻双倍与月度 20% 上限的时间关系 | 让利总额随交易持续增长，月度上限也随之提高。当前实现按「当前累计让利总额 × 20%」逐月计算。待确认：请确认是否按累计让利额或按当月让利额计算上限 |
| Q7 | 退出商家的烧伤范围 | 「退出商家未解冻钱的 50%」当前按其未解冻额度（双倍目标减已解冻）计算，剩余 50% 进平台储备金。待确认：请确认未解冻额度的定义与剩余部分归属 |
| Q8 | 资金合规与账户体系 | 现金红包可直接提现，需明确资金存管、提现通道、税务与发票处理方式。待确认：请提供支付通道与合规要求 |