Type 01 正式消費進口 — 產品規格（Spec / Flow / AC / Field Mapping）

Type 01（Consumption – Free & Dutiable）是最常見的正式進口報關。一筆 Type 01 由兩個 CBP 報文流組成：

• Cargo Release（SE → SO）：向 CBP 申請貨物放行（3461）。
• Entry Summary（AE → AX）：申報關稅、稅費、統計，供 CBP 結算（7501）。

兩者以同一個 Entry Number（Filer Code + Entry No）關聯，可分兩步送，或以「Certify for Cargo Release（AE 10-record 第 40 位 = A）/ Live Entry」一次送出。

1.1 資料模型階層（一筆 Entry 可含多個 Shipments）

因此 UI 必須支援「一筆 Entry 內新增多張 Shipment/Bill」，且計稅、驗證、送件都以整筆 Entry（彙總所有 shipments）為單位。

1.2 頁面架構（LDS-parity：Document Map + 分頁，100% 欄位對應）

各層級資料物件：CustomsEntry → Shipment → ShipmentInvoice → ShipmentArticle → ShipmentArticleTariff（+ PGA / AdditionalDeclaration / CensusWarning），整棵樹由 ICustomsEntryManager 之 New / Save / Get(include) / CalculateDutyAndFee / ValidateTreeById / PutToQUE 提供；關係人為 Contact（IContactManager，配合 P0 TP Sync）。少數畫面欄位 LDS API 尚無對應（Liquidation、Manifested quantity、Sanctions grid、Invoice 層 party 等），於頁面以紅色標示待 LDS 確認（清單見 05 文件）。

1.2a Entity detail 分頁（as built — EntityDetail / ENTITY_LAYOUT）

Detail pane 依選取的 entity kind 渲染分頁列,每個分頁含一個或多個 field group(2/3/4 欄 form grid),空 group 自動略過。as-built 的 tab → group → field 佈局如下:

注意與舊 LDS mockup 的刻意差異:Article 只有 Values + Commercial entities(無 Payment/FTZ/AD-CVD/Additional/PSC/Census 分頁);那些分頁實際位於 Tariff entity。Tariffs Miller 欄顯示完整 HTS code(由 harmonized_tariff_id 解析),非原始 id。

1.3 Customs Entry 列表檢視（List View，對照 LDS）

清單支援欄位排序、列點擊開啟單一 entry、「New Entry」新建（同採 LDS-parity 編輯器）。

1.4 Portal 左側導覽（Navigation / IA）

採 GoFreight 慣例：左側單一直欄導覽，分群（總覽 / 報關 / 貨運與文件 / 主檔 / 財務 / 查詢與監控）。Customs Entries 為首期主體；其餘主要功能（In-Bond、FTZ、ISF、Drawback、Shipments、Delivery Orders、DIS、Trade Partners、Reference Data、Statements、Customer Invoices、Customs Queries、Reports、Settings）依 LDS Applications 於選單預留位置並標示狀態（已建 / 進行中 / 預留）。完整導覽規劃見 06_GF_Portal_Navigation_IA.html。

Entry 編輯器 document tree（as built，ACE-7519）：entry 節點為 Main Info——header 與 Importer 合併,entry 層不再有獨立 Parties 節點(商業 parties 位於 Shipment 與 Article 層)。Entry 群組:Main Info · Bond · Payment · Additional info。Designated notify party (4811) 置於 Additional info,並顯示連結的 company。PGA 不是 entry 節點——它是 Tariff 的 tab;entry 層的「PGA data included」旗標仍留在 Additional info。Document Map 採 Miller-column 導覽(Finder 式):每一層 — Shipments ▸ Shipment ▸ Invoices ▸ Invoice ▸ Articles ▸ Article ▸ Tariffs ▸ Tariff — 往右開一欄而非往下縮排,Article/Tariff label 不再被截斷。下方 detail pane 顯示最深選取的**分頁(tabs)**欄位——Shipment(Bill / Commercial entities)、Invoice(Values / Commercial entities)、Article(Values / Commercial entities)、Tariff(Values / Payment / FTZ / Sanctions / P.G.A.)。每欄含 ＋ Add;Corrections = Post Summary Correction · Cancellation · Consolidated release;Filing = Duty & Fee · Result。(ACE-7521,option D)

