Archive note

• This file preserves the pre-refactor ecosystem/deferred account logic snapshot.
• Active DOL English Web V2 account logic is now maintained in: ../ACC_Logic.md.

Tài khoản - Logic (Account)

🔒 DOL English Web V2 Scope Gate (áp dụng hiện tại)

• Trong scope DOL English web V2 hiện tại: 1 tài khoản = 1 user profile chuẩn.
• Không bật household parent/child, không bật switch role Learner/Parent, không bật parent billing theo profile con.
• Các tier tài khoản áp dụng: Free, Pro, Pro Max; quyền truy cập khóa học vẫn mua lẻ tách riêng.
• Các phần parent/household/đa profile bên dưới được giữ làm logic tham chiếu hệ sinh thái (deferred), chỉ kích hoạt nếu có quyết định mở scope mới.

🎯 Scope & 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
• Tối giản thao tác, inline flows, re-auth cho hành động nhạy cảm

---

🧭 Entry Points

• Avatar menu: Tài khoản
• Post-signup: từ Welcome popup
• Deep link: Subscription, Billing
• SSO từ các domain khác trong hệ sinh thái (app.dolenglish.vn, marketing microsite, dolparents.vn, operation.doledu.vn…), giữ cùng session/identity.

---

🌐 Ecosystem & Domain Model

• Một dịch vụ user/identity chung cho toàn bộ sản phẩm (app/microsite quốc tế, phụ huynh, giáo viên, CRM/admin), tái sử dụng hệ thống payment, xếp lớp/lịch, CRM, teacher assignment.
• UI có thể thay đổi theo domain nhưng không tạo thêm user riêng; login một lần, đi qua các site vẫn giữ session (SSO).
• International/Exam sites (BTE/SAT/GMAT/GAEJON…): login-only (không cho tự signup); hỏi “Bạn đã có tài khoản DOL chưa?” rồi cho đăng nhập bằng tài khoản hiện có.
• Parent portal (dolparents.vn): xem toàn bộ con và dịch vụ đang dùng trong toàn bộ hệ sinh thái; dùng chung identity với app học.
• Domain chính:
  • app.dolenglish.vn: sản phẩm học tập chính (teaching tool, video, bài tập, assignment, phòng thi ảo, AI assistant).
  • dolenglish.vn: marketing/landing; header cần link tới app, kit.dolenglish.vn (dashboard nội bộ), donreferral (ứng viên/tuyển dụng/referral), dolparents.vn.
  • kit.dolenglish.vn: dashboard (kit) cho nội bộ/teacher; cũng dùng SSO chung.
• donreferral.*: kênh referral/apply; đăng nhập bằng tài khoản DOL.
• operation.doledu.vn/admin.doledu.vn: cấu hình role/ops.
• Parent vs Learner journeys:
  • Mua cho con: thực hiện ở app.dolenglish.vn; parent chọn/khởi tạo profile con, set Student ID + PIN; parent portal chủ yếu xem/ quản lý, không phải nơi thanh toán chính.
  • Mua cho mình: default learner flow tại app.dolenglish.vn.
  • Một email có thể vừa learner vừa parent; default mở learner, CTA “Mua cho con” dẫn sang flow parent (chọn profile con) thay vì đứng tại parent portal tách biệt.
• Auth/SSO layer:
  • IDP chung auth.doledu.vn phát hành JWT/SSO cho toàn bộ domain: app.dolenglish.vn, kid.dolenglish.vn, lms.dolschool.vn, lms.doltichhop.vn, lms.doluni.vn, parent.doledu.vn, teacher.doledu.vn, cs.doledu.vn, admin.doledu.vn.
  • Login một nơi → SSO silent giữa các app (tin JWT từ IDP, không auth cục bộ); cookie + silent refresh + device binding (chi tiết ở Register).

---

🏗 Information Architecture

• Account Information → Họ tên, ngày sinh, gender (optional), ảnh đại diện
• Identities & Contact → Email đăng nhập, SĐT, phương thức social, Primary contact
• Security & Sessions → Password + Sessions & Devices
• Subscription → Gói hiện tại, Upgrade/Renew/Cancel
• Payments → Phương thức thanh toán (thêm/xóa/đặt mặc định)
• Notifications & Privacy → Tùy chọn thông báo, tải dữ liệu, xóa tài khoản
• Downloads → Lịch sử tải về
• Profiles & Roles → Danh sách profile, quyền Learner/Parent, PIN trẻ em
• Guardian/Parent (optional) → Thông tin phụ huynh, liên kết tài khoản

Phân tách Subscription (trạng thái gói) và Payments (phương thức thanh toán)

---

🪪 Identity Model

