flnxi-Wu/docs/deployment/pre-deployment-checklist.md

# 模板系统优化 - 部署前检查清单

## 概述

本文档提供了部署模板系统优化到测试和生产环境的完整检查清单。

## 部署前准备

### 1. 代码检查

- [ ] 所有代码已提交到Git仓库
- [ ] 所有单元测试通过（118个测试用例）
- [ ] 代码已通过TypeScript类型检查
- [ ] 代码已通过ESLint检查
- [ ] 核心功能代码覆盖率达标（>80%）

```bash
# 运行检查
npm run check
npm test
```

### 2. 数据库准备

- [ ] 已创建数据库备份
- [ ] 已检查数据库迁移文件
- [ ] 已在本地测试数据库迁移
- [ ] 已准备回滚脚本

```bash
# 检查迁移文件
ls prisma/migrations

# 验证schema
npm run prisma:validate
```

### 3. 数据迁移准备

- [ ] 已准备数据迁移脚本（migrate-template-data.ts）
- [ ] 已准备数据验证脚本（verify-template-data.ts）
- [ ] 已在测试数据上验证迁移脚本
- [ ] 已准备迁移失败的回滚方案

```bash
# 测试迁移脚本（在测试环境）
npm run migrate:template-data

# 验证数据完整性
npm run verify:template-data
```

### 4. 文档检查

- [ ] API文档已更新（docs/api/template-system-api.md）
- [ ] 用户手册已更新（docs/user-guide/template-system-guide.md）
- [ ] 部署文档已准备
- [ ] 回滚文档已准备

## 测试环境部署

### 步骤 1: 备份数据库

```bash
# PostgreSQL备份示例
pg_dump -h <host> -U <user> -d <database> -F c -b -v -f backup_$(date +%Y%m%d_%H%M%S).dump

# 或使用Prisma Studio导出关键数据
npm run prisma:studio
```

### 步骤 2: 运行数据库迁移

```bash
# 生成Prisma客户端
npm run prisma:generate

# 应用数据库迁移
npx prisma migrate deploy

# 验证迁移结果
npm run verify:template-data
```

### 步骤 3: 运行数据迁移脚本

```bash
# 迁移旧数据
npm run migrate:template-data

# 再次验证数据完整性
npm run verify:template-data
```

### 步骤 4: 部署新代码

```bash
# 构建应用
npm run build

# 启动应用
npm start

# 或使用Docker
docker-compose up -d
```

### 步骤 5: 执行冒烟测试

#### 5.1 模板管理测试

- [ ] 访问模板管理页面（/admin/templates）
- [ ] 创建新模板
- [ ] 编辑模板字段
- [ ] 测试字段拖拽排序
- [ ] 测试select字段选项管理
- [ ] 删除测试模板

#### 5.2 素材上传测试

- [ ] 访问素材上传页面
- [ ] 选择模板
- [ ] 填写自定义字段
- [ ] 上传素材文件
- [ ] 验证素材详情页显示

#### 5.3 字段池同步测试

- [ ] 创建带有select字段的模板
- [ ] 验证字段池自动同步
- [ ] 访问分类管理页面
- [ ] 验证字段和选项显示正确

#### 5.4 首页筛选测试

- [ ] 访问首页
- [ ] 验证Tag按钮显示
- [ ] 测试单选筛选
- [ ] 测试多选筛选
- [ ] 验证筛选结果正确

#### 5.5 性能测试

- [ ] 模板列表加载时间 < 500ms
- [ ] 素材上传验证时间 < 100ms
- [ ] 字段池同步时间 < 1s
- [ ] 首页Tag按钮响应时间 < 100ms

### 步骤 6: 监控和日志

```bash
# 查看应用日志
docker logs -f <container_name>

# 或使用PM2
pm2 logs

# 监控数据库性能
# 检查慢查询日志
```

## 生产环境部署

### 部署前最终检查

- [ ] 测试环境已稳定运行至少24小时
- [ ] 所有冒烟测试通过
- [ ] 没有发现严重bug
- [ ] 性能指标达标
- [ ] 已通知相关人员部署计划
- [ ] 已准备回滚方案

### 部署窗口