Entry chrome(ACE-7522):最上方僅一行小字 — filer code · entry number(無大標題)+ 狀態 chip。Document Map 更 compact — 欄位高度砍半(≈126px;過長欄位於欄內捲動)且移除「Document Map」標題列,節省垂直空間。Save 改為**懸浮於畫面正中下方**(GoFreight FMS 式)— 一律存在、僅在有未存變更時啟用。Delete 降級為頁面最下方的低調文字連結,移出上方重要版位。

Entry tools(ACE-7524 / 7530):右上角 🛠 Tools 選單(分群,點外部 / Escape 關閉)含兩群。Tariffs:Autofill Special 99 Tariffs(Chapter 99 / Section 301 trade-remedy autofill)—— 為 compute-only round-trip(FillSpecial99CorrespondTariffs),在 entry 未存檔或有未存變更時停用(因它讀的是已存檔的 HTS codes);has_changes 時把修改後的樹帶回表單供操作員檢視後 Save。Transmit to CBP (ABI/ACE)(ACE-7533,完整動作集):傳輸子選單擴充為完整的 CustomsEntry.ActionQUE 傳輸動作集,依 ABI application 分組(見下方「Transmit 動作集」表)—— Entry Summary · AE(7501)、Cargo Release · SE(3461)、Entry Summary + Cargo Release、以及 Other ABI actions。每個 UI 動作的 action 字串原樣帶到 wire 上的 CustomsEntry.ActionQUE enum body(no allow-list)。每次傳輸皆二次把關(double-gated):UI 的 window.confirm("… — transmit to CBP via ABI/ACE? This sends to U.S. Customs."),以及請求本身帶 confirm:true 到後端。成功時頂部 banner 顯示「✓ {label} submitted to CBP.」;失敗則呈現完整 CBP/SMS fault,讓操作員看出該修什麼(state、缺資料、Add-vs-Replace)。Document Map 的 Tariffs 欄顯示完整 HTS code(由 harmonized-tariff id 解析),而非原始 id。

建檔與資料（US-01~04）

1. GIVEN 在 Entry List WHEN 點 New 並按 Entry Number 的「…」THEN 系統依序列自動帶入下一個 Entry Number（8 碼含 check digit），且 Entry Type 預設 01、Bond Type 預設 9、Payment Type 預設 1。
2. IOR Number 必填，格式須符合 IRS NN-NNNNNNNXX / CBP YYDDPP-NNNNN / SSN 三者之一，否則阻擋。
3. MOT、Port of Entry 必填（Type 01）；Port of Unlading 在 MOT 為 50/60/70 時必填。
4. 一筆 Entry 可新增多個 Shipment（多張 Bill）；每個 Shipment 各有自己的提單、件數、貨櫃與 invoice/行項。新增 ≥2 個 Shipment 時，系統自動將 Consolidated Summary Indicator 設為 Y。
5. 計稅、驗證、送件皆以整筆 Entry（彙總所有 Shipment 的行項）為單位；Total Amount Due 為所有 shipment 行項加總。
6. 每一商品行項必填 HTS（10 碼）、Country of Origin（ISO 2 碼）、Value、Quantity 與符合 HTS 的 UOM。
7. Manufacturer(MID) 與 Consignee 可於 header（共通時）或 line level 提供，二擇一須齊備。

Bond（US-02）

1. Bond Type = 9（單筆）時，Surety Code 與 Bond Amount 必填；= 8（連續）時帶連續保證資料；= 0 須提供 Bond Waiver Reason。

Payment（US-04, ACE-7497）

1. Payment 是完成 entry 的必要 portal 步驟(置於 PGA 之後、Duty & Fee 之前):Payment Type、Deferred Tax Payment、Preliminary Statement Print Date / Month,以及唯讀的 Calculated fees。對應 CustomsEntry.PaymentType / DeferredTaxPayment / PreliminaryStatementPrintDate / PreliminaryStatementMonth(Date)。
2. 依 LDS manual,Preliminary Statement Print Date 為到港後第 8 個工作日(放行後重算為放行後第 8 個工作日),付款落在第 10 個工作日。
3. 自動填入(ACE-7523):Payment 節點在 arrival date / entry date / payment type 三者皆齊全時自動呼叫 GetPreliminaryStatementDates(arrival ← CustomsEntry.DateOfArrival, entry ← CustomsEntry.Date, paymentType ← CustomsEntry.PaymentType)(經 GET /api/lookups/preliminary-statement-dates),任一輸入變更即重算(debounce),把算出的 print date 寫入欄位;periodic statement 才顯示 statement month(non-periodic 回 null)。僅在值確實不同時才寫入,開啟既有 entry 不會被誤標 dirty。另提供手動 Recompute print date 按鈕。

