GOHUB Documentation Hub

Mục tiêu bộ tài liệu

Mỗi menu là một tài liệu độc lập, dễ dùng khi họp hoặc onboarding.
Mỗi tài liệu trình bày theo slide ngắn gọn, tập trung quyết định và thao tác.
Nội dung đã đối chiếu từ source thực tế trong workspace.

Hệ sinh thái GOHUB

User Channels:
- gohub.vn (Next.js storefront VN)
- gohub.com (Next.js storefront global, multi-locale)
- gohub-app (Flutter mobile)

Admin Channels:
- gohub-admin (React + Vite, backoffice vận hành)
- gohub-product-admin (React + Vite, backoffice sản phẩm)

Backend:
- gohub-product-api (Express + Prisma + PostgreSQL)
- GOHUB API core (domain api.gohub.com / api.stg-space.gohub.com)

Mapping domain hiện tại

Dịch vụ	Staging	Production
GOHUB API	`api.stg-space.gohub.com` -> `34.59.152.45`	`api.gohub.com` -> `TBD`
GOHUB Admin	`admin.stg-space.gohub.com` (Cloudflare)	`admin.space.gohub.com` (Cloudflare)
GOHUB VN	`vn.stg-space.gohub.com` -> `34.59.152.45`	`gohub.vn` -> `TBD`
GOHUB COM	`com.stg-space.gohub.com` -> `34.59.152.45`	`gohub.com` -> `TBD`
PM + API PM	`pm.stg-space.gohub.com` (Cloudflare), `api-pm.stg-space.gohub.com` -> `34.124.129.187`	`pm.space.gohub.com` (Cloudflare), `api-pm.space.gohub.com` -> `TBD`

Stack chính theo nhóm hệ thống

Web Storefront

gohub-vn, gohub-com: Next.js 16 + React 19 + Tailwind 4
Build image Docker (Node 22), push lên Google Artifact Registry

Backoffice

gohub-admin, gohub-product-admin: React 19 + Vite 7 + TS
Deploy Cloudflare Pages qua GitHub Actions + Wrangler

Sơ đồ liên kết nền tảng (HTML Architecture Map)

Channels

gohub.vn
Next.js 16

gohub.com
Next.js 16 i18n

gohub-app
Flutter

Admin

gohub-admin
React + Vite

gohub-product-admin
React + Vite

API Layer

GOHUB API
api.gohub.com

Product API
api-pm.space.gohub.com

Data Layer

DB GOHUB
Core domain

DB GOHUB PM
Product domain

Luồng chính: channel/admin -> API tương ứng -> database domain tương ứng. Các domain admin/pm hiện được map qua Cloudflare.

Backend product domain

gohub-product-api: Node 20+, Express 4, Prisma 7, Postgres adapter.
Modules theo domain: product-master, pm-listing, pm-item, pm-sku, vendors, countries...
OpenAPI UI: /api-docs, health check: /health.
Deploy dạng container qua Dockerfile / docker-compose.

Mobile app

gohub-app: Flutter (Dart), GetX, Dio, Firebase, Stripe.
Config API bằng --dart-define cho dev/stg/prod.
Prod API mặc định trong source: https://api.gohub.com.
Có script build riêng cho IPA/AAB theo môi trường.

`gohub-admin`

React 19 + Vite + TS, React Router v7, React Query, Zustand, i18next.
API base URL: VITE_API_URL, refresh token qua /admin/auth/refresh.
Nhiều module vận hành: orders, products, promotions, posts, report, settings.
CI deploy Cloudflare Pages project gohub-admin.

`gohub-product-admin`

React 19 + Vite + TS, route tập trung cho product/master-data/guide.
API dùng bộ biến VITE_API_URL, VITE_AUTH_API_URL, VITE_PRODUCT_API_URL.
Màn hình trọng tâm: PM listing/item/SKU, categories, vendors, countries, operators.
Deploy Cloudflare Pages cho cả branch main và staging.

`gohub-product-api`

Express + Prisma, env bắt buộc DATABASE_URL, có auth service URL riêng.
Route chính: /pm-listing, /pm-item, /pm-sku, /product-master...
Lark sync endpoints có sẵn: /lark-*.
Deploy containerized, expose mặc định port 3003.

`gohub-vn` và `gohub-com`

Cả hai là Next.js storefront; VN tập trung thị trường nội địa, COM tập trung multi-locale.
gohub-com có routing /[locale], i18n JSON, sitemap theo locale.
Hai repo đều có Docker + workflow build/push image lên GAR.
Port local: VN 3006, COM 3005.

Phân lớp dữ liệu đề xuất

Layer	Mục đích	Ví dụ
Master	Danh mục cốt lõi, ít biến động	users, roles, platforms, vendors
Product	Dữ liệu danh mục bán hàng	product_master, variants, pricing, listing
Transaction	Dữ liệu phát sinh theo đơn	orders, payments, topup logs
Audit	Truy vết thao tác	activity_logs, status_histories

Quy tắc thay đổi schema

Mọi thay đổi DB phải qua migration versioned + rollback script.
Không thao tác trực tiếp prod khi chưa có ticket và phê duyệt.
Bắt buộc test hiệu năng query/index trên staging trước production.
Cập nhật data dictionary ngay sau release.

Thông tin endpoint DB cần bổ sung

DB GOHUB Prod: TBD
DB GOHUB Staging: TBD
DB GOHUB PM Prod: TBD
DB GOHUB PM Staging: TBD

Nhóm case chính

Quản lý tài khoản và phân quyền nội bộ.
Quản lý nội dung/cấu hình hệ thống.
Theo dõi vận hành đơn hàng, đối tác, campaign/promotion.
Rà soát báo cáo vận hành định kỳ.

SOP chuẩn theo case

Xác định mục tiêu nghiệp vụ và phạm vi tác động.
Kiểm tra permission trước thao tác.
Nếu thao tác rủi ro cao: test trên staging trước.
Ghi ticket + log thao tác.
Đối chiếu UI, API và audit log sau khi hoàn thành.

Template mô tả thao tác

Case: Khóa tài khoản user
Mục đích: Ngăn truy cập rủi ro
Bước chính: User Management -> Search -> Lock -> Confirm
Kết quả kiểm tra: user không login được, audit log có bản ghi

Nhóm nghiệp vụ PM

Quản lý product master, listing, item, SKU.
Quản lý category/vendor/platform/country/operator/currency.
Publish/unpublish nội dung sản phẩm.
Theo dõi đồng bộ API PM và dữ liệu hiển thị storefront.

SOP thao tác PM

Chọn đúng môi trường (staging hoặc prod).
Luồng chuẩn: Save Draft -> Verify -> Publish.
Với thay đổi diện rộng: thông báo ticket cho team liên quan.
Kiểm tra phản hồi từ API PM sau cập nhật.
Ghi log thay đổi (ai, thời điểm, nội dung).

Checklist vận hành tuần

Rà soát thay đổi schema và đồng bộ docs.
Kiểm tra lệch dữ liệu giữa PM Admin và API PM.
Cập nhật case mới vào SOP nếu có issue thực tế.
Xác nhận owner/backup owner cho từng nhóm màn hình.