交易所用户属性管理后端服务开发文档

项目概述

项目名称: Exchange User Attribute Backend 技术栈: Go 1.22.2, Gin, GORM, gRPC, MySQL/PostgreSQL 功能: 交易所用户属性管理系统，包括用户等级管理、推荐关系管理等功能

本服务是一个微服务架构的后端系统，主要负责管理交易所用户的各种属性信息，包括用户等级、VIP等级、推荐关系等。

核心功能

1. 用户等级管理

• 用户等级查询和更新
• 等级历史记录追踪
• 基于交易量的等级自动升级
• 支持现货(SPOT)和OTC两种账户类别

2. 用户推荐系统

• 推荐关系建立和查询
• 推荐奖励计算
• 推荐码生成和验证

3. VIP等级系统

• VIP等级配置管理
• VIP权益管理
• 等级有效期管理

项目架构

目录结构

├── consts/           # 常量定义
│   ├── app.go       # 应用常量
│   ├── db.go        # 数据库常量
│   ├── modules.go   # 模块常量
│   └── user.go      # 用户相关常量
├── core/            # 核心应用框架
│   ├── modules/     # 各种模块实现
│   ├── app.go       # 应用主体
│   └── app_init.go  # 应用初始化
├── g/               # 全局变量
├── grpc/            # gRPC服务实现
├── models/          # 数据模型
│   └── dbmodels/    # 数据库模型
├── service/         # 业务逻辑服务
├── types/           # 类型定义
├── utils/           # 工具函数
├── config.toml      # 配置文件
├── private.toml     # 私有配置文件
├── Dockerfile       # Docker构建文件
├── Makefile         # 构建脚本
├── docker-compose.yaml
└── main.go          # 程序入口

模块化设计

应用采用模块化设计，主要模块包括：

