進口模組 — 開發階段任務拆解

Phase 1 MVP — 核心進口管理

跑通一般進口報關、多維追蹤。建立品牌主檔→採購單→作業單→船務→貨櫃完整骨架，含 list/kanban/calendar/activity 多視圖。
交付標準：可建立一筆完整進口作業單，從草稿走到 released（海關放行）狀態，可查看 Kanban/Calendar。

Phase 1 交付物

trade.import.brand + case + shipment + container 四模型完整 CRUD
主狀態機：draft → released + done（到岸成本）；action_confirm / action_release / action_done
多視圖：list / kanban / calendar / activity / form / search
can_release compute（基礎版：報單全 released）
res.partner 角色旗標 + 權限群組

🗂 trade.import.brand — 品牌主檔

建立 trade.import.brand 模型（name/name_en/code/partner_id/default_forwarder_id/default_customs_broker_id/default_incoterm_id/default_payment_basis/default_payment_days/active）；🆕 新增 food_category Selection（seasoning/spread_breakfast/snack_biscuit/frozen_chilled/beverage）

code 欄位需 unique constraint；active 供封存舊品牌；food_category 與 food.regulation.profile 對應，建立作業單時自動帶入預設法規主檔

必要 M

@api.model create() 覆寫：建品牌時自動建對應 ir.sequence（prefix=code+'-', padding=3）並存入 sequence_id

⚠️ 不可用單一動態 prefix sequence；每品牌一個獨立 sequence 物件

必要 M

list / form / search 視圖（form 含 case smart button 計數）

必要 S

📋 trade.import.case — 進口作業單（協調器）

建立 trade.import.case 模型，繼承 mail.thread, mail.activity.mixin

所有欄位：name/title/brand_id/source/buyer_id/supplier_id/origin_country_id/incoterm_id/currency_id/forwarder_id/customs_broker_id/state/company_id

必要 L

brand_id onchange：帶入預設 forwarder/customs_broker/incoterm/payment_basis/payment_days

必要 S

name 取號：action_confirm() 內呼叫 brand_id.sequence_id._next()

draft 狀態下 name='/' 或暫存字串；confirm 才正式取號

必要 S

主狀態機 11 態 + cancel：draft/confirmed/production/ready/in_transit/arrived/customs/released/delivering/stored/done/cancel

必要 M

action_confirm()：驗證必填 → 取序號 → 鎖定 PO → 建船務骨架 → 算付款期限（Phase 2 完整實作，Phase 1 先算 tt_prepaid）

必要 M

_compute_can_release()（基礎版）：declaration_ids 全 released → True，否則 False；無報單也為 False

必要 S

action_release()：檢查 can_release，通過才轉 released；加 mail.message 紀錄

必要 S

action_store()：觸發關聯 stock.picking 收貨

🚫 超出範圍：收貨入倉屬倉後流程，本次不開發

超出範圍 M

ETD/ETA/ATD/ATA 欄位：related，取 shipment_ids 中最早船務

中 S

container_ids compute：彙整所有 shipment.container_ids（store=False）

中 S

🚢 trade.import.shipment + container — 船務與貨櫃

建立 trade.import.shipment（含 ir.sequence SHP/YYYY/00001）

欄位：name/case_id/transport_mode/master_bl_no/house_bl_no/bl_date/booking_no/vessel/voyage/pol_id/pod_id/forwarder_id/shipping_line_id/etd/eta/atd/ata/release_type/state

必要 M

建立 trade.import.container + trade.import.container.line

container: name/shipment_id/seal_no/container_type/free_days/demurrage_date/detention_date/per_diem_rate/overdue_days(compute)/demurrage_fee_est(compute)

必要 M

trade.import.port 港口主檔（輕量）：name/code/country_id/port_type

中 XS

Shipment list/form/calendar 視圖；Container list/form 視圖

必要 M

👥 res.partner 擴充 + 視圖 + 權限

res.partner 新增 Boolean 角色旗標：is_forwarder / is_customs_broker / is_shipping_line / is_trucking / is_inspection_agent / is_bonded_warehouse

