Tài khoản - Logic (Account)

Scope Gate - DOL English Platform (active)

• Trong scope DOL English Platform hiện tại: 1 tài khoản = 1 user profile.
• Không triển khai household parent/child và không có switch role learner/parent trong scope active này.
• Tier tài khoản áp dụng:
  • Free
  • Pro
  • Pro Max
• Quyền khóa học vẫn mua lẻ, tách khỏi gói luyện tập.
• Toàn bộ logic hệ sinh thái/deferred đã chuyển sang:
  • ./Archive/ACC_Logic_Ecosystem_Deferred_Reference.md

Goals

• Quản trị thông tin tài khoản, bảo mật, phiên, gói học và thanh toán.
• Bao quát đầy đủ subscription lifecycle theo từng chương trình (IELTS, TOEIC, SAT, Giao tiếp).
• Giao tiếp là lane luyện tiếng Anh thông dụng, không định vị theo mục tiêu thi chứng chỉ.
• Minh bạch lịch sử mua gói và lịch sử dùng credit để user tự kiểm soát entitlement/cost.
• Giữ flow nhẹ, rõ và đúng boundary V2.

Entry Points

• Avatar menu: Tài khoản.
• Post-signup: từ Home onboarding/nudge liên quan hồ sơ.
• Deep link: Subscription, Billing.
• Deep link bổ sung: Purchase History, Credit Usage History.

Identity & Auth Baseline

• Một userId tương ứng một profile học tập trong scope V2.
• Phương thức đăng nhập:
  • Email chính hoặc email đăng nhập phụ đã verify + Password (default),
  • Email OTP (fallback khi user chủ động chọn),
  • Google.
• Login priority:
  • password-first,
  • Email OTP fallback,
  • Google là lựa chọn social duy nhất.
• Password/OTP baseline:
  • password >= 6 ký tự,
  • OTP hiệu lực 10 phút,
  • resend OTP sau 60 giây.
• Identity boundary:
  • email chính + email đăng nhập phụ đã verify là login identifiers hợp lệ của account,
  • phone là dữ liệu liên hệ (non-auth, non-recovery),
  • không merge/transfer account.
• Nếu signup nhập email đã tồn tại:
  • nếu email đã tồn tại: chuyển thẳng sang step login, prefill email, hiển thị thông báo rõ ràng.
  • không auto-send OTP mặc định ở bước handoff này.
• Google signup không bắt buộc phone ở bước tạo tài khoản:
  • vẫn cho dùng bình thường,
  • thu phone contact ở checkout/course flow theo policy CS.
• Trusted-device window: 30 ngày.
• Hành động nhạy cảm cần re-auth (áp dụng Sensitive Identity Action Principle: yêu cầu Mật khẩu hoặc mã OTP Fallback):
  • đổi email chính,
  • đổi số điện thoại,
  • thêm/gỡ bỏ email phụ (phương thức đăng nhập),
  • đổi mật khẩu,
  • xóa tài khoản,
  • thêm/xóa phương thức thanh toán.

Information Architecture (V2 active)

• Account Information:
  • display name (optional, fallback nickname auto-generated nếu chưa nhập),
  • họ tên,
  • ngày sinh,
  • giới tính (optional),
  • ảnh đại diện.
• Identities & Contact:
  • email chính,
  • email đăng nhập phụ đã verify,
  • số điện thoại,
  • Google linked identity,
  • primary contact.
• Security & Sessions:
  • mật khẩu,
  • sessions/devices,
  • logout thiết bị.
