pos-system/services/merchant-service-net/README.md

Merchant Service .NET 10

Merchant & Shop Management Service for GoodGo Platform

Overview

Merchant Service manages Shop Owners (Merchants), Shops, and Staff for the GoodGo ecosystem. It supports online stores, physical stores, and hybrid business models.

Key Features

• 🏪 Shop Management - Create and manage shops (Online/Physical/Hybrid)
• 👥 Staff Management - Employee management with role-based permissions
• 💳 POS Support - PIN authentication for Point-of-Sale systems
• 📍 Branch Management - Multi-location support with geo-search
• 🔐 Role-based Access - Merchant, MerchantStaff, MerchantAdmin roles
• 🔗 Service Integration - IAM, Wallet, Membership, Chat services

Quick Start

# Clone and navigate
cd services/merchant-service-net

# Restore and build
dotnet restore
dotnet build

# Run
dotnet run --project src/MerchantService.API

Documentation

Language	README	Architecture
🇻🇳 Tiếng Việt	docs/vi/README.md	docs/vi/ARCHITECTURE.md
🇬🇧 English	docs/en/README.md	docs/en/ARCHITECTURE.md

API Endpoints

Resource	Base Path	Description
Merchants	/api/v1/merchants	Merchant registration & management
Shops	/api/v1/shops	Shop CRUD operations
Branches	/api/v1/shops/{id}/branches	Physical shop locations
Staff	/api/v1/merchants/me/staff	Staff management
POS	/api/v1/pos	POS device authentication
Admin Merchants	/api/v1/admin/merchants	Merchant admin operations
Admin Shops	/api/v1/admin/shops	Shop admin operations

Admin Endpoints (Backoffice)

Method	Endpoint	Description
GET	/api/v1/admin/merchants	List all merchants (paginated)
GET	/api/v1/admin/merchants/{id}	Get merchant details
GET	/api/v1/admin/merchants/statistics	Get platform statistics
POST	/api/v1/admin/merchants/{id}/approve	Approve merchant registration
POST	/api/v1/admin/merchants/{id}/reject	Reject merchant registration
POST	/api/v1/admin/merchants/{id}/suspend	Suspend active merchant
POST	/api/v1/admin/merchants/{id}/reactivate	Reactivate suspended merchant
POST	/api/v1/admin/merchants/{id}/ban	Permanently ban merchant
GET	/api/v1/admin/shops	List all shops (paginated)
GET	/api/v1/admin/shops/{id}	Get shop details
POST	/api/v1/admin/shops/{id}/suspend	Suspend shop
POST	/api/v1/admin/shops/{id}/reactivate	Reactivate shop
POST	/api/v1/admin/shops/{id}/close	Close shop permanently

Project Structure

merchant-service-net/
├── src/
│   ├── MerchantService.API/           # Controllers, Commands, Queries
│   ├── MerchantService.Domain/        # Entities, Value Objects, Events
│   └── MerchantService.Infrastructure/# DbContext, Repositories
├── tests/
│   ├── MerchantService.UnitTests/
│   └── MerchantService.FunctionalTests/
├── docs/
│   ├── en/                            # English documentation
│   └── vi/                            # Vietnamese documentation
├── Dockerfile
└── MerchantService.slnx

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	✅
Jwt__Authority	IAM Service URL	✅
IamService__BaseUrl	IAM Service base URL	✅
WalletService__BaseUrl	Wallet Service base URL	❌

Docker

# Build
docker build -t goodgo/merchant-service:latest .

# Run
docker run -p 5003:8080 \
  -e DATABASE_URL="Host=db;Port=5432;Database=merchant;..." \
  -e Jwt__Authority="http://iam-service:8080" \
  goodgo/merchant-service:latest

Testing

# Unit tests
dotnet test tests/MerchantService.UnitTests

# Integration tests
dotnet test tests/MerchantService.FunctionalTests

License

This project is part of the GoodGo Platform.