# Merchant Service .NET 10

> **Service quản lý Merchant (Shop Owner), Shop, và Merchant Staff cho hệ sinh thái GoodGo.**

## Tổng Quan

Merchant Service cung cấp các chức năng quản lý:

- **Merchant Management** - Đăng ký, xác minh, quản lý Merchant (Shop Owner)
- **Shop Management** - Tạo và quản lý cửa hàng (Online, Cửa hàng vật lý, Hybrid)
- **Staff Management** - Quản lý nhân viên, phân quyền cho POS System
- **Branch Management** - Quản lý chi nhánh cửa hàng
- **POS Authentication** - Xác thực PIN cho thiết bị POS
- **Multi-category Support** - Hỗ trợ đa ngành nghề kinh doanh

## Yêu Cầu

| Yêu cầu | Phiên bản |
|---------|-----------|
| .NET SDK | 10.0.101+ |
| Docker | 24.0+ |
| PostgreSQL | 15+ |

## Bắt Đầu Nhanh

### Chạy với Docker

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

### Chạy Local

```bash
cd services/merchant-service-net
dotnet restore
dotnet build
dotnet run --project src/MerchantService.API
```

## Database Migrations

### Yêu Cầu

```bash
# Cài đặt EF Core tools (một lần)
dotnet tool install --global dotnet-ef
```

### Tạo Migration

```bash
# Tạo migration mới
dotnet ef migrations add <TenMigration> \
  --project src/MerchantService.Infrastructure \
  --startup-project src/MerchantService.API
```

### Áp Dụng Migration

```bash
# Áp dụng migrations vào database
dotnet ef database update \
  --project src/MerchantService.Infrastructure \
  --startup-project src/MerchantService.API
```

## API Endpoints

### Merchant Endpoints (`/api/v1/merchants`)

| Method | Endpoint | Mô Tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/merchants/register` | Đăng ký trở thành Merchant | ✅ User |
| `GET` | `/api/v1/merchants/me` | Lấy thông tin Merchant hiện tại | ✅ Merchant |
| `PUT` | `/api/v1/merchants/me` | Cập nhật thông tin Merchant | ✅ Merchant |
| `POST` | `/api/v1/merchants/me/verify` | Submit verification documents | ✅ Merchant |

### Shop Endpoints (`/api/v1/shops`)

| Method | Endpoint | Mô Tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/shops` | Danh sách Shop của Merchant | ✅ Merchant |
| `POST` | `/api/v1/shops` | Tạo Shop mới | ✅ Merchant |
| `GET` | `/api/v1/shops/{id}` | Lấy Shop theo ID | ✅ Merchant |
| `PUT` | `/api/v1/shops/{id}` | Cập nhật Shop | ✅ Merchant |
| `DELETE` | `/api/v1/shops/{id}` | Đóng Shop | ✅ Merchant |
| `POST` | `/api/v1/shops/{id}/publish` | Công khai Shop (hiển thị với khách hàng) | ✅ Merchant |
| `POST` | `/api/v1/shops/{id}/deactivate` | Đặt Shop thành không hoạt động | ✅ Merchant |
| `GET` | `/api/v1/shops/slug/{slug}` | Lấy Shop theo slug (public) | ❌ |

### Shop Branch Endpoints

| Method | Endpoint | Mô Tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/shops/{shopId}/branches` | Danh sách chi nhánh | ✅ |
| `POST` | `/api/v1/shops/{shopId}/branches` | Tạo chi nhánh mới | ✅ Merchant |
| `PUT` | `/api/v1/shops/{shopId}/branches/{id}` | Cập nhật chi nhánh | ✅ Merchant |
| `DELETE` | `/api/v1/shops/{shopId}/branches/{id}` | Xóa chi nhánh | ✅ Merchant |
| `GET` | `/api/v1/shops/nearby` | Tìm cửa hàng gần đây | ❌ |

### Merchant Staff Endpoints

| Method | Endpoint | Mô Tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/merchants/me/staff` | Danh sách nhân viên | ✅ Merchant |
| `POST` | `/api/v1/merchants/me/staff/invite` | Mời nhân viên | ✅ Merchant |
| `PUT` | `/api/v1/merchants/me/staff/{id}` | Cập nhật nhân viên | ✅ Merchant |
| `DELETE` | `/api/v1/merchants/me/staff/{id}` | Xóa nhân viên | ✅ Merchant |
| `POST` | `/api/v1/staff/accept-invite` | Chấp nhận lời mời | ✅ User |

### POS Endpoints (`/api/v1/pos`)

