数据模型总览

本章节定位

定义袋鼠金融的核心数据骨架。架构和数据模型稳定后，业务规则可以反复迭代而不动表结构。
本文是总览，每个实体的字段、关系、状态机详情见子目录文档。

设计原则

1. 按系统组织 + 复用层标注

主组织维度：每张表归且仅归一个拥有系统所有，实体清单按系统列。这是数据归属的物理边界。

复用层标注（属性而非分类）：每张表标注是”金融核心层”还是”业务对象层”，反映跨业务线复用范围——

复用层	说明	复用范围
金融核心层	跨业务线共享的金融实体（客户、借据、还款计划、催收案件等）	消费分期、现金分期、虚拟卡上线时全部复用
业务对象层	业务线专属的实体（订单、分期申请、合同、首付等）	仅本业务线使用，新业务线各自有自己的业务对象层

关键判断：现金分期、虚拟卡未来上线时，金融核心层的表结构不动，只新增各自的业务对象层。

2. 系统拥有原则

每个实体明确归属一个系统拥有：

该系统是这张表的唯一写入方
其他系统通过 ID 引用，不直接共用表
同一字段不在两个系统同时维护

3. 授信申请 → 借款申请 → 借据三段解耦

借款流程分为两类申请 + 一类借据，对应”先授信、再用信、再产生债权”的金融关系演进：

实体	语义	结果
credit_application（授信申请）	建立信用关系	开通 credit_account / 调整额度
loan_application（借款申请）	在已授信额度内提取一笔借款	生成 loan
loan（借据）	单笔债权凭证	后续还款/催收/结清挂在这里

credit_application 通过 → 触发 credit_account 开户/调额
loan_application 通过审批后 → 生成 loan，loan 持有 loan_application_id 作为来源追溯
借据生成后，金融生命周期（还款、催收、结清）全部挂在借据上
现金分期/虚拟卡天然两阶段（先授信，再多次用信）；消费分期单笔单批由业务服务层 submitOneStop 封装首笔（同事务串行 credit_application + loan_application），UI 一次提交

4. 状态机分级

不是所有实体都画状态机：

等级	含义	处理方式
A	流程驱动，多状态流转，每次状态变更触发业务动作	在该实体的文档里画完整状态机
B	档案类，只有可用性标记	一个 `status` 字段（active / inactive / suspended）
C	流水/明细，无生命周期	只有结果终态（success / failed / pending）

5. 多租户与多国

所有业务实体携带 country_code + tenant_id（参考 02-能力地图与演进规划的两层租户模型）。

6. 资金方预留

loan 持有 funder_id 字段，自有资金时默认指向平台自身，未来接入助贷资金方时不动表结构。

7. 客户级差异化定价

所有产品条款字段（利率 / 期数 / 单笔上下限 / 罚息率 / 服务费率）都是客户级专属值，由风控基于客户风险评估给出。早期风险政策可以给统一值，但字段语义和命名必须按客户级独立设计（不带 default_ 前缀），支持后期分客群、分客户的差异化经营。

落地：credit_account 的 effective_interest_rate / effective_penalty_rate / max_tenor / max_loan_amount 等字段，配合 pricing_segment + pricing_strategy_id 用于定价依据追溯。

8. 扩展机制 + 早期简化

核心原则：数据模型保留长期扩展能力，但早期实现取主路径简化版。

具体表现：

枚举字段预留扩展值（如 component_type、fee_type、product_type），早期只用其中几个
类型化字段（calculation_type / allocation_method / beneficiary 等）支持多分支，早期默认主分支
聚合/快照字段与详情实体并存（loan 的余额字段是缓存，明细在 schedule/fee 等子实体）
辅助字段（pricing_strategy_id / source_ref / approval_id）允许早期 NULL，但保留追溯能力
配置中心承载早期产品/费用/活动模板，复杂时再升级为表

目的：避免长期重构。早期写少代码，但表结构和实体边界按未来需要的样子设计。

实体清单

