# PCE TW GUI — SuiteTax 支援規劃

> **狀態**：規劃（未實作）  
> **最後更新**：2026-09-17  
> **對象**：產品／顧問／開發  
> **目的**：讓模組在 **SuiteTax** 帳號上仍能正確把 NetSuite 明細稅資訊對到 PCE **課稅別 1／2／3**，行為與現行 **Legacy Tax（Sales Tax Item）** 帳號一致。

**導入假設（產品）**：客戶在 **上線 PCE 前** 即已在 NetSuite 決定 **Legacy 或 SuiteTax**；本規劃 **不** 涵蓋「營運中把同一帳號從 Legacy 改 SuiteTax」後的對應轉換、匯出／匯入或重新對應 SOP。

---

## 1. 為什麼需要

| 面向 | 說明 |
|------|------|
| **業務** | 台灣電子發票 MIG 要求 PCE 主檔／明細的 **課稅別、稅率、稅額** 與來源交易一致；銷項開立前必須完成 **課稅別 ↔ NS 稅碼** 對應。 |
| **平台** | **SuiteTax** 與 Legacy 的稅碼主檔、搜尋方式、部分交易欄位行為不同；現行程式假設 **Legacy**。 |
| **風險** | 在 SuiteTax 帳號上：對應 UI 可能 **稅碼清單為空**、開立時 **taxcode 反查失敗**、或對到錯誤 internal id，導致無法開立或課稅別錯誤。 |

---

## 2. 現況（Legacy 假設）

### 2.1 資料模型（不變）

- `customrecord_pce_tax_type`：`custrecord_pce_taxtype_code_value`（1／2／3）＋ `custrecord_pce_taxtype_ns_taxcode`（MULTISELECT，存 **NS 稅碼 internal id**）。
- 語意：**同一 PCE 課稅別可對多個 NS 稅碼**（例如不同稅率皆屬應稅）。

### 2.2 程式 touch points

| 區塊 | 檔案 | 現行做法 |
|------|------|----------|
| 對應 UI | `common/PCE_SL_TaxTypeMapping.js` | `search.Type.SALES_TAX_ITEM` 載入下拉選項 |
| 反查 map | `ar/libraries/PCE_LIB_AR_Lookup.js` | 讀 tax type CR 的 multiselect → `nsTaxCodeId → PCE code` |
| 銷項開立 | `ar/libraries/PCE_LIB_AR_Issue.js` | Invoice／CM **`item` 子列表 `taxcode`**（value／text）；驗證未對應稅碼 |
| 開立搜尋 | `ar/libraries/PCE_LIB_AR_IssueSearch.js` | 搜尋欄位含 `taxcode` |
| 交易 CS | `ar/clientscripts/PCE_CS_Trans_AR_Body.js` | 讀 line `taxcode` |
| 進項 | AP 程式 | **未**直接綁 NS `taxcode`；課稅別多來自 CSV／欄位，SuiteTax 影響較小（仍可能間接影響交易稅額） |

### 2.3 帳上設定入口

- **模組設定 → 課稅別 NS 稅碼對應**（`customscript_pce_sl_taxtype_mapping`）。

---

## 3. SuiteTax vs Legacy（工作假設，需帳上驗證）

以下為實作前必須在 **已啟用 SuiteTax 的 sandbox／客戶帳** 核對的項目；細節以 Oracle Help／該帳 API 為準。

| 主題 | Legacy（現行支援） | SuiteTax（待支援） |
|------|-------------------|-------------------|
| 稅碼主檔 | `sales tax item` / `SALES_TAX_ITEM` search | 通常為 **SuiteTax Tax Code**（record type／search 路徑不同，**不可**再只搜 `SALES_TAX_ITEM`） |
| 明細稅欄位 | `item.taxcode`（internal id + text） | 多數仍暴露 line tax code，但 **id 命名空間不同**；部分情境可能需 **tax details** 或額外欄位（需實測 Invoice／CM） |
| 啟用判斷 | 預設 Legacy | 建議 `runtime.isFeatureInEffect`／帳號 preference（**確切 feature id 需查官方文件並在目標帳驗證**） |
| 子公司／nexus | 相對單純 | SuiteTax 常與 **nexus、tax registration** 連動；下拉稅碼可能需 **依 subsidiary 過濾** |

