物流报关

今天要做什么

物流报关是销售 → 跟单 → 仓库备货之后的出口窗口：装箱单（PL）记箱规、出货单（shipment）记船期、报关单（customs declaration）推清关。每日盯状态推进和延误，每周核在途船期，每月归集运费成本交会计。

每日

1. 进出口仪表盘看状态分布（按状态汇总 byStatus）与延误清单（delayedShipments——预计到港 eta 已过但未到 arrived「已到港」）。
2. 跟单确认备货完成 → 建装箱单（按销售订单），录箱规、确认。
3. 已订舱的订单 → 建出货单，加集装箱（整柜 FCL），关联装箱单，推状态「草稿 draft → 已订舱 booked → 已装柜 loaded」。
4. 货代 / 船公司回传报关底单 → 上传报关单（报关单号 declaration_number + PDF），清关状态从「待提交 pending」推到「已提交 submitted」。
5. 海关放行 → 推报关「已提交 submitted → 已放行 cleared」；推出货「已装柜 loaded → 已清关 customs_cleared → 已离港 departed」。
6. 到港订单 → 人工发邮件 / 企微通知客户提单号 bl_number + 预计到港 eta（系统无到港通知 action）。

每周

• 在途盘点：筛「在途 status=in_transit」，比对船公司实时船期，回填实际离港 actual_departure / 实际到港 actual_arrival。
• 游离装箱单补链：未关联任何出货单的装箱单在列表找出来，回到出货单详情做关联。
• 清理「已被拒 clearance_status='rejected'」的报关单——按退回原因重新上传新单（原单不可改）。

每月

• 运费成本归集：对账出货单的运费 freight_cost / 保费 insurance_cost / 其他费用 other_costs（币种字段 cost_currency）一并交会计手工入账——系统未自动做到岸成本（landed cost）。
• 报关归档：已「已放行 cleared」的报关单核对附件地址 file_url 是否存在、报关单号 declaration_number 是否有值，月底交税务备查。

权限红线（先看这 5 条）

• 非草稿（draft）的装箱单不能删——要改内容只能走「改版」生成新版本（版本号 version_number 递增、父装箱单 parent_packing_list_id 指向原单）。
• 非草稿的出货单不能删——「已订舱 booked」之后错了只能靠业务回退（让客户 / 货代重新走流程），状态机无取消 / 作废终态。
• 报关单上传后清关状态进入「已提交 submitted」就不可回到「待提交 pending」——「已放行 cleared」/「已被拒 rejected」都是终态，错了必须重传新单。
• 贸易术语 FOB（离岸价）/ CIF（到岸价）目前手填在备注 notes 里，系统未枚举化；写清楚别写口语（"CIF Los Angeles" 不要写 "C字头到洛杉矶"）。
• 运费 / 保费 / 杂费字段存在但不会自动入账——由会计按月手工做凭证；别自己改 freight_cost 后以为会计看到。

Quickstart — 日常核心任务

2.1 建装箱单并录箱规

跟单确认备货完成、销售订单已存在、唛头已在订单主数据。装箱单（PL，Packing List）是出货单的前置——没有装箱单出不了货。

1. 进「装箱单」列表点右上「新建」按钮打开对话框。（见图 ①）
2. 在订单下拉里选源销售订单——若订单没有唛头 shipping_mark，弹窗会显示琥珀色警告条，通知跟单补唛头再建。（见图 ②）
3. 填备注 notes（可选），点「新建」——系统生成「PL-YYYYMM-」开头的装箱单号并跳进详情页。
4. 进详情页的「明细」卡，按行点「编辑」——录箱数 cartonQty、每箱件数 piecesPerCarton、单箱毛重 grossWeightPerCarton、单箱净重 netWeightPerCarton、尺寸「长 lengthCm × 宽 widthCm × 高 heightCm」（单位 cm）。（见图 ③）
5. 保存行——系统实时算单行体积 totalCbm（= 长 × 宽 × 高 × 箱数 / 1,000,000），回填顶部四张汇总卡（箱数 / 毛重 / 净重 / 体积）。
6. 全部明细录完、复核无误 → 头部点「确认」按钮（仅草稿可点），弹窗二次确认。

何时不该做：订单无唛头时别硬建——定制家具厂客户都看唛头识货，漏唛头货到港客户收不上对不上；回头让销售在订单 shipping_mark 字段补完。明细未录齐不要点「确认」——「已确认 confirmed」之后改内容只能改版，会多一版 v2 让货代混淆哪份是最新。

