智能字段映射使用指南.md•4.93 kB
# 简道云MCP服务器 - 智能字段映射使用指南
## 功能概述
智能字段映射功能允许您使用中文字段名（如"姓名"、"电话"）直接提交数据，系统会自动将这些用户友好的字段名转换为简道云后台的实际字段名（如`_widget_1234567890`）。
## 核心功能
### 1. 智能字段匹配策略
系统按以下优先级进行字段匹配：
1. **精确匹配label** - 完全匹配表单字段的显示名称
2. **包含匹配** - 部分匹配字段名称
3. **name匹配** - 匹配后台字段名
4. **常见字段映射** - 预定义的中英文字段对应关系
### 2. 预定义字段映射
```javascript
const commonMappings = {
'姓名': ['name', 'username', '用户名', '姓名'],
'电话': ['phone', 'tel', 'mobile', '手机', '电话'],
'邮箱': ['email', 'mail', '邮件', '邮箱'],
'地址': ['address', '地址', '住址'],
'备注': ['remark', 'note', 'comment', '备注', '说明']
};
```
## 使用方法
### 基本用法
```javascript
// 使用中文字段名提交数据
const testData = {
"姓名": "张鑫",
"电话": "13800138000",
"邮箱": "zhangxin@example.com",
"备注": "测试数据"
};
// 调用submit_form_data工具
const result = await mcpClient.call('submit_form_data', {
formId: 'your_form_id',
data: testData,
autoMatch: true // 启用智能字段映射
});
```
### 批量提交
```javascript
// 批量提交多条数据
const batchData = [
{ "姓名": "张鑫", "电话": "13800138000" },
{ "姓名": "李明", "电话": "13900139000" },
{ "姓名": "王芳", "电话": "13700137000" }
];
const result = await mcpClient.call('submit_form_data', {
formId: 'your_form_id',
data: batchData,
autoMatch: true
});
```
### 关闭自动匹配
```javascript
// 使用后台字段名直接提交
const backendData = {
"_widget_1234567890": "张鑫",
"_widget_0987654321": "13800138000"
};
const result = await mcpClient.call('submit_form_data', {
formId: 'your_form_id',
data: backendData,
autoMatch: false // 关闭自动匹配
});
```
## 返回结果
成功提交后，系统会返回详细的映射信息：
```json
{
"success": true,
"result": { /* 简道云API返回结果 */ },
"message": "数据提交成功",
"formUsed": "actual_form_id",
"appId": "app_id",
"originalData": { /* 原始提交数据 */ },
"processedData": { /* 映射后的数据 */ },
"fieldMapping": [
{
"name": "_widget_1234567890",
"label": "姓名",
"type": "text",
"required": true
}
]
}
```
## 字段映射日志
系统会在控制台输出详细的映射过程：
```
字段映射: "姓名" -> "_widget_1234567890" (姓名)
字段映射: "电话" -> "_widget_0987654321" (联系电话)
字段未映射: "自定义字段" 保持原样
```
## 最佳实践
### 1. 获取表单字段信息
在首次使用前，建议先获取表单字段信息：
```javascript
const fields = await mcpClient.call('get_form_fields', {
formId: 'your_form_id'
});
console.log('可用字段:', fields);
```
### 2. 错误处理
```javascript
try {
const result = await mcpClient.call('submit_form_data', {
formId: 'your_form_id',
data: testData,
autoMatch: true
});
console.log('提交成功:', result);
} catch (error) {
console.error('提交失败:', error.message);
// 检查是否是权限问题、字段不存在等
}
```
### 3. 验证映射结果
```javascript
const result = await mcpClient.call('submit_form_data', {
formId: 'your_form_id',
data: testData,
autoMatch: true
});
// 检查映射是否正确
console.log('原始数据:', result.originalData);
console.log('处理后数据:', result.processedData);
console.log('字段映射:', result.fieldMapping);
```
## 故障排除
### 1. 权限问题
如果遇到403错误，请检查：
- API密钥是否正确
- 是否有访问该表单的权限
- 应用ID和表单ID是否匹配
### 2. 字段映射失败
如果字段无法正确映射：
- 检查字段名是否准确
- 使用`get_form_fields`获取准确的字段信息
- 考虑使用后台字段名直接提交
### 3. 数据格式问题
确保提交的数据格式符合字段要求：
- 文本字段：字符串
- 数字字段：数字类型
- 日期字段：正确的日期格式
- 选择字段：有效的选项值
## 技术实现
智能字段映射功能通过以下步骤实现：
1. **获取表单字段** - 调用简道云API获取表单的所有字段定义
2. **字段匹配** - 使用多种策略匹配用户输入的字段名
3. **数据转换** - 将用户数据转换为后台可识别的格式
4. **提交数据** - 使用转换后的数据调用简道云提交API
5. **返回结果** - 包含原始数据、处理后数据和映射信息
这个功能大大简化了简道云表单数据的提交过程，让用户可以使用直观的中文字段名，而无需了解复杂的后台字段结构。