pos-system/services/wallet-service-net/docs/vi/ARCHITECTURE.md

Kiến Trúc Wallet Service

Tổng Quan

Wallet Service quản lý ví điện tử và tài khoản điểm thưởng cho GoodGo Platform.

┌─────────────────────────────────────────────────────────────┐
│                     Wallet Service                           │
├─────────────────────────────────────────────────────────────┤
│  API Layer (Controllers, CQRS)                               │
├─────────────────────────────────────────────────────────────┤
│  Domain Layer (Wallet, PointAccount Aggregates)             │
├─────────────────────────────────────────────────────────────┤
│  Infrastructure Layer (EF Core, Repositories)               │
├─────────────────────────────────────────────────────────────┤
│  PostgreSQL Database                                         │
└─────────────────────────────────────────────────────────────┘

Các Pattern Kiến Trúc

Domain-Driven Design (DDD)

• Aggregates: Wallet, PointAccount
• Entities: WalletTransaction, PointTransaction
• Value Objects: Money, PointBalance
• Domain Events: WalletCreated, BalanceChanged, PointsEarned

CQRS Pattern

Commands (Ghi)                Queries (Đọc)
    │                             │
    ▼                             ▼
CreateWallet                GetWalletQuery
DepositCommand              GetTransactionsQuery
WithdrawCommand             GetPointAccountQuery
TransferCommand             GetBalanceSummaryQuery
EarnPointsCommand
SpendPointsCommand

Domain Model

Wallet Aggregate

classDiagram
    class Wallet {
        +Guid Id
        +Guid UserId
        +Money Balance
        +WalletStatus Status
        +List~WalletTransaction~ Transactions
        +Deposit(Money, description, ref)
        +Withdraw(Money, description, ref)
        +Freeze()
        +Unfreeze()
        +Close()
    }
    
    class WalletTransaction {
        +Guid Id
        +TransactionType Type
        +Money Amount
        +Money BalanceAfter
        +string Description
        +DateTime CreatedAt
    }
    
    class Money {
        +decimal Amount
        +string Currency
    }
    
    Wallet "1" --> "*" WalletTransaction
    Wallet --> Money

PointAccount Aggregate

classDiagram
    class PointAccount {
        +Guid Id
        +Guid UserId
        +int TotalPoints
        +int AvailablePoints
        +int PendingPoints
        +EarnPoints(points, source, desc, expires)
        +SpendPoints(points, source, desc)
        +AdjustPoints(points, source, desc)
    }
    
    class PointTransaction {
        +Guid Id
        +PointTransactionType Type
        +int Points
        +int BalanceAfter
        +DateTime? ExpiresAt
    }
    
    PointAccount "1" --> "*" PointTransaction

Database Schema

Các Bảng

Bảng	Mô Tả
Wallets	Tài khoản ví người dùng
WalletTransactions	Lịch sử giao dịch ví
PointAccounts	Tài khoản điểm người dùng
PointTransactions	Lịch sử giao dịch điểm

Indexes Chính

• IX_Wallets_UserId - Tra cứu theo user
• IX_WalletTransactions_WalletId - Lịch sử giao dịch
• IX_PointAccounts_UserId - Tra cứu theo user

API Flow

Luồng Nạp Tiền

1. Client → POST /api/v1/wallets/deposit
2. Controller → DepositCommand (MediatR)
3. CommandHandler → Validate số tiền
4. Handler → wallet.Deposit(amount)
5. Domain → Tạo WalletTransaction + Domain Event
6. Infrastructure → Lưu database
7. Response → Số dư cập nhật

Luồng Chuyển Khoản

1. Client → POST /api/v1/wallets/transfer
2. Controller → TransferCommand
3. Handler → Lấy ví nguồn
4. Handler → Lấy ví đích
5. Domain → source.Withdraw() + target.Deposit()
6. Infrastructure → Lưu transactional
7. Response → Xác nhận chuyển khoản

Tích Hợp Giữa Các Service

Tích Hợp IAM Service

Wallet Service ──────► IAM Service
                          │
                          ▼
                    Xác thực User
                    Kiểm tra JWT

Luồng Xác Thực

1. Client gửi JWT token trong Authorization header
2. Wallet Service xác thực JWT với IAM Service
3. Trích xuất userId từ JWT claims
4. Xử lý thao tác ví cho user

Triển Khai

Cấu Hình Docker Compose

wallet-service:
  build:
    context: ../..
    dockerfile: services/wallet-service-net/Dockerfile
  environment:
    - DATABASE_URL=${WALLET_DATABASE_URL}
    - JWT_AUTHORITY=${IAM_SERVICE_URL}
  labels:
    - traefik.http.routers.wallet.rule=PathPrefix(`/api/v1/wallets`)

Health Checks

Endpoint	Kiểm Tra
/health/live	Service đang chạy
/health/ready	Database kết nối
/health	Trạng thái đầy đủ

Bảo Mật

Xác Thực

• Xác thực JWT Bearer token
• Tích hợp IAM Service

Phân Quyền

• User chỉ truy cập được ví của mình
• Admin endpoints cho system operations

Bảo Vệ Dữ Liệu

• Lưu số tiền với độ chính xác cao
• Audit trail giao dịch
• Soft delete cho ví

Hiệu Năng

Tối Ưu

• Connection pooling (EF Core)
• Index cho các queries thường xuyên
• Phân trang cho lịch sử giao dịch

Mở Rộng

• Horizontal scaling với load balancer
• Read replicas cho queries
• Redis caching (tương lai)

Giám Sát

Metrics

• Thời gian request
• Số lượng giao dịch
• Tỷ lệ lỗi

Logging

• Serilog structured logging
• Correlation IDs cho tracing
• Tích hợp Seq/Loki