系统功能需求文档生成器

功能概述

• 功能名称和标识符
  • 名称：物联网设备接入与远程固件升级（OTA）
  • 标识符：FRD-IOT-OTA-001
• 业务背景和价值陈述
  • 背景：在物联网场景下，设备规模化部署后需要安全、可控地进行设备接入和远程固件升级，以修复缺陷、发布新功能和满足合规要求。
  • 价值：提供标准化的设备注册与认证、安全可信的OTA版本管理、可控的灰度发布与回滚、面向多租户的权限治理与审计，降低运维成本，提升升级成功率与业务连续性。
• 功能范围和边界定义
  • 范围内
    • 设备通过 MQTT/HTTP 完成注册与认证
    • 支持 X.509 证书与设备密钥认证
    • 设备型号/批次录入，支持按产品、分组、地域管理
    • OTA 版本管理、灰度发布（百分比与白名单）
    • 断点续传与失败回滚
    • 升级任务策略（窗口期、并发阈值、低电量/弱网保护）
    • 进度与状态码上报、异常自动告警
    • 多租户隔离与角色权限控制
    • 对接消息总线、设备影子（Device Shadow）
    • 升级报表、审计日志、API 钩子（Webhook）
  • 范围外
    • 设备端固件实现细节与适配
    • 固件构建、签名工具链的实现
    • 第三方运维平台的可视化图表实现（仅提供数据接口/报表导出）
    • 硬件电源与网络模块物理层能力保证

用户角色

• 涉及的用户角色列表
  • 租户管理员：管理租户内产品、分组、地域、角色与权限策略；审批发布
  • 运维工程师：创建与执行升级任务，监控进度与告警，处理异常
  • 固件发布者：上传及管理固件版本、配置灰度策略
  • 审计员：查看审计日志与合规报表
  • 观察者（只读）：查看设备与任务信息
  • 集成应用（API 客户端）：通过 API/钩子集成第三方系统
  • 设备（系统实体）：注册、认证、接收升级、上报进度
• 各角色的权限和职责
  • 租户管理员：全部读写；租户级隔离策略配置；审批发布；删除/封禁设备
  • 运维工程师：升级任务的创建/修改/启动/暂停/终止；查看设备与任务指标
  • 固件发布者：固件上传、版本属性编辑、灰度策略配置（需管理员审批可选）
  • 审计员：只读访问审计日志、下载合规报表
  • 观察者：只读访问设备清单、任务与版本列表
  • 集成应用：按授予的 API 范围访问（读取事件、回调处理）
  • 设备：仅访问与自身相关的注册/认证/影子/升级接口

前置条件

• 系统环境要求
  • 提供可访问的 MQTT Broker 与 HTTP 接入端点（支持 TLS）
  • 支持 PKI 体系（租户级根/中间证书导入或平台签发），安全存储证书/密钥
  • 可用的对象存储/内容分发能力，用于固件包分发（支持分块/范围请求）
• 依赖功能和数据
  • 设备注册表（Device Registry）：设备标识、认证方式、模型、批次、固件版本
  • 消息总线：用于升级事件发布与系统内部异步处理
  • 设备影子：维护 desired/reported 的固件版本、升级状态
  • 告警与通知通道：邮件/短信/IM/Webhook（至少一种）
• 用户权限要求
  • 具备相应角色授权且通过租户认证后方可执行配置与运维操作
  • API 调用需要有效的访问令牌/签名；设备侧需要有效证书或设备密钥

功能需求详情

• 设备接入与注册
  • 描述：设备通过 MQTT 或 HTTP 方式注册并接入平台，完成身份标识与元数据录入。
  • 输入
    • 注册请求字段（示例，具体字段必须可配置为必填/选填）：deviceId、productId、model、batch、firmwareVersion、region、capabilities、nonce、signature 或证书链
  • 输出
    • 注册结果：success/failed、失败原因码、设备影子初始状态、后续接入参数（如主题/URI 模式）
  • 业务规则
    • deviceId 在租户+productId 维度内唯一
    • 若使用 X.509，验证证书链有效性与吊销状态；若使用设备密钥，验证签名与时效
    • 注册时记录设备当前 firmwareVersion、batteryLevel（若可上报）、networkQuality（若可上报）
