admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dae8aef31f92ea28bd6a283f651cdeeec3ab3040
pos-system/services/merchant-service-net/docs/vi
History

README.md

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

cd deployments/local
docker-compose up -d

Chạy Local

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

Database Migrations

Yêu Cầu

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

Tạo Migration

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

Áp Dụng Migration

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

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:

{
  "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

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ý)

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

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

{
  "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ử

# Unit tests
dotnet test tests/MerchantService.UnitTests

# Functional tests
dotnet test tests/MerchantService.FunctionalTests

Triển Khai

Docker Build

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:

Tài Nguyên

Reference in New Issue View Git Blame Copy Permalink