--- url: https://docs.nemo12.com/architecture/sdd-055-nemo-ielts-app.md description: >- Bản nháp NEMO IELTS (SDD-055): app Flutter trên backend chung, công nghệ, giao diện, token và các đợt code theo PRD-010. --- # SDD-055 - NEMO IELTS (Flutter) Yêu cầu: [PRD-010](../product/prd-010-nemo-ielts-app.md). Trạng thái **draft 0.2**: đợt 0 đã code ngày 28.09.2026 ở `apps/ielts-mobile/` (mã Dart, test, workflow `ielts-mobile.yml`) và `workers/api/src/modules/auth/`; chưa build trên máy thật vì thư mục `ios/` `android/` chỉ sinh được bằng `flutter create` trên máy có Flutter + Xcode (README của app). Thiết kế này ưu tiên đường ngắn nhất tới TestFlight (PRD-010 §3, đợt 0). ## 1. Hình dạng tổng thể ``` apps/ielts-mobile/ Flutter (Dart), một codebase ├─ ios/ android/ project native do `flutter create` sinh └─ lib/ api/ client HTTP gõ tay theo OpenAPI của workers/api auth/ Google + Apple → POST /v1/auth/* → token → secure storage features/home|reading|listening|speaking|writing|progress|account design/ token DS-001 dịch sang ThemeData │ HTTPS, Authorization: Bearer ▼ api.nemo12.com/v1/** workers/api (Hono) - KHÔNG có module "mobile" riêng │ D1 nemo12-platform · R2 (audio) - không bảng mới cho nội dung học ``` Nguyên tắc chọn: * **Không có backend thứ hai** (REQ-MOB-02). App gọi đúng các route learn đang gọi: `/v1/learners/{id}/ielts-*`, `/v1/public/ielts/reading|listening/*`, `/v1/me`. Mọi quyền truy cập vẫn đi qua `canAccessLearner`, nên app không mở thêm cửa nào. * **Đổi backend chỉ ở bốn chỗ**: đăng nhập Apple (§4), nhận nhiều Google client id (§4), token mới khi xoay phiên cho client Bearer (§4), và bảng token thiết bị cho push (§8, đợt 1). Mỗi chỗ có test trong `workers/api` theo skill `api-test`. * **Thư mục `apps/ielts-mobile/` không có `package.json`**, nên các cổng Node (`check-design-stack`, build CI của các app web) tự bỏ qua nó. Cổng riêng của Flutter ở §10. ## 2. Công nghệ (REQ-MOB-01) | Lớp | Chọn | Vì sao | | --- | --- | --- | | Framework | Flutter stable mới nhất; `pubspec.lock` commit sau lần `pub get` đầu tiên trên Mac | Chỉ đạo chủ dự án; "bản mới nhất" = nâng rồi ghim (luật SRC-650 áp tinh thần) | | State | `flutter_riverpod` | Ít boilerplate, test được không cần widget | | Điều hướng | `go_router` | Deep link `nemoielts://` và universal link về sau | | HTTP | `dio` + interceptor gắn Bearer và xử lý 401 | Một chỗ duy nhất đổi token | | Lưu an toàn | `flutter_secure_storage` (Keychain / Keystore) | REQ-MOB-04 | | Đăng nhập | `google_sign_in`, `sign_in_with_apple` | §4 | | Audio | `just_audio` + `audio_session` (phát khi khoá màn), `record` (ghi) | REQ-MOB-06, REQ-MOB-09 | | Lưu offline | `drift` (SQLite) | Đợt 2, REQ-MOB-12 | | Push | `firebase_messaging` | Đợt 1, REQ-MOB-11; FCM gửi được cả APNs | Không thêm thư viện UI bên thứ ba (không `getwidget`, không bộ component trả phí): widget Material 3 của Flutter + theme dịch từ token là đủ, đúng tinh thần "không thêm thứ tư" của DS-001. ## 3. Giao diện và token (REQ-MOB-16) * Một script (chưa dựng, dự định đặt ở `scripts/tokens-to-dart.mjs`) đọc token CSS của `packages/design-system` và sinh `lib/design/tokens.g.dart` (màu sáng/tối, cỡ chữ, bo góc, khoảng cách, thời lượng chuyển động). Sinh bằng máy để web và app không lệch; file sinh có dòng "không sửa tay". * Chuyển động dùng `AnimatedSwitcher` / implicit animation của Flutter với đúng thời lượng và easing của preset `Motion.tsx`. * Luật tối giản SRC-048: full-width, ít element, Home chỉ một việc. ## 4. Đăng nhập (REQ-MOB-03, REQ-MOB-04) **Chọn Google + Sign in with Apple, vì đây là đường ngắn nhất:** 1. Backend **đã có** `POST /v1/auth/google` với `client: "mobile"` trả `token`, và middleware đã nhận `Authorization: Bearer` (`workers/api/src/shared/middleware.ts`). Google trên app gần như không cần sửa backend. 2. App Store Review 4.8 bắt buộc: app có đăng nhập Google thì phải có Sign in with Apple. Không có Apple là bị từ chối, nên đây không phải lựa chọn mà là điều kiện. 3. Phương án thay thế (email + OTP) tránh được 4.8 nhưng phải dựng luồng mới, gửi thư mỗi lần đăng nhập, và learner đã quen nút Google trên web. Dài hơn. Việc ở backend (đã code 28.09.2026, `workers/api/src/modules/auth/`): | Thay đổi | Chi tiết | | --- | --- | | Nhận nhiều Google audience | `GOOGLE_CLIENT_ID` là một chuỗi. Đã thêm `GOOGLE_MOBILE_CLIENT_IDS` (iOS client id, Android client id); `verifyGoogleIdToken` nhận `aud` thuộc tập web ∪ mobile **chỉ khi `client: "mobile"`**; `client: "web"` vẫn chỉ nhận client id web, để token phát cho app không đổi được lấy cookie trình duyệt (rà soát 05.10.2026). Vẫn kiểm `iss`, `exp`, `email_verified` như cũ | | `POST /v1/auth/apple` | Nhận `identity_token` (JWT) + `name` (Apple chỉ gửi tên ở lần đầu). Kiểm chữ ký bằng JWKS `https://appleid.apple.com/auth/keys` (jose, đã có), `iss = https://appleid.apple.com`, `aud = APPLE_BUNDLE_ID` (`com.nemo12.ielts`), ghim RS256, `exp`, và **nonce bắt buộc**: app gửi chuỗi gốc trong trường `nonce`, Apple ký SHA-256 của nó vào token, server đối chiếu, nên token bị lấy cắp không phát lại được. Thiếu `APPLE_BUNDLE_ID` thì trả 503, không bao giờ xác thực. Rate limit + `audit_log 'auth.apple.rejected'` y như Google | | Tài khoản | Khớp theo `(provider, subject)` trong `auth_identities` có sẵn (cột `provider` nhận `'apple'`), **không cần migration**. Luật chống chiếm tài khoản (RISK-001) giữ nguyên: email đã thuộc một user mà danh tính Apple chưa từng gắn thì trả `CONFLICT`, không tự gộp. Nên người đã học trên web bằng Google phải chọn Google trên app; màn đăng nhập iOS đặt nút Google lên trên kèm dòng "Đã học trên web bằng Google? Chọn Google để giữ tiến độ." Apple "Hide My Email" thì thành tài khoản mới | | Xoay phiên | Phiên xoay sau 7 ngày (REQ-ACC-02) trước đây chỉ gửi token mới qua `Set-Cookie`, nên client Bearer sẽ bị đăng xuất sau 7 ngày + 60 giây ân hạn. Nay `requireSession` trả thêm header `X-Session-Token` khi request dùng Bearer (token lấy từ Bearer, nên người nhận đã cầm token cũ); app thay token trong secure storage. Header KHÔNG nằm trong `Access-Control-Expose-Headers`, nên JS chéo origin trên trình duyệt không đọc được nó | | Xoá tài khoản (REQ-MOB-15) | App gửi `POST /v1/privacy/deletion-requests` (`subject_type: 'user'`), luồng xoá có sẵn xử lý. Còn nợ: với tài khoản Apple phải gọi thêm `https://appleid.apple.com/auth/revoke`, cần khoá `.p8` của Sign in with Apple, làm trước khi nộp App Review (đợt 2) | Phiên: token mobile giữ trong secure storage. Hạn phiên theo `SESSION_MAX_AGE_S` hiện có, gia hạn trượt khi app gọi API (cùng cơ chế cookie web đang làm). 401 → xoá token, về màn đăng nhập. ## 5. Home và luồng học (REQ-MOB-05..08) | Màn | API (đã có) | | --- | --- | | Home, một việc tiếp theo | Journey Engine (SDD-045) + `/v1/learners/{id}/ielts-learning-plan` | | Setup lần đầu | `/v1/learners/{id}/ielts-setup` | | Reading / Listening | `/v1/public/ielts/reading|listening/{cluster}/{seq}` (+ `/audio`), nộp `POST .../ielts-practice-attempts` | | Progress | `/v1/learners/{id}/ielts-model`, `ielts-effort`, `ielts-journey` | | Membership (chỉ đọc) | `/v1/learners/{id}/ielts-membership` | Audio đang gác bằng `requireSession`; `just_audio` gửi header `Authorization` được, nên không cần URL ký. Thẻ `