Skip to content

IMPLEMENTATION.md

Latest commit

 

History

History
197 lines (151 loc) · 4.9 KB

IMPLEMENTATION.md

File metadata and controls

197 lines (151 loc) · 4.9 KB

飞书广告系统集成实现完成

概述

已成功实现通过飞书服务端 API 获取多维表格中的广告内容，包括完整的后端服务器和前端集成。

已实现的功能

后端 API 服务器 (api/)

  1. 完整的 Node.js + Express 服务器

    • 位置: api/server.js
    • 端口: 3000（可配置）
    • 支持跨域请求（CORS）

  2. 飞书 API 集成

    • ✅ 自动获取和缓存访问令牌
    • ✅ 支持分页获取大量记录
    • ✅ 从多维表格读取广告数据
    • ✅ 安全的凭证管理（存储在 .env 文件）

  3. 数据处理

    • ✅ 字段映射（支持多种字段名变体）
    • ✅ 数据验证和过滤
    • ✅ 按优先级自动排序
    • ✅ 日期范围检查

  4. API 端点

    • GET /api/ads - 获取所有活跃广告
    • GET /api/ads/:id - 获取特定广告
    • GET /health - 健康检查

前端集成 (script.js)

  1. 异步数据获取

    • ✅ 从后端 API 获取广告数据
    • ✅ 5秒超时保护
    • ✅ 自动降级到备用广告

  2. 广告展示

    • ✅ 支持三种广告类型（iframe、banner、card）
    • ✅ 优先级排序
    • ✅ 日期范围过滤
    • ✅ 用户关闭记忆（sessionStorage）

  3. 错误处理

    • ✅ API 失败时使用备用广告
    • ✅ 详细的错误日志
    • ✅ 优雅的降级机制

飞书多维表格字段支持

系统支持以下字段（包含多种命名变体）：

字段功能 支持的字段名 类型 必填
广告ID id, ad_id 文本 ✅
广告标题 title, ad_title 文本 ⭕
广告链接 url, ad_url, link URL ✅
广告内容 content, ad_content, description 文本 ⭕
广告图片 imageUrl, image_url, ad_image URL ⭕
广告标签 tag, ad_tag, label 文本 ⭕
广告类型 type 单选 ⭕
优先级 priority 单选 ⭕
开始时间 startDate, start_date, start_time 日期 ⭕
截止时间 endDate, end_date, end_time 日期 ⭕
是否启用 enabled 复选框 ⭕

配置步骤

1. 飞书开放平台配置

  1. 登录飞书开放平台: https://open.feishu.cn/
  2. 创建企业自建应用
  3. 获取 App ID 和 App Secret
  4. 申请权限: bitable:app 或 bitable:app:readonly
  5. 获取多维表格的 App Token 和 Table ID

2. 后端配置

cd api
npm install
cp .env.example .env
# 编辑 .env 文件，填入飞书凭证
npm start

3. 前端配置

前端代码已配置好，会自动从 /api/ads 获取数据。如果 API 不可用，会自动使用备用广告。

测试

运行自动化测试

cd api
npm test

测试内容：

  • ✅ API 健康检查
  • ✅ 广告端点响应
  • ✅ CORS 配置
  • ✅ 前端集成检查

手动测试

  1. 启动后端服务器:

    cd api
npm start

  2. 打开浏览器访问 test-ads.html 进行可视化测试

  3. 测试 API 端点:

    curl http://localhost:3000/health
curl http://localhost:3000/api/ads

部署建议

生产环境部署

  1. 使用 PM2:

    npm install -g pm2
cd api
pm2 start server.js --name "ad-api"
pm2 startup
pm2 save

  2. 使用 Docker:

    docker build -t ad-api ./api
docker run -d -p 3000:3000 --env-file ./api/.env ad-api

  3. 配置 Nginx 反向代理:

    location /api/ {
    proxy_pass http://localhost:3000/api/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

安全特性

✅ API 密钥存储在服务器端，不暴露给前端
✅ CORS 配置限制允许的来源
✅ iframe 沙箱限制潜在风险
✅ 输入验证和数据过滤
✅ 访问令牌自动缓存和刷新
✅ 错误处理和降级机制
✅ 无已知安全漏洞（npm audit 检查通过）

文件清单

新增文件

  • api/server.js - 后端 API 服务器
  • api/package.json - 依赖配置
  • api/.env.example - 环境变量示例
  • api/.gitignore - Git 忽略配置
  • api/README.md - API 详细文档
  • api/test.js - 自动化测试脚本
  • test-ads.html - 可视化测试页面

修改文件

  • script.js - 更新广告系统集成逻辑
  • AD_SYSTEM_README.md - 更新文档，添加实现细节

下一步

  1. ✅ 配置真实的飞书凭证（替换 api/.env 中的测试值）
  2. ✅ 在飞书中创建多维表格并填充广告数据
  3. ✅ 部署后端 API 到生产服务器
  4. ✅ 更新前端 apiEndpoint 配置（如果需要）
  5. ✅ 监控 API 性能和错误日志

支持

如遇问题，请参考：

  • api/README.md - 详细的 API 文档
  • AD_SYSTEM_README.md - 完整的系统文档
  • 后端日志输出
  • 浏览器控制台错误信息

实现完成时间: 2026-02-12
版本: 1.0.0
状态: ✅ 已完成并通过测试