• 安全认证
  • 支持方式：X.509 双向认证、设备密钥（对称/基于签名）二选一或双支持
  • 规则：同一设备可在租户授权下轮换凭证；密钥/证书过期前支持预置新证书并平滑切换
• 设备元数据管理
  • 维度：产品、分组、地域、型号、批次
  • 操作：创建/编辑/归档；设备可多维归属（如同一设备属于一个产品、一个地域、可加入多个逻辑分组）
  • 约束：跨租户不可见；跨产品不可移动（需管理员审批迁移）
• OTA 版本管理
  • 功能：上传固件、设置版本号、依赖/兼容范围、签名/校验和、发布说明
  • 输入：version、artifactURI、checksum（SHA-256/等至少一种）、signature（如启用）、minVersion/maxVersion、targetModel/batch、releaseNotes
  • 输出：版本唯一标识、可见范围（产品/租户）、状态（草稿/待审批/发布/下架）
  • 规则：同产品下版本号唯一；上传后生成不可变校验信息；可配置是否需要审批后方可发布
• 灰度发布（百分比/白名单）
  • 百分比：按选定目标集（产品/分组/地域/型号/批次的组合过滤）随机/稳定哈希选择 X% 设备。需保证同一设备在同一任务内选择结果稳定
  • 白名单：显式 deviceId 列表，优先级高于百分比
  • 规则：同一设备若在白名单则不参与百分比抽样；可分阶段提升比例；每次比例调整生成变更记录
• 断点续传与失败回滚
  • 断点续传：服务端支持范围请求/分块下载；设备上报已完成偏移；平台应返回合适的续传指引（分块索引或字节范围）
  • 校验：下载完成后进行校验和校验；不一致则标记为下载失败，可重试
  • 失败回滚：固件应用失败或校验失败达到重试上限时，设备回滚至上一个可用版本；平台同步影子状态为 rolled_back，并记录失败原因
• 升级任务编排
  • 窗口期：配置任务生效的日期/时间段（支持时区字段）；非窗口期不下发
  • 并发阈值：限制同时处于“下载/安装”状态的设备数量或速率；平台调度需严格遵循阈值
  • 低电量/弱网保护：当设备上报电量低于阈值或网络质量低于阈值时，任务自动延后并重试；阈值由任务参数定义
  • 可操作：创建、预览命中设备数、模拟抽样、启动、暂停、恢复、终止
• 实时上报进度与状态码
  • 状态码最小集合（必须支持以下状态与原因码结构）
    • QUEUED、DOWNLOADING、DOWNLOADED、VERIFYING、APPLYING、REBOOTING、SUCCEEDED、FAILED、ROLLED_BACK、SKIPPED（如低电量/弱网）
  • 失败原因建议分类（作为扩展字段）：NETWORK_ERROR、LOW_BATTERY、CHECKSUM_MISMATCH、SIGNATURE_INVALID、INSTALL_ERROR、TIMEOUT、CONCURRENCY_LIMITED、OUT_OF_WINDOW
  • 上报内容：deviceId、taskId、state、progress[0-100]、timestamp、reason(optional)、batteryLevel(optional)、networkQuality(optional)
  • 规则：设备状态变化必须幂等；重复上报以最后一次 timestamp 为准
• 异常自动告警
  • 触发条件：失败率超过阈值、单设备连续失败 N 次、签名校验失败、版本不兼容、任务调度受阻（并发/窗口）
  • 通知：通过配置的通知通道发送；包含故障摘要、影响范围、建议处理
• 多租户隔离与角色权限
  • 数据与任务按租户隔离；跨租户访问禁止
  • RBAC：基于角色+资源范围（产品/分组/地域）授权；审计全量记录权限变更
