开发文档
| 版本号 | 修改 | 修改时间 | 备注 |
|---|---|---|---|
| v1.0.0 | 王小琱 | 2024.12.20 | 初次修订 |
1. 项目简介
- 服务名称：
exchange-risk-service-backend - 服务描述：本项目为交易所、金融等业务提供KYC、风控、合规、反洗钱等能力，支持多种KYC流程、风控规则、专业投资者认证、企业及个人信息管理等功能。
- 所属模块：风控与合规服务组件。
- 负责人：王小琱（wang746277441@gmail.com）
2. 功能描述
- 用户KYC认证（个人/企业）
- 风控事件与规则管理
- 专业投资者认证
- 反洗钱（AML）信息管理
- 风控审核流程与记录
- 附件、声明、协议签名等合规材料管理
- 支持多角色（用户、审核员、管理员）操作
- 支持多种风控、合规业务场景的快速接入
3. 系统架构
3.1 主要技术栈
- 编程语言：[Go / Protocol Buffers v3]
- 服务框架：[Go Micro / GORM]
- 数据库：[MySQL]
- API接口：[gRPC]
- 监控：[Prometheus]
- 容器编排：[Docker]
- 消息队列：[RabbitMQ]
- 工作流引擎：[Camunda]
- 数据库：[MySQL]
- 缓存：[Redis]
备注：具体依赖版本详见go.mod文件。
3.2 架构图
3.3.1 Risk Task 架构图
3.2.2 Risk提供服务架构图
3.3 架构概括
业务层（Business Layer）
包含 Risk Service 和 Risk Task Service：
- Risk Service：主要提供KYC认证与审核管理，并提供接口供业务系统和后台管理系统调用。
- Risk Task Service：监听 Camunda 流程引擎，处理来自流程的风控查询任务，请求外部服务并返回结果，支持失败任务持久化和定时重试机制。
基础服务层（Infrastructure Layer）
包含以下基础能力服务：
- Camunda：流程引擎，负责驱动风控任务流的执行。
- MySQL：用于存储风控结果、查询任务记录、失败任务等持久化数据。
- 外部服务（EllipticBridge、Notabene 等）：提供 KYA/KYT/Travel Rule 数据查询能力。
3.4 业务流程
3.4.1 查询KYA/KYT/Travel Rule流程
3.4.2 KYC创建以及审核流程
4. 依赖组件
| 组件 | 版本 | 说明 |
|---|---|---|
| MySQL | 8.x | 关系型数据库 |
| Camunda | - | 流程引擎 |
| EllipticBridge | - | 外部服务 |
| Notabene | - | 外部服务 |
| User | - | 外部服务 |
| BankBridge | - | 外部服务 |
| LedgerManager | - | 外部服务 |
| Notify | - | 外部服务 |
| RabbitMQ | - | 消息队列 |
| Redis | - | 缓存 |
5. 接口设计
见接口文档
使用
make doc可以重新生成接口文档。
6. 数据库设计
7. 项目部署
见部署文档
8. 错误码定义
| 错误码 | 错误信息 | 说明 |
|---|---|---|
| ErrSystem | 系统错误 | 数据库、内部服务、未知异常 |
| ErrParam | 参数错误 | 请求参数校验失败 |
| ErrKYCNotFound | KYC不存在 | 未找到对应KYC信息 |
| ErrKYCState | KYC状态异常 | 当前KYC状态不允许此操作 |
| ErrKycNotCompleted | KYC未完成 | KYC流程未完成，无法进行后续操作 |
| ErrKYCAuditRole | 审核角色错误 | 审核人角色与流程要求不符 |
| ErrProfessionalState | 专业投资者状态异常 | 专业投资者信息不存在或状态异常 |
| ErrCompanyInfoState | 企业信息状态异常 | 企业信息未完善 |
| ErrConnectPartyState | 关联方信息状态异常 | 关联方信息未完善 |
| ErrSignatureNotFound | 签名信息不存在 | 未找到签名信息 |
| ErrSignatureNotMatch | 签名与实名不匹配 | 签名与实名信息不一致 |
| ErrPersonalInfoNotFound | 个人信息不存在 | 未找到个人信息 |
| ErrAddressInfoNotFound | 地址信息不存在 | 未找到地址信息 |
| ErrCompanyInfoNotFound | 公司信息不存在 | 未找到公司信息 |
| ErrConnectedPartyInfoNotFound | 关联方信息不存在 | 未找到关联方信息 |
| ErrQAData | 问卷数据异常 | 投资问卷等相关数据异常 |
| ErrQADataNotFound | 问卷数据不存在 | 未找到投资问卷数据 |
| ErrCallWorldCheck | 外部合规服务调用失败 | WorldCheck等外部服务异常 |
| ErrTravelRuleMessage | TravelRule消息类型错误 | TravelRule回调消息类型不符 |
| ErrTravelRuleState | TravelRule状态错误 | TravelRule回调状态不符 |
| ErrFileUpload | 文件上传失败 | 附件上传或处理失败 |
| ErrDuplicate | 数据重复 | 唯一性约束冲突 |
| ErrTimeout | 超时 | 操作超时 |
| ErrUnmarshal | 数据解析失败 | JSON/结构体解析失败 |
| ErrExternalService | 外部服务错误 | 第三方服务调用失败 |
9. FAQ
1. 如何提交个人或企业KYC？
通过 /api/kyc/submit 或相关接口提交个人/企业KYC资料，需按要求填写所有必填信息并上传相关附件。
2. KYC审核流程是怎样的？
用户提交KYC后，系统会根据配置流转到相应审核员或管理员进行审核。审核员可通过管理端接口（如 /admin/kyc/audit）进行审核操作，审核结果会同步更新KYC状态。
3. 为什么KYC审核被拒绝？
常见原因包括：资料不全、信息不一致、风控规则不通过、合规材料缺失等。可通过接口返回的错误信息或联系管理员获取详细原因。
4. 如何查询KYC或风控审核进度？
可通过 /api/kyc/status、/admin/kyc/list 等接口查询KYC状态和审核记录。
5. 专业投资者认证如何提交和审核？
用户可通过相关接口提交专业投资者材料，管理员通过 /admin/professional_investor/audit 等接口进行审核，审核通过后状态会更新。
6. 附件、声明等合规材料如何上传？
通过 /api/files/upload 或相关接口上传，需确保文件格式和大小符合要求。
7. 系统返回“状态异常”或“权限不足”怎么办？
请检查当前操作用户的角色和KYC/风控流程状态，部分操作仅限特定角色或特定状态下进行。
8. 如何处理“系统错误”或“数据库错误”？
请重试操作，如多次失败请联系技术支持或管理员，查看日志定位具体原因。
9. 如何扩展风控规则或KYC流程？
可在 /internal/repository/entity 和 service 层新增规则定义和处理逻辑，handler 层暴露管理接口。
10. 外部服务（如WorldCheck、TravelRule）调用失败怎么办？
请检查外部服务配置、网络连通性和密钥有效性，查看接口返回的详细错误信息。
11. 如何添加/修改数据库表结构？
修改 /internal/repository/entity 下对应 go 文件，并同步更新数据库结构，详见数据库设计文档。
如有其他问题，请联系项目负责人或查阅详细开发文档。