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

Promotion Service .NET

EN: Campaign, Voucher and Gift Card management service for GoodGo Platform.
VI: Dịch vụ quản lý Chiến dịch, Voucher và Gift Card cho GoodGo Platform.

Tổng Quan

Promotion Service quản lý chiến dịch khuyến mãi với Voucher và Gift Card:

• Campaign Management - Tạo, quản lý chiến dịch theo nhiều mô hình
• Voucher/Gift Card - Sinh mã, phân phối, sử dụng và hết hạn
• Unified Asset Model - Hỗ trợ cả Currency và Point làm tài sản đảm bảo
• Escrow Integration - Tích hợp ký quỹ với Wallet Service
• Refund Surplus - Cơ chế hoàn tiền dư về Merchant

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
Message Bus	RabbitMQ (Events)

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 promotion-service -d

3. Chạy Local

cd services/promotion-service-net
dotnet restore
dotnet build
dotnet run --project src/PromotionService.API

API Endpoints

Campaign APIs (Merchant)

Method	Endpoint	Mô Tả
POST	/api/v1/campaigns	Tạo chiến dịch mới
GET	/api/v1/campaigns	Danh sách campaigns của merchant
GET	/api/v1/campaigns/{id}	Chi tiết campaign
PUT	/api/v1/campaigns/{id}	Cập nhật campaign
POST	/api/v1/campaigns/{id}/activate	Kích hoạt campaign
POST	/api/v1/campaigns/{id}/pause	Tạm dừng campaign
POST	/api/v1/campaigns/{id}/cancel	Hủy campaign (hoàn escrow)

Voucher APIs (User)

Method	Endpoint	Mô Tả
POST	/api/v1/vouchers/claim	Nhận voucher miễn phí
POST	/api/v1/vouchers/exchange	Đổi points lấy voucher
POST	/api/v1/vouchers/purchase	Mua gift card
GET	/api/v1/vouchers/validate/{code}	Kiểm tra mã voucher
POST	/api/v1/vouchers/redeem	Sử dụng voucher
GET	/api/v1/users/{userId}/vouchers	Vouchers của user

Admin APIs

Method	Endpoint	Mô Tả
GET	/api/v1/admin/campaigns	Tất cả campaigns
GET	/api/v1/admin/campaigns/{id}/statistics	Thống kê campaign
POST	/api/v1/admin/vouchers/{id}/revoke	Thu hồi voucher

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

promotion-service-net/
├── src/
│   ├── PromotionService.API/           # API Layer
│   │   ├── Controllers/                # REST endpoints
│   │   └── Application/                # Commands & Queries
│   │       ├── Commands/               # Thao tác ghi
│   │       ├── Queries/                # Thao tác đọc
│   │       └── IntegrationEvents/      # Event handlers
│   │
│   ├── PromotionService.Domain/        # Domain Layer 
│   │   ├── AggregatesModel/
│   │   │   ├── CampaignAggregate/      # Campaign, Voucher
│   │   │   └── RedemptionAggregate/    # Redemption history
│   │   ├── Events/                     # Domain events
│   │   └── Exceptions/                 # Domain exceptions
│   │
│   └── PromotionService.Infrastructure/  # Infrastructure Layer
│       ├── EntityConfigurations/       # EF Core mappings
│       ├── Repositories/               # Data access
│       └── PromotionContext.cs         # DbContext
│
├── tests/
│   ├── PromotionService.UnitTests/     # Domain & Logic tests
│   └── PromotionService.FunctionalTests/  # API integration tests
│
├── docs/
│   ├── en/                             # Tài liệu tiếng Anh
│   └── vi/                             # Tài liệu tiếng Việt
│
└── Dockerfile

4 Kịch Bản Marketing

A. Tặng Free Voucher Tiền mặt

Campaign:
  backing_asset_type: CURRENCY
  backing_asset_code: VND
  face_value: 50000
  acquisition_type: FREE
  acquisition_price: 0

B. Đổi Point lấy Voucher Tiền mặt

Campaign:
  backing_asset_type: CURRENCY
  backing_asset_code: VND
  face_value: 50000
  acquisition_type: EXCHANGE_POINTS
  acquisition_price: 500  # 500 points

C. Mua Gift Card bằng Tiền

Campaign:
  backing_asset_type: CURRENCY
  backing_asset_code: VND
  face_value: 100000
  acquisition_type: PURCHASE
  acquisition_price: 100000  # VND

D. Tặng Voucher tích điểm

Campaign:
  backing_asset_type: POINT
  backing_asset_code: PPoint
  face_value: 100  # 100 points
  acquisition_type: FREE
  acquisition_price: 0

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/PromotionService.UnitTests

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

Cấu Hình

Biến Môi Trường

Biến	Mô Tả	Bắt Buộc
DATABASE_URL	Connection PostgreSQL	Có
WALLET_SERVICE_URL	URL Wallet Service	Có
RABBITMQ_URL	Connection RabbitMQ	Có
JWT_AUTHORITY	URL JWT issuer	Có

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=promotion_db;Username=postgres;Password=postgres"
  },
  "WalletService": {
    "BaseUrl": "http://wallet-service:5000"
  },
  "RabbitMQ": {
    "Host": "localhost",
    "Username": "guest",
    "Password": "guest"
  }
}

Database Migrations

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

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

Triển Khai

Docker Build

docker build -t goodgo/promotion-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
• Wallet Service
• Merchant Service

Giấy Phép

Proprietary - GoodGo Platform