• 集成能力
  • 消息总线：发布 OTA 相关事件（version.published、task.started、device.progress、task.completed、task.failed 等）至总线；事件载荷包含租户、产品、任务、设备、状态
  • 设备影子：将 desired.firmwareVersion 设置为目标版本；设备上报 reported.firmwareVersion 与升级状态；平台依据影子差异触发/停止下发
  • API 钩子（Webhook）
    • 触发事件：任务创建/启动/暂停/完成、设备进度变化、异常告警
    • 安全：请求签名（时间戳+签名头+重放保护）；失败重试与退避策略
• 升级报表与审计日志
  • 报表：按任务/产品/分组/地域统计命中设备数、成功/失败/跳过数量、阶段时长、失败原因分布；支持导出（CSV/JSON 至少一种）
  • 审计日志：记录时间、用户/应用、操作类型、目标对象、变更前后摘要、结果；不可篡改（追加写），可按时间与对象过滤

输入输出数据规格

• 设备注册（HTTP 示例）
  • 请求：POST /devices/register
    • Headers：Authorization/Certificate、Content-Type
    • Body：{ deviceId, productId, model, batch, firmwareVersion, region, nonce, signature? }
  • 响应：{ result: "success|failed", reason?, assignedTopics?, shadow? }
• 进度上报（MQTT 示例）
  • 主题：/tenant/{tenantId}/product/{productId}/device/{deviceId}/ota/progress
  • 载荷：{ taskId, state, progress, timestamp, reason?, batteryLevel?, networkQuality? }
• 版本元数据
  • 结构：{ version, artifactURI, checksum, signature?, compatible: { model?, batch?, minVersion?, maxVersion? }, releaseNotes, visibility }
• 升级任务
  • 结构：{ taskId, targetFilter, strategy: { percentage?, whitelist?, window?, concurrency?, thresholds: { battery?, network? } }, version, retryPolicy, status }

业务规则和约束条件

• 同一 deviceId 在同一时刻仅参与一个处于 APPLYING 阶段的任务
• 固件包需通过校验和验证；若启用签名，需通过签名验证才可进入 APPLYING
• 任务调度需严格遵守窗口期与并发阈值；超出阈值的设备进入 QUEUED
• 设备影子为最终一致性数据源；desired 与 reported 一致时视为升级完成
• 灰度百分比选择需稳定且可复现（基于 deviceId 的一致性哈希或等价机制）
• 回滚仅回滚到最近的成功版本（若记录存在）；无成功版本记录时标记为 FAILED 且不执行回滚

业务流程

• 正常流程步骤（设备侧 + 平台侧）
  1. 设备注册与认证：设备通过 MQTT/HTTP 提交注册请求 -> 平台校验身份并写入注册表 -> 初始化影子
  2. 版本发布：固件发布者上传版本 -> 校验并保存 -> 管理员审批（可选）-> 版本状态“发布”
  3. 创建任务：运维工程师配置目标过滤与灰度策略、窗口期、并发阈值与保护阈值 -> 预估命中设备数 -> 启动任务
  4. 调度与通知：平台根据窗口与并发阈值，将目标设备置为 desired.firmwareVersion=目标版本；事件发布至消息总线
  5. 设备执行：设备检测影子差异 -> 拉取下载 URL -> 分块下载 -> 校验通过 -> 应用固件 -> 重启 -> 上报进度与状态
  6. 完成与对账：设备上报 reported.firmwareVersion=目标版本、state=SUCCEEDED -> 平台统计成功并关闭该设备的任务上下文
• 异常处理流程
  • 认证失败：返回错误码（证书无效/签名失败）；设备拒绝接入；审计与告警记录
  • 超出窗口期：平台不下发，设备进入 SKIPPED 或 QUEUED，等待下个窗口
  • 并发受限：设备进入 QUEUED；平台在有配额时再下发
  • 低电量/弱网：设备或平台判定不满足阈值 -> 延迟执行并记录 SKIPPED（原因携带 LOW_BATTERY/WEAK_NETWORK）
  • 校验失败：标记 FAILED（CHECKSUM_MISMATCH）；达到重试上限触发 ROLLED_BACK
  • 安装失败：标记 FAILED（INSTALL_ERROR）；按策略回滚并上报 ROLLED_BACK
  • 影子不同步：若长时间无 reported 变化 -> 触发 TIMEOUT 告警，任务继续等待或按策略终止
