Đặt lại dữ liệu local (desktop)

import { Aside } from ‘@astrojs/starlight/components’;

Tình huống sử dụng

Vendor Desktop lưu cache danh mục + outbox (hàng đợi đơn offline) trong SQLite local. Khi cache lỗi nặng — giá sai, sản phẩm trùng, outbox không sync — cần đặt lại để hệ thống tải lại từ server.

Bài viết này cho chủ cửa hàng (cần quyền settings ghi).

Source: apps/vendor-web/src/app/point-of-sale/pages/settings/settings-local-data-page.tsx + <PosLocalDataResetPanel> (apps/vendor-web/src/components/point-of-sale/pos-local-data-reset-panel.tsx).

Panel đặt lại dữ liệu local — 2 scope + nút Reset Hình: Panel đặt lại — radio chọn scope (Chỉ danh mục / Bao gồm outbox), dòng backup hint, nút “Đặt lại” màu đỏ. Spec owner: cashier-screenshots.spec.ts → "settings — local data reset".

Trước khi bắt đầu

Ngoài giờ cao điểm — reset làm trống cache, lần bán tiếp theo phải sync danh mục (có thể chậm hơn).
Sync outbox trước nếu có thể — nếu chọn reset bao gồm outbox, các đơn chưa gửi sẽ bị xoá (mặc dù có backup).
Đã chọn cửa hàng active — cần storeId để reset, nếu không sẽ thấy banner “No store”.

2 lựa chọn scope

<PosLocalDataResetPanel> cung cấp 2 radio lựa chọn:

Scope	Xóa gì	Giữ gì	Khi nào dùng
Chỉ danh mục (`catalog_only`)	Bảng `catalog_*` trong local DB	Outbox (đơn chờ)	Cache cũ / giá sai / trùng sản phẩm
Bao gồm outbox (`with_outbox`)	Danh mục + toàn bộ outbox	—	Outbox lỗi, đơn kẹt không sync được

4 bước đặt lại

Bước 1 — Mở trang

Từ shell Thu ngân → Cài đặt → Dữ liệu local (/point-of-sale/settings/local-data).

Bước 2 — Chọn scope

Tick 1 trong 2 radio. Mặc định là Chỉ danh mục (an toàn hơn).

Bước 3 — Click “Đặt lại”

Mở modal xác nhận <PosLocalDataResetConfirmModal> → đọc kỹ → click Xác nhận.

Bước 4 — Đợi toast kết quả

Khi hoàn tất, toast hiển thị:

Đặt lại thành công. Backup: <backupVersion>;
danh mục xoá: <catalogRows>; outbox xoá: <outboxRows>.

Sau đó:

Reset Zustand hydration (resetHydration()).
Invalidate toàn bộ TanStack query.
Bootstrap settings cache lại từ server (bootstrapPosLocalSettingsQueryCache).
Pull catalog mới từ server (pullPosLocalCatalogFromServer) — best-effort, nếu lỗi cashier bấm Sync thủ công.

Kết quả mong đợi

Catalog hiển thị danh sách sản phẩm mới nhất từ API.
Giỏ hàng hiện tại có thể trống vì các dòng tham chiếu tới catalog cũ.
Đơn nháp server vẫn nguyên — chỉ cache local bị xoá.

Backup & phục hồi

Mỗi lần reset tạo 1 backup version trong thư mục user data của Electron (resetPosLocalDataForResync trả về backupVersion). Backup chứa toàn bộ DB trước khi xoá.

Để phục hồi (ngoài scope UI):

Liên hệ support kèm backup version từ toast.
Support dùng script restore từ file backup.

Lỗi thường gặp

Triệu chứng	Xử lý
Trang báo “Desktop only”	Đang dùng trình duyệt thuần — chỉ hoạt động trên Vendor Desktop
Trang báo “Unavailable”	Chưa bật `isVendorPosLocalDbEnabled` (flag local-first) — liên hệ support
Banner “No store”	Chưa chọn cửa hàng active trên top bar
Reset thất bại với toast lỗi	Kiểm tra kết nối server; thử lại sau
Sau reset catalog vẫn cũ	Click Sync thủ công trong màn Bán hàng; hoặc restart Vendor Desktop

Khi nào KHÔNG nên reset

Giờ cao điểm — ảnh hưởng tốc độ bán.
Outbox có đơn chưa sync mà chưa muốn mất — sync thủ công trước.
Sau khi vừa cập nhật giá hàng loạt trên Dashboard — đợi 5–10 phút cho các cashier nhận được pull tự động trước.

Kỹ thuật

Component: <PosLocalDataResetPanel> (pos-local-data-reset-panel.tsx)
Hook helper: usePosServerOnline, usePosStoreId
Service: resetPosLocalDataForResync, pullPosLocalCatalogFromServer
Modal confirm: <PosLocalDataResetConfirmModal> (pos-local-data-reset-confirm-modal.tsx)
Settings store: usePosLocalSettingsStore (Zustand)