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

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

## 概述

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

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

## 主要功能

### 1. 字段发现与分析

系统可以自动分析飞书表格中的字段，识别：
- 已映射的字段
- 未映射的字段
- 为未映射字段提供智能建议

### 2. 多种映射方式

#### 直接映射
```json
{
  "TR Number": "order_id"
}
```

#### 别名映射
```json
{
  "order_id": ["TR Number", "TR编号", "工单号", "Order ID"]
}
```

#### 模式匹配
```json
{
  "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. 获取字段映射状态
```http
GET /api/feishu-sync/field-mapping/status
```

### 2. 发现字段
```http
POST /api/feishu-sync/field-mapping/discover
Content-Type: application/json

{
  "limit": 5
}
```

### 3. 添加字段映射
```http
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. 删除字段映射
```http
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. 使用描述性的别名
为字段添加多个别名，提高匹配成功率：
```json
{
  "order_id": ["TR Number", "TR编号", "工单号", "Order ID", "Ticket ID"]
}
```

### 3. 合理设置优先级
- 核心业务字段设置高优先级
- 辅助字段设置低优先级

### 4. 使用模式匹配
对于有规律的字段名，使用正则表达式模式：
```json
{
  "order_id": [".*number.*", ".*id.*", ".*编号.*"]
}
```

## 故障排除

### 问题1：字段发现失败
**原因**：飞书连接配置问题
**解决**：检查飞书应用配置是否正确

### 问题2：映射建议不准确
**原因**：相似度阈值设置过高
**解决**：调整 `similarity_threshold` 参数

### 问题3：自动映射不工作
**原因**：自动映射功能被禁用
**解决**：在配置文件中设置 `auto_mapping_enabled: true`

## 更新日志

### v1.0.0 (2025-09-22)
- 初始版本发布
- 支持动态字段发现
- 支持智能映射建议
- 支持多种映射方式
- 提供Web管理界面

## 技术支持

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