欢迎页开发计划

📁 文件说明

26.1.28-欢迎页开发计划/
├── plan.md                    # 详细实现计划
├── brainstorm.md              # 头脑风暴与设计探索
├── README.md                  # 本文件
├── upload-welcome-video.sh    # 视频上传脚本 ✅ 可用
├── deploy.sh                  # 参考部署脚本
├── video/                     # 视频资源目录
│   └── welcome-bg.mp4        # ✅ 背景视频已添加
└── img/                       # 图片资源目录 (待添加)

---

🎬 快速开始

上传背景视频到七牛云

方式 1: 使用专用脚本 (推荐)

# 进入计划目录
cd docs/plan/26.1.28-欢迎页开发计划

# 直接上传
./upload-welcome-video.sh

# 注意: 七牛云空间名称为 ipadbiz

方式 2: 使用通用上传工具

# 上传视频
pnpm run upload:qiniu video/welcome-bg.mp4 mlaj/video/welcome-bg.mp4

上传成功后的 URL ✅

视频: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
封面: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001

文件信息:

• 大小: 17.57MB (18420585 字节)
• Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH
• MIME: video/mp4

更新环境变量

将以下配置添加到 .env.development 和 .env.production:

VITE_WELCOME_PAGE_ENABLED=true
VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4

---

📋 开发进度

✅ 已完成

• 背景视频文件准备 (welcome-bg.mp4)
• 视频上传到七牛云 ✅ (17.57MB, Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH)
• 通用上传工具 (scripts/upload-to-qiniu.sh)
• 详细实现计划 (plan.md)
• 头脑风暴文档 (brainstorm.md)
• 功能入口列表确定（课程、活动、时光机、我的）

⏳ 待开发

• VideoBackground 组件
• WelcomeContent 组件
• WelcomeEntryItem 组件
• 路由与首次访问逻辑
• 功能入口配置实现

❌ 待确认

• 页面效果图 (设计稿)
• 页面布局细节 (顶部/底部元素)

---

📖 文档索引

1. brainstorm.md - 头脑风暴与设计探索

   • 需求探索过程
   • 架构设计探索
   • 核心组件设计
   • 七牛云上传工具设计
   • 风险识别与应对
   • 关键决策总结

2. plan.md - 详细实现计划

   • 6个开发阶段
   • 完整代码示例
   • 测试清单
   • 技术要点
   • 使用指南

---

🔧 开发工具

调试欢迎页

重置欢迎页标志:

# URL 参数方式
http://localhost:5173/?reset_welcome=true

# 控制台方式
window.resetWelcomeFlag()
location.reload()

直接访问欢迎页:

window.showWelcome()

---

🎯 核心特性

视频背景

• ✅ 循环播放星空宇宙主题视频
• ✅ 移动端和 PC 端自适应
• ✅ 自动生成封面图 (七牛云视频处理)
• ✅ 降级方案 (视频加载失败时使用静态图)

首次访问检测

• ✅ localStorage 标志位
• ✅ 路由守卫自动拦截
• ✅ 调试工具支持

功能入口

• ✅ 四个核心功能入口已确定
• ⏳ 持续循环的呼吸缩放动效
• ⏳ 2-3列网格布局
• ⏳ 配置化入口列表

功能入口详情:

1. 课程中心 (/courses) - 探索精选课程
2. 活动中心 (/activity) - 精彩活动不容错过
3. 时光机 (/recall/login) - 回顾学习历程
4. 个人中心 (/profile) - 管理您的账户

---

📞 常见问题

Q: 视频上传失败?

A: 检查是否需要使用代理:

USE_PROXY=true PROXY_HOST="127.0.0.1:7890" ./upload-welcome-video.sh

Q: 封面图如何生成?

A: 自动从视频中提取第一帧:

const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001`

Q: 如何测试欢迎页?

A: 重置标志后刷新页面:

window.resetWelcomeFlag()
location.reload()

---

最后更新: 2026-01-28