crm/docs/screenshot-storage-upgrade.md

截图存储方案升级说明

改进概述

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

主要变更

1. 数据库结构调整

文件: internal/storage/db.go

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

-- 旧结构
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. 输出迁移日志

现有数据处理

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

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

新数据格式（Base64 Data URL）:

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

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

测试验证

1. 上传测试

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

预期响应:

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

2. 创建客户测试

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

3. 查询验证

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

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

回滚方案

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

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

总结

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