Rỗng, đang tải, lỗi, không có quyền

Mỗi vùng dữ liệu có ít nhất bốn trạng thái ngoài trạng thái "có dữ liệu". Thiết kế một màn hình là vẽ đủ các trạng thái đó — bỏ sót một cái là người dùng gặp màn hình trắng không lời giải thích.

<script setup lang="ts">
import { ref } from 'vue'
import { CDescriptions, CDescriptionsItem, CSkeleton } from '@tasco/ui'

// Một khối nội dung qua đủ trạng thái. Đang tải dùng khung xương cùng hình dạng nội dung; lỗi nói rõ nguyên nhân và cho
// thử lại; không có quyền thì giải thích, không mời hành động nào.
type BlockState = 'data' | 'loading' | 'empty' | 'error' | 'forbidden'

const STATES: { value: BlockState, label: string }[] = [
  { value: 'data', label: 'Có dữ liệu' },
  { value: 'loading', label: 'Đang tải' },
  { value: 'empty', label: 'Rỗng' },
  { value: 'error', label: 'Lỗi' },
  { value: 'forbidden', label: 'Không có quyền' },
]

const state = ref<BlockState>('data')

function retry() {
  state.value = 'loading'
  setTimeout(() => {
    state.value = 'data'
  }, 1200)
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div
      role="group"
      aria-label="Chọn trạng thái của khối"
      style="display: flex; gap: 8px; flex-wrap: wrap"
    >
      <CButton
        v-for="item in STATES"
        :key="item.value"
        size="sm"
        :variant="state === item.value ? 'primary' : 'outline'"
        :aria-pressed="state === item.value"
        @click="state = item.value"
      >
        {{ item.label }}
      </CButton>
    </div>

    <CCard title="Công nợ khách hàng">
      <CSkeleton
        v-if="state === 'loading'"
        active
        :title="false"
        :paragraph="{ rows: 3 }"
      />
      <CEmpty
        v-else-if="state === 'empty'"
        description="Khách hàng chưa phát sinh công nợ."
      />
      <CEmpty
        v-else-if="state === 'error'"
        description="Không tải được công nợ: máy chủ không phản hồi."
      >
        <CButton
          variant="primary"
          size="sm"
          @click="retry"
        >
          Thử lại
        </CButton>
      </CEmpty>
      <CEmpty
        v-else-if="state === 'forbidden'"
        description="Bạn không có quyền xem công nợ của khách hàng."
      />
      <CDescriptions
        v-else
        :column="1"
        size="small"
      >
        <CDescriptionsItem label="Dư nợ">
          48.200.000 ₫
        </CDescriptionsItem>
        <CDescriptionsItem label="Hạn mức">
          100.000.000 ₫
        </CDescriptionsItem>
        <CDescriptionsItem label="Quá hạn">
          <CTag color="error">
            12.000.000 ₫
          </CTag>
        </CDescriptionsItem>
      </CDescriptions>
    </CCard>
  </div>
</template>

Tóm tắt

Trạng thái	Người dùng cần biết	Hiển thị bằng
Đang tải	Hệ thống đang làm việc	Thanh tải đầu trang, loading của bảng và nút, khung xương CSkeleton
Rỗng	Không có gì — và làm gì tiếp	CEmpty kèm câu giải thích, có hoặc không có nút
Lỗi	Hỏng ở đâu, dữ liệu đã nhập có mất không, làm gì tiếp	Thông báo nổi cho thao tác; khối lỗi kèm "Thử lại" cho màn hình; lỗi dưới ô nhập cho form
Không có quyền	Không phải lỗi hệ thống, tìm ai để xin quyền	Ẩn hoặc khoá phần tử; trang 403; khối giải thích không có nút

Đang tải

Tình huống	Cách hiển thị
Chuyển trang	Thanh tải màu cam ở mép trên cửa sổ — layer có sẵn
Bảng tải hoặc tải lại	CTable :loading — lớp mờ phủ bảng, icon Tải lại tự xoay
Khối nội dung tải lần đầu	CSkeleton cùng hình dạng nội dung sắp hiện (số dòng, có ảnh hay không)
Gửi form, xoá, duyệt	loading trên chính nút vừa bấm — nút tự khoá, chống bấm hai lần
Tác vụ lâu (xuất file lớn)	Thông báo "Đang xuất file…" rồi thông báo kết quả khi xong

• Chỉ báo tải đặt đúng chỗ đang chờ: không khoá cả màn hình khi chỉ một khối đang tải.
• Lần tải đầu hiện khung trống kèm chỉ báo, không hiện dữ liệu cũ của màn hình trước.
• Phản hồi thường về dưới 300ms thì chỉ báo nháy lên rồi tắt, gây rối mắt: CSpin và loading của bảng nhận delay để chỉ hiện khi chờ lâu hơn ngưỡng đó.

Rỗng

Rỗng không phải lỗi, nhưng mỗi lý do rỗng cần một câu và một lời mời khác nhau:

Lý do	Câu mô tả	Hành động
Chưa có bản ghi nào	"Chưa có đơn hàng nào. Tạo đơn đầu tiên để bắt đầu theo dõi."	Tạo mới (nếu có quyền tạo)
Bộ lọc hoặc tìm kiếm không ra kết quả	"Không có đơn hàng nào khớp điều kiện lọc."	Xoá bộ lọc
Chưa đến lúc có dữ liệu	"Báo cáo tháng 9 có sau ngày 01/10."	Không có
Không có quyền xem	"Bạn không có quyền xem dữ liệu này."	Không có

Mời "Tạo mới" trong khi người dùng chỉ lọc nhầm là lỗi thường gặp nhất. Chi tiết và demo: CEmpty, Trạng thái bảng.

Lỗi

Chọn cách hiển thị theo phạm vi của lỗi:

Phạm vi	Ví dụ	Hiển thị
Một thao tác	Lưu, xoá, duyệt không thành công	Thông báo nổi ngắn (message); giữ nguyên màn hình và dữ liệu đã nhập
Lỗi hệ thống, mất mạng	5xx, không kết nối được máy chủ	Thông báo ở góc màn hình, tiêu đề "Lỗi hệ thống"
Dữ liệu nhập sai	Backend trả 422	Chữ đỏ ngay dưới từng ô nhập sai, không thêm thông báo nổi
Tải dữ liệu của một khối	Không lấy được công nợ	Khối đó hiện câu lỗi và nút "Thử lại"; khối khác vẫn hiện bình thường
Cả màn hình	Đường dẫn không tồn tại, lỗi không bắt được	Trang lỗi toàn màn hình với mã lỗi và nút "Về trang chủ"
Hết phiên đăng nhập	401	Tự chuyển về trang đăng nhập, đăng nhập xong quay lại đúng trang cũ

Phần lớn các cách trên đã chạy tự động qua bộ xử lý lỗi chung của layer — xem Hiển thị lỗi. Thiết kế chỉ cần vẽ phần do trang tự dựng: khối lỗi kèm "Thử lại" và lỗi dưới ô nhập.

Câu lỗi nói chuyện gì xảy ra và làm gì tiếp, không đổ lỗi cho người dùng, không hiện mã kỹ thuật trần — xem Câu chữ.

Một khối không có dữ liệu vì lỗi thì không hiện số 0 hay bảng rỗng: số 0 là một giá trị, người dùng sẽ tin là thật.

Không có quyền

Phạm vi	Cách hiển thị
Mục menu	Ẩn hẳn
Cả trang	Trang lỗi 403 "Bạn không có quyền truy cập trang này." kèm nút về trang chủ
Nút hành động không bao giờ được dùng	Ẩn (v-can)
Nút có thể được cấp quyền sau	Hiện nhưng khoá (v-can:disable)
Một khối trong trang	Câu giải thích thay cho nội dung, không có nút (<Can> với #fallback)

• Không để người dùng bấm nút rồi mới báo "không có quyền".
• Không có quyền không phải lỗi hệ thống: dùng màu trung tính, không dùng màu đỏ hay biểu tượng cảnh báo.
• Nếu tổ chức có quy trình xin quyền, câu giải thích nói rõ cần liên hệ ai.

Trang lỗi toàn màn hình của layer hiện dùng chung hình minh hoạ lỗi cho mọi mã khác 404, kể cả 403. Sản phẩm cần trang 403 riêng thì ghi đè app/error.vue — xem API của layer.

Cách khai báo quyền: Chặn theo quyền.

Checklist khi thiết kế

• [ ] Vẽ khung trống lúc đang tải, không để trắng.
• [ ] Hai loại rỗng (chưa có dữ liệu, lọc không ra) có câu và hành động khác nhau.
• [ ] Khối tải lỗi có câu lỗi và nút thử lại; các khối khác không bị kéo theo.
• [ ] Mỗi nút hành động đã quyết định: ẩn hay khoá khi thiếu quyền.
• [ ] Form hiện lỗi dưới từng ô, không mất dữ liệu đã nhập khi lưu lỗi.

Liên quan

• Hiển thị lỗi — bộ xử lý lỗi chung và khi nào tự dựng giao diện lỗi.
• Lỗi 422 và form — gắn lỗi của backend vào từng ô nhập.
• Trang tổng quan — một khối hỏng không kéo cả trang.