VWCG-1121 充值赠送账户 MVP 技术方案

版本：V0.9（评审稿）
日期：2026-07-27
适用仓库：store、ai_api、ai_app
风险等级：高
结论状态：有条件可实施，7 项产品/范围决策确认后进入开发

1. 方案摘要

本需求不是单纯增加一个 gift_balance 字段。要完整满足“充值赠送、不可提现、全渠道消费、可配置扣款顺序、原路退款”，必须同时改造账户、充值、消费、退款和对账链路。

推荐方案：

1. 在 yoshop_user 增加赠送余额，并把现有现金余额内部拆为“可提现现金 + 活动本金”。
2. 新建充值赠送规则表与赠送流水表，充值订单复用三金额字段并保存命中规则快照。
3. 新建账户结算单作为消费/退款幂等锚点，统一 PC、消费设备和小程序扣款算法。
4. 在 ydy_meal_order 增加赠送支付、赠送退款、赠送剩余金额及扣款顺序快照。
5. ydy_config 保存全局扣款顺序，暂定默认值为“餐补 → 现金 → 赠送”；只影响新订单。
6. 跨账户库与业务库采用“账户侧幂等提交 + 业务侧重试同步 + 对账补偿”，不依赖伪跨库事务。
7. 充值订单、消费订单及相关人员/部门/设备统计同步调整异步导出。

2. 关键冲突与开发前决策

3. 范围与非范围

3.1 本期范围

• PC 机构人员列表显示赠送余额。
• PC 账户设置新增赠送活动、扣款顺序设置及操作日志。
• PC 和小程序充值展示并记录支付金额、赠送金额、实际到账金额。
• 充值成功后现金与赠送余额、流水分别入账。
• PC、小程序、绑盘机、消费机、虚拟订单、外部订单、闸机、点餐机共用账户结算规则。
• 消费订单展示和保存现金、餐补、赠送拆分。
• 全额/部分退款按原订单实际来源恢复。
• 相关统计、流水、导出与人工验收。

3.2 本期非范围

• 赠送余额有效期、冻结、转赠、提现。
• 按商品、餐次、人群、部门等复杂赠送活动条件。
• 多活动叠加。
• 对历史订单重算赠送金额。
• 把两套数据库合并为一个数据库。

4. 系统边界与目标架构

4.1 设计原则

• 账户库是余额事实源，业务订单库保存业务状态与账户拆分快照。
• 所有金额使用 decimal(10,2)，服务层使用字符串/定点运算，禁止浮点比较。
• 客户端预览只用于展示，创建充值订单时必须由服务端重新匹配规则。
• 消费与退款都以业务订单号作为幂等键。
• 当前配置只用于新订单；历史订单退款只使用订单快照。
• 新接口字段采用增量兼容，旧客户端可忽略。

5. 账户与金额模型

5.1 账户定义

5.2 核心不变量

actual_money = pay_price + gift_money
balance = withdrawable_balance + activity_principal_balance
usable_total = valid_subsidy + balance + gift_balance
meal_order.pay_price = subsidy + cash + gift
cash = withdrawable_cash_payment + activity_principal_payment
累计退款金额 <= 原订单各账户实际扣款金额

建议现金账户消费内部顺序为“活动本金 → 可提现现金”，避免用户先消耗可提现资金而留下不可提现本金。这个内部顺序不改变前台显示的“现金”一级账户顺序，但须保存内部拆分以支持提现与退款。

6. 数据库设计

以下为逻辑设计，正式 DDL 应按项目数据库版本、索引长度和发布时间另行生成。

6.1 账户库 yoshop_*

yoshop_user

约束：

• 所有余额字段非负。
• 每次现金变动后检查 balance = withdrawable_balance + activity_principal_balance。
• subsidy_balance 继续兼容展示，但有效补贴以补贴明细合计为准。

yoshop_recharge_gift_rule（新增）

匹配规则：

1. 只匹配当前门店、启用且未删除的规则。
2. pay_price >= min_money。
<<<<<<< HEAD
3. 支付方式仅允许 cash、alipay_offline、wechat_offline、online_scan，规则不设置适用端。
=======
4. 平台、支付方式匹配；“全部”用明确枚举值表达。
>>>>>>> 5d05833ef476571c794ef3016336bc136526872c
5. 多条命中时依次取：min_money 最大、gift_money 最大、rule_id/create_time 最新。
6. 同一充值订单最多命中一条规则。

推荐索引：

<<<<<<< HEAD
• (store_id, status, is_delete, pay_method, min_money)
=======
• (store_id, status, is_delete, platform, pay_method, min_money)
>>>>>>> 5d05833ef476571c794ef3016336bc136526872c
• 列表页 (store_id, is_delete, create_time)

yoshop_recharge_order（复用并扩展）

继续复用：

