pos-system/pencil-design/docs/auth-workflow-guide.md

Auth Workflow Documentation | Tài liệu Quy trình Xác thực

Mục lục

1. Tổng quan
2. Customer Authentication
3. Staff Authentication
4. Admin Authentication
5. Branch Authentication
6. Password Recovery

---

1. Tổng Quan

So sánh 4 vai trò

Yếu tố	Customer	Staff	Admin	Branch
Phương thức	Phone + OTP	Email/Phone + Password	Email + Password	Email/Phone + Password
Social Login	✅ Có	❌ Không	❌ Không	❌ Không
Đăng ký	Tự đăng ký	Admin cấp	System cấp	Admin cấp
2FA	OTP	Tùy chọn	Bắt buộc	Tùy chọn
Theme	🟠 Orange	🟢 Green	🔵 Blue	🟠 Orange

Responsive Breakpoints

Device	Width	Layout
Desktop	1440px	Split screen hoặc Centered card
Tablet	1024px	Centered card (landscape)
Mobile	390px	Full-width vertical

---

2. Customer Authentication

2.1 Login Flow

flowchart TB
    subgraph START["👤 KHÁCH HÀNG"]
        A1[Mở app/web]
    end
    
    subgraph INPUT["📱 NHẬP SĐT"]
        B1[Chọn quốc gia]
        B2[Nhập số điện thoại]
        B3[Gửi OTP]
    end
    
    subgraph OTP["🔢 XÁC THỰC OTP"]
        C1[Nhận SMS]
        C2[Nhập 6 số OTP]
        C3{OTP đúng?}
        C4[❌ Sai - Nhập lại]
        C5[⏱️ Gửi lại sau 60s]
    end
    
    subgraph SUCCESS["✅ THÀNH CÔNG"]
        D1[Xác thực OK]
        D2[Chuyển trang chính]
    end
    
    A1 --> B1 --> B2 --> B3
    B3 --> C1 --> C2 --> C3
    C3 -->|Sai| C4 --> C2
    C3 -->|Hết lần| C5 --> B3
    C3 -->|Đúng| D1 --> D2

2.2 Social Login Flow

flowchart LR
    A[Chọn mạng xã hội] --> B{Loại?}
    B -->|Google| C[Google OAuth]
    B -->|Apple| D[Apple Sign-in]
    B -->|Zalo| E[Zalo OAuth]
    B -->|Facebook| F[Facebook OAuth]
    C & D & E & F --> G[Lấy profile]
    G --> H{Đã có tài khoản?}
    H -->|Có| I[Liên kết & Đăng nhập]
    H -->|Không| J[Tạo mới & Đăng nhập]
    I & J --> K[✅ Thành công]

2.3 Register Flow

flowchart TB
    subgraph INFO["📝 THÔNG TIN"]
        A1[Nhập họ tên]
        A2[Nhập SĐT]
        A3[Nhập email - tùy chọn]
        A4[Đồng ý điều khoản]
    end
    
    subgraph VERIFY["🔐 XÁC THỰC"]
        B1[Gửi OTP]
        B2[Nhập OTP]
        B3{Xác thực OK?}
    end
    
    subgraph COMPLETE["🎉 HOÀN TẤT"]
        C1[Tạo tài khoản]
        C2[Chuyển trang chính]
    end
    
    A1 --> A2 --> A3 --> A4
    A4 --> B1 --> B2 --> B3
    B3 -->|Thất bại| B1
    B3 -->|Thành công| C1 --> C2

Screens

Bước	Screen	Files
Login	Phone input	customer-desktop.pen, customer-tablet.pen, customer-mobile.pen
OTP	OTP verify	Tích hợp trong login page
Register	Form đăng ký	register/customer-*.pen

---

3. Staff Authentication

Login Flow

flowchart TB
    subgraph START["👨‍💼 NHÂN VIÊN"]
        A1[Mở app POS]
    end
    
    subgraph LOGIN["🔐 ĐĂNG NHẬP"]
        B1[Nhập tài khoản được cấp]
        B2[Nhập mật khẩu]
        B3{Xác thực?}
        B4[❌ Sai - Thử lại]
    end
    
    subgraph SHIFT["⏰ CA LÀM"]
        C1[Chọn chi nhánh]
        C2[Bắt đầu ca]
        C3[Vào POS chính]
    end
    
    A1 --> B1 --> B2 --> B3
    B3 -->|Sai| B4 --> B1
    B3 -->|Đúng| C1 --> C2 --> C3

Screens

Bước	Screen	Files
Login	Email/Password	staff-desktop.pen, staff-tablet.pen, staff-mobile.pen

---

