袋鼠金融蓝图

PocketBuy 协议模板字段说明与逻辑说明

说明对象：D:\Africa\生产协议\PoketBuy\PocketBuy_Loan_Agreement_Template.md

一、字段说明

1. 协议信息

字段含义说明
${AGREEMENT_REFERENCE}协议编号唯一标识本笔手机分期贷款协议，建议由系统生成。
${AGREEMENT_DATE}协议签署日期Borrower 在 App 点击提交或签署协议的日期。

2. 借款人信息

字段含义说明
${BORROWER_FULL_NAME}借款人姓名应与 KYC、BVN、NIN 等身份信息一致。
${BORROWER_ADDRESS}借款人地址借款人登记地址或居住地址。
${BORROWER_PHONE}借款人手机号用于通知、还款提醒、逾期触达等。
${BORROWER_BVN}借款人 BVN尼日利亚身份核验及征信查询字段。

3. 设备信息

字段含义说明
${DEVICE_BRAND_MODEL}设备品牌型号例如 Tecno Spark、Samsung Galaxy 等。
${DEVICE_IMEI}设备 IMEI设备唯一识别码。若同一融资设备存在多个 IMEI，应在该字段中展示多个 IMEI，例如按换行、逗号或分号分隔；展示顺序应与交机/MDM 绑定记录一致。

4. 贷款金额与费用

字段含义说明
${CASH_PRICE}设备现金价手机原始销售价格。
${DOWN_PAYMENT}首付款Borrower 在交机前支付的金额，不属于贷款本金。
${PRINCIPAL}贷款本金Lender 为 Borrower 垫付给 Sales Point 的融资金额。
${TOTAL_INTEREST}总利息本笔贷款期限内应收取的全部利息。
${TOTAL_REPAYABLE}总应还金额Borrower 需偿还的总金额，通常为本金、利息及已披露费用之和。
${TENOR}贷款期限展示实际贷款期限，例如 6 months、12 months。
${INSTALMENT_COUNT}还款期数实际还款期数，例如 6、9、12。
${INSTALMENT_AMOUNT}每期还款金额每期周期性还款金额。等额分期时每期一致。
${APR}年化利率Annual Percentage Rate，用百分比展示。
${LATE_FEE_RATE}逾期费率逾期后按 overdue amount 计算的每日逾期费率。

5. 日期字段

字段含义说明
${AGREEMENT_DATE}协议签署日期协议成立日期。
${FIRST_DUE_DATE}首期还款日第 1 期还款到期日，应与 ${DUE_DATE_01} 一致。
${LAST_DUE_DATE}最后一期还款日实际最后一期还款到期日，应与实际期数对应的 ${DUE_DATE_N} 一致。
${DUE_DATE_01} 至 ${DUE_DATE_12}第 1 至第 12 行到期日Schedule 2 固定展示 12 行；实际期数不足 12 时，后续行填 -。

6. 还款计划字段

字段含义说明
${DUE_DATE_01} 至 ${DUE_DATE_12}每行到期日实际期次展示到期日；超过实际期数的行填 -。
${PRINCIPAL_01} 至 ${PRINCIPAL_12}每行本金实际期次展示本金；超过实际期数的行填 -。
${INTEREST_01} 至 ${INTEREST_12}每行利息实际期次展示利息；超过实际期数的行填 -。
${REPAYMENT_AMOUNT_01} 至 ${REPAYMENT_AMOUNT_12}每行应还总额实际期次展示应还总额；超过实际期数的行填 -。

7. 紧急联系人字段

字段含义说明
${EMERGENCY_CONTACT_NAME_1}紧急联系人 1 姓名第 1 个紧急联系人姓名。
${EMERGENCY_CONTACT_PHONE_1}紧急联系人 1 手机号第 1 个紧急联系人联系电话。
${EMERGENCY_CONTACT_RELATIONSHIP_1}紧急联系人 1 关系第 1 个紧急联系人与 Borrower 的关系。
${EMERGENCY_CONTACT_NAME_2}紧急联系人 2 姓名第 2 个紧急联系人姓名。
${EMERGENCY_CONTACT_PHONE_2}紧急联系人 2 手机号第 2 个紧急联系人联系电话。
${EMERGENCY_CONTACT_RELATIONSHIP_2}紧急联系人 2 关系第 2 个紧急联系人与 Borrower 的关系。

