@tasco/composables

Composable dùng chung, layer auto-import sẵn nên trong app không cần import. Cách dùng theo tình huống: useApi và fetcher, Trang danh sách, Mô hình phân quyền.

Hàm

createPermissionChecker()

function createPermissionChecker(
   permissions, 
   roles, 
   superRoles?
): PermissionChecker;

Tạo checker từ danh sách permission/role. Super-role bỏ qua mọi check (admin). Item không khai permission luôn được giữ.

Tham số

Tham số	Kiểu	Mặc định
`permissions`	`string`[]	`undefined`
`roles`	`string`[]	`undefined`
`superRoles`	`string`[]	`[]`

Trả về

PermissionChecker

normalizeUri()

function normalizeUri(uri): string;

Chuẩn hoá URI: cắt query + bỏ dấu '/' cuối để tránh sai lệch vặt.

Tham số

Tham số	Kiểu
`uri`	`string`

Trả về

string

parseSuperRoles()

function parseSuperRoles(source): string[];

Danh sách super-role từ public.auth.superRoles (chuỗi 'a,b' hoặc mảng).

Tham số

Tham số	Kiểu
`source`	`unknown`

Trả về

string[]

useApi()

function useApi(options?): ApiFetch;

$fetch đã cấu hình sẵn cho framework:

baseURL từ runtimeConfig (mô hình BFF: mặc định '/api' proxy qua Nitro)
SSR-aware: forward cookie/header của request đến (useRequestFetch)
chuẩn hoá lỗi về AppError

Refresh token / 401 chủ yếu xử lý phía Nitro BFF (xem @tasco/nuxt-layer-base); ở client, 401 được ném ra dưới dạng AppError để middleware/caller xử lý.

Tham số

Tham số	Kiểu
`options`	`UseApiOptions`

Trả về

ApiFetch

useAuth()

function useAuth(): object;

State + hành động auth. Flow đăng nhập thực tế nằm ở AuthProvider (abstract), team sản phẩm không tự viết lại SSO.

Trả về

Tên	Kiểu	Mô tả
`fetchUser()`	() => `Promise`<`AuthUser` \| `null`>	Tải lại người dùng từ `/auth/session` và ghi vào `user`.
`isAuthenticated`	`ComputedRef`<`boolean`>	`true` khi `user` khác `null`.
`login()`	(`redirectTo?`) => `Promise`<`void`>	Chuyển tới trang đăng nhập, sau khi đăng nhập quay về `redirectTo` (mặc định trang hiện tại).
`loginWithPassword()`	(`credentials`) => `Promise`<`AuthUser`>	Đăng nhập bằng form (username/password/OTP) qua BFF. Cập nhật user state khi thành công. Ném lỗi nếu provider không hỗ trợ hoặc credential sai.
`logout()`	(`redirectTo?`) => `Promise`<`void`>	Xoá phiên (cookie) rồi chuyển tới `redirectTo` (mặc định `/`).
`refresh()`	() => `Promise`<`boolean`>	Kiểm tra phiên còn hợp lệ không (gọi lại `/auth/session`).
`user`	`Ref`<`AuthUser` \| `null`, `AuthUser` \| `null`>	Người dùng hiện tại; `null` khi chưa đăng nhập. Chung state với layout và middleware.

usePermission()

function usePermission(): object;

Kiểm tra quyền/role dựa trên user hiện tại. Chỉ là logic guard (UX) — KHÔNG chứa flow đăng nhập (xem useAuth), backend vẫn phải tự enforce. Permission là URI (exact match); super-role (public.auth.superRoles) bỏ qua check.

Trả về

Tên	Kiểu	Mô tả
`can()`	(`uri`) => `boolean`	Có permission `uri` (so khớp chính xác sau khi bỏ query và `/` cuối) hoặc là super-role.
`canAccess()`	(`uri`) => `boolean`	Alias ngữ nghĩa route/trang.
`canAll()`	(`uris`) => `boolean`	Có TẤT CẢ permission trong danh sách.
`canAny()`	(`uris`) => `boolean`	Có ít nhất một permission trong danh sách.
`filterByPermission()`	<`T`>(`items`) => `T`[]	Lọc mảng {permission?, children?} — bỏ item user không có quyền.
`hasAnyRole()`	(`roles`) => `boolean`	Có ít nhất một role trong danh sách.
`hasRole()`	(`role`) => `boolean`	Có role này.

useTable()

function useTable<T>(fetcher, options?): object;

Quản lý state phân trang/sắp xếp/lọc cho CTable, gọi dữ liệu qua fetcher (thường tạo từ useApi). Trả về props sẵn sàng bind vào CTable: pagination + onChange, bộ lọc dựng sẵn filterValues + onFilter (gộp với filter cột vào query.filters); options.settingsKey để lần load đầu theo sắp xếp mặc định đã lưu trong thiết lập của CTable.

