Register - Login Documentation Guidelines for AI (Cross-domain)

Purpose

• Chuẩn hóa cách AI viết/cập nhật tài liệu login cho DOL English, DOL Academy, DOL Kid.
• Giữ tài liệu dễ đọc cho Product/Design/QA, không thiên kỹ thuật.
• Duy trì một bộ quy tắc có thể tái dùng dài hạn mà không bó cứng sáng tạo.

Writing Direction (Soft Guardrails)

• UX-first: mô tả điều user thấy và làm trước.
• Decision-first: mỗi đoạn phải giúp chốt quyết định UX.
• Core + Delta: rule dùng chung viết 1 lần ở core; domain chỉ ghi khác biệt.
• Simple language: câu ngắn, rõ nghĩa, không jargon.
• Lean docs: bỏ nội dung dài nhưng không tạo quyết định.
• Account-state framing: nếu nói về quản lý thiết bị, ưu tiên mô tả theo account/session state thay vì chia theo loại thiết bị.
• Surface clarity: nếu nói về chỗ mở auth, phải nói rõ vì sao là full-page hay popup.

Execution Model (Codex -> Antigravity -> Sync-back)

• Codex:
  • dùng để khóa login logic core trong EduDoc
  • ưu tiên đóng đủ state, edge case, rule và continuity trước khi nghĩ tới UI
• Antigravity:
  • dùng để explore UI login từ logic đã chốt
  • có thể refine layout, microcopy, interaction, và micro-logic nhỏ nếu UX tốt hơn
• Sync-back:
  • mọi thay đổi từ UI exploration phải được phân loại trước khi cập nhật về EduDoc
  • nếu delta là logic-affecting, phải cập nhật lại canon login trước khi coi đó là đúng

Artifact Split (Keep Lean)

• Logic Core:
  • nơi chốt rule login chính
  • ưu tiên dùng docs/Command/Templates/CMD_Templates_Logic.md
• Screen Flow / UI Explore:
  • nơi mô tả flow màn hình và interaction
  • ưu tiên dùng docs/Command/Templates/CMD_Templates_Screen_Flow.md
• Delta Update:
  • chỉ ghi phần mới phát sinh từ UI exploration
  • mỗi delta phải gắn 1 trong 3 nhãn:
    • visual-only
    • interaction-refinement
    • logic-affecting

Canonical Sources (Priority)

1. REG_Login_UX_Blueprint.md - nguồn quyết định UX canon.
2. REG_Login_Domain_Coverage_Matrix.md - bản đồ coverage theo domain.
3. REG_Login_One_Page_Handbook.md - bản tóm tắt để align nhanh.
4. REG_Login_Scenario_Catalog.md - danh mục tình huống cần cover.
5. REG_Login_UX_Review_Checklist.md - cổng kiểm tra trước khi chốt.
6. REG_Login_Copy_Library.md - copy core + tone overlay theo domain.
7. REG_Session_Management_Strategy.md - canon cho UX session/device.
8. REG_00_Overview.md - scope map và references tổng.

Minimal Metadata Contract (For new docs)

• domain_scope: all | dol-english | dol-academy | dol-kid
• doc_role: core | overlay | supporting
• status: draft | active | canonical
• canonical_ref: link tới file canon
• last_reviewed: YYYY-MM-DD

Required Doc Structure

• Purpose
• When to use
• Main flow
• Domain delta (nếu có)
• Edge cases
• References
• Change log

Anti-drift Rules

• Không có 2 file cùng làm “nguồn chuẩn” cho cùng 1 behavior.
• Không viết lại nguyên flow core trong file domain.
• Nếu khác biệt nhỏ, thêm vào mục Domain delta thay vì tạo file mới.
• Mọi thay đổi behavior phải cập nhật ít nhất:
  • REG_Login_UX_Blueprint.md
  • REG_Login_Domain_Coverage_Matrix.md
  • file liên quan trực tiếp
• Không mặc định viết rule quota theo desktop/tablet/mobile nếu canon chưa chốt exception đó.

Domain Acceptance Contract (Reusable)

• Cross-domain continuity:
  • cùng account phải dùng được giữa English/Academy/Kid,
  • nếu domain đích chưa có dữ liệu thì đưa vào “điểm bắt đầu phù hợp”, không báo lỗi mơ hồ.
• Sensitive Identity Action Principle:
  • tài liệu khi bàn về đổi/xoá Email hoặc số điện thoại CẦN BẮT BUỘC có bước Re-Authentication (Password hoặc OTP Fallback),
  • tuyệt đối không dùng alert confirm mỏng manh để duyệt các tác vụ rủi ro này.