4. Admin Authentication

Login Flow

flowchart TB
    subgraph START["🔒 ADMIN"]
        A1[Truy cập admin panel]
    end
    
    subgraph AUTH["🛡️ BẢO MẬT CAO"]
        B1[Nhập email admin]
        B2[Nhập mật khẩu]
        B3{Xác thực?}
        B4[❌ Sai - 5 lần khóa 30p]
    end
    
    subgraph 2FA["🔐 XÁC THỰC 2 LỚP"]
        C1[Nhập mã 2FA]
        C2[Authenticator App]
        C3{Mã đúng?}
    end
    
    subgraph SUCCESS["✅ ĐĂNG NHẬP"]
        D1[Ghi log audit]
        D2[Vào dashboard admin]
    end
    
    A1 --> B1 --> B2 --> B3
    B3 -->|Sai| B4 --> B1
    B3 -->|Đúng| C1
    C1 --> C2 --> C3
    C3 -->|Sai| C1
    C3 -->|Đúng| D1 --> D2

Security Features

• 🔒 Khóa sau 5 lần nhập sai (30 phút)
• 🛡️ Bắt buộc 2FA
• 📝 Ghi log đăng nhập
• ⏱️ Session timeout 30 phút

Screens

Bước	Screen	Files
Login	Email/Password + 2FA	admin-desktop.pen, admin-tablet.pen, admin-mobile.pen

---

5. Branch Authentication

Login Flow

flowchart TB
    subgraph START["🏪 CHI NHÁNH"]
        A1[Truy cập portal]
    end
    
    subgraph AUTH["🔐 ĐĂNG NHẬP"]
        B1[Nhập email chi nhánh]
        B2[Nhập mật khẩu]
        B3{Xác thực?}
    end
    
    subgraph DASHBOARD["📊 QUẢN LÝ"]
        C1[Xem thống kê]
        C2[Quản lý nhân viên]
        C3[Báo cáo doanh thu]
    end
    
    A1 --> B1 --> B2 --> B3
    B3 -->|Sai| B1
    B3 -->|Đúng| C1
    C1 --> C2 --> C3

Screens

Bước	Screen	Files
Login	Email/Password	branch-desktop.pen, branch-tablet.pen, branch-mobile.pen

---

6. Password Recovery

Forgot Password Flow

flowchart TB
    subgraph REQUEST["📧 YÊU CẦU"]
        A1[Nhấn Quên mật khẩu]
        A2[Nhập email/SĐT]
        A3[Gửi yêu cầu]
    end
    
    subgraph VERIFY["✉️ XÁC MINH"]
        B1[Nhận email/SMS]
        B2[Click link reset]
        B3[Hoặc nhập code]
    end
    
    subgraph RESET["🔄 ĐẶT LẠI"]
        C1[Nhập mật khẩu mới]
        C2[Xác nhận mật khẩu]
        C3{Hợp lệ?}
        C4[❌ Không đủ mạnh]
    end
    
    subgraph DONE["✅ HOÀN TẤT"]
        D1[Cập nhật thành công]
        D2[Chuyển trang login]
    end
    
    A1 --> A2 --> A3
    A3 --> B1 --> B2 --> C1
    B1 --> B3 --> C1
    C1 --> C2 --> C3
    C3 -->|Yếu| C4 --> C1
    C3 -->|Mạnh| D1 --> D2

Password Requirements

Yêu cầu mật khẩu:
- Tối thiểu 8 ký tự
- Có chữ hoa (A-Z)
- Có chữ thường (a-z)
- Có số (0-9)
- Có ký tự đặc biệt (!@#$%^&*)

Screens

Bước	Screen	Files
Request	Form nhập email	forgot-password/desktop.pen, tablet.pen, mobile.pen
Confirm	Thông báo đã gửi	Tích hợp trong forgot-password
Reset	Form đặt lại	(Cần tạo thêm)

---

Tổng hợp Files

src/pages/auth/
├── login/
│   ├── customer-{desktop,tablet,mobile}.pen
│   ├── staff-{desktop,tablet,mobile}.pen
│   ├── admin-{desktop,tablet,mobile}.pen
│   └── branch-{desktop,tablet,mobile}.pen
├── register/
│   └── customer-{desktop,tablet,mobile}.pen
├── forgot-password/
│   └── {desktop,tablet,mobile}.pen
└── workflow/
    ├── otp-verify.pen        # OTP input + Success state
    ├── password-reset.pen    # Form + Success state
    ├── two-factor-auth.pen   # 2FA for Admin
    └── email-sent.pen        # Confirmation screen

Tổng: 22 files (18 auth pages + 4 workflow screens)