758 lines
20 KiB
Markdown
758 lines
20 KiB
Markdown
# Wallet Service 开发指导
|
||
|
||
## 项目概述
|
||
|
||
Wallet Service 是 RWA 榴莲女皇平台的钱包账本微服务，负责管理用户的平台内部余额、充值入账、提现、资金流水记账等功能。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: NestJS
|
||
- **数据库**: PostgreSQL + Prisma ORM
|
||
- **架构**: DDD + Hexagonal Architecture (六边形架构)
|
||
- **语言**: TypeScript
|
||
|
||
## 架构参考
|
||
|
||
请参考 `identity-service` 的架构模式，保持一致性：
|
||
|
||
```
|
||
wallet-service/
|
||
├── prisma/
|
||
│ └── schema.prisma # 数据库模型
|
||
├── src/
|
||
│ ├── api/ # Presentation Layer (API层)
|
||
│ │ ├── controllers/ # HTTP 控制器
|
||
│ │ │ ├── wallet.controller.ts
|
||
│ │ │ ├── ledger.controller.ts
|
||
│ │ │ ├── deposit.controller.ts
|
||
│ │ │ └── settlement.controller.ts
|
||
│ │ ├── dto/ # 数据传输对象
|
||
│ │ │ ├── wallet.dto.ts
|
||
│ │ │ ├── ledger.dto.ts
|
||
│ │ │ ├── deposit.dto.ts
|
||
│ │ │ └── settlement.dto.ts
|
||
│ │ └── api.module.ts
|
||
│ │
|
||
│ ├── application/ # Application Layer (应用层)
|
||
│ │ ├── commands/ # 命令对象
|
||
│ │ │ ├── handle-deposit.command.ts
|
||
│ │ │ ├── deduct-for-planting.command.ts
|
||
│ │ │ ├── allocate-funds.command.ts
|
||
│ │ │ ├── add-rewards.command.ts
|
||
│ │ │ ├── settle-rewards.command.ts
|
||
│ │ │ └── withdraw.command.ts
|
||
│ │ ├── queries/ # 查询对象
|
||
│ │ │ ├── get-my-wallet.query.ts
|
||
│ │ │ └── get-my-ledger.query.ts
|
||
│ │ └── services/
|
||
│ │ └── wallet-application.service.ts
|
||
│ │
|
||
│ ├── domain/ # Domain Layer (领域层)
|
||
│ │ ├── aggregates/ # 聚合根
|
||
│ │ │ ├── wallet-account.aggregate.ts
|
||
│ │ │ ├── ledger-entry.aggregate.ts
|
||
│ │ │ ├── deposit-order.aggregate.ts
|
||
│ │ │ └── settlement-order.aggregate.ts
|
||
│ │ ├── value-objects/ # 值对象
|
||
│ │ │ ├── wallet-id.vo.ts
|
||
│ │ │ ├── money.vo.ts
|
||
│ │ │ ├── balance.vo.ts
|
||
│ │ │ ├── wallet-balances.vo.ts
|
||
│ │ │ ├── wallet-rewards.vo.ts
|
||
│ │ │ ├── hashpower.vo.ts
|
||
│ │ │ ├── asset-type.enum.ts
|
||
│ │ │ ├── chain-type.enum.ts
|
||
│ │ │ ├── wallet-status.enum.ts
|
||
│ │ │ ├── ledger-entry-type.enum.ts
|
||
│ │ │ ├── deposit-status.enum.ts
|
||
│ │ │ └── settlement-status.enum.ts
|
||
│ │ ├── events/ # 领域事件
|
||
│ │ │ ├── deposit-completed.event.ts
|
||
│ │ │ ├── withdrawal-requested.event.ts
|
||
│ │ │ ├── reward-moved-to-settleable.event.ts
|
||
│ │ │ ├── reward-expired.event.ts
|
||
│ │ │ └── settlement-completed.event.ts
|
||
│ │ ├── repositories/ # 仓储接口 (Port)
|
||
│ │ │ ├── wallet-account.repository.interface.ts
|
||
│ │ │ ├── ledger-entry.repository.interface.ts
|
||
│ │ │ ├── deposit-order.repository.interface.ts
|
||
│ │ │ └── settlement-order.repository.interface.ts
|
||
│ │ └── services/ # 领域服务
|
||
│ │ └── wallet-ledger.service.ts
|
||
│ │
|
||
│ ├── infrastructure/ # Infrastructure Layer (基础设施层)
|
||
│ │ ├── persistence/ # 持久化实现 (Adapter)
|
||
│ │ │ ├── entities/ # Prisma 实体映射
|
||
│ │ │ ├── mappers/ # 领域模型与实体的映射
|
||
│ │ │ └── repositories/ # 仓储实现
|
||
│ │ └── infrastructure.module.ts
|
||
│ │
|
||
│ ├── app.module.ts
|
||
│ └── main.ts
|
||
├── .env.development
|
||
├── .env.example
|
||
├── package.json
|
||
└── tsconfig.json
|
||
```
|
||
|
||
---
|
||
|
||
## 第一阶段：项目初始化
|
||
|
||
### 1.1 创建 NestJS 项目
|
||
|
||
```bash
|
||
cd backend/services
|
||
npx @nestjs/cli new wallet-service --skip-git --package-manager npm
|
||
cd wallet-service
|
||
```
|
||
|
||
### 1.2 安装依赖
|
||
|
||
```bash
|
||
npm install @nestjs/config @prisma/client class-validator class-transformer uuid
|
||
npm install -D prisma @types/uuid
|
||
```
|
||
|
||
### 1.3 配置环境变量
|
||
|
||
创建 `.env.development`:
|
||
```env
|
||
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/rwadurian_wallet?schema=public"
|
||
NODE_ENV=development
|
||
PORT=3002
|
||
```
|
||
|
||
创建 `.env.example`:
|
||
```env
|
||
DATABASE_URL="postgresql://user:password@host:5432/database?schema=public"
|
||
NODE_ENV=development
|
||
PORT=3002
|
||
```
|
||
|
||
---
|
||
|
||
## 第二阶段：数据库设计 (Prisma Schema)
|
||
|
||
### 2.1 创建 prisma/schema.prisma
|
||
|
||
```prisma
|
||
generator client {
|
||
provider = "prisma-client-js"
|
||
}
|
||
|
||
datasource db {
|
||
provider = "postgresql"
|
||
url = env("DATABASE_URL")
|
||
}
|
||
|
||
// ============================================
|
||
// 钱包账户表 (状态表)
|
||
// ============================================
|
||
model WalletAccount {
|
||
id BigInt @id @default(autoincrement()) @map("wallet_id")
|
||
userId BigInt @unique @map("user_id")
|
||
|
||
// USDT 余额
|
||
usdtAvailable Decimal @default(0) @map("usdt_available") @db.Decimal(20, 8)
|
||
usdtFrozen Decimal @default(0) @map("usdt_frozen") @db.Decimal(20, 8)
|
||
|
||
// DST 余额
|
||
dstAvailable Decimal @default(0) @map("dst_available") @db.Decimal(20, 8)
|
||
dstFrozen Decimal @default(0) @map("dst_frozen") @db.Decimal(20, 8)
|
||
|
||
// BNB 余额
|
||
bnbAvailable Decimal @default(0) @map("bnb_available") @db.Decimal(20, 8)
|
||
bnbFrozen Decimal @default(0) @map("bnb_frozen") @db.Decimal(20, 8)
|
||
|
||
// OG 余额
|
||
ogAvailable Decimal @default(0) @map("og_available") @db.Decimal(20, 8)
|
||
ogFrozen Decimal @default(0) @map("og_frozen") @db.Decimal(20, 8)
|
||
|
||
// RWAD 余额
|
||
rwadAvailable Decimal @default(0) @map("rwad_available") @db.Decimal(20, 8)
|
||
rwadFrozen Decimal @default(0) @map("rwad_frozen") @db.Decimal(20, 8)
|
||
|
||
// 算力
|
||
hashpower Decimal @default(0) @map("hashpower") @db.Decimal(20, 8)
|
||
|
||
// 待领取收益
|
||
pendingUsdt Decimal @default(0) @map("pending_usdt") @db.Decimal(20, 8)
|
||
pendingHashpower Decimal @default(0) @map("pending_hashpower") @db.Decimal(20, 8)
|
||
pendingExpireAt DateTime? @map("pending_expire_at")
|
||
|
||
// 可结算收益
|
||
settleableUsdt Decimal @default(0) @map("settleable_usdt") @db.Decimal(20, 8)
|
||
settleableHashpower Decimal @default(0) @map("settleable_hashpower") @db.Decimal(20, 8)
|
||
|
||
// 已结算总额
|
||
settledTotalUsdt Decimal @default(0) @map("settled_total_usdt") @db.Decimal(20, 8)
|
||
settledTotalHashpower Decimal @default(0) @map("settled_total_hashpower") @db.Decimal(20, 8)
|
||
|
||
// 已过期总额
|
||
expiredTotalUsdt Decimal @default(0) @map("expired_total_usdt") @db.Decimal(20, 8)
|
||
expiredTotalHashpower Decimal @default(0) @map("expired_total_hashpower") @db.Decimal(20, 8)
|
||
|
||
// 状态
|
||
status String @default("ACTIVE") @map("status") @db.VarChar(20)
|
||
|
||
createdAt DateTime @default(now()) @map("created_at")
|
||
updatedAt DateTime @updatedAt @map("updated_at")
|
||
|
||
@@map("wallet_accounts")
|
||
@@index([userId])
|
||
@@index([usdtAvailable(sort: Desc)])
|
||
@@index([hashpower(sort: Desc)])
|
||
@@index([status])
|
||
}
|
||
|
||
// ============================================
|
||
// 账本流水表 (行为表, append-only)
|
||
// ============================================
|
||
model LedgerEntry {
|
||
id BigInt @id @default(autoincrement()) @map("entry_id")
|
||
userId BigInt @map("user_id")
|
||
|
||
// 流水类型
|
||
entryType String @map("entry_type") @db.VarChar(50)
|
||
|
||
// 金额变动 (正数入账, 负数支出)
|
||
amount Decimal @map("amount") @db.Decimal(20, 8)
|
||
assetType String @map("asset_type") @db.VarChar(20)
|
||
|
||
// 余额快照 (操作后余额)
|
||
balanceAfter Decimal? @map("balance_after") @db.Decimal(20, 8)
|
||
|
||
// 关联引用
|
||
refOrderId String? @map("ref_order_id") @db.VarChar(100)
|
||
refTxHash String? @map("ref_tx_hash") @db.VarChar(100)
|
||
|
||
// 备注
|
||
memo String? @map("memo") @db.VarChar(500)
|
||
|
||
// 扩展数据
|
||
payloadJson Json? @map("payload_json")
|
||
|
||
createdAt DateTime @default(now()) @map("created_at")
|
||
|
||
@@map("wallet_ledger_entries")
|
||
@@index([userId, createdAt(sort: Desc)])
|
||
@@index([entryType])
|
||
@@index([assetType])
|
||
@@index([refOrderId])
|
||
@@index([refTxHash])
|
||
@@index([createdAt])
|
||
}
|
||
|
||
// ============================================
|
||
// 充值订单表
|
||
// ============================================
|
||
model DepositOrder {
|
||
id BigInt @id @default(autoincrement()) @map("order_id")
|
||
userId BigInt @map("user_id")
|
||
|
||
// 充值信息
|
||
chainType String @map("chain_type") @db.VarChar(20)
|
||
amount Decimal @map("amount") @db.Decimal(20, 8)
|
||
txHash String @unique @map("tx_hash") @db.VarChar(100)
|
||
|
||
// 状态
|
||
status String @default("PENDING") @map("status") @db.VarChar(20)
|
||
confirmedAt DateTime? @map("confirmed_at")
|
||
|
||
createdAt DateTime @default(now()) @map("created_at")
|
||
|
||
@@map("deposit_orders")
|
||
@@index([userId])
|
||
@@index([txHash])
|
||
@@index([status])
|
||
@@index([chainType])
|
||
}
|
||
|
||
// ============================================
|
||
// 结算订单表
|
||
// ============================================
|
||
model SettlementOrder {
|
||
id BigInt @id @default(autoincrement()) @map("order_id")
|
||
userId BigInt @map("user_id")
|
||
|
||
// 结算信息
|
||
usdtAmount Decimal @map("usdt_amount") @db.Decimal(20, 8)
|
||
settleCurrency String @map("settle_currency") @db.VarChar(10)
|
||
|
||
// SWAP 信息
|
||
swapTxHash String? @map("swap_tx_hash") @db.VarChar(100)
|
||
receivedAmount Decimal? @map("received_amount") @db.Decimal(20, 8)
|
||
|
||
// 状态
|
||
status String @default("PENDING") @map("status") @db.VarChar(20)
|
||
settledAt DateTime? @map("settled_at")
|
||
|
||
createdAt DateTime @default(now()) @map("created_at")
|
||
|
||
@@map("settlement_orders")
|
||
@@index([userId])
|
||
@@index([status])
|
||
@@index([settleCurrency])
|
||
@@index([createdAt])
|
||
}
|
||
```
|
||
|
||
### 2.2 初始化数据库
|
||
|
||
```bash
|
||
npx prisma migrate dev --name init
|
||
npx prisma generate
|
||
```
|
||
|
||
---
|
||
|
||
## 第三阶段：领域层实现
|
||
|
||
### 3.1 值对象 (Value Objects)
|
||
|
||
#### 3.1.1 asset-type.enum.ts
|
||
```typescript
|
||
export enum AssetType {
|
||
USDT = 'USDT',
|
||
DST = 'DST',
|
||
BNB = 'BNB',
|
||
OG = 'OG',
|
||
RWAD = 'RWAD',
|
||
HASHPOWER = 'HASHPOWER',
|
||
}
|
||
```
|
||
|
||
#### 3.1.2 chain-type.enum.ts
|
||
```typescript
|
||
export enum ChainType {
|
||
KAVA = 'KAVA',
|
||
DST = 'DST',
|
||
BSC = 'BSC',
|
||
}
|
||
```
|
||
|
||
#### 3.1.3 wallet-status.enum.ts
|
||
```typescript
|
||
export enum WalletStatus {
|
||
ACTIVE = 'ACTIVE',
|
||
FROZEN = 'FROZEN',
|
||
CLOSED = 'CLOSED',
|
||
}
|
||
```
|
||
|
||
#### 3.1.4 ledger-entry-type.enum.ts
|
||
```typescript
|
||
export enum LedgerEntryType {
|
||
DEPOSIT_KAVA = 'DEPOSIT_KAVA',
|
||
DEPOSIT_BSC = 'DEPOSIT_BSC',
|
||
PLANT_PAYMENT = 'PLANT_PAYMENT',
|
||
REWARD_PENDING = 'REWARD_PENDING',
|
||
REWARD_TO_SETTLEABLE = 'REWARD_TO_SETTLEABLE',
|
||
REWARD_EXPIRED = 'REWARD_EXPIRED',
|
||
REWARD_SETTLED = 'REWARD_SETTLED',
|
||
TRANSFER_TO_POOL = 'TRANSFER_TO_POOL',
|
||
SWAP_EXECUTED = 'SWAP_EXECUTED',
|
||
WITHDRAWAL = 'WITHDRAWAL',
|
||
TRANSFER_IN = 'TRANSFER_IN',
|
||
TRANSFER_OUT = 'TRANSFER_OUT',
|
||
FREEZE = 'FREEZE',
|
||
UNFREEZE = 'UNFREEZE',
|
||
}
|
||
```
|
||
|
||
#### 3.1.5 deposit-status.enum.ts
|
||
```typescript
|
||
export enum DepositStatus {
|
||
PENDING = 'PENDING',
|
||
CONFIRMED = 'CONFIRMED',
|
||
FAILED = 'FAILED',
|
||
}
|
||
```
|
||
|
||
#### 3.1.6 settlement-status.enum.ts
|
||
```typescript
|
||
export enum SettlementStatus {
|
||
PENDING = 'PENDING',
|
||
SWAPPING = 'SWAPPING',
|
||
COMPLETED = 'COMPLETED',
|
||
FAILED = 'FAILED',
|
||
}
|
||
|
||
export enum SettleCurrency {
|
||
BNB = 'BNB',
|
||
OG = 'OG',
|
||
USDT = 'USDT',
|
||
DST = 'DST',
|
||
}
|
||
```
|
||
|
||
#### 3.1.7 money.vo.ts
|
||
```typescript
|
||
export class Money {
|
||
private constructor(
|
||
public readonly amount: number,
|
||
public readonly currency: string,
|
||
) {
|
||
if (amount < 0) {
|
||
throw new Error('Money amount cannot be negative');
|
||
}
|
||
}
|
||
|
||
static create(amount: number, currency: string): Money {
|
||
return new Money(amount, currency);
|
||
}
|
||
|
||
static USDT(amount: number): Money {
|
||
return new Money(amount, 'USDT');
|
||
}
|
||
|
||
static zero(currency: string = 'USDT'): Money {
|
||
return new Money(0, currency);
|
||
}
|
||
|
||
add(other: Money): Money {
|
||
this.ensureSameCurrency(other);
|
||
return new Money(this.amount + other.amount, this.currency);
|
||
}
|
||
|
||
subtract(other: Money): Money {
|
||
this.ensureSameCurrency(other);
|
||
if (this.amount < other.amount) {
|
||
throw new Error('Insufficient balance');
|
||
}
|
||
return new Money(this.amount - other.amount, this.currency);
|
||
}
|
||
|
||
lessThan(other: Money): boolean {
|
||
this.ensureSameCurrency(other);
|
||
return this.amount < other.amount;
|
||
}
|
||
|
||
greaterThan(other: Money): boolean {
|
||
this.ensureSameCurrency(other);
|
||
return this.amount > other.amount;
|
||
}
|
||
|
||
isZero(): boolean {
|
||
return this.amount === 0;
|
||
}
|
||
|
||
private ensureSameCurrency(other: Money): void {
|
||
if (this.currency !== other.currency) {
|
||
throw new Error('Currency mismatch');
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.1.8 balance.vo.ts
|
||
```typescript
|
||
import { Money } from './money.vo';
|
||
|
||
export class Balance {
|
||
constructor(
|
||
public readonly available: Money,
|
||
public readonly frozen: Money,
|
||
) {}
|
||
|
||
static zero(): Balance {
|
||
return new Balance(Money.zero(), Money.zero());
|
||
}
|
||
|
||
add(amount: Money): Balance {
|
||
return new Balance(this.available.add(amount), this.frozen);
|
||
}
|
||
|
||
deduct(amount: Money): Balance {
|
||
if (this.available.lessThan(amount)) {
|
||
throw new Error('Insufficient available balance');
|
||
}
|
||
return new Balance(this.available.subtract(amount), this.frozen);
|
||
}
|
||
|
||
freeze(amount: Money): Balance {
|
||
if (this.available.lessThan(amount)) {
|
||
throw new Error('Insufficient available balance to freeze');
|
||
}
|
||
return new Balance(
|
||
this.available.subtract(amount),
|
||
this.frozen.add(amount),
|
||
);
|
||
}
|
||
|
||
unfreeze(amount: Money): Balance {
|
||
if (this.frozen.lessThan(amount)) {
|
||
throw new Error('Insufficient frozen balance to unfreeze');
|
||
}
|
||
return new Balance(
|
||
this.available.add(amount),
|
||
this.frozen.subtract(amount),
|
||
);
|
||
}
|
||
|
||
get total(): Money {
|
||
return this.available.add(this.frozen);
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.1.9 hashpower.vo.ts
|
||
```typescript
|
||
export class Hashpower {
|
||
private constructor(public readonly value: number) {
|
||
if (value < 0) {
|
||
throw new Error('Hashpower cannot be negative');
|
||
}
|
||
}
|
||
|
||
static create(value: number): Hashpower {
|
||
return new Hashpower(value);
|
||
}
|
||
|
||
static zero(): Hashpower {
|
||
return new Hashpower(0);
|
||
}
|
||
|
||
add(other: Hashpower): Hashpower {
|
||
return new Hashpower(this.value + other.value);
|
||
}
|
||
|
||
subtract(other: Hashpower): Hashpower {
|
||
if (this.value < other.value) {
|
||
throw new Error('Insufficient hashpower');
|
||
}
|
||
return new Hashpower(this.value - other.value);
|
||
}
|
||
|
||
isZero(): boolean {
|
||
return this.value === 0;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 聚合根 (Aggregates)
|
||
|
||
#### 3.2.1 wallet-account.aggregate.ts
|
||
|
||
实现 `WalletAccount` 聚合根，包含：
|
||
- 余额管理 (USDT/DST/BNB/OG/RWAD/算力)
|
||
- 收益汇总 (待领取/可结算/已结算/过期)
|
||
- 核心领域行为：deposit, deduct, freeze, unfreeze, addPendingReward, movePendingToSettleable, settleReward, withdraw
|
||
|
||
#### 3.2.2 ledger-entry.aggregate.ts
|
||
|
||
实现 `LedgerEntry` 聚合根 (append-only)，包含：
|
||
- 流水类型
|
||
- 金额变动
|
||
- 余额快照
|
||
- 关联引用
|
||
|
||
### 3.3 仓储接口 (Repository Interfaces)
|
||
|
||
#### 3.3.1 wallet-account.repository.interface.ts
|
||
```typescript
|
||
export interface IWalletAccountRepository {
|
||
save(wallet: WalletAccount): Promise<void>;
|
||
findById(walletId: bigint): Promise<WalletAccount | null>;
|
||
findByUserId(userId: bigint): Promise<WalletAccount | null>;
|
||
getOrCreate(userId: bigint): Promise<WalletAccount>;
|
||
findByUserIds(userIds: bigint[]): Promise<Map<string, WalletAccount>>;
|
||
}
|
||
|
||
export const WALLET_ACCOUNT_REPOSITORY = Symbol('IWalletAccountRepository');
|
||
```
|
||
|
||
#### 3.3.2 ledger-entry.repository.interface.ts
|
||
```typescript
|
||
export interface ILedgerEntryRepository {
|
||
save(entry: LedgerEntry): Promise<void>;
|
||
saveAll(entries: LedgerEntry[]): Promise<void>;
|
||
findByUserId(userId: bigint, filters?: LedgerFilters, pagination?: Pagination): Promise<LedgerEntry[]>;
|
||
findByRefOrderId(refOrderId: string): Promise<LedgerEntry[]>;
|
||
}
|
||
|
||
export const LEDGER_ENTRY_REPOSITORY = Symbol('ILedgerEntryRepository');
|
||
```
|
||
|
||
---
|
||
|
||
## 第四阶段：基础设施层实现
|
||
|
||
### 4.1 实体映射 (Entities)
|
||
|
||
创建 Prisma 实体到领域模型的映射类。
|
||
|
||
### 4.2 仓储实现 (Repository Implementations)
|
||
|
||
实现所有仓储接口，使用 Prisma Client 进行数据库操作。
|
||
|
||
---
|
||
|
||
## 第五阶段：应用层实现
|
||
|
||
### 5.1 命令对象 (Commands)
|
||
|
||
```typescript
|
||
// handle-deposit.command.ts
|
||
export class HandleDepositCommand {
|
||
constructor(
|
||
public readonly userId: string,
|
||
public readonly amount: number,
|
||
public readonly chainType: ChainType,
|
||
public readonly txHash: string,
|
||
) {}
|
||
}
|
||
|
||
// deduct-for-planting.command.ts
|
||
export class DeductForPlantingCommand {
|
||
constructor(
|
||
public readonly userId: string,
|
||
public readonly amount: number,
|
||
public readonly orderId: string,
|
||
) {}
|
||
}
|
||
```
|
||
|
||
### 5.2 应用服务 (Application Service)
|
||
|
||
实现 `WalletApplicationService`，包含所有用例：
|
||
- handleDeposit - 处理充值
|
||
- deductForPlanting - 认种扣款
|
||
- allocateFunds - 资金分配
|
||
- addRewards - 增加奖励
|
||
- movePendingToSettleable - 待领取→可结算
|
||
- settleRewards - 结算收益
|
||
- getMyWallet - 查询我的钱包
|
||
- getMyLedger - 查询我的流水
|
||
|
||
---
|
||
|
||
## 第六阶段：API层实现
|
||
|
||
### 6.1 DTO 定义
|
||
|
||
```typescript
|
||
// wallet.dto.ts
|
||
export class WalletDTO {
|
||
walletId: string;
|
||
userId: string;
|
||
balances: BalancesDTO;
|
||
rewards: RewardsDTO;
|
||
status: string;
|
||
}
|
||
|
||
export class BalancesDTO {
|
||
usdt: BalanceDTO;
|
||
dst: BalanceDTO;
|
||
bnb: BalanceDTO;
|
||
og: BalanceDTO;
|
||
rwad: BalanceDTO;
|
||
hashpower: number;
|
||
}
|
||
|
||
export class BalanceDTO {
|
||
available: number;
|
||
frozen: number;
|
||
}
|
||
```
|
||
|
||
### 6.2 控制器实现
|
||
|
||
```typescript
|
||
// wallet.controller.ts
|
||
@Controller('wallet')
|
||
export class WalletController {
|
||
constructor(private readonly walletService: WalletApplicationService) {}
|
||
|
||
@Get('my-wallet')
|
||
@UseGuards(JwtAuthGuard)
|
||
async getMyWallet(@CurrentUser() user: User): Promise<WalletDTO> {
|
||
return this.walletService.getMyWallet({ userId: user.id });
|
||
}
|
||
}
|
||
|
||
// ledger.controller.ts
|
||
@Controller('wallet/ledger')
|
||
export class LedgerController {
|
||
constructor(private readonly walletService: WalletApplicationService) {}
|
||
|
||
@Get('my-ledger')
|
||
@UseGuards(JwtAuthGuard)
|
||
async getMyLedger(
|
||
@CurrentUser() user: User,
|
||
@Query() query: GetMyLedgerQueryDTO,
|
||
): Promise<LedgerEntryDTO[]> {
|
||
return this.walletService.getMyLedger({
|
||
userId: user.id,
|
||
...query,
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 第七阶段：模块配置
|
||
|
||
### 7.1 app.module.ts
|
||
|
||
```typescript
|
||
@Module({
|
||
imports: [
|
||
ConfigModule.forRoot({
|
||
isGlobal: true,
|
||
envFilePath: `.env.${process.env.NODE_ENV || 'development'}`,
|
||
}),
|
||
ApiModule,
|
||
InfrastructureModule,
|
||
],
|
||
})
|
||
export class AppModule {}
|
||
```
|
||
|
||
---
|
||
|
||
## 关键业务规则 (不变式)
|
||
|
||
1. **余额不能为负**: 任何币种的可用余额不能为负数
|
||
2. **流水表只能追加**: 账本流水表只能 INSERT，不能 UPDATE/DELETE
|
||
3. **每笔流水必须有余额快照**: 每笔流水必须记录操作后的余额快照
|
||
4. **结算金额不能超过可结算余额**: 结算金额必须 ≤ 可结算余额
|
||
|
||
---
|
||
|
||
## API 端点汇总
|
||
|
||
| 方法 | 路径 | 描述 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | /wallet/my-wallet | 查询我的钱包 | 需要 |
|
||
| GET | /wallet/ledger/my-ledger | 查询我的流水 | 需要 |
|
||
| POST | /wallet/deposit | 充值入账 (内部) | 服务间 |
|
||
| POST | /wallet/withdraw | 提现申请 | 需要 |
|
||
| POST | /wallet/settle | 结算收益 | 需要 |
|
||
|
||
---
|
||
|
||
## 开发顺序建议
|
||
|
||
1. 项目初始化和 Prisma Schema
|
||
2. 值对象实现
|
||
3. 聚合根实现
|
||
4. 仓储接口定义
|
||
5. 仓储实现
|
||
6. 领域服务实现
|
||
7. 应用服务实现
|
||
8. DTO 和控制器实现
|
||
9. 模块配置和测试
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. 所有金额使用 `Decimal(20, 8)` 存储，避免浮点数精度问题
|
||
2. 流水表是 append-only，不允许更新或删除
|
||
3. 每次余额变动都要创建对应的流水记录
|
||
4. 使用事务确保余额和流水的一致性
|
||
5. 参考 identity-service 的代码风格和命名规范
|