Tham số kiểu

Tham số kiểu
`T`

Tham số

Tham số	Kiểu
`fetcher`	`TableFetcher`<`T`>
`options`	`UseTableOptions`

Trả về

Tên	Kiểu	Mô tả
`dataSource`	`Ref`<`T`[], `T`[]>	Bản ghi của trang hiện tại — bind `:data-source`.
`error`	`Ref`<`unknown`, `unknown`>	Lỗi của lần tải gần nhất (đã quy về `AppError`); `null` khi thành công.
`filterValues`	`ComputedRef`<`Record`<`string`, `unknown`>>	Bộ lọc form đang áp dụng (chỉ đọc) — bind `:filter-values`.
`load()`	() => `Promise`<`void`>	Tải lại, giữ nguyên trang; ném `AppError` khi fetcher lỗi.
`loading`	`Ref`<`boolean`, `boolean`>	Đang tải — bind `:loading`.
`onChange()`	(`pag`, `filters?`, `sorter?`) => `Promise`<`void`>	Bind trực tiếp vào `@change` của CTable: cập nhật trang, filter cột, sắp xếp rồi tải lại (kể cả change CTable phát khi lưu sắp xếp mặc định mới).
`onFilter()`	(`values`) => `Promise`<`void`>	Bind vào `@update:filter-values` của CTable: thay bộ lọc form, về trang 1 rồi tải lại.
`pagination`	`ComputedRef`<{ `current`: `number`; `pageSize`: `number`; `showSizeChanger`: `boolean`; `total`: `number`; }>	Cấu hình phân trang — bind `:pagination`.
`query`	`object`	Truy vấn hiện tại (reactive) — gửi cho fetcher mỗi lần tải.
`query.filters?`	`Record`<`string`, `unknown`>	Filter cột gộp với bộ lọc form (trùng khoá thì bộ lọc form thắng); không có bộ lọc nào → `undefined`. Đổi trang hay sắp xếp không làm mất bộ lọc form.
`query.page`	`number`	Trang cần lấy, tính từ 1.
`query.pageSize`	`number`	Số bản ghi mỗi trang.
`query.sortField?`	`string`	`dataIndex` của cột đang sắp xếp; dataIndex lồng nối bằng `.` (`owner.name`). Sắp xếp nhiều cột (`sorter.multiple`) chỉ gửi cột đầu.
`query.sortOrder?`	`"ascend"` \| `"descend"`	Chiều sắp xếp; `undefined` khi không sắp xếp.
`reload()`	() => `Promise`<`void`>	Quay về trang 1 và tải lại.
`total`	`Ref`<`number`, `number`>	Tổng số bản ghi do fetcher trả về.

useThemeMode()

function useThemeMode(): object;

Quản lý chế độ sáng/tối ở runtime. Lưu qua cookie (SSR đọc được → không chớp theme khi tải lại). Giá trị mặc định lấy từ appConfig.tasco.themeMode.

app.vue của layer dùng mode để đổi antd algorithm + CSS vars --tasco-*.

Trả về

Tên	Kiểu	Mô tả
`isDark`	`ComputedRef`<`boolean`>	`true` khi đang ở chế độ tối.
`mode`	`CookieRef`<`ThemeMode`>	Chế độ hiện tại, lưu ở cookie `tasco:theme` một năm; gán trực tiếp cũng được.
`setMode()`	(`next`) => `void`	Đặt chế độ `'light'` hoặc `'dark'`.
`toggle()`	() => `void`	Đảo sáng ↔ tối.

Interface

AuthClientOption

Một ứng dụng (client) người dùng chọn khi đăng nhập.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
`code`	`string`	Mã ứng dụng, vd `WP_HRM` — giá trị gửi lên ở `LoginCredentials.clientId`.
`id`	`string`	Định danh của ứng dụng trong IAM.
`name`	`string`	Tên hiển thị trong dropdown.
`url?`	`string`	Địa chỉ của ứng dụng, nếu IAM có khai.

AuthProvider

Chiến lược xác thực mà layer cung cấp ở nuxtApp.$tascoAuth. useAuth gọi qua interface này, nên thay cách đăng nhập chỉ cần thay plugin cung cấp provider, không sửa code trang.

Phương thức

getUser()

getUser(): Promise<AuthUser | null>;

Lấy user hiện tại (từ session/cookie).

Trả về

Promise<AuthUser | null>

handleCallback()

handleCallback(): Promise<AuthUser | null>;

Xử lý callback sau khi IdP redirect về, trả user nếu thành công.

Trả về

Promise<AuthUser | null>

login(redirectTo?): void | Promise<void>;

Khởi động flow đăng nhập (redirect tới trang login / IdP).

