assist/灵活字段映射系统使用说明.md

灵活字段映射系统使用说明

概述

为了解决飞书同步系统字段映射过于呆板的问题，我们开发了一套灵活的字段映射系统。该系统支持：

• 动态字段发现：自动分析飞书表格中的字段
• 智能映射建议：基于相似度和模式匹配提供映射建议
• 灵活配置管理：支持添加、删除、修改字段映射
• 自动学习能力：系统会根据使用情况不断优化映射规则

主要功能

1. 字段发现与分析

系统可以自动分析飞书表格中的字段，识别：

• 已映射的字段
• 未映射的字段
• 为未映射字段提供智能建议

2. 多种映射方式

直接映射

{
  "TR Number": "order_id"
}

别名映射

{
  "order_id": ["TR Number", "TR编号", "工单号", "Order ID"]
}

模式匹配

{
  "order_id": [".*number.*", ".*id.*", ".*编号.*"]
}

3. 优先级管理

字段映射支持优先级设置：

• 优先级 1：核心字段（工单号、描述、状态等）
• 优先级 2：重要字段（来源、解决方案等）
• 优先级 3：扩展字段（版本信息、操作时间等）

使用方法

1. 访问字段映射管理页面

在浏览器中访问：http://your-server/api/feishu-sync/field-mapping

2. 发现字段

点击"发现字段"按钮，系统会：

• 分析飞书表格中的字段
• 显示已映射和未映射的字段
• 为未映射字段提供建议

3. 添加字段映射

方法一：使用建议映射

1. 在发现结果中，点击建议映射旁的"应用"按钮
2. 系统会自动添加映射关系

方法二：手动添加映射

1. 点击"添加映射"按钮
2. 填写飞书字段名和本地字段名
3. 可选：添加别名和匹配模式
4. 设置优先级
5. 点击"添加映射"

4. 管理现有映射

• 查看映射状态：点击"刷新状态"查看当前所有映射
• 删除映射：在映射列表中点击"删除"按钮

API接口

1. 获取字段映射状态

GET /api/feishu-sync/field-mapping/status

2. 发现字段

POST /api/feishu-sync/field-mapping/discover
Content-Type: application/json

{
  "limit": 5
}

3. 添加字段映射

POST /api/feishu-sync/field-mapping/add
Content-Type: application/json

{
  "feishu_field": "新字段名",
  "local_field": "order_id",
  "aliases": ["别名1", "别名2"],
  "patterns": [".*pattern.*"],
  "priority": 2
}

4. 删除字段映射

POST /api/feishu-sync/field-mapping/remove
Content-Type: application/json

{
  "feishu_field": "要删除的字段名"
}

配置文件

字段映射配置存储在 config/field_mapping_config.json 文件中，包含：

• field_mapping：直接映射关系
• field_aliases：字段别名
• field_patterns：匹配模式
• field_priorities：字段优先级
• auto_mapping_enabled：是否启用自动映射
• similarity_threshold：相似度阈值

智能建议算法

系统使用以下算法提供映射建议：

1. 相似度匹配

使用 difflib.SequenceMatcher 计算字段名相似度：

• 相似度 ≥ 0.8：高置信度建议
• 相似度 ≥ 0.6：中等置信度建议

2. 模式匹配

使用正则表达式匹配字段名模式：

• 支持中英文混合匹配
• 支持大小写不敏感匹配

3. 优先级排序

建议按相似度和优先级排序，优先显示高优先级字段的建议。

使用场景

场景1：飞书表格字段调整

当飞书表格的字段名发生变化时：

1. 运行字段发现功能
2. 查看未映射字段
3. 使用建议映射或手动添加映射

场景2：新增字段

当飞书表格新增字段时：

1. 系统会自动识别新字段
2. 提供映射建议
3. 一键应用建议或手动配置

场景3：字段顺序调整

当飞书表格字段顺序调整时：

• 系统不受影响，因为映射基于字段名而非位置

最佳实践

1. 定期检查映射状态

建议定期运行字段发现功能，确保所有重要字段都已正确映射。

2. 使用描述性的别名

为字段添加多个别名，提高匹配成功率：

{
  "order_id": ["TR Number", "TR编号", "工单号", "Order ID", "Ticket ID"]
}

3. 合理设置优先级

• 核心业务字段设置高优先级
• 辅助字段设置低优先级

4. 使用模式匹配

对于有规律的字段名，使用正则表达式模式：

{
  "order_id": [".*number.*", ".*id.*", ".*编号.*"]
}

故障排除

问题1：字段发现失败

原因：飞书连接配置问题 解决：检查飞书应用配置是否正确

问题2：映射建议不准确

原因：相似度阈值设置过高 解决：调整 similarity_threshold 参数

问题3：自动映射不工作

原因：自动映射功能被禁用 解决：在配置文件中设置 auto_mapping_enabled: true

更新日志

v1.0.0 (2025-09-22)

• 初始版本发布
• 支持动态字段发现
• 支持智能映射建议
• 支持多种映射方式
• 提供Web管理界面

技术支持

如有问题，请联系开发团队或查看系统日志获取详细错误信息。