A. 目的與整合方向

GoFreight 使用者在建立 Customs Entry 時需要選用 Trade Partner（IOR / consignee / shipper 等）。若該 TP 在 LDS 報關後端尚未存在，系統需由 GF 發動、以 GF 既有資料為基礎，在 LDS 建立對應 Contact（必要時送 CBP 5106 建立 importer），再帶回 Customs Entry。

方向（單向、GF 主動）：GoFreight 為 source of truth → 推送 / 建立 → LDS。本期不處理 LDS→GF 回寫主檔（僅回寫 LDS Code / 狀態供關聯）。主要對象：company、importer、shipper。

觸發情境

GF user 在 Customs Entry 指定某 TP。
系統先在 LDS 查找相同 TP（見 C 匹配策略）。
找不到 → 發動在 LDS 建立 Contact（+ 視需要 5106 importer）。
建立成功 → 帶入 Customs Entry（Importer_Id / Consignee_Id / Seller_Id）。
每一步都寫 log，並於獨立稽核頁可查。

B. 兩端實體模型

GoFreight（來源）

由 api.gofreight.com bundle 觀察：TP 以 reference 表示，公開結構精簡。

TP 物件：trade_partner { ref, name, uri }（只有三欄）
角色以 booking 上的 *_ref 表示：customer_ref、actual_shipper_ref、consignee_ref、customs_broker_ref、bill_to_ref、notify_ref …
文件上傳：POST /documents/trade-partner/{ref}
無 importer_ref、無稅號/IRS、地址、電話 email、角色 flag（公開 bundle 內 NOT FOUND）

關鍵限制：公開 bundle 的 TP 僅 ref / name / uri。建立 LDS importer 所需的 IRS、地址等需另一個 GF TP 詳細 endpoint（不在此 bundle）。見 F「候補欄位」。

LDS（目標）

TP = 單一 Contact 物件，角色用 flag；importer 另以 5106 建到 CBP。

類別：Contact : EntityDirectory / IContactManager
身分鍵：Id、Code(req,自動)、ExternalId(可存 GF ref)、IRSNumber、CBPNumber、SocialSecurityNumber+DateOfBirth、DUNS
角色 flag：RolesIsImporter / RolesIsShipper / RolesIsSeller / RolesIsManufacturer …（無 RolesIsConsignee — consignee 由文件 FK 表示）
地址：mailing（Adress1..3, AdressType, City, State, ZIP, Country）；business 在 Contact.Ext
5106：Contact.Ext 的 ImporterType + CBPF5106_*，送 ActionQUE.ImporterConsigneeCreate

注意：LDS 無 Shipment.Shipper 欄位 — shipper 角色於文件層用 Seller（+ Consolidator）；Contact.RolesIsShipper flag 仍可標記。

C. TP 對應策略（匹配鍵）

依需求：importer 由 IRS No. 對應；其他 TP 由 ID 對應。落地到 LDS 的查找順序：

順序	對象	匹配鍵	LDS 方法	說明
1	Importer	IRS No.（或 CBP No / SSN+DOB）	`GetByNumber(irs)` / `GetByCandidate`	先用標準 Customs 格式查；`IsIRSNumber()/IsCBPNumber()` 先分類
2	其他 TP（shipper/consignee/customer…）	GF TP ref（ID）	`GetByExternalId(gf_ref)`（建議把 GF ref 存 LDS `Contact.ExternalId`）	ID 對應：GF ref ↔ LDS ExternalId
3	任意	LDS Code	`GetByCode(code)`	已知 LDS code 時
4	fallback	Name + Address（fuzzy）	`GetByCandidate(candidate)` / `GetByName(name,Contains)`	避免重複建檔；需人工確認

對應持久化：建議在 GF 端維護一張 TP 對應表（GF ref ↔ LDS Code / Id / IRSNumber），並把 GF ref 同步寫入 LDS Contact.ExternalId，雙向可追。importer 以 IRS 為主鍵、其餘以 GF ref 為主鍵。

D. Flow Chart — GF 發動：查無 → 建檔 → 帶入 Entry（全程 log）

紅色虛線＝每個動作都寫入統一稽核 log（包含先前規劃的 customs filing 發動）。⑤ 5106 為非同步（PutToQUEOneWay），以 ABITransmission 關聯回填狀態。

E. Field Mapping（GF → LDS Contact）

M 必填(LDS Save)C 5106 必要O 選填