• 业务规则说明
  • 重试策略可配置最大次数与间隔；达到上限后不再推送
  • 任务可暂停；暂停期间不新发下发指令；已在设备侧执行的不被撤销

验收标准

• 功能验证场景
  • 注册与认证：使用有效与无效证书/签名分别测试，验证注册成功与失败原因码
  • 版本管理：上传固件并验证校验和检查生效；审批后版本状态变更正确
  • 灰度百分比：设定百分比与白名单，验证白名单设备必定入选且百分比稳定
  • 断点续传：模拟网络中断后续传成功，最终校验通过
  • 失败回滚：模拟安装失败，设备回滚至先前成功版本，影子状态为 ROLLED_BACK
  • 并发阈值与窗口期：设置阈值与有效窗口，验证同时活跃设备不超过阈值，窗口外不下发
  • 低电量/弱网保护：设备上报低电量/弱网值时，任务被延后或标记 SKIPPED 并记录原因
  • 进度与状态码：设备按状态流转上报，平台正确聚合并在任务页展示
  • 告警：失败率超过阈值时触发通知，告警内容包含任务与原因摘要
  • 设备影子联动：desired 设置后设备执行并最终 reported 一致，任务自动完成
  • Webhook：任务开始/完成事件按约定签名推送，接收方校验签名通过；失败重试生效
  • 审计日志：对关键操作（版本发布、任务启动、阈值变更）生成不可篡改的审计记录
• 性能指标要求（参数化验收）
  • 在验收环境确定参数：最大同时受控设备数、任务下发速率阈值、进度事件处理延迟阈值；平台在这些参数下应满足并发控制与事件处理的正确性
  • 平台应保证在设定的并发阈值下，不出现超发；进度事件在可配置的处理时限内被持久化并可查询
• 用户体验标准
  • 任务配置界面应提供命中设备数预估与抽样预览
  • 失败原因可视化分类展示；支持按设备/分组/地域过滤
  • 提供任务级与设备级时间线，状态变化有时间戳和操作者/系统来源

非功能需求

• 性能要求
  • 支持大规模设备的任务分批调度；并发阈值、窗口期与重试策略均可配置
  • 进度上报与告警事件处理具备可扩展的异步架构（通过消息总线解耦）
• 安全性要求
  • 传输层必须启用 TLS；支持 X.509 证书或设备密钥认证
  • 固件至少支持校验和验证；如启用签名需验证签名有效
  • 多租户强隔离；RBAC 最小权限原则；审计日志追加写不可篡改
  • Webhook/API 需请求签名与重放攻击防护
• 兼容性要求
  • 接入协议支持 MQTT 与 HTTP
  • 与设备影子与消息总线对接遵循统一事件与状态模型
  • 报表导出至少支持 CSV 与 JSON

备注

• 所有阈值（如电量、弱网、失败率、并发）与重试策略参数由实施阶段在环境与业务评估后设定为可配置参数；本需求要求功能完备与参数化能力，不定义具体数值默认值。
• 本需求文档不包含设备端固件实现细节与第三方具体产品选型。

功能概述

• 功能名称和标识符
  • 移动端开户KYC与黑名单校验（ID: KYC-AML-ONB-MOB-01）
• 业务背景和价值陈述
  • 面向金融业务移动应用的新客开户环节，完成身份识别（KYC）与制裁/风险名单筛查，降低欺诈与洗钱风险，满足监管合规（KYC/AML）要求，提升自动化通过率并保留可追溯审计证据。
