客戶環境 SuiteApp 部署（Installation Preferences）

對象：顧問／開發人員將 com.netsuite.pceguitw 部署到客戶正式或 UAT 帳
本機 dev：TD2905095 等開發帳請用一般 npm run deploy:sdf／npm run cpd，不要用 customer 模式。

兩種部署模式

模式	指令	Installation Preferences	典型帳號
開發	`npm run deploy:sdf`、`npm run cpd`	`locking.xml`／`hiding.xml` 預設 UNLOCK／UNHIDE	TD2905095（Chesley dev）
客戶	`npm run deploy:sdf:customer`	暫套用 `InstallationPreferences/customer/` 的 LOCK＋HIDE（結束後還原 dev 設定）	allowlist 內的客戶 Account ID

deploy:sdf:customer 不會自動切換 NetSuite 帳號；目標帳由 project.json 的 defaultAuthId 決定（suitecloud account:setup／account:manageauth）。

公版與 DFO

同一個 SuiteApp ID，用 Git 分支 決定客戶拿到哪一套，不是用 deploy 指令勾選。

客戶	部署的分支	內容
一般客戶	`master`	公版。不含 API進項審核、API進項資料、請購單 action
DFO	`Client/DFO-SB`	公版，再加上 API進項審核與請購單。設定與操作見該分支的 `docs/dfo/`

不要把 Client/DFO-SB 合併回 master。之後只把 master 合併進 Client/DFO-SB。

帳上若已裝過舊版，既有的 API進項資料與模組通用那兩個核取方塊不會因這次部署自動刪除。公版新部署不會再帶入這兩項。DFO 帳在下次部署後，審核開關改到中心標籤 API進項設定，須重新勾選。

技術人員作業流程（客戶帳）

給第一次把 SuiteApp 部署到客戶 UAT／正式帳 的 PwC 技術人員。業務資料（營業人、課稅別、發票本）的欄位說明在操作手冊 §4；本節只排順序、指令與驗收。

flowchart TD
  prep[1 本機：clone、npm install、JDK 17 或 21、SuiteCloud CLI]
  feat[2 客戶帳開啟 Custom Records、Server SuiteScript、Subsidiaries]
  auth[3 suitecloud account:setup 指向客戶帳]
  guard[4 allowlist 填入該 Account ID]
  deploy[5 npm run deploy:sdf:customer]
  setup[5 操作手冊 §4：Account ID、營業人、課稅別、統編、發票本]
  vac{需要加值中心上傳?}
  sftp[另讀 ar-phase3 與 sFTP helper]
  check[6 驗收：選單、種子、檢視頁開立按鈕]
  done[可交會計日常作業]
  prep --> feat --> auth --> guard --> deploy --> setup --> vac
  vac -->|是| sftp --> check
  vac -->|否| check
  check --> done

流程圖原文

1. 本機準備

在要執行部署的電腦上：

取得本儲存庫（com.netsuite.pceguitw）並切到要上線的 commit。
安裝 Node.js，於專案根目錄執行 npm install。
安裝 SuiteCloud CLI（suitecloud），並以具 SDF 部署權限的角色登入（通常為 Administrator，或已開 SuiteCloud Development Framework 的角色）。
JDK 17 或 21。macOS 若 SDKMAN 預設是 Java 11，npm run deploy:sdf:customer 仍會經 scripts/suitecloud-with-jdk.sh 改用已安裝的 JDK 21。除錯：PCE_SUITECloud_JAVA_DEBUG=1 npm run deploy:sdf:customer。

2. 客戶帳功能（部署前）

在目標帳 Enable Features 確認（與 manifest.xml、操作手冊 §2.1 一致）：

功能	必要性
Custom Records	必填
Server SuiteScript	必填
Subsidiaries	必填
Accounting	建議（交易單流程）

部署用角色需能建立自訂紀錄、部署 SDF，並在部署後看得到 Classic Center 的 PCE GUI 分頁。

3. 指向客戶帳並設定允許清單

# 目前 CLI 預設帳（必須是客戶帳，不能是 TD2905095）
npm run deploy:account

# 若不是，改 project.json 的 defaultAuthId
suitecloud account:setup
# 或 suitecloud account:manageauth

# 允許清單（擇一；檔案不進 Git）
cp scripts/deploy/customer-deploy-account-guard.local.json.example \
   scripts/deploy/customer-deploy-account-guard.local.json
# 編輯 allowedAccountIds，填該帳 Account ID