观测信号：

1. 装箱单列表顶部出现新行，单号 PL- 前缀，状态「草稿」。
2. 详情页汇总卡（箱数 / 毛重 / 净重 / 体积 CBM）数字随行内编辑实时刷新。
3. 确认后状态徽标从「草稿」变「已确认」，确认 / 删除按钮消失，只剩「改版」按钮。

技术追溯：装箱单号 packing_lists.packing_list_number 自增；明细体积 packing_list_items.total_cbm = carton_qty × length_cm × width_cm × height_cm / 1,000,000；packing_lists.status='confirmed'、version_number=1。

系统动作：createPackingList、updatePackingListItem、confirmPackingList、getOrdersForSelect、getPackingListData

2.3 新建出货单（整柜 FCL / 拼柜 LCL）

订舱信息到手：提单 BL 号 / 船名航次 / 装港 / 目的港 / 预计离港 ETD / 预计到港 ETA 都齐，且关联的装箱单已「已确认 confirmed」。

1. 进「出货单」列表点右上「新建」按钮。（见图 ①）
2. 选运输类型：整柜选「fcl（Full Container Load）」，拼箱选「lcl（Less than Container Load）」；拼箱不挂集装箱、只在装箱单层管箱规。（见图 ②）
3. 选销售订单（可选，留空用于多单合票）、填提单号 blNumber、船公司 shippingLine、船名 vesselName、航次 voyageNumber。
4. 填装港 portOfLoading、目的港 portOfDestination、预计离港 etd / 预计到港 eta。（见图 ③）
5. 填货代名称 forwarderName / 货代联系人 forwarderContact；贸易术语 FOB（离岸价）/ CIF（到岸价）写在 notes（未枚举化，见权限红线第 4 条）。
6. 点「新建」——系统生成 SHP- 前缀出货号、跳到详情页、状态「草稿 draft」。

何时不该做：提单（BL）号为空时禁止建出货单——提单号是客户提货凭证，遗漏到港客户凭什么拿货。装港 / 目的港不能口语化（写「上海→洛杉矶」会让报关单匹配不到），严格按货代给的英文港口名（Shanghai / Los Angeles）。FOB / CIF 写在 notes 时写全称和目的港，日后核对运费归属才对得上。

观测信号：

1. 出货单列表顶部出现新行，单号 SHP- 前缀，状态「草稿」，类型徽标显「整柜 FCL」/「拼柜 LCL」。
2. 详情页头部显示提单号（monospace 字体）与类型徽章。
3. 时间线卡显示「草稿」为当前节点。

技术追溯：出货单号 shipments.shipment_number 自增；提单号 shipments.bl_number、船名 shipments.vessel_name、预计离港 shipments.etd、预计到港 shipments.eta 回写；运输类型 shipment_type ∈ fcl | lcl；status='draft'。

系统动作：createShipment、updateShipment、getOrdersForSelect、getShipmentData

2.4 加集装箱（FCL 整柜专用）

整柜出货且码头已回柜号 / 铅封号。拼柜 LCL 跳过——拼箱无独立柜号，装柜信息在装箱单层。

1. 进出货单详情，下拉到「集装箱」卡，右上点「新增集装箱」。
2. 行内录柜号 containerNumber（如 MSCU7788990）、柜型 containerSize（20GP / 40GP / 40HC）、铅封号 sealNumber、装柜日期 loadingDate。（见图 ①、② ③ ④）
3. 点行末绿色勾确认保存——新行进入上方列表。
4. 多柜合一票：重复上述动作，每柜一行；铅封号必须与码头出具的一致。
5. 录错时点行内铅笔编辑，或垃圾桶删除（弹窗二次确认）。

何时不该做：拼柜 LCL 单点「新增集装箱」会看到提示「拼箱无独立柜」——别硬录假柜号，到港报关时海关查不到会扣柜。铅封号录错或漏录——到港码头铅封完整性核对失败会导致延放，赔偿客户滞箱费。「已送达 delivered」状态的出货单集装箱卡只读，要改必须回到业务流找原因。

观测信号：

1. 集装箱卡描述从「无集装箱」变 「N 个集装箱」。
2. 新行显示柜号（等宽字体）/ 柜型 / 铅封 / 装柜日期。
3. Toast 弹出「集装箱已添加」。