必要 S

Case 多視圖：list / kanban（依 state 分欄）/ calendar（預設 eta）/ activity / form（含 statusbar）/ search

必要 L

ir.model.access.csv + ir.rule：group_trade_import_user / group_trade_import_manager + company_id record rule

必要 M

__manifest__.py 設定 depends: purchase, stock, account, stock_landed_costs, stock_delivery

必要 XS

Phase 2 完整貿易核心

報單/稅費計算、保稅倉、付款管理、到岸成本、各種精靈、報表。
交付標準：可完整跑通含保稅、D2 出倉、部分扣倉的完整流程；付款期限/匯款通知運作正常。

⚠️ 稅費計算注意：完稅價格（customs_value）≠ CIF（起岸價格），關稅基底必須用 declaration.line.customs_value，禁止直接用 cif_value 代入。

📑 trade.import.declaration — 報單（含稅費）

建立 trade.import.declaration（含 ir.sequence DCL/YYYY/00001）

欄位：name/declaration_type/transport_mode/case_id/customs_office/declaration_date/exchange_rate/clearance_channel/cif_value/duty_total/commodity_tax/vat_amount/trade_fee/warehouse_fee/demurrage_fee/edi_ref/state

必要 L

建立 trade.import.declaration.line（含 HS code onchange）

欄位：declaration_id/product_id/hs_code_id/statistic_no/inspection_no/import_permit_no/qty/net_weight/customs_value/duty_rate/tax_basis/duty_amount/commodity_tax_rate

必要 M

建立 trade.import.hs.code 稅則主檔

name(unique)/statistic_no/inspection_no/description/duty_rate/tax_basis/commodity_tax_rate/requires_food_inspection/requires_quarantine

必要 S

action_compute_taxes() 強制四步驟計算（關稅→貨物稅→營業稅→推貿費；推貿費未逾 NT$100 免徵）

必要 M

海關狀態彙整 _compute_customs_state()（depends: declaration_ids.state）

全 released→released；任一 inspecting→inspecting；有 declared→declaring；皆 draft→draft；無→none

必要 S

Declaration list/form 視圖（form 含 line 明細頁籤）

必要 M

💰 付款管理 + Cron 通知

_compute_payment_deadline() 完整六種 payment_basis

tt_prepaid→order_date；iv_days→invoice_date；bl_days→最早 bl_date（_earliest_bl_date()）；da_days→acceptance_date；split→多筆；credit_card→不計

必要 M

建立 trade.import.payment（case_id/pay_date/amount/currency_id/exchange_rate/is_prepaid/note）

case compute: paid_total = Σ payment_ids.amount；balance = 應付金額 − paid_total

必要 M

Cron job：匯款期限前 N 天建 mail.activity 通知財務

中 S

🏭 保稅倉 + 精靈 + 到岸成本

stock.location 擴充：l10n_tw_is_bonded（保稅倉）/ l10n_tw_is_hold（扣倉）Boolean

必要 XS

trade.import.bonded.release.wizard：依出倉數量產生保稅→已稅內部調撥 + 過帳稅費 + 產生 D2 報單（對應 J0322）

📌 v3.1 決策：延後至 Phase 3（條件式）— 僅保稅倉客戶才需要；Phase 2 只建 l10n_tw_is_bonded 欄位架構預留

延後P3 XL

trade.import.partial.release.wizard：勾選品項→部分 picking 放行至一般倉，其餘移至 is_hold 庫位；沿用原生 backorder

📌 v3.1 決策：延後至 Phase 3 尾端（條件式）— C3 查驗比例低；先用手動 picking；食品模組 C3 流程跑通後再做

延後P3 XL

stock.landed.cost 擴充：trade_import_case_id / brand_id / purchase_order_id / sales_channel 分析維度

成本類別：國外貨款/海運費/空運費/保險費/報關費/倉租/拖車費/檢驗費/抽驗費/櫃期費

必要 M

Cron job：貨櫃 D&D overdue_days > 0 建 activity 警示

中 S

