# 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

```bash
# 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

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

### 2. Chạy với Docker

```bash
cd deployments/local
docker-compose up promotion-service -d
```

### 3. Chạy Local

```bash
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

```yaml
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

```yaml
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

```yaml
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

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

## Testing

```bash
# 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

```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

```bash
# 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

```bash
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](./ARCHITECTURE.md)
- [Wallet Service](../../../wallet-service-net/docs/vi/README.md)
- [Merchant Service](../../../merchant-service-net/docs/vi/README.md)

## Giấy Phép

Proprietary - GoodGo Platform
