7.8 KiB
7.8 KiB
飞书多维表格配置指南
一、创建飞书多维表格
1.1 创建多维表格
- 登录飞书
- 进入「工作台」→ 搜索「多维表格」
- 点击「新建多维表格」→ 选择「空白数据表」
- 将多维表格命名为「官网客户咨询」
1.2 设置字段
在数据表中创建以下字段：
| 序号 | 字段名称 | 字段类型 | 说明 |
|---|---|---|---|
| 1 | 编号 | 自动编号 | 系统自动生成 |
| 2 | 姓名 | 文本 | 客户姓名 |
| 3 | 手机 | 电话号码 | 客户手机 |
| 4 | 邮箱 | 邮箱 | 客户邮箱 |
| 5 | 当前使用系统 | 多选 | 物业系统/资管系统/CRM/其他 |
| 6 | 系统名称 | 文本 | 其他系统名称 |
| 7 | 咨询内容 | 长文本 | 客户留言 |
| 8 | 咨询时间 | 创建时间 | 自动记录 |
| 9 | 处理状态 | 单选 | 待联系/已联系/已转化/无效线索 |
| 10 | 处理备注 | 文本 | 客服跟进记录 |
| 11 | 处理人 | 成员 | 负责客服 |
| 12 | 跟进时间 | 修改时间 | 最后更新时间 |
1.3 获取多维表格信息
- 在浏览器中打开创建的多维表格
- URL 格式：
https://xxx.feishu.cn/bitable/appbXXXXXXXXXXXXXX/baselXXXXXXXXXXXXXX appbXXXXXXXXXXXXXX就是 BITABLE_APP_TOKEN- 点击数据表右上角「...」→「关于此数据表」→「数据表 ID」
- 或者进入数据表后，URL 中的
tbl后面的字符串就是 BITABLE_TABLE_ID
二、创建飞书应用
2.1 创建应用
- 进入 飞书开放平台
- 点击「创建企业自建应用」
- 填写应用名称和描述
- 创建后，进入应用详情页
2.2 获取凭证
- 进入「凭证与基础信息」
- 获取 App ID 和 App Secret
2.3 配置权限
- 进入「权限管理」
- 搜索并添加以下权限：
bitable:app- 多维表格权限contact:user.id:readonly- 通讯录只读权限bitable:table:readonly- 数据表只读bitable:record:create- 创建记录bitable:record:update- 更新记录
2.4 发布应用
- 进入「版本管理与发布」
- 创建新版本
- 填写版本信息
- 提交审核（如果是企业自建应用，通常无需审核直接发布）
2.5 添加应用到多维表格
- 打开创建的多维表格
- 点击右上角「...」→「添加应用」
- 搜索并添加刚创建的应用
- 确保应用有「查看和编辑」权限
三、获取 Webhook（可选）
3.1 创建群机器人
- 在飞书中创建一个专用群组（如「官网咨询处理群」）
- 点击群设置 → 群机器人 → 添加机器人
- 选择「自定义机器人」
- 设置机器人名称，点击添加
- 复制 Webhook 地址
3.2 Webhook 地址格式
https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
四、环境变量配置
复制 .env.example 为 .env，填写配置：
# 飞书应用凭证
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 多维表格信息
FEISHU_BITABLE_APP_TOKEN=appbXXXXXXXXXXXXXX
FEISHU_BITABLE_TABLE_ID=tblXXXXXXXXXXXXXX
# Webhook（可选）
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
五、启动服务
5.1 安装依赖
# 仅需要 Python 3.7+（标准库，无需额外安装）
python3 --version
5.2 启动服务
# 方法一：直接运行
python3 consult-service.py
# 方法二：使用环境变量
FEISHU_APP_ID=xxx FEISHU_APP_SECRET=xxx python3 consult-service.py
# 方法三：使用 .env 文件
# 安装 python-dotenv（可选）
pip3 install python-dotenv
# 启动服务
python3 consult-service.py
5.3 验证服务
# 健康检查
curl http://localhost:4001/api/consult/health
# 测试提交
curl -X POST http://localhost:4001/api/consult \
-H "Content-Type: application/json" \
-d '{
"name": "测试用户",
"phone": "13812345678",
"email": "test@example.com",
"current_system": ["物业系统", "CRM"],
"message": "测试咨询内容"
}'
六、配置 Nginx 反向代理（生产环境）
server {
listen 443 ssl;
server_name your-domain.com;
location /ai/api/consult {
proxy_pass http://127.0.0.1:4001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# 限制请求体大小
client_max_body_size 50k;
}
}
七、数据流程
┌─────────────┐
│ 用户提交 │
│ 表单数据 │
└──────┬──────┘
│
▼
┌─────────────┐
│ 前端验证 │
│ (HTML5 + │
│ JavaScript)│
└──────┬──────┘
│
▼
┌─────────────┐
│ 后端 API │
│ /api/consult│
└──────┬──────┘
│
├─────────────────┐
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ 本地存储 │ │ 飞书多维 │
│ JSON 文件 │ │ 表格 │
└─────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ 飞书通知 │
│ (Webhook) │
└─────────────┘
八、故障排查
8.1 常见问题
Q: 飞书多维表格写入失败
- 检查 APP_ID 和 APP_SECRET 是否正确
- 确认应用已发布并添加到多维表格
- 检查权限是否包含
bitable:record:create
Q: Webhook 通知发送失败
- 确认 Webhook 地址正确
- 检查网络是否可访问外网
Q: CORS 跨域问题
- 确认后端服务正常运行
- 检查 Nginx 配置是否正确转发
8.2 日志查看
服务运行时会输出详细日志：
[2026-05-19 10:00:00] ✓ 飞书 access_token 获取成功
[2026-05-19 10:00:01] ✓ 本地保存成功: /opt/ai-landing/data/2026-05.json
[2026-05-19 10:00:02] ✓ 飞书多维表格记录创建成功: recXXXXXXXXXXXXXX
[2026-05-19 10:00:03] ✓ 飞书通知发送成功
九、后续扩展
9.1 自动分配处理人
在 consult-service.py 中添加逻辑，根据不同条件自动分配处理人：
def _auto_assign_handler(self, record):
# 根据系统类型分配
system = record.get("current_system", "")
if "物业" in system:
return "张三"
elif "资管" in system:
return "李四"
else:
return "王五"
9.2 自动发送邮件通知
添加邮件通知功能：
import smtplib
from email.mime.text import MIMEText
def send_email_notification(self, record):
# 配置邮件服务器
smtp_server = os.getenv("SMTP_SERVER")
smtp_port = int(os.getenv("SMTP_PORT", 587))
smtp_user = os.getenv("SMTP_USER")
smtp_password = os.getenv("SMTP_PASSWORD")
msg = MIMEText(f"新咨询：{record['name']} - {record['phone']}", 'plain')
msg['Subject'] = '官网新咨询通知'
msg['From'] = smtp_user
msg['To'] = 'sales@example.com'
with smtplib.SMTP(smtp_server, smtp_port) as server:
server.starttls()
server.login(smtp_user, smtp_password)
server.send_message(msg)
9.3 数据统计
定期统计咨询数据：
def get_statistics(self):
"""获取统计数据"""
# 按月统计
# 按处理状态统计
# 按来源统计
pass
十、联系支持
如有问题，请联系技术支持。