组织维度：本文档以”拥有系统”为唯一分类轴。每张表归且仅归一个系统所有，业务上是否跨业务线复用作为附加属性（复用层）标注，不作为独立分类。

复用层标记：

🟢 核 = 金融核心层：跨业务线复用（消费分期/现金分期/虚拟卡共用）
🔵 务 = 业务对象层：业务线专属（仅消费分期使用，新业务线新增）

客户系统（4）

#	实体	复用	状态等级	说明
1	customer	🟢 核	B	客户主档案
2	customer_identity	🟢 核	C	身份凭证（BVN / NIN / 护照等多条）
3	customer_payment_method	🟢 核	B	绑卡（收款+代扣）
4	customer_emergency_contact	🟢 核	B	紧急联系人（多个）

进件中心（2）

#	实体	复用	状态等级	说明
1	credit_application	🟢 核	A	授信/开户申请（建立信用关系，触发 credit_account 开户/调额）
2	loan_application	🟢 核	A	借款/用信申请（在已授信额度内）

合同中心（1）

#	实体	复用	状态等级	说明
1	contract	🟢 核	A	电子合同

额度中心（3）

#	实体	复用	状态等级	说明
1	credit_account	🟢 核	A	信用账户（双层：master 主账户 + 产品子账户）
2	credit_limit_item	🟢 核	A	额度组成（基础/增信/临时/营销/人工调额/合作方专项）
3	credit_account_change_log	🟢 核	C	信用账户变更日志

账务核心（6）

#	实体	复用	状态等级	说明
1	loan	🟢 核	A	借据
2	loan_fee	🟢 核	B	借据费用项（利息/罚息/服务费/办理费等）
3	repayment_schedule	🟢 核	A	每期应还
4	repayment_record	🟢 核	C	实际还款流水
5	repayment_allocation	🟢 核	C	销账明细
6	penalty_record	🟢 核	C	罚息计提记录

风控系统（1）

#	实体	复用	状态等级	说明
1	risk_decision	🟢 核	C	风控决策留档

支付网关（2）

#	实体	复用	状态等级	说明
1	fund_transaction	🟢 核	C	资金流水（放款/还款/退款）——放款中心/还款中心引用
2	reconciliation_record	🟢 核	C	每日对账记录

催收系统（2）

#	实体	复用	状态等级	说明
1	collection_case	🟢 核	A	催收案件（一笔逾期借据对应一个案件）
2	collection_action	🟢 核	C	催收作业记录（每次触达/承诺）

运营系统（2）

#	实体	复用	状态等级	说明
1	ops_user	🔵 务	B	运营后台账号
2	ops_action_log	🔵 务	C	运营操作日志

消息网关（2）

#	实体	复用	状态等级	说明
1	message_template	🔵 务	B	消息模板
2	message_log	🔵 务	C	消息发送记录

业务服务层（3）——消费分期专用

#	实体	复用	状态等级	说明
1	order	🔵 务	A	商品订单（消费分期专属）
2	order_item	🔵 务	B	订单明细
3	down_payment	🔵 务	A	首付记录

渠道中心 / 商品中心（本轮范围外，列出供参考）

商户/门店/SA/商品/分期方案等实体属于消费分期业务前置依赖，详见 00-总览。

复用层小结

复用层	实体数	含义
🟢 金融核心层	19	跨业务线复用，现金分期/虚拟卡上线时表结构不动，只新增业务线专属对象
🔵 业务对象层	8	运营系统/消息网关/消费分期专属

跨产品共用的关键判断：credit_application / loan_application / contract 共用主表+ product_type 区分，正文/分支差异由配置中心和状态机分支处理。真正业务专属的只有 order / order_item / down_payment。

状态机统计

A 级（需画状态机）共 9 个：credit_account、credit_limit_item、credit_application、loan_application、contract、loan、repayment_schedule、collection_case、order、down_payment

注：本轮范围外的 merchant_application、sa_application 也是 A 级，未计入此处统计。

实体关系图（客户视角，第一轮 23 个实体）

