还款链接生成 — 迭代需求
对应需求：待同步飞书需求池。目标是由 FCS 按客户、借据、金额和触达场景生成可直接进入还款页的原始还款长链，供短信、客服、催收等外部触达场景继续生成短链并发送给客户。
1. 业务目标
- 支持 FCS 按客户、借据、还款金额和触达场景生成一次性还款入口链接。
- 支持短信、客服、催收等外部触达场景使用还款链接进入 H5 还款页。
- 支持通过
scene=3 区分短链触达来源，便于支付、FCS 和数据分析归因。
- 支持还款链接生成失败时阻断短链创建和短信发送，避免客户收到不可用链接。
- 支持后续与 12-短链服务 衔接，将还款长链压缩为可追踪、可过期的短链。
2. 范围
2.1 本期包含
| 能力 | 范围 |
|---|
| 还款链接生成 | FCS 根据客户、借据、还款金额、触达场景调用支付中台初始化还款页面，获得可跳转的还款长链 |
| 来源场景标识 | 短信、客服、催收等外部触达生成还款链接时固定传 scene=3 |
| 服务端校验 | FCS 生成还款链接前重新校验借据状态、还款试算、金额规则和在途订单 |
| 失败阻断 | 支付中台初始化失败时，不继续创建短链，不发送还款链接短信 |
| 链路衔接 | 生成成功后，将还款长链传给短链服务继续压缩和追踪 |
2.2 本期不包含
- 短码生成、短链跳转、短链访问追踪和短链有效期管理，详见 12-短链服务。
- 面向运营人员手工创建任意营销链接。
- 替代 App 内账单、还款计划和还款入口展示。
- 修改支付中台回调和 FCS 入账主链路。
3. 业务流程
FCS 确定触达客户、借据、金额和场景
-> FCS 校验借据状态、还款试算、金额规则和在途订单
-> FCS 调用支付中台初始化还款页面
-> 支付中台返回还款长链和支付参考号
-> FCS 记录还款链接生成结果
-> FCS 将还款长链传给短链服务
-> 短链服务返回短链 URL
-> FCS 将短链作为短信模板变量发送
-> 客户点击短链并跳转到原始还款长链
-> 客户完成还款
-> FCS / 支付侧按原还款链路入账
4. 链路边界
| 模块 | 职责 |
|---|
| FCS | 查询客户和借据还款事实；校验还款规则；生成还款长链；记录生成结果；将长链传给短链服务 |
| 支付中台 / Plutus | 根据 FCS 请求初始化还款页面，返回可支付的还款长链，并负责后续支付回调 |
| 短链服务 | 接收还款长链，生成短码，保存长短链映射，负责访问跳转和追踪 |
| CRS / 短信服务 | 按模板 ID 和变量发送短信；记录短信供应商请求和返回结果 |
| 还款 H5 / App | 承接原始还款长链，完成还款展示、支付发起和结果处理 |
| 数据分析 | 关联还款链接生成、短链访问、短信发送和还款结果 |
5. 生成入口
FCS 需提供内部还款链接生成能力，供还款提醒、逾期提醒、还款失败重试、客服/催收触达等场景调用。该能力不直接生成短码，而是先生成可进入还款页的原始长链，再交给短链服务压缩。
当前代码基础中，FCS 已有还款页面初始化链路：调用 /plutusWebPayInit，并通过 scene 区分入口来源。需求侧按以下口径固化：
| scene | 场景 | 说明 |
|---|
1 | App | App 内发起还款 |
2 | H5 | 普通 H5 还款入口；未传 scene 时按 H5 处理 |
3 | 短链 | 短信、客服、催收等外部短链入口 |
短链场景生成还款长链时，FCS 必须传 scene=3，便于支付、FCS 和数据分析按入口来源归因。
6. 触达业务场景定义
sceneCode 用于说明“为什么要生成这条还款链接”。它不是支付入口类型，也不是短信模板号，而是业务触达目的的稳定编码。FCS 生成还款长链和调用短链服务时均使用同一个 sceneCode，避免跨文档字段名不一致。
6.1 与 scene 的区别
| 字段 | 定义 | 示例 | 使用方 |
|---|
scene | 还款入口来源类型，告诉支付中台客户从哪里进入还款页 | 1 App、2 H5、3 短链 | FCS、支付中台、还款 H5 |
sceneCode | 业务触达场景，说明本次生成链接的业务目的 | repayment_due_reminder、repayment_overdue_reminder | FCS、短链服务、短信服务、数据分析 |
templateCode | 实际发送使用的短信或消息模板 | REPAYMENT_DUE_REMINDER_V1 | CRS / 短信服务、运营配置 |
同一 sceneCode 可以对应多个短信模板。例如逾期提醒可以按 D1、D3、D7 使用不同模板，但业务场景仍可统一归为 repayment_overdue_reminder，具体模板差异由 templateCode 承载。
6.2 定义原则
- 按“业务目的”定义，不按发送渠道定义；短信、WhatsApp、客服手动发送都可以复用同一个业务场景。
- 编码必须稳定，不能把日期、批次号、模板版本、手机号等动态值放进
sceneCode。
- 编码使用小写英文和下划线，建议格式为
repayment_{purpose}。
- 场景粒度要服务于有效期、幂等、防重复、转化统计和告警；不为每一个文案版本新增场景。
- 如果同一业务目的需要完全不同的有效期或风险控制规则，应拆成不同
sceneCode。
6.3 首批场景枚举
| 场景 | sceneCode | 触发时机 | 主要用途 | 默认有效期建议 |
|---|
| 还款日前提醒 | repayment_due_reminder | 借据到期日前固定 T-N 天批量提醒 | 提醒客户提前或按时还款 | 到应还日后 3 天，最长不超过 7 天 |
| 到期日提醒 | repayment_due_today | 借据应还日当天提醒 | 提醒客户当天完成还款 | 3 天 |
| 逾期提醒 | repayment_overdue_reminder | 借据进入逾期后按催收策略触发 | 引导客户尽快还款 | 7 天 |
| 还款失败后引导 | repayment_failed_retry | 主动还款或代扣失败后触发 | 引导客户更换方式或重新支付 | 24 小时 |
| 客服手动触达 | repayment_customer_service_notice | 客服处理来电、在线咨询、投诉时手动发送 | 给客户一个可直接还款的入口 | 由 FCS 指定，最长不超过 7 天 |
| 催收触达 | repayment_collection_notice | 催收系统或催收人员触达逾期客户时发送 | 催收还款转化和批次归因 | 由 FCS 指定，最长不超过 7 天 |
6.4 字段关系
FCS 生成还款链接时使用的 sceneCode 应原样传给短链服务，保证“还款长链生成 -> 短链生成 -> 短链访问 -> 还款成功”的统计口径一致。
FCS sceneCode
-> 短链服务 sceneCode
-> 短信发送 batch / template 统计
-> 短链访问日志
-> 还款转化归因
示例：
| FCS 字段 | 短链服务字段 | 示例 |
|---|
sceneCode | sceneCode | repayment_overdue_reminder |
batchNo | batchNo | repay-overdue-20260714-D3 |
templateCode | templateCode | REPAYMENT_OVERDUE_D3_V1 |
requestId | requestId | fcs-repay-overdue-20260714-LN123-001 |
7. 生成请求字段
| 字段 | 必填 | 说明 |
|---|
custId / customerId | 是 | 客户 ID；用于校验客户和生成还款订单 |
loanList | 是 | 本次还款关联借据列表；至少包含一笔未结清借据 |
repayAmount | 是 | 本次还款金额；以 FCS 试算和服务端校验结果为准 |
partialRepay | 是 | 是否部分还款 |
scene | 是 | 短链触达固定传 3 |
bizCode | 是 | App / 业务线标识，用于路由支付通道和数据隔离 |
requestId | 是 | 调用方幂等号，用于防止重复初始化还款链接 |
sceneCode | 是 | 触达业务场景，如 repayment_due_reminder、repayment_overdue_reminder |
batchNo | 否 | 批量触达批次号 |
templateCode | 否 | 后续短信模板编码 |
FCS 服务端必须重新读取客户、借据、还款计划、在途还款订单和还款试算结果，不能完全信任调用方传入金额。
8. 生成规则
| 规则 | 状态 | 说明 |
|---|
| 只有未结清、允许还款、无互斥在途还款处理的借据才能生成还款链接 | 现有逻辑 + 需确认覆盖 | 当前 FCS 已有还款试算、还款金额校验和在途 TP 订单校验；是否完整覆盖“未结清、锁定、核销”等状态需按最终接入场景复验 |
生成前需复用现有还款试算能力，确认 repayAmount 与当前应还金额、部分还款规则匹配 | 现有逻辑 | 当前 FCS /plutusWebPayInit 已调用主动还款试算，并校验非部分还款金额不能小于应还金额 |
| 同一客户同一时间只允许存在符合 FCS 规则的在途还款初始化，避免客户重复支付 | 现有逻辑 | 当前 FCS 已校验客户在途 TP 还款订单；短链场景继续复用该规则 |
| 短链入口必须生成 H5 可承接的支付页面 URL，不要求客户已安装 App | 现有逻辑 | 当前支付中台初始化返回 authorization_url，FCS 保存并返回该 URL |
短链触达生成还款长链时必须传 scene=3 | 现有能力 + 新增约束 | 当前请求字段和透传能力已存在；本需求要求短信、客服、催收等短链触达场景统一固定传 3 |
FCS 必须传入合法 sceneCode，并原样传给短链服务 | 新增需求 | 当前代码只有支付入口 scene，缺少业务触达场景编码；需新增字段传递、枚举校验和统计口径 |
| 返回的长链只作为跳转载体，不在短信模板中直接使用；短信优先使用短链 | 新增需求 | 当前代码可返回长链；本需求要求短信触达链路先压缩为短链，再作为模板变量发送 |
| 长链中不得明文暴露手机号、姓名、证件号、银行卡号等敏感信息 | 需确认 + 新增约束 | 需确认支付中台返回 URL 的参数形态；如存在明文敏感字段，需改为 token、加密参数或服务端态查询 |
| 如果支付中台初始化失败，FCS 不得继续创建短链或发送还款链接短信 | 现有逻辑 + 新增衔接约束 | 当前初始化失败会抛错；本需求要求后续短链和短信链路必须显式识别失败并停止 |
9. 返回字段
| 字段 | 说明 |
|---|
longUrl | 支付中台返回的还款页面长链，后续传给短链服务 |
paymentOrderId / referenceId | 支付初始化订单号或参考号，用于后续回调和排查 |
custId | 客户 ID |
loanIdList | 本次还款关联借据 |
repayAmount | 服务端确认后的还款金额 |
scene | 入口场景，短链触达为 3 |
expireTime | 建议短链失效时间，可由 FCS 按场景给出 |
10. 安全与风控
- 还款链接生成时必须校验客户、借据、金额和在途订单状态，不能只根据短信批次或外部传参生成支付入口。
- 支付中台返回的长链不得在业务日志中明文打印。
- 还款长链只能指向白名单域名下的还款页面。
- 还款长链不承担客户身份认证和金额最终确认职责，敏感校验仍由还款页和 FCS 服务端完成。
- 若借据已结清、已核销、已被锁定处理或存在互斥在途还款，不允许生成新的还款链接。
11. 监控告警
| 监控项 | 告警条件 |
|---|
| 还款长链生成失败率 | 连续 5 分钟超过阈值 |
| 支付中台初始化耗时 | P95 超过阈值 |
短链场景缺失 scene=3 | 批次内出现异常比例超过阈值 |
| 初始化成功但短链创建失败 | 批次级异常，用于排查短链服务或字段映射问题 |
| 短信成功但还款链接访问为 0 | 批次级异常，用于排查模板、域名或链路问题 |
12. 验收标准
- FCS 能按
custId、loanList、repayAmount、partialRepay 和 scene=3 初始化还款页面。
- FCS 生成还款长链前必须完成借据状态、还款试算、在途订单和金额规则校验。
- FCS 能按定义传入合法
sceneCode，并原样传给短链服务。
- 支付中台初始化成功后，FCS 能获得可访问的还款长链和支付参考号。
- 支付中台初始化失败时，不创建短链、不发送还款链接短信，并记录失败原因。
- 短链触达生成的还款链接可以被识别为
scene=3 来源。
- 还款长链可以被 12-短链服务 正常压缩为短链并完成跳转。
13. 上线清单
- 确认 FCS 还款链接生成入口、调用方权限和
scene=3 传参规则。
- 确认
sceneCode 首批枚举、默认有效期、短信模板和批次规则。
- 确认支付中台返回的还款长链可被 H5 正常承接。
- 确认还款长链生成失败时的短信发送降级策略。
- 确认还款长链域名白名单。
- 确认 FCS 与短链服务的字段映射关系。
- 确认还款长链生成失败、支付中台初始化耗时、短链创建失败等监控告警。