Pancake POSNhà phát triển
/
llms.txt
VIEN
Hướng dẫn

Quản lý ứng dụng trong POS

Mở trang Ứng dụng tuỳ biến, duyệt quyền và kích hoạt version, bật tắt app, quay về version cũ, xem lỗi, kết nối CLI và chế độ phát triển.

Xem Markdown

Mọi việc quản lý app của shop nằm trên trang Ứng dụng tuỳ biến trong POS: duyệt quyền và kích hoạt version, bật tắt, quay về version cũ, xem lỗi, kết nối CLI và bật chế độ phát triển.

Trang này chỉ hiện với tài khoản có quyền quản lý cấu hình, trên shop đã được Pancake bật POS Apps.

Mở trang quản lý

  1. Trong POS, bấm Cấu hình (biểu tượng bánh răng ở thanh bên trái).
  2. Ở nhóm Nâng cao, chọn Ứng dụng tuỳ biến.

Mục Ứng dụng tuỳ biến trong nhóm Nâng cao của trang Cấu hình

Đường dẫn trực tiếp: https://pos.pancake.vn/shop/<mã shop>/setting/custom-apps.

Danh sách ứng dụng

Danh sách ứng dụng tuỳ biến của shop

Cột hoặc nút Ý nghĩa
Ứng dụng Tên app và handle trong pos-app.json.
Trạng thái Công tắc bật/tắt app. App chưa có version nào được kích hoạt thì hiện nút Duyệt & kích hoạt.
Phiên bản đang dùng Version mọi người trong shop đang dùng.
Phiên bản Danh sách version đã upload; kích hoạt hoặc quay về version cũ.
Nhật ký lỗi Lỗi khi chạy POS ghi lại cho app.
Xóa ứng dụng Chỉ hiện khi app đang tắt; xóa app cùng mọi version (mục Xóa ứng dụng).
Chế độ phát triển Nạp bản đang chạy bằng pos-app dev trên máy bạn, chỉ trong trình duyệt này.
Kết nối CLI Tạo token cho lệnh pos-app và thu hồi token của shop.

App xuất hiện trong danh sách sau lần upload đầu tiên (pos-app deploy hoặc tool deploy của MCP).

Duyệt và kích hoạt version

Mỗi lần upload tạo một version chưa kích hoạt; người dùng chưa thấy gì cho tới khi quản trị viên kích hoạt.

  1. Bấm Phiên bản ở dòng của app (hoặc Duyệt & kích hoạt với app mới). Danh sách hiện version kèm ngày tải lên, nguồn (cli hoặc mcp), ghi chú lúc deploy và người duyệt. Mỗi app giữ 20 version gần nhất cùng version đang chạy; version cũ hơn tự xóa khi upload version mới.

    Danh sách version của app, version mới có nút Kích hoạt

  2. Bấm Kích hoạt ở version cần dùng. POS hiện những gì app yêu cầu:

    • Thao tác dữ liệu: Xem, Tạo mới, Sửa, Xóa theo access.methods. Thao tác ghi được tô màu cam.
    • Giới hạn dữ liệu: kho, nguồn đơn, trạng thái đơn, trường bị ẩn, danh mục sản phẩm… theo access. Không khai thì app theo đúng quyền của người dùng.
    • Máy chủ bên ngoài: domain trong network.allowed_origins mà app được gọi.
    • Trang tự host: địa chỉ url của trang app.page tự host, nếu có.
    • Vị trí hiển thị: từng extension và target của nó.

    Hộp duyệt quyền trước khi kích hoạt version

  3. Xem kỹ thao tác ghi và máy chủ bên ngoài, tick ô xác nhận app do cửa hàng tự phát triển và cửa hàng chịu trách nhiệm về dữ liệu app đọc, ghi, rồi bấm Kích hoạt. POS ghi lại người duyệt và thời điểm ở cột Người duyệt. Người dùng thấy version mới ở lần tải trang kế tiếp.

Mặc định mọi thành viên của shop đều thấy app; dữ liệu app đọc/ghi vẫn giới hạn trong quyền của từng người (xem Truy cập dữ liệu).

Quay về version cũ

Mở Phiên bản và bấm Kích hoạt ở version cũ. POS vẫn hiện lại hộp duyệt quyền của version đó trước khi đổi.

Tắt và bật lại app

Gạt công tắc ở cột Trạng thái:

  • Tắt: mọi extension của app biến mất khỏi POS và app token đang dùng bị thu hồi ngay. Dùng khi app lỗi nặng hoặc nghi bị lộ dữ liệu.
  • Bật lại: app chạy lại với version đang kích hoạt, không phải duyệt lại.

Xóa ứng dụng

App không dùng nữa thì xóa để giải phóng dung lượng của shop:

  1. Tắt app bằng công tắc ở cột Trạng thái.
  2. Bấm Xóa ứng dụng ở dòng của app, rồi xác nhận.

