Giới thiệu

Có gì mới

Thay đổi của từng bản SDK POS Apps, cách cập nhật dự án.

Xem Markdown

Thay đổi của SDK POS Apps (@pancake-pos/ui-extensions, @pancake-pos/ui, @pancake-pos/app-cli, @pancake-pos/eslint-plugin, create-pos-app). Các gói phát hành cùng số phiên bản.

  • App đã deploy không cần làm gì: runtime do POS phục vụ nên sửa lỗi và element mới có hiệu lực ngay. Mọi thay đổi trong api_version 2026-01 chỉ thêm, không phá code cũ.
  • Dự án đang viết nên cập nhật để có type, luật kiểm tra, tài liệu và ví dụ mới cho MCP. CLI tự nhắc khi có bản mới (Cập nhật SDK):
Terminal
npm i @pancake-pos/ui@latest @pancake-pos/ui-extensions@latest
npm i -D @pancake-pos/app-cli@latest @pancake-pos/eslint-plugin@latest

Dùng MCP thì khởi động lại MCP server sau khi cập nhật.

2026.1.13

  • pos.api gọi được danh mục địa chỉ của Open API: /geo/provinces, /geo/districts, /geo/communes (trước đây báo invalid_path). Trang iframe cần build lại bằng SDK này.

2026.1.12

  • Trang iframe: PosModal, PosDrawer mở thì POS làm mờ dòng tiêu đề, menu và thanh trên quanh iframe như modal của POS; bấm vùng mờ hay nhấn Esc đóng lớp trên cùng. Modal, Drawer của antd hay thư viện khác dùng usePosBackdrop(open, onClose). Xem Modal và drawer phủ cả POS.
  • Runtime API: pos.page.setBackdrop(on) và sự kiện backdrop-dismiss cho trang iframe.
  • Luật mới cho page/ (cảnh báo): Modal, Drawer, Modal.confirm của antd chỉ phủ iframe; dùng PosModal/PosDrawer, pos.ui.modal/drawer, pos.ui.confirm.
  • PosModal không tự focus nút đóng, PosDrawer không vẽ viền focus quanh màn hình, như modal của POS.
  • Trang iframe đã deploy cần build lại bằng SDK này để có lớp mờ (gói @pancake-pos/ui nằm trong bundle của app).

2026.1.11

Giao diện trang iframe

  • @pancake-pos/ui có component React cho cả 36 element pos-* (PosPage, PosSection, PosStat, PosTable…), cùng tên, thuộc tính, sự kiện { detail } với Worker UI. POS cũng vẽ Worker UI bằng các component này, nên trang iframe giống trang Worker UI tới từng điểm ảnh. Xem Giao diện trang iframe.
  • PosProvider nạp font Inter kèm gói, bỏ thẻ trắng quanh iframe để trang nằm trên nền xám như trang của POS, đưa heading, description, nút của PosPage lên dòng tiêu đề của POS. Trang đang tự vẽ nền trắng toàn trang: <PosProvider frame="card"> giữ như cũ. App đã deploy bằng SDK cũ không đổi.
  • Token màu, chữ, khoảng cách: tokens, @pancake-pos/ui/tokens.css, tailwind.css (Tailwind 4), tailwind-preset (Tailwind 3), fonts.css. Có tiếng Lào cho antd.

Runtime API

  • pos.ui.modal, pos.ui.drawer: mở trang iframe của app trong modal/drawer phủ cả POS từ block, action, trang; trang bên trong có pos.data.presentation, đóng và trả kết quả bằng pos.close(result).
  • pos.page.setHeader (tiêu đề, mô tả, tối đa 5 nút trên dòng tiêu đề; sự kiện header-action) và pos.page.setFrame cho trang iframe.
  • connect({ optional: true }), isEmbedded(), PosProvider standalone, usePosOptional(): trang tự host mở được cả ngoài POS.

Kiểm tra, mẫu

  • Luật mới cho page/ (cảnh báo): thư viện UI khác, màu ngoài bảng màu POS, tiền tự định dạng, file vào không dùng PosProvider. pos-app check báo lỗi <link>, @import, @font-face trỏ ra ngoài gói (CSP chặn khi chạy).
  • Trang iframe của create-pos-app dùng PosPage, PosFilterBar, PosTable. get_example thêm iframe-report và self-hosted.