Tham số

Tham số	Kiểu
`redirectTo?`	`string`

Trả về

void | Promise<void>

loginWithPassword()?

optional loginWithPassword(credentials): Promise<AuthUser>;

Đăng nhập bằng credential qua BFF (form first-party). Trả user nếu thành công, ném lỗi nếu sai. Provider không hỗ trợ form có thể bỏ trống.

Tham số

Tham số	Kiểu
`credentials`	`LoginCredentials`

Trả về

Promise<AuthUser>

logout()

logout(redirectTo?): void | Promise<void>;

Đăng xuất + dọn session.

Tham số

Tham số	Kiểu
`redirectTo?`	`string`

Trả về

void | Promise<void>

refresh()

refresh(): Promise<boolean>;

Làm mới phiên (token refresh). Trả true nếu còn phiên hợp lệ.

Trả về

Promise<boolean>

AuthUser

Người dùng đang đăng nhập, lưu ở useState('tasco:auth:user'). Layer dựng từ userInfo của IAM theo runtimeConfig.auth.mapping; field ngoài danh sách dưới đây đi vào chỉ mục [key: string].

Truy cập theo khoá

[key: string]: unknown

Thuộc tính

Thuộc tính	Kiểu	Mô tả
`email?`	`string`	Email.
`id`	`string`	Định danh người dùng.
`name?`	`string`	Tên hiển thị.
`permissions`	`string`[]	Permission là URI hành động, so khớp chính xác, vd `/orders/search`.
`roles`	`string`[]	Mã role, vd `AIWSP_ADMIN`. Role nằm trong `public.auth.superRoles` bỏ qua mọi kiểm tra quyền.

LoginCredentials

Thông tin đăng nhập form gửi lên BFF (password/OTP KHÔNG bao giờ lưu ở client).

Thuộc tính

Thuộc tính	Kiểu	Mô tả
`clientId?`	`string`	Mã ứng dụng (`AuthClientOption.code`), không phải id.
`method?`	`AuthMethod`	Phương thức OTP người dùng chọn.
`otp?`	`string`	Mã OTP người dùng nhập.
`password`	`string`	Mật khẩu — chỉ gửi qua HTTPS tới `/auth/login`, không lưu lại.
`transactionId?`	`string`	Mã giao dịch trả về từ bước gửi OTP qua Telegram (`/auth/otp/send`).
`username`	`string`	Tên đăng nhập.

PermissionChecker

Bộ kiểm quyền trên một danh sách permission/role cố định — tạo bằng createPermissionChecker.

Phương thức

can()

can(uri): boolean;

Có permission uri (sau chuẩn hoá) hoặc là super-role.

Tham số

Tham số	Kiểu
`uri`	`string`

Trả về

boolean

canAll()

canAll(uris): boolean;

Có TẤT CẢ permission trong danh sách; danh sách rỗng → true.

Tham số

Tham số	Kiểu
`uris`	`string`[]

Trả về

boolean

canAny()

canAny(uris): boolean;

Có ÍT NHẤT MỘT permission trong danh sách; danh sách rỗng → false.

Tham số

Tham số	Kiểu
`uris`	`string`[]

Trả về

boolean

filterByPermission()

filterByPermission<T>(items): T[];

Lọc cây item theo permission (đệ quy qua children); item không khai permission luôn được giữ.

Tham số kiểu

Tham số kiểu
`T` extends `object`

Tham số

Tham số	Kiểu
`items`	`T`[]

Trả về

T[]

hasAnyRole()

hasAnyRole(roles): boolean;

Có ít nhất một role trong danh sách.

Tham số

Tham số	Kiểu
`roles`	`string`[]

Trả về

boolean

hasRole()

hasRole(role): boolean;

Có role này (so khớp chính xác, không xét super-role).

Tham số

Tham số	Kiểu
`role`	`string`

Trả về

boolean

TableQuery

Truy vấn useTable gửi cho fetcher mỗi lần tải — fetcher chuyển thành query string theo backend.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
`filters?`	`Record`<`string`, `unknown`>	Filter cột gộp với bộ lọc form (trùng khoá thì bộ lọc form thắng); không có bộ lọc nào → `undefined`. Đổi trang hay sắp xếp không làm mất bộ lọc form.
`page`	`number`	Trang cần lấy, tính từ 1.
`pageSize`	`number`	Số bản ghi mỗi trang.
`sortField?`	`string`	`dataIndex` của cột đang sắp xếp; dataIndex lồng nối bằng `.` (`owner.name`). Sắp xếp nhiều cột (`sorter.multiple`) chỉ gửi cột đầu.
`sortOrder?`	`"ascend"` \| `"descend"`	Chiều sắp xếp; `undefined` khi không sắp xếp.

UseApiOptions