Shipment parties & dates（US-02~06）

1. 每張 Shipment 卡需捕捉 CBP SE/AE 必要的 parties——Seller(seller_id)、Buyer(buyer_id)、Consignee(consignee_id),皆為 Trade-Partner / contacts directory 欄位——以及 Date of arrival(date_of_arrival)與 Date of export(date_of_export)。缺這些時 Calculate/Validate 會報缺。
2. date_of_export(「Export date」)存在於 Shipment entity(DateOfExport)但 manifest 未含;portal 以 augmentConfig 注入 shipments config,使其能渲染且存檔正常 round-trip(亦已加入 manifest JSON,供伺服器端 first-class 支援)。
3. Article 的 Country of export(country_of_export)以「COE」欄顯示於 Lines 表與 Invoice Wizard;Invoice 的 Value currency rate(invoice_value_currency_rate)顯示於 invoice 表頭與 Wizard。

計稅與驗證（US-05~06）

1. WHEN按 Calculate duty & fee THEN 系統呼叫 CalculateDutyAndFee(id) 算出 Duty、MPF(class 499)、HMF(class 501)、IR-Tax 與 Total Amount Due;金額欄唯讀(server 計算)。As built(ACE-7531/7491):Calculate 為 compute-only,該步驟僅在 LDS 真的回傳 totals 時才標為完成(200 但無 result 或 422 皆為 FAILED calc — 不標為完成)。Totals 以 4 卡 grid 顯示(Duty / MPF / HMF / Total amount due)。查詢記錄(ACE-7534):每一次 Calculate 都記入統一的 Query log(見 §6.1),含 ✓ PASSED / ✕ FAILED chip + 時間戳 + 原因;Calculate 失敗時 reason 另附修復方式(確認 entry 有 shipment → invoice → article → tariff 且每行有 HTS code 與應稅金額並已 Save,再重新計算)。
2. 按 Check 時呼叫 ValidateTreeById(id,"QUE AE") 與 ("QUE SE")，任一失敗顯示紅叉；點開列出錯誤,雙擊錯誤列跳到對應欄位。As built(ACE-7531):Duty & Fee 節點有兩顆按鈕 — Validate Entry Summary(action "QUE AE")與 Validate Cargo Release(action "QUE SE"),各自顯示 pass/fail 與逐欄錯誤(含 SMS error code,如 6083/6127)。修正:先前版本送空 action,不對應任何 CBP edit-set 而假 pass(LDS app 卻有錯);現改送對應的 "QUE …" action。查詢記錄(ACE-7534):每一次 Validate Entry Summary 與 Validate Cargo Release 都與 Calculate 共用同一份 Query log(見 §6.1);失敗紀錄另列出 CBP edit 錯誤清單(欄位 — 訊息 [code])與「Fix:」修復方式。
3. 驗證未通過時，QUE（送件）按鈕停用。「Validated」狀態與 Submit gate 需 AE 與 SE 皆通過。

送件與回覆（US-07~08）

1. 送件呼叫 PutToQUEOneWay(id, AddEntrySummaryAndCargoRelease)（或分送 AddEntrySummary / AddCargoRelease），UI 即時顯示「已入列」並記錄 transmission Id 與 SourceLink。
2. 系統輪詢 GetBySourceLink("CustomsEntry={id}") 與 LastStatuses，把狀態映射到看板：Cargo Release（SO60 代碼）、Entry Summary（AX 的 A/R + severity）、Statement。
3. AX 回 R/F（Reject/Fatal）時標紅並列出 condition code 與敘述，提供「修正並重送」；回 A/W（Census Warning）時提示需校正或送 Census Warning Override（CW02）。
4. SO60 = 98 RELEASED 時標示貨物已放行；其他（如 29 NOT RELEASED、03 Intensive Exam、53 CBP Hold 等）顯示對應狀態與處理建議。

文件與送後（US-09~10）