GF 來源	LDS Contact 屬性	必填	CBP 5106	說明 / 對應規則
`trade_partner.ref`	`Contact.ExternalId`	建議	—	ID 對應主鍵（GF ref ↔ LDS ExternalId）
`trade_partner.name`	`Contact.Name`	M	Name	≤35 字；超長拆 SecondName
（自動）	`Contact.Code`	M	—	未給則 `GenerateCode()` 自動產生
角色（依 booking *_ref）	`RolesIsImporter / RolesIsShipper / RolesIsSeller …`	O	—	customer/actual_shipper/… → 對應 flag
IRS / EIN ✱缺	`Contact.IRSNumber`	C	Importer No. (EI)	importer 對應主鍵；格式 NN-NNNNNNNXX
SSN + DOB ✱缺	`SocialSecurityNumber + DateOfBirth`	C	Importer No. (SSN)	個人 importer 替代
CBP No ✱缺	`Contact.CBPNumber`	O	CBP Assigned	僅更新用；無 SSN 可申請
地址（街/市/州/郵/國）✱缺	`Adress1 / City / State / ZIP / Country`	C	Mailing Address	5106 必要
地址類型 ✱缺	`AdressType`（+Explanation）	C	Address Type	5106 必要（Has Possible Values）
實體營業地址 ✱缺	`Ext.BusinessAddress1 / BusinessAddressType …`	O	Physical Address	有填則 BusinessAddressType 必填
Importer 類型 ✱缺	`Ext.ImporterType`	C	Importer Type	5106 必要（1 碼）
電話/Email ✱缺	`Phone / Email`	O	—	—
DUNS ✱缺	`Contact.DUNS`	O	DUNS	—
MID（製造商）✱缺	`ManufacturerSupplierCode`	O	—	shipper/manufacturer 用

帶入 Customs Entry 的關聯

角色	LDS 文件屬性	說明
Importer of Record	`CustomsEntry.Importer_Id`	必填；ABI 取號順序 IRS→CBP→SSN
Consignee	`Shipment.Consignee_Id`	—
Shipper / Seller	`Shipment.Seller_Id`（+ Consolidator）	LDS 無 Shipment.Shipper，用 Seller
Buyer / ShipTo	`Shipment.Buyer_Id / ShipTo_Id`	—

✱缺＝在 GF 公開 bundle 的 TP 物件中找不到，需 GF 提供 TP 詳細 endpoint 才能取得（見 F）。

F. 候補欄位 — GF TP API 缺漏（建立 LDS importer 必要）

核心結論：GF 公開 bundle 的 Trade Partner 僅 ref / name / uri。要在 LDS 建立可用的 importer（5106）與完整 Contact，GF 需補以下欄位（建議於 TP 詳細 endpoint 提供）。下表為候補清單，標注 LDS 對應與必要性。

#	GF 需補欄位（建議名）	對應 LDS	建 importer 必要性	備註
1	`irs_no / ein`	`Contact.IRSNumber`	必要	importer 主鍵；NN-NNNNNNNXX，後兩碼不可 O/I/Z
2	`importer_no_type`（EI/SSN/CBP）	`Ext.ImporterType` + 號碼欄位	必要	決定用哪個號碼
3	`ssn` + `date_of_birth`	`SocialSecurityNumber + DateOfBirth`	替代	個人 importer
4	`cbp_no`	`Contact.CBPNumber`	更新用	無 SSN 可申請 CBP-assigned
5	`mailing_address {line1,line2,city,state,zip,country}`	`Adress1..3, City, State, ZIP, Country`	必要	5106 mailing
6	`address_type`	`AdressType` (+Explanation)	必要	5106 必填（代碼）
7	`physical_address {…}` + `physical_address_type`	`Ext.BusinessAddress* / BusinessAddressType`	條件	有實體地址則類型必填
8	`legal_name` / `dba`	`FullLegalName / SecondName`	建議	name ≤35，法定名另存
9	`phone / email / fax`	`Phone / Email / Fax`	選	聯絡
10	`duns`	`Contact.DUNS`	選	—
11	`mid_code`（製造商）	`ManufacturerSupplierCode`	選	shipper/manufacturer
12	`program_codes[]`	`Ext.CBPF5106_ProgramCode1..4`	選	5106 program（代碼）
13	`owner_officer {name,title}`	`Ext.CBPF5106_Person1/Title`	選	負責人/officer
14	`roles[]`（importer/shipper/consignee/…）	`RolesIs*` flags	建議	明確標記角色，免靠 booking 推斷

建議：GF 新增一個 TP 詳細查詢 endpoint（如 GET /trade-partners/{ref}）回傳上述欄位；至少 #1、#2、#5、#6、#8、#14 應補齊，才能無人工介入完成 LDS importer 自動建檔。未補齊前，系統需在建檔精靈中提示人工補欄位並記錄缺漏。另：ImporterType / AdressType / Country / ProgramCode 的代碼值清單來自 CBP CATAIR，需建對照表。