# 或：
# export PCE_CUSTOMER_DEPLOY_ALLOWED_ACCOUNT_IDS=11776409

Blocklist（scripts/deploy/customer-deploy-account-guard.json）已禁止 TD2905095。Allowlist 空白時部署會失敗，避免指到未知帳號卻套上客戶 LOCK／HIDE。

4. 部署

npm run deploy:sdf:customer

腳本會：帳號檢查 → 若帳號在排除清單則先移開指定 XML → 產生 InstallationPreferences/customer/ → 暫時覆寫本機 locking.xml／hiding.xml → suitecloud project:deploy -a（Apply Installation Preferences）→ 還原開發用的 UNLOCK／UNHIDE，並把移開的 XML 放回。

ViewSonic sandbox 11133471-sb1（11133471_SB1） 帳上已有同名、但不屬於本 SuiteApp 的物件，SDF 無法覆寫。對這個帳號，npm run deploy:sdf 與 npm run deploy:sdf:customer 會依 scripts/deploy/deploy-account-object-skip.json 暫時移開這兩個 XML，部署結束（含失敗、中斷）再放回專案，其他帳號仍會部署：

src/Objects/Custom_Records/customrecord_pce_tx_create_log.xml
src/Objects/Scripts/customscript_pce_rl_tx_create.xml

客戶部署會在產生 locking／hiding 之前移開，避免鎖定清單指向這次沒帶的物件。檔案櫃裡的 PCE_RL_TX_Create.js 仍會上傳；帳上既有的 Script 紀錄與 External URL 不會被這次部署改掉。SuiteCloud IDE 直接按 Deploy 不會套用這份排除，這個帳號請改跑 npm。

部署末段 deploy.xml 的安裝腳本會種子代碼對照表，以及模組通用設定的 正式區／測試區 兩筆（功能預設關閉，Account ID 先空白）。同名略過，可重跑。使用者儲存時 NetSuite Account ID 為必填。

部署成功、失敗或按 Ctrl+C 結束時，腳本都會把本機 locking.xml、hiding.xml 還原成已提交的開發版（UNLOCK／UNHIDE）。還原不使用備份檔，避免上次中斷留下的客戶版被再寫回去。只有程序被強制結束、檔案仍是客戶版時，才從 src/InstallationPreferences/.dev-install-prefs-backup/ 拷回。

部署完成後若還要在開發帳工作，把 defaultAuthId 指回開發 authId，之後只用 npm run deploy:sdf 或 npm run cpd。

5. 部署後設定（帳上）

會計照從無到有操作手冊第 1～7 步。欄位對照仍見操作手冊 §4。未做完前，選單可能看得到，但開立與上傳不會生效。

順序	做什麼	完成標準
A	重新整理後確認 PCE GUI	功能入口、模組設定、進項、銷項都在；操作手冊在 PCE GUI Portal → 說明
A0	模組通用系統設定填本帳 NetSuite Account ID（必填），並開啟需要的銷項	未對到 Account ID 時，模組功能視為關閉
B	PCE 營業人資料（統編、名稱、子公司）並啟用銷項	開立前銷項必須啟用
B2	PCE GUI Portal → 模組設定 → 課稅別稅碼對應（應稅／零稅率／免稅）	未對應無法開立
C	Vendor／Customer 的 PCE 發票統編、抬頭、地址	進項／銷項帶入與檢核用
發票本	PCE GUI Portal → 模組設定 → 發票本管理（CSV 或手動）	無可用字軌無法取號
D	僅外部寫入進項時：OAuth 與 AP Write	見介接手冊
加值中心	僅要上傳時：sFTP Host Key、三支 MR 的 password GUID	Phase 3 — 加值中心上傳（TXT＋sFTP）與進階控管、PCE SFTP Helper Suitelet（加值中心建置用）

6. 驗收

PCE GUI 分頁可開；PCE GUI Portal → 說明 → 操作手冊 可下載 CSV 範本。
模組通用設定有正式區／測試區，且目前帳號那一筆 Account ID 正確、銷項已依範圍開啟。
開一張已選客戶、子公司已啟用銷項的 Invoice 檢視頁：應出現開立相關按鈕（Client Script 未隱藏）。
File Cabinet 裡 server 進入點與 server-only PCE_LIB_* 看不到是預期結果；與 Client Script 共用的 library（例如 PCE_LIB_ModuleSettings）仍可見。
自訂紀錄 類型與欄位定義 已鎖定；仍可新增營業人、發票本等 資料列。公版不含 API進項資料。

