feat: Add initial documentation for WebClientBase architecture and usage in English and Vietnamese.

2026-01-19 09:34:11 +07:00
parent e1dfc4e7a7
commit 118ba50058
4 changed files with 328 additions and 0 deletions
--- a/apps/web-client-base-net/docs/en/ARCHITECTURE.md
+++ b/apps/web-client-base-net/docs/en/ARCHITECTURE.md
@@ -0,0 +1,99 @@
+# WebClientBase Architecture
+
+Base frontend architecture for GoodGo Platform using Blazor WebAssembly with BFF Pattern.
+
+## Overview
+
+This application implements the **Backend for Frontend (BFF)** pattern with YARP reverse proxy:
+
+- **Client**: Blazor WebAssembly running in browser
+- **BFF**: ASP.NET Core server proxying requests to microservices
+- **Shared**: Common DTOs with validation (shared between Client/BFF)
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph Browser["🌐 Browser"]
+        C[Blazor WASM Client]
+    end
+    
+    subgraph BFF["⚙️ BFF Layer"]
+        Y[YARP Reverse Proxy]
+        SA[Static Assets]
+    end
+    
+    subgraph MS["🔧 Microservices"]
+        IAM[IAM Service]
+        MER[Merchant Service]
+        CAT[Catalog Service]
+        ORD[Order Service]
+    end
+    
+    C -->|Static Files| SA
+    C -->|/api/*| Y
+    Y -->|/api/iam/**| IAM
+    Y -->|/api/merchants/**| MER
+    Y -->|/api/catalog/**| CAT
+    Y -->|/api/orders/**| ORD
+    
+    style C fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
+    style Y fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
+    style SA fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
+    style IAM fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
+    style MER fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
+    style CAT fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
+    style ORD fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
+```
+
+## Project Structure
+
+```
+web-client-base-net/
+├── src/
+│   ├── WebClientBase.Client/    # Blazor WebAssembly
+│   │   ├── Layout/              # MainLayout, NavMenu
+│   │   ├── Pages/               # Razor pages
+│   │   └── wwwroot/             # Static assets, CSS
+│   ├── WebClientBase.Server/    # BFF + YARP Proxy
+│   │   ├── Program.cs           # App configuration
+│   │   └── yarp.json            # Proxy routes
+│   └── WebClientBase.Shared/    # Shared DTOs
+│       └── DTOs/                # ProductDto, UserDto
+└── docs/
+```
+
+## Shared DTOs
+
+| DTO | Purpose | Validation |
+|-----|---------|------------|
+| `ProductDto` | Product data | Name (3-100 chars), Price (0.01-1B) |
+| `RegisterDto` | User registration | Email, Password (8+ chars, complexity) |
+| `LoginDto` | User login | Email, Password |
+| `ApiResponse<T>` | Standard response wrapper | Success, Data, Error |
+
+## YARP Routes
+
+| Route | Target Service | Port |
+|-------|---------------|------|
+| `/api/iam/**` | IAM Service | 5101 |
+| `/api/merchants/**` | Merchant Service | 5102 |
+| `/api/catalog/**` | Catalog Service | 5103 |
+| `/api/orders/**` | Order Service | 5104 |
+
+## Blazor Pages
+
+| Page | Route | Description |
+|------|-------|-------------|
+| Home | `/` | Landing page |
+| Products | `/products` | Product management |
+| Auth | `/auth` | Login/Register |
+| Counter | `/counter` | Demo component |
+| Weather | `/weather` | Demo data fetch |
+
+## Key Technologies
+
+- **.NET 10** - Latest framework
+- **Blazor WebAssembly** - Client-side SPA
+- **YARP** - Reverse proxy for microservices
+- **Data Annotations** - Shared validation
--- a/apps/web-client-base-net/docs/en/README.md
+++ b/apps/web-client-base-net/docs/en/README.md
@@ -0,0 +1,65 @@
+# WebClientBase
+
+Base frontend application cho GoodGo Platform.
+
+## Quick Start
+
+```bash
+# Navigate to project
+cd apps/web-client-base-net
+
+# Restore packages
+dotnet restore
+
+# Run BFF server
+dotnet run --project src/WebClientBase.Server
+
+# Open browser at http://localhost:5091
+```
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Client | Blazor WebAssembly (.NET 10) |
+| BFF | ASP.NET Core + YARP |
+| Shared | Class Library with Data Annotations |
+| Styling | CSS Variables, Dark Mode |
+
+## Project Structure
+
+```
+src/
+├── WebClientBase.Client/    # Blazor WASM frontend
+├── WebClientBase.Server/    # BFF with YARP proxy
+└── WebClientBase.Shared/    # Shared DTOs
+```
+
+## Features
+
+- ✅ BFF Pattern with YARP reverse proxy
+- ✅ Shared validation (Client + Server)
+- ✅ Dark/Light mode support
+- ✅ Glassmorphism UI design
+- ✅ Health check endpoint `/health`
+
+## Configuration
+
+YARP proxy routes in `yarp.json`:
+
+```json
+{
+  "ReverseProxy": {
+    "Routes": {
+      "iam-route": { "Match": { "Path": "/api/iam/{**catch-all}" } }
+    },
+    "Clusters": {
+      "iam-cluster": { "Destinations": { "d1": { "Address": "http://localhost:5101" } } }
+    }
+  }
+}
+```
+
+## Related Documentation
+
+- [Architecture](ARCHITECTURE.md) - System architecture details
--- a/apps/web-client-base-net/docs/vi/ARCHITECTURE.md
+++ b/apps/web-client-base-net/docs/vi/ARCHITECTURE.md
@@ -0,0 +1,99 @@
+# Kiến trúc WebClientBase
+
+Kiến trúc frontend cơ sở cho GoodGo Platform sử dụng Blazor WebAssembly với mô hình BFF.
+
+## Tổng quan
+
+Ứng dụng này triển khai mô hình **Backend for Frontend (BFF)** với YARP reverse proxy:
+
+- **Client**: Blazor WebAssembly chạy trên trình duyệt
+- **BFF**: ASP.NET Core server proxy yêu cầu đến microservices
+- **Shared**: DTOs chung với validation (chia sẻ giữa Client/BFF)
+
+## Sơ đồ Kiến trúc
+
+```mermaid
+flowchart TD
+    subgraph Browser["🌐 Trình duyệt"]
+        C[Blazor WASM Client]
+    end
+    
+    subgraph BFF["⚙️ Lớp BFF"]
+        Y[YARP Reverse Proxy]
+        SA[Tài nguyên tĩnh]
+    end
+    
+    subgraph MS["🔧 Microservices"]
+        IAM[Dịch vụ IAM]
+        MER[Dịch vụ Merchant]
+        CAT[Dịch vụ Catalog]
+        ORD[Dịch vụ Order]
+    end
+    
+    C -->|Tệp tĩnh| SA
+    C -->|/api/*| Y
+    Y -->|/api/iam/**| IAM
+    Y -->|/api/merchants/**| MER
+    Y -->|/api/catalog/**| CAT
+    Y -->|/api/orders/**| ORD
+    
+    style C fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
+    style Y fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
+    style SA fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
+    style IAM fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
+    style MER fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
+    style CAT fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
+    style ORD fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
+```
+
+## Cấu trúc Dự án
+
+```
+web-client-base-net/
+├── src/
+│   ├── WebClientBase.Client/    # Blazor WebAssembly
+│   │   ├── Layout/              # MainLayout, NavMenu
+│   │   ├── Pages/               # Trang Razor
+│   │   └── wwwroot/             # Tài nguyên tĩnh, CSS
+│   ├── WebClientBase.Server/    # BFF + YARP Proxy
+│   │   ├── Program.cs           # Cấu hình ứng dụng
+│   │   └── yarp.json            # Routes proxy
+│   └── WebClientBase.Shared/    # DTOs chung
+│       └── DTOs/                # ProductDto, UserDto
+└── docs/
+```
+
+## Shared DTOs
+
+| DTO | Mục đích | Validation |
+|-----|----------|------------|
+| `ProductDto` | Dữ liệu sản phẩm | Tên (3-100 ký tự), Giá (0.01-1 tỷ) |
+| `RegisterDto` | Đăng ký người dùng | Email, Mật khẩu (8+ ký tự, độ phức tạp) |
+| `LoginDto` | Đăng nhập | Email, Mật khẩu |
+| `ApiResponse<T>` | Wrapper response chuẩn | Success, Data, Error |
+
+## YARP Routes
+
+| Route | Dịch vụ đích | Cổng |
+|-------|-------------|------|
+| `/api/iam/**` | Dịch vụ IAM | 5101 |
+| `/api/merchants/**` | Dịch vụ Merchant | 5102 |
+| `/api/catalog/**` | Dịch vụ Catalog | 5103 |
+| `/api/orders/**` | Dịch vụ Order | 5104 |
+
+## Trang Blazor
+
+| Trang | Route | Mô tả |
+|-------|-------|-------|
+| Home | `/` | Trang chủ |
+| Products | `/products` | Quản lý sản phẩm |
+| Auth | `/auth` | Đăng nhập/Đăng ký |
+| Counter | `/counter` | Component demo |
+| Weather | `/weather` | Demo fetch dữ liệu |
+
+## Công nghệ chính
+
+- **.NET 10** - Framework mới nhất
+- **Blazor WebAssembly** - SPA phía client
+- **YARP** - Reverse proxy cho microservices
+- **Data Annotations** - Validation chia sẻ
--- a/apps/web-client-base-net/docs/vi/README.md
+++ b/apps/web-client-base-net/docs/vi/README.md
@@ -0,0 +1,65 @@
+# WebClientBase
+
+Ứng dụng frontend cơ sở cho GoodGo Platform.
+
+## Bắt đầu nhanh
+
+```bash
+# Di chuyển đến dự án
+cd apps/web-client-base-net
+
+# Khôi phục packages
+dotnet restore
+
+# Chạy BFF server
+dotnet run --project src/WebClientBase.Server
+
+# Mở trình duyệt tại http://localhost:5091
+```
+
+## Công nghệ
+
+| Thành phần | Công nghệ |
+|------------|-----------|
+| Client | Blazor WebAssembly (.NET 10) |
+| BFF | ASP.NET Core + YARP |
+| Shared | Class Library với Data Annotations |
+| Styling | CSS Variables, Dark Mode |
+
+## Cấu trúc Dự án
+
+```
+src/
+├── WebClientBase.Client/    # Blazor WASM frontend
+├── WebClientBase.Server/    # BFF với YARP proxy
+└── WebClientBase.Shared/    # DTOs chia sẻ
+```
+
+## Tính năng
+
+- ✅ Mô hình BFF với YARP reverse proxy
+- ✅ Validation chia sẻ (Client + Server)
+- ✅ Hỗ trợ chế độ Sáng/Tối
+- ✅ Thiết kế UI Glassmorphism
+- ✅ Endpoint kiểm tra sức khỏe `/health`
+
+## Cấu hình
+
+Routes YARP proxy trong `yarp.json`:
+
+```json
+{
+  "ReverseProxy": {
+    "Routes": {
+      "iam-route": { "Match": { "Path": "/api/iam/{**catch-all}" } }
+    },
+    "Clusters": {
+      "iam-cluster": { "Destinations": { "d1": { "Address": "http://localhost:5101" } } }
+    }
+  }
+}
+```
+
+## Tài liệu liên quan
+
+- [Kiến trúc](ARCHITECTURE.md) - Chi tiết kiến trúc hệ thống