docs: full documentation audit — update 7 files, create MCP SERVICE_DOCS

Project-level docs: - README.md: rewrite with correct tech stack (.NET 10/Blazor, not Node.js/Flutter) - ROADMAP.md: add MCP server, shop lifecycle, onboarding redesign, POS nav fix - CLAUDE.md: add goodgo-mcp-server to project structure - CTO_REPORT_SHOP_DELETE.md: status OPEN → RESOLVED (implemented in 6263eeb) MCP Server docs: - SERVICE_DOCS.md: new file — 12 tools reference, architecture, setup guide Frontend docs: - web-client-tpos-net README: fix wrong paths (web-client-base-net → web-client-tpos-net) - web-client-tpos-net docs/en/README: same path fix Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-20 16:46:15 +07:00
parent ca022de832
commit d0211e5a3c
7 changed files with 502 additions and 260 deletions
--- a/README.md
+++ b/README.md
@@ -1,290 +1,129 @@
-# GoodGo Microservices Platform
+# GoodGo Platform

-[![English](https://img.shields.io/badge/Language-English-blue.svg)](README.md) [![Tiếng Việt](https://img.shields.io/badge/Ngôn%20ngữ-Tiếng%20Việt-red.svg)](README.vi.md)
+Monorepo platform with microservices architecture for the merchant/customer ecosystem — POS, F&B, retail, spa, karaoke, and more.

-Enterprise-grade microservices monorepo built with modern technologies and best practices.
+**Domain**: [goodgo.vn](https://goodgo.vn) | **Staging**: api.staging.goodgo.vn

-## 🏗️ Architecture
+## Tech Stack

-This monorepo follows a microservices architecture pattern with:
+| Layer | Technologies |
+|-------|-------------|
+| **Backend** | .NET 10.0 (C# 14), MediatR/CQRS, EF Core 10, FluentValidation, Serilog, Dapper, Polly |
+| **Web** | Blazor WASM + MudBlazor 8.15 (Material Design) |
+| **Mobile** | .NET MAUI (cross-platform), SwiftUI (iOS) |
+| **Database** | PostgreSQL 16 (local) / Neon PostgreSQL (cloud), Redis 7 |
+| **Messaging** | RabbitMQ 3 (AMQP) |
+| **Storage** | MinIO (S3-compatible) |
+| **Gateway** | Traefik v3 |
+| **Infra** | Docker Compose (local), Kubernetes RKE2 (staging/prod) |
+| **CI/CD** | GitHub Actions, Docker Hub |
+| **Observability** | Prometheus + Grafana + Loki + Promtail |
+| **Auth** | Duende IdentityServer, JWT Bearer, OAuth2 |
+| **Monorepo** | pnpm 8 workspaces, Turborepo |

- **Apps**: Frontend applications (Web + Mobile)
- **Services**: Backend microservices (Node.js/TypeScript)
- **Packages**: Shared libraries and utilities
- **Infrastructure**: Traefik, Observability, Databases
- **Deployments**: Environment-specific configurations
-
-## 📁 Project Structure
+## Project Structure

 ```
-├── apps/                 # Frontend applications
-│   ├── web-admin/       # Next.js admin web application
-│   ├── web-client/      # Next.js client web application
-│   ├── app-admin/       # Flutter admin mobile application
-│   └── app-client/      # Flutter client mobile application
-├── services/            # Backend microservices
-│   ├── iam-service/     # Identity and Access Management service (Node.js)
-│   └── _template/       # Service template for new services
-├── packages/            # Shared libraries
-│   ├── auth-sdk/        # Auth utilities and guards
-│   ├── config/          # Shared configurations
-│   ├── http-client/     # Standardized API client
-│   ├── logger/          # Centralized logging (Winston)
-│   ├── tracing/         # OpenTelemetry setup
-│   └── types/           # Shared TypeScript types
-├── infra/               # Infrastructure as Code
-│   ├── databases/       # Database configs (PostgreSQL/Neon, Redis)
-│   ├── docker/          # Docker compose files
-│   ├── observability/   # Monitoring stack (Prometheus, Grafana, Loki)
-│   ├── secrets/         # Secret management
-│   └── traefik/         # API Gateway configuration
-├── deployments/         # Environment configs
-│   ├── local/           # Local development setup
-│   ├── staging/         # Staging environment (Kubernetes)
-│   └── production/      # Production environment (Kubernetes)
-├── scripts/             # Automation scripts (Bilingual EN/VI)
-│   ├── build/           # Build scripts
-│   ├── db/              # Database management (backup, seed, migrate)
-│   ├── deploy/          # Deployment scripts
-│   ├── dev/             # Development helpers
-│   ├── setup/           # Project initialization
-│   └── utils/           # Utility scripts (cleanup, generators)
-└── docs/                # Documentation
+services/                    # 26 .NET microservices (Clean Architecture + CQRS)
+apps/                        # Frontend applications
+packages/                    # Shared Node.js packages (@goodgo/*)
+deployments/                 # Environment configs (local, staging, production)
+infra/                       # Infrastructure (Traefik, databases, observability)
+scripts/                     # Automation scripts (dev, db, deploy, build)
 ```

-## ⚠️ Breaking Changes
+## Services

-### v1.0.0 - Module Format Migration (2026-01-07)
+**Core Platform**
+- `iam-service-net` — Identity & Access Management (JWT, RBAC, MFA, Sessions)
+- `merchant-service-net` — Merchant & Shop management
+- `catalog-service-net` — Product catalog
+- `order-service-net` — Order processing
+- `inventory-service-net` — Inventory management
+- `wallet-service-net` — Wallet & payments
+- `fnb-engine-net` — F&B engine
+- `booking-service-net` — Booking & reservations

-**BREAKING**: All shared packages now use ES modules instead of CommonJS.
+**Engagement**
+- `promotion-service-net` — Promotions & discounts
+- `membership-service-net` — Membership & loyalty
+- `chat-service-net` — Chat & messaging (SignalR + Redis)
+- `social-service-net` — Social features
+- `mission-service-net` — Gamification missions

-**What Changed:**
- TypeScript compilation target changed from `commonjs` to `ES2020`
- All packages (`@goodgo/types`, `@goodgo/http-client`, `@goodgo/logger`, `@goodgo/auth-sdk`, `@goodgo/tracing`) now export ES modules
- `package.json` files already declared `"type": "module"`, now TypeScript output matches
+**Advertising**
+- `ads-manager-service-net` — Campaign management
+- `ads-serving-service-net` — Ad delivery
+- `ads-billing-service-net` — Ad billing
+- `ads-tracking-service-net` — Event tracking
+- `ads-analytics-service-net` — Analytics

-**Migration Required:**
-If you have existing code importing these packages:
+**Marketing Integrations**
+- `mkt-facebook-service-net` — Facebook
+- `mkt-whatsapp-service-net` — WhatsApp
+- `mkt-x-service-net` — X (Twitter)
+- `mkt-zalo-service-net` — Zalo

-```typescript
-// ✅ This still works (no changes needed for most cases)
-import { UserResponse } from '@goodgo/types';
-import { createHttpClient } from '@goodgo/http-client';
+**Utilities**
+- `storage-service-net` — File storage (MinIO)
+- `mining-service-net` — Data mining

-// ⚠️ If you were using require() (CommonJS), you must update:
-// ❌ OLD: const { UserResponse } = require('@goodgo/types');
-// ✅ NEW: import { UserResponse } from '@goodgo/types';
-```
+## Frontend Apps

-**Action Required:**
-1. Pull latest changes
-2. Clean and rebuild: `pnpm -r --filter "./packages/*" run clean && pnpm build`
-3. Update any CommonJS `require()` statements to ES `import`
+| App | Stack | Description |
+|-----|-------|-------------|
+| `web-client-tpos-net` | Blazor WASM + MudBlazor | POS system (multi-vertical: karaoke, restaurant, cafe, spa, retail) |
+| `web-client-base-net` | Blazor WASM + MudBlazor | Enterprise portal |
+| `app-client-base-net` | .NET MAUI | Cross-platform mobile app |
+| `app-client-base-swift` | SwiftUI | iOS app |
+| `web-docs` | VitePress | Documentation site |

-**Files Changed:**
- `packages/config/tsconfig/node.json` - Changed `"module": "commonjs"` → `"module": "ES2020"`
- `packages/types/tsconfig.json` - Added `"moduleResolution": "node"`
-
-For detailed information, see [Migration Walkthrough](docs/en/guides/module-format-migration.md).
-
-## 🚀 Getting Started
+## Quick Start

 ### Prerequisites

- Node.js >= 20.0.0
- pnpm >= 8.0.0
 - Docker & Docker Compose
- Neon account (https://neon.tech) - for PostgreSQL database
+- .NET 10.0 SDK
+- Node.js 25+
+- pnpm 8+

-### Quick Start (One-Command Setup)
-
-We provide a comprehensive initialization script to get you up and running quickly:
+### Run Locally

 ```bash
-./scripts/setup/init-project.sh
+# Start infrastructure (PostgreSQL, Redis, RabbitMQ, MinIO, Traefik) + all services
+cd deployments/local
+docker compose up -d
+
+# Run database migrations (per service)
+./scripts/db/migrate.sh
+
+# Start a specific service for development
+./scripts/dev/start-service.sh iam-service-net
 ```

-This script will:
-1.  Check prerequisites
-2.  Install dependencies
-3.  Generate Prisma clients
-4.  Create necessary `.env` files from examples
+### Architecture

-### Manual Installation
+Each .NET service follows **Clean Architecture + CQRS**:

-If you prefer to set up manually:
-
-```bash
-# Install dependencies
-pnpm install
-
-# Generate Prisma clients
-pnpm prisma:generate
-
-# Start all services (development)
-./scripts/dev/start-all.sh
+```
+ServiceName/
+  src/
+    ServiceName.API/              # Controllers + MediatR Commands/Queries
+    ServiceName.Domain/           # Entities, aggregates, domain events (no dependencies)
+    ServiceName.Infrastructure/   # EF Core, repositories, migrations
+  tests/
+    ServiceName.UnitTests/        # xUnit + FluentAssertions
+    ServiceName.FunctionalTests/  # WebApplicationFactory integration tests
 ```

-### Local Development Flow
+## Documentation

-1.  **Database Setup**:
-    ```bash
-    ./scripts/db/setup-neon.sh
-    # Follow the interactive prompts to configure your Neon URL
-    ```
+- [ROADMAP.md](ROADMAP.md) — Development roadmap and phase tracking
+- [CLAUDE.md](CLAUDE.md) — Full architecture reference and agent configuration

-2.  **Start Infrastructure**:
-    ```bash
-    # Starts Redis, Traefik, and Observability stack
-    cd deployments/local
-    docker-compose up -d
-    ```
+## Maintainer

-3.  **Run Migrations**:
-    ```bash
-    ./scripts/db/migrate.sh iam-service dev
-    ```
-
-4.  **Start Services**:
-    ```bash
-    ./scripts/dev/start-all.sh
-    # Or to start a specific service:
-    # ./scripts/dev/start-service.sh iam-service
-    ```
-
-## 🛠️ Helper Scripts
-
-The `scripts/` directory contains bilingual (English/Vietnamese) automation scripts to streamline daily tasks:
-
-| Category | Script | Description |
-|----------|--------|-------------|
-| **Setup** | `init-project.sh` | Full project initialization |
-| | `install-deps.sh` | Install dependencies |
-| **Dev** | `start-all.sh` | Start infrastructure and all services |
-| | `start-service.sh` | Start a specific service |
-| | `logs.sh` | View logs for services or docker containers |
-| | `setup-env.sh` | Helper to setup environment variables |
-| **DB** | `migrate.sh` | Run Prisma migrations (dev/deploy) |
-| | `seed.sh` | Seed database with initial data |
-| | `backup.sh` | Backup database (supports Neon) |
-| | `setup-neon.sh` | Wizard to configure Neon DB connection |
-| **Utils** | `create-service.sh` | Scaffold a new microservice from template |
-| | `cleanup.sh` | Clean build artifacts and caches |
-| **Build** | `build-all.sh` | Build entire monorepo |
-| | `build-service.sh` | Build specific service |
-| **Deploy** | `deploy-staging.sh` | Deploy to staging cluster |
-| | `deploy-prod.sh` | Deploy to production cluster |
-
-## 🛠️ Tech Stack
-
-**Frontend:**
- Web: Next.js 14+ (App Router)
- Mobile: Flutter 3.x
- Styling: Tailwind CSS
- State: Zustand / Provider
-
-**Backend:**
- Runtime: Node.js + TypeScript
- Framework: Express/NestJS (via service template)
- ORM: Prisma
- Database: PostgreSQL (Neon Serverless), Redis (Caching/Queues)
-
-**Infrastructure:**
- Gateway: Traefik
- Containerization: Docker
- Orchestration: Kubernetes
- Observability: Prometheus, Grafana, Loki, OpenTelemetry
-
-**DevOps:**
- Build System: Turborepo
- Package Manager: PNPM Workspaces
- CI/CD: GitHub Actions
-
-## 🌐 Coding Standards
-
-### Bilingual Comments
-To support our diverse team, we follow a bilingual commenting standard (English & Vietnamese) for:
- Scripts
- Complex logic
- Public APIs
- Configuration files
-
-Example:
-```bash
-# EN: Verify Docker daemon is running
-# VI: Xác minh Docker daemon đang chạy
-```
-
-### Monorepo Management
- We use **Turborepo** for build pipelines and caching.
- **PNPM Workspaces** manage dependencies across apps and services.
-
-## 📚 Documentation
-
- [Architecture Overview](docs/en/architecture/system-design.md)
- [API Documentation](docs/en/api/openapi/)
- [Development Guide](docs/en/guides/development.md)
- [Deployment Guide](docs/en/guides/deployment.md)
- [Contributing Guide](CONTRIBUTING.md)
-
-## 🔐 Environment Variables
-
-**Important**: Never commit `.env` files. Use `.env.example` as templates.
-
- **Dev**: `deployments/local/.env.local` (Shared), `services/*/.env.local` (Service specific)
- **Staging/Prod**: Managed via Kubernetes Secrets
-
-## 🧪 Testing
-
-```bash
-# Run all tests
-pnpm test
-
-# Run tests for specific package
-pnpm --filter @goodgo/iam-service test
-
-# Run with coverage
-pnpm --filter @goodgo/iam-service test:coverage
-```
-
-## 📦 Building
-
-```bash
-# Build all packages and services
-pnpm build
-
-# Build specific service
-pnpm --filter @goodgo/iam-service build
-```
-
-## 🚢 Deployment
-
-See [Deployment Guide](docs/guides/deployment.md) for detailed instructions.
-
-### Quick Deploy
-
-```bash
-# Local
-cd deployments/local && docker-compose up -d
-
-# Staging (Kubernetes)
-cd deployments/staging && kubectl apply -f kubernetes/
-
-# Production
-cd deployments/production && kubectl apply -f kubernetes/
-```
-
-## 🤝 Contributing
-
-Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 👥 Maintainer
-
-Built with ❤️ by **VelikHo** ([@hongochai10](https://github.com/hongochai10))
+Built by **VelikHo** ([@hongochai10](https://github.com/hongochai10))

 - **Email**: hongochai10@icloud.com
 - **GitHub**: https://github.com/hongochai10