1. 放行/接受後可產生 3461、7501、Delivery Order，並可建立 DIS 文件影像封包上傳。
2. 放行後 15 個日曆日內可送 SE 「U」更新 bill/manifest/port；不可再送「R」Replace。
3. 可發起 Post Summary Correction（PSC），帶 reason code 與說明文字。

5.1 Header（CustomsEntry / SE10 / AE 10-11）

5.2 Parties（Contact / SE30-36 / AE 11、SE50-56 line level）

5.3 Bond（CustomsEntry / SE20 / AE 31）

5.4 Shipments / Bill of Lading（CustomsEntry.Shipments : List<Shipment> — 可多筆 / SE15-17）

一筆 Entry 可有多個 Shipment，每個 Shipment 為下列欄位的一組（一張提單）。多張提單併入同一 Entry 時，AE 10 pos42 Consolidated Summary Indicator = Y。

5.5 Invoice / Line Item / Tariff（ShipmentInvoice → Article → Tariff / SE40-60 / AE 40-50）

5.6 Duty / Tax / Fee（皆 server 計算，唯讀 / AE 50,60,62,88-90）

5.7 Payment / Statement（CustomsEntry / AE 10 51-61）

Type 01 happy path 的 LDS API 呼叫順序：

6.1 Query log — Duty & Fee 查詢記錄（ACE-7534）

Duty & Fee 節點原本只有 Calculate 的 attempt log;現一般化為統一的 Query log 卡片,記錄該 entry 在此節點發起的每一次查詢。涵蓋三種查詢 op,皆與 CBP/SMS 互動:

每次查詢在 Query log 由新到舊新增一筆,每筆含下列欄位:

失敗的紀錄除 CBP edit 清單外,另顯示「Fix:」修復方式。已知 CBP/ABI SMS edit code 對應具體指引:

Transmit 動作集 — 🛠 Tools ▸ Transmit to CBP（ActionQUE,依 ABI application 分組,ACE-7533）

權威來源:LDS SMS API spec doc 03「Customs entry classes and interfaces. Part 1」p11 + doc 08「Annex. ABI classes and interfaces」pp5-6 的 ABI app-id → CustomsEntry.ActionQUE 對照矩陣。每個 UI 動作的 action 字串原樣帶到 wire 上的 ActionQUE enum body(no allow-list);每個動作皆 window.confirm + 後端 confirm:true 二次把關。

Entry 底部的 log 區由單一卡片改為雙 tab 切換:「User log」(§6.1 的逐欄位 / 逐查詢 edit log)與新增的 「🛠 Engineer Debug」。Engineer Debug tab 列出 portal 對 LDS(SMS Broker)的每一次 SOAP 呼叫,供工程與支援人員直接在 entry 內看 wire 上實際送/收了什麼,不必翻後端 log。實作見 Type01_Customs_Portal.html 的 Duty & Fee 節點 log 區。

權限（暫不綁,gating 為後續）

Tab UX

• tab 列:「User log」與「🛠 Engineer Debug」,各帶筆數 count;預設停在 User log。
• 每列(由新到舊):status chip(HTTP {status} / ERR · {transport error})· service.operation(例 CustomsEntryManager.CalculateDutyAndFee)· 時間 · 耗時 ms。
• 展開列:顯示完整 request SOAP envelope 與完整 response payload(等寬字、navy 底、可捲動)。response 為 transport error 時顯示 fault / exception 文字。
• 控制:Refresh 重新抓取;toggle 「Show all recent calls(not just this entry)」—— 預設只看本 entry(以 request path 設定的 entry-id context 歸屬),勾選後看 process-wide 最近全部呼叫。

記錄內容（每筆 ring-buffer entry）

Broker 認證遮罩（永不顯示）

後端 — read-only endpoint + ring buffer

涵蓋範圍 — 所有 portal 觸發的 LDS op

擷取涵蓋 portal 觸發的所有 LDS operation,包含:

Cargo Release（SO / SX）— SO60 Disposition

Entry Summary（AX）— E1 Disposition + Severity

UC（Entry Summary Status Notification）另回送後事件：4=summary rejected/PSC rejected（2 工作日內回應）、3=request documents、6=canceled、P=PGA、Q=quota 等；reason code 如 003 Classification、005 Line Value、010 AD/CVD Required 等。

