Phase 3 — 加值中心上傳（TXT＋sFTP）與進階控管

1. 目標

1. 上傳（文件 1）：依 MIG 4.1 中介文字檔說明 將銷項主檔＋明細組成 TXT，經 sFTP 上傳至汎宇。
2. 結果（文件 2）：依 汎宇 ACK 回覆檔案說明 自 sFTP 下載 ACK XML，解析後更新 上傳狀態／錯誤訊息，完成作廢閘道所需之 上傳成功。
3. 進階控管（後續）：發票本鎖定／盤點、權限、欄位精簡（§10）。
4. 零稅率開立：課稅別為零稅率時，通關方式註記與零稅率原因必填，寫入主檔並帶入上傳 TXT（已實作）。零稅率銷售額合計已有。零稅率清單 PDF 仍屬加購 Phase 5。

不在 Phase 3：加購 Phase 4–7（含零稅率清單 PDF）、營業稅 TXT/T02（vat-filing-status）、進項上傳。

2. 現況基線（Phase 1／7）

欄位對照：PCE 銷項欄位對照 — MIG 4.1 中介文字檔（匯出層 @|@|、INVTEXT_… 不進 CR）。

3. 整合方式（已定案）

4. 架構概覽

flowchart TB
  subgraph upIssue [開立上傳 MR]
    Q1[queue action=issue]
    T1[PCE_LIB_AR_VacTxtPayload]
    SF1[sFTP 上傳目錄]
    Q1 --> T1 --> SF1
  end
  subgraph upVoid [作廢上傳 MR]
    Q2[queue action=void]
    T2[PCE_LIB_AR_VacTxtPayload]
    SF2[sFTP 上傳目錄]
    Q2 --> T2 --> SF2
  end
  subgraph ack [ACK 抓取 MR]
    SF3[sFTP ACK 目錄]
    P[PCE_LIB_AR_VacAckParser]
    SF3 --> P
  end
  MS[modsys sFTP 設定] --> SF1
  MS --> SF2
  MS --> SF3
  SF1 --> WAIT[主檔 上傳中 + log 出站檔名]
  SF2 --> WAIT
  P --> ST[上傳成功 / 上傳失敗 + error_msg]

流程圖原文

觸發

• 開立／背景開立／作廢成功 → 寫入 upload_queue（不阻塞原 transaction）。
• 排程：Issue MR、Void MR、Ack MR 各自獨立部署。
• Suitelet 監控：查詢 queue／log、手動重試 enqueue（Phase 3A 末或 3B）。

5. 建議 SDF／程式元件

5.1 模組通用系統設定（sFTP）

modsys 不含密碼：PCE_LIB_ModuleSettings.getVacSftpSettingsByAccountId() 只回 host／user／hostKey／path 等；passwordGuid 不進 CR。

5.1.1 sFTP 密碼：passwordGuid（每支 MR 各一組）

NetSuite N/sftp 的 passwordGuid 須來自 Credential Field（或同等機制），且該欄位的 restrictToScriptIds 必須包含「正在呼叫 sftp.createConnection 的那支 script id」（並 restrictToDomains 含汎宇 host）。因此：

modsys 欄位（建議，TEST／PRODUCTION 各填一組）

後備：各 MR Script Parameter（modsys 空白時沿用）

設定方式（帳上）：依 SFTP Authentication 建立 Credential 取得 passwordGuid（三支 MR 各一 GUID，restrictToScriptIds 對應上表）；優先貼到 modsys 通用設定（依 Account mapping 的 TEST／PRODUCTION 列）。domain 限 sftp-t.einvoice.com.tw／sftp.einvoice.com.tw。HostKey 仍填 modsys custrecord_pce_modsys_vac_sftp_hostkey。

帳內輔助工具（選用）：Suitelet customscript_pce_sl_sftp_conn — 建立 GUID、查 Host Key、試連下載；步驟見 sFTP 建置說明。

5.1.2 遠端目錄（測試區實測 2026-10-05）

正式區 sftp.einvoice.com.tw 的 path_up／path_ack 已於 2026-10-07 通過。TEST／PRODUCTION 可沿用與測試區相同的相對路徑（/、ACK/）。

5.1.3 環境／帳上設定

5.2 佇列與紀錄

ACK 處理後另可寫 ack_log 列（或併入 upload_log，direction=inbound）。

去重（已實作）：同一 ar_invoice＋action 若已有 queue 狀態 pending／processing／outbound，enqueue 回傳既有列 id，不重複建列。Ack 成功／失敗時將對應 processing／outbound 列更新為 done／failed，並寫入 inbound log（含 queue 參照）。

