GF Customs Filing — 總體產品開發計劃

文件導覽

1. 專案摘要與目標
2. 系統架構（GoFreight ↔ LDS ↔ ABI/ACE）
3. CBP 報文與 LDS API 對應
4. Entry Type 優先順序與依據
5. 各 Entry Type 所需頁面與功能矩陣
6. 共用平台元件
7. 每一型別的標準產品文件包
8. 階段性開發路線圖
8.1 Highest-priority 跨型功能（2026-06 LDS meeting）
9. 風險與相依

1. 專案摘要與目標

目前 GoFreight 客戶（美國貨代 / 報關行 / NVOCC）需要在第三方系統完成美國進口報關。本專案要在 GoFreight 內建一個 Customs Filing Portal，作為前端操作與資料模型層，後端透過 LDS SMS API（WCF/.NET 服務）轉換成 CBP CATAIR 報文並送往 ABI/ACE，再把 CBP 的回覆（放行、Hold、Reject、Census Warning、稅費結算等）回傳並呈現給客戶。

14需支援的 CBP Entry Type

P0–P4依 filing type 的階段路線圖（ACE-7419）

≈205.5all-in 人天（P0–P4,5 phase）

SE/AE/QP三大送件報文流

核心成果

客戶可於 GoFreight 內新建 → 填寫 → 驗證 → 計稅 → 送件 → 取得 CBP 回覆的端到端報關。
單一資料模型可支援多種 Entry Type，避免每型別重做。
所有 CBP 報文細節、bond / PGA / AD-CVD / 配額判斷由系統規則引擎處理，降低客戶 reject 率。

2. 系統架構

GoFreight Customs Portal

前端 UI / 資料模型 / 驗證 / 文件產生

→

GF Integration Adapter

REST facade → 呼叫 LDS WCF
狀態輪詢 / 對應 mapping

→

LDS SMS API

WCF/.NET ‧ ClientContext
CATAIR 編/解碼

→

CBP ABI / ACE

Cargo Release / Entry Summary / In-Bond

關鍵設計：LDS API 為 WCF/SOAP、強型別 C#（單一 SMS.Broker.Standard.dll，.NET 4.8），無 REST/JSON。建議 GoFreight 建一個 .NET Integration Adapter（薄轉接層），對內以 REST/JSON 與 GoFreight 平台溝通，對外用 ClientContext.InitializeContext(url, "user@database", password) 取得 ServicesFactory，再以 GetManager<ICustomsEntryManager>() 等取得各服務代理。

非同步與關聯模型

LDS 採「佇列 + 輪詢」，無 callback：送件用 PutToQUEOneWay(...) 入列，CBP 回覆稍後成為一筆 incoming ABITransmission。GoFreight 以 SourceLink="CustomsEntry={id}" 與 clientRef 作為關聯鍵，輪詢 IABITransmissionManager.GetBySourceLink() 及文件的 LastStatuses 取得最新狀態。

3. CBP 報文與 LDS API 對應

業務動作	CBP 報文（App ID）	LDS API 方法 / 物件	說明
貨物放行申請	SE（in）→ SO/SX（out）	`PutToQUEOneWay(id, AddCargoRelease)`	3461 Cargo Release；SO 回放行 / Hold / Exam
報關彙總（稅費）	AE（in）→ AX（out）	`PutToQUEOneWay(id, AddEntrySummary)`	7501 Entry Summary；AX 回 Accept / Reject / Census Warning
放行+彙總合併（Live/Certify）	AE（Cert Ind=A）	`AddEntrySummaryAndCargoRelease`	單次送件同時驅動放行
In-Bond 移動	QP（in）→ QT（out）	`InBond.PutToQueue(id, Add)`	CBPF-7512；Type 61/62/63
In-Bond 到港/出口	WP（in）→ WT / NS（out）	`InBondUpdate.PutToQueue(id)`	arrival / export / transfer
計稅與驗證	—（本地）	`CalculateDutyAndFee(id)` / `ValidateTreeById(id,"QUE AE")`	送件前必跑
狀態通知	UC（Entry Summary）/ SO（Release）/ NS（In-Bond）	輪詢 `GetBySourceLink` + `LastStatuses`	incoming 非同步
文件影像上傳	DIS	（DIS document package）	補充文件

