系统架构文档
视频点播中心 - 完整架构与数据流
1. 核心数据实体
Video（视频）
video_id: 系统生成唯一ID
youtube_id: YouTube视频ID（唯一键）
title: 视频标题
category: 分类（public_talk/qa/topic/internal）
date: 发布日期
is_internal: 内部内容标志
TranscriptSegment（字幕段）
video_key: 关联Video.youtube_id
start_sec: 开始时间（秒）
end_sec: 结束时间
text: 字幕文本
lang: 语言（zh-Hans/zh-Hant/en...）
is_internal: 继承视频的内部标志
TextTeaching（文字开示）
title: 文章标题
date: 发布日期
series: 系列名称（可选）
tags: 标签（逗号分隔）
lang: 语言（BCP-47标准）
is_internal: 内部内容标志
cover_image_url: 封面图片
header_image_url: 顶部横幅
background_image_url: 背景图（祥云）
excerpt: 摘要
content_md: Markdown正文
source_ref: 来源引用
2. 字幕同步流程
外部字幕系统
↓ (POST请求)
syncTranscripts Webhook
↓
验证密钥 (X-SYNC-SECRET)
↓
删除旧字幕 (按video_key)
↓
批量插入新字幕 (bulkCreate)
↓
返回结果 {deleted_count, inserted_count}Webhook端点
POST /functions/syncTranscripts请求头: X-SYNC-SECRET: {webhook_secret}
请求体示例
{
"video_key": "YouTube视频ID",
"is_internal": false,
"segments": [
{
"start_sec": 0.0,
"end_sec": 5.5,
"lang": "zh",
"text": "字幕文本"
}
]
}成功响应 (200)
{
"success": true,
"deleted_count": 150,
"inserted_count": 200
}3. 安全验证机制
密钥验证
- 请求头 X-SYNC-SECRET 必须与环境变量 VOD_SYNC_SECRET 完全匹配
- 验证失败返回 401 Unauthorized
- 保存在 Base44 dashboard 环境变量中
数据验证
video_key: 必需，string 类型is_internal: 必需，boolean 类型segments: 必需，数组类型- 每个段落的
start_sec必须是非负数字 - 验证失败返回 400 Bad Request
4. 详细处理流程
步骤1: 删除旧字幕
- 使用 Base44 SDK 查询 TranscriptSegment 实体
- 过滤条件: video_key 等于传入的值
- 逐条删除匹配的记录
- 支持重试机制（最多3次，指数退避延迟）
步骤2: 插入新字幕
- 处理每个 segment:
- 生成 YouTube 跳转链接:
youtube.com/watch?v={id}&t={time}s - 生成 YouTube 嵌入链接:
youtube.com/embed/{id}?start={time} - 继承 is_internal 标志
- 生成 YouTube 跳转链接:
- 批量操作: 使用
bulkCreate()（批大小: 50条） - 批次间延迟: 500ms 避免服务器压力
- 错误处理: 单个批次失败不影响整体，继续处理下一批
重试机制
• 最大重试次数: 3次
• 初始延迟: 1000ms（删除）、2000ms（插入）
• 延迟策略: 指数退避 = 初始延迟 × 尝试次数
5. 日志记录示例
[syncTranscripts] Starting sync for video_key: 0rWQOYqnzyU, segments: 733
[syncTranscripts] Step 1: Deleting old segments...
[syncTranscripts] Found 150 old segments to delete
[syncTranscripts] Deleted 150 old segments
[syncTranscripts] Step 2: Inserting new segments...
[syncTranscripts] Inserted batch 1, total: 50
[syncTranscripts] Inserted batch 2, total: 100
[syncTranscripts] Sync completed
[syncTranscripts] Final counts - Deleted: 150, Inserted: 733
6. 部署和配置
环境变量
BASE44_APP_ID: Base44 应用ID（自动设置）
VOD_SYNC_SECRET: Webhook 同步密钥（需手动设置）
外部系统集成
• 端点: POST /functions/syncTranscripts
• 认证: X-SYNC-SECRET 头部密钥
• 推荐批次: 每次 50-200 个字幕段落
7. 故障排除
| 错误 | 原因 | 解决方案 |
|---|---|---|
401 | X-SYNC-SECRET 不匹配 | 检查环境变量是否正确设置 |
400 | 数据格式不符 | 检查 segments 数组结构 |
405 | API 端点错误 | 检查请求方法和 URL |
504 | 同步超时 | 减小 segments 数量，分多次调用 |
8. 页面架构与功能
公开页面
Home: 首页展示
VideoLibrary: 视频库（分类/年份筛选）
VideoDetail: 视频详情（播放器+字幕）
TextLibrary: 文字开示库（系列/语言筛选）
TextDetail: 文字详情（文化机构风格）
UnifiedSearch: 全站搜索（字幕+文字）
About: 关于页面
内部页面（需口令）
InternalPortal: 旧内部入口（已移除）
InternalTexts: 旧内部文字页（已移除）
管理页面（仅管理员）
VideoManagement: 视频管理（CRUD）
TextManagement: 文字管理（含CSV导入）
9. 三档响应式布局
手机端（< 768px）
- 单栏布局，全屏内容
- 详情页全屏显示，带返回按钮
- 保留搜索状态与滚动位置
普通桌面（768px - 1599px）
- 搜索页：左栏结果列表 + 右栏详情
- 正文阅读区 max-width 820px
- 居中对齐，充分留白
超宽屏（≥ 1600px）
- 三栏布局：搜索 + 详情 + 辅助栏
- 文字详情右侧显示目录、相关推荐
- 整体限宽 max-width 1600px 居中
10. 核心特色功能
🔍 智能全站搜索
• 同时搜索视频字幕与文字开示
• 按系列/标题聚合结果
• 高亮关键词匹配
• 保持搜索状态与滚动位置
📝 文化机构出版物风格
• Markdown内容渲染（h2/h3自动生成目录）
• Serif标题 + Sans正文，行距1.85
• 顶部横幅 + 祥云背景（仅顶部25-30%）
• 多语言切换（同系列/标题）
• 相关推荐与文献元信息
🔐 双层安全控制
• is_internal字段区分公开/内部内容
• 内部内容需口令验证（sessionStorage）
• 管理功能仅管理员可见（role检查）
• Webhook密钥验证（X-SYNC-SECRET）
🌓 暗黑模式支持
• 全站深色主题切换
• 根据系统偏好/时间自动切换
• 本地存储用户偏好
最后更新: 2026-02-25 | 系统版本: 2.0（含文字开示模块）