2026.1.10

  • pos-app login kết nối qua trình duyệt: trang Kết nối CLI của POS cho chọn nhiều cửa hàng một lần, không phải sao chép token. login --token vẫn dùng cho CI. Dự án đang viết cần cập nhật SDK trước: CLI cũ chưa có login qua trình duyệt và bỏ qua deploy --all.
  • Một app cho nhiều cửa hàng: deploy --all hoặc --shop lặp lại, versions liệt kê từng cửa hàng, lệnh mới shops và use, logout --shop.
  • MCP không gắn một cửa hàng: tool list_shops; deploy nhận shops hoặc all; get_errors gộp lỗi mọi cửa hàng; list_shop_meta, sample_context nhận shop.

2026.1.9

  • CLI nhắc khi có SDK mới: npm run check, build, deploy, dev in lệnh cập nhật; kết quả --json và tool MCP (check_app, deploy, get_errors) có trường update để AI đề nghị cập nhật. Tắt bằng POS_APP_NO_UPDATE_CHECK=1.
  • Luật pos-app/valid-elements: element, thuộc tính hay sự kiện lạ mà không giống tên nào thì gợi ý cập nhật SDK (thường do code viết theo tài liệu mới hơn).
  • Trang Có gì mới này.

2026.1.8

Component

  • Mới: pos-switch, pos-radio-group, pos-time-picker, pos-file-input (POS đọc CSV/Excel thành bảng cho app).
  • pos-table: rows nhận thẳng bản ghi Open API, key của cột là đường dẫn (customer.name, items.0.sku); cột "Thao tác" rowActions với onRowAction; cột copyable.
  • pos-select: tìm qua API bằng onSearch và loading. pos-date-picker: time để chọn cả giờ.
  • pos-modal: width (520, 720, 1000 px). Footer của pos-modal, pos-drawer nhận thêm pos-menu-button, pos-link.

API (runtime-api)

  • pos.api.paginate tải nhiều trang song song trong giới hạn tần suất; pos.api.get(path, { cache }) nhớ danh mục.
  • pos.download({ sheet }): POS dựng file .xlsx hoặc .csv từ cột và dòng.
  • pos.navigate({ resource: 'order', id }) mở đơn ở tab mới. pos.format định dạng số, tiền, ngày như POS. pos.clipboard.copy.

Runtime và công cụ

  • Giá trị sai schema (kiểu sai, element đặt sai chỗ, chữ quá dài) không còn dừng extension: POS bỏ phần sai và ghi vào nhật ký lỗi.
  • Chế độ phát triển ghi cảnh báo "Màn hình chuẩn" (standard_screen) vào nhật ký, đọc bằng get_errors.
  • Tool MCP get_example: app mẫu hoàn chỉnh (báo cáo, danh sách có panel chi tiết, nhập từ file, block trong form đơn, mẫu in, hook).

2026.1.7

  • Element cho màn báo cáo và danh sách: pos-stat, pos-date-range, pos-menu-button, pos-description-list, pos-timeline, pos-progress, pos-empty, pos-drawer.
  • pos-table: cột format badge, link, percent, tones, subtitle, sortable, fixed, ellipsis; sort, summary, selectable, selected; sự kiện onSortChange, onSelectionChange, onCellClick.
  • pos-chart: kết hợp cột và đường, biểu đồ ngang, phần trăm. pos-button: icon, tooltip.
  • pos.download tải file app tạo.
  • Luật pos-app/standard-screen (cảnh báo) theo Màn hình chuẩn; template create-pos-app có trang báo cáo mẫu.
  • Tool MCP search_api, get_api tra endpoint Open API.
  • Sửa: chế độ phát triển không tải được dữ liệu khi POS gọi API qua pos.pancake.vn.

2026.1.6

  • Tài liệu và template chạy CLI qua npm run … hoặc npx @pancake-pos/app-cli … (gói pos-app trên npm không phải của Pancake).

2026.1.5

  • Target khách hàng: customer.details.action, customer.index.action, customer.index.selection-action, customer.index.column.

2026.1.4

  • Trang Worker UI (app.page với render: "worker") và element trang: pos-page, pos-tabs, pos-filter-bar, pos-chart.
  • Cột trong danh sách (<resource>.index.column), mẫu in của app (<resource>.print-action), khối hồ sơ khách hàng (customer.details.block).