4. Entry Type 優先順序與依據

優先順序依：① 你指定的 Type 01、61 先行；② 其餘按「客戶最有機會使用到的機率」排序——機率以美國一般進口貨代/報關行的日常交易量、是否為其他型別的前置流程、實作可重用度綜合判斷。

P1 首期必做、流程基底 P2 高頻多數客戶常用 P3 中頻特定情境 P4 低頻少數/專業客戶

順位	Entry Type	名稱	優先級	選入依據
1	01	Formal Consumption 正式消費進口	P1	指定優先；最常見正式進口；SE+AE 完整流程，是所有 consumption 型別的基底
2	03	AD/CVD Consumption 反傾銷/平衡稅	P1	= Type 01 + AD/CVD case；中國等貨源高頻；重用 01 + 53-record
3	11	Informal Entry 非正式進口	P1	2026-06 LDS meeting 由 P2 提前:LDS 指出 formal / informal 同構、forwarder 高量；與 01 共用 90% 欄位，簡化 summary
4	61	Immediate Transportation (IT) In-Bond	P2	2026-06 LDS meeting 由 P1 下移:in-bond 屬不同交易性質；港到港保稅移動；QP/WP 流程基底，後續 62/63 共用
5	86	Section 321 / De Minimis	P2	跨境電商小包裹爆量；只需 SE+（必要時）PGA，無 summary，量大
6	07	Quota + AD/CVD Consumption 配額+反傾銷	P3	2026-06 LDS meeting 由 P2 下移:量低、後期；行項 AD/CVD + Visa/Quota 組合
7	21	Warehouse Entry 入保稅倉	P3	保稅倉客戶；建立 inventory balance，為 31 前置
8	31	Warehouse Withdrawal 保稅倉提貨進口	P3	需 reference Type 21 + balance 檢查；與 21 成對
9	62	Transportation & Exportation (T&E)	P3	經美轉出口；重用 61 + export port/date
10	63	Immediate Exportation (IE)	P3	抵港即出口；重用 61
11	02	Quota / Visa Consumption 配額	P4	= 01 + 配額/簽證；特定商品
12	23	TIB 臨時進口	P4	需 9813 + 商品 HTS 成對、re-export 義務追蹤
13	12 / 32 / 34 / 38 / 52	複合型（Quota + AD/CVD 變體）	P4	02/03/31 的組合，最後處理
—	06	FTZ Consumption 自貿區出區	Deferred	2026-06 LDS meeting 列為 Deferred:複雜、deferred duty、初期排除；需 FTZ status/zone 欄位群與 e-214
—	47	Drawback 關稅退稅	Deferred	獨立 Drawback flow，非一般 SE/AE；LDS 無對應 API,待補件

5. 各 Entry Type 所需頁面與功能矩陣

系統採「共用骨架 + 型別差異模組」。下表標示每型別在標準頁面之外，額外需要的頁面/功能。✔=需要、＋=額外模組、—=不需。