二、逻辑说明

1. 模板变量格式

协议模板统一使用 ${FIELD_NAME} 作为变量格式。变量命名采用大写英文和下划线：

  • 主协议级字段直接使用业务名，例如 ${AGREEMENT_DATE}、${BORROWER_FULL_NAME}。
  • 还款计划字段使用两位期号后缀，例如 ${DUE_DATE_01}、${PRINCIPAL_12}。
  • 紧急联系人字段使用联系人序号后缀，例如 ${EMERGENCY_CONTACT_NAME_1}、${EMERGENCY_CONTACT_NAME_2}。

2. 金额关系

CASH_PRICE = DOWN_PAYMENT + PRINCIPAL
TOTAL_REPAYABLE = PRINCIPAL + TOTAL_INTEREST + disclosed fees/charges

等额分期时：

INSTALMENT_AMOUNT = TOTAL_REPAYABLE / INSTALMENT_COUNT

如果存在四舍五入尾差，应归入实际最后一期，并保证实际期次的还款金额之和等于 ${TOTAL_REPAYABLE}。

3. 年化利率 APR 计算逻辑

APR 应反映 Borrower 使用贷款资金的年化成本。推荐按现金流内部收益率口径计算：

放款时点现金流 = PRINCIPAL
每期还款现金流 = -REPAYMENT_AMOUNT_N
APR = period_IRR * periods_per_year * 100%

其中：

  • period_IRR 为按实际还款计划现金流计算出的单期内部收益率。
  • periods_per_year 为一年内的还款周期数；月还为 12，周还为 52。
  • 如果业务使用近似口径，可使用 APR = TOTAL_INTEREST / PRINCIPAL / TENOR_DAYS * 365 * 100%，但应与前端展示、合同生成和风控定价保持同一口径。

4. Schedule 2 固定 12 行展示规则

Schedule 2 固定展示 12 行，用于兼容最长 12 期的协议展示。

当实际还款期数不足 12 期时：

  • 实际存在的期次正常展示到期日、本金、利息、应还总额。
  • 超过实际期数的后续行，Due Date、Loan Principal、Interest、Repayment Amount 均展示 -。

示例：实际为 6 期时，第 1 至第 6 行展示实际还款计划，第 7 至第 12 行全部展示 -。

一致性要求：

  • ${FIRST_DUE_DATE} 必须等于 ${DUE_DATE_01}。
  • ${LAST_DUE_DATE} 必须等于实际最后一期的 ${DUE_DATE_N}。
  • 实际期次的本金合计应等于 ${PRINCIPAL}。
  • 实际期次的利息合计应等于 ${TOTAL_INTEREST}。
  • 实际期次的应还总额合计应等于 ${TOTAL_REPAYABLE}。

5. 紧急联系人逻辑

Schedule 3 固定为 2 个紧急联系人：

  • 两个联系人均应在协议生成前完成采集。
  • 联系人不是 guarantor，不承担还款责任。
  • 逾期或失联时，只能用于联系 Borrower，不应向联系人披露贷款金额、逾期余额或其他债务细节。

6. 生成校验建议

协议生成前建议校验：

  • 所有 ${...} 字段均已替换完成，不应残留模板变量。
  • IMEI 多个时应全部展示，不应只展示第一个。
  • Schedule 2 必须固定输出 12 行。
  • 实际期数不足 12 时，后续行必须使用 - 占位。
  • 两个紧急联系人姓名、手机号、关系均不能为空。
  • 金额、期数、日期、APR 口径应与贷款计划计算结果一致。

关系图谱