admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
pos-system/microservices/.claude/LOCAL_DEV_QUICK_REFERENCE.md
Ho Ngoc Hai 76d75c753b Migrate
2026-05-23 18:37:02 +07:00

11 KiB
Raw Permalink Blame History

GoodGo POS - Tham Chiếu Nhanh Phát Triển Cục Bộ

Cập nhật lần cuối: 2026-04-12

🚀 QUICK START (5 minutes)

Option 1: Full Docker Stack (Production-like)

cd deployments/local
docker compose up -d
# Wait 60 seconds for all services to be healthy
open http://localhost:3001

Option 2: Hybrid (Recommended for Development)

# Terminal 1: Start infrastructure
cd deployments/local
docker compose up -d postgres redis rabbitmq minio

# Terminal 2: Start service with hot-reload
./scripts/dev/start-service.sh iam-service-net

# Terminal 3: Start another service
./scripts/dev/start-service.sh order-service-net

# Terminal 4: Frontend (if available)
cd apps/web-client-tpos-net
pnpm dev

📋 SERVICE INVENTORY

26 Total Microservices

Core (6): iam, storage, membership, wallet, merchant, mining
Engagement (5): mission, promotion, social, chat, ads-manager
Ads (5): ads-serving, ads-billing, ads-tracking, ads-analytics, catalog
Multi-Vertical (4): order, inventory, fnb-engine, booking
Marketing (4): mkt-facebook, mkt-whatsapp, mkt-x, mkt-zalo
Frontend (1): web-client-tpos-net

Port Mapping

Service Ports:  5001-5024 (internal 8080)
Frontend:       3001 (web-client-tpos-net)
Infrastructure:
  - PostgreSQL: 5432
  - Redis:      6379
  - RabbitMQ:   5672 (AMQP), 15672 (UI)
  - MinIO:      9000 (API), 9001 (Console)
Observability:
  - Traefik:    80, 8080
  - Prometheus: 9090
  - Grafana:    3002
  - Loki:       3100

🔧 HELPFUL COMMANDS

Start/Stop

cd deployments/local

# Start all services
docker compose up -d

# Start specific services only
docker compose up -d postgres redis minio rabbitmq

# Stop all
docker compose down

# Stop and clean volumes
docker compose down -v

# Restart a service
docker compose restart iam-service-net

Logs & Trạng thái

# Smart log viewer
./scripts/dev/logs.sh iam-service
./scripts/dev/logs.sh order-service-net

# Docker logs
docker logs -f postgres-local
docker logs -f iam-service-net-local

# Container status
docker ps --format "table {{.Names}}\t{{.Trạng thái}}"

Cơ Sở Dữ Liệu

# Connect to PostgreSQL
psql -h localhost -p 5432 -U goodgo -d iam_service

# List all databases
psql -h localhost -U goodgo -l

# Run migrations (per service)
cd services/iam-service-net
dotnet ef database update --project src/IamService.Infrastructure

Individual Service Development

# Start single service with hot-reload (requires infrastructure running)
./scripts/dev/start-service.sh iam-service-net

# Or directly with dotnet
cd services/iam-service-net
dotnet watch run

# Export environment variables first (optional)
export $(grep -v '^#' ../../deployments/local/.env.local | xargs)

🌐 ACCESS POINTS (After Services Start)

URL Mục đích
http://localhost Main POS App (web-client-tpos-net)
http://localhost:8080 Traefik Dashboard
http://localhost:9001 MinIO Console
http://localhost:15672 RabbitMQ Management
http://localhost:9090 Prometheus Metrics
http://localhost:3002 Grafana Dashboards
http://localhost:3100 Loki Logs

Direct Service Access (if needed)

iam-service:        http://localhost:5001
merchant-service:   http://localhost:5005
order-service:      http://localhost:5017
wallet-service:     http://localhost:5004
catalog-service:    http://localhost:5016
fnb-engine:         http://localhost:5019

📁 KEY FILES

Path Mục đích
deployments/local/docker-compose.yml Main config (1,645 lines)
deployments/local/.env Environment variables (checked in)
deployments/local/.env.local Local overrides (NOT committed)
scripts/dev/start-all.sh Start everything
scripts/dev/start-service.sh Start single service
scripts/dev/logs.sh Smart log viewer
infra/traefik/traefik.yml API gateway config
infra/traefik/dynamic/routes.yml Service routing

⚙️ ENVIRONMENT SETUP

.env File (Default - Checked In)

Contains defaults with staging database (212.28.186.239:30992)

.env.local File (Per-Developer - NOT Committed)

Override specific settings locally. Template: env.local.example

# Example: Use local PostgreSQL instead of staging
IAM_DATABASE_URL=Host=postgres;Port=5432;Database=iam_service;Username=goodgo;Password=goodgo-local-2024;SSL Mode=Disable
MERCHANT_DATABASE_URL=Host=postgres;Port=5432;Database=merchant_service;Username=goodgo;Password=goodgo-local-2024;SSL Mode=Disable
# ... etc for all 23 services