• Subscription:
  • portfolio gói theo từng chương trình (IELTS, TOEIC, SAT, Giao tiếp),
  • mỗi program card hiển thị:
    • tier hiện tại (Free|Pro|Pro Max),
    • mechanism (Auto-renew|One-time),
    • cycle/duration hiện tại,
    • next billing hoặc expiry date theo mechanism,
    • trạng thái entitlement (active, queued, grace, cancelled).
  • action theo từng program:
    • Manage package,
    • Change plan,
    • Cancel (nếu là auto-renew),
    • Renew (nếu one-time sắp hết hạn),
  • upgrade tier cao hơn: hiệu lực ngay + prorated charge phần chu kỳ còn lại,
  • downgrade tier thấp hơn: hiệu lực kỳ kế tiếp, không hoàn tiền giữa kỳ,
  • one-time pass: không có mid-cycle downgrade/cancel refund,
  • downgrade Pro Max -> Pro: giữ số dư AI credit, lock usage cho feature vượt entitlement,
  • hiển thị rõ trạng thái credit retained but usage-locked.
• Payments:
  • phương thức thanh toán,
  • default method,
  • purchase history (subscription purchase, one-time pass, top-up, renewal),
  • lịch sử thanh toán/invoice,
  • nhãn trạng thái credit lock liên quan entitlement trong khu vực Billing/Subscription.
• Credits:
  • credit balance hiện tại theo entitlement context,
  • credit usage history: add/spend/refund/expire,
  • metadata tối thiểu mỗi event:
    • program,
    • source (topup|subscription_quota|manual_adjust|system_refund),
    • linked action (attempt/result/scoring_job) nếu có,
    • timestamp + delta + balance after.
• Notifications & Privacy:
  • channel preferences,
  • export dữ liệu,
  • xóa tài khoản.

Program-scoped Subscription Contract

• Subscription management trong Account phải tách theo program (IELTS, TOEIC, SAT, Giao tiếp) thay vì một card tổng hợp duy nhất.
• Mỗi program giữ lifecycle độc lập:
  • có thể khác mechanism/cycle,
  • có timeline billing/expiry riêng,
  • action (upgrade/downgrade/cancel/renew) áp dụng theo program đó.
• Khi đổi gói tại một program:
  • không được làm thay đổi entitlement của program khác.
• Queue overlap rule áp dụng theo từng program:
  • nếu one-time của một program còn hạn và user mua auto-renew cùng program đó,
  • auto-renew được queue sau expiry của one-time program tương ứng.

Mechanism-first Package Management Contract

• Change plan/checkout từ Account phải bám contract mechanism-first:
  • step 1: chọn Auto-renew hoặc One-time,
  • step 2:
    • Auto-renew -> Monthly|Annual,
    • One-time -> 3 tháng|6 tháng.
• Payment method visibility phải theo mechanism đã chọn:
  • Auto-renew -> Card + Momo,
  • One-time -> Card + Momo + Bank QR/Chuyển khoản.
• Không hiển thị toàn bộ method cùng lúc để tránh mismatch và giảm cognitive load.

History Surfaces Contract

• Purchase History:
  • tập trung vào item mua: package/top-up/renewal, amount, promotion, status, invoice link.
  • filter tối thiểu: program, item type, date range, status.
• Credit Usage History:
  • tập trung vào ledger event: add/spend/refund/expire.
  • filter tối thiểu: program, event type, source, date range.
  • mỗi dòng phải trace được reason rõ ràng (ví dụ: AI scoring result ID, manual adjust note).
• Cross-link rule:
  • từ purchase item có thể mở các credit events liên quan (nếu có),
  • từ credit event có thể back-link về purchase/top-up source (nếu có).

Goal/Profile Policy in Account

• Mục tiêu học tập là optional.
• User có thể chỉnh mục tiêu tại profile bất kỳ lúc nào.
• Nếu chưa có mục tiêu, không khóa tính năng account/payment.
• Goal model theo lane:
  • lane thi chứng chỉ (IELTS, TOEIC, SAT): mục tiêu điểm theo scale chương trình + ngày thi dự kiến (optional).
  • lane Giao tiếp: mục tiêu năng lực giao tiếp + mốc thời gian kỳ vọng (optional).
