落地并存测服全端：智能体 Graph/路由、后台切 8180、主账与部署脚本齐备，便于线上重发与验收。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-13 21:15:58 +08:00
parent 0eb1adecc8
commit 8103b3b651
143 changed files with 8968 additions and 277 deletions
@@ -1,20 +1,15 @@
 # 字段合同（contracts）

-本目录存放与现网等价的字段 / 字典投影 JSON。智能体写字段校验、主账写 TMS 字典投影前，**必须**以本目录真文件为准。
+本目录存放字段 / 字典投影 JSON。智能体写字段校验、主账写 TMS 字典投影前，**必须**以本目录**正式**文件为准。

-## 需要从现网拷贝的文件
+## 当前状态

-| 文件名 | 用途 |
+| 文件名 | 状态 |
 |---|---|
-| `inquiry-required-fields-v1.json` | 询价必填与条件激活合同 |
-| `tms-dictionary-projection-v2.json` | TMS 字典 EXACT_ONLY 投影合同 |
+| `inquiry-required-fields-v1.json` | 正式（已从现网对照源拉入） |
+| `tms-dictionary-projection-v2.json` | 正式（已从现网对照源拉入） |
+| `*.PLACEHOLDER.json` | 历史占位，加载器优先正式文件 |

-骨架阶段仅放占位文件（见同名 `*.PLACEHOLDER.json`）。拿到现网拷贝后：
+备份另见 `_ref/prod-pull/contracts/`（勿提交密钥目录）。

-1. 覆盖为正式文件名（去掉 `.PLACEHOLDER`）。
-2. 再实现字段校验 / 字典投影；没读真 JSON 不准写校验逻辑。
-
-## 禁止
-
- 不要把合同只记在提示词里而不更新本目录。
- 不要在代码里硬编码另一套字段名。
+代码加载：`agent.schema.load_contract` / `require_formal_contract`。
@@ -1,5 +1,5 @@
 {
-  "_comment": "占位：请用现网 inquiry-required-fields-v1.json 覆盖为同名正式文件后再写字段校验。骨架阶段禁止依赖本文件做业务判断。",
+  "_comment": "占位：正式合同由产品/仓库内审交付到同名 inquiry-required-fields-v1.json。禁止从现网服务器或现网发布目录拷贝。骨架阶段禁止依赖本文件做业务判断。",
  "schemaVersion": "v1-placeholder",
  "fields": []
 }