建立 trade.import.recycle.declaration（period/case_id/line_ids/amount_total/state）；ir.sequence RCY/YYYY/00001

中 M

到岸成本分析報表（採購價 vs 實際到岸；依品牌/通路維度）；通關時效統計；報關行月結對帳

後期 L

🚫 trade.stock.reservation — 庫存保留單（超出本次範圍）

本次範圍以出關（released + 到岸成本）為終點，庫存保留屬倉後管理，後期另立需求。

建立 trade.stock.reservation 模型；ir.sequence RSV/YYYY/00001

超出範圍 M

available_qty compute + stock.quant 整合 + 視圖 + Cron + 揀貨警示

超出範圍 L

Phase 3 食品合規垂直（dobtor_food_import_inspection）

食品法規主檔、中文標版控、邊境報驗/自主送驗、抽驗回連、食品業者登錄、非追不可申報、放行閘門整合。
交付標準：食品進口案可完整跑通：報驗→抽驗→合格→放行；食藥署雙軌閘門驗證。
🚫 批號效期管制（stock.lot/FEFO/效期 Cron）超出本次範圍，已移除。

📌 模組依賴：dobtor_food_import_inspection depends on dobtor_trade_import + product_expiry。_compute_can_release 必須正確覆寫並聲明完整 @api.depends。

🌿 food.regulation.profile — 食品法規主檔

建立 food.regulation.profile

欄位：name/food_category/tfda_category/inspection_method/risk_level/shelf_life_days/requires_quarantine/required_document_type_ids

必要 S

🏷 product.template 食品擴充

product.template 新增食品合規欄位：is_food/name_en/factory_code/regulation_profile_id/default_hs_code_id/requires_quarantine/allergen_ids/nutrition_ids/storage_condition/date_mark_format/label_ids/label_print_mark

必要 M

食品物流欄位：pack_qty/inner_pack_note/piece_dimension/case_dimension/gross_weight_case/case_per_pallet/barcode_ids/product_state

中 M

下單防呆：product_state in ('discontinued','stop_import') domain 過濾；barcode_changed/renamed onchange 警語

必要 S

PO line 擴充：factory_quote_price / is_sample / label_method_override（onchange 帶預設、不回寫）

中 S

建立 food.allergen、food.nutrition.line 輔助模型

中 XS

📄 food.label — 中文標版本管控

建立 food.label（product_id/version/label_method/state/product_name_zh/ingredients_zh/net_weight/origin/manufacturer/importer/shelf_life/expiry_rule/allergen_info/nutrition/attachment_ids）

必要 M

label_preview compute：彙整中文標全文（含食品業者登錄字號/保險字號），供平台登錄複貼

中 S

approved 版本鎖定（write 限制），新需求另開版本（version+1）

必要 S

🔬 trade.import.inspection + sample — 查驗軌

建立 trade.import.inspection（inspection_type=border/self 決定是否進閘門）

欄位：name/inspection_type/case_id/declaration_id/inspection_agent_id/lab_id/channel/product_id/lot_id/import_permit_no/inspection_method/apply_deadline/amend_deadline/submit_date/sampling_date/release_date/report_email_date/requires_quarantine/quarantine_state/state

必要 L

建立 trade.import.inspection.sample（inspection_id/product_id/purchase_order_id/case_id/sample_date/sample_qty/lab_id/test_item_ids/result/report_attachment_ids）

必要 M

product.template 加 inspection_sample_ids compute（反查抽驗歷史）+ last_sampled_case_id + has_open_doc_gap

選此產品下單時，若 has_open_doc_gap 或最近抽驗 rejected → onchange 跳警語

中 M

Cron job：apply_deadline / amend_deadline 到期前建 mail.activity 提醒

必要 S

🚫 stock.lot 效期擴充 + FEFO（超出本次範圍）

批號效期管制、FEFO 揀貨策略、效期 Cron 均屬入倉後倉庫管理功能，超出本次出關範圍，後期再做。

stock.lot 新增：manufacture_date / supplier_lot / trade_import_case_id

超出範圍 S

