开发文档
| 版本号 | 修改 | 修改时间 | 备注 |
|---|---|---|---|
| v1.0.0 | 王小琱 | 2024.12.20 | 初次修订 |
| v1.0.1 | 王小琱 | 2025.5.20 | 完善细节 |
1. 项目简介
- 服务名称：
exchange-elliptic-bridge-backend - 服务描述：本项目旨在为交易所和金融业务提供合规分析能力，帮助快速完成用户KYA/KYT信息查询和报告获取。
- 所属模块：基础服务组件。
- 负责人：王小琱（wang746277441@gmail.com）
2. 功能描述
- 给定任意用户的钱包地址，查询其 KYA 信息。
- 给定区块链上的交易哈希，查询其 KYT 信息。
- 给定报告ID，查询其 KYA/KYT 详细信息。
3. 系统架构
3.1 主要技术栈
- 编程语言：[Go / Protocol Buffers v3]
- 服务框架：[Go Micro / GORM]
- 数据库：[MySQL]
- API接口：[gRPC]
- 监控：[Prometheus]
- 容器编排：[Docker]
备注：以上技术栈仅为示例，具体版本以项目中的依赖文件为准。详见go.mod文件。
3.2 架构图
3.3 架构概括
业务层（Business Layer）
包含 Risk Service，负责业务风控逻辑，向内部服务提供风控能力。
基础服务层（Infrastructure Layer）
包含 Elliptic Bridge，专注于提供 KYT（Know Your Transaction）/ KYA（Know Your Address）等底层监测和反洗钱服务，供业务层调用。
3.4 业务流程
3.4.1 查询KYA/KYT流程
3.4.2 查询报告流程
4. 依赖组件
| 组件 | 版本 | 说明 |
|---|---|---|
| MySQL | 8.x | 关系型数据库 |
| Elliptic | - | KYT/KYA服务提供商 |
5. 接口设计
见接口文档
使用
make doc可以重新生成接口文档。
6. 数据库设计
7. 项目部署
见部署文档
8. 错误码定义
| 错误码 | 错误信息 | 说明 |
|---|---|---|
| ErrCallElliptic | 请求失败 | 调用Elliptic失败 |
| ErrSystem | 内部错误 | 内部服务调用失败 |
| ErrGetEllipticReport | 获取失败 | 报告内容格式错误 |
9. FAQ
1. reportId和screeningId的区别是什么？
reportId是报告ID，screeningId是筛选ID。reportId是跟着address或TxHash走的，screeningId是跟着查询走的，意思就是相同的address或TxHash，reportId是一样的，但是screeningId是不一样的。
2. riskScore的取值范围是多少？
riskScore的取值范围是0-10，0表示风险最低，10表示风险最高。
3. blockchain值如何选择？
blockchain值可以参考Elliptic API文档的API文档，如果你不确定，可以使用HOLISTIC。
4. 查询返回空数据？
- 确认请求参数（地址、交易哈希、报告ID）正确；
- 如果为 KYA/KYT 报告ID查询，请先确保报告数据已经同步到数据库。
5. 访问 Elliptic API 超时或失败？
- 检查 Elliptic API Key 是否正确配置；
- 检查 Elliptic API URL 是否正确配置；
- 查看服务日志，排查请求参数或超时时间设置。
6. 如何找到接口文档?
- DDL文件中有接口描述，可以参考DDL文件；
10. 参考资料
11. 致谢
感谢 elliptic 提供的 API 服务。