G. Logging 規格（統一稽核日誌）

所有操作都寫入統一稽核日誌——包含 TP 查找、TP 建檔、5106 送件、帶入 entry，以及先前規劃的 customs filing 發動（calc/validate/QUE/收到 CBP 回覆）。

Log 紀錄結構（建議 schema）

TpSyncAuditLog { log_id // 流水號 timestamp // 動作時間（UTC + 顯示時區） user // GF 操作者（email / id） action // TP_LOOKUP | TP_CREATE_LDS | IMPORTER_5106 | // LINK_TO_ENTRY | CUSTOMS_FILE_QUE | CBP_RESPONSE | ... tp_name // TP 名稱 tp_code // LDS Contact.Code（建立後） tp_type / role // importer / shipper / consignee / customer ... gf_ref // GF trade_partner.ref（ID 對應） irs_no // importer 對應鍵（遮罩顯示） lds_contact_id // LDS Contact.Id entry_no // 關聯 Customs Entry（如適用） abi_transmission // 5106 / filing 的 ABITransmission id（非同步關聯） status // SUCCESS | PENDING | FAILED detail / message // 結果說明 / 錯誤碼 source_link // "Contact={id}" / "CustomsEntry={id}" }

記錄規則

每個動作落一筆；非同步動作（5106、QUE）先 PENDING，收到 LDS/CBP 回覆後更新同一筆或補一筆 CBP_RESPONSE。
敏感欄位（IRS/SSN）遮罩顯示、保留完整於後端供稽核。
不可變（append-only），保留操作者、時間、前後值。
與 LDS ABITransmission.SourceLink / EntityLastStatus 對齊，可回查原始 payload。

H. 獨立稽核頁設計

提供一頁獨立頁面：紀錄 GF 自動在 LDS 新建了哪些 company / TP，歷程含時間、使用者、TP name、code、type（及狀態、IRS/GF ref、關聯 entry）。可篩選、可看明細。

LDS TP Auto-Create — Audit Log（獨立頁）

🔍 搜尋 TP / IRS / ref Type: All ▾ Action: TP_CREATE_LDS ▾ Date: 30d ▾ Export CSV

Time	User	TP Name	LDS Code	Type	IRS / GF ref	Status
06-19 10:21	brad.fan	PACIFIC TRADING LLC	PACTRAD01	Importer	95-•••• / TP-1	Created+5106
06-19 10:24	brad.fan	SHANGHAI APPAREL MFG	SHGAPP02	Shipper/MFR	— / TP-204	Created
06-19 10:25	brad.fan	J SMITH (TX)	—	Consignee	— / TP-810	Pending(欄位缺)

點任一列 → 明細抽屜：完整歷程、欄位值、ABITransmission、關聯 Customs Entry、錯誤/缺漏欄位。

互動版頁面：TP_Sync_Audit_Log.html（可點擊篩選 / 明細抽屜 / 缺漏欄位提示）。

I. Acceptance Criteria 與風險

Acceptance Criteria

建 Customs Entry 指定 TP 時，系統自動於 LDS 查找：importer 用 IRS（GetByNumber），其他用 GF ref（ExternalId）；找到則直接用。
查無時，GF 發動以 GF 資料 New→Save 建 LDS Contact；importer 另送 ImporterConsigneeCreate（5106）。
建檔成功後，GF ref 寫入 LDS ExternalId，並把 Contact.Id 帶入 CustomsEntry.Importer_Id / Shipment.Consignee_Id/Seller_Id。
若 GF 缺必要欄位（IRS/地址/ImporterType…），系統阻擋自動 5106，提示人工補欄位，並記 PENDING + 缺漏清單。
每一步寫稽核 log（含 customs filing 發動）；非同步動作以 ABITransmission 關聯回填狀態。
獨立稽核頁可依 time/user/type/action/狀態篩選，顯示 TP name/code/type、IRS/GF ref、狀態，並可匯出。
重複建檔防呆：建立前必跑 GetByCandidate 比對，疑似重複需人工確認。

風險

風險	對策
GF TP 缺 IRS/地址等（公開 bundle 無）	請 GF 提供 TP 詳細 endpoint（F 候補欄位）；未補前人工補欄並記錄
重複建檔	GetByCandidate + ExternalId 去重；對應表單一來源
5106 非同步失敗	PENDING 狀態 + 重試 + 反序列化 EntryValidationFault 顯示原因
代碼值（ImporterType/AddressType…）	建 CBP CATAIR 對照表，隨規格更新
敏感資料（IRS/SSN）	遮罩顯示、加密儲存、存取稽核