diff --git a/docs/本地验证检查清单.md b/docs/本地验证检查清单.md deleted file mode 100644 index 074747c43..000000000 --- a/docs/本地验证检查清单.md +++ /dev/null @@ -1,534 +0,0 @@ -# 小虾 SaaS 本地验证检查清单 - -**验证目标**：确保前后端真实联调通过，为上线做准备 -**预计时间**：30 分钟 - 1 小时 -**执行人**：老大 -**协助**：小虾 🦐 - ---- - -## 一、环境准备（10 分钟） - -### 1.1 检查系统依赖 - -```bash -# 检查 FFmpeg -ffmpeg -version - -# 检查 Python -python --version # 需要 3.12+ - -# 检查 Node.js -node --version # 需要 18+ -``` - -**预期**： -- ✅ FFmpeg 已安装 -- ✅ Python 3.12+ -- ✅ Node.js 18+ - ---- - -### 1.2 准备环境变量 - -**位置**：`F:\openclaw-saas\.env.development` - -**必须配置的项**： -```env -# 数据库 -DATABASE_URL=postgresql://xiaoxia:xiaoxia123@localhost:5432/xiaoxia_saas - -# Redis -REDIS_URL=redis://localhost:6379/0 - -# MinIO -MINIO_ENDPOINT=localhost:9000 -MINIO_ACCESS_KEY=minioadmin -MINIO_SECRET_KEY=minioadmin -MINIO_BUCKET=xiaoxia-saas -MINIO_SECURE=false -MINIO_PUBLIC_URL=http://localhost:9000 - -# JWT -JWT_SECRET_KEY=your-super-secret-key-change-in-production -JWT_ALGORITHM=HS256 -JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30 - -# Celery -CELERY_BROKER_URL=redis://localhost:6379/1 -CELERY_RESULT_BACKEND=redis://localhost:6379/2 -``` - -**检查方式**： -```bash -cd F:\openclaw-saas -cat .env.development -``` - ---- - -### 1.3 启动基础设施 - -**方式 1：Docker Compose（推荐）** -```bash -cd F:\openclaw-saas\infra\docker -docker-compose up -d postgres redis minio -``` - -**方式 2：本地服务** -- PostgreSQL 手动启动 -- Redis 手动启动 -- MinIO 手动启动 - -**验证**： -```bash -# 检查 PostgreSQL -psql -h localhost -U xiaoxia -d xiaoxia_saas -c "SELECT 1;" - -# 检查 Redis -redis-cli ping - -# 检查 MinIO -curl http://localhost:9000/minio/health/live -``` - -**预期**： -- ✅ PostgreSQL 连接成功 -- ✅ Redis 返回 PONG -- ✅ MinIO 返回 200 OK - ---- - -### 1.4 安装依赖 - -**后端依赖**： -```bash -cd F:\openclaw-saas -python -m venv .venv -.venv\Scripts\activate -pip install -r requirements.txt -``` - -**前端依赖**： -```bash -cd F:\openclaw-saas\apps\web -npm install -``` - -**预期时间**：5-10 分钟 - ---- - -### 1.5 初始化数据库 - -```bash -cd F:\openclaw-saas -.venv\Scripts\activate - -# 运行数据库迁移 -# （如果有 alembic） -# alembic upgrade head - -# 或者直接运行 SQL -psql -h localhost -U xiaoxia -d xiaoxia_saas -f migrations/001_initial_schema.sql -psql -h localhost -U xiaoxia -d xiaoxia_saas -f migrations/004_asset_management.sql -``` - -**验证**： -```bash -psql -h localhost -U xiaoxia -d xiaoxia_saas -c "\dt" -``` - -**预期**：看到所有表（users, workspaces, assets, generation_tasks 等） - ---- - -## 二、启动服务（5 分钟） - -### 2.1 启动 API 服务 - -**终端 1**： -```bash -cd F:\openclaw-saas -.venv\Scripts\activate -cd apps\api -python main.py -``` - -**预期输出**： -``` -INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) -``` - -**验证**： -```bash -curl http://localhost:8000/api/v1/health -``` - -**预期响应**： -```json -{"status": "healthy"} -``` - ---- - -### 2.2 启动 Worker 服务 - -**终端 2**： -```bash -cd F:\openclaw-saas -.venv\Scripts\activate -cd apps\worker -celery -A celery_app worker --loglevel=info -``` - -**预期输出**： -``` -[tasks] - . worker.generate_video -celery@LAPTOP ready. -``` - ---- - -### 2.3 启动前端服务 - -**终端 3**： -```bash -cd F:\openclaw-saas\apps\web -npm run dev -``` - -**预期输出**： -``` -VITE v5.x.x ready in xxx ms - - ➜ Local: http://localhost:5173/ -``` - ---- - -## 三、功能验证（15-30 分钟） - -### 3.1 用户注册/登录 - -**步骤**： -1. 打开浏览器：`http://localhost:5173` -2. 点击"注册" -3. 填写信息： - - 邮箱：`test@example.com` - - 密码：`Test123456` - - 用户名：`测试用户` -4. 点击注册 -5. 使用刚注册的账号登录 - -**检查点**： -- [ ] 注册成功 -- [ ] 登录成功 -- [ ] 跳转到工作空间页面 - -**预期时间**：2 分钟 - ---- - -### 3.2 创建工作空间和项目 - -**步骤**： -1. 点击"创建工作空间" -2. 填写名称：`测试工作空间` -3. 创建成功后，点击进入 -4. 点击"创建项目" -5. 填写项目名称：`测试项目` - -**检查点**： -- [ ] 工作空间创建成功 -- [ ] 项目创建成功 -- [ ] 能看到项目详情页 - -**预期时间**：2 分钟 - ---- - -### 3.3 上传素材 - -**步骤**： -1. 进入项目 -2. 点击"素材管理" -3. 点击"上传素材" -4. 选择 2-3 个视频文件（MP4 格式） -5. 等待上传完成 - -**检查点**： -- [ ] 上传进度条显示 -- [ ] 上传成功提示 -- [ ] 素材列表显示上传的文件 -- [ ] 能看到缩略图 - -**预期时间**：3-5 分钟（取决于文件大小） - -**调试检查**（如果上传失败）： -```bash -# 查看 API 日志（终端 1） -# 查看 MinIO 存储 -curl http://localhost:9000 # 应该能访问 -``` - ---- - -### 3.4 素材分类 - -**步骤**： -1. 在素材列表中选择一个素材 -2. 点击"分类" -3. 等待分类完成 - -**检查点**： -- [ ] 分类任务创建成功 -- [ ] 分类状态显示为"处理中" -- [ ] 分类完成后显示结果（如：scenic, product, person 等） - -**预期时间**：1-2 分钟 - -**调试检查**（如果分类卡住）： -```bash -# 查看 Worker 日志（终端 2） -# 应该看到分类任务执行 -``` - ---- - -### 3.5 创建生成任务 - -**步骤**： -1. 点击"视频生成" -2. 选择素材库 -3. 选择生成策略（如果有） -4. 点击"开始生成" - -**检查点**： -- [ ] 生成任务创建成功 -- [ ] 任务状态显示为"队列中"或"处理中" -- [ ] 进度条更新 - -**预期时间**：1 分钟 - ---- - -### 3.6 等待生成完成 - -**步骤**： -1. 刷新页面或等待自动刷新 -2. 查看任务状态 - -**检查点**： -- [ ] 任务状态变为"已完成" -- [ ] 进度条显示 100% -- [ ] 显示生成的视频数量 - -**预期时间**：2-5 分钟（取决于素材数量和大小） - -**调试检查**（如果生成失败）： -```bash -# 查看 Worker 日志（终端 2） -# 应该看到： -# - 素材下载 -# - FFmpeg 执行 -# - 文件上传 -``` - ---- - -### 3.7 查看生成结果 - -**步骤**： -1. 点击"生成结果" -2. 查看生成的视频列表 -3. 点击某个视频 - -**检查点**： -- [ ] 能看到视频列表 -- [ ] 显示缩略图 -- [ ] 显示视频元数据（时长、分辨率、大小） - -**预期时间**：1 分钟 - ---- - -### 3.8 下载视频 - -**步骤**： -1. 在视频详情页点击"下载" -2. 浏览器开始下载 -3. 下载完成后播放视频 - -**检查点**： -- [ ] 下载链接正常 -- [ ] 文件下载成功 -- [ ] 视频能正常播放 -- [ ] 视频内容是多个素材的拼接 - -**预期时间**：2-3 分钟 - -**最终验证**： -- 播放器能打开 -- 画面流畅 -- 没有黑屏或错误 - ---- - -## 四、问题记录 - -### 发现的问题 - -| 序号 | 功能点 | 问题描述 | 严重程度 | -|------|--------|----------|----------| -| 1 | | | P0/P1/P2 | -| 2 | | | | -| 3 | | | | - -**严重程度定义**： -- **P0**：阻断上线（如：无法登录、无法生成） -- **P1**：影响体验（如：UI 错位、加载慢） -- **P2**：小问题（如：文字错误、样式小瑕疵） - ---- - -## 五、验收标准 - -### ✅ 通过标准 - -**核心流程必须全部通过**： -- [x] 用户注册/登录 -- [x] 创建工作空间/项目 -- [x] 上传素材 -- [x] 素材分类 -- [x] 创建生成任务 -- [x] 生成完成 -- [x] 查看结果 -- [x] 下载视频 - -**无 P0 问题** - ---- - -### ⚠️ 有条件通过 - -**核心流程通过，但有 P1 问题**： -- 可以先修复后上线 -- 或者标注已知问题后上线 - ---- - -### ❌ 不通过 - -**任何核心流程失败，或有 P0 问题**： -- 必须修复后再验证 -- 不能上线 - ---- - -## 六、验证完成后 - -### ✅ 如果通过 - -**下一步**： -1. 小虾准备生产部署脚本 -2. 部署到服务器 -3. 绑定域名 -4. 开放访问 - -### ⚠️ 如果有问题 - -**下一步**： -1. 老大记录问题到上面的表格 -2. 小虾立刻修复 P0 问题 -3. P1/P2 问题排期修复 -4. 修复后再次验证 - ---- - -## 七、验证提示 - -### 💡 验证技巧 - -1. **别着急** - - 每个步骤都看清楚 - - 发现问题立刻截图 - -2. **多试几次** - - 如果某个功能失败，试 2-3 次 - - 确认是真的有问题，不是网络抖动 - -3. **记录详细** - - 问题描述要具体（不是"不行"，而是"点击后无响应"） - - 最好有截图或错误信息 - -4. **随时叫小虾** - - 遇到问题不确定的，立刻问我 - - 我可以远程看日志帮你诊断 - ---- - -## 八、常见问题 - -### Q1: MinIO 连不上 - -**症状**：上传素材失败 - -**解决**： -```bash -# 检查 MinIO 是否启动 -docker ps | grep minio - -# 重启 MinIO -docker restart minio -``` - ---- - -### Q2: Worker 没反应 - -**症状**：分类/生成任务一直"处理中" - -**解决**： -```bash -# 检查 Worker 日志（终端 2） -# 如果没有任务输出，重启 Worker -Ctrl+C -celery -A celery_app worker --loglevel=info -``` - ---- - -### Q3: 前端报错 - -**症状**：浏览器控制台有红色错误 - -**解决**： -- F12 打开开发者工具 -- 截图错误信息 -- 发给小虾 - ---- - -### Q4: 视频生成失败 - -**症状**：任务状态变为"失败" - -**解决**： -```bash -# 查看 Worker 日志（终端 2） -# 找到错误信息 -# 发给小虾 -``` - ---- - -**检查清单创建完成！** - -**老大，现在可以开始验证了！** - ---- - -**小虾待命中** 🦐 -**有问题随时叫我！**