POS xóa mọi version, gói đã upload và nhật ký lỗi của app, không khôi phục được. App đang bật không xóa được. Muốn dùng lại thì pos-app deploy như app mới (dùng lại được handle cũ).

Giới hạn của shop

  • Tối đa 10 app đang bật. Số app upload không giới hạn, chỉ app đang bật được tính. Đủ 10 app thì kích hoạt hoặc bật thêm sẽ báo "Cửa hàng chỉ bật được tối đa 10 ứng dụng"; tắt một app để có chỗ.
  • Tối đa 500 MB cho toàn bộ app. Tính tổng các version còn giữ của mọi app, kể cả app đang tắt. Mỗi app giữ 20 version gần nhất cùng version đang chạy; bản cũ hơn tự xóa khi upload bản mới. Vượt hạn mức thì pos-app deploy báo storage_quota_exceeded; xóa ứng dụng không dùng để giải phóng.

Các giới hạn khác: Tổng quan › Giới hạn.

Nhật ký lỗi

Bấm Nhật ký lỗi để xem lỗi POS ghi lại khi app chạy trên máy người dùng: thời điểm, extension (id trong manifest), mã lỗi và nội dung.

Nhật ký lỗi của một app

Mã lỗi Nghĩa
uncaught Code của app ném lỗi mà không bắt.
timeout Module không trả kết quả trong thời gian cho phép (ví dụ before_submit quá timeout_ms).
module_timeout Module không khởi động kịp.
render_error POS không vẽ được giao diện app gửi lên.
hook_failed, should_render_failed, invalid_result Hook hoặc should_render lỗi, hay trả sai kiểu kết quả.
frame_timeout Không tải được sandbox của app (mạng chặn domain sandbox, hoặc sandbox đang lỗi).

POS giữ 500 lỗi gần nhất của mỗi app trong 7 ngày. Lập trình viên đọc cùng nhật ký này bằng tool get_errors của MCP.

Kết nối CLI

Lệnh pos-app (và MCP server) cần token để upload app lên shop.

  1. Bấm Kết nối CLI › Tạo token.
  2. Bấm biểu tượng sao chép và chạy lệnh trên máy của bạn. Lệnh chỉ hiện một lần; đóng hộp thoại thì phải tạo token mới.

Hộp Kết nối CLI: lệnh đăng nhập và danh sách token đang dùng được

  • Token có hạn 30 ngày và hết hiệu lực khi người tạo đăng xuất khỏi POS.
  • Token chỉ làm được việc của lập trình viên: upload version, xem app, version, lỗi và dữ liệu mẫu. Token không kích hoạt version và không đổi cấu hình shop.
  • Bảng Token đang dùng được liệt kê token của mọi người trong shop. Bấm Thu hồi khi token không còn dùng hoặc nghi bị lộ. Lệnh pos-app logout cũng thu hồi token trên máy đó.

Chế độ phát triển

Chế độ phát triển cho bạn thử code đang viết ngay trong POS thật mà không ảnh hưởng người khác.

  1. Trên máy, chạy npx pos-app dev trong thư mục app (mặc định phục vụ tại http://localhost:5174).
  2. Bấm Chế độ phát triển, nhập Địa chỉ máy phát triển rồi bấm Bật chế độ phát triển.

Hộp Chế độ phát triển

  • Chỉ trình duyệt đang dùng nạp bản dev; người khác trong shop vẫn dùng version đang kích hoạt.
  • Sửa code thì POS tự nạp lại extension, không phải tải lại trang.
  • Mở lại hộp này và bấm Tắt chế độ phát triển khi xong.

Chi tiết và lưu ý về dữ liệu thật: Bắt đầu › Chạy thử với POS.

Câu hỏi thường gặp

Không thấy mục Ứng dụng tuỳ biến. Tài khoản thiếu quyền quản lý cấu hình. Nếu đã có quyền mà vẫn không thấy, liên hệ Pancake.

Đã kích hoạt mà chưa thấy app. Tải lại trang POS. Kiểm tra công tắc ở cột Trạng thái đang bật và conditions của extension khớp với bản ghi đang mở.

pos-app deploy báo storage_quota_exceeded. Shop đã dùng hết 500 MB cho app. Xóa ứng dụng không dùng nữa rồi deploy lại.

Nhân viên thấy app nhưng báo lỗi không đủ quyền. App dùng quyền của chính người đang dùng. Cấp thêm quyền cho nhân viên đó, hoặc để app xử lý lỗi 403 (xem Truy cập dữ liệu).

Gặp lỗi của nền tảng hoặc cần tính năng mới. Nhờ công cụ AI gửi báo cáo bằng tool send_feedback của MCP, hoặc liên hệ Pancake.