Tổng quan & thiết kế

POS Apps cho phép shop tự xây dựng app (viết tay hoặc vibe-code bằng công cụ AI), upload lên Pancake POS và dùng ngay trong giao diện POS. App chỉ hoạt động trong shop đã cài, không phát hành công khai.

App có thể:

• Thêm action vào menu thao tác có sẵn, ví dụ "Đẩy sang ERP" trong menu thao tác của đơn hàng.
• Gắn vào đơn hàng, sản phẩm, phiếu nhập, phiếu xuất và phiếu chuyển kho với cùng bộ extension point và cùng cách viết code.
• Chèn block vào màn hình có sẵn, ví dụ một box "Công nợ khách hàng" trong form đơn.
• Thêm trang riêng vào menu của POS, ví dụ màn "Đối soát công nợ".
• Chạy hook trước hoặc sau một thao tác, ví dụ chặn lưu đơn khi khách vượt hạn mức nợ.
• Đọc và ghi dữ liệu của shop qua Open API, theo đúng quyền của người đang dùng.

App không sửa, ẩn hay thay thế giao diện và action có sẵn của POS.

#Thuật ngữ

#Kiến trúc

Trang POS (pos.pages.fm)                         Sandbox của app (domain riêng)
┌──────────────────────────────────┐            ┌──────────────────────────────────┐
│ Vị trí extension                 │ postMessage│ Iframe ẩn                        │
│  ├─ Block / modal (Worker UI)    │◄──────────►│  └─ Web Worker                   │
│  │   POS vẽ bằng component chuẩn │            │      ├─ Code của app + Preact    │
│  ├─ Trang của app (iframe)       │            │      └─ Runtime POS (pos, DOM)   │
│  └─ Hook, điều kiện hiển thị     │            │ Iframe trang: SPA của app        │
│ Cầu nối: dữ liệu ngữ cảnh,       │            │      └─ SDK client (connect)     │
│ token, toast, điều hướng         │            │  fetch ──► Open API (app token)  │
└──────────────────────────────────┘            └──────────────────────────────────┘

Nguyên tắc:

1. Code app không bao giờ chạy trên domain của POS. App chạy trong web worker hoặc iframe trên một domain sandbox riêng cho từng app, nên không đọc được phiên đăng nhập, cookie hay giao diện của POS.
2. POS vẽ giao diện, app chỉ mô tả. Với block và modal, app dựng cây element pos-*. POS nhận mô tả đó và vẽ bằng component của chính POS, nên giao diện giống hệt POS và app không chạm được vào trang.
3. Mọi dữ liệu đi qua Open API, bằng app token có quyền của người đang dùng.
4. Vị trí, component và dữ liệu ngữ cảnh là hợp đồng có version (api_version trong manifest). POS giữ tương thích ngược trong thời gian hỗ trợ của mỗi version.

#SDK

App không tự viết phần giao tiếp với POS. Phần này chia làm hai:

• Runtime POS: POS nạp sẵn vào worker trước code của app. Gồm biến toàn cục pos, DOM tối giản cho Worker UI, element pos-*, kênh postMessage, app token và client gọi Open API. Runtime không nằm trong bundle của app, nên POS cập nhật hoặc vá lỗi mà app không phải deploy lại.
• Gói SDK cài vào dự án của app:

Phiên bản gói đi theo api_version (gói 2026.1.x cho 2026-01). Lệnh pos-app check kiểm tra manifest và chặn các lỗi hay gặp khi AI sinh code (dùng DOM thật, thẻ HTML thường, method hoặc domain chưa khai). Chi tiết: SDK & CLI.

#Chọn kiểu hiển thị

Quy tắc ngắn: nằm trong màn hình POS → Worker UI; là màn hình riêng → iframe; không có giao diện → headless.

#Worker UI hoạt động thế nào

Web worker không có DOM. Runtime POS nạp vào worker một DOM tối giản, chỉ đủ để Preact hoặc JS thuần dựng cây element pos-*. Mỗi khi cây thay đổi, runtime ghi lại thay đổi (thêm, xóa node, đổi thuộc tính, đổi chữ) và gửi về POS thành một lô sau mỗi lượt render. POS kiểm tra từng element rồi vẽ bằng component thật. Khi người dùng bấm hoặc gõ, POS gửi sự kiện vào worker và code của app nhận giá trị qua event.detail.

Worker (code của app)                              POS
setState → Preact render lại trên DOM tối giản
         → runtime gom thay đổi thành một lô ────► kiểm tra → vẽ bằng component POS
onChange(event.detail) ◄───────────────────────── người dùng bấm, gõ

Hệ quả:

• State nằm trong code của app (useState, biến…). POS chỉ giữ bản vẽ giao diện, không giữ state của app.
• Mỗi lần extension hiển thị chạy trong một worker riêng. Đóng modal hoặc rời màn hình thì worker dừng và state mất; dữ liệu cần giữ lâu thì lưu qua Open API hoặc server của app.
• Ô nhập không giật khi app đang bận: POS hiện ngay chữ người dùng gõ rồi mới báo cho app.
• Runtime có sẵn trong worker; app không cài thêm thư viện nào để kết nối với POS.
• Chỉ dùng được element trong danh mục component. Element lạ sẽ không hiển thị và extension báo lỗi.
• Không có window, document.querySelector, localStorage, canvas hay đo kích thước DOM. Thư viện chart hoặc UI bên ngoài không chạy trong worker; khi cần, dùng component do POS cung cấp hoặc chuyển sang trang iframe.

#Mô hình bảo mật

#Truy cập dữ liệu

App dùng chính Open API hiện có: cùng endpoint, format, phân trang. Khác ở credential:

• Không có API key cố định trong code. POS tự cấp app token khi app chạy.
• Quyền của app = quyền của người đang dùng ∩ giới hạn admin đặt cho app (kho, trường bị ẩn, chỉ đọc…).
• Mọi thao tác ghi được audit theo người dùng thật và app.

Chi tiết: Truy cập dữ liệu.

#Vòng đời app

1. Người có quyền quản lý cấu hình của shop upload bundle bằng CLI. Mỗi lần upload tạo một version.
2. POS kiểm tra manifest: target hợp lệ, file tồn tại, kích thước trong giới hạn.
3. Admin xem quyền dữ liệu và domain bên ngoài mà app yêu cầu, xác nhận cửa hàng chịu trách nhiệm về app, rồi kích hoạt version trên trang Ứng dụng tuỳ biến.
4. Mặc định mọi thành viên của shop đều thấy app; giới hạn theo bộ phận chưa có trên trang quản lý.
5. Có thể rollback về version trước, tắt app bất kỳ lúc nào. Tắt app thu hồi toàn bộ app token đang dùng.

#Giới hạn

#Phạm vi hỗ trợ

• Chỉ áp dụng trên POS web. App mobile chưa chạy extension.
• Hook phía giao diện chỉ chạy khi thao tác trên POS web, ở đúng vị trí đã gắn hook. Bản ghi tạo hoặc sửa từ Open API, app mobile, cập nhật hàng loạt hay đồng bộ sàn không đi qua hook. Quy tắc bắt buộc đúng mọi lúc cần làm ở phía server.
• App không chạy nền. Tác vụ định kỳ hoặc xử lý webhook cần backend riêng của shop (xem Truy cập dữ liệu).

#Lộ trình