# PCE TW GUI documentation

## SuiteApp 操作手冊

帳上：**PCE GUI → 說明**（可下載進項／發票本 CSV 範本）。專案 Markdown 為同一份手冊。

| Document | Word | Audience | Language |
|----------|------|----------|----------|
| [PCE_GUI_MODULE_suiteapp-user-guide.md](./PCE_GUI_MODULE_suiteapp-user-guide.md) | [PCE_GUI_MODULE_suiteapp-user-guide.docx](./word/PCE_GUI_MODULE_suiteapp-user-guide.docx) | Admins, accountants, consultants | 繁中 |
| [PCE_GUI_MODULE_suiteapp-user-guide.en.md](./PCE_GUI_MODULE_suiteapp-user-guide.en.md) | [PCE_GUI_MODULE_suiteapp-user-guide.en.docx](./word/PCE_GUI_MODULE_suiteapp-user-guide.en.docx) | Admins, accountants, consultants | English |
| [samples/README.md](./samples/README.md) | — | 會計（CSV 範本下載目錄） | 繁中 |

Screenshots used in the user guides live under [`images/user-guide/`](./images/user-guide/).

## Purchases (AP)

**實作進度（建議先看）**：[PCE_GUI_MODULE_ap-status.md](./PCE_GUI_MODULE_ap-status.md) · [HTML](./html/PCE_GUI_MODULE_ap-status.html) · [SuiteApp 實作進度總覽 HTML](./html/index.html)

| 瀏覽方式 | 說明 |
|----------|------|
| **Cloudflare Pages** | Private repo 可用；步驟見 **[CLOUDFLARE-PAGES.md](./CLOUDFLARE-PAGES.md)**。預設總覽：<https://pceguitw-status.pages.dev/html/index.html>（部署後生效；根 URL 經 [index.html](./index.html) 導向）。 |
| **本機** | `npm run serve:status` → http://127.0.0.1:8765/html/index.html（伺服器根目錄＝`docs/`，`../` 才連到藍圖等 `.md`）。 |

進項 CP／CPD 前更新 Markdown，再跑 `npm run build:status-html`（或 push 後由 [sync-status-html workflow](../.github/workflows/sync-status-html.yml) 自動同步 HTML）。

日常操作見使用說明 **§5.1–5.4**；外部介接見 AP Write 文件。

| Document | Audience | Language |
|----------|----------|----------|
| [PCE_GUI_MODULE_ap-status.md](./PCE_GUI_MODULE_ap-status.md) | 進度／做沒做／變更紀錄 | 繁中 |
| [PCE_GUI_MODULE_suiteapp-user-guide.md](./PCE_GUI_MODULE_suiteapp-user-guide.md) §5.1–5.4 | 進項登錄、CSV | 繁中 |

## Sales (AR)

**實作進度（建議先看）**：[PCE_GUI_MODULE_ar-status.md](./PCE_GUI_MODULE_ar-status.md) · [HTML](./html/PCE_GUI_MODULE_ar-status.html) — 同上（Pages／本機／`build:status-html`／CI 同步）。

**平台（規劃中）**：[PCE_GUI_MODULE_suitetax-plan.md](./PCE_GUI_MODULE_suitetax-plan.md) — SuiteTax 與 Legacy 稅碼／銷項開立支援。

開立取配號操作見使用說明 **§5.5**（繁中／英文）；完整流程見 [取號流程與邏輯](./PCE_GUI_MODULE_ar-invoice-numbering.md)；規格見藍圖 **§9.5**。

| Document | Audience | Language |
|----------|----------|----------|
| [PCE_GUI_MODULE_ar-status.md](./PCE_GUI_MODULE_ar-status.md) | 進度／做沒做／變更紀錄 | 繁中 |
| [PCE_GUI_MODULE_ar-invoice-numbering.md](./PCE_GUI_MODULE_ar-invoice-numbering.md) | 開立取號流程與邏輯（現行實作） | 繁中 |
| [PCE_GUI_MODULE_ar-blueprint.md](./PCE_GUI_MODULE_ar-blueprint.md) | Product / consultants / developers | 繁中 |
| [PCE_GUI_MODULE_ar-field-map-mig41.md](./PCE_GUI_MODULE_ar-field-map-mig41.md) | 銷項主檔／表身欄位（MIG 4.1） | 繁中 |
| [reference/電子發票B2BB2C中介文字檔MIG4.1說明.pdf](./reference/電子發票B2BB2C中介文字檔MIG4.1說明.pdf) | MIG 來源 PDF | — |
| [prototypes/einvoice-issue.html](./prototypes/einvoice-issue.html) | UX prototype（開立銷項發票） | — |

