fix: handle complex bitable field emptiness

Author: BlueSkyXN

core/converter.py

@@ -225,7 +225,8 @@ def _normalize_index_value(
                 return self._normalize_index_value(value.get("value"), nested_type)
 
             if "text" in value:
-                return str(value.get("text", ""))
+                text_value = str(value.get("text", ""))
+                return text_value if text_value.strip() else None
 
             if "link_record_ids" in value:
                 return self._normalize_index_value(
@@ -261,7 +262,9 @@ def _normalize_index_value(
                 text_parts = []
                 for item in values:
                     if isinstance(item, dict) and "text" in item:
-                        text_parts.append(str(item.get("text", "")))
+                        text_value = str(item.get("text", ""))
+                        if text_value.strip():
+                            text_parts.append(text_value)
                     else:
                         item_value = self._normalize_index_value(item)
                         if item_value is not None:
@@ -919,11 +922,11 @@ def convert_field_value_safe(
         self, field_name: str, value, field_types: Optional[Dict[str, int]] = None
     ):
         """安全的字段值转换"""
-        if pd.isnull(value):
-            return None
-
         # 多维表格模式使用复杂转换
         if self.target_type == TargetType.BITABLE:
+            if self._is_empty_value(value):
+                return None
+
             # 如果没有字段类型信息，使用智能转换
             if field_types is None or field_name not in field_types:
                 return self.smart_convert_value(value)
@@ -948,6 +951,13 @@ def convert_field_value_safe(
                 self.conversion_stats["failed"] += 1
                 return None
         else:
+            if pd.api.types.is_scalar(value):
+                try:
+                    if pd.isnull(value):
+                        return None
+                except (TypeError, ValueError):
+                    pass
+
             # 电子表格模式使用简单转换
             return self.simple_convert_value(value)
 
@@ -1249,7 +1259,7 @@ def simple_convert_value(self, value):
 
     def convert_to_user_field(self, value):
         """转换为人员字段格式"""
-        if pd.isnull(value) or not value:
+        if self._is_empty_value(value):
             return None
 
         # 如果已经是正确的字典格式
@@ -1280,7 +1290,7 @@ def convert_to_user_field(self, value):
 
     def convert_to_url_field(self, value):
         """转换为超链接字段格式"""
-        if pd.isnull(value) or not value:
+        if self._is_empty_value(value):
             return None
 
         # 如果已经是正确的字典格式
@@ -1299,7 +1309,7 @@ def convert_to_url_field(self, value):
 
     def convert_to_attachment_field(self, value):
         """转换为附件字段格式"""
-        if pd.isnull(value) or not value:
+        if self._is_empty_value(value):
             return None
 
         # 如果已经是正确的字典格式
@@ -1322,7 +1332,7 @@ def convert_to_attachment_field(self, value):
 
     def convert_to_link_field(self, value):
         """转换为关联字段格式"""
-        if pd.isnull(value) or not value:
+        if self._is_empty_value(value):
             return None
 
         # 如果已经是列表格式

core/engine.py

@@ -2128,7 +2128,10 @@ def sync(self, df: pd.DataFrame) -> bool:
 
             for _, row in df.head(sample_size).iterrows():
                 for col_name, value in row.to_dict().items():
-                    if pd.notnull(value) and col_name in field_types:
+                    if (
+                        not self.converter._is_empty_value(value)
+                        and col_name in field_types
+                    ):
                         field_type = field_types[col_name]
                         # 简单的类型不匹配检测
                         if field_type == 2 and isinstance(

tests/test_converter.py

@@ -180,6 +180,15 @@ def test_get_index_value_hash_text_list_matches_plain_text(self):
 
         assert plain_hash == text_list_hash
 
+    def test_get_index_value_hash_empty_rich_text_is_empty(self):
+        """测试空富文本不会生成空字符串哈希"""
+        converter = DataConverter(TargetType.BITABLE)
+        rich_text_row = pd.Series({"ID": [{"text": "", "type": "text"}]})
+
+        hash_value = converter.get_index_value_hash(rich_text_row, "ID", {"ID": 1})
+
+        assert hash_value is None
+
     def test_get_index_value_hash_date_string_matches_timestamp(self):
         """测试本地日期字符串和飞书日期时间戳生成相同索引哈希"""
         converter = DataConverter(TargetType.BITABLE)
@@ -522,6 +531,32 @@ def test_convert_without_field_types(self):
         result = converter.convert_field_value_safe("test", "123", None)
         assert result == 123  # 智能识别为数字
 
+    def test_convert_multi_segment_text_value(self):
+        """测试多段富文本写入文本字段时不会触发 pandas 空值判断异常"""
+        converter = DataConverter(TargetType.BITABLE)
+        value = [
+            {"text": "李宁少昊", "type": "text"},
+            {"text": "运动户外专卖店", "type": "text"},
+        ]
+
+        result = converter.convert_field_value_safe("Name", value, {"Name": 1})
+
+        assert result == "李宁少昊运动户外专卖店"
+
+    def test_convert_multi_value_complex_fields(self):
+        """测试多个复杂字段值写入时不会触发 pandas 空值判断异常"""
+        converter = DataConverter(TargetType.BITABLE)
+
+        assert converter.convert_field_value_safe(
+            "Users", ["ou_1", "ou_2"], {"Users": 11}
+        ) == [{"id": "ou_1"}, {"id": "ou_2"}]
+        assert converter.convert_field_value_safe(
+            "Files", ["file_1", "file_2"], {"Files": 17}
+        ) == [{"file_token": "file_1"}, {"file_token": "file_2"}]
+        assert converter.convert_field_value_safe(
+            "Links", ["rec_1", "rec_2"], {"Links": 18}
+        ) == ["rec_1", "rec_2"]
+
 
 class TestSimpleConvertValue:
     """简单值转换测试（电子表格模式）"""
@@ -683,6 +718,24 @@ def test_df_to_records_preserves_complex_text_value(self):
 
         assert records == [{"fields": {"Name": "李宁少昊运动户外专卖店"}}]
 
+    def test_df_to_records_preserves_multi_segment_text_value(self):
+        """测试多段富文本写入不会被 pandas 空值判断中断"""
+        converter = DataConverter(TargetType.BITABLE)
+        df = pd.DataFrame(
+            {
+                "Name": [
+                    [
+                        {"text": "李宁少昊", "type": "text"},
+                        {"text": "运动户外专卖店", "type": "text"},
+                    ],
+                ]
+            }
+        )
+
+        records = converter.df_to_records(df, {"Name": 1})
+
+        assert records == [{"fields": {"Name": "李宁少昊运动户外专卖店"}}]
+
     def test_df_to_records_sheet_raises_error(self, sample_dataframe):
         """测试电子表格模式调用 df_to_records 抛出错误"""
         converter = DataConverter(TargetType.SHEET)