System Architecture & ML Pipeline

Kiến trúc hệ thống — phiên bản nâng cấp

Tổng quan

Hệ thống gồm 4 thành phần chính + hạ tầng hỗ trợ:

┌──────────────────────┐     ┌───────────────────────────────┐
│  React 18 + TS       │     │  FastAPI (3-layer)            │
│  Tailwind + shadcn   │────▶│  endpoints → services → repos │
│  MapLibre + OSM      │     │  + Prisma (payments module)   │
└──────────────────────┘     └──────────────┬────────────────┘
                                            │
                    ┌───────────────────────┼───────────────────────┐
                    ▼                       ▼                       ▼
            ┌──────────────┐        ┌──────────────┐        ┌──────────────┐
            │  PostgreSQL  │        │ Redis / file │        │ FAISS index  │
            │  (catalog,   │        │ cache (bền   │        │ (MiniLM +    │
            │  orders,     │        │ vững qua     │        │  CLIP embed- │
            │  logistics)  │        │ restart)     │        │  dings)      │
            └──────────────┘        └──────────────┘        └──────────────┘

Các hệ thống mới

1. Logistics & Bản đồ (Nhóm 31)

  • Mạng kho 3 cấp: Cửa hàng Supplier → Kho tỉnh (34 tỉnh, dữ liệu MIT thanglequoc/vietnamese-provinces-database v4.2) → 4 Kho tổng (Hà Nội, Đà Nẵng, TP.HCM, Cần Thơ).
  • Định tuyến tự động: cùng tỉnh đi thẳng; khác tỉnh qua kho tổng gần nhất (haversine).
  • Engine mô phỏng: asyncio loop tiến gói hàng qua từng chặng (PICKUP → LINEHAUL → LAST_MILE), ghi tracking_event kèm tọa độ; chế độ demo tăng tốc.
  • Bản đồ: MapLibre GL + OpenFreeMap (miễn phí, không API key, style Dark). Khách xem lộ trình trong modal đơn hàng; Admin xem toàn mạng lưới.

2. ML Console & Hybrid Recommender (Nhóm 1, 8)

  • 6 mô hình gợi ý được hợp nhất bằng weighted ranker — Admin bật/tắt + kéo trọng số ngay trên UI, không cần deploy.
  • Mỗi item gợi ý kèm sources → nhãn giải thích “Vì sao gợi ý”.
  • A/B framework: chia bucket user 50/50 (hash), arm B dùng bộ trọng số khác; đo CTR qua vòng phản hồi (impression/click events).

3. Semantic & Image Search

  • Text: all-MiniLM-L6-v2 + FAISS; hybrid score = 0.6×vector + exact-match boost + rating.
  • Image: CLIP ViT-B/32 + FAISS; upload ảnh → tìm sản phẩm tương tự.
  • Fallback an toàn: index chưa có → tự về trending, UI không bao giờ vỡ.

4. Thanh toán & Ví (Nhóm 32)

  • Prisma (prisma-client-py) quản các bảng mới: PaymentTransaction, Wallet, WalletLedger, GiftCardBatch, GiftCard.
  • Payment gateway giả lập: thẻ (Luhn check), QR mock; ví trừ tiền trong transaction; gift card do Admin cấp theo nhóm user.
  • Sổ cái (ledger) ghi mọi dòng tiền: nạp / tiêu / hoàn / quà.

5. Data Pipeline

scraper/ (Playwright, amazon.com, USD cookie + VND fallback, identity rotation)
  → ModelApp/implementation/pre_processing.py   → Data/Amazon-Products_processed_03.csv
  → generate_users.py (2000 user VN, ratings tương quan sở thích)
  → association_rules.py (Apriori, 64k rules)
  → generate_reviews.py (66k reviews theo bucket sao — tín hiệu sentiment)
  → Backend/scripts/database/import_new_data.py (auto-backup → PostgreSQL)
  → scripts/ml/embed_products.py (FAISS index)

Điểm đau đã giải quyết

Vấn đề Giải pháp
Cache gợi ý mất khi restart CacheService: Redis hoặc file-persistence (append-only dump + load-on-init)
Interest/Trending là dead code Expose 2 endpoint mới + derive interests từ rating history
17 endpoint admin không có auth verify_admin_user trên toàn bộ /admin/*
Sản phẩm mới làm TF-IDF re-fit chậm FAISS index build offline; runtime chỉ encode query (~50ms)