# Merchant Service .NET 10

> **Service for managing Merchants (Shop Owners), Shops, and Merchant Staff for the GoodGo ecosystem.**

## Overview

Merchant Service provides management capabilities for:

- **Merchant Management** - Registration, verification, merchant (shop owner) management
- **Shop Management** - Create and manage stores (Online, Physical, Hybrid)
- **Staff Management** - Employee management, permissions for POS System
- **Branch Management** - Shop branch/location management
- **POS Authentication** - PIN authentication for POS devices
- **Multi-category Support** - Support for multiple business categories

## Requirements

| Requirement | Version |
|-------------|---------|
| .NET SDK | 10.0.101+ |
| Docker | 24.0+ |
| PostgreSQL | 15+ |

## Quick Start

### Run with Docker

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

### Run Local

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

## Database Migrations

### Requirements

```bash
# Install EF Core tools (one-time)
dotnet tool install --global dotnet-ef
```

### Create Migration

```bash
# Create new migration
dotnet ef migrations add <MigrationName> \
  --project src/MerchantService.Infrastructure \
  --startup-project src/MerchantService.API
```

### Apply Migration

```bash
# Apply migrations to database
dotnet ef database update \
  --project src/MerchantService.Infrastructure \
  --startup-project src/MerchantService.API
```

## API Endpoints

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

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| `POST` | `/api/v1/merchants/register` | Register as a Merchant | ✅ User |
| `GET` | `/api/v1/merchants/me` | Get current Merchant info | ✅ Merchant |
| `PUT` | `/api/v1/merchants/me` | Update Merchant info | ✅ Merchant |
| `POST` | `/api/v1/merchants/me/verify` | Submit verification documents | ✅ Merchant |

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

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| `GET` | `/api/v1/shops` | List Merchant's shops | ✅ Merchant |
| `POST` | `/api/v1/shops` | Create new shop | ✅ Merchant |
| `GET` | `/api/v1/shops/{id}` | Get shop by ID | ✅ Merchant |
| `PUT` | `/api/v1/shops/{id}` | Update shop | ✅ Merchant |
| `DELETE` | `/api/v1/shops/{id}` | Close shop | ✅ Merchant |
| `POST` | `/api/v1/shops/{id}/publish` | Publish shop (visible to customers) | ✅ Merchant |
| `POST` | `/api/v1/shops/{id}/deactivate` | Set shop inactive | ✅ Merchant |
| `GET` | `/api/v1/shops/slug/{slug}` | Get shop by slug (public) | ❌ |

### Shop Branch Endpoints

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| `GET` | `/api/v1/shops/{shopId}/branches` | List branches | ✅ |
| `POST` | `/api/v1/shops/{shopId}/branches` | Create new branch | ✅ Merchant |
| `PUT` | `/api/v1/shops/{shopId}/branches/{id}` | Update branch | ✅ Merchant |
| `DELETE` | `/api/v1/shops/{shopId}/branches/{id}` | Delete branch | ✅ Merchant |
| `GET` | `/api/v1/shops/nearby` | Find nearby shops | ❌ |

### Merchant Staff Endpoints

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| `GET` | `/api/v1/merchants/me/staff` | List staff | ✅ Merchant |
| `POST` | `/api/v1/merchants/me/staff/invite` | Invite staff | ✅ Merchant |
| `PUT` | `/api/v1/merchants/me/staff/{id}` | Update staff | ✅ Merchant |
| `DELETE` | `/api/v1/merchants/me/staff/{id}` | Remove staff | ✅ Merchant |
| `POST` | `/api/v1/staff/accept-invite` | Accept invitation | ✅ User |

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

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| `POST` | `/api/v1/pos/auth/pin` | POS login with PIN | ✅ Staff |
| `POST` | `/api/v1/pos/devices/register` | Register POS device | ✅ Staff |
| `GET` | `/api/v1/pos/me` | Get current Staff info | ✅ Staff |

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

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| `GET` | `/api/v1/admin/merchants` | List all merchants (paginated) | ✅ Admin |
| `GET` | `/api/v1/admin/merchants/statistics` | Merchant statistics | ✅ Admin |
| `GET` | `/api/v1/admin/merchants/{id}` | Merchant details | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/approve` | Approve merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/reject` | Reject merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/suspend` | Suspend merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/reactivate` | Reactivate merchant | ✅ Admin |
| `POST` | `/api/v1/admin/merchants/{id}/ban` | Permanently ban merchant | ✅ Admin |

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

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| `GET` | `/api/v1/admin/shops` | List all shops (paginated) | ✅ Admin |
| `GET` | `/api/v1/admin/shops/{id}` | Shop details | ✅ Admin |
| `POST` | `/api/v1/admin/shops/{id}/suspend` | Suspend shop | ✅ Admin |
| `POST` | `/api/v1/admin/shops/{id}/reactivate` | Reactivate shop | ✅ Admin |
| `POST` | `/api/v1/admin/shops/{id}/close` | Permanently close shop | ✅ Admin |


### Health Checks

| Endpoint | Purpose |
|----------|---------|
| `/health` | Full health status |
| `/health/live` | Liveness check |
| `/health/ready` | Readiness check |

## Merchant Registration Flow

### Step 1: Register as 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": "Saigon Coffee",
    "type": "Company",
    "taxId": "0123456789",
    "businessLicenseNumber": "BL-2024-001"
  }'
```

**Response:**
```json
{
  "success": true,
  "data": {
    "merchantId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Saigon Coffee",
    "status": "PendingApproval"
  }
}
```

### Step 2: Wait for Admin Approval

Admin will review and approve the merchant. After approval:
- Role `Merchant` will be assigned to the user in IAM Service
- Status changes to `Active`

### Step 3: Create Shop

```bash
curl -X POST http://localhost:5003/api/v1/shops \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Saigon Coffee - District 1",
    "slug": "saigon-coffee-d1",
    "type": "Hybrid",
    "category": "FoodBeverage",
    "phone": "0901234567",
    "email": "d1@saigoncoffee.vn"
  }'
```

### Step 4: Add Branch (For physical stores)

```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": "Le Loi Branch",
    "street": "123 Le Loi Street",
    "district": "District 1",
    "city": "Ho Chi Minh City",
    "latitude": 10.7769,
    "longitude": 106.7009
  }'
```

### Step 5: Invite Staff

```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": "staff@example.com",
    "role": "Cashier",
    "shopId": "shop-uuid",
    "branchId": "branch-uuid"
  }'
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ASPNETCORE_ENVIRONMENT` | Environment | `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 with Other Services

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

## Testing

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

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

## Deployment

### Docker Build

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

### Kubernetes

See `deployments/kubernetes/merchant-service.yaml`

## Swagger UI

After running the service, access Swagger UI at:
- **Local**: http://localhost:5003/swagger
- **Docker**: http://localhost/api/v1/merchants/swagger

## Resources

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