注意：下图按客户业务流程的几个阶段做了 subgraph 分组（客户/申请/金融/资金/催收），这只是视觉分组帮助读者理解业务流程，不是数据分类维度——数据归属以”实体清单”中的拥有系统为准。

颜色含义：

🟡 黄底（A 级）— 有完整状态机
🔵 蓝底（B 级）— 有简单 status 字段
⚪ 灰底虚线（C 级）— 流水/明细，无生命周期

graph LR
    classDef levelA fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#000
    classDef levelB fill:#d1ecf1,stroke:#0c5460,color:#000
    classDef levelC fill:#f8f9fa,stroke:#6c757d,stroke-dasharray: 4 2,color:#000

    subgraph 客户域
        direction TB
        C[customer]:::levelB
        CI[customer_identity]:::levelC
        CBC[customer_payment_method]:::levelB
        CEC[customer_emergency_contact]:::levelB
        C --> CI
        C --> CBC
        C --> CEC
    end

    subgraph 申请域
        direction TB
        CAPP[credit_application]:::levelA
        LAPP[loan_application]:::levelA
        O[order]:::levelA
        OI[order_item]:::levelB
        CT[contract]:::levelA
        DP[down_payment]:::levelA
        RD[risk_decision]:::levelC
        CAPP -.开户/调额触发.-> RD
        LAPP --> O
        O --> OI
        LAPP --> CT
        LAPP --> DP
        LAPP --> RD
    end

    subgraph 金融域
        direction TB
        CA_M[credit_account · master]:::levelA
        CA_S[credit_account · 子账户]:::levelA
        CLC[credit_limit_item]:::levelA
        L[loan]:::levelA
        LF[loan_fee]:::levelB
        RS[repayment_schedule]:::levelA
        RR[repayment_record]:::levelC
        RA[repayment_allocation]:::levelC
        PR[penalty_record]:::levelC
        CA_M --> CA_S
        CLC --> CA_S
        CA_S --> L
        L --> LF
        L --> RS
        L --> RR
        L --> PR
        RR --> RA
        RA -.精确销账.-> LF
    end

    subgraph 资金域
        direction TB
        FT[fund_transaction]:::levelC
    end

    subgraph 催收域
        direction TB
        CC[collection_case]:::levelA
        CA[collection_action]:::levelC
        CC --> CA
    end

    %% 跨域核心关系
    C --> CAPP
    C --> LAPP
    CAPP -.approved 触发开户/调额.-> CA_S
    LAPP -.前置 active.-> CA_S
    LAPP -.审批通过.-> L
    LAPP -.in_review 占用.-> CA_S
    C -.客户级总授信.-> CA_M
    L -.逾期触发.-> CC
    L -.逾期触发账户冻结.-> CA_S

    %% 资金留痕
    L -.放款.-> FT
    RR -.还款.-> FT
    DP -.首付.-> FT

    %% 客户子实体的下游使用
    CBC -.扣款.-> RR
    CEC -.催收联系.-> CA

    %% 销账与罚息回填
    RA -.销到.-> RS
    PR -.针对.-> RS

阅读要点

关系类型	视觉	含义
实线	`-->`	强关系：父子归属、聚合
虚线	`-.->`	弱关系：跨域引用、状态触发、销账回填

三条主线

业务主线：customer → credit_application（开户） → loan_application（用信） → loan → repayment_schedule → collection_case
资金主线：down_payment → fund_transaction ← loan（放款） / repayment_record（还款）
客户子实体下游：customer_payment_method → repayment_record（扣款）；customer_emergency_contact → collection_action（催收）

各产品流程差异

产品	首笔流程	复借流程
消费分期（手机分期）	业务服务层 submitOneStop 同事务串行 credit_application + loan_application（UI 一次提交）	直接 loan_application
现金分期	用户先做 credit_application（独立申请额度）	已授信后多次 loan_application（用信）
虚拟卡（远期）	credit_application（开卡授信）	loan_application 或交易记录（每笔消费/分期）

现金分期专属点：

