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

# App đầu tiên

> Thực hành xây app đầu tiên theo từng bước.

Bài thực hành này hướng dẫn xây **app đầu tiên** có thể chạy được đầu-cuối theo tư duy Cleeksy: bắt đầu từ **một bài toán nghiệp vụ cụ thể**, sau đó cấu hình **App → Entity → Fields → Form → View → Workflow → Roles**.

<Info>
  Tài liệu ví dụ “Purchase Request Handling” mô tả yêu cầu nghiệp vụ, luồng xử lý và các field đề xuất.
</Info>

## Mục tiêu học tập

Hoàn thành bài thực hành này sẽ có một app với:

* 1 entity **Purchase Request** và các field chính
* UI tối thiểu: **Grid view** + **Record layout**
* Workflow phản ánh luồng: tạo yêu cầu → phê duyệt → xử lý mua sắm → hoàn tất/đóng
* Phân quyền theo vai trò và kiểm thử end-to-end

<Note>
  Theo SDD, một **value slice** khi triển khai có thể gồm **một hoặc nhiều app**. Quickstart này tập trung vào việc hoàn thành **một app đầu tiên** trong phạm vi bài toán Purchase Request.
</Note>

## Kịch bản nghiệp vụ (Purchase Request)

**Mục tiêu nghiệp vụ:** Cho phép nhân viên gửi yêu cầu mua sắm (laptop, phụ kiện, phần mềm, vật tư…), đi qua phê duyệt của Trưởng nhóm/Trưởng phòng trước khi chuyển sang bộ phận Procurement xử lý. Trạng thái cần được cập nhật và thông báo theo từng bước.

**Luồng chính (tối thiểu):**

1. Nhân viên tạo Purchase Request
2. Trưởng nhóm/Trưởng phòng review và Approve/Reject
3. Nếu Approve → chuyển sang Procurement xử lý
4. Nếu Reject → đóng request
5. Người yêu cầu theo dõi trạng thái
6. Procurement hoàn tất → cập nhật trạng thái nhận hàng

## Điều kiện tiên quyết

* Có quyền tạo App trong Space
* Có thể tạo và gán vai trò (Requester/Approver/Procurement)

***

## Thiết kế dữ liệu tối thiểu

### Entity: Purchase Request

Các field đề xuất (có thể điều chỉnh theo tổ chức):

| Field (EN)      | Nhãn (VI)       | Kiểu dữ liệu      | Bắt buộc | Ghi chú                                                                        |
| --------------- | --------------- | ----------------- | -------- | ------------------------------------------------------------------------------ |
| Request No      | Số yêu cầu      | Auto number       | Tự sinh  | Hệ thống sinh                                                                  |
| Title           | Tiêu đề         | Text (short)      | Có       | Mô tả ngắn                                                                     |
| Requester       | Người yêu cầu   | People/User       | Có       | Người gửi                                                                      |
| Department      | Phòng ban       | Choice/Text       | Có       | Phục vụ routing                                                                |
| Category        | Loại mua        | Choice            | Có       | Laptop, Software…                                                              |
| Description     | Mô tả chi tiết  | Long text         | Có       | Lý do                                                                          |
| Estimated Cost  | Chi phí dự kiến | Number/Currency   | Không    |                                                                                |
| Status          | Trạng thái      | Choice            | Có       | Draft, Pending Approval, Approved, Rejected, In Procurement, Completed, Closed |
| Approver        | Người phê duyệt | People/User       | Hệ thống | Trưởng nhóm/phòng                                                              |
| Procurement PIC | Người xử lý mua | People/User       | Hệ thống |                                                                                |
| Created on      | Ngày tạo        | DateTime (System) | Tự sinh  |                                                                                |

***

## Các bước thực hiện

