主题
12. 使用说明书
简介
v1.1.0 版本带来了两项重大架构升级：
- 短信微服务：将短信发送能力从快递业务中独立出来，全平台统一调用，支持模板管理、多租户接入、异步发送和状态回调
- 支付架构重构：自助洗衣业务支付体系升级为以服务商模式为核心的多模式架构，支持网点级别的灵活收款配置
使用前提
- 已部署短信微服务并完成基础配置（短信渠道、签名、模板）
- 已在微信支付服务商平台 / 支付宝开放平台完成商户注册
- 已获得后台管理员权限（支付配置、网点管理）
操作步骤
短信微服务
接入短信服务（面向研发）
- 获取 API Key：联系运营管理员，在短信服务后台创建租户并获取 API Key 和 Secret
- 确认模板：确认需要使用的短信模板已在后台创建并启用
- 调用发送接口：
POST https://sms-gateway.example.com/api/v1/sms/send
Header: X-Api-Key: {your_api_key}
Body: {
"template_id": "TMPL_001",
"mobiles": ["13800138000"],
"variables": { "code": "123456" }
}- 配置回调（可选）：如需接收发送结果通知，配置租户回调 URL
管理短信模板（面向运营）
- 进入后台：登录管理后台 →「短信服务」→「模板管理」
- 新建模板：填写模板名称 → 选择渠道（阿里云/腾讯云）→ 输入渠道模板 ID → 填写模板内容（
{var}为变量占位符）→ 选择签名 → 保存 - 提交审核：新建模板状态为「待审核」，由超管审核通过后变为「已启用」
- 管理配额：在「租户管理」中为各业务线配置日发送配额和 QPS 限制
支付配置中心
创建支付配置
- 进入后台：登录管理后台 →「支付配置」→「新建配置」
- 选择支付模式：
- 微信服务商分账：适用于平台需要与加盟商/供应商分账的场景
- 微信服务商直收：适用于加盟商独立收款、平台不参与分账的场景
- 支付宝直收：适用于希望支持支付宝收款的网点
- 填写配置参数：根据所选模式填写对应的商户号、密钥、分账规则等
- 保存配置：系统校验参数后创建配置，状态为「已启用」
为网点绑定支付配置
- 进入网点管理：后台 →「网点管理」→ 选择目标网点
- 支付设置：点击「支付设置」标签，页面分为「微信支付」和「支付宝支付」两个区域
- 绑定微信配置：在微信支付区域，从已启用的微信类配置中选一个（分账或直收）
- 绑定支付宝配置（可选）：在支付宝支付区域，从已启用的支付宝配置中选一个（也可不选，则仅支持微信支付）
- 确认绑定：点击「确认绑定」，建议随后分别测试微信和支付宝的 0.01 元支付验证
切换网点支付配置
- 在网点支付设置页，分别切换微信或支付宝的支付配置
- 切换一个渠道的配置不影响另一个渠道
- 系统记录变更日志（渠道、旧配置、新配置、操作人、时间）
- 下一笔支付自动使用新配置，无需重启服务
常见问题
Q1：短信发送失败怎么排查？
A：按以下步骤排查：
- 确认 API Key 有效且日配额未用尽
- 确认模板 ID 正确且模板状态为「已启用」
- 在短信服务后台查看发送记录，确认失败原因码
- 常见失败原因：手机号在黑名单、渠道余额不足、签名未报备
Q2：微信分账和直收有什么区别？网点该怎么选？
A：
- 分账模式：用户付款后，资金按预设比例自动分给平台、加盟商等各方。适用于平台统一管理、需要自动抽成的场景
- 直收模式：用户付款直接进加盟商账户，平台不参与资金分配。适用于加盟商独立经营、平台通过其他方式收取服务费的场景
- 选择建议：如果平台与加盟商有明确的分成比例，选分账模式；如果加盟商自负盈亏、平台仅收固定月费，选直收模式
Q3：一个网点能同时支持微信和支付宝吗？
A：可以。一个网点最多绑定两个支付配置：一个微信渠道（分账或直收二选一）和一个支付宝渠道（可选）。客户端分为微信小程序和支付宝小程序两个独立 App，前端根据所在平台自动获取对应支付配置：微信小程序走微信支付，支付宝小程序走支付宝支付。如果网点只想用微信收款，不绑定支付宝配置即可。
Q4：修改分账规则会影响正在进行的支付吗？
A：不会。分账规则更新只对配置变更后新发起的支付生效，已完成的支付不受影响，正在分账中的支付仍使用旧规则。
Q5：短信模板审核一般多久？
A：渠道侧（阿里云/腾讯云）模板审核通常 2 小时内完成。建议提前在渠道侧提交审核，审核通过后再在管理后台创建模板记录。
Q6：支付配置切换后多久生效？
A：配置切换后 1 分钟内生效（Redis 缓存刷新周期）。网点设备端在下次发起支付时自动获取最新配置。