Skip to content

fix(bitable): 规范化复杂字段索引匹配#10

Merged
BlueSkyXN merged 6 commits into
mainfrom
fix/issue-9-bitable-index-field-types
May 4, 2026
Merged

fix(bitable): 规范化复杂字段索引匹配#10
BlueSkyXN merged 6 commits into
mainfrom
fix/issue-9-bitable-index-field-types

Conversation

@BlueSkyXN

@BlueSkyXN BlueSkyXN commented Apr 30, 2026

Copy link
Copy Markdown
Owner

背景

修复 #9:多维表格在使用索引列匹配记录时,远端字段返回值可能是富文本对象列表、日期毫秒时间戳、公式/查找引用包装结构等复杂类型。原逻辑在本地和远端两侧使用了不一致的字符串化方式,导致本应更新的记录无法命中索引,进而被当作新增记录处理。

问题归因

  • 文本字段写入时通常是普通字符串,但查询记录时可能返回 [{"text": "...", "type": "text"}] 这类富文本片段列表。
  • 日期字段写入和读取都使用毫秒时间戳,但日期字符串写入侧按本地日期语义生成时间戳;索引归一化如果按 UTC 解释该时间戳,会在 Asia/Shanghai 等时区出现跨日偏移。
  • 公式/查找引用等字段可能返回 {type, value} 包装结构,不能直接 str() 后参与 hash。
  • pd.isnull() / pd.notnull() 直接处理 list/dict 会出现歧义,容易在复杂字段写入或预检查阶段中断同步。

变更内容

  • 为 Bitable 索引匹配增加统一规范化逻辑:
    • 文本/富文本:[{"text": "...", "type": "text"}]list[str] 与普通字符串按同一文本值匹配。
    • 日期字段:本地日期字符串与远端毫秒时间戳按同一本地日期语义匹配,覆盖 XTF 写出后读回的 roundtrip 场景。
    • 公式/查找引用包装:支持 {type, value} 结构展开后参与索引匹配。
    • 数字、布尔、人员、附件、关联等常见结构增加稳定规范化处理。
  • fullincrementaloverwrite 三种 Bitable 同步路径中传入字段类型,确保索引构建和本地行匹配使用同一规则。
  • 复杂字段空值判断改为统一方法,避免 pd.isnull() / pd.notnull() 处理 list/dict 时出现歧义。
  • 文本字段写入时不再把飞书富文本结构直接转换成 Python 字面量字符串,空富文本不会生成空字符串 hash。
  • 增加 issue 场景相关单元测试,覆盖富文本、list[str]、日期时间戳、日期本地时区 roundtrip、公式包装、空复杂字段和多值复杂字段。
  • 补充少量 Black/Mypy 所需的格式与类型标注收口,确保现有 CI 质量门禁通过。

验证

按要求未进行真实飞书运行测试,没有使用真实 token 调用飞书 API。已完成本地静态/单元验证:

  • PYTHONPATH=. python3 -m pytest tests/test_converter.py -q:57 passed
  • PYTHONPATH=. python3 -m pytest tests/ -q -m "not integration":164 passed,本机 requests 依赖版本 warning 不影响结果
  • python3 -m ruff check . --ignore E501,F401
  • python3 -m black --check .
  • python3 -m mypy core/ api/ utils/ --ignore-missing-imports
  • python3 -m py_compile XTF.py core/*.py api/*.py utils/*.py
  • git diff --check origin/main...HEAD && git diff --check

已补充本地最小复现验证:多段富文本、多值人员字段、空富文本索引、日期字段写出后读回 roundtrip 均通过。

远端 GitHub Actions 已通过当前 head 的 Code QualityTest Summary、Ubuntu/macOS/Windows 全矩阵 Unit Tests。当前 head 为 f0e8737b6a970be01adda25e889279a836d7441d

Closes #9

@BlueSkyXN BlueSkyXN force-pushed the fix/issue-9-bitable-index-field-types branch from 66e8488 to 6b12eba Compare May 4, 2026 05:58
@BlueSkyXN BlueSkyXN merged commit a283c58 into main May 4, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

其他字段类型没法更新,只支持普通值

1 participant