D09 风控与合规域 · 设计文档

本域总览见《账号计费中心 · 结构大纲》。本文为该域完整设计：定位与边界 / 角色与依赖 / 数据模型 / 核心流程 / 接口契约 / 关键约束与验收标准。 章节顺序理由：先数据模型（事实结构）→ 再核心流程（结构之上的运行路径）→ 最后接口契约（流程的对外投影）。

1. 定位与边界

定位：本域承载门禁的判定口径、扫描与处置的闭环、实名合规的事实。

• 门禁判定口径：访问密钥可用性、实名等级对开票资质的前置判定、协议版本一致性、欠款账龄分级下的准入口径；执行面在各准入点（准入状态键读侧、下单与充值入口、开票入口），本域给出口径与事实来源。
• 扫描与处置：以规则目录为输入、以台账为输出——用量异常（绝对阈值突增、环比陡增）、对账异常（多扣 / 缺扣）、免计费量级突增；命中落台账与站内信，解除回写台账并驱动生效参数收敛。
• 实名合规：个人二要素核验与企业主体认证两条线，渠道抽象与 mock 渠道运行期门禁，实名等级产出及其在开票资质上的落点。

关键口径

边界

• 不管计量口径：用量日聚合与流水的产生属计量与计费域，本域只读聚合结果作判据（§4.1）。
• 不管准入执行与密钥生命周期：额度判定、生命周期状态、宽限窗口、状态键发布属账户状态与准入域；密钥创建、过期策略、软删、成员与组联动属订购与支付域；本域只写门禁口径（§4.9）与风控处置（§4.6）。
• 不管身份域门禁实现与协议留痕表：登录限流与图形码、滑块门禁的计数与拦截属身份域；同意历史与用户资料上的同意版本列属身份域，本域只写版本选择与门禁判定（§4.10）。
• 不管通知通道与运营面索引：站内信与告警的投递、模板与选路属通知与触达域；运营面端点语义在本域、统一索引登记在 D11。

归属口径：本域端点 = 门户实名校验链 /api/account/real-name（5）+ 内部运营链 /internal/risk（9）+ 运营面风控与实名复核段（11）；两条运营通道共用同一实现。

2. 角色与依赖

能力矩阵

• 运营面按能力拆权限范围：风控与密钥处置属风控范围，实名复核属客户范围；只持一段访问另一段即被拒。外部操作人不在本域用户表时不落组织审计外键，由对侧双写审计留痕。

上游依赖

下游被引用

3. 数据模型

group_id 只作定位线索、不建外键：组可能被停用，台账必须留在历史里可查。核验记录的操作人列都是置空删除——用户注销不连带抹掉实名事实。

• 台账对规则、客户、组织是受限删除的实外键：命中不允许留下无主规则线索；组织或客户被物理删除（受控维护）时才随行消失。
• 台账对用量聚合与流水只作读数源、不建跨域外键；密钥台账所有权在订购与支付域，本域只读其行并写 status 列。

3.3 表清单（4 表）

• 数据源与判据：用量日聚合与流水的产生在计量与计费域，本域只读；组织（可被规则限定到单组织）与组的 tokens 合计严格大于阈值才命中、等值不命中，无客户记录的组织防御性跳过。
• 窗口与幂等：窗口为「近 N 天」，起算日以业务时区当天为锚、与日聚合归日口径一致（取数据库会话时区当前日会漏检）；window_days 默认 1、threshold_tokens 必须为正、risk_spike_dedupe_hours 默认 24 内同规则 + 同组织 + 同组不重复落台账与发信。

• 与绝对阈值互补：绝对阈值需预设基线，环比规则按客户自身历史判定，规则上线不必先定阈值。
• 参数：multiplier 默认 3（必须为正）、baseline_periods 默认 3、consecutive_periods 默认 2，后两者至少 1；窗口起点为业务日减「连续周期数 + 基线周期数」，基线为零不触发。
• 动作联动：notify_and_downshift 命中的范围生效限速减半，直至该台账置 resolved；本域只落信号与生效参数，收敛到模型侧的执行面在计费路由。