<Steps>
  <Step title="Bước 1 — Tạo App">
    Tạo app mới: <code>Purchase Request Handling</code>.

    Mục tiêu: tạo “work system container” để cấu hình dữ liệu + UI + workflow + vai trò.
  </Step>

  <Step title="Bước 2 — Tạo Entity và Fields">
    Tạo entity: <code>Purchase Request</code>, sau đó thêm các field theo bảng “Thiết kế dữ liệu tối thiểu”.

    ✅ Kết quả: có thể tạo record “Purchase Request” với thông tin và trạng thái ban đầu.

    Xem thêm: [Thực thể dữ liệu (Entity)](/build-apps/data-modeling/entities) và [Kiểu trường dữ liệu (Field types)](/build-apps/data-modeling/field-types).
  </Step>

  <Step title="Bước 3 — Tạo Grid view (UI làm việc hằng ngày)">
    Tạo **Grid view** cho entity <code>Purchase Request</code>.

    Cột gợi ý:

    * Request No, Title, Requester, Department, Category, Estimated Cost, Status, Created on

    Cấu hình tối thiểu:

    * Sort theo <code>Created on</code> (mới nhất trước)
    * Filter theo <code>Status</code> (tuỳ nhóm sử dụng)

    Xem chi tiết: [Dạng bảng (Grid view)](/build-apps/ui-views/grid-view).
  </Step>

  <Step title="Bước 4 — Thiết kế Record layout (form/chi tiết record)">
    Thiết kế **Record layout** theo nhóm thông tin:

    * Thông tin yêu cầu (Request No, Title, Description, Category, Estimated Cost)
    * Thông tin tổ chức (Requester, Department, Created on)
    * Thông tin xử lý (Status, Approver, Procurement PIC)

    Mục tiêu: giảm lỗi nhập liệu, ưu tiên các trường quan trọng ở phần đầu.

    Xem chi tiết: [Bố cục bản ghi (Record layout)](/build-apps/ui-views/record-layout).
  </Step>

  <Step title="Bước 5 — Tạo Workflow tối thiểu (phản ánh luồng xử lý)">
    Thiết kế workflow theo các trạng thái đề xuất:

    * <b>Draft</b> → <b>Pending Approval</b> → <b>Approved</b> → <b>In Procurement</b> → <b>Completed</b> → <b>Closed</b>
    * Nhánh từ chối: <b>Pending Approval</b> → <b>Rejected</b> → <b>Closed</b>

    Nguyên tắc:

    * Mỗi chuyển trạng thái gắn với một hành động rõ ràng và một vai trò chịu trách nhiệm.
    * Trạng thái phải thể hiện vị trí công việc trong luồng.

    Xem chi tiết: [Thiết kế quy trình (Process Builder)](/build-apps/workflows/process-builder) và [Phê duyệt (Approvals)](/build-apps/workflows/approvals).
  </Step>

  <Step title="Bước 6 — Thiết lập Roles & Permissions">
    Tối thiểu 3 vai trò:

    * <b>Requester</b>: tạo/sửa khi Draft, gửi duyệt (Pending Approval), theo dõi trạng thái
    * <b>Approver</b>: xem và Approve/Reject khi Pending Approval
    * <b>Procurement</b>: cập nhật trạng thái In Procurement → Completed

    ✅ Kết quả: đúng người, đúng bước, đúng quyền.

    Xem tổng quan: [Mô hình phân quyền (Permissions model)](/reference/permissions-model-public)
    Và xử lý lỗi quyền: [Quyền & truy cập (Permissions & access)](/troubleshooting/permissions-access).
  </Step>

  <Step title="Bước 7 — Kiểm thử end-to-end theo luồng chính">
    Thực hiện kiểm thử theo 3 vai trò:

    1. Requester tạo record ở Draft
    2. Requester chuyển sang Pending Approval
    3. Approver Approve hoặc Reject
    4. Nếu Approved: Procurement chuyển sang In Procurement → Completed
    5. Đóng vòng: Closed (khi đã hoàn tất hoặc bị từ chối)

    Khi phát hiện vấn đề:

    * Không thấy dữ liệu/không thao tác được → kiểm tra Permissions
    * Không chuyển được trạng thái → kiểm tra workflow/điều kiện
    * Form khó sử dụng → chỉnh record layout

    Xem: [quy trình & tự động hoá (Workflows & automation)](/troubleshooting/workflows-automation) và [giao diện (Views & UI)](/troubleshooting/views-ui).
  </Step>
</Steps>

***

## Phạm vi của quickstart này

Quickstart này chỉ bao gồm phần tối thiểu để app “chạy được”:

* Grid view cơ bản, record layout cơ bản, workflow cơ bản, phân quyền cơ bản.

Các nội dung nâng cao (Kanban, dashboard, automation nâng cao, publish/consume, API/webhook, Analytics Hub) sẽ được giới thiệu ở các trang tính năng tương ứng.

## Bước tiếp theo

* Quyết định “tách app hay giữ một app”: [Ranh giới App](/foundations/app-boundaries)
* Kết nối app bằng publish/consume: [Chia sẻ dữ liệu (Publish/Consume)](/build-apps/integrations/publish-consume-overview)
* Scenario-Driven (SDD) —: [SDD là gì](/sdd/overview)
* Thảo luận: [community.cleeksy.com](https:\[Community]\(//community\).cleeksy.com)