頁面 / 功能	01	11	86	03	06	21	31	61/62/63	47
Entry List（清單/搜尋/狀態看板）	✔	✔	✔	✔	✔	✔	✔	✔	✔
Header（entry no/type/MOT/port）	✔	✔	✔	✔	✔	✔	✔	✔	✔
Parties（IOR/Consignee/MID）	✔	✔	✔	✔	✔	✔	✔	✔	✔
Bond Info	✔	條件	通常免	✔	✔	✔	✔	✔	✔
Shipment / Bill of Lading	✔	✔	✔	✔	✔	✔	✔	✔	—
Invoice / Line Items（HTS/COO/Value）	✔	✔	✔	✔	✔	✔	✔	簡化	＋退稅明細
Duty & Fee 計算（MPF/HMF）	✔	簡化	免稅	✔	✔	延後	✔	—	＋退稅試算
Payment / Statement	✔	✔	—	✔	✔	延後	✔	—	＋refund
PGA Data	條件	條件	條件	條件	條件	條件	條件	＋BTA/FDA	—
＋ AD/CVD Case 模組	—	—	—	＋	條件	條件	＋(34/38)	—	—
＋ Quota / Visa 模組	—	—	—	—	—	—	＋(32/38)	—	—
＋ FTZ Status / Zone 模組	—	—	—	—	＋	—	—	＋(FTZ conv)	—
＋ Warehouse Inventory / Balance	—	—	—	—	—	＋建立	＋扣帳	—	—
＋ In-Bond Movement Lifecycle	—	—	—	—	—	—	—	＋	—
＋ Export Proof / Event 追蹤	—	—	—	—	—	—	—	＋(62/63)	＋
＋ Drawback Import/Export 比對	—	—	—	—	—	—	—	—	＋
Validate & Submit（QUE）	✔	✔	✔	✔	✔	✔	✔	✔	✔
CBP Response / Status 看板	✔	✔	✔	✔	✔	✔	✔	✔	✔
Document 產生（3461/7501/DO 等）	✔	✔	✔	✔	✔	✔	✔	＋7512	＋
Post-Release 修正（PSC/Update）	✔	✔	條件	✔	✔	✔	✔	＋更正	—

資料模型：一筆 Entry（報關單）可包含多個 Shipment（多張提單） → 對應 LDS CustomsEntry.Shipments : List<Shipment>；每個 Shipment 下再各有多張 Invoice 與多個 Line Item。多張提單併入同一 Entry 時設 Consolidated Summary Indicator = Y。

由此可見：完成 Type 01 即建立了 80% 的共用頁面（List / Header / Parties / Bond / Shipment / Invoice / Duty&Fee / Payment / Validate&Submit / Response / Document / Post-Release）。其後每型別多半是「掛上 1–2 個差異模組」。

6. 共用平台元件

規則引擎

Entry Type 判斷邏輯（貨值 / Section 321 eligibility / AD-CVD / quota / bond requirement）
HTS 10-digit 驗證 + Chapter 99 特別關稅自動帶入
PGA trigger check（FDA/EPA/FCC/USDA/APHIS）
MPF/HMF/IR-Tax 計算與 census warning override

主檔 / 參考資料

Contact（IOR/Consignee/Manufacturer/Bond/Surety）— 對應 LDS Contact
CustomsPort / Carrier(SCAC) / Country / FIRMS（LDS Extract Reference File Query）
HTS 表、AD/CVD case、SPI(Trade Agreement) 代碼

整合與狀態

LDS Adapter（WCF proxy 管理、重試、錯誤反序列化）
ABITransmission 輪詢與狀態映射（LastStatuses → 看板）
CATAIR 錯誤字典（error dictionary v48）對應友善訊息

文件與稽核

3461 / 7501 / 7512 / Delivery Order / Customer Invoice 產生
DIS 文件影像上傳封包
送件 payload 與 CBP 回覆的完整 audit log
Amendment / PSC / cancellation workflow

7. 每一型別的標準產品文件包

依你的要求，每一個 Entry Type 都交付以下「相同規格」四件套（全部 HTML）：

#	文件	內容
A	Product Spec（HTML）	User Story、Flow Chart、Acceptance Criteria、欄位對應與說明、LDS API spec mapping
B	Interactive FE Prototype（HTML）	從新建 entry → 填寫 → 驗證 → 計稅 → 送件 → 產生文件 → 取得 CBP 回覆的可點擊原型
C	Customer Manual（HTML，圖文）	依原型截圖的 end-to-end 客戶操作教學
D	（隨附）Field Mapping Sheet	UI 欄位 → LDS 物件/屬性 → CBP CATAIR record/field 對照（併入 A）

本次交付：Type 01 完整四件套 + 本總體計劃。Type 61 及其後型別依路線圖逐型產出，沿用 Type 01 模板。

8. 階段性開發路線圖

