放款与还款结果提醒 — MVP 系统需求

本文补充本期需要实现的“事件结果类短信”：放款结果提醒、还款结果提醒。还款日前/逾期后的周期性提醒仍见 01-还款提醒。

参考模板：飞书《短信模板》表，当前已审批模板包含 WITHDRAWAL_SUCCESS、WITHDRAWAL_FAILED；还款结果类模板需按本文变量口径在 crs/短信供应商侧补齐或确认。

1. 业务目标

放款与还款结果提醒用于在交易结果明确后及时通知客户：

• 放款成功后告知客户资金已发放，以及发放金额和收款账户信息。
• 放款失败后告知客户本次放款未成功，避免客户误以为订单已完成。
• 还款成功后告知客户还款已入账，降低重复还款和客服咨询。
• 还款失败后告知客户扣款未成功，引导客户重新还款。
• 借据结清后告知客户本笔借据已结清。
• MVP 先做短信，不做 Push、WhatsApp、站内信等其他渠道。

2. MVP 范围

2.1 MVP 包含

能力	MVP 范围
放款成功提醒	FCS 确认放款成功后发送 SMS
放款失败提醒	FCS 确认放款失败后发送 SMS
还款成功提醒	主动还款、代扣还款入账成功后发送 SMS
还款失败提醒	主动还款、代扣还款失败后发送 SMS
结清提醒	还款后借据 paidOffDate 已产生时发送 SMS
模板管理	模板内容与模板 ID 在 crs 或短信供应商侧维护，FCS 只传模板 ID/场景编码和变量
发送记录	FCS 记录业务发送结果；crs 记录短信供应商请求和返回结果

2.2 MVP 不包含

• 独立短信网关。
• 运营后台配置短信模板。
• 多语言模板。
• 营销类短信。
• 人工重发后台。
• 供应商投递状态的完整回执闭环；MVP 以 crs 受理/失败结果为准。

3. 模板与变量

3.1 已审批模板

场景	Template Name	Template ID	模板内容	变量
放款成功	WITHDRAWAL_SUCCESS	UTB26062396M46X	Success! NGN {1} has been successfully disbursed to your bank account {2} ending {3}.	{1}=amount, {2}=bankName, {3}=accountLast4
放款失败	WITHDRAWAL_FAILED	UTB26062336KX3M	Sorry, your withdrawal of NGN {1} could not be processed. Please try again later or contact support if the issue persists.	{1}=amount

3.2 本期还款结果模板

场景	Template Name	Template ID	模板内容	变量
还款成功	REPAYMENT_SUCCESS	待供应商审批后回填	Dear {1}, your {2} repayment of NGN {3} was successful on {4}. Thank you for your payment.	{1}=customerName, {2}=productName, {3}=amount, {4}=repaymentDate
还款失败	REPAYMENT_FAILED	待供应商审批后回填	Dear {1}, your {2} repayment of NGN {3} was not successful. Please try again in the app.	{1}=customerName, {2}=productName, {3}=amount
借据结清	LOAN_PAID_OFF	待供应商审批后回填	Dear {1}, your {2} loan has been fully paid off. Thank you for choosing us.	{1}=customerName, {2}=productName

还款结果模板按短信供应商要求使用 {1}、{2}、{3}、{4} 顺序占位符；FCS 内部变量名与占位符顺序需保持一致。模板审批通过后需将供应商返回的 Template ID 回填到本文和飞书《短信模板》表。

4. 发送场景

4.1 放款成功提醒

触发条件：

• 放款订单处理成功。
• 借据状态已进入正常还款状态。
• 放款金额大于 0。
• 客户手机号存在且格式有效。
• 同一放款订单未成功发送过放款成功提醒。

变量取值：

变量	取值
amount	放款订单实际成功金额，按 NGN 金额格式化
bankName	放款收款账户银行名称；手机分期为门店/商户收款账户对应银行
accountLast4	放款收款账号后 4 位

发送边界：

• 手机分期放款到门店/商户账户，短信仍发送给客户本人手机号。
• 如果放款成功后还需要通知商户，本期不在 FCS 短信范围内。
• 放款成功短信不替代合同、账单和还款计划展示。

4.2 放款失败提醒

触发条件：

• 放款订单最终失败。
• 借据未进入正常还款状态，或已按失败流程关闭/取消。
• 放款金额大于 0。
• 客户手机号存在且格式有效。
• 同一放款订单未成功发送过放款失败提醒。

变量取值：

变量	取值
amount	本次尝试放款金额，按 NGN 金额格式化

发送边界：

• 仅在最终失败时发送；处理中、待重试、结果未知不发送失败短信。
• 失败原因不在短信中展开，避免暴露通道细节。

4.3 还款成功提醒

触发条件：

• 还款订单入账成功。
• 成功金额大于 0。
• 客户手机号存在且格式有效。
• 同一还款订单未成功发送过还款成功提醒。
• 如果本次还款已导致借据结清，优先发送结清提醒；是否同时发送还款成功提醒由配置控制，MVP 默认只发结清提醒。

