Skip to content

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:

  1. 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-admin phải nhận ra được app-user.
  2. Feature-first, lớp sạch bên trong feature. Đơn vị mang data / domain / presentation là feature, không phải toàn app. Không có usecase-class cho từng hành động.
  3. App mỏng. Cái gì hai app dùng chung được thì thành package.

Phụ thuộc một chiều ​

appsapp-user · app-salepi_featuresfeature dùng chungpi_servicesgraphql · httppi_uipi_localizationpi_corecopy-freepi_pipointchỉ app-userPhụ thuộc một chiều. pi_core và pi_services không chứa chữ hiển thị.
PackageGiữ gìTương đương bên web
pi_coreHằng số, PiRoutes, Result<T>, PiFailure, reader JSON, logger@pi/web-constants
pi_servicesNơi duy nhất import graphql, http, flutter_secure_storage. Phiên PIDEAL, PiApi, PiRpc@pi/web-services
pi_pipointClient PiPoint. Nơi duy nhất import Firebase; chỉ app-user dùng—
pi_uiDesign system, widget Pi*, token theme@pi/ui
pi_localizationslang (vi gốc + en), và cả định dạng số/tiền/ngày/điện thoại@pi/web-localization
pi_featuresFeature 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à Equatable mang một status enum (initial · loading · success · failure) cộng một PiFailure?. 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.dart gọ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ên bloc_test không chạm get_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ầngNhậnTrảKhông bao giờ
pi_servicesexception của SDK, lỗi socket/timeoutResult<T> với PiFailuređể lọt kiểu của SDK ra ngoài
repositoryResult<T>Result<T>bắt lỗi, log, hiển thị
blocResult<T>state có status + failurelưu một chuỗi thông báo
screenstate.failuretoast / lỗi inline / error viewrẽ 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ụcNói chuyện vớiGửi gì
graphql/ — PiApifunction graphqlmột tài liệu GraphQL
rpc/ — PiRpcmọi function khácmộ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 khi

pi_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ền

SessionState 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:

AppChính sáchHành vi
Sale AppAuthPolicy.requiredMọi route trừ route đăng nhập đều cần READY
User AppAuthPolicy.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.

→ Đường dẫn app mobile

Chế độ mock: chạy không cần backend ​

DATA_SOURCE=mock thay đúng ba thứ ở biên service:

Dịch vụremotemock
PiApiHttpLink → Edge FunctionFixtureLink — trả lời từ handler
PiRpcHTTPFixtureRpcTransport
PiSessionphiên PIDEAL thậtFakePiSession — 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 env

Lư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   # slang

File 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.

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

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-widgetbook

Widgetbook (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.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17