first commit

2026-03-09 16:31:42 +08:00
commit 4a9c444b10
486 changed files with 52479 additions and 0 deletions
@@ -0,0 +1,42 @@
+# 差异字段汇总清单
+
+本文档记录了在同步推流测试中，本地（Local payload）与远端（Remote API 响应/DB落库）产生明确差异的字段。这些差异通常是因为远端后端代码主动忽略了前端传值，并采用关联覆盖、自动计算或默认补全所致。
+
+> **备注**: 
+> 1. 根据梳理，完全被远端忽略的、只作为返回展示的字段已经从本地/远端的 `Create`、`Update` Schema 中彻底**剔除 (已删)**，不再作为入参推送。
+> 2. 标有 **[🔥远端接收并参与逻辑计算，但最终与本地不一致]** 的字段没有被删，作为强逻辑关联字段保留。
+
+## 1. contract_settlement (合同结算)
+
+### Create 请求 (`ContractSettlementCreate`)
+- **`contract_type` (合同类型)**: **(从 Schema 彻底剔除)** 远端完全不接收本地传值，根据关联逻辑自动赋予了实际类别（如 `'PC'`, `'GJ'`, `'E'`）。
+- **`contract_price` (合同总额)**: Create不需要传（本地本身无该入参）。远端在创建时直接从近端 Contract 数据库查取并覆盖。
+
+### Update / Plan Update 请求 (`ContractSettlementUpdate` 等)
+- **`plan_complete_date`**: **[🔥远端接收并参与逻辑计算，但最终与本地不一致]** 远端接收该字段，主要作用于 `clean_plan_nodes` 数据清洗以保证非法边界节点被剔除，同时可能经过远端状态与明细上托更新，使得终值可能扭转。
+- **`complete_price` / `status` / `delay_days` / `statistic_date` / `actual_start_date`**: 远端自动计算累加的衍生只读字段，均不在 Create / Update Schema 范畴中，故不维护入参。
+
+## 2. construction_task & construction_task_detail (施工任务及明细)
+
+### Create 请求 (`ConstructionTaskCreate`)
+- **`contract_quantity` (合同工程量)**: **(已从 Create Schema 彻底剔除)** 远端由于 `create_construction` 函数底层逻辑完全不读此字段，现已被安全双端剪除。不在初始创建时推送。
+- **`plan_start_date` / `plan_complete_date`**: **[🔥远端接收并参与逻辑计算，但最终与本地不一致]** 远端校验WBS结构树约束时会接收这俩参数进行合规计算，如果超出父子节点范围，存在自动修正或打回改写的逻辑。
+
+### Update / Plan Update 请求 (`ConstructionTaskUpdate` 及明细)
+- **`contract_quantity` (合同工程量)**: **[🔥远端接收并参与逻辑计算，但最终与本地不一致]** 在针对 `ConstructionPlanUpdate` 更新计划节点时，远程接受本字段控制计算与校验完成率基准，但仍可能会受 WBS 重制。
+- **`complete_quantity` / `complete_rate` / `rate` / `status` / `actual_complete_date`**: 纯内部状态更新触发、只读汇总，本地本来就未放至 Update Schema 内进行提交。
+
+## 3. supplier (供应商)
+
+### 字段表现
+- **`city_name`, `province_name`, `country_name`**: Response专用字段。本地不推，仅仅是远端依托外部库映射在接口返回中补全的只读显示。
+
+## 4. company (组织/公司)
+
+### 字段表现
+- **`parent_name` (父级机构名称)**: Response专用显示字段。远端依赖 `parent_id` 自动向上追溯返回字段。
+
+## 5. production (产值等)
+
+### Create / Update 请求
+- **`is_exist`**: **[🔥远端接收并参与逻辑计算，但最终与本地不一致]** 本地推流中有 `is_exist = True`，且远端后端提取了 `production_data.is_exist` 进行存入判断（确实参与了代码落库前置过滤逻辑），但最后远程抓回验证时为 `None`，这归因于远端的废弃映射和覆盖逻辑。该字段须保留不能删。