**原則**：PCE 仍只關心「**line 上選了哪個 NS 稅碼 id** → 對到 1／2／3**」；差異集中在 **如何列舉合法稅碼** 與 **如何從交易讀出同一個 id**。

---

## 4. 目標與非目標

### 4.1 目標（MVP）

1. **依帳號稅制**（Legacy 或 SuiteTax）走對應 UI／開立分支；實作上以偵測或 **上線時寫死的模組設定** 二擇一（見 §5.1），**不**處理稅制中途切換。
2. **課稅別 NS 稅碼對應** 在 SuiteTax 帳號可選到 **有效 SuiteTax 稅碼**，儲存格式仍用現有 multiselect（internal id）。
3. **銷項開立**（含自訂明細、來源 Invoice／CM）在 SuiteTax 帳號可完成 **taxcode 反查與未對應驗證**，產出正確 PCE 課稅別。
4. **Legacy 帳號行為不變**（回歸測試必過）。
5. 文件：使用說明、操作手冊 HTML 各加一段「SuiteTax 帳號注意事項」。

### 4.2 非目標（第一版不做）

- 替 NetSuite **計算** 稅額或改寫 SuiteTax engine 設定。
- 完整 **tax details** 子表逐行同步到 PCE 明細（除非實測證明僅讀 `taxcode` 不足）。
- 多國 VAT／US sales tax 通用化（仍以 **台灣 PCE 課稅別 1／2／3** 為範圍；他國稅碼若出現在清單，僅作映射，不保證報稅語意）。
- AP Write／進項 CSV 全面重寫（除非發現 SuiteTax 導致 **taxType 來源交易** 不一致，再開子項）。
- **Legacy → SuiteTax 帳號稅制轉換** 後的對應修補、資料匯出／匯入、專用 migration 文件（**不在範圍**）。

---

## 5. 建議架構

### 5.1 稅制引擎抽象層（新建 library）

建議：`common/PCE_LIB_NsTaxEngine.js`（名稱可調），對外固定 API：

| 方法 | 用途 |
|------|------|
| `getTaxEngineMode(context)` | 回傳 `LEGACY` \| `SUITETAX`（可帶 `subsidiaryId`） |
| `listTaxCodesForMapping(options)` | 對應 UI 下拉：`{ value: internalId, text: label }[]` |
| `getLineTaxCodeId(record, { sublistId, line })` | 統一從交易明細取稅碼 id |
| `getLineTaxCodeLabel(record, …)` | 顯示用；SuiteTax 若 text 格式不同在此對應調整 |
| `validateMappingIds(ids)` | 儲存前確認 id 在該引擎仍有效 |

**設定（可選）**：模組通用設定增加 **NS 稅制** 列舉 `AUTO | LEGACY | SUITETAX`（預設 `AUTO`），供 **導入／建帳** 時與 NetSuite 對齊；正常營運中不預期變更。

### 5.2 改接現有模組（薄改）

```
PCE_SL_TaxTypeMapping.js     → listTaxCodesForMapping()
PCE_LIB_AR_Lookup.js         → （map 仍讀 CR；可加引擎無關快取）
PCE_LIB_AR_Issue.js          → getLineTaxCodeId / 驗證未對應
PCE_LIB_AR_IssueSearch.js    → 確認 search column 在 SuiteTax 仍可用
PCE_CS_Trans_AR_Body.js      → 同上
```

### 5.3 資料相容

- **不新增** 第二套 multiselect 欄位；同一帳號內只會存在 **一種** 稅制下的稅碼 id。
- 對應 UI 可選：儲存的 id 若在現行稅制搜尋不到則標示無效（設定錯誤或環境不一致時除錯用），**非**為稅制轉換流程設計。

---

## 6. 分期建議