P0（最優先，跨所有型別的前置）— GF↔LDS Trade Partner Master Mapping：由 GF 發動，當 LDS 缺對應 TP（company/importer/shipper）時以 GF 資料在 LDS 建檔（importer 經 5106），帶入 Customs Entry；全程寫統一稽核 log，並有獨立稽核頁。詳見 03_GF_LDS_TP_Master_Mapping.html 與 TP_Sync_Audit_Log.html。匹配：importer 用 IRS No.、其他用 GF ref↔LDS ExternalId。注意 GF 公開 API TP 僅 ref/name/uri，缺 IRS/地址等建 importer 必要欄位（候補清單見該文件 F 節）。

P0 — Invoice & Article 精靈（Wizard）：一個引導式 modal,一次建立一張商業 Invoice 連同它的 Articles(品項行)與每個 article 的 Tariff(HTS)——對齊 LDS 桌面的「Wizard」。把輸入(HTS / Qty / UOM / Value / Description / COO / MID / FDA code)依序對應到正確層級 Shipment ▸ Invoice ▸ Article ▸ Tariff,讓操作員不必先學階層。規格見 01_Type01_Spec.html §9;設計見 Type01_Invoice_Wizard_Design.html;操作教學見 Type01_Invoice_HTS_Input_Guide.html。

P0 — Payment Info 頁（ACE-7497）：完成 entry 的必要頁(LDS manual《Payment info》):Payment Type、Deferred Tax Payment、Preliminary Statement Print Date / Month,以及唯讀的 Calculated fees。以獨立 portal 步驟呈現(置於 PGA 之後、Duty & Fee 之前)。對應 CustomsEntry.PaymentType / DeferredTaxPayment / PreliminaryStatement*;print date 依 manual「到港/放行後第 8 個工作日,第 10 個工作日付款」。規格見 §8/§5.7。

P0 — Special 99-Series Tariffs autofill 精靈(ACE-7498):對齊桌面「Autofill Special 99 Tariffs」——一鍵為 entry 上既有的商品 HTS 補上對應的 Chapter 99 稅則行(Section 301 等貿易救濟),由操作員檢視後 Save(compute-only FillSpecial99CorrespondTariffs)。exclusion list 上的品項仍需手動加 HTS。規格見 §9.4。

✅ 已交付（AS-BUILT）— Customs Entry Portal（Type 01）（ACE-7419 epic · ACE-7511 master · PR #6,分支 feat/customs-entry-portal）：portal 已重建為與 LDS field/data 對齊（via API），並進一步演進,超出原本的 stepper 原型與中途的 tree master-detail 設計。實作上,導覽改為 Miller-columns「Document Map」導覽器（Finder 式串接欄位:Entry → Shipment → Invoice → Article → Tariff,ACE-7521）,而非 stepper 或巢狀樹。其周邊:精簡頂列（filer · entry no + 即時狀態 chip,無大頁標題,ACE-7522）、置底置中浮動 Save bar（未變更前 disabled）、低調的底部 Delete 連結,以及 🛠 Tools 選單（Autofill Special 99 Tariffs;送件 Entry Summary / Cargo Release——Add 與 Replace,送出前需確認,ACE-7524/7530）。Main Info 合併 Parties + Header/Importer;Designated notify party（4811）與 PGA 已搬移（4811 → Additional、PGA → Tariff entity 分頁）（ACE-7519）。欄位對應 05_LDS_Field_API_Mapping.html（~147 欄）;設計 Type01_Customs_Portal.html;導覽 IA 06_GF_Portal_Navigation_IA.html;Type01_Customs_Entry_LDS_Parity.html。已 landed 票:ACE-7513 LDS-parity 清單,含四個真實狀態欄（Entry Summary / Cargo Release / Entry status / Duty & Fee,ACE-7532）· ACE-7521 Miller-columns 導覽器 · ACE-7522 精簡 chrome · ACE-7523 Payment + 自動帶入 preliminary-statement 日期/月份 · ACE-7524/7530 Tools + 送件 · ACE-7525 可編輯的 article Charge USD · ACE-7529 存檔併發強化（fresh row_version overlay）· ACE-7531 拆分 Validate（Entry Summary QUE AE / Cargo Release QUE SE） · ACE-7534 Duty & Fee 統一 Query log（記錄每次 Calculate / Validate Entry Summary / Validate Cargo Release 查詢;失敗附 CBP edit 清單與「Fix:」修復指引,如 6048/6083/6127）。