技术追溯：集装箱表 shipment_containers 新增一行，字段 shipment_id、柜号 container_number、柜型 container_size、铅封号 seal_number、装柜日期 loading_date。

系统动作：addContainer、updateContainer、removeContainer

2.5 关联装箱单到出货单

装箱单已「已确认 confirmed」，出货单已「草稿 draft」或「已订舱 booked」；多个装箱单可挂同一出货单（多订单合票）。

1. 出货单详情页下拉到「关联装箱单」卡。（见图 ①）
2. 点「关联装箱单」按钮展开装箱单下拉，选要挂的装箱单号（列表已滤掉已关联和非「已确认」的装箱单）。
3. 点「确认关联」——装箱单出现在已关联列表；要解除点装箱单行末「取消关联」。
4. 多个装箱单同装一票：重复选、关联，已关联装箱单在卡内分为"已关联 / 可关联"两区。

何时不该做：草稿的装箱单不能关联——只有「已确认 / 已发」的装箱单在下拉里。关联错出货单后发现装箱单归属变了——先解除再重关联，别让货代用错版本装箱单做清关。

观测信号：

1. 「关联装箱单」卡的「已关联」区出现装箱单号行。
2. 装箱单列表里该装箱单行显示已挂靠的出货单号（点击可跳转）。
3. 关联 / 取消关联都无企微推送，纯内部数据动作。

技术追溯：联表 shipment_packing_lists 新增 / 删除一行（复合键 shipment_id + packing_list_id）。

系统动作：linkPackingList、unlinkPackingList、getPackingListsForLink

2.6 推进出货状态（草稿 → 已送达）

按业务节点推状态：订舱 / 装柜 / 报关放行 / 离港 / 在途 / 到港 / 派送。每次推进都有审计留痕。

1. 出货单详情页头部右侧看「推进状态」按钮，按钮文案含下一节点名（如「推进状态: 已订舱」）。（见图 ①）
2. 点击弹出二次确认，写清楚 from → to 的转换。（见图 ②）
3. 点「推进状态」确认——系统按固定序列推进：「草稿 draft → 已订舱 booked → 已装柜 loaded → 已清关 customs_cleared → 已离港 departed → 在途 in_transit → 已到港 arrived → 已送达 delivered」。
4. 实际离港后回填 actual_departure，实际到港后回填 actual_arrival（在详情页「港口 / 日期」卡编辑）。
5. 到港后人工发邮件 / 企微通知客户提单号 + 预计到港——系统无到港通知 action。

何时不该做：不要直接改 DB status——审计日志缺失违反合规；工作流无法回退的节点推过去就是一条单向路。「已清关 customs_cleared」之前推「已离港 departed」会让报关侧对不上（报关未放行但船已离港记录），让会计查账发现时间线错乱。到港后客户未付尾款禁止推「已送达 delivered」——派送后无法追回款项。

观测信号：

1. 头部状态徽标按序列变动（草稿 → 已订舱 → 已装柜 → …）。
2. 时间线卡高亮当前节点并点亮前序节点时间戳。
3. 审计日志卡新增一行（操作人 / 时间 / from / to）。
4. Toast 提示「状态已更新」。

技术追溯：shipments.status 在 draft | booked | loaded | customs_cleared | departed | in_transit | arrived | delivered 间单向推进；审计表 workflow_audit_trail 按 from_status / to_status 新增；shipments.actual_departure / actual_arrival 离港到港后回填。

系统动作：updateShipmentStatus、executeShipmentTransitionAction、getShipmentWorkflowState、getShipmentAvailableTransitions、getShipmentAuditTrail、updateShipment

2.7 上传报关单并推进清关状态

货代 / 海关代理回传报关底单 PDF 或图片；出货单已在「已装柜 loaded」附近节点（装柜完成等待清关）。

1. 进「报关单」列表点右上「上传」按钮打开对话框。（见图 ①）
2. 选出货单 ID shipmentId（下拉里是全部可关联出货单），填报关单号 declarationNumber、报关日期 declarationDate，上传 PDF / JPG / PNG 文件（有大小上限，页面提示）。（见图 ②）
3. 点「上传」——系统把文件存到 Storage，写附件地址 file_url / 附件路径 file_path，记录进入「待提交 pending」状态。
4. 海关受理后，在报关列表找到该行点行末「...」菜单 → 选「已提交」（待提交 pending → 已提交 submitted）。（见图 ③）
5. 海关放行 → 同菜单选「已放行」（已提交 submitted → 已放行 cleared）；被退 → 选「已被拒」（已提交 submitted → 已被拒 rejected）——两者都是终态。