• Email identity clarity:
  • nếu account dùng nhiều email đăng nhập, tài liệu phải phân biệt rõ primary email và verified login emails,
  • không được mô tả theo hướng mỗi email là một account khác nhau.
• Kid role clarity:
  • tài liệu phải thể hiện rõ ít nhất 2 trạng thái phụ huynh/học viên,
  • mỗi trạng thái có copy + CTA đúng vai trò.
• Kid parent-managed access:
  • phụ huynh có flow tạo account học cho con từ khu quản lý rõ ràng,
  • flow phụ huynh chỉ áp dụng ở domain KID, không hiển thị tại English/Academy,
  • con vào học bằng code với thông điệp dễ hiểu,
  • continuity sang English/Academy phải được mô tả rõ khi user lớn lên,
  • khi user cần tự quản account, tài liệu phải nêu rõ cơ chế nâng cấp login độc lập trên cùng account.
• Device and session clarity:
  • nếu tài liệu có nói tới giới hạn thiết bị, phải mô tả theo số phiên hoặc thiết bị active ở cấp account,
  • không mặc định chia quota theo desktop/tablet/mobile,
  • khi chạm limit phải có đường user tự quản lý thiết bị hoặc logout phiên khác.
• Surface selection clarity:
  • CTA auth toàn cục hoặc journey auth độc lập -> full-page,
  • protected action đang diễn ra trong context -> popup,
  • flow dài, role-sensitive, từ email/deep link -> full-page.
• Recovery delivery clarity:
  • nếu dùng email recovery, tài liệu phải nêu rõ OTP là đường chính trên UI,
  • có thể có link shortcut trong cùng email,
  • link lỗi phải quay về OTP, không tạo 2 logic recovery mâu thuẫn.

Creativity-safe Rules

• Được đề xuất ý tưởng UX mới nếu:
  • không phá nguyên tắc core,
  • có lợi ích rõ cho user,
  • thêm được vào matrix/checklist mà không làm docs phình to.
• Không siết theo template cứng; template là khung tham chiếu, không phải khuôn bắt buộc từng câu.

AI Quality Rubric (Weighted)

• Correctness 30% (hard gate: không mâu thuẫn canon)
• Coverage 25% (hard gate: đủ login/signup/recovery/protected-action/cross-domain)
• Risk & Safety 15% (hard gate: không tạo dead-end UX)
• Verification Evidence 15% (phải tự check bằng checklist + matrix)
• Maintainability 10% (core/delta rõ, không trùng lặp)
• Delivery Efficiency 5% (ngắn gọn, dễ reuse)

Iterative Loop (Required)

1. Analyze: đọc canon + matrix + file đang sửa.
2. Lock Logic: dùng Codex để chốt login logic core trước.
3. Explore UI: dùng Antigravity để mở hướng UI nếu cần.
4. Classify Delta: phân loại visual-only / interaction-refinement / logic-affecting.
5. Sync-back: cập nhật lại EduDoc nếu delta ảnh hưởng tới flow, state, hay rule.
6. Finalize: cập nhật references + changelog + coverage matrix nếu cần.

Reusable Prompt Snippets

• Codex / Logic Core
  • Hãy dùng canon login hiện tại để chốt logic core end-to-end. Ưu tiên state, edge case, rule, và continuity. Phân biệt rõ logic fixed và UI flexible. Giữ tài liệu ngắn gọn, không kỹ thuật hóa.
• Antigravity / UI Explore
  • Hãy dùng logic login đã chốt từ EduDoc để explore UI. Có thể refine layout, microcopy, interaction và micro-logic nhỏ. Nếu có gì đổi logic, ghi riêng thành delta và không tự coi đó là canon.
• Sync-back
  • Dựa trên kết quả UI exploration, hãy cập nhật lại tài liệu login. Chỉ giữ những thay đổi thực sự cải thiện UX. Gắn rõ delta là visual-only, interaction-refinement, hay logic-affecting.

Change log

• 2026-03-05: Chuyển guideline sang scope DOL Edu cross-domain, thêm cơ chế Core + Domain Delta và quality rubric tái sử dụng cho AI.
• 2026-03-05: Bổ sung acceptance contract cho parent-managed Kid flow và continuity khi user chuyển sang English/Academy.
• 2026-03-05: Làm rõ rule same-account upgrade khi user chuyển từ KID code sang login độc lập.
• 2026-03-05: Khóa rule Kid-only cho lane phụ huynh để tránh drift sang English/Academy.
• 2026-03-06: Bổ sung acceptance contract cho mô hình primary email + verified login emails.
• 2026-03-06: Bổ sung acceptance contract cho policy quản lý thiết bị theo account/session state, tránh quota hệ điều hành.
• 2026-03-06: Bổ sung acceptance contract cho rule chọn full-page/popup và recovery email OTP + link shortcut.