客戶模式做了什麼

物件鎖定（locking）

npm run build:install-prefs:customer 會掃描 src/Objects/ 產生 InstallationPreferences/customer/locking.xml（defaultAction="UNLOCK"，清單內 LOCK）：

類別	內容
Script	非 Client Script 的 `customscript_*`（39）
Custom Record	各 `customrecordtype` 的 `scriptid`（內嵌 `custrecord_*` 欄位隨類型一併鎖，不可單獨列 LOCK）
欄位	獨立 XML 的 `custbody_`、`custcol_`、`custentity_*`
Custom List	`customlist_*`（下拉選項定義）

7 支 Client Script（customscript_pce_cs_*）→ 不鎖。
不鎖 File Cabinet 的 PCE_LIB_* 原始檔；不鎖 Center Tab／Entry Form 等（若日後要鎖可擴充產生器）。
Script deployment 依平台規則不可 lock；CR instance 資料仍可新增（鎖的是類型／欄位定義，非每一筆業務資料）。

Script 與 server-only 程式碼隱藏（hiding）

自 39 支 server script 的 <scriptfile> 進入點走訪 define() 相依圖，對圖內、且不在 Client Script 相依圖的 .js 設 HIDE（進入點 + server-only 的 PCE_LIB_*／helper；客戶 File Cabinet 不可檢視／下載）。
與 CS 共用的 library（如 PCE_LIB_ModuleSettings、PCE_LIB_AR_Feature）不 HIDE，否則 CS 執行期無法載入。
Client Script 進入點：Oracle 不允許 HIDE；CS 相依圖（約 25 路徑）整體排除在 HIDE 清單外。
若 server 進入點檔與 CS 相依圖為同一檔，產生器會 失敗退出（不可藏 CS 進入點）。

帳號防呆（blocklist／allowlist）

部署前執行 scripts/deploy/assert-customer-deploy-account.js：

清單	檔案	用途
Blocklist（禁止）	`scripts/deploy/customer-deploy-account-guard.json`（進 Git）	一律不可 customer deploy；內建 TD2905095（本機 dev）
Allowlist（允許）	`scripts/deploy/customer-deploy-account-guard.local.json`（不進 Git）或環境變數 `PCE_CUSTOMER_DEPLOY_ALLOWED_ACCOUNT_IDS`	只有列出的 Account ID 才允許繼續

Allowlist 未設定時也會失敗，避免指向未知帳號卻套用 customer lock/hide。逐步指令見上方 §3–§4。新增或更名 script／define() 相依後，部署腳本會自行重跑 build:install-prefs:customer；若只想更新 XML、先不要部署，可單獨執行該指令。

與 CP／CPD 的關係

使用者說	行為
CP	只 git push；不 deploy
CPD	push + `npm run deploy:sdf`（開發帳、不套用 customer lock/hide）
客戶上線	通常 CP 程式碼後，在顧問本機對客戶 authId 跑 `npm run deploy:sdf:customer`（非 `cpd` 預設路徑）

若要在 CI 對客戶 deploy，需另設 pipeline 步驟並注入 PCE_CUSTOMER_DEPLOY_ALLOWED_ACCOUNT_IDS；cpd 腳本本身未改為 customer 模式。

路徑	說明
`src/InstallationPreferences/locking.xml`、`hiding.xml`	開發帳預設（UNLOCK／UNHIDE）
`src/InstallationPreferences/customer/`	客戶用 lock/hide（含 README 摘要）
`scripts/deploy/build-customer-install-prefs.js`	產生 customer XML + CS 相依檢查
`scripts/deploy/pce-deploy-sdf-customer.sh`	customer deploy 包裝
`scripts/deploy/assert-customer-deploy-account.js`	blocklist／allowlist
`.cursor/rules/sdf-deployment-audience.mdc`	deployment Audience、overwriting
`.cursor/rules/cp-deploy.mdc`	CP／CPD 定義

限制與後續

CS 共用的 PCE_LIB_* 在客戶 File Cabinet 仍可見（刻意保留）；其餘 server 相依檔由產生器自動 HIDE。新增 server define() 相依後請重跑 build:install-prefs:customer。
overwriting.xml 預設多數 deployment PRESERVE；runasrole／log level 等若要覆寫帳上設定，需對該 deployment 設 action="OVERWRITE" 並 deploy 時勾 Apply Installation Preferences。