• Goal scale source:
  • picker target bắt buộc tham chiếu Register/REG_Goal_Scale_Catalog.md,
  • không dùng một field target-score chung cho mọi chương trình.
• Trước khi lưu goal nên có thẻ tóm tắt mục tiêu để user rà lại lựa chọn.
• Goal/profile nudge là non-blocking và theo ngữ cảnh.
• Nếu cùng lúc thiếu goal và profile milestone:
  • ưu tiên nudge goal trước.
• Tổng cap nudge goal/profile:
  • tối đa 1 lần/ngày/account.
• Chống mỏi nudge goal:
  • nếu dismiss/ignore goal nudge >=3 lần trong rolling 14 ngày và goal vẫn thiếu:
    • bật goal_nudge_soft_snooze trong 14 ngày.
  • trong soft-snooze:
    • không hiện popup goal,
    • chỉ giữ nhắc nhẹ inline theo touchpoint.
  • soft-snooze kết thúc sớm khi user mở form goal hoặc lưu goal.
• Profile completion model:
  • milestone gồm basic | academic | goal | payment,
  • payment milestone hiển thị cho mọi user,
  • payment milestone có trọng số trong % hoàn thiện hồ sơ.

Profile Visibility Defaults

• Profile sharing mặc định là private:
  • profile không public cho người ngoài cho đến khi user chủ động bật chia sẻ.
• Khi user bật public sharing:
  • public fields gồm display name, avatar, high-level badges/streak, và các chỉ số học tập dạng tổng hợp do user cho phép.
• Dữ liệu nhạy cảm luôn private mặc định:
  • email,
  • phone,
  • ngày sinh,
  • thông tin thanh toán/phương thức thanh toán,
  • billing details,
  • social links,
  • recovery/security detail.

Checkout Boundary (Account view)

• Checkout là protected flow:
  • guest phải login trước khi vào bước checkout đầu tiên.
• Checkout không yêu cầu user hoàn thành goal hoặc learning profile.
• Dữ liệu bắt buộc trong checkout chỉ là dữ liệu thanh toán liên quan giao dịch.
• Trước khi hoàn tất checkout cho Pro/Pro Max hoặc đăng ký khóa học:
  • bắt buộc email đã verify,
  • bắt buộc có số điện thoại liên hệ hợp lệ cho chăm sóc khách hàng.
• Phone contact không cần OTP verify ở checkout và không được coi là auth factor.
• Sau checkout, các dữ liệu học thuật còn thiếu được xử lý bằng nudge, không hard gate.

Redirect & State

• Thay đổi thông tin thành công -> ở lại trang + toast/inline success.
• Nếu vào payment từ context khác -> quay lại context hợp lệ sau auth/checkout.
• Nếu vừa nâng cấp gói -> quay về context khởi phát trước, chỉ hiển thị success popover nhẹ (không ép mini-tour).
• Session hết hạn -> yêu cầu đăng nhập lại và giữ returnTo nếu còn hiệu lực.

Errors & Limits

• Email conflict, OTP sai/hết hạn/quá lần, phone contact sai định dạng ở checkout/course flow.
• Timeout mạng -> cho retry và giữ state.
• Change limits:
  • Email: 1/24h.
  • Phone: 1/7 ngày.
• Password failures:
  • sai liên tiếp 5 lần -> lock 15 phút + OTP unlock path.
• New device:
  • login password trên thiết bị mới -> step-up OTP.
• Device/session concurrency:
  • số phiên hoặc thiết bị tin cậy active là policy cấu hình theo tier + slot mua thêm.
  • không định nghĩa quota theo kiểu 1 desktop + 1 tablet + 1 mobile làm mặc định.
  • khi vượt hạn: chặn login mới, hiển thị danh sách phiên đang active để user logout từ xa rồi tiếp tục.
  • nếu KID cần policy riêng, mô tả ở ACC_KID_Guardian_Managed_Overlay.md, không kéo vào baseline active này.