• userId duy nhất → ánh xạ tới nhiều identityId (Email 1, Email 2, SĐT, Google).
• Primary contact bắt buộc: chọn 1 kênh nhận thông báo chính (email hoặc SĐT); auto fallback sang kênh khác khi lỗi.
• Recovery methods tối thiểu 2 (password + OTP channel). Sau đăng ký yêu cầu bổ sung kênh phụ nếu thiếu.
• Linked accounts cho phép nối tài khoản phụ (ví dụ phụ huynh khác) nhưng không merge dữ liệu.
• SSO đa domain: cùng userId dùng cho learner, parent, teacher, operations; session chia sẻ giữa các site thuộc hệ sinh thái.
• Profile layer tách theo persona:
  • StudentProfile, ParentProfile, TeacherProfile, StaffProfile.
  • Bảng nối ParentStudent(parent_profile_id, student_profile_id, relation) cho multi-parent/multi-child; không nhân bản Student khi thêm phụ huynh.
• Role & scope:
  • Role: parent, prospect_learner, learner, teacher, cs, marketer, finance_admin, system_admin…
  • Scope: system / product_domain / center / class.
  • Rule: nếu user là parent → luôn gắn parent + prospect_learner; parent quản lý con tại parent portal, không trong app learner.

---

👤 Profiles & Roles

• Mỗi userId có profileId[]. Default: Learner profile gắn với chủ tài khoản.
• Parent role thêm khi user mua “cho con” hoặc được mời quản lý → truy cập dashboard quản lý con, quyền thanh toán. Parent được cấp sẵn (không tự signup); gửi qua email/phone đã có.
• Child profiles share lịch sử học riêng, có thể chuyển thành user độc lập (tạo userId mới, giữ lịch sử).
• Parent billing → gói subscription tính phí theo số profile con đang hoạt động (billable=true); parent có thể đánh dấu profile tạm dừng để tránh tính phí kỳ sau.
• UI hỗ trợ Switch profile (dropdown + avatar) và Switch role (Learner ↔ Parent) trong header; khi email có cả learner + parent, default mở learner, cho chuyển sang parent portal (dolparents.vn) hoặc tab Parent trong app.
• Audit log: tạo profile, đổi role, chuyển ownership.
• Parent có thể tạo nhiều profile con (profile1/2/3), cấp Student ID + PIN cho từng con; login tại app bằng ID+PIN; parent quản lý tại parent portal/app; cần truyền thông rõ cho parent biết họ theo dõi được tiến độ từng con.
• Multi-parent: parent nhập student_code + DOB/PIN để liên kết con đã có; invite phụ huynh khác bằng email/SĐT → tạo thêm ParentStudent, không nhân bản child.
• Commerce flows:
  • Free practice: user login phone/email/Google → tạo User + role=prospect_learner, lưu progress vào userId.
  • Mua cho mình: tạo StudentProfile cho chính user (nếu chưa có) + role=learner, enrollment gắn profile; tùy chọn migrate progress free.
  • Mua cho con: tạo ParentProfile + role=parent, tạo StudentProfile cho con + student_code/PIN/QR (tạo user tối giản), gắn ParentStudent, enrollment gắn child; parent giữ prospect_learner.
  • Mua lần sau: chọn bé A/B hoặc thêm con mới; backend checkout chung cho parent ở app/parent portal.

---

🧒 Child Access Modes

• Parent device → Parent đăng nhập, chọn profile con, nhập PIN 4–6 số để xác thực mỗi lần đổi profile.
• Family code → Nhập Family ID + Child code + PIN trên thiết bị mới (không yêu cầu email/SĐT).
• QR pairing → Parent quét mã, cấp quyền cho thiết bị mới (tùy chọn).
• Quick sign-in code hết hạn sau 10 phút; mỗi profile có giới hạn thiết bị tin cậy; parent có thể revoke.
• Học sinh nhỏ tuổi (đặc biệt K12 < lớp 12): cho đăng nhập bằng Student ID + PIN do trung tâm cấp; parent được nhắc lưu thiết bị tin cậy và có thể reset PIN.

---

🔐 Security Rules (Re-auth & Sensitive Ops)

• Re-auth bắt buộc khi: Đổi email, Đổi SĐT, Đổi mật khẩu, Xóa tài khoản, Xóa/Thêm phương thức thanh toán, Unlink social
• Re-auth bằng Password hoặc OTP hợp lệ theo ngữ cảnh
• Rate limits tuân theo rule chung

---

📧 Change Email – Logic

• 3 bước linh hoạt:
  1. Password hiện tại
  2. Xác minh liên hệ hiện tại: OTP Email cũ hoặc OTP SĐT (cho phép chuyển bất kỳ lúc nào)
  3. OTP Email mới
• Giới hạn: 1 lần/24h
• Thất bại nhiều lần → cooldown tăng dần
• Thành công → cập nhật email, duy trì phiên

---

📱 Change Phone – Logic

