Cin7 集成与状态映射¶

本文档解释了采购订单如何从 Cin7（采购订单数据的源头）流向 PO 管理应用程序，以及 Cin7 的状态/阶段模型如何映射到应用的内部状态系统。

概览¶

Cin7 是公司的 ERP/库存系统。采购订单在 Cin7 中创建和管理。每晚通过 Airflow DAG 将 Cin7 API 中的采购订单数据同步到 Azure SQL 数据库。PO 管理应用随后在同步的数据之上添加了自己的工作流层。

[!IMPORTANT] 应用不会写回 Cin7。所有工作流操作（批准、拒绝、发货等）仅更新应用自己的状态列（app_po_status_id、app_po_status）。Cin7 仍然是采购订单行项目数据、日期和供应商信息的原始记录系统。

Cin7 数据模型与应用数据模型¶

Cin7 使用两个独立的字段跟踪采购订单：

Cin7 字段	含义	示例值
`status`	高级采购订单审批状态	`APPROVED`, `VOID`
`stage`	履行/发货阶段	`NULL`, `New`, `In Transit`, `Delivered`, `Received`

应用将这两个字段合并为一个单一状态 ID (app_po_status_id)，用于驱动整个工作流。

状态映射表¶

下表显示了每个有意义的 Cin7 status + stage 组合如何映射到应用状态。此映射在初始夜间同步期间应用，也通过阶段 3 回填迁移应用。

Cin7 `status`	Cin7 `stage`	应用状态 ID	应用状态标签	备注
`APPROVED`	`NULL` / `New`	100	New	采购订单刚到达，供应商尚未采取行动
`APPROVED`	`In Transit`	500	Shipped	同步时货物已在途中
`APPROVED`	`Delivered`	600	Delivered	同步时已到货
`APPROVED`	`Received`	600	Delivered	Cin7 交替使用这两个术语
`VOID`	(任意)	(隐藏)	—	通过 SQL 过滤器完全从应用中排除

[!NOTE] 为什么 Cin7 显示 "In Transit" 而应用显示 "Shipped"？

Cin7 的 stage = 'In Transit' 意味着货物正处于物理运输途中 —— 这就是应用所称的 Shipped (状态 ID 500)。应用的术语已与团队的内部语言对齐（“已发货”对于经理确认交付更清晰）。仪表板上的 KPI 卡片标为 "Shipped" 以匹配此项。

Airflow 每晚同步行为¶

Airflow DAG 每晚对 cin7_purchase_orders_headers 执行 MERGE 操作：

匹配行（采购订单已存在）：更新 Cin7 来源的列（日期、供应商名称、行项目等）。应用拥有的列永远不会被覆盖（见下表）。
新行（数据库中尚无采购订单）：插入新行，默认 app_po_status_id = 100 (New)，除非 Cin7 stage 指示了更高级的状态（见上述映射）。

应用拥有的列（受同步保护）¶

这些列由应用拥有，Airflow 永远不会触碰：

列名	用途
`app_po_status_id`	当前工作流状态
`app_po_status`	状态标签（为了查询性能而去规范化）
`vendor_reply_xfd`	供应商建议的离厂日期
`vendor_reply_factory`	供应商建议的工厂
`vendor_reply_comment`	供应商备注
`has_pending_changes`	供应商是否有未保存的编辑
`vendor_confirmed_at`	上次供应商提交的时间戳
`manager_action_at`	上次经理操作的时间戳
`manager_rejection_reason`	拒绝反馈
`container_number`	集装箱号
`tracking_number`	物流单号
`is_locked`	采购订单是否已锁定无法编辑
`is_fit_sample_approved`	FIT 样品确认状态
`is_cfm_sample_approved`	CFM 样品确认状态

VOID 采购订单处理¶

Cin7 使用 status = 'VOID' 标记已取消/作废的采购订单。应用按下述方式处理：

所有 API 查询都包含过滤器 ISNULL(h.status, '') <> 'VOID'，因此 VOID 采购订单在 UI（采购订单列表、仪表板、详情页）中完全不可见。
VOID 采购订单不会从数据库中删除 —— 它们保留用于审计。
阶段 3 迁移脚本还将 VOID 行的 app_po_status_id 设置为 900 (Cancelled) 以确保数据完整性，即使它们从未显示。

状态颜色参考¶

为了快速参考，每个应用状态都有在整个 UI 徽章中使用的唯一颜色：

状态	ID	徽章颜色
New	100	蓝色 (`#0078d4`)
Requires Revision	150	红色 (`#c50f1f`)
Pending Approval	200	橙色 (`#ca5010`)
Confirmed	300	绿色 (`#107c10`)
In Production	400	绿色 (`#0e7a0d`)
Shipped	500	紫色 (`#8764b8`)
Delivered	600	蓝绿色 (`#038387`)
Cancelled	900	灰色 (`#797775`)