• pay_price
• gift_money
• actual_money

建议增加快照字段：

规则：

• 普通充值：withdrawable_amount = pay_price，activity_principal_amount = 0。
• 命中赠送：withdrawable_amount = 0，activity_principal_amount = pay_price。
• gift_money 只进入 gift_balance。
• 旧订单四个新增字段默认 0/空，维持历史含义。

yoshop_user_gift_log（新增）

场景建议：

• 10：充值赠送
• 20：消费扣款
• 30：后台调整（本期若无入口则保留枚举、不开放）
• 40：消费退款
• 50：充值退款冲正

对 idempotency_key 建唯一索引，避免回调/消费/退款重复入账。

yoshop_account_settlement（新增）

用于跨库消费和退款的幂等、重试与对账，不取代现有账户流水。

唯一键：

• 消费：(biz_type, biz_order_no)
• 退款：(biz_type, biz_order_no, refund_no)

6.2 业务库 ydy_*

ydy_config

新增配置：

key: account_deduction_order
value: ["subsidy","cash","gift"]
desc: 消费账户扣款顺序

校验规则：

• 必须恰好包含 subsidy、cash、gift 三项。
• 不允许重复或未知账户。
• 缺失、关闭或非法时回退到 ["subsidy","cash","gift"] 并告警。
• 保存后使相关缓存失效。

建议新增 ydy_account_config_log，记录配置键、变更前、变更后、操作人、时间、IP，满足账户设置审计要求。

ydy_meal_order

兼容规则：

• 新增金额字段默认 0.00，历史订单视为 gift=0。
• 历史订单保留已有现金/餐补值，不回填虚构的扣款顺序。
• 历史订单退款按旧逻辑兼容；新订单以是否存在结算快照区分。
• 不修改 source 既有枚举值。

ydy_meal_order_refund

增加：

• gift
• withdrawable_cash
• activity_principal
• account_settlement_id

退款单保存本次实际恢复金额，不只保存申请金额。

7. 充值流程

7.1 服务端规则

• 预览结果不作为入账依据。
• 创建订单时重算并保存规则快照，后续规则修改不影响该订单。
• 支付回调按订单快照入账，不能再次匹配当前规则。
• 使用订单号/支付回调号做幂等，重复回调返回已有成功结果。
• 订单、用户余额、现金流水、赠送流水在同一账户库事务中提交。
• 回调失败必须向上抛出并进入渠道重试或内部补偿，禁止吞异常后返回成功。

7.2 三金额与流水

示例：支付 100 元，赠送 20 元。

8. 消费结算流程

8.1 统一算法

输入：

• 用户、门店、业务订单号、订单来源、应付金额。
• 有效补贴明细、现金内部余额、赠送余额。
• 当前合法扣款顺序。

输出：

• 餐补、现金、赠送拆分。
• 现金内部的活动本金、可提现现金拆分。
• 扣款顺序、账户前后快照和结算单 ID。

伪代码：

remaining = payable
for account in configured_order:
    used[account] = min(available(account), remaining)
    remaining -= used[account]
if remaining > 0:
    fail("账户余额不足")

if used.cash > 0:
    used.activity_principal = min(activity_principal_balance, used.cash)
    used.withdrawable = used.cash - used.activity_principal

8.2 跨库一致性

规则：

• 账户扣款前锁定用户汇总行及需要使用的补贴明细。
• 同一业务订单只允许一个成功消费结算单。
• 账户库提交后，业务库更新失败时不得重复扣款；重试只同步原结算结果。
• 对账任务按“已提交但未同步”“业务已支付但无账户结算”“金额拆分不等”三类检测。
• 异常订单在设备/客户端返回“处理中”或明确失败，不能返回虚假成功。

8.3 所有下单入口接入

设备协议新增 gift_payment、remain_gift 等字段应保持可选，旧设备继续读取既有字段。

9. 退款与提现

9.1 消费退款

• 全额退款：按原订单各账户实际扣款金额全部恢复。
• 部分退款：建议从实际扣款顺序的末端向前恢复。例如订单按“餐补→现金→赠送”扣款 10/20/30，退款 35 时先恢复赠送 30，再恢复现金 5。
• 现金恢复时继续按原订单保存的 activity_principal_payment、withdrawable_cash_payment 逆序恢复，不把活动本金误恢复为可提现现金。
• 重复退款以退款单号幂等；累计恢复不能超过原订单拆分。
• 配置修改不影响历史订单退款。

9.2 充值退款/提现

• 用户可提现金额上限为 withdrawable_balance，不能再仅依据 balance 或充值订单原始 refundable_money。
• 命中赠送活动的充值：支付本金进入活动本金，赠送进入赠送余额，二者均不可提现。
• 普通充值：支付本金进入可提现现金。
• 充值退款如仍需支持，应先明确“已消费后的退款”规则，并在账户余额足够时按原充值来源冲正。

