Skip to content

FIELD_TYPES.md

Latest commit

 

History

History
349 lines (253 loc) · 10 KB

FIELD_TYPES.md

File metadata and controls

349 lines (253 loc) · 10 KB

XTF 智能字段类型策略

源码位置：core/converter.py

目录

1. 策略概览

XTF 提供四种字段类型策略，控制如何将 Excel 列映射为飞书字段类型：

策略 支持类型 复杂度 推荐场景
raw 文本 🟢 最低 数据完整性要求极高
base 文本 / 数字 / 日期 🟢 低 ⭐ 日常使用（默认推荐）
auto + 单选 / 多选 🟡 中 有标准化 Excel 模板
intelligence 全部 8 种类型 🔴 高 高质量数据 + 进阶用户 
python XTF.py --field-type-strategy base       # 默认推荐
python XTF.py --field-type-strategy intelligence  # 全面智能

2. Raw 策略 — 保持原值

🛡️ 数据完整性最高，零转换风险

Bitable 行为：

  • 所有字段创建为文本类型 (type=1)
  • 不进行任何数据类型转换
  • 原始值直接写入

Sheet 行为：

  • 不应用任何格式化
  • 保持 Excel 原始数据和格式
  • 不创建下拉列表

适用场景：

  • 数据归档：原封不动搬迁
  • 敏感数据：不能承受转换错误
  • 调试：排除类型转换问题

3. Base 策略 — 基础智能

⭐ 默认推荐，最大化同步成功率

Bitable 行为：

  • 自动识别三种基础类型：文本 (1) / 数字 (2) / 日期 (5)
  • 数字：清理格式后转为数值
  • 日期：多格式解析后转为毫秒时间戳

Sheet 行为：

  • 自动设置数字格式（#,##0.00）
  • 自动设置日期格式（yyyy/MM/dd）
  • 不创建下拉列表

CSV 兼容性：✅ 完美支持

4. Auto 策略 — 增强智能

在 Base 基础上增加 Excel 数据验证检测

Bitable 行为：

  • 包含 Base 的全部能力
  • 检测 Excel 数据验证（下拉列表）→ 推荐单选 (3) / 多选 (4)
  • 仅在检测到 Excel 验证时才推荐选择类型

Sheet 行为：

  • 包含 Base 的全部能力
  • 基于 Excel 数据验证自动创建飞书下拉列表
  • 自动设置日期和数字格式

CSV 兼容性：⚠️ 部分受限（CSV 不保留 Excel 数据验证信息）

5. Intelligence 策略 — 全面智能

基于置信度算法的全面类型推断

Bitable 行为：

  • 所有 8 种字段类型均可推荐
  • 基于数据分析和置信度评分决定类型
  • 每个字段附带推荐理由和置信度

Sheet 行为：

  • 基于数据内容智能创建下拉列表
  • 单选：唯一值 ≤ 20 个的字符串字段
  • 多选：包含分隔符的字符串字段
  • 自动为下拉选项分配颜色

置信度阈值（可配置）：

类型 参数 默认值 说明
日期 intelligence_date_confidence 0.85 超过此值推荐日期类型
选择 intelligence_choice_confidence 0.9 超过此值推荐单选/多选
布尔 intelligence_boolean_confidence 0.95 超过此值推荐复选框

CSV 兼容性：✅ 完美支持（基于数据内容分析，不依赖 Excel 验证）

6. 数据类型检测算法

数字检测

支持格式：

  • 整数：123, 1,234, -456
  • 小数：3.14, -0.5, 1,234.56
  • 货币：$1,234.56, ¥100, €50.00
  • 百分比：85%, 12.5%
  • 科学计数：1.5e10, 3.14E-5

清洗规则：去除货币符号、千分位分隔符、百分号后转为数值。

日期检测

支持格式（11+ 种）：

格式 示例 置信度
ISO 8601 2024-01-15, 2024-01-15T10:30:00 高
中文日期 2024年1月15日 高
斜线分隔 01/15/2024, 2024/01/15 中
短横线分隔 15-01-2024 中
时间戳（秒） 1705276800 需范围验证
时间戳（毫秒） 1705276800000 需范围验证

转换结果：统一转为毫秒时间戳（飞书日期字段要求）。

时间戳范围验证：

  • 秒级：946684800（2000-01-01）～ 4102444800（2100-01-01）
  • 毫秒级：上述范围 × 1000

布尔检测

支持关键字：

True 值 False 值
true, True, TRUE false, False, FALSE
yes, Yes, YES no, No, NO
是 否
on, On, ON off, Off, OFF

⚠️ 数字字符串 '1' / '0' 不会被识别为布尔值（防止误判）。

枚举/选择检测

检测条件：

  • 唯一值数量 ≤ 20
  • 重复率高（同一值出现多次）
  • 非纯数字和非日期

