photography/backend/SEED_DATA_README.md

# 摄影作品集项目 - 种子数据说明

本文档说明如何使用项目的种子数据来填充数据库，为开发和测试提供丰富的样本数据。

## 📊 种子数据概览

### 数据统计
- **用户数量**: 6个 (1个管理员 + 5个摄影师)
- **分类数量**: 10个 (4个默认 + 6个新增)
- **照片数量**: 30张 (涵盖所有分类)

### 用户信息
| 用户名 | 邮箱 | 角色 | 照片数量 | 密码 |
|--------|------|------|----------|------|
| admin | admin@example.com | 管理员 | 5张 | admin123 |
| photographer1 | photographer1@example.com | 摄影师 | 3张 | admin123 |
| photographer2 | photographer2@example.com | 摄影师 | 6张 | admin123 |
| nature_lover | nature@example.com | 摄影师 | 5张 | admin123 |
| urban_explorer | urban@example.com | 摄影师 | 6张 | admin123 |
| portrait_artist | portrait@example.com | 摄影师 | 5张 | admin123 |

### 分类信息
| 分类名称 | 描述 | 照片数量 |
|----------|------|----------|
| 风景摄影 | 自然风景摄影作品 | 5张 |
| 人像摄影 | 人物肖像摄影作品 | 5张 |
| 建筑摄影 | 建筑摄影作品 | 5张 |
| 街拍摄影 | 街头摄影作品 | 5张 |
| 艺术摄影 | 创意艺术摄影作品 | 3张 |
| 宠物摄影 | 可爱宠物摄影作品 | 3张 |
| 食物摄影 | 美食摄影作品 | 3张 |
| 旅行摄影 | 旅行纪念摄影作品 | 3张 |
| 黑白摄影 | 经典黑白摄影作品 | 3张 |

## 🚀 快速开始

### 方法一：使用 Makefile（推荐）

```bash
# 1. 进入后端目录
cd backend/

# 2. 检查当前数据库状态
make db-status

# 3. 执行种子数据
make seed

# 4. 再次检查数据库状态，验证数据插入
make db-status
```

### 方法二：直接运行脚本

```bash
# 1. 进入后端目录
cd backend/

# 2. 运行种子数据脚本
./run_seed_data.sh
```

### 方法三：手动执行 SQL

```bash
# 1. 进入后端目录
cd backend/

# 2. 直接执行 SQL 文件
sqlite3 ./data/photography.db < seed_data.sql
```

## 📋 使用说明

### 前置条件

1. **确保数据库已创建**
   ```bash
   # 如果数据库不存在，先启动后端服务创建数据库
   make quick
   # 或
   go run cmd/api/main.go -f etc/photographyapi-api.yaml
   ```

2. **确保 SQLite3 已安装**
   ```bash
   # macOS
   brew install sqlite3
   
   # Ubuntu/Debian
   sudo apt-get install sqlite3
   
   # CentOS/RHEL
   sudo yum install sqlite
   ```

### 安全备份

脚本会自动创建数据库备份：
- 备份位置：`./data/backups/`
- 备份格式：`photography_YYYYMMDD_HHMMSS.db`
- 每次执行种子数据前都会自动备份

### 数据重置

如果需要完全重置数据库：

```bash
# 方法一：使用 Makefile
make db-reset
make quick  # 重新创建数据库
make seed   # 重新插入种子数据

# 方法二：手动删除
rm -f ./data/photography.db
go run cmd/api/main.go -f etc/photographyapi-api.yaml  # 重新创建
./run_seed_data.sh  # 重新插入种子数据
```

## 🔍 数据验证

### 检查数据完整性

```bash
# 使用 Makefile 检查
make db-status

# 或手动检查
sqlite3 ./data/photography.db "
SELECT 
    '用户' as 表名, COUNT(*) as 数量 FROM user
UNION ALL
SELECT 
    '分类' as 表名, COUNT(*) as 数量 FROM category
UNION ALL
SELECT 
    '照片' as 表名, COUNT(*) as 数量 FROM photo;
"
```

### 查看分类统计

```bash
sqlite3 ./data/photography.db "
SELECT 
    c.name as '分类名称',
    COUNT(p.id) as '照片数量'
FROM category c
LEFT JOIN photo p ON c.id = p.category_id
GROUP BY c.id, c.name
ORDER BY COUNT(p.id) DESC;
"
```

