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](#1-tổng-quan)
2. [Customer Authentication](#2-customer-authentication)
3. [Staff Authentication](#3-staff-authentication)
4. [Admin Authentication](#4-admin-authentication)
5. [Branch Authentication](#5-branch-authentication)
6. [Password Recovery](#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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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)