# 飞书多维表格配置指南

## 一、创建飞书多维表格

### 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
```

## 十、联系支持

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