fischer-site/FEISHU_BITABLE_SETUP.md

飞书多维表格配置指南

一、创建飞书多维表格

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. 进入 飞书开放平台
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，填写配置：

# 飞书应用凭证
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

十、联系支持

如有问题，请联系技术支持。