Auto 策略：仅在检测到 Excel 数据验证（下拉列表）时推荐。

Intelligence 策略：基于数据统计分析自动检测：

  • 单选：唯一值 ≤ 20 的字符串字段
  • 多选：包含分隔符（; / 、）的字段

特殊类型检测（仅 Intelligence）

类型 检测规则 示例
人员 (11) 匹配 ou_ 前缀的用户 ID ou_xxx123
超链接 (15) 匹配 URL 模式 https://example.com

7. 数据转换规则

数字转换

原始值          →  转换结果
"$1,234.56"    →  1234.56
"85%"          →  0.85
"1,234"        →  1234
"N/A"          →  "N/A" (保持文本)

日期转换

原始值               →  转换结果 (毫秒时间戳)
"2024-01-15"        →  1705248000000
"2024年1月15日"      →  1705248000000
"01/15/2024"        →  1705248000000
"1705248000"        →  1705248000000 (秒级自动×1000)

布尔转换

原始值    →  转换结果
"是"     →  true
"否"     →  false
"Yes"    →  true
"off"    →  false

多选转换

原始值               →  转换结果
"选项1;选项2;选项3"  →  ["选项1", "选项2", "选项3"]
"A/B/C"             →  ["A", "B", "C"]
"标签1、标签2"       →  ["标签1", "标签2"]

特殊类型转换

# 人员
"ou_xxx123"          →  [{"id": "ou_xxx123"}]

# 超链接
"https://example.com" →  {"text": "https://example.com", "link": "https://example.com"}

强制转换

当目标类型与数据不匹配时，系统会尝试强制转换：

  • 数字字段遇到非数字 → 保持为文本（记录警告）
  • 日期字段遇到非日期 → 保持为文本（记录警告）
  • 强制转换失败不会阻断同步，会记录在转换统计中

8. 转换统计报告

每次同步完成后，系统自动生成转换统计报告：

═══════════════════════════════════════════
📊 数据转换统计报告
═══════════════════════════════════════════
字段类型策略: base
总字段数: 15
转换字段: 12

字段转换详情:
  ✓ ID: 文本(1) → 100% 成功
  ✓ 金额: 数字(2) → 98.5% 成功 (3条转换失败)
  ✓ 日期: 日期(5) → 99.2% 成功 (2条格式异常)
  ✓ 姓名: 文本(1) → 100% 成功

问题汇总:
  ⚠ 金额: 3 条记录无法转为数字 (行号: 15, 42, 89)
  ⚠ 日期: 2 条记录日期格式无法解析
═══════════════════════════════════════════

报告内容：

  • 使用的策略名称
  • 各字段的推荐类型和转换成功率
  • 转换失败的详细记录（行号和原因）
  • Intelligence 策略额外显示置信度和推荐理由

9. 双平台行为差异

同一策略在 Bitable 和 Sheet 下的行为存在差异：

Base 策略

操作 Bitable Sheet
数字检测 创建数字字段 (type=2) 设置数字格式 (#,##0.00)
日期检测 创建日期字段 (type=5)，值转毫秒时间戳 设置日期格式 (yyyy/MM/dd)
文本 创建文本字段 (type=1) 无特殊处理

Auto 策略

操作 Bitable Sheet
Excel 验证 创建单选 (3) / 多选 (4) 字段 创建飞书下拉列表
无验证 回退到 Base 行为 回退到 Base 行为

Intelligence 策略

操作 Bitable Sheet
枚举检测 创建单选/多选字段 + 选项 创建下拉列表 + 颜色标记
布尔检测 创建复选框字段 (type=7) 无特殊处理
人员检测 创建人员字段 (type=11) 无特殊处理
链接检测 创建超链接字段 (type=15) 无特殊处理

10. 策略选择指南

决策树

数据完整性要求极高？
  └─ 是 → raw
  └─ 否 → 需要 Excel 验证（下拉列表）？
            └─ 是 → auto
            └─ 否 → 需要高级类型（布尔/人员/链接）？
                      └─ 是 → intelligence
                      └─ 否 → base ⭐

CSV 文件策略建议

策略 CSV 兼容性 建议
raw ✅ 完美 仅需归档时使用
base ✅ 完美 ⭐ CSV 首选推荐
auto ⚠️ 受限 CSV 无验证信息，等同 base
intelligence ✅ 完美 需要高级类型时使用

常见问题

Q: 字段类型推荐不准确？

  • 降级到 base 策略确保稳定
  • Intelligence 策略可调整置信度阈值

Q: 日期格式识别错误？

  • 检查原始数据格式是否在支持列表中
  • 使用 raw 策略跳过日期检测
  • 调低 intelligence_date_confidence 阈值

Q: 数字被识别为文本？

  • 检查是否包含非数字字符
  • base 策略会自动清洗货币符号和千分位分隔符