Compute: shelf_life_days / remaining_days(UTC+8) / life_ratio / expiry_alert

超出範圍 M

Cron 效期預警 + lot list 著色 + pivot 二分之一庫存表 + FEFO removal_date

超出範圍 M

🔒 放行閘門覆寫 + 文件管控

trade.import.case 的 _compute_can_release 覆寫：super() → 篩 border → 食品合格 → 防檢署雙軌

@api.depends 必須完整宣告：declaration_ids.state / inspection_ids.state / inspection_ids.inspection_type / inspection_ids.quarantine_state / inspection_ids.requires_quarantine

必要 M

建立 trade.import.document（case_id/product_id/doc_type/attachment_id/issue_date/expiry_date/state）

中 S

文件到期 Cron + required_document_type_ids 缺件 → has_open_doc_gap = True → 閘門擋放行

中 M

🏢 食品業者登錄 + 非追不可申報

res.company / res.partner 新增：food_business_no（食品業者登錄字號）/ insurance_policy_no（保險字號）

中 XS

food.tracebook.report 精靈：依月份彙整進貨（採購/報單）+ 產品流向（下游出貨 lot 移動），匯出 CSV/XLSX（每月10日前申報義務）

必要 L

Phase 4 產品化 — Global Trade Suite

儀表板強化、CorPaaS 多租戶商品化；food.recall 完整流程（條件式，有需求才做）。
📌 v3.1：OCA spreadsheet 已移除；food.recall 從 Phase 3 移至此（Phase 3 只需 lot 回連即可手動追溯）

🔁 food.recall — 完整追溯回收（條件式）

📌 v3.1 決策：Phase 3 僅確認 stock.lot 有 trade_import_case_id 回連即可手動追溯；完整 food.recall 流程延後至此，且為條件式（有實際需求才開發）

建立 food.recall（name RCL/YYYY/00001 / reason / lot_ids / affected_picking_ids compute 向下 / source_case_id 向上 / state）

條件式 L

affected_picking_ids compute：由 lot_ids 追蹤所有下游出貨 stock.move（向下一步追溯）

條件式 M

📊 儀表板 + 互動報表 + 商品化

Kanban 儀表板強化（查驗抽中率/合格率、案件週期、付款逾期警示）

後期 L

OCA spreadsheet 互動報表整合（進口到岸成本分析、效期管制）

❌ v3.1 決策：移除出開發範圍— 無客戶需求；Odoo 原生 pivot + Excel export 已足夠

已移除 XL

CorPaaS 多租戶：以 company_id + record rule 控管；外部入口（貨代/報關行 Portal）資料邊界檢視

後期 XL

EDI 電子報關直連：只保留 edi_ref 欄位，不實作介接

📌 v3.1 決策：政府介接成本高且客戶未要求；欄位預留即可，Trade-Van 串接不在範圍

欄位預留 XS

⚠️ 注意關鍵技術風險

高風險項目

ir.sequence 每品牌獨立

不可用單一 sequence 動態換 prefix，每個品牌必須有自己的 ir.sequence 物件，建品牌時 create() 覆寫自動建立。

高風險 —

完稅價格 ≠ CIF

稅費計算必須以 declaration.line.customs_value 為關稅基底，絕對不能直接用 declaration.cif_value。

高風險 —

食品閘門 @api.depends 完整宣告

覆寫 _compute_can_release 時必須完整列出所有依賴欄位，漏列將造成閘門不觸發重算。

高風險 —

stock.lot.remaining_days UTC+8 偏移

Odoo 預設 UTC 儲存，remaining_days 計算今日必須轉換為 Asia/Taipei (UTC+8)，否則凌晨前後效期判斷會差一天。

高風險 —

Odoo 18 視圖語法

list tag 不加 string；條件顯隱用 invisible="expression" 非 attrs；確認 Odoo 18 Community 版本可用功能（部分 Enterprise 限定）。

中風險 —

stock_delivery 依賴（HS Code 欄位）

product.template.hs_code / country_of_origin 由 stock_delivery 模組提供，若客戶環境未安裝需確認。

中風險 —