• 窗口与容差：默认扫描「昨天」起往前 N 天（reconcile_scan_window_days 默认 1），只取已完结窗口以免在途数据误报；差异超过 reconcile_tolerance_amount（默认 0，即精确比对）且该组至少有量或有钱才落台账，纯入账日不算异常。
• 方向与落法：扣减大于计量为多扣（钱不可重放，处置优先级最高）、小于为缺扣（可补扣），两值由服务层枚举给出；异常金额与容差以分整数落既有整数列、展示按规则类型渲染，不把「分」当 tokens；去重窗口 reconcile_dedupe_hours 默认 24。

• 参数：倍数 reconcile_waiver_spike_ratio 默认 5、计数下限 reconcile_waiver_spike_min_count 默认 10，任一非正即关闭该告警；窗口天数与对账扫描同源。
• 口径：免计费留痕不计入钱与量的等式，本规则只做自身量级监控，跨侧事件数比对属计费路由的每日比对职责；连续窗口内免计费话单数突增指向误免或漏定价嫌疑。

• 流转与留痕：台账仅两态且单向前进，重复解除是幂等写、响应用变更标记区分是否真的改了状态；解除携带处置人与结论，操作人由调用侧给出（运营面取登录主体，内部运营链取请求头线索），不在本域用户表时不落外键、线索走审计。
• 后果收敛：解除后该范围生效限速不再减半，由读侧按生效限速自行收敛回档位默认值，本域不主动回改档位。

• 封禁后果口径：被禁用密钥不可调用——扣费的密钥层据此拒绝并返回 403 key_disabled，客户侧密钥状态页即时可见「已禁用」；台账行、展示前缀与历史归因不被改写。
• 解封与边界：解封幂等（泄露误判或密钥已完成轮换后恢复），封禁与解封都必须给原因（2～200 字符）并随审计留痕；密钥创建、额度周期、过期策略、软删、成员与组联动属订购与支付域，本域只写 status 两值；检索按展示前缀模糊匹配并按组织与状态收窄。

• 格式与每日上限：证件号按 18 位受理、前 17 位须为数字、末位为校验码，按居民身份证加权因子与校验码表（模 11-2 算法）核验；id_verify_daily_limit 默认 5、按自然日清零，成功、比对不符、渠道异常都计入（异常可能是「已计费但无结果」，口径与渠道账单对齐）。
• fail-closed 两处：mock 渠道在非白名单环境解析即拒（白名单为开发环境，预发需显式开启且默认关），绝不静默回落真实渠道；真实渠道凭据（地址、应用标识、密钥、超时）任一为空即拒服务。
• 最小化与同意时序：完整证件号只在内存与渠道请求中流转、落库仅末四位，只做正向核验不做反查；同意先于渠道，与待核验行同一次落库写入，且同意时刻与行创建时刻同源。

• 企业侧不得自助通过：无自动定案能力的渠道，点一下即通过的路径被单点卡死（403 manual_review_required），未知渠道按需人工复核处理（fail-closed）；应打金额由渠道发起时生成，比对失败累计不超过 3 次，超限置失败并 422，需重新发起。
• 运营复核定案：队列默认取待复核与自动核验失败两类、按提交时刻升序（先到先审），只出运营判定所需字段、不含证件照或身份证明文；驳回原因必填（否则 422 review_note_required），通过走与企业自助同一回写点，保证等级与时间戳口径不分叉。
• 终态与分列留痕：终态记录拒绝再次复核（409 verification_not_pending），改判须重新发起；驳回只回退处于进行中的主体、不降级已通过者；提交 / 确认 / 审核三人分列留痕。实名等级对票种的前置判定落点在发票域（专票需企业 L2、普票需 L1、个人恒不可专票，详见 D08）。

• 触发条件：现金可用为正即 active；可用不大于 0 且宽限未到即 grace（仍服务，属催缴阶段）；宽限已尽或无宽限即 overdue；banned 与 closed 按状态拒绝。宽限天数默认 0（额度尽即停服），开启后自动授限且重授有冷却期（防最小充值循环反复刷宽限）。
• 委托边界：判定顺序为生命周期优先、账务态在后；状态机、状态键发布与准入执行属账户状态与准入域（详见 D06），本域只登记门禁口径与账龄分级，债务判据（只认真实负现金）以 D04 / D06 为准。
• 验证码门禁口径（实现属身份域）：身份维度两档——同身份窗口内失败达 2 次要图形码（否则 400 captcha_required）、达 5 次锁 15 分钟（423 account_locked）；IP 维度两档——达 10 次要图形码、达 30 次按重试等待拒绝；发码前须过滑块一次性票据（开关默认开启）。