@@ -0,0 +1,102 @@
+{
+  "schema_version": 1,
+  "contract_id": "INQUIRY_REQUIRED_FIELDS_V1",
+  "status": "APPROVED",
+  "approved_by": "user",
+  "approved_at": "2026-08-30T02:30:00+08:00",
+  "requirement_id": "REQ-20260830-030",
+  "last_amended_requirement_id": "REQ-20260831-009 revision 1",
+  "stage_semantics": {
+    "PRICE_REQUIRED": "首次查价必须满足的字段；只按已确认的业务线和二级类型激活。",
+    "COLLAB_REQUIRED": "首次查价字段保持有效后，进入协同阶段追加的必填字段。"
+  },
+  "value_validity": {
+    "scope": "ONLY_CURRENTLY_ACTIVATED_REQUIRED_FIELDS",
+    "completion_rule": "TRIMMED_NON_EMPTY_VALUE_IS_PRESENT",
+    "content_validation": "DISABLED_LOCAL_VALUE_FORMAT_AND_COMPATIBILITY_VALIDATION_EXCEPT_DECLARED_MACHINE_TYPES",
+    "accepted_user_values": "当前作用域字段收到任意非空值即视为已采集；本地不得按单位、车型、布尔文案、别名、格式或封闭枚举拒绝。SEA箱型箱量保持一个原始业务字段，结构化containerItems只由DeepSeek B投影；投影不可用时由TMS查询边返回1003。",
+    "inactive_field_display_not_a_fact": "未激活字段摘要中的-只表示不适用，不作为字段值进入完整性校验。"
+  },
+  "model_scopes": {
+    "PRICING": "DeepSeek B只接收本合同pricing_required中当前激活字段、必要路由身份和optional_projection_fields中当前业务线允许的可选事实；缺项只按pricing_required计算。",
+    "COLLABORATION": "DeepSeek B接收同一票不可变销售原话、已确认运输模式和陆运二级类型，只返回当前激活协同字段；结果保存到独立快照。点击协同时必须重新执行本范围。"
+  },
+  "pricing_required": {
+    "SEA": {
+      "always": ["起运港", "目的港", "品名", "货量", "整柜或拼柜", "箱型箱量"],
+      "display_names": {"货量": "货物数量"}
+    },
+    "AIR": {
+      "always": ["起运港", "目的港", "品名", "件数", "毛重", "体积", "包装方式"],
+      "display_names": {"起运港": "起运地", "目的港": "目的地", "毛重": "重量(KG)", "体积": "体积(CBM)", "包装方式": "包装类型"}
+    },
+    "LAND": {
+      "国内运输拼车": {
+        "always": ["起运港", "目的港", "品名", "体积", "毛重"],
+        "display_names": {"起运港": "始发站", "目的港": "目的地", "品名": "货物品名", "体积": "体积(CBM)", "毛重": "重量(KG)"}
+      },
+      "国内运输整车": {
+        "always": ["起运港", "目的港", "品名", "车型数量"],
+        "display_names": {"起运港": "始发站", "目的港": "目的地", "品名": "货物品名", "车型数量": "车型/数量"}
+      },
+      "跨境集拼": {
+        "always": ["起运港", "目的港", "品名", "体积", "毛重"],
+        "display_names": {"起运港": "始发站", "目的港": "目的地", "品名": "货物品名", "体积": "体积(CBM)", "毛重": "重量(KG)"}
+      },
+      "跨境整车": {
+        "always": ["起运港", "目的港", "品名"],
+        "display_names": {"起运港": "起运地", "目的港": "目的地", "品名": "货物品名"}
+      },
+      "中港": {
+        "always": ["起运港", "目的港", "品名", "车型数量"],
+        "display_names": {"起运港": "始发站", "目的港": "目的地", "品名": "货物品名", "车型数量": "车型/数量"}
+      }
+    }
+  },
+  "optional_projection_fields": {
+    "LAND": ["件数", "毛重", "体积", "时效要求", "cargo_items"],
+    "semantics": "这些字段不是首次查价必填项；只有销售原话明确出现且DeepSeek B给出逐项证据时才保真保存。代码不得从原始自然语言猜测，只可对模型结构化cargo_items做单位与算术投影。"
+  },
+  "collaboration_required": {
+    "SEA": ["贸易条款", "货好时间", "HS编码", "是否含油", "是否含电", "是否含磁"],
+    "AIR": ["是否含电", "是否含磁"],
+    "LAND": {
+      "国内运输整车": ["时效要求", "客户名称", "货值", "包装方式", "是否危险品"],
+      "国内运输拼车": ["时效要求", "客户名称", "包装方式", "货值", "是否危险品"],
+      "跨境整车": ["时效要求", "客户名称", "HS编码", "车型数量", "贸易条款", "货值", "包装方式", "是否危险品"],
+      "跨境集拼": ["时效要求", "客户名称", "HS编码", "贸易条款", "包装方式", "是否危险品"],
+      "中港": {"same_as": "跨境整车"}
+    }
+  },
+  "collaboration_value_contracts": {
+    "enforcement": "SUGGESTION_ONLY_USER_TYPED_NON_EMPTY_VALUE_IS_ACCEPTED",
+    "LAND": {
+      "时效要求": {
+        "国内运输整车": ["普件（常用线路/常规车型）", "普件（非常用线路/临时线路/特种车型）", "急件"],
+        "国内运输拼车": ["普件（常用线路/常规车型）", "普件（非常用线路/临时线路/特种车型）", "急件"],
+        "跨境整车": ["普件（中港、东南亚常用线路/常规车型）", "普件（中亚、中欧、东南亚涉及国内+国外段）", "普件（中亚、中欧、东南亚涉及境外段清派等特殊要求）", "急件"],
+        "跨境集拼": ["普件（中港、东南亚常用线路/常规车型）", "普件（中亚、中欧、东南亚涉及国内+国外段）", "普件（中亚、中欧、东南亚涉及境外段清派等特殊要求）", "急件"],
+        "中港": {"same_as": "跨境整车"}
+      }
+    }
+  },
+  "legacy_read_aliases": {
+    "时效要求": ["服务档位", "货物类型", "服务类型", "普件/急件"]
+  },
+  "semantic_ownership": {
+    "owner": "DeepSeek B",
+    "must_output": ["raw_value", "normalized_value", "evidence", "segment_binding", "cargo_binding"],
+    "forbidden_local_capabilities": ["semantic_regex", "alias_inference", "content_normalization", "semantic_fallback", "value_format_rejection", "closed_enum_value_rejection"]
+  },
+  "machine_types": {},
+  "deterministic_invariants": [
+    "SEA货物数量与AIR件数是不同字段；自然语言数量落入哪个字段只能由DeepSeek B依据已解析业务线决定。",
+    "SEA箱型箱量是一个首次查价必填字段，整柜/FCL和拼柜/LCL均激活；任意非空原值完成采集。",
+    "SEA箱型箱量原值到containerItems.type/quantity的结构化投影只由DeepSeek B输出，本地不得拆分、去单位或限制格式。",
+    "DeepSeek B不能形成可用containerItems时不得重新补问箱型或箱量，由item投影或TMS查询边返回业务1003。",
+    "AIR包装类型使用内部字段包装方式承载，但只在AIR首次查价作用域激活。",
+    "尺寸原文不得在本地代码中用正则、别名或关键词解析为体积(CBM)；DeepSeek B已输出带证据的结构化cargo_items后，代码可按单位做确定性乘法和加总并投影总体积。",
+    "协同字段只能在对应基础查价字段满足后追加，不得反向扩大首次查价必填。",
+    "代码只校验字段键作用域、JSON结构、非空、条件激活、权限、版本与幂等；字段内容格式、规范性和是否适合报价由模型与下游报价服务负责。"
+  ]
+}
@@ -1,5 +1,5 @@
 {
-  "_comment": "占位：请用现网 tms-dictionary-projection-v2.json 覆盖为同名正式文件后再写字典投影。骨架阶段禁止依赖本文件做业务判断。",
+  "_comment": "占位：正式合同由产品/仓库内审交付到同名 tms-dictionary-projection-v2.json。禁止从现网服务器或现网发布目录拷贝。骨架阶段禁止依赖本文件做业务判断。",
  "schemaVersion": "v2-placeholder",
  "projections": []
 }