兩條不同的階段軸,請勿混淆：(1) 本節 P0–P4「可發送的 customs filing type」階段(Jira epic ACE-7419;phase Story ACE-7691…7695)——每個 phase 代表「該階段可送出哪些 entry type 的哪些報文」(highest-priority 跨型功能含 PGA 皆歸 P1);(2) ACE-7511 的 LDS-parity portal 建置階段(P1–P6)——是把單張 Customs Entry portal 做到與 LDS 100% 欄位對齊的建置里程碑。兩者是不同維度,下表為前者。

2026-06 LDS meeting 重新排序：依 LDS 建議按 customs filing type 的同構性與貨代量重排——11 Informal 由 P2 提前到 P1（LDS:formal / informal 同構、forwarder 高量）；61 In-Bond IT 由 P1 下移到 P2（in-bond 屬不同交易性質）；07 Quota+AD/CVD 由 P2 下移到 P3（量低、後期）。06 FTZ + e-214（複雜、deferred duty、初期排除）與 47 Drawback（LDS 無對應 API）同列 Deferred,不在 P1–P4。

2026-06：PGA 併回 P1。PGA workflow（ACE-7945）併回 P1 highest-priority 功能群（CPSC + FDA 先;與 LDS 聯合 review）=19 MD,與 Tariff templates + PGA 資料庫（ACE-7939）同在 P1。維持 5 phase（P0–P4）：P1（01 / 03 / 11 + 全部 8 項 highest-priority 含 PGA）、P2（61 / 86）、P3（07 / 21·31 / 62·63）、P4（變體）。合計 MD 不變。

P0–P4 階段路線圖（依 customs filing type）

Phase	Jira	納入的 filing type	送件報文	備註
P0 平台地基	ACE-7691	—（不送任何 filing）	—	GF↔LDS 資料同步 + 主檔管理（MDM）:TP sync + Contact / Port / Carrier / HTS / 參考表同步。所有後續 phase 的前置。
P1	ACE-7692 + ACE-7938/7939/7940/7941/7942/7943/7944/7945	01 Formal（含 §301 / 99-series）、03 AD/CVD、11 Informal + 全部 8 項 highest-priority 功能（含 PGA）	01 / 03 / 11 → AE（7501）+ SE（3461）；PGA 隨各報文夾帶（PG/PGA records）	正式進口主流程;formal / informal 同構（11 由 P2 提前），forwarder 高量。Type-01 portal 已交付（PR #6）。PGA workflow（ACE-7945）含於本 phase。
P2	ACE-7693	61 In-Bond IT、86 Section 321	61 → InBond QP / WP（7512）；86 → SE only	In-Bond 基底（61 由 P1 下移,屬不同交易）+ 跨境電商 321 量大效能優化。
P3	ACE-7694	07 Quota+AD/CVD、21 / 31 Warehouse、62 / 63 In-Bond T&E / IE	07 → AE + SE；21 → AE + SE；31 → AE only；62 / 63 → InBond QP / WP	量低、後期。07 由 P2 下移;Warehouse inventory / balance、In-Bond 出口變體。
P4	ACE-7695	變體 02 / 12 / 23 / 52（Pack A）+ 22 / 32 / 34 / 38（Pack B）	依各變體沿用對應主型別報文流	配額/簽證、TIB、複合型。
Deferred 保留	—	06 FTZ + e-214、47 Drawback	—	不在 P1–P4。06 FTZ 複雜、deferred duty,初期排除;47 Drawback LDS API 無對應 class,待補件。

Highest-priority 跨型功能（2026-06 LDS meeting · Phase 1）

2026-06 LDS meeting 議定的一組跨 filing type 的最高優先功能——皆歸 P1、最高優先。它們不綁單一 entry type,而是構成 P1 可用性的主體（statement / tariff templates / entry 01 等)。本週 Thursday demo 涵蓋 statement / tariff templates / entry 01 三項。