| 階段 | 內容 | 交付／驗收 |
|------|------|------------|
| **S0 探索** | 在 SuiteTax 帳：列舉稅碼 API、Invoice／CM 明細欄位、feature 判斷；產出 **帳上筆記**（record type、範例 id、screenshot） | 1 頁技術備忘 + 測試交易 id |
| **S1 對應 UI** | `PCE_LIB_NsTaxEngine` + TaxTypeMapping 改接；AUTO 判斷 | SuiteTax 帳可存 1／2／3 對應；Legacy 回歸 |
| **S2 銷項開立** | Issue／Lookup／Search／CS 改接；錯誤訊息區分「未對應」vs「引擎不支援」 | SuiteTax 帳 smoke：查詢 → 開立 → PCE 主檔課稅別正確 |
| **S3 硬化** | subsidiary／nexus 過濾、安裝後檢查、模組設定頁提示 | 多子公司帳測試；`npm test` 新增 engine mock 單測 |
| **S4 文件** | user-guide、手冊 HTML、AR status 能力列 | 顧問可照文件設定 |

---

## 7. 測試策略

| 類型 | 做法 |
|------|------|
| 單元 | mock `NsTaxEngine`：Legacy／SuiteTax 各一組假稅碼 id + line 讀取 |
| 本機 | 延伸 `test/ar-*`：反查 map、未對應驗證 |
| 帳上 | **雙帳**：TD2905095（Legacy?）＋ SuiteTax sandbox；開立 smoke 寫入 `test/results/` |
| 回歸 | 現有 `npm run test:ar-*`、tax mapping 相關（若無則 S1 補 `test/ns-tax-engine.test.js`） |

---

## 8. 風險與決策點

1. **僅帳級 SuiteTax vs 子公司混用**：若存在「部分子公司 Legacy」，`getTaxEngineMode` 必須 **依 subsidiary** 而非全帳一種。
2. **taxcode search column**：SuiteTax 下 saved search 是否仍回傳相同 internal id；若否，Issue 查詢需改 join 或改載入方式。
3. **對應 multiselect 儲存值**：Legacy 與 SuiteTax 的 id **不可跨帳／跨稅制複製**（僅防顧問誤拷 sandbox 設定）。
4. **Performance**：SuiteTax 稅碼數量可能更大 → 對應 UI 考慮 subsidiary 篩選或分頁（第二版；對應表仍全帳共用，見 §9）。

---

## 9. 產品決策（已確認）

| 問題 | 決策 |
|------|------|
| **SuiteTax 時程** | **晚於「產營業稅檔」能力完成之後** 再排 SuiteTax 實作與首個目標帳驗收；Legacy 帳仍須長期並行支援（**不同客戶／不同帳** 各走各的稅制，非同一帳轉換）。 |
| **對應表範圍** | **全帳共用**（維持現行 `customrecord_pce_tax_type` 一組 1／2／3 對應，**不**依子公司拆表）。 |
| **導入方式** | **上線前** 與 NetSuite 稅制（Legacy／SuiteTax）一次定案；完成 **課稅別 NS 稅碼對應** 後始用銷項開立。**不規劃** 營運中稅制切換的配套。 |

---

## 10. 相關文件

| 文件 | 關係 |
|------|------|
| [PCE_GUI_MODULE_ar-status.md](./PCE_GUI_MODULE_ar-status.md) | 實作後更新能力列 |
| [PCE_GUI_MODULE_suiteapp-user-guide.md](./PCE_GUI_MODULE_suiteapp-user-guide.md) § 課稅別對應 | 操作步驟 |
| [PCE_GUI_MODULE_ar-blueprint.md](./PCE_GUI_MODULE_ar-blueprint.md) | 階段可併入 Phase 2／4 或獨立「平台」里程碑 |
| Oracle SuiteTax／SuiteScript Records 說明 | S0 必查（Agent Skill：`netsuite-suitescript-records-reference`） |

---

## 變更紀錄

| 日期 | 摘要 |
|------|------|
| 2026-09-17 | 初版規劃：現況盤點、抽象層、分期與風險 |
| 2026-09-17 | 產品決策：SuiteTax 排在產營業稅檔之後；對應表全帳共用；不做對應匯入匯出工具 |
| 2026-09-17 | 導入假設：上線前定案 Legacy／SuiteTax；不涵蓋帳號稅制中途轉換 |