跨境多币种收款台 Skill
为学页平台（私有化部署，在线教育）的东南亚/中东教培机构提供
"收银台 → 多渠道多币种收款 → 自动结算对账"的跨境招生回款闭环。
1. 角色定位
- 你是财务机器人，不是开发者工具：用自然语言完成收款与对账，所有资金操作保留人工确认。
- 用户角色：机构运营/财务（对话交互）、平台运营（配置与审计）、学员/家长（仅使用收银台页面）。
- 内核代码：Python 3，零第三方依赖（YAML 解析自带兜底实现），可在任意环境直接运行。
2. 目录结构
~/.workbuddy/skills/cross-border-pay-counter/
├── SKILL.md # 本文件（工作流入口）
├── config/ # 配置（全部可改，改完即生效）
│ ├── channels.yaml # 渠道接入 + 本地支付方式注册表（覆盖矩阵）
│ ├── routing.yaml # 路由策略（评分权重 + 国家×币种矩阵 + 业务规则）
│ ├── fx.yaml # 汇率策略（三层币种 + 锁定窗口 + 静态汇率表）
│ ├── reconciliation.yaml # 对账策略（容差 + 时间线 + 差异 SOP + 告警）
│ └── split.yaml # 分账规则（平台/代理/机构 + 退款政策红线）
├── src/ # 内核（Python 模块）
│ ├── config.py # 配置加载（PyYAML 优先，tinyyaml 兜底）
│ ├── models.py # 数据模型（订单/意图/支付/流水/提现）
│ ├── store.py # 本地账本（JSON 持久化，单一事实来源）
│ ├── fx.py # 多币种与汇率引擎（定价/支付/结算三层）
│ ├── router.py # 支付路由引擎（评分 + 业务规则加权）
│ ├── cashier.py # 收银台引擎（创建支付意图 + 渲染页面）
│ ├── reconciliation.py # 三层自动对账引擎 + 差异 SOP
│ ├── settlement.py # 分账/提现/退款（人工确认闸门）
│ └── gateway/ # 三渠道统一网关（mock 全功能 + 真实 API 骨架）
├── templates/checkout.html # 收银台页面模板（多语言/本地币种大字/RTL 就绪）
├── scripts/
│ ├── demo.py # 端到端演示（4 国订单→收银台→支付→对账→分账→红线）
│ └── reconcile.py # 每日对账 CLI（供 automations 定时调用）
└── tests/test_core.py # 单元测试（mock 模式）
3. 渠道与覆盖（默认配置）
| 渠道 | 定位 | 覆盖要点 |
|---|---|---|
| Airwallex | 主干 | 东南亚本地清算 + 阿联酋/沙特（含 Tabby BNPL）+ 多币种账户；支持中国主体开户 |
| Stripe | 补充 | 新加坡/马来西亚/泰国 + 全球卡 + 订阅扣款；中东仅阿联酋；需海外主体 |
| Yuansfer | 钱包聚合补充 | GCash/DANA/Touch n Go/TrueMoney 等东南亚钱包 + 支付宝/微信（华人学员） |
路由原则：按 国家×币种×金额×支付方式 使用路由矩阵（routing.yaml），不是简单主备。
覆盖矩阵默认值（集成前须以渠道最新 capability 校验）：
- 印尼 → QRIS/DANA/GoPay/OVO/ShopeePay/VA（Airwallex，Stripe preview）
- 菲律宾 → GCash/Maya（Yuansfer/Airwallex）
- 泰国 → PromptPay/TrueMoney（Airwallex/Stripe）
- 越南 → MoMo/ZaloPay/VietQR（Airwallex）
- 马来西亚 → TnG/FPX/GrabPay（Airwallex/Stripe）
- 新加坡 → 卡/PayNow（Stripe）
- 沙特 → mada/STC Pay/Tabby/Tamara/Apple Pay（Airwallex）
- 阿联酋 → 卡/Apple Pay/Tabby（Airwallex/Stripe）
- 埃及 → Fawry/Vodafone Cash（Airwallex；Fawry 为现金网络，退款走独立退汇通道）
4. 核心工作流
WF-1 生成收银台/收款链接
- 解析意图：课程/金额/定价币种/学员国家（缺省则询问或按订单上下文推断，并说明假设）。
- 创建本地订单（幂等，订单号即幂等键）→
store.create_order(...)。 Router.route(order)按路由矩阵输出支付方式（含渠道标签/预估费率/可解释原因）。cashier.create_payment(order, method, channel, ...)调渠道创建支付意图（支付币种按学员国家，
汇率按 fx.yaml 锁定 15 分钟），返回 Payment。cashier.build_checkout(...)生成收银台 HTML（托管模式，学页页面承载），返回链接/二维码。
WF-2 支付状态跟踪
- 渠道 Webhook（
gateway.verify_webhook校验签名）或轮询（get_payment_status）→ 更新状态机
（pending/paid/failed/refunded/expired）。 - mock 模式用
gateway.capture(payment_id)模拟学员支付成功。 - 状态变更通知机构；支付失败给出可重试方式。
WF-3 每日自动对账（automations 定时触发）
- CLI：
python scripts/reconcile.py（默认对账今天，报告输出到 reports/）。 - 三层对账：
ReconEngine.run()： - L1 交易级：本地支付 vs 渠道流水（主键 external_id + 金额±0.5% 容差）→ 孤儿单/缺单/手续费差。
- L2 资金级：渠道净额 vs 本地净额 → 金额差/汇率差（≤1.5% 归汇率损益科目）。
- L3 余额级：账面期望（已收-退款-提现）vs 渠道报告 → 余额偏差。
- 输出：对账报告 md + 差异清单（每条带 SOP 建议动作）。
- 差异闭环：金额差→归科目；汇率差→汇率损益；时间差→在途 T+10 复查；孤儿单→查伪成功/风控拦截；
退款不同步→补冲销。差异处理动作由人工确认后执行。
WF-4 结算/分账
settlement.split_proceeds(order, ...)在"渠道已入账、提现前"按 split.yaml 拆分：
平台服务费 → 机构 → 代理佣金，校验分账平衡。settlement.request_payout(gateway, ...)：默认 dry-run 出方案，confirm=True才执行。- 中东退款红线：Fawry/COD 等现金网络不可原路退 → 拦截并引导走独立退汇通道。
WF-5 退款
settlement.request_refund(gateway, payment, amount, reason, confirm=...)：
校验订单 → 全额/部分退款（原路退回或退汇通道）→ 更新分账与对账记录 → 通知双方。- 一律先出方案（confirm=False）→ 人工确认（confirm=True）→ 执行。
5. 配置与模式切换
- 默认
mode: mock：零密钥零依赖，本地模拟渠道，适合演示/联调/测试。 - 切换真实渠道：在
config/channels.yaml填入凭证并把对应渠道mode改为sandbox（再验证后live）。 - Airwallex：
client_id/api_key/webhook_secret - Stripe：
secret_key/publishable_key/webhook_secret - Yuansfer：
api_key/api_token/merchant_no/store_no - 真实调用已按各渠道公开 API 实现骨架（Airwallex OAuth + payment_intents、Stripe payment_intents、
Yuansfer v3/payments），沙箱验证字段与回调为准。 - 路由/汇率/对账/分账全部配置化，改 YAML 即生效，无需改代码。
6. 常用指令示例（供对话引导）
- "给泰国学员创建 300 美元的课程收款链接" → WF-1
- "查看订单 X 的支付状态" → WF-2
- "对一下昨天所有渠道的账，出报告" → WF-3（
python scripts/reconcile.py --date=...） - "这几笔对账差异是什么原因？怎么处理" → WF-3 差异 SOP
- "印尼上月的款分账并提现（先给我方案）" → WF-4
- "原路退回学员 A 的课程费" → WF-5
- "出上个月的财务月报" → 汇总 reconcile 报告
- "最近拒付率情况如何" → reconciliation.yaml alert_rules 看板
7. 非功能约束（必须遵守）
- 安全：不落库卡号（tokenization）；API Key 存凭证库，对话中永不输出密钥；接口幂等+签名校验。
- 合规：跟随渠道牌照体系，不自行收单；中东分期必须无息（伊斯兰金融合规）；数据本地化提示。
- 资金安全：提现、退款、大额操作一律先出方案 → 人工确认 → 执行；所有操作留痕可审计（本地账本全量记录）。
- 多语言：收银台支持英/中/印尼/泰/越/阿拉伯语（RTL 就绪，模板 lang/dir 参数）。
- 私有化：外联仅放行渠道 API 白名单；支持机构维度数据隔离（Store 按机构隔离）。
8. 验证与测试
- 端到端演示：
python scripts/demo.py（产出 demo_output/ 收银台页面 + 对账报告） - 单元测试：
python -m unittest discover -s tests -v - 覆盖：路由（IDN/SA/SG 优先方法）、汇率换算与锁定、支付闭环、孤儿单/汇率差识别、
提现与退款确认闸门、现金网络退款红线、分账平衡。
9. 已知限制与后续
- 真实渠道 API 需在各自沙箱验证（字段/签名以官方最新文档为准）；覆盖矩阵定期核查。
- 报告导出 Excel/CSV、Webhook 服务、邮件/IM 告警、BNPL（Tabby）专项、拒付证据包为后续迭代（PRD M2~M4）。
- 对账引擎可重入（重跑幂等）；历史快照与断点续跑可在此基础上扩展。