Ack idempotency（已實作）：upload_log.custrecord_pce_ar_upllog_ack_file 存遠端 ACK 檔名；Ack MR 已處理者略過。處理後 path_done 有值則上傳至 done 目錄再刪 ACK 目錄檔；否則僅刪除遠端 ACK 檔。

5.3 三支 Map/Reduce

各 MR 部署須含 專用 passwordGuid Script Parameter（§5.1.1）、Audience（allemployees／allroles 等，見 repo 部署規則）。

共用 LIB：

6. 子階段與驗收

Checklist

總覽

一句結論：3A～3B 程式面可視為交付。帳上 sFTP 連線、三支 GUID、正式區路徑、MR 排程、開立上傳→ACK 已通過。Phase 3 結案仍取決於 作廢上傳→ACK、Ack list 篩選（§8.3）、3C、3D。零稅率開立已完成。

已完成（程式／文件）

基線（Phase 1／7，Phase 3 前置）

3A — 出站

3A+ — ACK

3B — 作廢與營運 UI

帳上已驗

未完成

帳上必做（3A～3B 驗收門檻）

規格 vs 實作落差

3C／3D

建議優先順序

1. 作廢上傳 → ACK：作廢後 Void MR → ACK；失敗走錯誤清單重送。
2. 留證：冒煙 ?action=json 存結果檔（含 uploadLogUrl／queueUrl／arInvoiceUrl）。
3. Ack list 變大時：實作 §8.3 統編／日期篩選。
4. 作廢 void 後狀態：實際 void 一筆確認交易欄位回寫。
5. 3D：角色矩陣 + 固定 smoke 步驟。
6. 3C：與申報前控管一併排程（非上傳管線阻塞）。

7. MIG 4.1 中介 TXT（文件 1 — 上傳）

權威來源：電子發票B2BB2C中介文字檔MIG4.1說明.pdf（repo 內與汎宇提供之 sFTP 參考文件 1 同系）。

7.1 檔案與編碼

本 repo 範例：docs/samples/vac-sftp/。

7.2 與 PCE 資料

• 來源：customrecord_pce_ar_invoice ＋ customrecord_pce_ar_invoice_line。
• 對照：PCE 銷項欄位對照 — MIG 4.1 中介文字檔；custrecord_pce_ar_mig_msg（如開立 F0401、折讓 G0401 等）與 doc_kind／作廢欄位。
• Issue MR：doc_kind=invoice、已開立、35-07＋vacUpload 等（背景開立已固定）。
• Void MR：已作廢、MIG 作廢／註銷訊息列（void_date／void_time／void_reason）。作廢訊息在檔案內容；檔名與開立相同，用統編與組檔時間。

7.3 出站後狀態

• sFTP 上傳成功：主檔 → 上傳中；queue 記 outbound_txt_name；不直接標上傳成功（成功以 ACK 為準）。
• sFTP 失敗：→ 上傳失敗、upload_error_msg 寫傳輸錯誤。

7.4 出站分檔（賣方統編）

同一個 INVTEXT 檔案內只能含同一賣方統編（MIG／汎宇限制）。實作時：

• 組檔前依 賣方統編（PCE 營業人／主檔 custrecord_pce_ar_seller_tax_id 或對應 MIG 賣方欄）分組，只為了確認檔內統編，以及同一統編共用一次 sFTP 連線。
• 每一筆銷項主檔一個 .txt。不可把多張發票或折讓合成一個檔，也不可把 A 公司與 B 公司列混在同一檔。
• Issue／Void MR 對每一筆呼叫 buildIssueOutboundText／buildVoidOutboundText 後各自上傳。queue 的 outbound_txt_name 記該筆檔名。
• 檔名仍是 INVTEXT_{統編}_{YYMMDDHHMMSS}.txt（台灣時間）。同一秒有多筆時，時間逐筆加 1 秒。

8. 汎宇 ACK XML（文件 2 — 結果）

權威來源：汎宇ACK回覆檔案說明.pdf（已納入 docs/reference/）。

8.1 檔名與位置

範例：docs/samples/vac-sftp/ack/。

8.2 XML 結構（摘要）

根元素 UecML 可含多筆 ElcInvData。Ack MR 會逐筆回寫，不會只留第一筆。每一筆欄位：

8.3 Ack MR 邏輯