func (a *Application) init() error {
	// cacher module
	cacherModule, err := modules.NewCacherModule(a.cfg)
	if err != nil {
		return err
	}
	a.AddModule(cacherModule)

	// database module
	databaseModule, err := modules.NewDatabaseModule(a.cfg)
	if err != nil {
		return err
	}
	a.AddModule(databaseModule)

	// grpc module
	grpcModule := modules.NewGrpcServerModule(a.cfg)
	a.AddModule(grpcModule)

	// cron module
	cronModule, err := modules.NewCronModule(a.cfg)
	if err != nil {
		return err
	}
	a.AddModule(cronModule)

1. Cacher Module: 缓存模块
2. Database Module: 数据库模块
3. gRPC Server Module: gRPC服务模块
4. Cron Module: 定时任务模块
5. HTTP Server Module: HTTP API服务模块
6. gRPC Client Module: gRPC客户端模块

数据模型

用户等级相关模型

// UserLevelHistory 用户等级历史记录表
type UserLevelHistory struct {
	UserID    string `gorm:"size:50;index;not null;comment:用户ID"`
	Category  string `gorm:"size:50;index;not null;comment:账户类别"` // consts.AccountCategorySpot consts.AccountCategoryOTC
	LevelID   int64  `gorm:"comment:用户等级ID"`
	LevelName string `gorm:"size:50;comment:用户等级名称"`

	ExpireTime time.Time `gorm:"comment:过期时间"`
	Operator   string    `gorm:"size:50;comment:操作人"` // consts.UpdateUserLevelOperatorInit consts.UpdateUserLevelOperatorAdmin consts.UpdateUserLevelOperatorInvite consts.UpdateUserLevelOperatorTrade
	Remark     string    `gorm:"type:text;comment:备注"`

// UserLevel 用户当前等级表
type UserLevel struct {
	UserID    string `gorm:"size:50;uniqueIndex:idx_user_category;not null;comment:用户ID"`
	Category  string `gorm:"size:50;uniqueIndex:idx_user_category;not null;comment:账户类别"` // consts.AccountCategorySpot consts.AccountCategoryOTC
	HistoryID uint   `gorm:"index;comment:历史记录ID"`

	gorm.Model
}

常量定义

const (
	RegularUserLevelId   = -1
	RegularUserLevelName = "Regular"
)

const (
	// 除了Regular之外的等级总数
	VipUserLevelCount = 20
)

配置管理

主配置文件 (config.toml)

[common]
# production为true时设置zerolog的output为os.Stderr,否则为ConsoleWriter
is_production = true

[log]
level = "info"

[cacher]
default_expiration = "1h"
cleanup_interval = "10m"

[db_main]
enable = true
log_level = "info"
driver = "mysql"
dsn = ""
read_write_separate = false
replicas = "dsn1||dsn2"
# random,round_robin,strict_round_robin
policy = "random"

[grpc]
enable = true
host = "0.0.0.0"
port = 9000
with_health = true

[cron]
enable = true
scan_kyc_interval = "5m"
scan_vip_interval = "5m"
update_user_level_stmt = "0 8 * * *"

[http_server]
enable = false
host = "0.0.0.0"
port = 8080
enable_swagger = true
enable_cors = true

环境变量覆盖

配置文件中的所有配置项都可以使用环境变量来覆盖，格式为USER_ATTRIBUTE_XX_YY,比如log下的level使用环境变量 USER_ATTRIBUTE_LOG_LEVEL来配置

API 接口

gRPC 服务

项目提供以下gRPC服务接口：

用户等级服务

• 查询用户当前等级: 获取指定用户的当前等级信息
• 更新用户等级: 更新用户等级，支持管理员操作、交易升级等多种方式
• 查询等级历史: 获取用户等级变更历史记录

用户推荐服务

• 查询推荐信息: 根据用户ID查询推荐码和推荐统计
• 添加推荐记录: 记录用户推荐关系
• 查询推荐统计: 获取推荐人数、认证人数等统计信息

数据模型详解

推荐系统模型

type UserReferral struct {
	UserID       string `gorm:"size:50;uniqueIndex:idx_id_code;not null;comment:用户ID"`
	ReferralCode string `gorm:"size:50;uniqueIndex:idx_id_code;not null;comment:推荐码"`

	gorm.Model
}

type ReferralHistory struct {
	ReferralUserID string `gorm:"size:50;not null;comment:推荐人ID"` // 冗余字段
	ReferralCode   string `gorm:"size:50;not null;uniqueIndex:idx_code_email;comment:推荐码"`
	Email          string `gorm:"size:50;not null;uniqueIndex:idx_code_email;comment:被邀请人邮箱"`
	UserID         string `gorm:"size:50;not null;unique;index;comment:被邀请人ID"`

	IsCompleteKYC   bool         `gorm:"comment:是否完成KYC"` // 完成KYC时通过回调更新
	CompleteKYCTime sql.NullTime `gorm:"comment:完成KYC时间"` // 完成KYC时通过回调更新

	gorm.Model
}

VIP等级模型

type VipLevel struct {
	LevelID   int64  `gorm:"uniqueIndex;comment:用户等级ID"`
	LevelName string `gorm:"size:50;unique;comment:用户等级名称"`

	gorm.Model
}

业务逻辑

用户等级管理

等级类型

• Regular: 普通用户（默认等级，ID: -1）
• VIP: VIP用户（ID: 1-20，共20个等级）

等级更新操作者类型

const (
	UpdateUserLevelOperatorInit   = "INIT"   // 初始化
	UpdateUserLevelOperatorAdmin  = "ADMIN"  // 管理员
	UpdateUserLevelOperatorInvite = "INVITE" // 邀请
	UpdateUserLevelOperatorTrade  = "TRADE"  // 交易
	UpdateUserLevelOperatorExpire = "EXPIRE" // 过期
)

账户类别支持

var (
	AccountCategorySpot = ledger_manager_service.AccountCategory_SPOT
	AccountCategoryOTC  = ledger_manager_service.AccountCategory_OTC
)

系统支持现货(SPOT)和OTC两种账户类别，用户在不同账户类别下可以有不同的等级。

推荐系统

推荐流程

1. 用户注册时自动生成推荐码
2. 推荐人分享推荐码给新用户
3. 新用户使用推荐码注册，建立推荐关系
4. 系统记录推荐历史和奖励信息

推荐奖励配置

[referral]
reward_vip_level = 6
# 90 days
reward_duration = 90

• reward_vip_level: 推荐奖励的VIP等级
• reward_duration: 奖励持续时间（天）

定时任务

系统包含以下定时任务：

1. KYC扫描任务: 每5分钟扫描一次KYC状态更新
2. VIP扫描任务: 每5分钟扫描一次VIP等级状态
3. 用户等级更新任务: 每天上午8点(香港时区)执行用户等级更新

配置参数：

[cron]
enable = true
scan_kyc_interval = "5m"
scan_vip_interval = "5m"
update_user_level_stmt = "0 8 * * *"

开发环境搭建

环境要求

• Go 1.22.2+
• MySQL/PostgreSQL/SQLite
• Docker (可选)

本地开发

1. 克隆项目

git clone <repository-url>
cd exchange-user-attribute-backend

2. 安装依赖

go mod tidy

3. 配置文件 复制 config.toml 并根据需要修改配置：

cp config.toml private.toml
# 编辑 private.toml 设置数据库连接等私有配置

4. 运行项目

make run

构建和部署

本地构建

.PHONY: build-linux
build-linux:
	@echo "Building for Linux.."
	@echo "GIT_HASH: $(GIT_HASH)"
	@echo "BUILD_DATE_TIME: $(BUILD_DATE_TIME)"
	@echo "Module Name: $(MODULE)"
	@CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags "-X $(MODULE)/consts.AppName=$(MODULE) -X $(MODULE)/utils.buildDateTime=$(BUILD_DATE_TIME) -X $(MODULE)/utils.gitHash=$(GIT_HASH)" -a -o user-attribute main.go

Docker 部署

# Builder
FROM golang:1.22-bullseye AS builder

RUN useradd -m builder

WORKDIR /src
RUN go env -w GOPRIVATE=gitlab.atom8.io/hkbitex/*

ARG ACCESS_TOKEN_USR="nothing"
ARG ACCESS_TOKEN_PWD="nothing"

RUN printf "machine gitlab.atom8.io\n\
	login ${ACCESS_TOKEN_USR}\n\
	password ${ACCESS_TOKEN_PWD}\n"\
	>> /home/builder/.netrc

构建Docker镜像：

docker build -t user-attribute:latest .

开发环境部署

make dev

此命令会自动构建并部署到开发服务器。

代码规范

项目结构规范

• consts/: 存放项目常量定义
• core/: 核心应用框架和模块管理
• models/: 数据模型定义
• service/: 业务逻辑实现
• grpc/: gRPC服务接口实现
• utils/: 工具函数
• types/: 类型定义

命名规范

• 包名使用小写字母
• 结构体使用大写字母开头的驼峰命名
• 接口名通常以er结尾
• 常量使用大写字母和下划线

错误处理

项目统一使用Go标准的错误处理方式，重要操作都需要进行错误检查和日志记录。

监控和日志

日志配置

使用zerolog作为日志库，支持结构化日志：

[log]
level = "info"

健康检查

gRPC服务支持健康检查：

[grpc]
enable = true
host = "0.0.0.0"
port = 9000
with_health = true

安全注意事项

1. 配置文件安全: 敏感配置信息存放在private.toml文件中，不要提交到版本控制
2. 数据库连接: 使用环境变量或安全的配置管理来存储数据库连接信息
3. API访问控制: gRPC接口需要适当的认证和授权机制
4. 日志安全: 避免在日志中记录敏感信息

常见问题

Q: 如何添加新的VIP等级？

A: 在数据库的vip_levels表中添加新记录，并更新相关的业务逻辑。

Q: 如何修改推荐奖励配置？

A: 修改配置文件中的[referral]部分，然后重启服务。

Q: 如何查看用户等级变更历史？

A: 查询user_level_histories表，包含了所有的等级变更记录。

Q: 如何处理数据库迁移？

A: 使用GORM的自动迁移功能，或者编写自定义的迁移脚本。

贡献指南

1. Fork项目
2. 创建功能分支: git checkout -b feature/new-feature
3. 提交更改: git commit -am 'Add new feature'
4. 推送分支: git push origin feature/new-feature
5. 创建Pull Request

许可证

[添加许可证信息]

---

这份文档涵盖了项目的主要功能、架构设计、配置管理、API接口、开发部署等各个方面。如需更详细的信息，请查看具体的代码实现或联系开发团队。