Tuỳ chọn của useApi.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
`baseURL?`	`string`	Ghi đè baseURL (mặc định lấy từ runtimeConfig.public.apiBaseURL hoặc '/api').

UseTableOptions

Tuỳ chọn của useTable.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
`filters?`	`Record`<`string`, `unknown`>	Bộ lọc form ban đầu (vd mặc định lọc theo trạng thái) — có hiệu lực ngay từ lần load đầu.
`immediate?`	`boolean`	Tự load lần đầu (mặc định true). Đặt false nếu muốn tự gọi trong onMounted.
`pageSize?`	`number`	Số bản ghi mỗi trang ban đầu (mặc định 20).
`settingsKey?`	`string`	Khoá thiết lập của CTable (`settings-key`, cùng giá trị) — đọc sắp xếp mặc định người dùng đã lưu để lần load đầu đúng thứ tự, không phải tải lại khi bảng dựng xong.

Kiểu

ApiFetch

type ApiFetch = <T>(request, options?) => Promise<T>;

Hàm gọi API mà useApi trả về: cùng chữ ký $fetch của ofetch, T là kiểu body response. Lỗi luôn ném dưới dạng AppError.

Tham số kiểu

Tham số kiểu	Default type
`T`	`unknown`

Tham số

Tham số	Kiểu
`request`	`string`
`options?`	`FetchOptions`

Trả về

Promise<T>

AuthMethod

type AuthMethod = "google" | "telegram";

Phương thức sinh/gửi OTP hỗ trợ trên form đăng nhập.

TableFetcher

type TableFetcher<T> = (query) => Promise<Paginated<T>>;

Hàm lấy một trang dữ liệu cho useTable, thường gọi useApi rồi quy đổi response về Paginated<T>.

Tham số kiểu

Tham số kiểu
`T`

Tham số

Tham số	Kiểu
`query`	`TableQuery`

Trả về

Promise<Paginated<T>>

@tasco/composables ​

Hàm ​

createPermissionChecker() ​

Tham số ​

Trả về ​

normalizeUri() ​

Tham số ​

Trả về ​

parseSuperRoles() ​

Tham số ​

Trả về ​

useApi() ​

Tham số ​

Trả về ​

useAuth() ​

Trả về ​

usePermission() ​

Trả về ​

useTable() ​

Tham số kiểu ​

Tham số ​

Trả về ​

useThemeMode() ​

Trả về ​

Interface ​

AuthClientOption ​

Thuộc tính ​

AuthProvider ​

Phương thức ​

getUser() ​

Trả về ​

handleCallback() ​

Trả về ​

login() ​

Tham số ​

Trả về ​

loginWithPassword()? ​

Tham số ​

Trả về ​

logout() ​

Tham số ​

Trả về ​

refresh() ​

Trả về ​

AuthUser ​

Truy cập theo khoá ​

Thuộc tính ​

LoginCredentials ​

Thuộc tính ​

PermissionChecker ​

Phương thức ​

can() ​

Tham số ​

Trả về ​

canAll() ​

Tham số ​

Trả về ​

canAny() ​

Tham số ​

Trả về ​

filterByPermission() ​

Tham số kiểu ​

Tham số ​

Trả về ​

hasAnyRole() ​

Tham số ​

Trả về ​

hasRole() ​

Tham số ​

Trả về ​

TableQuery ​

Thuộc tính ​

UseApiOptions ​

Thuộc tính ​

UseTableOptions ​

Thuộc tính ​

Kiểu ​

ApiFetch ​

Tham số kiểu ​

Tham số ​

@tasco/composables

Hàm

createPermissionChecker()

Tham số

Trả về

normalizeUri()

Tham số

Trả về

parseSuperRoles()

Tham số

Trả về

useApi()

Tham số

Trả về

useAuth()

Trả về

usePermission()

Trả về

useTable()

Tham số kiểu

Tham số

Trả về

useThemeMode()

Trả về

Interface

AuthClientOption

Thuộc tính

AuthProvider

Phương thức

getUser()

Trả về

handleCallback()

Trả về

login()

Tham số

Trả về

loginWithPassword()?

Tham số

Trả về

logout()

Tham số

Trả về

refresh()

Trả về

AuthUser

Truy cập theo khoá

Thuộc tính

LoginCredentials

Thuộc tính

PermissionChecker

Phương thức

can()

Tham số

Trả về

canAll()

Tham số

Trả về

canAny()

Tham số

Trả về

filterByPermission()

Tham số kiểu

Tham số

Trả về

hasAnyRole()

Tham số

Trả về

hasRole()

Tham số

Trả về

TableQuery

Thuộc tính

UseApiOptions

Thuộc tính

UseTableOptions

Thuộc tính

Kiểu

ApiFetch

Tham số kiểu

Tham số