## 營業稅申報（跨 AP＋AR）

**實作進度**：[PCE_GUI_MODULE_vat-filing-status.md](./PCE_GUI_MODULE_vat-filing-status.md) · [HTML](./html/PCE_GUI_MODULE_vat-filing-status.html) — 頂部導覽「營業稅申報」分頁；進項＋銷項合併產 **TXT／T02**，含 **空白字軌／空白發票**（規格見 [銷項藍圖 §5](./PCE_GUI_MODULE_ar-blueprint.md)）。

## AP Write API

| Document | Word | Audience | Language |
|----------|------|----------|----------|
| [PCE_GUI_MODULE_ap-write-api-integration-guide.md](./PCE_GUI_MODULE_ap-write-api-integration-guide.md) | [PCE_GUI_MODULE_ap-write-api-integration-guide.docx](./word/PCE_GUI_MODULE_ap-write-api-integration-guide.docx) | External vendors | 繁中 |
| [PCE_GUI_MODULE_ap-write-api-integration-guide.en.md](./PCE_GUI_MODULE_ap-write-api-integration-guide.en.md) | [PCE_GUI_MODULE_ap-write-api-integration-guide.en.docx](./word/PCE_GUI_MODULE_ap-write-api-integration-guide.en.docx) | External vendors | English |
| [PCE_GUI_MODULE_ap-write-api-technical.md](./PCE_GUI_MODULE_ap-write-api-technical.md) | [PCE_GUI_MODULE_ap-write-api-technical.docx](./word/PCE_GUI_MODULE_ap-write-api-technical.docx) | Internal / consultants | 繁中 |
| [PCE_GUI_MODULE_ap-write-api-technical.en.md](./PCE_GUI_MODULE_ap-write-api-technical.en.md) | [PCE_GUI_MODULE_ap-write-api-technical.en.docx](./word/PCE_GUI_MODULE_ap-write-api-technical.en.docx) | Internal / consultants | English |
| [postman/PCE-AP-Write.postman_collection.json](./postman/PCE-AP-Write.postman_collection.json) | — | All | — |
| [postman/PCE-AP-Write.postman_environment.json](./postman/PCE-AP-Write.postman_environment.json) | — | All (template) | — |
| [postman/generate-client-assertion.js](./postman/generate-client-assertion.js) | — | OAuth 2.0 M2M JWT helper | — |

## Account smoke results (`transactionOnly`)

Recorded on **TD2905095** — see technical docs §5.5 (ZH / EN).

| Round | Method | Result | Raw JSON |
|-------|--------|--------|----------|
| A (2026-08-04) | SDF Installation smoke | 4/4 Pass (VB 25647, ER 25648, VC 25649, VP 25551) | [`../test/results/ap-write-smoke-result.json`](../test/results/ap-write-smoke-result.json) |
| B (2026-08-04) | Browser MCP + Suitelet | 4/4 Pass (VB 25747, ER 25847, VC 25848, VP 25947) | [`../test/results/ap-write-browser-smoke-result.json`](../test/results/ap-write-browser-smoke-result.json) |

## Authentication

This API uses **OAuth 2.0 Bearer tokens** (not OAuth 1.0a / TBA).

- **Vendors / M2M**: Client Credentials grant with JWT `client_assertion`
- **Interactive testing**: Authorization Code Grant, then paste access token into `accessToken`

## Postman import

1. Postman → **Import** → collection JSON (and optionally environment JSON).
2. Set `accountId`, `restletUrl`, `clientId`.
3. Generate JWT with `generate-client-assertion.js` → set `clientAssertion`.
4. Run **0. Auth → POST Get Access Token (Client Credentials)** (saves `accessToken`).
5. Run **POST validateOnly** (GET is not allowed), then real writes.
6. All RESTlet requests send `Authorization: Bearer {{accessToken}}`.