@@ -0,0 +1,163 @@
+{
+  "schema_version": 2,
+  "contract_version": "TMS-DICTIONARY-PROJECTION-V2",
+  "supersedes": ".project-control/architecture/tms-dictionary-projection-v1.json",
+  "required_fields_contract_ref": ".project-control/architecture/inquiry-required-fields-v1.json",
+  "business_semantics_owner": "DEEPSEEK_B",
+  "protocol_projection_owner": "JAVA_TMS_ADAPTER",
+  "last_amended_requirement_id": "REQ-20260831-009 revision 1",
+  "matching_policy": {
+    "mode": "EXACT_ONLY",
+    "allowed_keys": ["source_code", "source_name"],
+    "allow_regex": false,
+    "allow_fuzzy": false,
+    "allow_alias_inference": false,
+    "allow_suffix_trimming": false,
+    "allow_last_write_wins": false,
+    "multiple_distinct_values": "AMBIGUOUS",
+    "zero_values": "UNMAPPED",
+    "air_package_fallback": {
+      "target_field": "packageType",
+      "value": 1,
+      "meaning": "全部",
+      "preserve_raw_source": true
+    }
+  },
+  "catalog_statuses": [
+    "PROJECTABLE",
+    "AMBIGUOUS_NAME_GROUP",
+    "SOURCE_VALUE_MISSING",
+    "REFERENCE_ONLY"
+  ],
+  "resolution_statuses": [
+    "RESOLVED",
+    "UNMAPPED",
+    "AMBIGUOUS",
+    "SOURCE_VALUE_MISSING",
+    "CARDINALITY_UNSUPPORTED",
+    "NOT_APPLICABLE"
+  ],
+  "dictionary_domains": [
+    "air_airport",
+    "air_packaging_type",
+    "land_address",
+    "land_vehicle",
+    "sea_container",
+    "land_transport_type",
+    "currency_reference"
+  ],
+  "projection_rules": [
+    {
+      "transport_mode": "AIR",
+      "transport_type": null,
+      "source_field": "origin",
+      "target_field": "originCode",
+      "dictionary_domain": "air_airport",
+      "output_column": "projection_value",
+      "default_source_value": null
+    },
+    {
+      "transport_mode": "AIR",
+      "transport_type": null,
+      "source_field": "destination",
+      "target_field": "destinationCode",
+      "dictionary_domain": "air_airport",
+      "output_column": "projection_value",
+      "default_source_value": null
+    },
+    {
+      "transport_mode": "AIR",
+      "transport_type": null,
+      "source_field": "packagingType",
+      "target_field": "packageType",
+      "dictionary_domain": "air_packaging_type",
+      "output_column": "projection_value",
+      "default_source_value": "全部"
+    },
+    {
+      "transport_mode": "LAND",
+      "transport_type": null,
+      "source_field": "origin",
+      "target_field": "originCode",
+      "dictionary_domain": "land_address",
+      "output_column": "projection_value",
+      "default_source_value": null
+    },
+    {
+      "transport_mode": "LAND",
+      "transport_type": null,
+      "source_field": "destination",
+      "target_field": "destinationCode",
+      "dictionary_domain": "land_address",
+      "output_column": "projection_value",
+      "default_source_value": null
+    },
+    {
+      "transport_mode": "LAND",
+      "transport_type": "DOMESTIC_FTL|HK",
+      "source_field": "vehicleItems",
+      "target_field": "vehicleType",
+      "dictionary_domain": "land_vehicle",
+      "output_column": "projection_value",
+      "default_source_value": null
+    },
+    {
+      "transport_mode": "SEA",
+      "transport_type": null,
+      "source_field": "containerItems",
+      "target_field": "containerType",
+      "dictionary_domain": "sea_container",
+      "output_column": "projection_value",
+      "default_source_value": null
+    },
+    {
+      "transport_mode": "LAND",
+      "transport_type": null,
+      "source_field": "transportType",
+      "target_field": "landTransportType",
+      "dictionary_domain": "land_transport_type",
+      "output_column": "projection_value",
+      "default_source_value": null
+    }
+  ],
+  "direct_projection_rules": [
+    {
+      "transport_mode": "SEA",
+      "transport_type": null,
+      "source_field": "containerItems",
+      "source_item_field": "quantity",
+      "target_field": "containerQty",
+      "value_type": "positive_integer",
+      "dictionary_domain": null,
+      "unit_in_value": false
+    }
+  ],
+  "non_blocking_projection_failures": [
+    {
+      "transport_mode": "LAND",
+      "dictionary_domain": "land_address",
+      "target_fields": ["originCode", "destinationCode"],
+      "resolution_status": "UNMAPPED",
+      "required_source_names": ["origin", "destination"],
+      "behavior": "保留投影审计；名称非空时以名称且代码空值继续真实TMS查询。AMBIGUOUS、SOURCE_VALUE_MISSING及其他业务线仍失败关闭。"
+    }
+  ],
+  "direct_passthrough_fields": [
+    {
+      "transport_mode": "LAND",
+      "source_field": "时效要求",
+      "target_field": "routeCategory",
+      "behavior": "逐字透传用户值，不做字典或本地语义映射。"
+    }
+  ],
+  "unsupported_projection_fields": [
+    {
+      "field": "seaPortCode",
+      "reason": "SOURCE_WORKBOOK_HAS_NO_SEA_PORT_DICTIONARY"
+    },
+    {
+      "field": "currency",
+      "reason": "WORKBOOK_NUMERIC_VALUE_IS_REFERENCE_ONLY_NOT_ISO4217_PROJECTION"
+    }
+  ]
+}