diff --git a/web-admin/src/utils/pl-plan-contract-product.ts b/web-admin/src/utils/pl-plan-contract-product.ts
new file mode 100644
index 000000000..409ddae03
--- /dev/null
+++ b/web-admin/src/utils/pl-plan-contract-product.ts
@@ -0,0 +1,26 @@
+/** 从合同明细行收集 CRM productId */
+export function collectContractProductIds(
+  products?: Array<{ productId?: string | null }> | null
+): string[] {
+  const ids: string[] = []
+  const seen = new Set<string>()
+  for (const row of products || []) {
+    const id = String(row?.productId || '').trim()
+    if (!id || seen.has(id)) continue
+    seen.add(id)
+    ids.push(id)
+  }
+  return ids
+}
+
+/** 保留 productId 落在 allowed 内的装货行；allowed 为空则全部移除（换合同且新合同无产品） */
+export function filterProductsByAllowedProductIds<T extends { productId?: string | null }>(
+  products: T[],
+  allowedProductIds: string[]
+): T[] {
+  const allowed = new Set(
+    (allowedProductIds || []).map((id) => String(id).trim()).filter(Boolean)
+  )
+  if (!allowed.size) return []
+  return (products || []).filter((row) => allowed.has(String(row.productId || '').trim()))
+}