# 截图存储方案升级说明

## 改进概述

将截图存储方式从**文件系统存储**升级为**数据库 Base64 存储**，解决数据一致性问题。

## 主要变更

### 1. 数据库结构调整

**文件**: `internal/storage/db.go`

- 将 `screenshots` 字段类型从 `TEXT` 升级为 `LONGTEXT`
- 添加自动迁移逻辑，检测并升级现有数据库的字段类型
- `LONGTEXT` 最大支持 4GB 数据，足够存储多张 Base64 编码的图片

```sql
-- 旧结构
screenshots TEXT

-- 新结构
screenshots LONGTEXT
```

### 2. 上传处理逻辑重构

**文件**: `internal/handlers/customer_handler.go`

**旧方案**:

- 上传的图片保存到 `./frontend/uploads/screenshots/` 目录
- 返回文件路径: `/static/uploads/screenshots/{uuid}.jpg`
- 需要配置静态文件服务器

**新方案**:

- 上传的图片转换为 Base64 编码
- 返回 Data URL 格式: `data:image/jpeg;base64,{base64_string}`
- 无需文件系统存储，无需静态文件服务器配置

### 3. 前端兼容性

前端代码**无需修改**！因为：

- `<img>` 标签的 `src` 属性同时支持 URL 和 Data URL
- 现有代码 `img.src = path` 可以直接使用 Base64 Data URL

## 优势对比

### 文件系统存储方案的问题

❌ **数据一致性问题**

- 数据库记录存在，但文件可能被误删
- 文件存在，但数据库记录可能被删除
- 备份恢复时需要同时处理数据库和文件系统

❌ **部署复杂性**

- 需要配置静态文件服务器路由
- 需要确保上传目录权限正确
- 多服务器部署需要共享存储或文件同步

❌ **维护成本**

- 需要定期清理孤立文件
- 需要监控磁盘空间使用

### Base64 数据库存储方案的优势

✅ **数据一致性保证**

- 图片数据和业务数据在同一事务中
- 删除记录时图片数据自动删除
- 备份恢复只需处理数据库

✅ **部署简化**

- 无需配置文件上传目录
- 无需配置静态文件服务器
- 多服务器部署无需共享存储

✅ **维护简化**

- 无需清理孤立文件
- 无需监控文件系统空间

## 性能考虑

### Base64 编码开销

- Base64 编码会增加约 33% 的数据大小
- 例如: 1MB 图片 → 约 1.33MB Base64 字符串

### 数据库存储

- `LONGTEXT` 最大 4GB，足够存储多张高清截图
- MySQL 对 LONGTEXT 字段有优化，不会影响其他字段查询性能

### 建议

- 单张图片建议不超过 2MB
- 每条记录建议不超过 5 张截图
- 如需存储大量高清图片，可考虑对象存储服务（OSS）

## 迁移说明

### 自动迁移

启动服务器时会自动执行以下操作：

1. 检测 `screenshots` 字段类型
2. 如果是 `TEXT`，自动升级为 `LONGTEXT`
3. 输出迁移日志

### 现有数据处理

**旧数据格式**（文件路径）:

```json
{
  "screenshots": [
    "/static/uploads/screenshots/uuid1.jpg",
    "/static/uploads/screenshots/uuid2.png"
  ]
}
```

**新数据格式**（Base64 Data URL）:

```json
{
  "screenshots": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "data:image/png;base64,iVBORw0KGgoAAAANSUh..."
  ]
}
```

**兼容性**: 前端代码同时支持两种格式，旧数据仍可正常显示（如果文件未被删除）

## 测试验证

### 1. 上传测试

```bash
curl -X POST http://localhost:8081/api/upload \
  -F "screenshots=@test1.jpg" \
  -F "screenshots=@test2.png"
```

预期响应:

```json
{
  "filePaths": [
    "data:image/jpeg;base64,/9j/4AAQ...",
    "data:image/png;base64,iVBORw0KG..."
  ]
}
```

### 2. 创建客户测试

```bash
curl -X POST http://localhost:8081/api/customers \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "测试客户",
    "screenshots": ["data:image/jpeg;base64,/9j/4AAQ..."]
  }'
```

### 3. 查询验证

```bash
curl http://localhost:8081/api/customers/{id}
```

验证返回的 `screenshots` 字段包含完整的 Base64 Data URL

## 回滚方案

如需回滚到文件系统存储方案：

1. 恢复 `customer_handler.go` 中的上传逻辑
2. 恢复 `main.go` 中的静态文件服务配置
3. 数据库字段保持 `LONGTEXT`（向下兼容 `TEXT`）

## 总结

这次升级从根本上解决了文件系统和数据库数据不一致的问题，简化了部署和维护流程，提高了系统的可靠性和可维护性。