• 功能范围和边界定义
  • 范围内：
    • 身份证件OCR采集与结构化
    • 活体检测与人脸与证件照人证比对
    • 四要素采集与权威库/风险名单/设备指纹交叉校验
    • 地址标准化处理
    • 反洗钱可疑名单对接与筛查（实时+复筛）
    • 自动化判定与人工复核流程、差错纠正与重试
    • 异常分级处置与用户申诉
    • 加密存储、脱敏展示、访问审计
    • 稽核报表生成与审计追溯
  • 范围外：
    • 账户产品签约与资质审批（除KYC/AML相关）
    • 资金划转、风控评分模型训练
    • 非移动端渠道（如网点/PC端）实现

用户角色

• 涉及的用户角色列表
  • 用户（新开户客户）
  • 审核员（运营/客服一线审核）
  • 风控（二线风险复核/策略配置/名单管理）
• 各角色的权限和职责
  • 用户：提交证件影像/视频，确认四要素与地址，查看进度，查看与发起申诉，进行差错纠正与重试
  • 审核员：查看待审核工单（脱敏），补充/纠正结构化字段，做出通过/拒绝/升级决策，记录原因，发起补件
  • 风控：配置策略与阈值，管理黑/灰名单来源与更新频率，处理高风险工单，审批白名单/豁免，查看与导出稽核报表，访问审计日志（只读）

前置条件

• 系统环境要求
  • 移动端：iOS/Android原生或混合应用，摄像头/麦克风/存储权限已授权
  • 网络：可访问OCR/活体/人脸/权威库/名单/地址标准化/设备指纹等对接服务
• 依赖功能和数据
  • 手机号验证（短信或运营商一致性校验完成）
  • 隐私与数据处理授权（明确目的、范围、留存、撤回方式）已记录
  • 第三方/内部服务可用：OCR、活体、人脸比对、权威库、AML名单、设备指纹、地址标准化、审计与报表
• 用户权限要求
  • 用户端完成必要系统权限授权；审核员/风控具备系统分配的最小化访问权限

功能需求详情

• 功能特性详细描述

  1. 证件OCR采集
     • 支持证件类型：按当地监管与产品定义（最少支持居民身份证/护照其一），可配置
     • 引导拍摄与防反光/防遮挡/边框对齐提示；质量校验未通过则阻止提交
     • 结构化字段提取：姓名、证件号码、性别/出生日期、有效期、签发机关、住址（若有）
  2. 活体检测与人证比对
     • 活体检测：支持静默/动作/3D活体任一方案，可配置；返回置信度
     • 人脸比对：用户自拍与证件头像比对，输出相似度分数
  3. 四要素采集与交叉校验
     • 四要素字段集（可配置，默认）：真实姓名、政府签发证件号码、预留手机号、支付/账户标识（如银行卡号）
     • 校验来源：权威库（身份/实名一致性）、风险名单（黑/灰/内部）、设备指纹画像与历史关联
  4. 地址标准化
     • 将OCR/用户输入的地址解析为标准层级（国家/省/市/区/街道/门牌），输出标准化与可核验标识
  5. AML可疑/制裁名单筛查
     • 对接外部/内部名单源，进行姓名+证件号+别名模糊匹配；维护匹配分数与命中明细
     • 支持开户后周期性复筛（频率可配置）
  6. 决策与复核
     • 规则引擎：阈值与规则组合生成“通过/待人工/拒绝”决策
     • 人工复核：审核员查看工单（脱敏），可发起补件、修改结构化字段（保留痕迹）、升级风控复核
  7. 差错纠正与重试
     • 用户可对OCR错误字段进行更正；支持重拍证件/重做活体/重传四要素；重试次数与冷却时间可配
  8. 异常分级处置与申诉
     • 异常分级：阻断类（Critical）、高风险（High）、可疑（Medium）、提醒（Low），自动触发相应流程
     • 申诉：用户提交材料与说明，进入单独工作流，由审核员或风控处理
  9. 加密存储、脱敏展示、访问审计
     • 敏感数据加密存储；界面按角色脱敏显示；所有访问与操作留痕、可追溯、可审计
  10. 稽核报表
  • 报表包含：流程轨迹、决策依据、版本/阈值、访问日志摘要、名单命中明细、人工操作痕迹；支持导出与留存