变量取值：

变量	取值
customerName	客户 First Name
productName	产品名称；无法取得时使用默认产品展示名
amount	本次还款成功金额，按 NGN 金额格式化
repaymentDate	还款入账业务日期

4.4 还款失败提醒

触发条件：

• 还款订单最终失败。
• 本次还款金额大于 0。
• 客户手机号存在且格式有效。
• 同一还款订单未成功发送过还款失败提醒。

变量取值：

变量	取值
customerName	客户 First Name
productName	产品名称；无法取得时使用默认产品展示名
amount	本次还款金额，按 NGN 金额格式化
发送边界：

• 仅最终失败发送；处理中、银行处理中、待回调不发送失败短信。
• 如果失败后系统会自动重试，本期可配置为不发送，避免客户重复操作。

4.5 借据结清提醒

触发条件：

• 还款入账后借据已结清。
• 借据 paidOffDate 已产生。
• 客户手机号存在且格式有效。
• 同一借据未成功发送过结清提醒。

变量取值：

变量	取值
customerName	客户 First Name
productName	产品名称；无法取得时使用默认产品展示名

5. crs 对接

FCS 负责生成短信发送请求，crs 负责实际调用短信供应商。

FCS 请求字段建议：

字段	说明
custId	客户 ID
mobile	客户手机号
templateName 或 templateId	模板名称或供应商模板 ID
sceneCode	FCS 业务场景编码
variables	模板变量，按供应商要求保持顺序或键值
bizOrderId	放款订单号/还款订单号
loanId	借据 ID
bizCode	租户/业务线

场景编码建议：

场景	sceneCode
放款成功	loan_disbursement_success
放款失败	loan_disbursement_failed
还款成功	repayment_success
还款失败	repayment_failed
借据结清	loan_paid_off

6. 防重复与发送记录

防重复口径：

• 放款结果：同一 orderId + sceneCode + mobile 只允许成功发送一次。
• 还款结果：同一 orderId + sceneCode + mobile 只允许成功发送一次。
• 结清提醒：同一 loanId + sceneCode + mobile 只允许成功发送一次。

发送记录字段建议：

字段	说明
businessDate	FCS 业务日期
sceneCode	场景编码
custId	客户 ID
loanId	借据 ID
orderId	放款/还款订单号
mobileMasked	脱敏手机号
templateId	模板 ID
variables	发送变量快照
sendStatus	待发送/已提交/成功/失败/跳过
crsMessageId	crs 返回消息 ID
failureReason	失败原因
createTime	创建时间
sendTime	发送时间

7. MVP 流程

7.1 放款结果提醒

放款回调/放款结果处理
  -> 判断放款成功或最终失败
  -> 查询客户手机号和放款订单信息
  -> 生成模板变量
  -> 检查是否重复发送
  -> 调用 crs 发送短信
  -> 记录发送结果

7.2 还款结果提醒

还款回调/还款结果处理
  -> 判断还款成功、失败或借据结清
  -> 查询客户手机号、借据和还款订单信息
  -> 生成模板变量
  -> 检查是否重复发送
  -> 调用 crs 发送短信
  -> 记录发送结果

8. 验收标准

8.1 放款成功

• 放款成功后能按 WITHDRAWAL_SUCCESS 模板发送短信。
• {1} 使用实际放款金额，格式为 NGN 金额。
• {2} 使用收款账户银行名称。
• {3} 使用收款账号后 4 位。
• 同一放款订单重复回调不重复发送成功短信。

8.2 放款失败

• 放款最终失败后能按 WITHDRAWAL_FAILED 模板发送短信。
• {1} 使用本次尝试放款金额，格式为 NGN 金额。
• 处理中或待重试状态不发送失败短信。
• 同一放款订单重复回调不重复发送失败短信。

8.3 还款成功

• 还款成功后能发送还款成功短信。
• 短信金额与订单成功入账金额一致。
• 同一还款订单重复回调不重复发送成功短信。
• 如果本次还款导致结清，MVP 默认只发送结清提醒。

8.4 还款失败

• 还款最终失败后能发送还款失败短信。
• 处理中或待回调状态不发送失败短信。
• 同一还款订单重复回调不重复发送失败短信。

8.5 借据结清

• 借据结清后能发送结清短信。
• 同一借据只发送一次结清短信。
• 还款成功短信与结清短信不会因同一事件重复打扰客户。

9. 上线清单

• 确认 WITHDRAWAL_SUCCESS、WITHDRAWAL_FAILED 模板在生产短信供应商侧可用。
• 确认还款成功、还款失败、借据结清模板名称、模板 ID 和变量顺序。
• 确认 crs 发送接口支持按模板 ID 和变量发送。
• 确认 FCS 发送记录表或复用记录机制。
• 确认放款、还款回调重复通知场景下的防重复逻辑。
• 抽样核对放款到门店/商户账户时短信变量中的银行名称和账号后四位。