- **推荐时间**: 非业务高峰期（如凌晨2-6点）
- **预计时长**: 30-60分钟
- **回滚时间**: 15分钟

### 部署步骤

与测试环境部署步骤相同，但需要额外注意：

1. **数据库备份**: 必须创建完整备份
2. **灰度发布**: 如果可能，先部署到部分服务器
3. **监控**: 密切监控系统指标和错误日志
4. **用户通知**: 如需停机，提前通知用户

### 部署后验证

- [ ] 所有冒烟测试通过
- [ ] 数据完整性验证通过
- [ ] 性能指标正常
- [ ] 错误日志无异常
- [ ] 用户反馈正常

## 回滚方案

### 何时回滚

- 发现严重bug影响核心功能
- 性能严重下降
- 数据完整性问题
- 用户无法正常使用

### 回滚步骤

1. **停止应用**
   ```bash
   docker-compose down
   # 或
   pm2 stop all
   ```

2. **恢复数据库**
   ```bash
   # PostgreSQL恢复示例
   pg_restore -h <host> -U <user> -d <database> -v backup_YYYYMMDD_HHMMSS.dump
   ```

3. **部署旧版本代码**
   ```bash
   git checkout <previous_version>
   npm run build
   npm start
   ```

4. **验证回滚**
   - 检查应用是否正常运行
   - 验证数据完整性
   - 执行基本功能测试

## 监控指标

### 应用指标

- 响应时间
- 错误率
- 请求量
- CPU使用率
- 内存使用率

### 数据库指标

- 查询响应时间
- 连接数
- 慢查询数量
- 锁等待时间

### 业务指标

- 模板创建数量
- 素材上传数量
- 字段池同步次数
- 用户活跃度

## 常见问题处理

### 问题 1: 数据迁移失败

**症状**: migrate-template-data.ts 执行失败

**解决方案**:
1. 检查错误日志
2. 验证数据库连接
3. 检查数据完整性
4. 手动修复问题数据
5. 重新运行迁移脚本

### 问题 2: 字段池同步失败

**症状**: 分类管理页面显示不正确

**解决方案**:
1. 检查字段池同步日志
2. 手动触发同步：调用 `/api/admin/sync-field-pool`
3. 验证字段定义和选项

### 问题 3: 性能下降

**症状**: 页面加载缓慢

**解决方案**:
1. 检查数据库索引是否正确创建
2. 检查慢查询日志
3. 优化查询语句
4. 增加缓存

### 问题 4: 版本冲突

**症状**: 模板更新时出现409错误

**解决方案**:
1. 这是正常的并发控制机制
2. 提示用户刷新页面重新编辑
3. 检查是否有多人同时编辑

## 联系人

- **技术负责人**: [姓名] - [联系方式]
- **运维负责人**: [姓名] - [联系方式]
- **产品负责人**: [姓名] - [联系方式]

## 附录

### A. 数据库迁移文件列表

```
prisma/migrations/
├── 20251201133500_add_material_kind_to_templates/
├── 20251202000000_add_material_kind_to_materials/
├── 20251202091500_add_material_ownership_fields/
└── 20251213073100_add_template_system_indexes/
```

### B. 关键API端点

- `GET /api/admin/upload-templates` - 获取模板列表
- `POST /api/admin/upload-templates` - 创建模板
- `GET /api/admin/upload-templates/[id]` - 获取模板详情
- `PUT /api/admin/upload-templates/[id]` - 更新模板
- `DELETE /api/admin/upload-templates/[id]` - 删除模板
- `POST /api/admin/sync-field-pool` - 同步字段池

### C. 环境变量检查

```bash
# 必需的环境变量
DATABASE_URL=postgresql://...
NEXTAUTH_SECRET=...
NEXTAUTH_URL=...
S3_ENDPOINT=...
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_BUCKET_NAME=...
```

### D. 性能基准

| 操作 | 目标时间 | 可接受时间 |
|------|---------|-----------|
| 模板列表加载 | < 300ms | < 500ms |
| 模板详情加载 | < 200ms | < 400ms |
| 素材上传验证 | < 50ms | < 100ms |
| 字段池同步 | < 500ms | < 1s |
| 首页Tag响应 | < 50ms | < 100ms |