目的。一個引導式 modal,一次建立一張商業 Invoice 連同它的 Articles(品項行)與每個 article 的 Tariff(HTS)——對齊 LDS 桌面的「Wizard」按鈕(ce-invoice.html)。解決「我有 HTS / 數量 / 金額,但不知道該填哪裡」的困惑:把每個輸入依序對應到正確欄位。

9.1 流程

9.2 欄位 — 每個輸入填在哪

9.3 驗收標準

• AC-W1 shipment 上的「Wizard」會開 modal,顯示該 shipment(BoL)情境。
• AC-W2 精靈可輸入 Invoice 表頭 + ≥1 個 Article,每個 Article 帶一條 Tariff(HTS)行。
• AC-W3 「只填主 HTS」;UOM 對照 HTS 規定驗證(不符給警告)。
• AC-W4 一次精靈可加多個 article;每個可移除。
• AC-W5 OK 把 invoice(含 articles + tariffs)寫入該 shipment 的 Invoices;Cancel 全部捨棄。
• AC-W6 新 invoice / article / tariff 列存檔時取得 server Number / Line(不會 duplicate-key (0))。
• AC-W7 寫入結果與手動建立的 invoice 結構一致(同一 RHF field array),Calculate / Validate / Submit 行為不變。
• AC-W8 shipment 的任一張 invoice(含唯一/最後一張)皆可用「✕ Remove invoice」刪除(會 confirm;連同該 invoice 的 article 行一併移除)。刪到 0 張時顯示空狀態,可再用「+ Add invoice」或 Wizard 重建。(ACE-7493)
• AC-W9 在稅則行選定 HTS 後,自動以該 HTS 紀錄的申報單位(unit1)帶出該行的 UOM(Unit of Measure 1),使用者免手動查找(例:6109100012→DOZ、5211202940→M2),仍可手動覆寫。(ACE-7494)
• AC-W10 Country of Origin 與 Invoice value Currency 為可搜尋下拉(combobox)——可用代碼或名稱過濾(冗長的)參照清單(如 US / United);新 article 的 Country of Origin 預設 US。Wizard 以外的其他參照欄位仍維持原生下拉。(ACE-7495)
• AC-W11 在稅則行選定 HTS 後,自動連結該 importer 對應的 CustomerTariff(「Tariff No.」,tariff_id),使線項在 LDS 桌面正確顯示(LDS 以 Tariff No. 為線項主鍵)。解析方式 = entry 的 importer(importer_id)+ HTS code;找到 → 設 tariff_id,找不到 → 留 null。Wizard 與 Invoice & Lines 表皆適用。(ACE-7499)
• AC-W12 一個 article 可有多條稅則行(ShipmentArticle → 多個 ShipmentArticleTariff):Chapter-99 Section-301 行 + Chapters 1–97 商品行。Invoice & Lines 表會把該 article 的每一條稅則行各渲染成一列(article 欄位顯示在第一條,其餘列編號 n.2、n.3…),並提供「＋ Add tariff line」。這就是為何自動帶出的 Special-99 行現在看得到(先前只顯示 tariffs[0])。(ACE-7500)

9.4 Special 99-Series Tariffs autofill（ACE-7498）

對齊 LDS 桌面「Autofill Special 99 Tariffs」精靈。針對 entry 上既有的商品 HTS(Chapters 1–97),一鍵自動補上對應的 Chapter 99 稅則行(Section 301 / 貿易救濟),操作員免手動查找。

• AC-S1 🛠 Tools 選單(Tariffs 群)提供「Autofill Special 99 Tariffs」動作;在 entry 未存檔或有未存變更時停用(它讀的是已存檔 entry 的 HTS codes)。(ACE-7524)
• AC-S2 呼叫 compute-only op FillSpecial99CorrespondTariffs(ce)(後端 POST /{id}/fill-special99-tariffs),回 {has_changes, entry},不落地。
• AC-S3 has_changes 時把回傳 entity 帶回表單(新增的 Chapter-99 行可見)並啟用 Save;操作員檢視後 Save 落地(新列存檔時取得 Line ordinal)。
• AC-S4 無變更時顯示「無可套用的 Special 99 稅則」且不更動任何資料。
• AC-S5 在 CBP exclusion list 上的品項須手動加 HTS(依 LDS manual)——autofill 不涵蓋 exclusion。