| Method | Endpoint | Mô Tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/pos/auth/pin` | Đăng nhập POS bằng PIN | ✅ Staff |
| `POST` | `/api/v1/pos/devices/register` | Đăng ký thiết bị POS | ✅ Staff |
| `GET` | `/api/v1/pos/me` | Thông tin Staff hiện tại | ✅ Staff |

### Admin Merchant Endpoints (`/api/v1/admin/merchants`)

| Method | Endpoint | Mô Tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/admin/merchants` | Danh sách tất cả Merchants (phân trang) | ✅ Admin |
| `GET` | `/api/v1/admin/merchants/statistics` | Thống kê Merchants | ✅ Admin |
| `GET` | `/api/v1/admin/merchants/{id}` | Chi tiết Merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/approve` | Phê duyệt Merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/reject` | Từ chối Merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/suspend` | Tạm ngưng Merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/reactivate` | Kích hoạt lại Merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/ban` | Cấm vĩnh viễn Merchant | ✅ Admin |

### Admin Shop Endpoints (`/api/v1/admin/shops`)

| Method | Endpoint | Mô Tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/admin/shops` | Danh sách tất cả Shops (phân trang) | ✅ Admin |
| `GET` | `/api/v1/admin/shops/{id}` | Chi tiết Shop | ✅ Admin |
| `POST` | `/api/v1/admin/shops/{id}/suspend` | Tạm ngưng Shop | ✅ Admin |
| `POST` | `/api/v1/admin/shops/{id}/reactivate` | Kích hoạt lại Shop | ✅ Admin |
| `POST` | `/api/v1/admin/shops/{id}/close` | Đóng Shop vĩnh viễn | ✅ Admin |


### Health Checks

| Endpoint | Mục Đích |
|----------|----------|
| `/health` | Trạng thái health đầy đủ |
| `/health/live` | Kiểm tra sống |
| `/health/ready` | Kiểm tra sẵn sàng |

## Quy Trình Đăng Ký Merchant

### Bước 1: Đăng Ký Trở Thành Merchant

```bash
curl -X POST http://localhost:5003/api/v1/merchants/register \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Cà Phê Sài Gòn",
    "type": "Company",
    "taxId": "0123456789",
    "businessLicenseNumber": "BL-2024-001"
  }'
```

**Response:**
```json
{
  "success": true,
  "data": {
    "merchantId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Cà Phê Sài Gòn",
    "status": "PendingApproval"
  }
}
```

### Bước 2: Chờ Admin Phê Duyệt

Admin sẽ review và phê duyệt Merchant. Sau khi được phê duyệt:
- Role `Merchant` sẽ được gán cho user trong IAM Service
- Status chuyển thành `Active`

### Bước 3: Tạo Shop

```bash
curl -X POST http://localhost:5003/api/v1/shops \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cà Phê Sài Gòn - Quận 1",
    "slug": "ca-phe-sai-gon-q1",
    "type": "Hybrid",
    "category": "FoodBeverage",
    "phone": "0901234567",
    "email": "q1@caphesaigon.vn"
  }'
```

### Bước 4: Thêm Chi Nhánh (Cho cửa hàng vật lý)

```bash
curl -X POST http://localhost:5003/api/v1/shops/{shopId}/branches \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chi Nhánh Lê Lợi",
    "street": "123 Lê Lợi",
    "district": "Quận 1",
    "city": "TP. Hồ Chí Minh",
    "latitude": 10.7769,
    "longitude": 106.7009
  }'
```

### Bước 5: Mời Nhân Viên

```bash
curl -X POST http://localhost:5003/api/v1/merchants/me/staff/invite \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "nhanvien@example.com",
    "role": "Cashier",
    "shopId": "shop-uuid",
    "branchId": "branch-uuid"
  }'
```

## Cấu Hình

### Biến Môi Trường

| Biến | Mô Tả | Mặc định |
|------|-------|----------|
| `ASPNETCORE_ENVIRONMENT` | Môi trường | `Development` |
| `DATABASE_URL` | PostgreSQL connection | - |
| `Jwt__Authority` | IAM Service URL | `http://iam-service-net:8080` |
| `IamService__BaseUrl` | IAM Service base URL | - |
| `WalletService__BaseUrl` | Wallet Service base URL | - |

### appsettings.json

```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=merchant;Username=postgres;Password=postgres"
  },
  "Jwt": {
    "Authority": "http://localhost:5001"
  },
  "IamService": {
    "BaseUrl": "http://localhost:5001"
  },
  "WalletService": {
    "BaseUrl": "http://localhost:5004"
  }
}
```

## Integration với Các Services Khác

### IAM Service
- Validate User token
- Assign Merchant/MerchantStaff roles
- Get Organization hierarchy

### Wallet Service
- Merchant settlement
- Commission calculation
- Balance check

### Membership Service
- Customer visit tracking → Add EXP
- Member level → Special discount at shop

### Chat Service
- Shop support channel
- Staff-Customer conversation

### Gift Voucher Service (Planned)
- Create voucher campaigns
- Voucher redemption at shop

## Kiểm Thử

```bash
# Unit tests
dotnet test tests/MerchantService.UnitTests

# Functional tests
dotnet test tests/MerchantService.FunctionalTests
```

## Triển Khai

### Docker Build

```bash
docker build -t goodgo/merchant-service:latest .
docker run -p 5003:8080 --env-file .env goodgo/merchant-service:latest
```

### Kubernetes

Xem file `deployments/kubernetes/merchant-service.yaml`

## Swagger UI

Sau khi chạy service, truy cập Swagger UI tại:
- **Local**: http://localhost:5003/swagger
- **Docker**: http://localhost/api/v1/merchants/swagger

## Tài Nguyên

- [Clean Architecture Documentation](../../docs/vi/architecture/)
- [API Design Skill](../../.agent/skills/api-design/SKILL.md)
- [CQRS Pattern Skill](../../.agent/skills/cqrs-mediatr/SKILL.md)