• 输入输出数据规格

  • 输入（移动端上传）
    • 证件影像：JPEG/PNG，单张≤3MB，分辨率≥1080p，包含正反面（若适用）
    • 活体素材：视频MP4或多帧图片，时长≤10s，大小≤15MB
    • 四要素：UTF-8文本，格式校验（号码校验位、手机号格式、卡号Luhn）
    • 地址：自由文本，最长256字符
    • 用户同意记录：时间戳、版本、关键条款ID、设备指纹ID
  • 输出（服务侧）
    • OCR结构化结果及置信度
    • 活体检测结果：通过/拒绝/不确定 + 置信度
    • 人证比对相似度分数
    • 四要素一致性校验结果与来源
    • 设备指纹风险评分与命中标签
    • AML/黑名单命中列表、匹配分数、来源、更新时间
    • 决策结论、规则ID、阈值版本、原因码
    • 审计ID（全流程关联）、时间线

• 业务规则和约束条件

  • 质量门槛（可配置）
    • OCR有效：关键字段置信度≥T_OCR，否则提示重拍
    • 活体通过：置信度≥T_LIVE；低于T_RETRY触发重试，高风险直接拒绝
    • 人证比对：相似度≥T_FACE_PASS通过；[T_FACE_REVIEW, T_FACE_PASS)进入人工
  • 四要素一致性：任一关键要素与权威库不一致→人工或拒绝（依据规则）
  • 黑/灰名单命中：制裁/禁止类→直接拒绝；可疑/观察类→人工复核
  • 设备指纹：
    • 与高风险设备/代理/越狱/多账户关联→升级人工或拒绝
    • 同设备多次失败超阈值→冷却并限制重试
  • 地址标准化失败：需用户确认或补充；仍失败则人工复核
  • 重试限制：每环节最多N次（默认3），冷却期M分钟（默认10）
  • 数据最小化：仅收集完成KYC/AML所必需数据
  • 留存与复筛：满足适用监管留存期（可配置，默认5年）；开户后按配置频率复筛

业务流程

• 正常流程步骤
  1. 前置校验：手机号验证与隐私授权完成
  2. 证件拍摄与OCR → 字段结构化与质量校验
  3. 活体检测 → 人证比对得分
  4. 用户确认/补充四要素与地址 → 地址标准化
  5. 交叉校验：权威库、设备指纹、黑/灰/AML名单
  6. 决策引擎出结论（通过/待人工/拒绝）
  7. 通过：开户完成；复筛计划入库；生成审计记录与报表条目
• 异常处理流程
  • 影像质量不足：提示重拍（计入重试）
  • 活体/人证边界分数：允许重试或流转人工（遵循阈值与次数）
  • 权威库/外部服务超时：重试K次（指数退避），仍失败→人工
  • 名单命中：按分级处置（直接拒绝或人工）
  • 设备指纹异常：限制重试/人工复核/冻结一段时间
  • 申诉：用户提交材料→审核员处理→必要时风控复核→结案
• 业务规则说明
  • 所有自动化决策必须记录：规则ID、参数、模型版本、输入摘要哈希
  • 人工修改任何字段需留痕：修改前后值、原因、工号、时间戳

验收标准

• 功能验证场景
  • OCR：不同光照/角度/证件状况下采集，关键字段抽取准确率≥98%（在标准测试集上）
  • 活体：正常用户通过率（FRR）≤3%；欺骗攻击通过率（FAR）≤0.1%（测试集）
  • 人证比对：在运营点位阈值下，误接受率FAR≤0.1%，误拒率FRR≤3%
  • 四要素：格式校验100%覆盖；与权威库一致性正确判定率≥99.5%
  • 名单筛查：已知命中样本召回率≥99%，误报率≤2%（在验证集）
  • 设备指纹：同设备多账户/多失败场景正确识别率≥95%
  • 决策流：自动通过率达到策略设定目标（例如≥70%），与人工复核闭环正确率≥99%
  • 申诉：提交流程、材料补交、结论回执全链路通过
  • 审计与报表：可生成、可检索、字段完备、链路一致