跳过：order / order_item / down_payment / agent / merchant / installment_plan
新增字段（loan_application）：intended_use（借款用途，监管要求）+ disbursement_bank_card_id（放款收款账户，指向 customer_payment_method）
状态机分支：approved → contract_signed → disbursed（无 ready_to_disburse 首付中间态）
资金路径：直接打款到客户银行卡，不经商户分账

客户回流场景与 draft 治理

问题：客户填了一半 draft 后流失，半年后回来。直接复用旧 draft 会导致风控数据时效性问题、产品参数已变、客户基础信息可能过期。

处理机制（跨实体协同）：

阶段	动作	数据归属
1. draft 过期治理	定时 job 扫超期 draft → status=canceled，canceled_reason=draft_expired，数据保留不删	loan_application / credit_application
2. 客户再次进件	创建新 application，不复用旧 draft（风控/参数时效性都已失）	loan_application / credit_application
3. 稳定字段预填	业务服务层从客户主档案读取，自动填入新 application	客户中心 4 个实体
4. 时效性字段重采	收入/就业、商品订单、设备/IP/位置、用途等必须重新采集	业务服务层采集后写入

TTL 设置（按 product_type 配置）：

产品	loan_application draft TTL	credit_application draft TTL
consumer_finance	7 天（SA 代客办单流失快）	30 天
cash_loan	30 天	30 天
virtual_card	30 天	30 天

这正是当初拆”客户主档案 vs 申请单”的价值兑现：

长期稳定（客户中心，跨申请复用）	短期时效（信贷核心 application，每次重采）
姓名 / 出生信息 / 性别	收入 / 就业状态
BVN / NIN / 护照（customer_identity）	商品订单 / 首付方案
还款绑卡（customer_payment_method）	设备指纹 / IP / 位置
紧急联系人（customer_emergency_contact）	借款用途（监管要求）
客户级条款（credit_account effective_*）	单次申请的具体条款

UI 上对客户表现为**“无感继续”**——身份/绑卡/紧急联系人都不用重填——但数据层是干净的新申请记录。

历史/宏观主线（含本轮未建实体）

下图保留原宏观视角，包含本轮范围外的 merchant / agent / sku 等渠道域实体，仅供参考。

graph LR
    subgraph 渠道域
        M[merchant] --> S[store]
        S --> A[agent]
        MA[merchant_application] -.通过后生成.-> M
        SA_A[sa_application] -.通过后生成.-> A
    end

    subgraph 客户域
        C[customer]
        C --> CBC[customer_payment_method]
        C --> CI[customer_identity]
    end

    subgraph 业务域
        SKU[sku] --> IP[installment_plan]
        SKU --> OI[order_item]
        OI --> O[order]
        O --> APP[application]
        A -.SA代客办单.-> APP
        C --> APP
        IP --> APP
        APP --> CT[contract]
        APP --> DP[down_payment]
        APP --> RD[risk_decision]
    end

    subgraph 金融域
        APP -.审批通过.-> L[loan]
        L --> RS[repayment_schedule]
        RS --> RR[repayment_record]
        RR --> RA[repayment_allocation]
        L --> PR[penalty_record]
        L -.逾期.-> CC[collection_case]
        CC --> CA[collection_action]
    end

    subgraph 资金域
        FA[fund_account] --> FT[fund_transaction]
        L -.放款.-> FT
        RR -.收款.-> FT
        DP -.首付分账.-> FT
        M --> FA
    end

    L -.funder_id.-> F[funder]

数据资产归属（按系统）

数据归属以拥有系统为唯一分类轴。每张表归且仅归一个系统，详见上方”实体清单”按系统的分组。下面只补充每个系统的资产特征摘要、与业务能力的映射，以及跨系统访问规则。

各系统资产特征

系统	实体数	资产特征
客户中心	4	客户档案的唯一权威源，跨业务线共享
业务服务层	3	商品销售业务粘合对象（order / order_item / down_payment）；贷前流程编排不持有信贷数据
风控系统	4	决策结果 + 信用账户（双层）+ 额度组成（多类型）+ 账户变更审计
账务核心	6	完整闭环：借据 → 分期 → 还款流水 → 销账 → 罚息（含扩展型费用结构）
资金系统	1	本轮仅资金流水；fund_account 二轮再建
催收系统	2	案件 + 作业流水，闭环