9.3 历史现金迁移

建议初始迁移：

withdrawable_balance = balance
activity_principal_balance = 0
gift_balance = 0

该方案保持历史现金可提现能力，不倒推历史活动属性。若产品要求按 365 天或旧活动记录重建可提现金额，必须另立数据治理任务并做差异报表，本期不能凭现有余额字段可靠推导。

10. API 与页面改造

10.1 PC 后台

权限要求：

• 新页面和接口必须同时配置菜单、功能权限与数据权限。
• 控制器不能只因继承基类就假设权限完整；需核对 beforeActionList。
• 规则新增/编辑/启停、扣款顺序变更必须记录操作人、前后值和时间。

10.2 小程序 ai_app / ai_api

创建订单和支付成功响应建议增加：

{
  "pay_price": "100.00",
  "gift_money": "20.00",
  "actual_money": "120.00",
  "account_payment": {
    "subsidy": "10.00",
    "cash": "20.00",
    "gift": "30.00"
  },
  "deduction_order": ["subsidy", "cash", "gift"]
}

金额字段统一使用两位小数字符串，避免前端浮点误差。

11. 统计与异步导出

该列表页关联异步导出功能，需同步确认/修改异步导出逻辑。

菜品销量、餐厅经营汇总、档口营收结算是否受影响，取决于其收入口径是否只看订单实付总额。若只看订单总额且不展示账户来源，可不改金额口径，但仍需回归证明。

12. 安全、并发与审计

• 所有查询、规则、流水和配置按 store_id 做租户隔离。
• 账户行、补贴批次按确定顺序加锁，降低死锁概率。
• 充值回调、消费、退款均有唯一业务幂等键。
• 后端拒绝负数、超过金额精度、非法账户顺序、越权门店和超额退款。
• 不信任客户端传入的赠送金额、扣款拆分或可提现金额。
• 流水不允许物理修改；冲正使用相反方向的新流水。
• 配置与规则变更写审计日志，记录操作前后值。
• 错误日志不记录支付密钥、数据库口令和完整个人敏感信息。

13. 兼容、上线与回滚

13.1 上线顺序

1. 在影子环境执行 DDL 并验证表锁、耗时、索引和回滚脚本。
2. 先部署后端兼容代码，新增字段读取为空时按 0/默认顺序处理。
3. 执行用户现金属性迁移并产出迁移前后余额对账报告。
4. 部署 PC 与小程序，保持赠送规则全部停用。
5. 对内部测试门店启用一条小额规则，覆盖充值、消费、退款、导出。
6. 观察对账无差异后逐门店启用。

13.2 监控

• 充值三金额不相等计数。
• 账户余额不变量异常数。
• 重复回调拦截数。
• 账户已提交但业务未同步数量与最长滞留时间。
• 订单实付与账户拆分差额。
• 退款超额/幂等拦截数。
• 各账户余额负数告警。

13.3 回滚

• 业务回滚：先停用全部赠送活动，将扣款顺序恢复默认；旧客户端继续使用原字段。
• 代码回滚：保留新增字段和表，不在有数据后直接删列；回滚版本应忽略赠送规则并阻止产生新赠送。
• 数据回滚：对已产生的赠送与消费不得直接覆盖余额，必须用冲正流水和结算单逐笔恢复。
• 跨库未同步：先停止新交易，完成结算单对账和补偿，再决定代码回滚。
• DDL 回滚：只在确认新增表/列无业务数据时执行；生产已入账后采用前向修复。

14. 测试覆盖矩阵

建议新增专门的 GiftAccount 测试组，并回归既有：

• tests/Security/SecurityFixesTest.php
• tests/apifox/http/run_dengbao_regression.sh
• 卡务/消费、充值、补贴、退款相关 PHPUnit 与 Apifox 集。

15. 验收映射

16. 推荐实施切片

1. 数据结构、迁移脚本、账户不变量与对账基线。
2. 赠送规则和 PC 账户设置权限/审计。
3. PC、小程序充值三金额与双流水。
4. 统一账户结算服务和消费幂等结算单。
5. 按来源逐个接入所有下单入口。
6. 消费退款、提现资格和跨库补偿。
7. PC/小程序页面、统计、异步导出与全链路验收。

每个切片都应先补回归测试，再合并到下一切片；资金链路不建议一次性大爆炸发布。

17. 评审结论

方案可以作为研发拆分基线，但不能在 D1～D7 未确认前直接编码。尤其是“默认扣款顺序”“活动本金不可提现模型”“部分退款规则”三项会直接决定数据库字段和历史兼容策略。

文档评审通过后，应为各实施切片创建独立研发任务，并分别补充 DDL、API 契约、测试用例和发布证据。