• 性能指标要求
  • 端到端P95时延（从提交到决策）：≤6秒（在并发≤100 TPS、外部服务SLA正常条件）
  • 单环节P95：OCR≤1.5s，活体/人脸≤2.5s，名单与权威库聚合≤1.5s
  • 可用性：≥99.9%（月度），降级策略生效且可观测
• 用户体验标准
  • 引导与错误提示清晰，不得出现技术性术语未解释
  • 重试与冷却反馈明确，展示剩余次数
  • 脱敏显示符合规范：证件号/卡号/手机号仅显示末4位

非功能需求

• 性能要求
  • 异步聚合与并发请求；外部接口超时与重试策略可配置
  • 缓存名单与权威数据的非敏感元信息以降低时延（遵守有效期）
• 安全性要求
  • 传输与存储加密：TLS 1.2+；静态加密使用行业标准算法与密钥长度（如AES-256）
  • 密钥与凭据管理：集中化KMS，分级权限与轮换；密钥不落盘明文
  • 数据最小化与脱敏：界面与导出默认脱敏；敏感操作二次确认
  • 访问审计：所有读取/下载/导出均记录；日志具备防篡改能力（如哈希链或WORM）
  • 权限控制：RBAC最小权限；双人复核用于高敏操作（如白名单豁免）
  • 反自动化：设备指纹结合行为特征，限制批量/脚本化攻击
• 兼容性要求
  • 移动端兼容：iOS 13+/Android 8+；弱网与间断网络可恢复
  • 第三方服务可插拔：OCR/活体/人脸/名单/地址可替换并保持统一接口规范
  • 国际化：字符集UTF-8，支持多语言证件（按业务启用）

————————

以下为更细化的要素以支撑实施与测试：

• 接口与数据字典（概要）
  • /kyc/ocr/upload：入参file(image)，出参fields{name,idNo,expiry,address,...},confidences
  • /kyc/liveness/verify：入参video|frames，出参live:boolean,score
  • /kyc/face/match：入参faceSelfie,faceDoc，出参similarity
  • /kyc/fourelements/verify：入参name,idNo,phone,accountId，出参matchResults{source,result,detail}
  • /kyc/device/evaluate：入参deviceFingerprint，出参riskScore,tags
  • /kyc/aml/screen：入参name,idNo,aliases，出参hits{list,score,source}
  • /kyc/address/normalize：入参rawAddress，出参std{country,prov,city,district,street,no},verified:boolean
  • /kyc/decision/evaluate：入参上述聚合结果，出参decision{pass|review|reject},reasonCodes,ruleId,version
  • /kyc/audit/report：入参filters，出参report文件/数据集
• 决策与异常分级（示例，可配置）
  • Critical：制裁名单命中、伪造证件高置信、活体明显失败、冒用高置信→拒绝
  • High：黑名单命中、设备高风险、四要素强不一致→人工/拒绝
  • Medium：边界分数、地址异常、服务不稳定→人工
  • Low：轻微格式问题→提示纠正或人工
• 重试与冷却
  • OCR/拍摄：≤3次；活体：≤3次；四要素提交：≤2次；默认冷却10分钟（均可配置）
• 稽核报表字段最小集
  • 审计ID、用户ID（脱敏）、时间线、设备指纹ID、证件类型与掩码、各环节分数/阈值/版本、名单命中、决策与原因码、人工操作痕迹、导出人/时间
• 合规与留存
  • 留存期与复筛频率按适用监管要求配置；提供数据删除/匿名化与用户撤回处理闭环（保留法律留存的最小必要副本）
• 监控与告警
  • 指标：成功率、各环节P95/P99、外部依赖SLA、命中率、人工转介率、误报/漏报样本
  • 告警：外部接口失败率/时延阈值、模型/规则版本漂移、命中分布异常

本需求文档遵循可执行、可测试原则；具体阈值、名单源、证件类型与留存周期需在项目实施前由合规/风控/产品联合确认并参数化落地。