业务能力域 ↔ 系统映射（已有信息汇总）

能力域	主要落地系统
客户运营域	客户中心
信贷业务域	业务服务层（贷前编排）+ 进件中心/合同中心/额度中心/放款中心/账务核心/还款中心（金融核心）
风控域	风控系统
资金域	资金系统
催收（含信贷业务域贷后）	催收系统
渠道与获客域	渠道中心（本轮未建实体）
供应链域	商品中心 + 供应链系统（中期建设）

跨系统访问的硬规则

规则	说明
不共用表	系统之间通过 ID 引用，不允许跨系统直接读写对方表
冗余可控	业务对象可冗余少量金融核心字段（如 application 冗余商品名/方案）；金融决策性字段（如 schedule.principal_due）不冗余
写入唯一	每张表只有 owner 系统可以写；其他系统通过 owner 提供的 API/事件订阅获取数据
事件驱动同步	跨系统状态联动通过事件（如 loan 逾期事件 → 催收系统建案）

跨系统引用约定

引用规则

规则	说明
ID 引用	跨系统实体之间用全局唯一 ID 引用（如 `customer_id`、`loan_id`），不共用表
冗余可控	业务对象可冗余少量金融核心字段（如 application 冗余商品名称、SKU 价格快照），但金融决策性字段（如还款计划金额）不冗余
来源追溯	转换性实体保留来源 ID（如 loan 持有 application_id，merchant 持有 merchant_application_id）
租户标识	所有业务实体携带 `country_code` + `tenant_id` 用于多国/多运营主体隔离

ID 命名约定

主键：<entity>_id，如 customer_id、loan_id
外键：保持来源命名，如 application 表中的 customer_id、agent_id
全局唯一，不复用、不语义化

实体文档约定

每个实体文档（06-数据模型/<拥有系统>/<entity>.md）按以下统一结构编写：

# <entity> — 中文名

## 1. 实体定义
- 业务含义
- 拥有系统
- 状态等级（A/B/C）

## 2. 字段
| 字段 | 类型 | 说明 | 必填 |
（核心字段，不写完整 DDL）

## 3. 关系
- 关联的其他实体（外键引用）

## 4. 状态机（仅 A 级）
- 状态枚举
- 状态流转图（mermaid stateDiagram）
- 状态变更触发的业务动作

## 5. 关键业务规则
- 该实体特有的约束、校验、计算规则

## 6. 索引/约束建议
- 主键、唯一索引、查询索引提示

实体详情索引

袋鼠金融蓝图

探索

数据模型总览

设计原则

1. 按系统组织 + 复用层标注

2. 系统拥有原则

3. 授信申请 → 借款申请 → 借据 三段解耦

4. 状态机分级

5. 多租户与多国

6. 资金方预留

7. 客户级差异化定价

8. 扩展机制 + 早期简化

实体清单

客户系统（4）

进件中心（2）

合同中心（1）

额度中心（3）

账务核心（6）

风控系统（1）

支付网关（2）

催收系统（2）

运营系统（2）

消息网关（2）

业务服务层（3）——消费分期专用

渠道中心 / 商品中心（本轮范围外，列出供参考）

复用层小结

状态机统计

实体关系图（客户视角，第一轮 23 个实体）

阅读要点

三条主线

各产品流程差异

客户回流场景与 draft 治理

历史/宏观主线（含本轮未建实体）

数据资产归属（按系统）

各系统资产特征

业务能力域 ↔ 系统映射（已有信息汇总）

跨系统访问的硬规则

跨系统引用约定

引用规则

ID 命名约定

实体文档约定

实体详情索引

客户系统

进件中心

合同中心

额度中心

账务核心

风控系统

支付网关

催收系统

运营系统

消息网关

业务服务层（消费分期专用）

本轮范围外（参考）

关系图谱

目录

3. 授信申请 → 借款申请 → 借据三段解耦