# Làm app với AI

> Trang này dành cho người viết app bằng công cụ AI (Claude Code, Cursor, Codex, Copilot…) và cho chính công cụ AI đọc.

## Cho AI hiểu POS Apps

| Cách | Dùng khi | AI làm được |
|---|---|---|
| **MCP server `pos-app`** (khuyên dùng) | Công cụ AI hỗ trợ MCP | Tra tài liệu, xem mã thật của shop, kiểm tra app, chạy thử trong POS, đọc lỗi, deploy, báo lỗi cho Pancake |
| **`AGENTS.md`** | Mọi dự án tạo bằng `create-pos-app` | Đọc quy tắc bắt buộc mỗi lần sửa code |
| **`llms-full.txt`** | Công cụ không hỗ trợ MCP, hoặc chat trên web | Đọc toàn bộ tài liệu một lần |

Ba cách dùng chung được: dự án tạo bằng `create-pos-app` đã có `AGENTS.md`, chỉ cần thêm MCP server.

## MCP

`pos-app mcp` chạy một [MCP](https://modelcontextprotocol.io) server để công cụ AI tự tra tài liệu và endpoint Open API, xem dữ liệu nền thật của shop, kiểm tra app, đọc lỗi khi chạy và deploy ngay trong cuộc trò chuyện. Server chạy trên máy của bạn (stdio), trong thư mục dự án app, bằng tài khoản đã đăng nhập qua `pos-app login`.

### Kết nối MCP server

1. Kết nối CLI một lần: chạy `npx @pancake-pos/app-cli login`, chọn các cửa hàng trên trình duyệt rồi bấm **Cho phép** (xem [Quản lý ứng dụng › Kết nối CLI](/developers/apps/manage-apps#ket-noi-cli)).
2. Thêm server vào công cụ AI, trong thư mục dự án app. Tool cần cửa hàng dùng cửa hàng mặc định của CLI, hoặc cửa hàng AI truyền vào (`list_shops` liệt kê cửa hàng đã kết nối):

```bash
# Claude Code
claude mcp add pos-app -- npx @pancake-pos/app-cli mcp
```

Cursor (`.cursor/mcp.json` trong dự án):

```json
{
  "mcpServers": {
    "pos-app": { "command": "npx", "args": ["@pancake-pos/app-cli", "mcp"] }
  }
}
```

VS Code với Copilot (`.vscode/mcp.json` trong dự án):

```json
{
  "servers": {
    "pos-app": { "type": "stdio", "command": "npx", "args": ["@pancake-pos/app-cli", "mcp"] }
  }
}
```

```toml
# Codex: ~/.codex/config.toml
[mcp_servers.pos-app]
command = "npx"
args = ["@pancake-pos/app-cli", "mcp"]
```

Claude Desktop (`claude_desktop_config.json`) không chạy trong thư mục dự án, nên thêm `--cwd`:

```json
{
  "mcpServers": {
    "pos-app": { "command": "npx", "args": ["@pancake-pos/app-cli", "mcp", "--cwd", "/đường/dẫn/tới/my-app"] }
  }
}
```

3. Mở lại công cụ AI và hỏi "Liệt kê tool của pos-app". Trong Claude Code, lệnh `/mcp` cho biết server đã kết nối chưa.

### Tool

| Tool | Đầu vào | Trả về |
|---|---|---|
| `search_docs` | `query` | Các đoạn tài liệu khớp, dạng Markdown |
| `get_target` | `target`, ví dụ `purchase.details.action` | Schema dữ liệu ngữ cảnh, giá trị cần trả về, trường manifest và ví dụ ngắn |
| `list_shop_meta` | `resource`, `shop` | Mã và tên dùng được trong `conditions` và code: trạng thái, thẻ, kho, danh mục sản phẩm, nguồn đơn. Mã thuộc riêng từng cửa hàng |
| `sample_context` | `target`, mã bản ghi, `shop` (không bắt buộc) | `pos.data` mẫu dựng từ dữ liệu thật của cửa hàng, đã lọc theo `access` của app và quyền của người đăng nhập |
| `list_shops` | | Cửa hàng đã kết nối, cửa hàng mặc định, và với app đang làm: đã upload chưa, version đang kích hoạt, version mới nhất |
| `search_api` | `query`, ví dụ `order list` hay `post order` | Endpoint Open API app được gọi bằng `pos.api` (method, đường dẫn, tóm tắt) và `access.methods` mỗi endpoint cần |
| `get_example` | `id` (bỏ trống để xem danh sách) | Mẫu app đầy đủ theo Màn hình chuẩn: trang báo cáo, trang danh sách có panel chi tiết, trang nhập từ file CSV/Excel, block trong form đơn, mẫu in, hook kiểm tra trước khi lưu, trang iframe dùng `@pancake-pos/ui`, trang tự host; kèm phần manifest và toàn bộ code |
| `get_api` | `path` và `method`, hoặc `schema` | Cách gọi một endpoint: lệnh `pos.api`, tham số đường dẫn và query, dạng request body và response, ví dụ. `field` mở một object lồng nhau (`data.items`, `body.customer`) |
| `check_app` | không có | Kết quả `pos-app check`: từng lỗi kèm file, dòng, mã luật và gợi ý sửa |
| `dev_start`, `dev_status` | không có | Chạy `pos-app dev`; trả URL local, link POS cần mở ở chế độ phát triển và lỗi build |
| `get_errors` | `version` (mặc định `dev`), `since`, `shop` | Lỗi khi chạy mà POS ghi lại cho app: target, nội dung, stack trace, thời điểm. `dev` là bản đang chạy trên máy, có thêm cảnh báo `standard_screen` về layout; version đã upload thì gộp lỗi ở mọi cửa hàng đã kết nối (mỗi lỗi ghi `shop`) |
| `deploy` | `message`, `shops` hoặc `all` | Chạy `check` và `build` một lần, rồi upload version mới **chưa kích hoạt** lên cửa hàng mặc định, các cửa hàng trong `shops`, hoặc mọi cửa hàng đã kết nối; trả về version và link trang quản lý ứng dụng của từng cửa hàng |
| `send_feedback` | `kind` (`bug` hoặc `feature`), `title`, `description`, `include_errors` | Gửi báo lỗi hoặc yêu cầu tính năng về POS Apps cho đội hỗ trợ POS của Pancake; trả mã `FB-…` |

- `deploy` không bao giờ kích hoạt version. Quản trị viên duyệt quyền và kích hoạt trên trang [Ứng dụng tuỳ biến](/developers/apps/manage-apps#duyet-va-kich-hoat-version), giống hệt `pos-app deploy`.
- Nếu `version` trong `pos-app.json` đã tồn tại, `deploy` báo lỗi `duplicate_version`; tăng `version` rồi deploy lại.
- Tool chạy dưới danh nghĩa người đã đăng nhập, trên shop đã chọn. Tool không trả app token hay API key và không ghi dữ liệu shop: `list_shop_meta` và `sample_context` chỉ đọc. `search_api` và `get_api` đọc bản Open API đóng gói kèm CLI, không gọi API nào. Code của app vẫn đọc/ghi dữ liệu qua `pos.api`.

### Vòng làm việc

1. `get_target` và `search_docs` để chọn đúng target và kiểu dữ liệu.
2. `list_shop_meta` và `sample_context` để viết `conditions` và code theo mã, trường thật.
3. `search_api` và `get_api` trước mỗi lần gọi `pos.api`, để dùng đúng endpoint đã công bố với tham số và dạng response chính xác.
4. `get_example` lấy mẫu cùng loại màn hình rồi chép cấu trúc; viết code, chạy `check_app` đến khi hết lỗi.
5. `dev_start`, thử app trong POS, rồi `get_errors` để sửa lỗi khi chạy và cảnh báo layout.
6. `deploy` và nhờ quản trị viên kích hoạt version mới.

### Câu lệnh mẫu

```text
Tạo app POS "Nhắc công nợ": block trong form đơn hiện tổng công nợ của khách,
nút "Gửi nhắc nợ" gọi https://crm.example.com/api/remind. Chỉ cần quyền đọc.
Dùng sample_context để lấy dữ liệu đơn thật, check_app đến khi hết lỗi, rồi dev_start để tôi thử trong POS.
```

```text
Nút "Đẩy sang ERP" của version 1.2.0 đang báo lỗi. Đọc get_errors của version đó, tìm nguyên nhân, sửa,
tăng version rồi deploy kèm ghi chú.
```

```text
Chỉ hiện action "Duyệt đơn" với đơn ở trạng thái Chờ xác nhận và nguồn Facebook.
Lấy mã trạng thái và nguồn đơn bằng list_shop_meta, không viết cứng theo tên.
```

## Báo lỗi và đề xuất tính năng

Gặp lỗi của nền tảng (runtime, component, SDK, CLI, MCP, tài liệu, Open API) hoặc cần tính năng chưa có, nhờ công cụ AI gửi cho Pancake bằng tool `send_feedback`:

```text
Báo cho Pancake: pos-table không hiện cột ngày khi format là "date".
```

1. AI soạn tiêu đề và mô tả (lỗi gì, mong đợi gì, các bước tái hiện; hoặc nhu cầu và tình huống dùng), cho bạn xem trước.
2. Bạn đồng ý thì AI mới gửi. Báo cáo vào thẳng kênh hỗ trợ POS của Pancake; AI trả lại mã `FB-…` để bạn dẫn khi trao đổi tiếp.

Báo cáo tự kèm phiên bản CLI và runtime, hệ điều hành, Node, handle và version của app, 5 lỗi gần nhất của app (bỏ bằng `include_errors: false`). Không gửi code hay dữ liệu shop; token lỡ dán vào nội dung bị che trước khi gửi. Mỗi shop gửi tối đa 20 báo cáo mỗi ngày.

## Không dùng MCP

- Toàn bộ tài liệu dạng Markdown: `/developers/apps/llms-full.txt`. Mục lục: `/developers/apps/llms.txt`. Mỗi trang có bản Markdown tại cùng đường dẫn thêm `.md`, ví dụ `/developers/apps/targets.md`.
- Các file cho LLM mặc định là tiếng Anh. Bản tiếng Việt nằm ở `/developers/apps/vi/`, ví dụ `/developers/apps/vi/llms-full.txt`.
- Template `create-pos-app` sinh sẵn `AGENTS.md` với nội dung ở [mục cuối](#agents-md-mau). Giữ file này trong dự án để AI luôn đọc quy tắc.

Câu lệnh mẫu:

```text
Đọc https://pos.pages.fm/developers/apps/llms-full.txt.
Tạo app POS "Nhắc công nợ": block trong form đơn hiện tổng công nợ của khách,
nút "Gửi nhắc nợ" gọi https://crm.example.com/api/remind. Chỉ cần quyền đọc.
```

## Quy tắc bắt buộc

### Môi trường chạy

1. Code trong `extensions/` chạy trong **Web Worker**, không có DOM thật.
   - Không dùng `window`, `document.querySelector`, `document.getElementById`, `localStorage`, `sessionStorage`, `alert`, `confirm`, `canvas`, `getBoundingClientRect`.
   - Không import thư viện UI (antd, MUI, Tailwind, thư viện chart, thư viện kéo thả) và file CSS.
   - Dùng Preact (khuyến nghị) hoặc JS thuần để render element `pos-*` vào `document.body`. Không dùng React trong `extensions/`.
   - Không cài thư viện nào để kết nối hay vẽ giao diện với POS; runtime POS đã có sẵn trong worker.
2. Trang iframe (`page/`) là ứng dụng web bình thường: lấy `pos` bằng `<PosProvider>`/`usePos()` của `@pancake-pos/ui` (hoặc `connect()`), không truy cập `window.top`/`window.parent` và không dùng route bắt đầu bằng `/_pos/` (dành riêng cho POS). Dựng giao diện bằng component của `@pancake-pos/ui` (xem [Giao diện trang iframe](/developers/apps/page-ui)), không dùng thư viện UI khác. Hộp xác nhận, form ngắn dùng `PosModal`/`PosDrawer` (POS làm mờ phần quanh iframe); panel chi tiết, form rộng cao hết màn hình dùng `pos.ui.modal`/`drawer`.

### Giao diện

3. Extension Worker UI **chỉ** dùng element trong [Component giao diện](/developers/apps/components). Không dùng `div`, `span`, `p`, `img`, `table`, `button`, `input`.
4. Text phải nằm trong `pos-text`, `pos-heading`, `pos-badge`, `pos-link`, `pos-button` hoặc `pos-banner`.
5. Không dùng `style`, `className`. Giá trị sự kiện lấy từ `event.detail`.
6. Số tiền hiển thị bằng `pos-money` hoặc cột `format: 'money'`, không tự định dạng.

### Dữ liệu

7. Dữ liệu POS chỉ lấy qua `pos.api` với đường dẫn `/shops/${pos.shop.id}/...` và endpoint có trong [Open API](/developers/api).
8. Không viết cứng shop id, API key, token; không gửi app token ra ngoài, trừ backend của [trang tự host](/developers/apps/runtime-api#trang-tu-host); không đặt secret trong code.
9. Mọi method dùng trong code (`POST`, `PUT`, `DELETE`) phải có trong `access.methods`. Mọi domain ngoài (kể cả ảnh của `pos-image`) phải có trong `network.allowed_origins`.
10. Đọc bản ghi hiện tại từ `data.record` (`data.records` ở action hàng loạt). Gọi Open API bằng `record.system_id` với đơn hàng, `record.id` với sản phẩm, phiếu nhập, phiếu xuất, phiếu chuyển kho.

### Module và manifest

11. Mỗi module có `export default async function (data)`.
    - Block, action `modal`/`fullscreen`, trang `render: "worker"`: render vào `document.body`.
    - Action `headless`: trả `{ message?, refresh? }` hoặc ném lỗi.
    - `should_render`: trả `boolean`, chạy dưới 300 ms, không gọi API chậm.
    - `*.before_submit`: trả `{ ok: true }` hoặc `{ ok: false, message }`, chạy dưới `timeout_ms`.
12. Mỗi extension trong `pos-app.json` có `id` duy nhất; `target` phải có trong [Extension point](/developers/apps/targets).
13. Nên bọc module bằng `defineExtension(target, fn)` từ `@pancake-pos/ui-extensions` để type của `data` và giá trị trả về khớp target.

### Chất lượng

14. Bọc mọi lời gọi API trong `try/catch`; hiện lỗi bằng `pos-banner` (trong giao diện) hoặc `pos.toast.show(..., { tone: 'error' })`.
15. Xử lý `403` (người dùng không đủ quyền) và `429` (thử lại sau, tăng dần thời gian chờ).
16. Không gọi API trong mỗi lần render; dùng `useEffect` với dependency rõ ràng, phân trang và `AbortController`.
17. Viết giao diện bằng ngôn ngữ của người dùng (`pos.user.locale`); mặc định tiếng Việt.
18. Sau mỗi lần sửa, chạy `npx eslint .` (hoặc tool `check_app`) và sửa hết lỗi. Không thêm `eslint-disable` để né lỗi; `pos-app check` vẫn chặn deploy.

## Lỗi thường gặp

| Sai | Đúng |
|---|---|
| `<div className="box">…</div>` | `<pos-section heading="…">…</pos-section>` |
| `<input onChange={(e) => set(e.target.value)} />` | `<pos-text-field onChange={(e) => set(e.detail)} />` |
| `fetch('https://pos.pages.fm/api/v1/shops/123/orders?api_key=...')` | `` pos.api.get(`/shops/${pos.shop.id}/orders`) `` |
| `localStorage.setItem(...)` trong extension | Lưu qua Open API (bảng CRM) hoặc backend riêng |
| `alert('Xong')` | `pos.toast.show('Xong')` |
| `data.order`, `data.purchase` | `data.record` (`data.resource` cho biết loại bản ghi) |
| `` `/shops/${shopId}/purchases/${record.display_id}` `` | `` `/shops/${shopId}/purchases/${record.id}` `` |
| `import { Table } from 'antd'` trong extension | `<pos-table columns={…} rows={…} />` |
| Gọi `PUT` khi `access.methods` chỉ có `GET` | Thêm `"PUT"` vào `access.methods` |
| `new Intl.NumberFormat(...).format(total) + 'đ'` | `<pos-money value={total} />` |

## Checklist trước khi deploy

- [ ] `pos-app.json` hợp lệ: `handle`, `version` mới, `api_version`, `id` không trùng.
- [ ] `access.methods` đủ cho mọi request ghi; không xin quyền thừa.
- [ ] Mọi domain ngoài nằm trong `network.allowed_origins`.
- [ ] Module trong `extensions/` không dùng DOM thật, thư viện UI hay CSS.
- [ ] Không có token, API key, secret trong code.
- [ ] Có xử lý lỗi và trạng thái đang tải.
- [ ] Màn hình Worker UI theo [Màn hình chuẩn](/developers/apps/components#man-hinh-chuan): không emoji, không lặp tiêu đề, số liệu dùng `pos-stat`.
- [ ] `npm run check` không còn lỗi.
- [ ] Chạy thử bằng `npm run dev` (tài khoản có quyền Cấu hình), rồi deploy lên shop test và thử với tài khoản nhân viên quyền hẹp.

## AGENTS.md mẫu

````markdown
# POS App

Dự án này là app tuỳ biến chạy trong Pancake POS.
Tài liệu: https://pos.pages.fm/developers/apps/llms-full.txt (đọc trước khi sửa code).

## Cấu trúc
- pos-app.json: manifest (quyền, domain ngoài, extension).
- extensions/: module chạy trong Web Worker, render element pos-* bằng Preact.
- extensions/report.tsx: trang Worker UI mẫu theo layout chung của POS; trang mới chép theo cấu trúc này.
- page/: trang iframe (React + Vite) nằm trong `<PosProvider>` của `@pancake-pos/ui`, lấy `pos` bằng `usePos()`; route bắt đầu bằng /_pos/ dành riêng cho POS.

## Quy tắc
- extensions/: không dùng DOM thật, window, localStorage, React, thư viện UI, CSS. Chỉ dùng element pos-* có trong tài liệu.
- Text nằm trong pos-text/pos-heading/pos-badge/pos-link/pos-button/pos-banner. Giá trị sự kiện ở event.detail.
- Màn hình Worker UI theo Component > Màn hình chuẩn: pos-page làm khung trang, pos-section làm thẻ, pos-stat trong pos-grid cho số liệu, một pos-filter-bar cho bộ lọc, pos-tabs có badge cho lọc trạng thái. Không emoji hay ký tự trang trí trong nhãn, không lặp tiêu đề trang, không bọc từng element trong pos-section.
- Dữ liệu POS chỉ qua pos.api với đường dẫn /shops/${pos.shop.id}/... và endpoint Open API.
- Không viết cứng shop id, API key, token, secret.
- Method ghi phải có trong access.methods; domain ngoài phải có trong network.allowed_origins.
- Module: export default async function (data). Headless trả { message }; before_submit trả { ok, changes? } (changes: note, add_tags) hoặc { ok: false, message }; *.print-action trả { html }; *.index.column trả { values }.
- page/: dựng giao diện bằng component của @pancake-pos/ui (PosPage, PosSection, PosTable…: cùng tên, thuộc tính, event.detail với element pos-*) và token của gói; không dùng thư viện UI khác, màu tự chọn, tự định dạng tiền (dùng PosMoney, pos.format.money) hay font, CSS, script từ ngoài.
- page/: hộp xác nhận, form ngắn dùng PosModal/PosDrawer (POS làm mờ phần quanh iframe); panel chi tiết, form rộng dùng pos.ui.drawer/pos.ui.modal (cao hết màn hình). Không dùng Modal, Drawer của antd.
- Bắt lỗi mọi lời gọi API; xử lý 403 và 429.

## Lệnh
- Chạy CLI qua các script npm dưới đây, hoặc npx @pancake-pos/app-cli <lệnh> (login, versions, mcp). Không chạy npx pos-app: gói pos-app trên npm không phải của Pancake, npx tải gói đó về khi dự án chưa cài.
- npm run dev: chạy thử với POS (bật Chế độ phát triển trong trang quản lý ứng dụng tuỳ biến); POS tự nạp lại khi sửa code.
- npx eslint .: kiểm tra code sau mỗi lần sửa; không thêm eslint-disable để né lỗi.
- npm run typecheck: TypeScript cho extensions/ (Preact) và page/ (React).
- npm run check: kiểm tra manifest và code; sửa hết lỗi trước khi deploy.
- CLI hoặc kết quả MCP báo có SDK mới (`update`): báo người dùng và đề nghị chạy lệnh đi kèm. Element, thuộc tính hay sự kiện có trong tài liệu mà check báo không tồn tại cũng là do SDK cũ: cập nhật thay vì tìm cách né.
- npm run deploy: build, kiểm tra manifest, upload version mới (tuỳ chọn đặt sau --, ví dụ npm run deploy -- --message "...").
- Có MCP server pos-app: gọi get_target/list_shop_meta/sample_context trước khi viết code, search_api/get_api trước mỗi lần gọi pos.api, get_example trước khi làm màn hình mới, check_app sau mỗi lần sửa, get_errors sau khi thử trong POS (cả cảnh báo layout), deploy khi xong (upload version chưa kích hoạt; admin kích hoạt; nhiều cửa hàng thì list_shops rồi deploy với shops hoặc all). Mã lấy từ list_shop_meta/sample_context thuộc riêng một cửa hàng: tra theo tên lúc chạy. Gặp lỗi của nền tảng hoặc thiếu tính năng: soạn báo cáo, cho người dùng xem, chỉ gọi send_feedback khi họ đồng ý.
````