• Password reset:
  • OTP về email đã đăng ký.
• Contact change:
  • đổi email: re-auth -> OTP email hiện tại -> OTP email mới,
  • đổi phone: re-auth -> OTP email hiện tại -> cập nhật phone contact mới,
  • gửi security alert về email chính cũ sau thay đổi thành công,
  • không áp hold window sau đổi.
• Social recovery:
  • nếu Google account có email usable -> dùng làm recovery channel,
  • nếu không usable -> fallback qua CS recovery.
• Local password setup cho social account:
  • yêu cầu email đã verify.
• Account deletion:
  • soft-delete 30 ngày,
  • cần manual confirm để restore,
  • khi delete: cancel auto-renew ngay,
  • quá 30 ngày: hard-delete, chỉ giữ legal finance records.

Analytics (minimum)

• am_change_email_start/success/fail.
• am_change_phone_start/success/fail.
• am_link_social_start/success/fail.
• am_logout_all.
• sb_change_plan_start/success/fail.
• sb_program_manage_view.
• sb_program_change_plan_start/success/fail.
• sb_program_cancel_start/success/fail.
• sb_program_renew_start/success/fail.
• bl_add_method_start/success/fail.
• bl_purchase_history_view/filter.
• cr_history_view/filter.
• cr_event_drilldown_open.

Change Log

• 2026-03-16: Làm rõ account contact canon active: login identifiers là email-only; checkout cần signed-in + email verified + phone contact nhưng không verify phone; flow đổi email/phone đều neo vào OTP email hiện tại.
• 2026-03-04: Mở rộng scope program active: bổ sung Giao tiếp vào nhóm quản lý gói theo program trong Account (IELTS/TOEIC/SAT/Giao tiếp).
• 2026-03-03: Đồng bộ auth baseline active: chỉ còn Email + Password (default), Email OTP (fallback), Google; loại bỏ xác thực bằng số điện thoại/Facebook/passkey khỏi scope active và cập nhật checkout contact gate (email verified + phone contact).
• 2026-02-27: Mở rộng Account scope theo payment logic mới: quản lý gói theo program (baseline thời điểm đó: IELTS/TOEIC/SAT), contract mechanism-first cho đổi gói, bổ sung Purchase History và Credit Usage History.
• 2026-02-22: Bổ sung policy chống mỏi goal nudge ở cấp account: trigger >=3 dismiss/ignore trong 14 ngày -> soft-snooze 14 ngày, popup bị suppress, chỉ inline reminder; thoát sớm khi user mở/lưu goal.
• 2026-02-21: Bổ sung passkey (WebAuthn) trong baseline account: passkey quick sign-in cho account có password, quản lý passkey tại Security & Sessions, và re-auth bắt buộc cho add/remove passkey (legacy baseline, đã được thay bởi cập nhật 2026-03-03).
• 2026-02-20: Khóa baseline privacy/profile và switching: public tối thiểu + private mặc định cho dữ liệu nhạy cảm; upgrade hiệu lực ngay (prorate), downgrade kỳ kế tiếp, one-time không refund giữa kỳ.
• 2026-02-20: Bổ sung rule downgrade Pro Max -> Pro: giữ credit, lock usage ngoài entitlement.
• 2026-02-20: Đồng bộ handoff signup trùng contact: chuyển thẳng về login step + prefill, không auto-send OTP mặc định.
• 2026-02-19: Chốt guardrail Account giai đoạn đầu: lock threshold 5 lần sai/15 phút + OTP unlock path; baseline checkout contact thời điểm đó đã được thay bởi cập nhật 2026-03-03 và 2026-03-16.
• 2026-02-18: Refactor về scope active Web V2; tách logic ecosystem/deferred sang archive reference.
• 2026-02-17: Áp dụng scope gate single-user baseline cho DOL English Web V2.