开发文档
| 版本号 | 修改 | 修改时间 | 备注 |
|---|---|---|---|
| v1.0.0 | 王小琱 | 2024.12.20 | 初次修订 |
1. 项目简介
- 服务名称：
exchange-statistical-service-backend - 服务描述：本项目为交易所、金融等业务提供多维度统计报表、财务结算、用户资金流水、市场数据归档等自动化统计与导出能力，支持定时任务、S3归档、丰富的报表模板。
- 所属模块：中间层服务。
- 负责人：王小琱（wang746277441@gmail.com）
2. 功能描述
- 自动统计并归档日结单、月结单、财务报表、手续费报表等
- 支持用户资金流水、成交明细、持仓快照等多维度数据统计
- 支持市场数据归档（如订单簿、成交占比、价差等）
- 支持定时任务自动调度，失败任务自动重试
- 报表自动上传 S3，支持多种模板导出（Excel、PDF、HTML）
- 提供 gRPC 接口，便于与其他微服务集成
- 支持eventus、solidus等交易所数据统计
- 支持用户资金、交易、持仓等数据统计
3. 系统架构
3.1 主要技术栈
- 编程语言：[Go / Protocol Buffers v3]
- 服务框架：[Go Micro / GORM]
- 数据库：[MySQL]
- API接口：[gRPC]
- 对象存储：兼容 AWS S3
- 监控：[Prometheus]
- 容器编排：[Docker]
- 报表/文档：Excelize、wkhtmltopdf、PDFCPU
备注：具体依赖版本详见go.mod文件。
3.2 架构图
3.3 架构概括
接口层（Handler）
负责 gRPC/HTTP 接口实现，参数校验、调用业务逻辑、返回响应。主要代码在handler/目录。业务逻辑层（Internal）
负责核心统计、报表、归档、任务调度等业务实现。主要代码在internal/service/、internal/cron/、internal/repository/等目录。数据访问层（Data/Repository）
负责与数据库、缓存、S3等外部系统的数据交互。主要代码在internal/repository/entity/、data/、views/等目录。协议定义层（Protos）
负责 gRPC 协议定义与自动生成代码。主要代码在protos/目录。测试层（Test）
单元测试、集成测试，位于test/及各业务目录下。
3.4 业务流程
3.4.1 财务报表统计/日(月)结单统计
3.4.2 Eventus/Solidus数据统计
3.4.3 失败任务重试流程
4. 依赖组件
| 组件 | 版本 | 说明 |
|---|---|---|
| MySQL | 8.x | 关系型数据库 |
| Redis | 6.x+ | 缓存 |
| S3 | - | 对象存储 |
| Prometheus | - | 监控 |
| Docker | 20+ | 容器化部署 |
5. 接口设计
详见 [protos/proto/statistical.proto] 及自动生成的 gRPC 文档。
使用
make doc可以重新生成借口文档。
6. 数据库设计
详见数据库设计文档，涵盖所有统计、报表、任务、归档等相关表结构。
7. 项目部署
详见 [docs/deploy.md]，支持本地、Docker、K8s 等多种部署方式。
8. 错误码定义
| 错误码 | 错误信息 | 说明 |
|---|---|---|
| ErrParam | 参数错误 | 请求参数错误 |
| ErrSystem | 内部错误 | 内部服务调用失败 |
| ErrKYCNotFound | KYC认证失败 | 用户KYC认证失败 |
| ErrReportDate | 报表日期错误 | 报表日期格式错误 |
| ErrFailed | 操作失败 | 操作失败 |
9. FAQ
1. 如何新增统计报表类型？
- 在
internal/service/新增对应统计逻辑，并在internal/cron/cron.go注册定时任务。
2. 报表归档失败如何处理？
- 失败任务会自动写入
tasks表，定时重试，最大重试次数可配置。
3. 如何自定义报表模板？
- 在
data/template/或views/目录下新增模板文件，并在业务逻辑中引用。
4. S3 归档如何配置？
- 通过环境变量或配置文件设置 S3 区域、Bucket、AccessKey 等参数。
5. 如何扩展 gRPC 接口？
- 修改
protos/proto/statistical.proto，重新生成代码并在handler/实现。