• 3 bước linh hoạt:
  1. Password hiện tại
  2. Xác minh hiện tại: OTP Email hoặc OTP SĐT cũ (switch bất kỳ lúc nào)
  3. OTP SĐT mới
• Giới hạn: 1 lần/7 ngày

---

🛡 Security & Sessions – Logic

• Password:
  • Inputs: Mật khẩu hiện tại, Mật khẩu mới, Xác nhận
  • Policy: ≥ 8 ký tự, có chữ hoa, chữ thường, số
  • Strength meter + validation realtime
  • Thành công → không cần logout toàn bộ; tùy chọn Đăng xuất tất cả
• Sessions & Devices:
• Liệt kê: tên thiết bị, thời gian hoạt động, vị trí tương đối
• Hành động: Đăng xuất thiết bị này, Đăng xuất tất cả
• Cảnh báo khi đăng nhập từ thiết bị mới
• Parent xem được danh sách thiết bị của profile con; thao tác log-out yêu cầu PIN + re-auth parent.

---

🔗 Social Link/Unlink – Logic

• Link: OAuth thành công + kiểm tra xung đột email
• Unlink: chỉ khi còn ≥ 2 phương thức đăng nhập an toàn
• Unlink yêu cầu re-auth

---

🎫 Subscription – Logic

• Hiển thị: gói hiện tại, trạng thái, ngày gia hạn/hết hạn
• Hành động: Upgrade, Renew, Cancel/Resume
• Upgrade/Change plan → chuyển SB.2 (chọn gói) → Checkout
• Nếu chưa đăng nhập tại entry: inline auth (reuse PM.1/PM.2)
• Billing summary: hiển thị {activeProfiles} x {pricePerProfile} + thuế/discount; parent có thể toggle profile billable status trước kỳ mới.
• Profile selector: parent chọn profile áp dụng gói; learner chỉ thấy gói của profile hiện tại.

---

💳 Payments – Logic

• Danh sách phương thức: thẻ (mask), thương hiệu, hết hạn, Default
• Hành động: Add, Set default, Remove
• Re-auth cho thêm/xóa/đặt mặc định
• Billing info (nếu cần): tên, địa chỉ
• Không lưu dữ liệu nhạy cảm tại client; tuân thủ chuẩn nhà cung cấp
• Cho phép lưu Profile billing preference: gói nào đang được parent chi trả; hiển thị promotion đang áp dụng.
• Credit usage history (parent): bảng thao tác credit hiển thị cột Profile, Feature, Amount, Timestamp; hỗ trợ filter theo profile để parent kiểm soát việc tiêu credit của từng con.

---

⬇️ Downloads – Logic

• Liệt kê: tên file, loại, ngày, nguồn
• Re-download nếu còn hiệu lực
• Lọc theo thời gian/loại
• Lưu ý bản quyền/tái sử dụng nội dung

---

👪 Guardian/Parent (Optional) – Logic

• Trường: tên, email, SĐT, quan hệ
• Checkbox đồng thuận (nếu yêu cầu)
• Chỉ hiển thị khi áp dụng; re-auth khi cập nhật

---

🛡 OTP & Recovery – Consistency

• OTP: 6 digits, hết hạn 5 phút, Gửi lại (60s); cho phép đổi phương thức bất kỳ lúc nào
• Forgot Password: ưu tiên Email OTP, ẩn SĐT nếu chưa liên kết
• Khôi phục tài khoản theo thứ tự: Email+Password → SĐT OTP → Social → Hỗ trợ
• Nhắc cập nhật recovery sau mỗi lần thay đổi contact; parent được nhắc thiết lập PIN profile nếu chưa có.

Tham chiếu: rules-otp.mdc, rules-recovery.mdc

---

↪️ Redirect & State

• Thay đổi thông tin thành công → ở lại trang với toast/inline success
• Payment entry inline; sau auth quay lại bước đang dở
• Không dùng success pages riêng
• Cross-domain: khi người dùng nhảy từ microsite/parent/admin sang app, giữ trạng thái login và đưa tới trang tương ứng với role (Learner/Parent) thay vì yêu cầu login lại.

---

⚠️ Errors & Rate Limits

• Email/Phone conflicts, OTP sai/hết hạn/quá lần
• Network timeout → cho retry, giữ state
• Giới hạn thay đổi: Email 1/24h, Phone 1/7 ngày

---

📊 Analytics (minimal)

• 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
• bl_add_method_start/success/fail

Change Log

• 2026-02-17: Thêm scope gate cho DOL English web V2: single-user baseline, Free/Pro/Pro Max, household/parent logic để deferred.
• 2025-12-09: Thêm mô hình đa domain/SSO (auth.doledu.vn, domain list), profile/role/scope, multi-parent/child, commerce flow free→buy self/child với checkout parent chung.