Ticket	功能	All-in 人天
ACE-7938	Statement processing（periodic / daily + preliminary statement date + 付款）	16
ACE-7939	Tariff templates + PGA 資料庫（registration# / device-ID / product-code）	20
ACE-7940	Print CBP response message（AX / SO / UC + 7501 / 3461）	9
ACE-7941	Customs warning / alert 通知（census warning / reject / hold）	10
ACE-7942	建 entry 前 shipment 存在檢查 → update（修 ISF 重複 HBL）	9
ACE-7943	Chapter-99 / §301 autofill 改用 LDS API	7
ACE-7944	ISF 資料整合（帶入 entry）	13
ACE-7945	PGA workflow（CPSC + FDA 先;隨各 filing type 報文夾帶 PG/PGA records;與 LDS 聯合 review）	19
小計		103

2026-06：PGA 併回 P1。PGA workflow（ACE-7945）併回本表 = 19 MD,與 Tariff templates + PGA 資料庫（ACE-7939）同在 P1。本表 8 列小計 103（7938 16 + 7939 20 + 7940 9 + 7941 10 + 7942 9 + 7943 7 + 7944 13 + 7945 19 = 84 + 19）。

✅ 已交付（對應 2026-06 LDS meeting action items）：

Engineer Debug Log（ACE-7709）= 「為 LDS 工程師加 API 請求 / 回應 logging」的 action item,已上兩個 sandbox。
UAT + DEV sandbox:tunnel gf-customs-portal-brad.hardcoretech.link（UAT）/ -dev.hardcoretech.link（DEV）,為給 LDS 取用的穩定連結。
Document sharing（GoFreight → LDS）:另線已完成。

各 phase 工時估計（人天）

下表為 P0–P4 各 phase 的 all-in 工時（5 phase;PGA 併回 P1）。不含已交付之 Type-01 portal 與 Deferred 的 FTZ / Drawback。

Phase	Jira	內容	All-in
P0 地基（MDM）	ACE-7691	平台地基 — GF↔LDS 資料同步 + 主檔（MDM）	16.5
P1 01 / 03 / 11 + highest-priority（含 PGA）	ACE-7692 + 7938…7945	型別主流程 ~20 + highest-priority 功能 103（8 列,含 PGA ACE-7945）	123
P2 61 / 86	ACE-7693	In-Bond 基底 + Section 321	~20
P3 07 / 21 / 31 / 62 / 63	ACE-7694	Quota+AD/CVD、Warehouse、In-Bond 出口變體	~25
P4 變體 Pack A / B	ACE-7695	配額/簽證、TIB、複合型	21
合計 P0–P4（Epic ACE-7419）			≈ 205.5

摘要：P0 16.5 · P1 123（型別 ~20 + highest-priority 103,含 PGA）· P2 ~20（61/86）· P3 ~25（07/21·31/62·63）· P4 21（變體）;合計 ≈ 205.5 all-in 人天。註:PGA workflow（ACE-7945,19 MD）併回 P1,總數不變。不含已建之 Type-01 portal 與 Deferred 的 06 FTZ / 47 Drawback。Epic ACE-7419,phase Story ACE-7691…7695。

9. 風險與相依

項目	風險 / 相依	對策
LDS 為 WCF/C#	GoFreight 若非 .NET 端，整合需轉接層	建 .NET Adapter，對內出 REST/JSON facade
非同步無 callback	狀態延遲、需輪詢	輪詢 + Webhook 模擬、狀態看板、清楚的 pending UI
PGA / Condition codes 外置	細項碼值在另檔（PGA Status Codes、Appendix G、error dictionary v48）	建錯誤字典對照表，持續同步 CBP 更新
CBP 規格更新	CATAIR 持續改版	以最新 CBP CATAIR 為準，版本化 mapping 設定
計稅正確性	稅費由 LDS 計算（read-only），需驗證	以 `CalculateDutyAndFee` 為準，UI 顯示 server 值，禁止前端覆寫除非 manual override