何时不该做：「已放行 cleared」/「已被拒 rejected」是终态——发现错了不能「回到待提交」，必须删除原报关单（仅待提交可删）或新建一条。上传前确认 declaration_number 与货代文件完全一致——错一位数字海关查验失败、出货滞关。附件超出允许大小（页面显示上限）会报错，用 PDF 压缩工具先瘦身。

观测信号：

1. 报关单列表顶部出现新行，declaration_number 显等宽字体，状态徽标「待提交」。
2. 文件列显示「下载文件」链接。
3. 关联出货单列有可点击链接回出货单详情页。
4. 「相关文档」卡（在出货单详情）列出报关单。

技术追溯：报关单号 customs_declarations.declaration_number、清关状态 customs_declarations.clearance_status ∈ pending | submitted | cleared | rejected；file_url / file_path 指向 Storage。

系统动作：uploadCustomsDeclarationAction、updateClearanceStatusAction、deleteCustomsDeclarationAction、getCustomsDeclarationsData、getShipmentsForSelect

2.8 登记运费 / 保费 / 杂费（交会计手工入账）

货代开账或船公司月结到手，按实际金额回写出货单的成本字段。会计依此手工做到岸成本（landed cost）凭证——系统不会自动生成。

1. 打开目标出货单详情页，下拉到成本卡区（运费 / 保费 / 杂费 / 合计）。（见图 ①）
2. 在成本卡点「编辑」打开表单——录入运费 freightCost、保费 insuranceCost、杂费 otherCosts、币种 costCurrency。币种要和账单币种一致，不做自动换算。
3. 保存后成本卡合计即时刷新；若月末前多笔账单到手，依次更新（覆盖式）。
4. 月初导出出货单成本明细给会计，由会计在 /dashboard/accounting/journal-entries 手工建到岸成本凭证并分摊到销售订单明细 sales_order_items（代码未自动实现）。

何时不该做：把船公司发票未到部分估算填入不要做——会计拿到真实发票后两次录入对不上账。币种混填（USD 运费填在 CNY 保费旁）会让成本卡汇总错误，且会计无法识别跨币种汇总。改成本字段后必须通知会计重新过账——系统不会触发凭证自动刷新。

观测信号：

1. 出货单详情成本卡「合计」= 运费 + 保费 + 杂费。
2. 币种徽标显示 USD / CNY 等。
3. 会计凭证表 journal_entries 里并不会自动新增凭证——须会计手工补。

技术追溯：运费 shipments.freight_cost / 保费 insurance_cost / 杂费 other_costs / 币种 cost_currency；系统未自动写 journal_entries，亦未分摊到 sales_order_items。

系统动作：updateShipment、getShipmentData

上下游交接契约

物流报关接跟单和仓库的交付，把货推向客户，把运费推给会计。上游缺字段装箱单建不出、下游缺通知客户等不到货。

异常回滚

误操作先不要改 DB。按下表选对应入口——状态机无取消 / 作废终态，非草稿单据只能靠「改版」或重建。

进阶功能

相关业务场景

物流报关在 6 大跨角色场景里参与 1 条核心链路（出货阶段），另外在到岸成本归集和项目制订单里作为桥接。

1. 标准成单流（询盘 → 报价 → 订单 → 发货 → 开票）： 物流在末尾出货阶段接力——建装箱单 → 确认装箱单 → 建出货单 → 加集装箱 → 关联装箱单 → 推状态「已订舱 → 已装柜 → 已清关 → 已离港 → 在途 → 已到港 → 已送达」；同步上传报关单推清关。 → 场景详解
2. 定制家具项目流： 项目制订单分批发货 → 多票装箱单（按拆单 split_order_id 拆）；超规家具装箱单改版迭代（尺寸常变）；多柜合一票出货单，每柜独立柜号 / 铅封号。 → 场景详解
3. 回款流：物流不参与——回款由销售 / 出纳 / 会计处理。但「已到港」后必须及时通知客户提单号，帮助销售催尾款。 → 场景（了解即可）
4. 采购付款流：物流不参与——采购付款由采购 / 出纳 / 会计处理。 → 场景（了解即可）
5. 月结流： 物流月初归集运费 / 保费 / 杂费交会计手工入账；报关单归档（「已放行」的附件地址 + 报关单号完整）做税务备查。 → 场景详解
6. 报销审批流：物流作为申请人走 /dashboard/expenses（出差 / 货代垫付报销），非核心动作。 → 场景（作为申请人）

