PCE TW GUI documentation
可分享的 HTML 文件在 handbook/。把這個資料夾整包傳出去即可離線閱讀；截圖與文件之間的連結都在資料夾內。
開發者索引
| 資源 | 說明 |
|---|---|
AGENTS.md | Agent／Cursor 專案地圖、模組入口、本機指令、codebase-memory MCP 專案 ID |
.cursor/rules/cp-deploy.mdc | CP／CPD；npm run cpd（push + dev deploy）、.cursor/permissions.json |
| 客戶帳部署 · HTML | 客戶帳 deploy 作業流程（流程圖：本機準備 → allowlist → deploy:sdf:customer → 操作手冊 §4 → 驗收）。公版不含 API進項審核與請購單。LOCK 非 CS script 與頂層物件；HIDE server 進入點與 server-only LIB |
| Pceguitw Architecture（Cursor Canvas） | 知識圖摘要＋SDF 部署模式（本機圖索引 2026-10-30 · 69d1651：9,000 節點／15,221 關係／2,984 CALLS；頂層 LOCK、server-only HIDE、JDK 21 wrapper） |
| Pce Ar Flow（Cursor Canvas） | 銷項四管線。作廢：單月 15 日前含上一期、待上傳即排佇列、作廢換開 ACK 不回寫交易；加值中心一主檔一 TXT、ACK 多筆回寫並留檔 |
PCE_LIB_ListValue.js | 共用 resolveListValueId（UploadStatus、VacUploadQueue、Issue、Void、AutoIssue 等）；測試 npm run test:list-value |
| sFTP 建置說明 · HTML | Phase 3 建置：customscript_pce_sl_sftp_conn（GUID／Host Key／試連；連線與三支 GUID 已通過） |
.codebase-memory/ | 本機 graph（graph.db.zst，不納 Git）；拉程式後 index_repository mode full |
進項／銷項交付進度見下方 AP／AR status。架構 Canvas 的 codebase-memory 數字需本機重新索引才與 HEAD 一致；部署流程以 customer-deploy（HTML）與 Canvas「部署」段落為準。
SuiteApp 操作手冊
帳上：PCE GUI Portal → 說明 → 操作手冊（可下載進項／發票本 CSV 範本，內容是摘要）。從空白帳號照著做到開出第一張發票，用下面第一份。
| Document | Word | Audience | Language |
|---|---|---|---|
| 操作手冊 · HTML | — | 會計、第一次設定的顧問 | 繁中 |
| 使用說明 · HTML | PCE_GUI_MODULE_suiteapp-user-guide.docx | Admins, accountants, consultants | 繁中 |
| User guide · HTML | PCE_GUI_MODULE_suiteapp-user-guide.en.docx | Admins, accountants, consultants | English |
| 文件索引 · HTML | — | 會計（CSV 範本下載目錄） | 繁中 |
Screenshots used in the user guides live under images/user-guide/.
Purchases (AP)
實作進度（建議先看）：PCE TW GUI MODULE — 進項（AP）實作進度（一頁式） · HTML · SuiteApp 實作進度總覽 HTML
| 瀏覽方式 | 說明 |
|---|---|
| Cloudflare Pages | Private repo 可用；步驟見 Cloudflare Pages：PCE 實作進度（private GitHub repo）（HTML）。預設總覽：<https://pceguitw-status.pages.dev/html/index.html>（部署後生效；根 URL 經 index.html 導向）。 |
| 本機 | npm run serve:status → http://127.0.0.1:8765/html/index.html（伺服器根目錄＝docs/，進度頁連結到同層的 HTML 手冊）。 |
進項／銷項 CP／CPD 前更新對應 status Markdown，再跑 npm run build:status-html（或 push 後由 sync-status-html workflow 自動同步 HTML）。部署：npm run cpd（本地已 commit 後）。
日常操作見使用說明 §5.1–5.4；外部介接見 AP Write 文件。
| Document | Audience | Language |
|---|---|---|
| PCE TW GUI MODULE — 進項（AP）實作進度（一頁式） | 進度／做沒做／變更紀錄 | 繁中 |
| 使用說明 §5.1–5.4 | 進項登錄、CSV | 繁中 |
| 進項憑證檢核規則 | 畫面、CSV、API 同一套檢核 | 繁中／EN |
Sales (AR)
實作進度（建議先看）：PCE TW GUI MODULE — 銷項（AR）實作進度（一頁式） · HTML — 同上（Pages／本機／build:status-html／CI 同步）。
平台：PCE TW GUI — SuiteTax 支援規劃（HTML）— 模組通用 suiteTax 勾選後，銷項改讀 Tax Details、進項與交易建立改寫 Tax Details。課稅別對應維持既有稅碼清單，定案不改。SuiteTax 帳上已開立台幣銷項發票與折讓單。
日常銷項操作見使用說明 §5.5 開立取配號、§5.6 發票本、§5.7 作廢、§5.8 背景自動開立（繁中／英文）；主檔上傳狀態與交易狀態對照見手冊 §3.2.1。完整取號流程見 取號流程與邏輯（HTML）；背景開立規格見 銷項背景自動開立發票（Phase 7）（HTML）；Phase 3 加值中心（TXT＋sFTP）見 Phase 3 — 加值中心上傳（TXT＋sFTP）與進階控管（HTML）；換中心修改範圍見 換加值中心 — 修改範圍（HTML）；Portal iframe 查詢條件／workbench 版面現況見 PCE GUI Portal — 銷項內頁 UI（查詢條件／workbench）（HTML）；規格見藍圖 §9.5。
| Document | Audience | Language |
|---|---|---|
| PCE TW GUI MODULE — 銷項（AR）實作進度（一頁式） | 進度／做沒做／變更紀錄 | 繁中 |
| Portal 銷項版面 · HTML | Portal 銷項內頁 UI（查詢條件／workbench 交付範圍） | 繁中 |
| 銷項開立取號流程與邏輯 · HTML | 開立取號流程與邏輯（現行實作） | 繁中 |
| 銷項藍圖 · HTML | Product / consultants / developers | 繁中 |
| PCE 銷項欄位對照 — MIG 4.1 中介文字檔 · HTML | 銷項主檔／表身欄位（MIG 4.1） | 繁中 |
| 使用說明 §5.5–5.8 | 開立、發票本、作廢、背景開立（§3.2.1 上傳狀態） | 繁中／EN |
| 背景自動開立 · HTML | Phase 7 背景自動開立（佇列、MR、進度頁） | 繁中 |
| 加值中心上傳 · HTML | Phase 3 汎宇加值中心（MIG TXT、ACK、三支 MR；開立上傳→ACK 已通過；作廢上傳→ACK 待驗） | 繁中 |
| 換加值中心 — 修改範圍 · HTML | 換加值中心時要改的程式與設定（現行契約為汎宇） | 繁中 |
| reference/電子發票B2BB2C中介文字檔MIG4.1說明.pdf | MIG 來源 PDF | — |
| prototypes/einvoice-issue.html | UX prototype（開立銷項發票） | — |
營業稅申報（跨 AP＋AR）
實作進度：PCE TW GUI MODULE — 營業稅申報 實作進度（一頁式） · HTML — 頂部導覽「營業稅申報」分頁；進項＋銷項合併產 TXT／T02，含 空白字軌／空白發票（規格見 銷項藍圖 §5，HTML）。
AP Write API
| Document | Word | Audience | Language |
|---|---|---|---|
| 進項憑證檢核規則 · HTML | PCE_GUI_MODULE_ap-validation.pdf | 會計／顧問／廠商 | 繁中 |
| AP validation rules · HTML | — | Accountants / consultants / vendors | English |
| AP Write 介接手冊 · HTML | PCE_GUI_MODULE_ap-write-api-integration-guide.docx | External vendors | 繁中 |
| AP Write integration guide · HTML | PCE_GUI_MODULE_ap-write-api-integration-guide.en.docx | External vendors | English |
| 技術與測試文件 · HTML | PCE_GUI_MODULE_ap-write-api-technical.docx | Internal / consultants | 繁中 |
| Technical and testing guide · HTML | PCE_GUI_MODULE_ap-write-api-technical.en.docx | Internal / consultants | English |
| postman/PCE-AP-Write.postman_collection.json | — | All | — |
| postman/PCE-AP-Write.postman_environment.json | — | All (template) | — |
| postman/generate-client-assertion.js | — | OAuth 2.0 M2M JWT helper | — |
交易建立 API（不含進項憑證）
| Document | Audience | Language |
|---|---|---|
| PCE 交易建立 API · HTML | External vendors | 繁中 |
| PCE Transaction Create API · HTML | External vendors | English |
OAuth 2.0 取 token 的方式與 AP Write 介接手冊 §1 相同，External URL 是另一支腳本 customscript_pce_rl_tx_create。
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 |
| 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 |
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
- Postman → Import → collection JSON (and optionally environment JSON).
- Set
accountId,restletUrl,clientId. - Generate JWT with
generate-client-assertion.js→ setclientAssertion. - Run 0. Auth → POST Get Access Token (Client Credentials) (saves
accessToken). - Run POST validateOnly (GET is not allowed), then real writes.
- All RESTlet requests send
Authorization: Bearer {{accessToken}}.