SMS eSMS — Ma trận · Sơ đồ · Logic audit (đầy đủ)

Domain: D-AUTH · WP: WP-AUTH-SMS-01 · WP-FE-AUTH-SMS-ESMS-01
Ngày: 2026-08-14 · Surface: CON + API + OWNER
E2E live: chưa chạy (docs-only) — OWNER chọn done | fail | blast ok + SĐT

Liên quan: STATUS · OWNER-GATES · e2e preflight · FE wire · ready keys

1. Verdict ma trận (snapshot)

Điểm dừng agent: không blast OTP trừ khi OWNER gửi blast ok + SĐT E.164.

2. Ma trận traceability D-AUTH · SMS

Surfaces: CON (consumer phone) · API shared · DRV/PAR có thể reuse cùng endpoint với surface (chưa e2e riêng).

3. Sơ đồ kiến trúc (happy path)

sequenceDiagram
  autonumber
  actor U as User CON
  participant App as PhoneFirebaseScreen
  participant Ctx as AuthContext
  participant API as Nest /auth/otp
  participant Store as OTP Store Redis
  participant SMS as SmsService eSMS
  participant ES as rest.esms.vn

  U->>App: Nhập SĐT +84… · Gửi OTP
  App->>Ctx: sendPhoneOtp(+84…)
  Ctx->>API: POST /otp/send {phone, surface:CONSUMER}
  API->>API: validate VN phone · rate-limit · lock?
  API->>Store: set(phone, code, TTL)
  API->>SMS: sendOtp(phone, code)
  SMS->>ES: SendMultipleMessage_V4 (Brandname=WELIFE)
  ES-->>SMS: CodeResult=100 · SMSID
  SMS-->>API: {provider:esms, sent:true}
  API-->>Ctx: {success, smsProvider, smsSent, expiresInSec}
  Ctx-->>App: hint WELIFE · step=code
  ES-->>U: SMS OTP brand WELIFE

  U->>App: Nhập 6 số · Xác nhận
  App->>Ctx: verifyPhoneOtp(+84…, otp)
  Ctx->>API: POST /otp/verify
  API->>Store: get · match · del · clearFailures
  API->>API: findOrCreateByPhone · issueTokens
  API-->>Ctx: accessToken · refreshToken · user
  Ctx->>Ctx: setTokens · UsersApi.me · chat/push
  Ctx-->>App: session ready → Home

4. Sơ đồ quyết định OWNER reply

flowchart TD
  A[OWNER thử e2e trên app prod] --> B{Kết quả?}
  B -->|SMS eSMS done| C[PASS gate SMS]
  B -->|SMS eSMS fail: lỗi| D[Phân loại fail]
  B -->|blast ok + SĐT| E{Agent có SĐT E.164?}
  B -->|docs only / chưa thử| F[Giữ PENDING · không blast]

  C --> C1[Cập nhật STATUS SMS = PASS]
  C --> C2[Next: Pay hoặc MoMo]

  D --> D1{Fail ở đâu?}
  D1 -->|Gửi OTP API lỗi| D2[503 esms / 429 lock / 400 phone]
  D1 -->|Không nhận SMS| D3[Portal eSMS · brand · credit · SĐT]
  D1 -->|Sai OTP / hết hạn| D4[TTL · attempts · clock]
  D1 -->|Login xong nhưng không Home| D5[FE applySession / me]

  E -->|Có + blast ok| E1[Agent POST /otp/send 1 lần]
  E -->|Thiếu SĐT| E2[Hỏi lại SĐT · không gửi]
  E1 --> E3[OWNER đọc SMS · verify trên app hoặc curl]
  E3 --> B

5. Logic audit — từng bước

5.1 FE send

Không còn: firebaseStartPhoneLogin trên màn phone.

5.2 API send (AuthService.sendOtp)

5.3 eSMS adapter (SmsService.sendEsms)

5.4 API verify (AuthService.verifyOtp)

5.5 FE verify

6. Ma trận outcome OWNER (điền khi có kết quả)

Hiện tại: docs-only → PENDING.

7. Ma trận fail triage (checklist)

8. Env split (audit bảo mật)

9. So sánh cũ vs mới

Email / Google vẫn có thể dùng Firebase (tuỳ bridge) — không đụng trong WP này.

10. Agent runbook (sau khi OWNER reply)

IF message contains "SMS eSMS done":
  → STATUS SMS = PASS · report PASS · stop blast
ELIF message starts "SMS eSMS fail":
  → map symptom → §7 · propose fix · no invent WP
ELIF message contains "blast ok" AND phone matches /^\+84\d{9,10}$/:
  → ONE POST prod /auth/otp/send · report smsProvider/smsSent · never print OTP
ELSE:
  → ask clarification · no send

11. File đụng (code đã IMP)

• mobile/src/features/auth/screens/PhoneFirebaseScreen.tsx
• mobile/src/features/auth/AuthContext.tsx
• mobile/src/features/auth/AuthGate.tsx
• mobile/src/features/auth/LoginScreen.tsx
• mobile/src/services/api.ts
• api/src/modules/auth/auth.controller.ts · dto/auth.dto.ts · sms.service.ts · auth.service.ts

Footer

Domain: D-AUTH
WP: WP-AUTH-SMS-01 · WP-FE-AUTH-SMS-ESMS-01
Surfaces: CON · API · OWNER
Status: WIRED · e2e PENDING (docs-only)
Local: N/A (audit docs)
Next: SMS eSMS done | fail:… | blast ok + +84…