外部协作入口

• /dashboard/export/dashboard — 出口仪表盘（状态分布 + 延误清单），早会必看。
• /dashboard/sales/orders — 上游销售订单列表，确认唛头 / 币种 / 交期。
• /dashboard/sales/delivery-notes — 上游送货单（仓库出库凭证），对照实发数量录装箱单箱规。
• /dashboard/accounting/journal-entries — 下游会计到岸成本入账查验。
• /dashboard/wecom — 企微推送（暂无到港 SOP，手工发群通知）。
• /dashboard/settings/email — 外贸邮件网关（发提单号 + 预计到港给客户）。
• /dashboard/manual — 系统内置使用手册（补充参考）。

权限与范围

看得到什么（RLS 边界）

• 当前组织（organization_id）下的所有出货单 shipments / 集装箱 shipment_containers / 装箱单 packing_lists / 装箱明细 packing_list_items / 报关单 customs_declarations。
• 可读销售订单 sales_orders / 客户 customers（建装箱单 / 出货单时选单用），不可改订单 / 客户。
• 不可见：purchasing/* / accounting/*（除会计凭证查账只读）/ hr/*。

核心概念

• organization_id — 租户隔离键。所有出货单 / 装箱单 / 报关单带此字段，跨租户通过 RLS 隔离。
• book_id — 账套隔离键；运费 / 保费成本属于财务表，切账套后到岸成本分布可能变。
• 工作流引擎（src/services/workflow-engine.ts）——出货单和装箱单的状态机统一走该引擎；审计日志强制留痕。清关状态在 service 层有 VALID_CLEARANCE_TRANSITIONS 硬约束（非工作流）。

术语表

出货单 shipment

shipments.shipment_number（SHP- 前缀）

装箱单 PL (Packing List)

packing_lists.packing_list_number（PL- 前缀）

报关单 customs declaration

customs_declarations.declaration_number（货代手填）

提单 BL (Bill of Lading)

shipments.bl_number（字段，无 PDF 生成）

信用证 LC (Letter of Credit)

无专用单据表，单据走文件附件上传（Gap）

柜号 container number

shipment_containers.container_number

铅封号 seal number

shipment_containers.seal_number

柜型 container size

container_size（20GP | 40GP | 40HC）

唛头 shipping mark

sales_orders.shipping_mark（订单带入装箱单）

船名 / 航次

vessel_name / voyage_number

船公司 shipping line

shipping_line（MSC / Maersk 等，手填字符串）

货代 forwarder

forwarder_name / forwarder_contact

装港 / 目的港 port of loading / destination

port_of_loading / port_of_destination（手填，英文港口名）

预计离港 ETD / 预计到港 ETA

etd / eta；实际值 actual_departure / actual_arrival

箱数 / 箱规

carton_qty / pieces_per_carton / length_cm × width_cm × height_cm

毛重 / 净重 / 体积 CBM

total_gross_weight / total_net_weight / total_cbm（CBM = 长×宽×高×箱数 / 1,000,000）

出货类型 enum

fcl（整柜 Full Container Load）/ lcl（拼箱 Less than Container Load）

出货状态 enum

draft 草稿 | booked 已订舱 | loaded 已装柜 | customs_cleared 已清关 | departed 已离港 | in_transit 在途 | arrived 已到港 | delivered 已送达

装箱单状态 enum

draft 草稿 | confirmed 已确认 | shipped 已发

清关状态 enum

pending 待提交 | submitted 已提交 | cleared 已放行 | rejected 已被拒（后两者终态）

贸易术语 Incoterm

FOB（离岸价）/ CIF（到岸价）/ EXW（工厂交货）（未枚举化，手填在 shipments.notes）

运费 / 保费 / 杂费

freight_cost / insurance_cost / other_costs + 币种 cost_currency

到岸成本 Landed cost

运费 + 保费 + 杂费之和，需会计手工过账到 journal_entries（未自动）

装箱单改版核心动作

revisePackingList（version_number+1、parent_packing_list_id）

出货状态推进动作

updateShipmentStatus / executeShipmentTransitionAction

常见问题