457 lines
15 KiB
Markdown
457 lines
15 KiB
Markdown
# Genex 后端开发指南
|
||
|
||
> DDD + Clean Architecture + 微服务 | NestJS + Go + Kong + PostgreSQL
|
||
|
||
---
|
||
|
||
## 1. 技术栈总览
|
||
|
||
| 层级 | 技术 | 用途 |
|
||
|------|------|------|
|
||
| **API网关** | Kong | 限流、认证、路由、负载均衡 |
|
||
| **主要业务服务** | NestJS (TypeScript) | 业务逻辑微服务 |
|
||
| **高性能服务** | Go | 撮合引擎、链上事件监听、高频任务 |
|
||
| **翻译层** | Go + Redis | 地址映射、Gas代付、术语翻译 |
|
||
| **数据库** | PostgreSQL 15+ | 核心业务数据 |
|
||
| **时序数据库** | TimescaleDB | 行情数据、监控指标 |
|
||
| **缓存** | Redis Cluster | 热点数据、会话、订单簿缓存 |
|
||
| **消息队列** | Kafka | 事件驱动、链上事件监听 |
|
||
| **搜索** | Elasticsearch | 全文检索、日志分析 |
|
||
| **AI/ML** | FastAPI (Python) | 信用评分、价格预测、异常检测 |
|
||
|
||
---
|
||
|
||
## 2. 架构设计：三层五域
|
||
|
||
### 2.1 五大业务域
|
||
|
||
| 域 | 服务名 | 语言 | 职责 |
|
||
|----|--------|------|------|
|
||
| D1 发行域 | `issuer-service` | NestJS | 发行方入驻、券管理、发行审批 |
|
||
| D2 交易域 | `trading-service` | Go | 撮合引擎、订单簿、做市商 |
|
||
| D3 清算域 | `clearing-service` | NestJS + Go | 链上结算、兑付清算、退款 |
|
||
| D4 合规域 | `compliance-service` | NestJS | KYC/AML、OFAC、Travel Rule |
|
||
| D5 AI域 | `ai-service` | FastAPI | 信用评分、定价、异常检测 |
|
||
| 通用 | `user-service` | NestJS | 用户注册、认证、Profile |
|
||
| 通用 | `translate-service` | Go | UX翻译层（地址映射、Gas代付） |
|
||
| 通用 | `notification-service` | NestJS | 消息推送、邮件、短信 |
|
||
| 通用 | `chain-indexer` | Go | 链上事件监听、数据索引 |
|
||
|
||
### 2.2 服务间通信
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ Kong API Gateway │
|
||
│ 限流 | OAuth 2.1 + JWT | 路由 | 负载均衡 │
|
||
├──────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────┐ ┌──────────┐ ┌────────────┐ │
|
||
│ │ user │ │ issuer │ │ trading │ │
|
||
│ │ service │ │ service │ │ service(Go)│ │
|
||
│ └────┬────┘ └────┬─────┘ └─────┬──────┘ │
|
||
│ │ │ │ │
|
||
│ └────────────┼──────────────┘ │
|
||
│ │ │
|
||
│ ┌─────┴─────┐ │
|
||
│ │ Kafka │ │
|
||
│ └─────┬─────┘ │
|
||
│ ┌────────────┼───────────────┐ │
|
||
│ ┌────┴────┐ ┌─────┴──────┐ ┌─────┴─────┐ │
|
||
│ │clearing │ │compliance │ │ai-service │ │
|
||
│ │service │ │service │ │(FastAPI) │ │
|
||
│ └─────────┘ └────────────┘ └───────────┘ │
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
- **同步通信**：gRPC（服务间直接调用，如撮合→结算）
|
||
- **异步通信**：Kafka事件驱动（链上事件、通知、审计日志）
|
||
|
||
---
|
||
|
||
## 3. DDD + Clean Architecture（NestJS服务）
|
||
|
||
### 3.1 模块结构（以issuer-service为例）
|
||
|
||
```
|
||
issuer-service/
|
||
├── src/
|
||
│ ├── main.ts
|
||
│ ├── app.module.ts
|
||
│ ├── domain/ # 领域层（纯业务逻辑，零外部依赖）
|
||
│ │ ├── entities/
|
||
│ │ │ ├── issuer.entity.ts # 发行方聚合根
|
||
│ │ │ ├── coupon-template.entity.ts
|
||
│ │ │ └── credit-rating.vo.ts # 值对象
|
||
│ │ ├── repositories/
|
||
│ │ │ └── issuer.repository.ts # Repository接口
|
||
│ │ ├── services/
|
||
│ │ │ ├── issuer-domain.service.ts
|
||
│ │ │ └── credit-scoring.service.ts
|
||
│ │ └── events/
|
||
│ │ ├── issuer-approved.event.ts
|
||
│ │ └── coupon-issued.event.ts
|
||
│ ├── application/ # 应用层（用例编排）
|
||
│ │ ├── commands/
|
||
│ │ │ ├── register-issuer.command.ts
|
||
│ │ │ ├── create-coupon.command.ts
|
||
│ │ │ └── handlers/
|
||
│ │ ├── queries/
|
||
│ │ │ ├── get-issuer.query.ts
|
||
│ │ │ └── handlers/
|
||
│ │ └── dto/
|
||
│ │ ├── create-issuer.dto.ts
|
||
│ │ └── create-coupon.dto.ts
|
||
│ ├── infrastructure/ # 基础设施层（外部实现）
|
||
│ │ ├── persistence/
|
||
│ │ │ ├── issuer.repository.impl.ts
|
||
│ │ │ ├── issuer.orm-entity.ts
|
||
│ │ │ └── typeorm.config.ts
|
||
│ │ ├── messaging/
|
||
│ │ │ └── kafka-publisher.ts
|
||
│ │ └── external/
|
||
│ │ └── chain-client.ts # 链上交互
|
||
│ └── interfaces/ # 接口层（HTTP/gRPC）
|
||
│ ├── http/
|
||
│ │ ├── issuer.controller.ts
|
||
│ │ └── coupon.controller.ts
|
||
│ └── grpc/
|
||
│ └── issuer.grpc-controller.ts
|
||
├── test/
|
||
└── package.json
|
||
```
|
||
|
||
### 3.2 领域实体
|
||
|
||
```typescript
|
||
// src/domain/entities/issuer.entity.ts
|
||
export class Issuer {
|
||
readonly id: string;
|
||
readonly companyName: string;
|
||
private _creditRating: CreditRating;
|
||
private _issuanceQuota: number;
|
||
private _tier: IssuerTier;
|
||
private _status: IssuerStatus;
|
||
|
||
// 信用评分四因子
|
||
updateCreditScore(metrics: CreditMetrics): void {
|
||
const score =
|
||
0.35 * metrics.redemptionRate +
|
||
0.25 * (1 - metrics.breakageRatio) +
|
||
0.20 * Math.log(metrics.marketTenure + 1) / Math.log(37) +
|
||
0.20 * metrics.userSatisfaction;
|
||
|
||
this._creditRating = CreditRating.fromScore(score);
|
||
this._issuanceQuota = this._creditRating.calculateQuota();
|
||
}
|
||
|
||
// 发券校验
|
||
canIssueCoupon(params: CreateCouponParams): Result<void> {
|
||
if (this._status !== IssuerStatus.ACTIVE)
|
||
return Result.fail('发行方状态异常');
|
||
if (params.totalValue > this.remainingQuota)
|
||
return Result.fail('超出发行额度');
|
||
if (params.expiryDays > 365)
|
||
return Result.fail('Utility Track有效期不得超过12个月');
|
||
return Result.ok();
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 应用层Command
|
||
|
||
```typescript
|
||
// src/application/commands/handlers/create-coupon.handler.ts
|
||
@CommandHandler(CreateCouponCommand)
|
||
export class CreateCouponHandler {
|
||
constructor(
|
||
private issuerRepo: IssuerRepository,
|
||
private eventBus: EventBus,
|
||
) {}
|
||
|
||
async execute(command: CreateCouponCommand): Promise<CouponDraft> {
|
||
const issuer = await this.issuerRepo.findById(command.issuerId);
|
||
if (!issuer) throw new NotFoundException('发行方不存在');
|
||
|
||
// 领域校验
|
||
const validation = issuer.canIssueCoupon(command.params);
|
||
if (validation.isFailure) throw new BadRequestException(validation.error);
|
||
|
||
// 创建券草稿（待审核）
|
||
const draft = CouponDraft.create(issuer, command.params);
|
||
await this.issuerRepo.saveCouponDraft(draft);
|
||
|
||
// 发布领域事件
|
||
this.eventBus.publish(new CouponDraftCreatedEvent(draft));
|
||
|
||
return draft;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Go 高性能服务
|
||
|
||
### 4.1 撮合引擎
|
||
|
||
```go
|
||
// trading-service/internal/matching/engine.go
|
||
type MatchingEngine struct {
|
||
orderBooks map[string]*OrderBook // couponId → OrderBook
|
||
mu sync.RWMutex
|
||
}
|
||
|
||
type OrderBook struct {
|
||
Bids *redblacktree.Tree // 买单：价格降序
|
||
Asks *redblacktree.Tree // 卖单：价格升序
|
||
}
|
||
|
||
func (e *MatchingEngine) SubmitOrder(order *Order) []*Trade {
|
||
e.mu.Lock()
|
||
defer e.mu.Unlock()
|
||
|
||
book := e.getOrCreateBook(order.CouponID)
|
||
|
||
// Utility Track价格校验
|
||
if order.CouponType == CouponTypeUtility && order.Price > order.FaceValue {
|
||
return nil // 拒绝溢价单
|
||
}
|
||
|
||
// 撮合：价格优先 → 时间优先
|
||
trades := book.Match(order)
|
||
|
||
// 成交后发布事件到Kafka
|
||
for _, trade := range trades {
|
||
e.publisher.Publish("trade.matched", trade)
|
||
}
|
||
|
||
return trades
|
||
}
|
||
```
|
||
|
||
### 4.2 链上事件监听
|
||
|
||
```go
|
||
// chain-indexer/internal/indexer/indexer.go
|
||
type ChainIndexer struct {
|
||
ethClient *ethclient.Client
|
||
kafka sarama.SyncProducer
|
||
contracts map[string]common.Address
|
||
}
|
||
|
||
func (i *ChainIndexer) Start(ctx context.Context) {
|
||
// 监听Genex Chain事件
|
||
query := ethereum.FilterQuery{
|
||
Addresses: []common.Address{
|
||
i.contracts["CouponFactory"],
|
||
i.contracts["Settlement"],
|
||
i.contracts["Redemption"],
|
||
},
|
||
}
|
||
|
||
logs := make(chan types.Log)
|
||
sub, _ := i.ethClient.SubscribeFilterLogs(ctx, query, logs)
|
||
|
||
for {
|
||
select {
|
||
case log := <-logs:
|
||
event := i.parseEvent(log)
|
||
i.kafka.SendMessage(&sarama.ProducerMessage{
|
||
Topic: "chain.events",
|
||
Value: sarama.ByteEncoder(event.Marshal()),
|
||
})
|
||
case err := <-sub.Err():
|
||
log.Error("subscription error", "err", err)
|
||
// 重连逻辑
|
||
case <-ctx.Done():
|
||
return
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. UX翻译层
|
||
|
||
> 核心创新：将所有Web3操作翻译为Web2用户可理解的操作。
|
||
|
||
```go
|
||
// translate-service/internal/service/translate.go
|
||
type TranslateService struct {
|
||
mappingDB *redis.Client // 手机号→链上地址映射
|
||
mpcClient MPCClient // MPC钱包服务
|
||
paymaster PaymasterClient // Gas代付服务
|
||
}
|
||
|
||
// 手机号→链上地址
|
||
func (s *TranslateService) ResolveAddress(phone string) (common.Address, error) {
|
||
addr, err := s.mappingDB.Get(ctx, "phone:"+phone).Result()
|
||
if err == redis.Nil {
|
||
return common.Address{}, ErrUserNotFound
|
||
}
|
||
return common.HexToAddress(addr), nil
|
||
}
|
||
|
||
// 购买券：法币→链上原子交换
|
||
func (s *TranslateService) ExecutePurchase(req PurchaseRequest) (*PurchaseResult, error) {
|
||
// 1. 法币支付确认
|
||
// 2. 法币→稳定币转换
|
||
// 3. 调用Settlement合约原子交换（Gas由Paymaster代付）
|
||
// 4. 返回"订单号"（映射TX Hash）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. API设计
|
||
|
||
### 6.1 RESTful规范
|
||
|
||
```yaml
|
||
API规范:
|
||
风格: RESTful
|
||
版本控制: URL路径 /api/v1/
|
||
认证: OAuth 2.1 + JWT
|
||
限流:
|
||
普通用户: 100 req/min
|
||
发行方: 1,000 req/min
|
||
做市商: 10,000 req/min
|
||
响应格式: JSON
|
||
错误处理: RFC 7807 Problem Details
|
||
```
|
||
|
||
### 6.2 核心API端点
|
||
|
||
| 域 | 路径前缀 | 主要接口 |
|
||
|-----|---------|---------|
|
||
| 用户 | `/api/v1/users` | 注册、登录、KYC、资产查询 |
|
||
| 券 | `/api/v1/coupons` | 发行、查询、转让、核销 |
|
||
| 交易 | `/api/v1/trades` | 挂单、撤单、成交、历史 |
|
||
| 支付 | `/api/v1/payments` | 充值、提现、法币转换 |
|
||
| 发行方 | `/api/v1/issuers` | 入驻、审核、数据统计 |
|
||
| 合规 | `/api/v1/compliance` | KYC、AML、审计日志 |
|
||
| 翻译层 | `/api/v1/translate` | 地址映射、Gas代付 |
|
||
|
||
---
|
||
|
||
## 7. 数据库设计
|
||
|
||
### 7.1 PostgreSQL核心表
|
||
|
||
```sql
|
||
-- 用户表
|
||
CREATE TABLE users (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
phone VARCHAR(20) UNIQUE,
|
||
email VARCHAR(100) UNIQUE,
|
||
kyc_level SMALLINT NOT NULL DEFAULT 0,
|
||
wallet_mode VARCHAR(10) NOT NULL DEFAULT 'standard',
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 发行方表
|
||
CREATE TABLE issuers (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
company_name VARCHAR(200) NOT NULL,
|
||
business_license VARCHAR(100),
|
||
credit_rating VARCHAR(5) NOT NULL DEFAULT 'BBB',
|
||
credit_score NUMERIC(5,2) NOT NULL DEFAULT 60.00,
|
||
issuance_quota NUMERIC(15,2) NOT NULL DEFAULT 100000,
|
||
tier VARCHAR(10) NOT NULL DEFAULT 'silver',
|
||
status VARCHAR(20) NOT NULL DEFAULT 'pending',
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 券表（链下缓存，权威数据在链上）
|
||
CREATE TABLE coupons (
|
||
id UUID PRIMARY KEY,
|
||
chain_token_id BIGINT UNIQUE, -- 链上Token ID
|
||
issuer_id UUID REFERENCES issuers(id),
|
||
face_value NUMERIC(12,2) NOT NULL,
|
||
current_price NUMERIC(12,2),
|
||
expiry_date DATE NOT NULL,
|
||
coupon_type VARCHAR(10) NOT NULL DEFAULT 'utility',
|
||
status VARCHAR(20) NOT NULL DEFAULT 'available',
|
||
resale_count SMALLINT NOT NULL DEFAULT 0,
|
||
max_resale_count SMALLINT NOT NULL DEFAULT 3,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 地址映射表（翻译层核心）
|
||
CREATE TABLE address_mappings (
|
||
user_id UUID REFERENCES users(id),
|
||
chain_address VARCHAR(42) NOT NULL UNIQUE,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
PRIMARY KEY (user_id)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 安全规范
|
||
|
||
| 领域 | 规范 |
|
||
|------|------|
|
||
| 传输 | TLS 1.3 + 服务间mTLS |
|
||
| 认证 | OAuth 2.1 + JWT（短有效期 + Refresh Token） |
|
||
| 授权 | RBAC |
|
||
| 数据加密 | AES-256（敏感字段），HSM管理密钥 |
|
||
| API安全 | Rate Limiting + CORS + CSRF防护 |
|
||
| SQL注入 | ORM参数化查询（TypeORM / sqlx） |
|
||
| 审计 | 全链路操作日志，不可篡改 |
|
||
|
||
---
|
||
|
||
## 9. 部署架构
|
||
|
||
```yaml
|
||
# Kubernetes部署
|
||
apiVersion: apps/v1
|
||
kind: Deployment
|
||
metadata:
|
||
name: issuer-service
|
||
spec:
|
||
replicas: 3
|
||
template:
|
||
spec:
|
||
containers:
|
||
- name: issuer-service
|
||
image: genex/issuer-service:latest
|
||
resources:
|
||
requests: { cpu: "250m", memory: "512Mi" }
|
||
limits: { cpu: "1000m", memory: "1Gi" }
|
||
env:
|
||
- name: DB_HOST
|
||
valueFrom:
|
||
configMapKeyRef: { name: db-config, key: host }
|
||
- name: DB_PASSWORD
|
||
valueFrom:
|
||
secretKeyRef: { name: db-secrets, key: password }
|
||
```
|
||
|
||
### 多区域部署
|
||
|
||
| 区域 | 部署 | 角色 |
|
||
|------|------|------|
|
||
| AWS美国（主） | 全量服务 + 主数据库 + Genex Chain主验证节点 |
|
||
| AWS新加坡 | 亚太服务 + 灾备数据库 + 区域验证节点 |
|
||
| 香港 | 监管节点 + 审计接口 |
|
||
|
||
---
|
||
|
||
## 10. 监控与可观测性
|
||
|
||
| 组件 | 工具 | 用途 |
|
||
|------|------|------|
|
||
| 指标 | Prometheus + Grafana | 服务指标、业务指标 |
|
||
| 日志 | ELK Stack | 日志收集分析 |
|
||
| 链路追踪 | Jaeger | 分布式调用追踪 |
|
||
| 告警 | AlertManager + PagerDuty | 异常告警 |
|
||
|
||
---
|
||
|
||
*文档版本: v1.0*
|
||
*基于: Genex 券交易平台 - 软件需求规格说明书 v4.1*
|
||
*技术栈: NestJS + Go + Kong + PostgreSQL + Kafka + Redis*
|