297 lines
7.8 KiB
Markdown
297 lines
7.8 KiB
Markdown
# 飞书多维表格配置指南
|
||
|
||
## 一、创建飞书多维表格
|
||
|
||
### 1.1 创建多维表格
|
||
|
||
1. 登录飞书
|
||
2. 进入「工作台」→ 搜索「多维表格」
|
||
3. 点击「新建多维表格」→ 选择「空白数据表」
|
||
4. 将多维表格命名为「官网客户咨询」
|
||
|
||
### 1.2 设置字段
|
||
|
||
在数据表中创建以下字段：
|
||
|
||
| 序号 | 字段名称 | 字段类型 | 说明 |
|
||
|------|---------|---------|------|
|
||
| 1 | 编号 | 自动编号 | 系统自动生成 |
|
||
| 2 | 姓名 | 文本 | 客户姓名 |
|
||
| 3 | 手机 | 电话号码 | 客户手机 |
|
||
| 4 | 邮箱 | 邮箱 | 客户邮箱 |
|
||
| 5 | 当前使用系统 | 多选 | 物业系统/资管系统/CRM/其他 |
|
||
| 6 | 系统名称 | 文本 | 其他系统名称 |
|
||
| 7 | 咨询内容 | 长文本 | 客户留言 |
|
||
| 8 | 咨询时间 | 创建时间 | 自动记录 |
|
||
| 9 | 处理状态 | 单选 | 待联系/已联系/已转化/无效线索 |
|
||
| 10 | 处理备注 | 文本 | 客服跟进记录 |
|
||
| 11 | 处理人 | 成员 | 负责客服 |
|
||
| 12 | 跟进时间 | 修改时间 | 最后更新时间 |
|
||
|
||
### 1.3 获取多维表格信息
|
||
|
||
1. 在浏览器中打开创建的多维表格
|
||
2. URL 格式：`https://xxx.feishu.cn/bitable/appbXXXXXXXXXXXXXX/baselXXXXXXXXXXXXXX`
|
||
3. `appbXXXXXXXXXXXXXX` 就是 **BITABLE_APP_TOKEN**
|
||
4. 点击数据表右上角「...」→「关于此数据表」→「数据表 ID」
|
||
5. 或者进入数据表后，URL 中的 `tbl` 后面的字符串就是 **BITABLE_TABLE_ID**
|
||
|
||
## 二、创建飞书应用
|
||
|
||
### 2.1 创建应用
|
||
|
||
1. 进入 [飞书开放平台](https://open.feishu.cn/)
|
||
2. 点击「创建企业自建应用」
|
||
3. 填写应用名称和描述
|
||
4. 创建后，进入应用详情页
|
||
|
||
### 2.2 获取凭证
|
||
|
||
1. 进入「凭证与基础信息」
|
||
2. 获取 **App ID** 和 **App Secret**
|
||
|
||
### 2.3 配置权限
|
||
|
||
1. 进入「权限管理」
|
||
2. 搜索并添加以下权限：
|
||
- `bitable:app` - 多维表格权限
|
||
- `contact:user.id:readonly` - 通讯录只读权限
|
||
- `bitable:table:readonly` - 数据表只读
|
||
- `bitable:record:create` - 创建记录
|
||
- `bitable:record:update` - 更新记录
|
||
|
||
### 2.4 发布应用
|
||
|
||
1. 进入「版本管理与发布」
|
||
2. 创建新版本
|
||
3. 填写版本信息
|
||
4. 提交审核（如果是企业自建应用，通常无需审核直接发布）
|
||
|
||
### 2.5 添加应用到多维表格
|
||
|
||
1. 打开创建的多维表格
|
||
2. 点击右上角「...」→「添加应用」
|
||
3. 搜索并添加刚创建的应用
|
||
4. 确保应用有「查看和编辑」权限
|
||
|
||
## 三、获取 Webhook（可选）
|
||
|
||
### 3.1 创建群机器人
|
||
|
||
1. 在飞书中创建一个专用群组（如「官网咨询处理群」）
|
||
2. 点击群设置 → 群机器人 → 添加机器人
|
||
3. 选择「自定义机器人」
|
||
4. 设置机器人名称，点击添加
|
||
5. 复制 Webhook 地址
|
||
|
||
### 3.2 Webhook 地址格式
|
||
|
||
```
|
||
https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||
```
|
||
|
||
## 四、环境变量配置
|
||
|
||
复制 `.env.example` 为 `.env`，填写配置：
|
||
|
||
```bash
|
||
# 飞书应用凭证
|
||
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 安装依赖
|
||
|
||
```bash
|
||
# 仅需要 Python 3.7+（标准库，无需额外安装）
|
||
python3 --version
|
||
```
|
||
|
||
### 5.2 启动服务
|
||
|
||
```bash
|
||
# 方法一：直接运行
|
||
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 验证服务
|
||
|
||
```bash
|
||
# 健康检查
|
||
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 反向代理（生产环境）
|
||
|
||
```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` 中添加逻辑，根据不同条件自动分配处理人：
|
||
|
||
```python
|
||
def _auto_assign_handler(self, record):
|
||
# 根据系统类型分配
|
||
system = record.get("current_system", "")
|
||
if "物业" in system:
|
||
return "张三"
|
||
elif "资管" in system:
|
||
return "李四"
|
||
else:
|
||
return "王五"
|
||
```
|
||
|
||
### 9.2 自动发送邮件通知
|
||
|
||
添加邮件通知功能：
|
||
|
||
```python
|
||
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 数据统计
|
||
|
||
定期统计咨询数据：
|
||
|
||
```python
|
||
def get_statistics(self):
|
||
"""获取统计数据"""
|
||
# 按月统计
|
||
# 按处理状态统计
|
||
# 按来源统计
|
||
pass
|
||
```
|
||
|
||
## 十、联系支持
|
||
|
||
如有问题，请联系技术支持。
|