Redis Configuration

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=goodgo-redis-local

JWT Secrets (for local dev)

JWT_SECRET=GoodGo-Local-Dev-JWT-Secret-2024-Min32Chars!!
JWT_ISSUER=goodgo-platform
JWT_AUDIENCE=goodgo-services

🐛 TROUBLESHOOTING

"Connection refused" when running services

Problem: Infrastructure services not started
Solution:

cd deployments/local
docker compose up -d postgres redis rabbitmq minio

"Database connection timeout"

Problem: Using staging DB (212.28.186.239:30992) without network access
Solution:

  1. Update .env.local to use Docker Postgres (Host=postgres)
  2. Or ensure network access to staging IP

Service not found in logs

Problem: Container naming issue
Solution:

# List running containers
docker ps

# View logs by exact container name
docker logs -f <container-name>

Port already in use

Problem: Another service using same port
Solution:

# Find what's using the port
lsof -i :5001

# Kill the process
kill -9 <PID>

# Or change port in docker-compose.yml

.NET Service won't start locally

Problem: Missing environment variables
Solution:

# Load environment before running
export $(grep -v '^#' deployments/local/.env.local | xargs)
dotnet watch run --project services/iam-service-net

📊 ARCHITECTURE LAYERS

┌─────────────────────────────────────────────────────────┐
│ Frontend Layer (Blazor WASM)                            │
│ web-client-tpos-net:3001                                │
└──────────────────────┬──────────────────────────────────┘
                       │ Routes via Traefik
┌──────────────────────▼──────────────────────────────────┐
│ API Gateway (Traefik v3.3:80)                           │
│ Path-based routing to services                          │
└──────────────────────┬──────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
┌───────▼─────┐  ┌────▼────┐  ┌─────▼───────┐
│ Core        │  │ Engagement    │ Ads System      │
│ Services    │  │ Services      │ Services (RTB)  │
└──────┬──────┘  └────┬────┘  └─────┬───────┘
       │              │             │
└──────┴──────────────┴─────────────┘
       │
┌──────▼────────────────────────────────────┐
│ Shared Infrastructure                      │
│ postgres │ redis │ rabbitmq │ minio      │
└───────────────────────────────────────────┘

📈 RECOMMENDED WORKFLOW

Day-to-Day Development

  1. Start infrastructure once (morning):
cd deployments/local
docker compose up -d postgres redis rabbitmq minio
  1. Start services you're working on (per terminal):
./scripts/dev/start-service.sh iam-service-net
./scripts/dev/start-service.sh order-service-net
# Hot-reload available - save code to auto-reload
  1. Run frontend (separate terminal):
cd apps/web-client-tpos-net
pnpm dev
  1. Use IDE debugging:
  • Set breakpoints in VS Code / Visual Studio
  • Attach debugger to running process
  • Step through code normally
  1. Stop everything (end of day):
# Stop all containers
cd deployments/local
docker compose down

# Optional: Clean volumes for fresh start next time
docker compose down -v

🔍 DATABASE SCHEMAS

Each service has its own database:

iam_service           - Identity & access management
merchant_service      - Shop/merchant management
order_service         - Order orchestration
catalog_service       - Product catalog
inventory_service     - Stock management
wallet_service        - Wallet/balance management
promotion_service     - Vouchers & campaigns
... 17 more databases

All create automatically via init-databases.sh on first PostgreSQL startup.

🚀 DEPLOYMENT REFERENCE

For Staging/Production deployment info:

  • See .claude/POS_DEPLOYMENT_STATE.md
  • See .claude/DEPLOYMENT_QUICK_REFERENCE.md

💡 TIPS & TRICKS

Debug a specific service

# Terminal 1: Run with verbose logging
export $(grep -v '^#' deployments/local/.env.local | xargs)
cd services/iam-service-net
ASPNETCORE_ENVIRONMENT=Development dotnet watch run

# Terminal 2: Attach debugger from IDE

Test API locally

# Get auth token
curl -X POST http://localhost:5001/api/v1/auth/login \
  -H "Content-Loại: application/json" \
  -d '{"username":"test","password":"test"}'

# Use token in other requests
curl http://localhost:5017/api/v1/orders \
  -H "Authorization: Bearer $TOKEN"

View database queries

# Enable EF Core command logging in appsettings.Development.json
# Then check console output for SQL queries

Reset everything

cd deployments/local
docker compose down -v
docker compose up -d
# All databases will be recreated fresh

📞 SUPPORT

For detailed information:

  • .claude/LOCAL_DEV_SETUP_INVESTIGATION.md - Full technical investigation
  • .claude/POS_DEPLOYMENT_STATE.md - Deployment state & staging setup
  • .claude/TROUBLESHOOTING.md - Known issues & solutions
Reference in New Issue View Git Blame Copy Permalink