Skip to content

Kiến trúc front-end ​

Web Admin là React 19 + Vite SPA. Không server render; mọi dữ liệu lấy qua một endpoint GraphQL. Phần chung cho cả ba phía ở Kiến trúc chung.

Bốn package, mỗi package một việc ​

ImportGiữ gìKhông giữ gì
@pi/uiToàn bộ component và styleChữ hiển thị, route, lệnh gọi API
@pi/web-constantsROUTING_PATH, cây ADMIN_NAVComponent, logic
@pi/web-servicesPhiên PIDEAL, API auth/MFA, SDK GraphQL có kiểuChữ hiển thị (chỉ trả mã lỗi)
@pi/web-localizationMọi chữ, một instance i18next cho mỗi appLogic

Ứng dụng khai chúng là workspace:*; đường alias trong code/tsconfig.base.json.

Phân chia này có một hệ quả quan trọng: @pi/web-services copy-free. Nó trả về mã lỗi (AuthErrorCode), còn app bridge mã sang khoá từ điển (app/auth-i18n.ts). Nhờ vậy một dịch vụ dùng được cho nhiều app với từ điển khác nhau.

Năm luật bị review bắt nhiều nhất ​

1. UI chỉ lấy từ barrel @pi/ui. Không @radix-ui/*, không file shadcn, không đường dẫn sâu. Không export trong src/index.ts thì không phải API công khai. Style nằm trong kit, không nằm trong trang; trang chỉ dùng tối đa vài utility layout (space-y-4, grid). Mẫu lặp lại thì thành component của kit.

2. Icon chỉ qua <Icon name="…" /> dựa trên registry ICONS. Không SVG inline, không import thư viện icon trong app. Thêm icon là thêm vào registry.

3. @/* là alias dành riêng cho nội bộ @pi/ui trong toàn workspace. Code app dùng đường dẫn tương đối, và không được tạo file trùng tên với nội bộ kit (src/lib/utils.ts, src/hooks/use-mobile.ts) — sẽ che mất file thật.

4. Không viết thẳng đường dẫn route. Thêm vào ROUTING_PATH trước, rồi mới dùng trong route, <Link to>, navigate() và redirect. Đường dẫn có tham số thì dựng link bằng helper nằm cạnh hằng số (campaignDetailPath(id)), không nối chuỗi tại chỗ. → Đường dẫn Web Admin

5. Không có chữ hiển thị trong code app hay trong @pi/ui. Trang gọi t(); component của kit nhận chữ qua props (ví dụ InputPhone nhận placeholder, dialCodeLabel). Cả schema Zod cũng là factory nhận t (makeSignInSchema(t)), nên thông báo lỗi cũng đi qua từ điển.

Kit @pi/ui ​

Kit lấy từ ba nguồn, theo thứ tự ưu tiên:

  1. Animate UI (họ Radix) — nguồn chính.
  2. shadcn/ui — lấp chỗ Animate UI không có.
  3. pi/ — component riêng của PIDEAL (AdminShell, DataTable, Icon, AuthShell, FieldError, RichTextEditor…).

Component đồng bộ từ registry Animate UI bằng script. Mỗi component mới của kit phải có một story trong apps/web-storybook; nx check-coverage web-storybook fail khi một component được export mà chưa có story.

Bẫy Tailwind, đọc trước khi sync ​

Workspace dùng Tailwind v3, nhưng registry Animate UI phát hành theo cú pháp v4 (w-(--sidebar-width), --spacing(4)). Những utility đó không sinh ra gì và cũng không báo lỗi — giao diện chỉ lệch đi một cách khó hiểu.

File đã chuyển bằng tay được đưa vào SKIP_TARGETS của script sync để lần sau không bị ghi đè. Component mới sync về phải kiểm đúng mẫu này.

Cấu trúc một trang ​

src/pages/ phẳng — không lồng thư mục theo tính năng. Một thư mục cho một trang, tên có tiền tố chỉ nhóm chức năng (auth-sign-in, catalog-brand, order-detail):

pages/catalog-brand/
├── index.tsx          điểm vào: lấy view-model, chọn view, mở popup
├── view.tsx           chỉ trình bày (component từ @pi/ui)
├── use-brands.ts      view-model: form, mutation, handler
├── schema.ts          Zod, nhận `t`
├── columns.tsx        cột của DataTable
├── mobile-view.tsx    bản card cho màn hẹp
└── *.test.tsx         test đặt cạnh trang

View nhận ReturnType<typeof useX> và chỉ render. Trang nào không cần một file thì không tạo file đó.

Hạ tầng dùng chung cho cả app ở src/app/: router.tsx, require-auth.tsx, admin-layout.tsx, api.ts, use-me.ts, cộng các file route theo nhóm (order-routes.tsx, campaign-routes.tsx…).

Router và cây điều hướng ​

router.tsx sinh một route cho mỗi lá của ADMIN_NAV (trong @pi/web-constants), và render trang thật nếu nó đã đăng ký trong BUILT_PAGES, còn không thì render trang "sắp có".

Thêm một mục Admin là ba bước:

1  ROUTING_PATH   đường dẫn
2  ADMIN_NAV      mục trong cây, kèm nhãn nav.* và tên icon
3  BUILT_PAGES    trang thật

Route không nằm trong sidebar (trang soạn /cms/articles/:id) khai riêng và lấy tiêu đề từ PAGE_TITLE_KEYS; layout khớp đường dẫn có tham số bằng matchPath.

Thanh tìm kiếm trên masthead thuộc về trang, không thuộc layout. Trang danh sách gọi useAdminSearch({ placeholder, onChange }) để nói nó tìm cái gì; trang nào không đăng ký thì ô tìm kiếm ẩn.

RequireAuth gác trên quyền, không chỉ trên phiên ​

Đây là điểm dễ hiểu sai: có phiên chỉ chứng minh danh tính. RequireAuth đọc me.nextStep và đẩy mọi giá trị khác READY sang trang chờ.

Một người vừa được tạo tài khoản STAFF đăng nhập được ngay — nhưng chưa có vai trò, nên họ thấy "Chưa có quyền" cho tới khi người khác duyệt vai trò.

Quyền còn dùng để quyết định nút nào tồn tại, nhưng đó chỉ là trải nghiệm: API kiểm lại mọi lần. Giấu nút không phải là kiểm soát truy cập.

Dữ liệu và form ​

Server state: TanStack Query. Query key là mảng bắt đầu bằng tên domain (['cms', 'articles', filters]), nên một mutation vô hiệu hoá được cả nhóm bằng invalidateQueries({ queryKey: ['cms'] }).

Form: react-hook-form + Zod, schema là factory nhận t.

Danh sách luôn dùng DataTable của kit — cột, dòng, skeleton, trạng thái rỗng, phân trang phía server, chọn nhiều dòng, chọn kích thước trang. Trang không tự dựng <table>. Tập dòng đã chọn do trang giữ và giữ qua các trang phân trang; checkbox ở header chỉ tác động lên các dòng đang hiện.

Trạng thái nằm trên URL. Bộ lọc, trang và kích thước trang đi vào query string (?q=&status=&page=&size=, bỏ giá trị mặc định), nên tải lại hay gửi link vẫn giữ nguyên. Đổi kích thước trang luôn quay về trang 1.

Ngày là chuỗi ISO YYYY-MM-DD trong form state, hiển thị DD/MM/YYYY.

Rich text là RichTextEditor (Tiptap). Trang giữ tài liệu dạng JSON và gửi JSON; web không bao giờ tạo hay làm sạch HTML — server kiểm theo allow-list rồi render HTML. RichTextContent chỉ render HTML do server trả về.

Upload: trang xin API một vé (createMediaUploadUrl) rồi tải thẳng lên URL đã ký. File riêng tư không bao giờ được link trực tiếp — trang xin URL ký hạn ngắn khi người dùng bấm.

Lỗi hiện thành toast qua một helper chuyển extensions.code sang câu trong từ điển, ưu tiên message của server khi có.

Màn hẹp ​

Dưới 768px, nhiều trang danh sách đổi sang thể card thay vì bảng. Cùng một view-model được vẽ hai kiểu: truy vấn, lựa chọn và popup nào đang mở đều thuộc model, nên vượt qua ranh giới 768 không mất gì — popup đang mở vẫn là cùng một instance và bản nháp trong form còn nguyên.

Localization ​

Tiếng Việt là gốc, tiếng Anh là bản dịch. vi.ts là nguồn chuẩn có kiểu; en.ts được kiểm kiểu theo nó, nên thiếu một khoá là build fail.

Mỗi app có thư mục riêng trong packages/web-localization/src/<app>/ với instance i18next riêng — app không bao giờ import từ điển của app khác.

Kiểm thử ​

Test web là vitest, chạy thuần logic, không trình duyệt. Không có jest, không có playwright.

LệnhKiểm gì
nx test <project>vitest cho web-admin, web-services, web-ui, web-localization
nx typecheck <project>tsc cho cả 7 project web
nx check-coverage web-storybookMọi component export của @pi/ui có story

Test đặt cạnh trang (pages/catalog-brand/*.test.tsx), không gom vào một thư mục test riêng.

Môi trường và build ​

Giá trị theo môi trường qua Vite env, một file cho mỗi môi trường trong apps/web-admin/env/: .env.development (local — Vite giữ chỗ tên local), .env.dev, .env.staging, .env.uat.

vite.config.ts tắt cơ chế nạp env của Vite (envDir: false, vốn sẽ đọc cả .env và .env.local ở mọi mode) và đọc đúng một file env/.env.<mode>. Biến của shell thắng — đó là cách CI và Amplify truyền giá trị vào.

→ Môi trường & triển khai


Nguồn: docs/technical/04-front-end.md, 05-package-web-ui.md, 07–10, code/packages/web-ui/CLAUDE.md, và code trong code/apps/web-admin/src/, code/packages/web-*/. Trang viết tay — xem mức độ tin cậy.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17