Giao diện
Kiến trúc mobile
Hai app Flutter — User App (khách hàng) và Sale App (nhân viên bán hàng) — trong một pub workspace với một lockfile. Sale App đang tạm dừng phát triển; xem Phạm vi & độ tin cậy.
Phần chung cho cả ba phía ở Kiến trúc chung.
Ba nguyên tắc, theo đúng thứ tự ưu tiên:
- Giống web. Cùng cách chia package, cùng luật "style nằm trong kit", cùng nghĩa của route guard. Người biết
web-adminphải nhận ra đượcapp-user. - Feature-first, lớp sạch bên trong feature. Đơn vị mang
data / domain / presentationlà feature, không phải toàn app. Không có usecase-class cho từng hành động. - App mỏng. Cái gì hai app dùng chung được thì thành package.
Phụ thuộc một chiều
| Package | Giữ gì | Tương đương bên web |
|---|---|---|
pi_core | Hằng số, PiRoutes, Result<T>, PiFailure, reader JSON, logger | @pi/web-constants |
pi_services | Nơi duy nhất import graphql, http, flutter_secure_storage. Phiên PIDEAL, PiApi, PiRpc | @pi/web-services |
pi_pipoint | Client PiPoint. Nơi duy nhất import Firebase; chỉ app-user dùng | — |
pi_ui | Design system, widget Pi*, token theme | @pi/ui |
pi_localization | slang (vi gốc + en), và cả định dạng số/tiền/ngày/điện thoại | @pi/web-localization |
pi_features | Feature dùng chung, một library cho mỗi feature | — |
pi_core và pi_services copy-free: chúng trả về mã lỗi, không bao giờ trả chuỗi hiển thị. Package feature mới bridge mã sang khoá từ điển — đó là điểm lệch có chủ ý so với web, vì feature ở đây có cả màn hình.
lib/ là gốc của mọi package — không có lib/src/. Barrel (lib/pi_core.dart, lib/<feature>.dart) vẫn là bề mặt công khai và là thứ duy nhất package khác import.
Tên file kebab-case, kể cả Dart (sign-in-screen.dart, pi-button.dart). Import và part của Dart là URI nên không sao; lint file_names đã tắt. Hai ngoại lệ do công cụ bắt buộc: *_test.dart (cách flutter test tìm test) và file sinh *.g.dart / *.graphql.dart. Tên package Dart vẫn snake_case (pi_core) vì đó là định danh, không phải tên file.
Bên trong một feature
auth/
├── data/ repository — chỉ nói chuyện với pi_services, trả Result<T>
├── domain/ chỉ tạo khi feature có quy tắc thật
└── presentation/
├── sign-in/ một thư mục cho một màn
│ ├── sign-in-screen.dart BlocProvider + BlocBuilder, composes Pi*
│ ├── sign-in-bloc.dart
│ ├── sign-in-event.dart part of; sealed class
│ └── sign-in-state.dart part of; Equatable
└── shared/ widget dùng lại giữa các màn của feature- Bloc, không Cubit. Event là sealed class; state là
Equatablemang mộtstatusenum (initial · loading · success · failure) cộng mộtPiFailure?. Một bloc cho một màn. State dùng chung cả app (phiên) là bloc ở gốc. - get_it: mỗi package có
void register<Name>(GetIt sl);bootstrap.dartgọi chúng theo thứ tự phụ thuộc.sl()chỉ được gọi trong screen để dựng bloc; bloc nhận repository qua constructor, nênbloc_testkhông chạmget_it. - Widget layout không style (
Column,Padding,ListView,SafeArea) dùng thoải mái. Cái gì có style — nút, input, card, dialog, sheet, toast, avatar, badge — phải làPi*. - Thư mục chỉ xuất hiện khi có thứ để đựng. Feature trong app bắt đầu phẳng;
presentation/<màn>/thêm khi một màn có bloc riêng,data/thêm với repository đầu tiên. Không tạo trước.
Lỗi là giá trị, không phải exception
Đây là khác biệt lớn nhất so với một app Flutter thông thường.
| Tầng | Nhận | Trả | Không bao giờ |
|---|---|---|---|
pi_services | exception của SDK, lỗi socket/timeout | Result<T> với PiFailure | để lọt kiểu của SDK ra ngoài |
| repository | Result<T> | Result<T> | bắt lỗi, log, hiển thị |
| bloc | Result<T> | state có status + failure | lưu một chuỗi thông báo |
| screen | state.failure | toast / lỗi inline / error view | rẽ nhánh theo kiểu SDK |
Chỉ có hai chỗ bắt lỗi trong toàn app: PiApi.run() cho GraphQL và PiRpc.run() cho function JSON.
status và failure luôn set cùng một lúc, bằng cách dựng state mới, không bao giờ bằng copyWith(failure: null) — copyWith thông thường là failure ?? this.failure, nên truyền null sẽ giữ lại giá trị cũ.
Rỗng là dữ liệu, không phải trạng thái. Danh sách rỗng về như Ok và màn hình vẽ trạng thái rỗng từ dữ liệu; không có status empty.
Bất cứ thứ gì khác ném ra trong repository hay bloc là bug, không phải failure, và không được bọc lại.
Hệ quả cấp phiên
bloc gặp UnauthorizedFailure → báo SessionBloc kiểm lại phiên
bloc gặp ForbiddenFailure → báo SessionBloc đọc lại `me`Bloc không bao giờ tự đăng xuất. SessionBloc là bloc duy nhất được gọi signOut().
Mọi lệnh gọi đều qua Edge Function
Hai luật trùm lên tất cả:
1. Chỉ Edge Function. App không bao giờ truy vấn bảng, không dùng Data API của Supabase, không dùng PostgREST hay Storage, không chạy SQL. Không có Supabase SDK nào trong workspace mobile; kể cả đăng nhập cũng là PiRpc gọi function auth.
2. Schema là bản sao sinh từ backend, không viết tay. schema.graphql và mọi *.graphql.dart trong pi_services do codegen tạo từ SDL backend. Một kiểu dữ liệu app cần mà schema chưa có là một thay đổi backend trước. File duy nhất được viết tay là các operation document (operations/*.graphql).
| Thư mục | Nói chuyện với | Gửi gì |
|---|---|---|
graphql/ — PiApi | function graphql | một tài liệu GraphQL |
rpc/ — PiRpc | mọi function khác | một body JSON |
Tên thư mục nói hình dạng của lệnh gọi, không nói nơi đến — cả hai đều tới Edge Function.
Không có cache chuẩn hoá (fetchPolicy: noCache) — bloc giữ state. Cùng lý do với việc web chọn graphql-request thay vì Apollo.
Ngoại lệ PiPoint, có kiểm soát
User App đăng nhập bằng OTP của PiPoint. Đường đi:
pi_pipoint gọi callable Firebase của PiPoint → lấy PiPoint ID token
pi_services nhận token dưới dạng chuỗi → POST auth/pipoint/exchange
→ nhận phiên PIDEAL như mọi khipi_services không bao giờ import Firebase, và backend không bao giờ thấy OTP, custom token hay refresh token của PiPoint. Mọi lần refresh phiên đều gửi kèm PiPoint ID token; token chết hoặc khác uid thì phiên kết thúc.
Sale App không có Firebase.
Phiên và điều hướng
SessionBloc là bản mobile của RequireAuth, hai cổng giống hệt:
khởi động → chưa rõ (màn splash)
không có phiên → đã đăng xuất
có phiên → gọi me()
├─ nextStep READY → sẵn sàng
└─ còn lại → chờ quyềnSessionState là sealed hierarchy chứ không phải status enum, vì mỗi trạng thái mang payload khác nhau. Trong lúc chưa rõ, router đỗ ở /splash?from=<đích> rồi quay lại from khi đã rõ.
Chính sách gác khai một lần trong router.dart:
| App | Chính sách | Hành vi |
|---|---|---|
| Sale App | AuthPolicy.required | Mọi route trừ route đăng nhập đều cần READY |
| User App | AuthPolicy.optional(protected: …) | Xem hàng là công khai; chỉ route trong tập protected mới đẩy sang đăng nhập, rồi quay lại đúng chỗ |
Không có if (app == …) nào bên trong feature.
Tab: mỗi app khai danh sách AppTab trong lib/tabs.dart, và tabShellRoute(tabs) dựng shell. Nhãn đọc từ từ điển lúc build nên đổi ngôn ngữ là bar đổi theo. Thêm một tab là ba sửa đổi — đường dẫn trong PiRoutes, khoá nav.*, một mục trong tabs.dart — không sửa router.
Chế độ mock: chạy không cần backend
DATA_SOURCE=mock thay đúng ba thứ ở biên service:
| Dịch vụ | remote | mock |
|---|---|---|
PiApi | HttpLink → Edge Function | FixtureLink — trả lời từ handler |
PiRpc | HTTP | FixtureRpcTransport |
PiSession | phiên PIDEAL thật | FakePiSession — trong bộ nhớ |
Feature, repository và bloc chạy y nguyên, và toàn bộ đường parse dữ liệu thật (fromJson sinh ra, PiApi.run(), mapping) vẫn được chạy qua. Đây là điểm khác với việc mock từng repository.
Mỗi operation GraphQL và mỗi function JSON phải có một fixture; thiếu thì trả lỗi internal nhìn thấy được, không âm thầm trả rỗng. Fixture được giữ trạng thái trong bộ nhớ, nên một mutation đổi được kết quả của query kế tiếp.
bash
pnpm exec nx run app-user:run --configuration=mock # không backend, không file envLưu trữ phiên
Token nằm trong Keychain / Keystore, không nằm trong SharedPreferences. Lớp bọc có hai lời hứa: nó không bao giờ ném exception (keystore lỗi nghĩa là "đã đăng xuất") và không bao giờ log token.
Lần chạy đầu sau khi nâng cấp, app xoá phiên mà SDK cũ để lại trên máy — việc này idempotent và không bao giờ ném lỗi.
Codegen và flavor
bash
pnpm exec nx gen app-services # graphql_codegen, sau khi backend schema:export
pnpm exec nx gen app-localization # slangFile sinh ra được commit.
Mỗi app có hai flavor native, dev và staging, với bundle id riêng nên cài song song được; local và mock chạy trên flavor dev. Không có flavor cho uat hay production.
Kiểm thử và catalog
flutter_test + bloc_test + mocktail, hiện chỉ unit test.
bash
pnpm exec nx run-many -t analyze test -p tag:scope:mobile
pnpm exec nx check-coverage app-widgetbookWidgetbook (apps/app-widgetbook) là catalog component — bản mobile của Storybook, use case viết tay, xem trên simulator hoặc dựng thành site tĩnh. check-coverage fail khi một widget Pi* được export mà chưa có use case — đúng lời hứa mà web có với check-coverage web-storybook.
Trong CI, test của mỗi package được gom thành một lần biên dịch: một entry import mọi file test rồi chạy trong một lệnh flutter test; file nào cần isolate riêng thì khai trong danh sách kèm lý do. Không file test nào bị bỏ qua, và có một check riêng fail khi một file test không nằm trong danh sách nào.
Nguồn: docs/technical/12-mobile-architecture.md, 06-package-app-ui.md, 19-mobile-flavors-cicd.md, code/packages/app-ui/CLAUDE.md, và code trong code/apps/app-user/, code/packages/app-*/. Trang viết tay — xem mức độ tin cậy.