pos-system/services/wallet-service-net/docs/vi

Wallet Service .NET

EN: Wallet and Point Account management service for GoodGo Platform.
VI: Dịch vụ quản lý Ví và Tài khoản Điểm cho GoodGo Platform.

Tổng Quan

Wallet Service cung cấp quản lý ví và điểm thưởng toàn diện:

• Quản Lý Ví - Tạo, nạp tiền, rút tiền, chuyển khoản
• Escrow Module - Ký quỹ, cam kết và giải phóng tiền (cho Promotion Service)
• Tài Khoản Điểm - Tích, tiêu và theo dõi điểm thưởng
• Lịch Sử Giao Dịch - Audit trail đầy đủ các giao dịch
• Hỗ Trợ Đa Tiền Tệ - Mặc định VND với hỗ trợ đa tiền tệ
• Domain-Driven Design - Clean Architecture với CQRS pattern

Tech Stack

Thành Phần	Công Nghệ
Framework	.NET 10
Database	PostgreSQL (EF Core)
CQRS	MediatR
Validation	FluentValidation
API Docs	Swagger/OpenAPI
Logging	Serilog

Yêu Cầu Hệ Thống

# Kiểm tra phiên bản .NET
dotnet --version  # Phải là 10.0.x

Bắt Đầu Nhanh

1. Cấu Hình Môi Trường

cp .env.example .env
# Chỉnh sửa .env với connection database của bạn

2. Chạy với Docker

cd deployments/local
docker-compose up wallet-service -d

3. Chạy Local

cd services/wallet-service-net
dotnet restore
dotnet build
dotnet run --project src/WalletService.API

API Endpoints

Wallet APIs

Method	Endpoint	Mô Tả
POST	/api/v1/wallets	Tạo ví mới
GET	/api/v1/wallets/me	Lấy ví của người dùng hiện tại
GET	/api/v1/wallets/{id}	Lấy ví theo ID
POST	/api/v1/wallets/deposit	Nạp tiền vào ví
POST	/api/v1/wallets/withdraw	Rút tiền từ ví
POST	/api/v1/wallets/transfer	Chuyển tiền giữa các ví
POST	/api/v1/wallets/{id}/freeze	Đóng băng ví
POST	/api/v1/wallets/{id}/unfreeze	Mở đóng băng ví
GET	/api/v1/wallets/transactions	Lấy lịch sử giao dịch

Escrow APIs (New)

Method	Endpoint	Mô Tả
POST	/api/v1/wallets/{walletId}/holds	Tạo lệnh giữ tiền (Hold)
POST	/api/v1/wallets/{walletId}/holds/{holdId}/execute	Thực thi lệnh giữ tiền (trừ tiền thực)
POST	/api/v1/wallets/{walletId}/holds/{holdId}/release	Giải phóng tiền giữ (trả lại ví)
POST	/api/v1/wallets/{walletId}/holds/{holdId}/cancel	Hủy lệnh giữ tiền
GET	/api/v1/wallets/{walletId}/holds/{holdId}	Lấy thông tin lệnh giữ tiền

Points APIs

Method	Endpoint	Mô Tả
GET	/api/v1/points/me	Lấy điểm của người dùng
POST	/api/v1/points/earn	Tích điểm
POST	/api/v1/points/spend	Tiêu điểm
GET	/api/v1/points/transactions	Lấy lịch sử điểm

Health Endpoints

Endpoint	Mục Đích
/health	Trạng thái sức khỏe đầy đủ
/health/live	Liveness probe (K8s)
/health/ready	Readiness probe (K8s)

Cấu Trúc Dự Án

wallet-service-net/
├── src/
│   ├── WalletService.API/           # API Layer
│   │   ├── Controllers/             # REST endpoints
│   │   └── Application/             # Commands & Queries
│   │       ├── Commands/            # Thao tác ghi
│   │       └── Queries/             # Thao tác đọc
│   │
│   ├── WalletService.Domain/        # Domain Layer 
│   │   ├── AggregatesModel/
│   │   │   ├── WalletAggregate/     # Wallet, Transaction, Money
│   │   │   └── PointAccountAggregate/  # Points, PointTransaction
│   │   ├── Events/                  # Domain events
│   │   └── Exceptions/              # Domain exceptions
│   │
│   └── WalletService.Infrastructure/  # Infrastructure Layer
│       ├── EntityConfigurations/    # EF Core mappings
│       ├── Repositories/            # Data access
│       └── WalletServiceContext.cs  # DbContext
│
├── tests/
│   ├── WalletService.UnitTests/     # Domain & Logic tests
│   └── WalletService.FunctionalTests/  # API integration tests
│
├── docs/
│   ├── en/                          # Tài liệu tiếng Anh
│   └── vi/                          # Tài liệu tiếng Việt
│
└── Dockerfile

Domain Model

Wallet Aggregate

// Tạo ví
var wallet = new Wallet(userId, "VND");

// Nạp tiền
wallet.Deposit(new Money(1000000m, "VND"), "Lương", "REF001");

// Rút tiền  
wallet.Withdraw(new Money(500000m, "VND"), "Mua sắm", "REF002");

// Đóng băng/Mở đóng băng
wallet.Freeze();
wallet.Unfreeze();

// Escrow / Ký Quỹ
var hold = wallet.Hold(100000m, CurrencyType.VND, "CAMPAIGN", campaignId, "Hold for campaign");
wallet.ExecuteHold(hold.Id, 50000m, "ORDER123"); // Thực thi 50k
wallet.ReleaseHold(hold.Id, 50000m); // Trả lại 50k
wallet.CancelHold(hold.Id); // Hủy phần còn lại

Point Account Aggregate

// Tạo tài khoản điểm
var account = new PointAccount(userId);

// Tích điểm
account.EarnPoints(100, "ORDER001", "Thưởng mua hàng", expiresAt);

// Tiêu điểm
account.SpendPoints(50, "ORDER002", "Đổi giảm giá");

// Điều chỉnh điểm (admin)
account.AdjustPoints(10, "ADMIN", "Điều chỉnh thưởng");

Testing

# Chạy tất cả tests
dotnet test

# Chạy với coverage
dotnet test /p:CollectCoverage=true

# Chỉ unit tests
dotnet test tests/WalletService.UnitTests

# Chỉ functional tests
dotnet test tests/WalletService.FunctionalTests

Kết Quả Test

• 23 tests tổng cộng
• 20 unit tests (Wallet, PointAccount domain)
• 3 functional tests (Health endpoints)

Cấu Hình

Biến Môi Trường

Biến	Mô Tả	Bắt Buộc
DATABASE_URL	Connection PostgreSQL	Có
ASPNETCORE_ENVIRONMENT	Môi trường	Không (mặc định: Development)
JWT_AUTHORITY	URL JWT issuer	Có (cho auth)

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=wallet_db;Username=postgres;Password=postgres"
  },
  "Jwt": {
    "Authority": "http://localhost:5001",
    "Issuer": "http://localhost:5001"
  }
}

Database Migrations

# Tạo migration
dotnet ef migrations add InitialCreate \
  --project src/WalletService.Infrastructure \
  --startup-project src/WalletService.API

# Áp dụng migration
dotnet ef database update \
  --project src/WalletService.Infrastructure \
  --startup-project src/WalletService.API

Triển Khai

Docker Build

docker build -t goodgo/wallet-service:latest .

Docker Compose

Service được đăng ký trong deployments/local/docker-compose.yml với Traefik routing.

Tài Nguyên

• Tài liệu Kiến trúc
• Tài liệu GoodGo Platform
• eShopOnContainers Reference

Giấy Phép

Proprietary - GoodGo Platform