• 版本选择：三类协议（用户协议、隐私政策、服务等级协议）共用同一当前版本号，版本号唯一来源是运行配置项；文本随镜像分发，协议更新即替换文本并提升版本号。
• 判定口径：用户资料上的同意版本与当前版本不等即视为需重新确认（未同意与已同意旧版本同一口径），服务端在下单与充值入口兜底拦截 403 terms_not_agreed。
• 留痕属身份域：同意历史与用户资料上的同意版本列由身份域维护；实名场景另有独立同意文本与版本号，随核验行留痕（§4.7）。

5. 接口契约

5.1 门户实名校验链（5 个端点）

• 鉴权为门户登录主体；企业侧写端点要求组织管理员角色，状态查询要求组织成员角色。

5.2 内部运营链（9 个端点）

• 鉴权为内部运营令牌且须持有运营范围；台账行附组织名、规则名与规则类型（展示按类型选择渲染）；处置对象为未软删密钥，其余返回 404 key_not_found。

5.3 运营面（11 个端点）

• 风控段与密钥处置要求风控权限范围，实名复核段要求客户权限范围，两段能力隔离；端点索引与权限载体登记在 D11。

6. 关键约束与验收标准

6.1 约束

1. 台账必有规则来源：命中必须挂在真实规则上；内置规则在被首次需要时惰性创建，创建幂等（同类型平台级规则最多一条）。
2. 扫描幂等：去重窗口内同规则 + 同组织 + 同组不重复落台账、不重复发信；重复与多副本并发扫描不产生重复副作用。
3. 规则参数形态互斥：绝对阈值规则必须有正阈值且不接受环比参数；环比规则的倍数必须为正、两个周期数至少为 1；触发值语义由规则类型决定（tokens / 异常金额分整数 / 话单计数）。
4. 命中动作只落信号：notify_and_downshift 的下调以「台账未解除」为条件，本域只落信号与生效参数，执行面在计费路由。
5. 事件两态且解除幂等：仅在待处置与已处置之间单向流转，重复解除如实返回是否变更。
6. 密钥封禁即可用性归零：置禁用后该密钥不可调用、扣费侧据此拒绝；台账行、展示前缀与历史归因不被改写；软删行不接受处置，处置必留原因。
7. 每人每日实名提交有上限：按自然日计数，成功、比对不符、渠道异常均计入，超限即拒。
8. mock 渠道在非白名单环境 fail-closed：解析 mock 即拒并给出诊断，绝不静默回落真实渠道；真实渠道凭据不全同样拒服务。
9. 实名不落完整证件号：落库只有末四位、完整号不落日志，只做正向核验不做反查；单独同意先于渠道，未同意不落核验行。
10. 企业侧无自助通过通路：无自动定案能力的渠道一律拒绝自助确认，未知渠道按需人工复核处理；终态记录不可再复核，两条定案路径共用同一回写口径。
11. 协议版本不一致即拦：同意版本与当前版本不等即要求重新确认，服务端在下单与充值入口兜底；门禁开关关闭仅限灰度与演示场景。
12. 门禁判定与执行分离：本域只产出口径与事实，门禁执行在各准入点与计费路由；平台侧审核人与企业侧操作人分列留痕。

6.2 验收标准

6.3 待后续设计细化的开放项

1. 规则目录的版本化与灰度：规则改动目前就地下轮生效，缺少生效时点与按组织灰度；变更前后值对照的留痕粒度待定。
2. 触发值列的语义收敛：对账类与免计费类的判据寄居在用量类的整数列上，随台账结构收敛应拆出金额列与计数列，摆脱按规则类型解释的约定。
3. 自动处置动作：notify_and_downshift 之外的自动动作（自动封禁密钥、自动降级准入门槛）尚不可配，需先定「谁有权自动执行」与回滚路径。
4. 真实渠道与账龄催收分级：企业实名（对公打款线下通知与对账、执照类要素核验与工商回执）与个人二要素渠道的凭据投放、轮换周期均待选型定策；企业 L1 与 L2 目前按过渡口径等价，资金权限认证接入后的升降级规则、宽限之外的多级提醒与冻结前置阈值亦待与通知与触达域、账户状态与准入域共同定口径。