1. 讀取本帳啟用中營業人統編（customrecord_pce_business_info）。一筆都沒有時不連線。
2. sFTP 下載 ACK/list/list.txt（directory=ACK/list/）。檔名第二段統編須屬於這些營業人，才列入待處理；其他統編、或檔名沒有 8 碼統編的列不下載、不搬移、不刪除。符合的列再取前 N 筆，並略過 idempotency 已處理檔。
3. 下載 ACK/{檔名}（含 **ACK01_*.xml** 等）；處理完可刪除或搬移遠端檔。
4. PCE_LIB_AR_VacAckParser 解析。同一個 XML 裡的每個 ElcInvData 各成一筆。
5. 每一筆以 MessageNo（＋必要時 MessageType／日期）對應 upload_queue／銷項主檔（狀態 上傳中）。
6. 依 StatusCode（§8.4 產品定案）更新該筆主檔；錯誤文字一律用 StatusDesc。
7. 每一筆寫 upload_log（遠端檔名相同，之後輪詢會略過整份），並把整份 ACK 存進檔案櫃 PCE 加值中心交換檔，掛在留存檔案。同一檔每一筆都套用後才搬移遠端檔。上傳 TXT 也在上傳成功後以同樣方式留存。

PCE_LIB_AR_VacAckParser 對主檔狀態（摘要）

StatusCode === 'C'           → 上傳成功（大平台已上傳成功），清空 upload_error_msg
StatusCode in E9001,E9002,E9003 → 上傳失敗，upload_error_msg = StatusDesc
StatusCode === 'S0002'       → 不更新主檔上傳狀態（忽略）
其他 StatusCode              → 上傳失敗（大平台回傳錯誤），upload_error_msg = StatusDesc

未收到 ACK：維持 上傳中；監控 Suitelet 可顯示逾時；可設定重送策略（產品另定）。

8.4 StatusCode 對照表（產品定案 2026-10-04）

補充：ACK PDF 仍可對照完整碼表；實作與驗收以本表為準。

作廢閘道：僅在 ACK 判為 C → 上傳成功 後，才與現行 uploadStatusAllowsVoid 一致（與 不上傳 並列可作廢）。

9. 狀態機（端到端）

主檔 上傳狀態 代表「目前這張單最新一則訊息」的進度：銷項狀態 已開立 → 開立訊息；已作廢 → 作廢訊息。主檔清單不新增值。

9.1 主檔與交易對照

主檔變更時，所有來源交易（合併開立時為多張 Invoice）同步回寫 custbody_pce_ar_inv_status。

作廢換開 當下清空來源單據的號碼、狀態、錯誤訊息與鎖定，不套用上表的作廢列，也不 void 交易。舊發票的作廢上傳進度只看主檔。作廢與作廢換開在主檔改為待上傳時都會排入作廢上傳佇列。作廢換開的上傳中、ACK 與重送都只更新主檔。

待帳上驗證：「作廢」模式以 transaction.void 作廢 NetSuite 交易後，Phase 3 是否仍能對已作廢交易 submitFields 回寫狀態。

9.1.1 交易錯誤訊息（custbody_pce_ar_error_msg）

交易表身單一欄位 發票錯誤訊息（Long Text、唯讀、銷項 PCE 分頁），合併兩種失敗來源，使用者在 Invoice／Credit Memo／Customer Deposit 上即可看到原因，不必再開主檔。

合併開立時，主檔的上傳錯誤同步寫入所有來源交易。

9.2 作廢閘道

維持現行 uploadStatusAllowsVoid：僅 上傳成功 或 不上傳 可作廢。開立上傳失敗的發票不可作廢，只能修正後重送（產品定案 2026-10-04）。

9.3 上傳錯誤清單與重送（Suitelet）

開立上傳與作廢上傳失敗的唯一出路是重送，不另開作廢路徑。

修正資料（例如客戶統編、品名）在主檔或來源交易上進行；清單頁只負責顯示錯誤與重送，不提供欄位編輯。

實作（2026-10-05）：PCE_LIB_AR_UploadErrorsSearch＋PCE_LIB_AR_UploadErrorsRequest＋PCE_LIB_AR_UploadErrorsHtml（Bootstrap、PceFilterCollapse、Portal embed）；期別篩選依憑證日期換算財政部雙月區間；最後上傳時間取該主檔最新一筆 upload_log；進頁預設列出失敗主檔（可再按查詢套用篩選）；npm run test:ar-upload-errors-search。

10. 發票本進階控管（Phase 3C — 概要）

藍圖原項：多本、鎖定、盤點。實作時擴充 PCE_LIB_AR_BookAllocate 拒絕鎖定本取號；Suitelet 匯出未使用區間。細節另開 PR。

11. 測試與範例

npm run test:ar-vac-txt        # 草案：Payload 對照 sample
npm run test:ar-vac-ack-parser # 草案：解析 sample XML
npm run validate:sdf-ids

帳上測試：須連 upload_log／queue id（比照 AP write log 規則）。直接開 加值中心上傳冒煙 Suitelet（不在 Portal 側欄；加值中心上傳 — 帳上冒煙（E2E））。

12. 相關文件

13. 變更紀錄