> ## Documentation Index
> Fetch the complete documentation index at: https://tomotek.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# US-OWN-27: Onboarding & Tạo hồ sơ lần đầu

> Trình hướng dẫn (Wizard) gồm các bước giúp Pet Owner cập nhật thông tin cá nhân và thú cưng thiết yếu ngay lần đầu tiên đăng nhập vào ứng dụng.

> Là một người dùng mới (Pet Owner), Tôi muốn được hệ thống hướng dẫn từng bước thiết lập hồ sơ cá nhân và thú cưng, Để tôi có thể nhanh chóng bắt đầu sử dụng các tính năng mua sắm và đặt lịch phù hợp.

## 1. Điều kiện tiên quyết (Pre-conditions)

* Người dùng mới vừa đăng ký tài khoản thành công qua OTP hoặc Social Login (`US-OWN-02`).
* Ứng dụng (Frontend) kiểm tra thấy trường thông tin cá nhân bắt buộc (ví dụ: `full_name`) đang bị trống (null/empty). Đây là điều kiện tự nhiên để kích hoạt tự động luồng Onboarding mà không cần BE sửa đổi luồng Auth.

## 2. Quy trình Onboarding (Flowchart)

```mermaid theme={null}
flowchart TD
    A["Đăng nhập / Mở App"] --> B{"Profile có Tên?"}

    %% Nhánh đã có thông tin
    B -->|Đã có| M["Trang chủ (Home)"]

    %% Nhánh người dùng mới/thiếu thông tin
    B -->|Rỗng / Null| C["Màn hình Setup Profile"]
    C --> D{"Xác thực & Submit"}

    D -->|Dữ liệu lỗi| E["Hiển thị lỗi tại chỗ"]
    E --> C

    D -->|Hợp lệ| F["API: Cập nhật User Name"]
    F --> F1{"Kết quả API?"}
    F1 -->|Thất bại| E
    F1 -->|Thành công| G["Màn hình Tạo nhanh Thú cưng"]

    %% Luồng tạo thú cưng
    G --> H{"Hành động"}
    H -->|Bỏ qua / Skip| M
    H -->|Nhập thông tin| I{"Xác thực thông tin"}

    I -->|Không hợp lệ| K["Cảnh báo lỗi trường dữ liệu"]
    K --> G

    I -->|Hợp lệ| J["API: Tạo hồ sơ Thú cưng"]
    J --> J1{"Kết quả API?"}
    J1 -->|Thành công| M
    J1 -->|Thất bại| K
```

## 3. Tiêu chí chấp nhận (Acceptance Criteria) & Giao diện

> **Bước 1: Welcome & Nhập thông tin cá nhân (Bắt buộc)**
>
> * **UI/UX**: Hiển thị màn hình chào mừng "Chào mừng bạn đến với ILU PET".
> * **Trường thông tin yêu cầu**:
>   * **Ảnh đại diện (Avatar)**: Tùy chọn. Cho phép chụp ảnh trực tiếp hoặc tải lên từ thư viện thiết bị. Hỗ trợ cắt (crop) ảnh vuông 1:1. Giới hạn dung lượng 5MB, định dạng `.jpg, .png, .jpeg`.
>   * **Họ và tên**: **Bắt buộc**. Text input, độ dài 2-50 ký tự, không chứa ký tự đặc biệt không hợp lệ (như `@, #, $, %...`).
> * **Ràng buộc (Business Logic)**:
>   * Đây là bước **Hard-stop** (Bắt buộc). Người dùng không thể bấm "Bỏ qua" hoặc back lại.
>   * Nếu người dùng thoát ứng dụng (Force close) ở bước này, lần mở app tiếp theo vẫn sẽ hiện màn hình này.
>   * Nút **"Tiếp tục"** chỉ sáng lên (Enabled) khi trường "Họ và tên" hợp lệ.

> **Bước 2: Tạo nhanh Thú cưng (Tùy chọn)**
>
> * **UI/UX**: Hệ thống gợi ý câu thông điệp thân thiện: *"Bạn đang nuôi bé nào? Hãy để ILU PET làm quen nhé!"*.
> * **Trường thông tin yêu cầu**:
>   * **Ảnh thú cưng**: Tùy chọn (Tương tự avatar user).
>   * **Tên gọi (Pet Name)**: Bắt buộc nếu chọn điền form. Max 50 ký tự.
>   * **Chủng loại (Species)**: Dropdown list lấy từ Master Data (Chó, Mèo, Chim...). Bắt buộc nếu tạo thú cưng.
>   * **Giống (Breed)**: Dropdown list phụ thuộc vào Chủng loại. Cho phép search nội bộ. Có tùy chọn "Khác".
>   * **Cân nặng (Weight)**: Tùy chọn. Numeric input, lớn hơn 0 (kg).
> * **Nút hành động**:
>   * **"Lưu & Tiếp tục"**: Chỉ sáng lên khi các trường bắt buộc đã được điền. Nhấn vào sẽ gọi API tạo hồ sơ thú cưng (`is_identified = false`).
>   * **"Bỏ qua (Skip)"**: Luôn hiển thị ở góc trên bên phải hoặc dưới cùng. Cho phép người dùng lướt nhanh vào ứng dụng nếu họ chưa muốn điền thông tin thú cưng lúc này.

> **Bước 3: Hoàn tất & Điều hướng**
>
> * **UI/UX**:
>   * Hiển thị màn hình chúc mừng (Success Screen) với Lottie animation sinh động.
>   * Câu chúc mừng được cá nhân hóa: *"Tuyệt vời! Hồ sơ của \[Tên User] (và bé \[Tên Pet]) đã sẵn sàng."*
> * **Xử lý ngầm (Background Task)**:
>   * **Không cần cờ đặc biệt**: Việc API cập nhật thành công trường **Họ và tên** ở Bước 1 đã tự nhiên đánh dấu tài khoản này hoàn tất Onboarding. Ở các lần mở app sau, Frontend kiểm tra thấy `full_name != null` sẽ tự động bỏ qua luồng này.
> * **Điều hướng**:
>   * Sau 2-3 giây tự động điều hướng, hoặc khi người dùng nhấn "Bắt đầu khám phá", hệ thống sẽ chuyển hướng người dùng về **Trang chủ mua sắm** (`US-OWN-13`) hoặc **Trang khám phá Dịch vụ** (`US-OWN-19`) tùy cấu hình.

## 4. Ngoại lệ & Xử lý lỗi (Exception Handling)

| Tình huống ngoại lệ | Xử lý của hệ thống |
| - | - |
| Lỗi kết nối mạng (Network Error) khi đang lưu thông tin | Hiển thị Toast message: *"Không thể kết nối đến máy chủ. Vui lòng thử lại sau."*. Giữ nguyên dữ liệu người dùng đã điền trên form để tránh nhập lại. |
| Người dùng thoát ứng dụng (Force close) khi đang ở Bước 2 | Do Bước 1 (Tên User) là bắt buộc và được gọi API lưu ngay khi nhấn "Tiếp tục". Nếu Tên đã lưu thành công (`full_name != null`), lần mở ứng dụng tiếp theo Frontend sẽ **không** hiện lại trình Onboarding nữa. Việc tạo hồ sơ thú cưng có thể được thực hiện sau ở tab Profile. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.