### 查看用户统计

```bash
sqlite3 ./data/photography.db "
SELECT 
    u.username as '用户名',
    COUNT(p.id) as '照片数量'
FROM user u
LEFT JOIN photo p ON u.id = p.user_id
GROUP BY u.id, u.username
ORDER BY COUNT(p.id) DESC;
"
```

## 🖼️ 照片文件说明

**重要提示**: 种子数据中的照片路径是模拟路径，实际文件并不存在。

- 照片路径格式：`/uploads/photos/[category]_[name]_[number].jpg`
- 缩略图路径格式：`/uploads/thumbnails/[category]_[name]_[number]_thumb.jpg`

### 在测试环境中使用

1. **前端展示**: 可以使用占位符图片或默认图片
2. **管理后台**: 可以显示路径信息，但图片可能无法加载
3. **API 测试**: 可以正常测试所有与照片元数据相关的功能

### 添加真实图片文件

如果需要添加真实的图片文件进行完整测试：

```bash
# 1. 创建上传目录
mkdir -p uploads/photos uploads/thumbnails

# 2. 添加对应的图片文件
# 例如：uploads/photos/landscape_sunrise_001.jpg
#      uploads/thumbnails/landscape_sunrise_001_thumb.jpg
```

## 🛠️ 自定义种子数据

### 修改现有数据

编辑 `seed_data.sql` 文件：
- 修改用户信息
- 增加或删除分类
- 调整照片信息
- 更新照片路径

### 添加新数据

```sql
-- 添加新用户
INSERT INTO user (username, password, email, avatar, status, created_at, updated_at) VALUES
('新用户名', '$2a$10$fryeTxwwsFe8fIe1aekht.NV/KGr8tcWUB25EA4MMdEF5Qw5lJkPm', '邮箱', '', 1, datetime('now'), datetime('now'));

-- 添加新分类
INSERT INTO category (name, description, created_at, updated_at) VALUES
('新分类', '新分类描述', datetime('now'), datetime('now'));

-- 添加新照片
INSERT INTO photo (title, description, file_path, thumbnail_path, user_id, category_id, created_at, updated_at) VALUES
('照片标题', '照片描述', '照片路径', '缩略图路径', 用户ID, 分类ID, datetime('now'), datetime('now'));
```

### 重新生成种子数据

```bash
# 1. 修改 seed_data.sql
# 2. 重新执行
make seed
```

## 🔧 常见问题

### 1. 数据库文件不存在

**错误**: `数据库文件不存在: ./data/photography.db`

**解决**: 先启动后端服务创建数据库
```bash
make quick
# 等待服务启动后按 Ctrl+C 停止
make seed
```

### 2. SQLite3 命令未找到

**错误**: `sqlite3: command not found`

**解决**: 安装 SQLite3
```bash
# macOS
brew install sqlite3

# Ubuntu/Debian
sudo apt-get install sqlite3
```

### 3. 权限错误

**错误**: `permission denied: ./run_seed_data.sh`

**解决**: 添加执行权限
```bash
chmod +x ./run_seed_data.sh
```

### 4. 数据重复插入

**说明**: 脚本会先清理现有数据，然后插入新数据，不会产生重复数据。

### 5. 备份文件过多

**解决**: 定期清理备份文件
```bash
# 删除30天前的备份
find ./data/backups/ -name "*.db" -mtime +30 -delete
```

## 📝 最佳实践

1. **定期备份**: 在执行种子数据前，脚本会自动备份数据库
2. **版本控制**: 将 `seed_data.sql` 纳入版本控制，方便团队协作
3. **环境隔离**: 在开发、测试、生产环境中使用不同的种子数据
4. **数据一致性**: 确保种子数据与实际业务逻辑一致
5. **性能考虑**: 对于大量数据，考虑分批插入或使用事务

## 📞 技术支持

如果在使用种子数据过程中遇到问题：

1. 检查日志输出中的错误信息
2. 确认数据库文件权限正确
3. 验证 SQLite3 版本兼容性
4. 查看备份文件是否正常生成

## 🔗 相关文档

- [后端开发文档](./CLAUDE.md)
- [API 接口文档](./api/desc/)
- [数据库设计文档](../docs/v1/database/)
- [部署配置文档](../docs/deployment/)