xiaoxia-saas/docs/本地验证检查清单.md

# 小虾 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
OSS_ENDPOINT=localhost:9000
OSS_ACCESS_KEY_ID=minioadmin
OSS_ACCESS_KEY_SECRET=minioadmin
OSS_BUCKET_NAME=xiaoxia-saas
OSS_SECURE=false
OSS_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）
# 找到错误信息
# 发给小虾
```

---

**检查清单创建完成！**

**老大，现在可以开始验证了！**

---

**小虾待命中** 🦐  
**有问题随时叫我！**