圣诞礼物交换系统 - 部署与操作文档

项目概述

这是一个3D圣诞树礼物交换系统，包含：

• 前端：React + Three.js 3D圣诞树动画，用户通过邮箱查询礼物
• 后端：Python FastAPI，基于 AI + 遗传算法的礼物匹配系统

---

一、环境准备

1.1 前端环境

Node.js >= 16
npm 或 yarn

1.2 后端环境

Python >= 3.8
pip

1.3 依赖安装

前端依赖：

cd tree2
npm install

后端依赖：

cd backend
pip install fastapi uvicorn openai pydantic python-dotenv requests

---

二、配置文件

2.1 后端配置 (backend/.env)

复制 .env.example 为 .env 并填写：

# AI 配置（必填）
AI_API_KEY=your_api_key_here
AI_BASE_URL=https://api.siliconflow.cn/v1
AI_MODEL_NAME=Qwen/Qwen2-7B-Instruct

# 飞书配置（必填）
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
FEISHU_APP_TOKEN=your_app_token
FEISHU_TABLE_ID=your_table_id

# 邮件配置（可选，用于发送通知）
SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_USER=your_email@qq.com
SMTP_PASSWORD=your_auth_code

---

三、正式运行流程

步骤 1：收集用户数据

用户在飞书多维表格中填写信息，包括：

• 选手名
• 邮箱
• 微信账号
• MBTI
• 准备的礼物描述
• 用户选择题的答案
• 选择卡面（卡面1-4）
• 选择装饰（装饰1-4）

步骤 2：运行后端匹配

cd backend
python3 app.py

选择 [2] 正式运行，系统会：

1. 从飞书读取所有参与者数据
2. 运行 AI 评分 + 遗传算法匹配
3. 生成匹配文案
4. 自动保存结果到 match_results.json

步骤 3：启动后端 API 服务

cd backend
python3 run.py

或直接：

uvicorn main:app --host 0.0.0.0 --port 8000

API 服务地址：http://localhost:8000

步骤 4：启动前端服务

cd tree2
npm run dev

前端地址：http://localhost:5174

步骤 5：用户查询礼物

1. 用户访问前端页面
2. 等待圣诞树聚合（自动）
3. 点击 "🎁 查询礼物" 按钮
4. 输入报名时填写的邮箱
5. 查看礼物信息：
   • 收到的礼物名称和编号（如 GIFT-001）
   • 送礼人姓名
   • 匹配理由
   • 贺卡样式（送礼人选择的卡面和装饰）

---

四、API 接口说明

4.1 查询礼物接口

接口： GET /query-gift?email={email}

返回示例：

{
  "found": true,
  "user_name": "张三",
  "received_gift_id": "GIFT-001",
  "received_gift_name": "手工围巾",
  "received_from_name": "李四",
  "received_reason": "温暖的礼物...",
  "received_card_style": "卡面2",
  "received_decoration_style": "装饰3",
  "sent_gift_name": "复古键盘",
  "sent_to_name": "王五",
  "sent_reason": "科技感礼物..."
}

4.2 健康检查接口

接口： GET /health

返回示例：

{
  "status": "ok",
  "has_results": true,
  "total_participants": 40
}

---

五、生产部署

5.1 前端部署

构建生产版本：

cd tree2
npm run build

生成的文件在 tree2/dist/ 目录，可部署到：

• Vercel
• Netlify
• Nginx 静态服务器

Nginx 配置示例：

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/tree2/dist;
    index index.html;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 代理后端 API
    location /api/ {
        proxy_pass http://localhost:8000/;
    }
}

5.2 后端部署

使用 systemd 守护进程：

创建 /etc/systemd/system/gift-api.service：

[Unit]
Description=Gift Exchange API
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/backend
Environment="PATH=/usr/bin:/usr/local/bin"
ExecStart=/usr/bin/python3 -m uvicorn main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl start gift-api
sudo systemctl enable gift-api

---

六、故障排查

6.1 前端白屏

原因： node_modules 缓存损坏

解决：

cd tree2
rm -rf node_modules package-lock.json
npm install
npm run dev

6.2 后端 API Key 错误

错误信息： OpenAIError: The api_key client option must be set

解决： 检查 backend/.env 文件是否正确配置 AI_API_KEY

6.3 查询不到礼物

原因： 匹配结果未生成或邮箱不匹配

解决：

1. 确认已运行 python3 app.py 选择 [2] 正式运行
2. 检查 backend/match_results.json 文件是否存在
3. 确认输入的邮箱与飞书表格中的邮箱一致（不区分大小写）

6.4 CORS 跨域错误

解决： 后端已配置 CORS，如果仍有问题，检查 backend/main.py 中的 allow_origins 配置

---

七、文件结构

.
├── backend/                 # 后端代码
│   ├── app.py              # 交互式入口（匹配流程）
│   ├── main.py             # FastAPI 服务
│   ├── models.py           # 数据模型
│   ├── services.py         # 匹配算法
│   ├── feishu_reader.py    # 飞书数据读取
│   ├── config.py           # 配置管理
│   ├── .env                # 环境变量（需自行创建）
│   └── match_results.json  # 匹配结果（自动生成）
│
├── tree2/                   # 前端代码
│   ├── src/
│   │   ├── App.tsx         # 主应用
│   │   ├── GiftResult.tsx  # 礼物查询组件
│   │   ├── GiftBox.tsx     # 礼物盒动画
│   │   └── Letter.tsx      # 信件组件
│   ├── public/
│   │   ├── cards/          # 贺卡样式（card1-4.png）
│   │   └── decorations/    # 装饰样式（decoration1-4.png）
│   └── package.json
│
└── DEPLOYMENT.md            # 本文档

---

八、注意事项

1. AI API Key 有效期：确保 API Key 有足够的额度
2. 飞书 Token 有效期：tenant_access_token 有效期 2 小时，系统会自动刷新
3. 匹配结果保存：每次运行匹配会覆盖 match_results.json，建议备份
4. 邮箱匹配：查询时不区分大小写，但建议用户输入与报名时一致的邮箱
5. 贺卡资源：确保 tree2/public/cards/ 和 tree2/public/decorations/ 目录下有对应的图片文件

---

九、联系与支持

如有问题，请检查：

1. 后端日志输出
2. 浏览器控制台错误信息
3. match_results.json 文件内容

祝圣诞快乐！🎄