Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
311e168b 1 parent 9affcbda

docs(welcome): 完善欢迎页开发计划和文档 

- 新增 README.md 项目说明文档，包含快速开始指南和常见问题
- 新增 upload-welcome-video.sh 视频上传脚本
- 更新 plan.md：采用七牛云视频处理参数自动生成封面图
- 更新 brainstorm.md：记录封面图方案探索过程
- 更新 .gitignore：忽略视频文件（*.mp4, *.mov 等）
- 更新 .env.development：切换代理服务器配置

技术亮点：
- 使用七牛云 ?vframe/jpg/offset/0.001 参数自动提取视频首帧
- 只需上传一个视频文件，无需单独准备封面图
- 视频文件已准备（welcome-bg.mp4），待上传到七牛云

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Inline Side-by-side
Showing 6 changed files with 401 additions and 44 deletions
###
# @Date: 2025-03-20 23:40:15
# @Date: 2025-03-20 23:40:15
# @LastEditors: hookehuyr hookehuyr@gmail.com
# @LastEditTime: 2026-01-18 11:32:59
# @LastEditTime: 2026-01-26 09:51:29
# @FilePath: /mlaj/.env.development
# @Description: 文件描述
# @Description: 开发环境配置文件
###
# 资源公共路径
VITE_BASE = /
......@@ -23,10 +23,10 @@ VITE_PIN =
# 反向代理服务器地址
# VITE_PROXY_TARGET = https://oa.anxinchashi.com/
# VITE_PROXY_TARGET = http://behalo.onwall.cn/
# VITE_PROXY_TARGET = http://oa-dev.onwall.cn/
VITE_PROXY_TARGET = http://oa-dev.onwall.cn/
# VITE_PROXY_TARGET = https://oa.behalo.cc/
# VITE_PROXY_TARGET = https://www.wxgzjs.cn/
VITE_PROXY_TARGET = https://wxm.behalo.cc/
# VITE_PROXY_TARGET = https://wxm.behalo.cc/
# PC端地址
VITE_MOBILE_URL = http://localhost:5173/
......
......@@ -33,3 +33,14 @@ mlaj
.specify
.trae
.github
# Video files (large media assets)
*.mp4
*.mov
*.avi
*.mkv
*.flv
*.webm
# Plan directory video resources
docs/plan/*/video/
......
# 欢迎页开发计划
## 📁 文件说明
```
26.1.28-欢迎页开发计划/
├── plan.md # 详细实现计划
├── brainstorm.md # 头脑风暴与设计探索
├── README.md # 本文件
├── upload-welcome-video.sh # 视频上传脚本 ✅ 可用
├── deploy.sh # 参考部署脚本
├── video/ # 视频资源目录
│ └── welcome-bg.mp4 # ✅ 背景视频已添加
└── img/ # 图片资源目录 (待添加)
```
---
## 🎬 快速开始
### 上传背景视频到七牛云
**方式 1: 使用专用脚本 (推荐)**
```bash
# 进入计划目录
cd docs/plan/26.1.28-欢迎页开发计划
# 直接上传
./upload-welcome-video.sh
# 使用代理上传
USE_PROXY=true PROXY_HOST="127.0.0.1:7890" ./upload-welcome-video.sh
```
**方式 2: 使用通用上传工具**
```bash
# 初始化七牛账户 (首次使用)
pnpm run qiniu:init
# 上传视频
pnpm run upload:qiniu video/welcome-bg.mp4 mlaj/video/welcome-bg.mp4
# 使用代理上传
USE_PROXY=true 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
```
### 更新环境变量
将以下配置添加到 `.env.development` 和 `.env.production`:
```bash
VITE_WELCOME_PAGE_ENABLED=true
VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
```
---
## 📋 开发进度
### ✅ 已完成
- [x] 背景视频文件准备 (`welcome-bg.mp4`)
- [x] 上传工具脚本 (`upload-welcome-video.sh`)
- [x] 详细实现计划 (`plan.md`)
- [x] 头脑风暴文档 (`brainstorm.md`)
### ⏳ 待开发
- [ ] 七牛云通用上传工具 (`scripts/upload-to-qiniu.sh`)
- [ ] VideoBackground 组件
- [ ] WelcomeContent 组件
- [ ] 路由与首次访问逻辑
- [ ] 功能入口配置
### ❌ 待确认
- [ ] 页面效果图 (设计稿)
- [ ] 功能入口列表
- [ ] 页面布局细节 (顶部/底部元素)
---
## 📖 文档索引
1. **brainstorm.md** - 头脑风暴与设计探索
- 需求探索过程
- 架构设计探索
- 核心组件设计
- 七牛云上传工具设计
- 风险识别与应对
- 关键决策总结
2. **plan.md** - 详细实现计划
- 6个开发阶段
- 完整代码示例
- 测试清单
- 技术要点
- 使用指南
---
## 🔧 开发工具
### 调试欢迎页
**重置欢迎页标志:**
```bash
# URL 参数方式
http://localhost:5173/?reset_welcome=true
# 控制台方式
window.resetWelcomeFlag()
location.reload()
```
**直接访问欢迎页:**
```javascript
window.showWelcome()
```
---
## 🎯 核心特性
### 视频背景
- ✅ 循环播放星空宇宙主题视频
- ✅ 移动端和 PC 端自适应
- ✅ 自动生成封面图 (七牛云视频处理)
- ✅ 降级方案 (视频加载失败时使用静态图)
### 首次访问检测
- ✅ localStorage 标志位
- ✅ 路由守卫自动拦截
- ✅ 调试工具支持
### 功能入口
- ⏳ 持续循环的呼吸缩放动效
- ⏳ 2-3列网格布局
- ⏳ 配置化入口列表
---
## 📞 常见问题
### Q: 视频上传失败?
**A:** 检查是否需要使用代理:
```bash
USE_PROXY=true PROXY_HOST="127.0.0.1:7890" ./upload-welcome-video.sh
```
### Q: 封面图如何生成?
**A:** 自动从视频中提取第一帧:
```javascript
const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001`
```
### Q: 如何测试欢迎页?
**A:** 重置标志后刷新页面:
```javascript
window.resetWelcomeFlag()
location.reload()
```
---
*最后更新: 2026-01-28*
......@@ -285,6 +285,54 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
---
### 视频封面图方案探索
**原始方案问题:**
- 需要单独准备和上传封面图片
- 封面图可能与视频内容不匹配
- 增加资源管理成本
**改进方案: 使用七牛云视频处理参数**
**方案选择:**
```javascript
// 自动从视频中提取第一帧作为封面
const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001`
// 完整示例
const videoUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4'
const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001'
```
**七牛云视频帧处理参数:**
- `vframe/jpg/offset/0.001` - 从视频第 0.001 秒截取一帧作为 JPG
- 官方文档: https://developer.qiniu.com/dora/1316/video-frame-operation
**高级参数 (可选):**
```javascript
// 指定截取时间点
?vframe/jpg/offset/1
// 指定输出尺寸
?vframe/jpg/offset/0.001/w/1920/h/1080
// 指定图片质量
?vframe/jpg/offset/0.001/quality/85
```
**优势:**
- ✅ 只需上传一个视频文件
- ✅ 封面图与视频内容一致
- ✅ 减少资源管理成本
- ✅ 支持动态调整参数
**实现位置:**
- `VideoBackground.vue` 组件内部使用 computed 自动生成
- 环境变量只需配置 `VITE_WELCOME_VIDEO_URL`
- 移除 `VITE_WELCOME_VIDEO_POSTER` 配置项
---
## 风险识别与应对
### 技术风险
......@@ -326,8 +374,9 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
**应对:**
- 限制文件大小 < 10MB
- 提供封面图在视频加载前显示
- 添加加载进度提示
- 使用七牛云视频处理参数自动生成封面图 (`?vframe/jpg/offset/0.001`)
- 封面图在视频加载前显示，提升用户体验
- 可选: 指定封面图质量和尺寸优化加载速度
- 考虑视频分段加载或 M3U8
---
......@@ -368,8 +417,8 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
根据需求文档，以下事项需要确认：
1. ❌ **背景视频文件** - `video/?.mp4` 文件名未知
2. ❌ **页面效果图** - `img/` 文件夹为空
1. ✅ **背景视频文件** - `video/welcome-bg.mp4` 已添加
2. ❌ **页面效果图** - `img/` 文件夹为空，需要设计稿确认布局
3. ❌ **功能入口列表** - 具体跳转地址未知
4. ❌ **页面布局细节** - 顶部/底部是否需要元素（Logo、标语、按钮等）
......@@ -387,6 +436,7 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
| 动效风格 | 持续循环 | 符合主题，视觉冲击力强 |
| 架构设计 | 组件化 | 职责清晰，易维护 |
| 上传工具 | 通用化 | 支持多种场景复用 |
| 封面图方案 | 七牛云自动生成 | 减少资源管理，内容一致 |
---
......
......@@ -106,12 +106,13 @@ scripts/qiniu/configs/
#### 步骤 3: 准备视频资源
- 在 `docs/plan/26.1.28-欢迎页开发计划/video/` 添加背景视频
- 建议规格:
- 分辨率: 1920x1080 (1080p)
- 编码格式: H.264
- 时长: 10-20秒循环视频
- 文件大小: < 10MB
**视频文件:** `docs/plan/26.1.28-欢迎页开发计划/video/welcome-bg.mp4` ✅ 已添加
**建议规格:**
- 分辨率: 1920x1080 (1080p)
- 编码格式: H.264
- 时长: 10-20秒循环视频
- 文件大小: < 10MB
#### 步骤 4: 上传资源到七牛云
......@@ -120,9 +121,15 @@ scripts/qiniu/configs/
chmod +x scripts/upload-to-qiniu.sh
./scripts/upload-to-qiniu.sh init
# 上传视频(如果有代理)
# 上传欢迎页背景视频
USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
./scripts/upload-to-qiniu.sh video/background.mp4 mlaj/video/welcome-background.mp4
./scripts/upload-to-qiniu.sh 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
```
#### 步骤 5: 更新环境变量
......@@ -131,17 +138,23 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
```bash
# 欢迎页功能开关
VITE_WELCOME_PAGE_ENABLED=true
VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-background.mp4
VITE_WELCOME_VIDEO_POSTER=https://cdn.ipadbiz.cn/mlaj/images/welcome-poster.jpg
# 视频资源 URL
# 封面图会自动通过七牛云处理参数生成: videoUrl + ?vframe/jpg/offset/0.001
VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
```
**`.env.production`:**
```bash
VITE_WELCOME_PAGE_ENABLED=true
VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-background.mp4
VITE_WELCOME_VIDEO_POSTER=https://cdn.ipadbiz.cn/mlaj/images/welcome-poster.jpg
VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
```
**说明:**
- 只需配置视频 URL，封面图会自动从视频中提取第一帧生成
- 七牛云处理参数: `?vframe/jpg/offset/0.001` 表示从视频第 0.001 秒截取一帧作为 JPG 图片
- 降级方案: 视频加载失败时自动使用该封面图作为静态背景
---
### 第 1 阶段: 通用上传工具开发 (优先级: 🔴 高)
......@@ -390,7 +403,7 @@ USE_PROXY=true pnpm run upload:qiniu ./test/file.mp4 mlaj/video/test.mp4
ref="videoRef"
class="video-element"
:src="videoSrc"
:poster="poster"
:poster="posterUrl"
:autoplay="autoplay"
:loop="loop"
:muted="muted"
......@@ -406,13 +419,13 @@ USE_PROXY=true pnpm run upload:qiniu ./test/file.mp4 mlaj/video/test.mp4
<div
v-if="showFallback"
class="video-fallback"
:style="{ backgroundImage: `url(${poster || videoSrc})` }"
:style="{ backgroundImage: `url(${posterUrl})` }"
></div>
</div>
</template>
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import { ref, computed, onMounted, onUnmounted } from 'vue'
const props = defineProps({
/** 视频源 URL */
......@@ -420,7 +433,7 @@ const props = defineProps({
type: String,
required: true
},
/** 封面图 URL */
/** 封面图 URL (可选，不传则自动从视频生成) */
poster: {
type: String,
default: ''
......@@ -451,6 +464,20 @@ const videoRef = ref(null)
const isLoading = ref(true)
const showFallback = ref(false)
/**
* 自动生成封面图 URL
* 如果没有传入 poster，使用七牛云视频处理参数从视频中提取第一帧
* 处理参数: ?vframe/jpg/offset/0.001 表示从视频第 0.001 秒截取一帧作为 JPG
*/
const posterUrl = computed(() => {
if (props.poster) {
return props.poster
}
// 从视频 URL 自动生成封面图
// 七牛云视频处理: https://developer.qiniu.com/dora/1316/video-frame-operation
return `${props.videoSrc}?vframe/jpg/offset/0.001`
})
// 视频可以播放时
const onCanPlay = () => {
isLoading.value = false
......@@ -555,7 +582,6 @@ defineExpose({
<template>
<VideoBackground
:video-src="videoUrl"
:poster="posterUrl"
autoplay
loop
muted
......@@ -565,8 +591,9 @@ defineExpose({
<script setup>
import VideoBackground from '@/components/effects/VideoBackground.vue'
const videoUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-background.mp4'
const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/images/welcome-poster.jpg'
const videoUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4'
// poster 会自动生成: videoUrl + ?vframe/jpg/offset/0.001
// 即: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001
</script>
```
......@@ -587,7 +614,6 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/images/welcome-poster.jpg'
<VideoBackground
v-if="videoUrl"
:video-src="videoUrl"
:poster="posterUrl"
/>
<!-- 内容区域 -->
......@@ -597,19 +623,13 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/images/welcome-poster.jpg'
<script setup>
import { computed } from 'vue'
import { useRoute } from 'vue-router'
import VideoBackground from '@/components/effects/VideoBackground.vue'
import WelcomeContent from '@/components/welcome/WelcomeContent.vue'
const route = useRoute()
const videoUrl = computed(() => {
return import.meta.env.VITE_WELCOME_VIDEO_URL || ''
})
const posterUrl = computed(() => {
return import.meta.env.VITE_WELCOME_VIDEO_POSTER || ''
})
// poster 会自动从 videoUrl 生成，无需单独配置
</script>
<style scoped>
......@@ -1075,12 +1095,14 @@ window.showWelcome()
### 使用上传工具
**当前视频文件:** `docs/plan/26.1.28-欢迎页开发计划/video/welcome-bg.mp4`
```bash
# 单文件上传
pnpm run upload:qiniu ./local/video.mp4 mlaj/video/welcome-background.mp4
# 上传欢迎页背景视频
pnpm run upload:qiniu video/welcome-bg.mp4 mlaj/video/welcome-bg.mp4
# 使用代理上传
USE_PROXY=true pnpm run upload:qiniu ./local/video.mp4 mlaj/video/welcome-background.mp4
USE_PROXY=true pnpm run upload:qiniu video/welcome-bg.mp4 mlaj/video/welcome-bg.mp4
```
### 视频规格建议
......@@ -1089,7 +1111,6 @@ USE_PROXY=true pnpm run upload:qiniu ./local/video.mp4 mlaj/video/welcome-backgr
- 编码格式: H.264
- 时长: 10-20秒循环
- 文件大小: < 10MB
```
#### 步骤 3: 部署到开发环境
......@@ -1145,17 +1166,68 @@ transform: scale(1.08);
will-change: transform, opacity;
```
### 3. 降级方案
### 3. 七牛云视频处理 - 自动生成封面图
**封面图自动生成:**
```javascript
// VideoBackground 组件内部实现
const posterUrl = computed(() => {
if (props.poster) {
return props.poster
}
// 从视频 URL 自动生成封面图
return `${props.videoSrc}?vframe/jpg/offset/0.001`
})
```
**七牛云视频帧处理参数说明:**
- `?vframe/jpg/offset/0.001` - 从视频第 0.001 秒截取一帧作为 JPG 图片
- 完整示例: `https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001`
- 官方文档: https://developer.qiniu.com/dora/1316/video-frame-operation
**高级参数 (可选):**
```javascript
// 指定截取时间点 (第 1 秒)
https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/1
// 指定输出尺寸 (1920x1080)
https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/h/1080
// 指定图片质量 (质量 85)
https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/quality/85
// 组合使用
https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/h/1080/quality/85
```
**优势:**
- ✅ 只需上传一个视频文件，无需单独准备封面图
- ✅ 封面图与视频内容一致，不会出现不匹配
- ✅ 减少资源管理成本
- ✅ 支持动态调整截取时间和图片质量
---
### 4. 降级方案
```vue
<!-- 视频加载失败时显示静态背景图 -->
<div
v-if="showFallback"
class="video-fallback"
:style="{ backgroundImage: `url(${poster})` }"
:style="{ backgroundImage: `url(${posterUrl})` }"
></div>
```
**降级触发条件:**
1. 视频加载失败 (网络错误、格式不支持)
2. 视频自动播放被阻止 (iOS Safari 政策)
3. 视频解码失败
**降级方案:**
- 使用自动生成的封面图作为静态背景
- 保证用户始终能看到背景内容
---
## 风险与注意事项
......@@ -1172,7 +1244,11 @@ will-change: transform, opacity;
3. **视频加载性能**
- 文件过大导致加载缓慢
- 解决方案: 限制文件大小 < 10MB，提供封面图
- 解决方案:
- 限制文件大小 < 10MB
- 使用七牛云自动生成封面图作为 loading 状态
- 支持封面图质量参数优化加载速度
- 考虑使用 CDN 加速
4. **七牛云代理问题**
- 需要挂代理才能访问
......@@ -1207,7 +1283,7 @@ will-change: transform, opacity;
## 待确认事项
1. ❌ **背景视频文件** - 需要提供视频资源
1. ✅ **背景视频文件** - `video/welcome-bg.mp4` 已添加
2. ❌ **页面效果图** - 需要设计稿确认布局
3. ❌ **功能入口列表** - 需要确认具体入口和跳转地址
4. ❌ **页面布局细节** - 顶部/底部是否需要元素
......
#!/usr/bin/env bash
# 欢迎页视频上传脚本
# 用途: 将 video/welcome-bg.mp4 上传到七牛云
set -euo pipefail
# 项目根目录
repo_root="$(cd "$(dirname "$0")" && pwd)"
video_file="$repo_root/video/welcome-bg.mp4"
remote_path="mlaj/video/welcome-bg.mp4"
log_info() {
echo "[upload] $1"
}
# 检查视频文件是否存在
if [ ! -f "$video_file" ]; then
echo "错误: 视频文件不存在 $video_file"
exit 1
fi
log_info "准备上传欢迎页背景视频..."
log_info "本地文件: $video_file"
log_info "远程路径: $remote_path"
# 调用通用上传工具
upload_script="$repo_root/../../scripts/upload-to-qiniu.sh"
if [ ! -f "$upload_script" ]; then
echo "错误: 上传脚本不存在 $upload_script"
echo "请先创建 scripts/upload-to-qiniu.sh"
exit 1
fi
# 使用代理上传(如果设置了环境变量)
if [ "${USE_PROXY:-}" = "true" ]; then
log_info "使用代理: ${PROXY_HOST:-127.0.0.1:7890}"
fi
# 执行上传
bash "$upload_script" "$video_file" "$remote_path"
log_info "✅ 上传完成!"
log_info "视频 URL: https://cdn.ipadbiz.cn/$remote_path"
log_info "封面 URL: https://cdn.ipadbiz.cn/$remote_path?vframe/jpg/offset/0.001"