# Frontend API Integration Guide

此文档说明如何将前端展示网站连接到后端 go-zero API。

## 🚀 快速开始

### 1. 环境配置

确保 `.env.local` 文件配置正确：

```bash
# API配置 - 连接到后端 go-zero API
NEXT_PUBLIC_API_URL=http://localhost:8888/api/v1

# Mock API (仅开发时使用)
NEXT_PUBLIC_MOCK_API_URL=http://localhost:3001/api

# 开发环境配置
NODE_ENV=development

# 启用真实API
NEXT_PUBLIC_USE_REAL_API=true
```

### 2. 启动后端服务

首先启动后端 go-zero API 服务：

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

# 启动后端服务 (端口 8888)
make dev
# 或者
go run cmd/api/main.go -f etc/photographyapi-api.yaml
```

确保后端服务在 `http://localhost:8888` 运行正常。

### 3. 启动前端服务

在新的终端窗口中启动前端：

```bash
# 进入前端目录
cd frontend

# 安装依赖 (首次运行)
bun install

# 启动开发服务器
bun run dev
```

前端将在 `http://localhost:3000` 启动。

## 🔄 API 模式切换

### 开发环境切换

在开发环境中，你可以通过右下角的 API 状态指示器来切换 API 模式：

- **后端API**: 连接到真实的 go-zero 后端服务 (localhost:8888)
- **Mock API**: 使用本地模拟数据 (localhost:3001)

### 手动切换

1. **使用真实 API**:
   ```bash
   # 在 .env.local 中设置
   NEXT_PUBLIC_USE_REAL_API=true
   ```

2. **使用 Mock API**:
   ```bash
   # 在 .env.local 中设置
   NEXT_PUBLIC_USE_REAL_API=false
   ```

修改后需要重启前端开发服务器。

## 📊 数据格式转换

### 后端 API 数据格式

后端 go-zero API 返回的数据格式：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "photos": [
      {
        "id": 1,
        "title": "照片标题",
        "description": "照片描述",
        "file_path": "/uploads/photos/xxx.jpg",
        "thumbnail_path": "/uploads/photos/thumb_xxx.jpg",
        "user_id": 1,
        "category_id": 1,
        "created_at": 1641024000,
        "updated_at": 1641024000
      }
    ],
    "total": 1,
    "page": 1,
    "size": 10
  }
}
```

### 前端显示格式

前端自动转换为统一的显示格式：

```typescript
interface Photo {
  id: number
  title: string
  description: string
  src: string              // 转换自 file_path
  category: string         // 通过 category_id 查找分类名称
  tags: string[]           // 暂时为空数组
  date: string             // 转换自 created_at 时间戳
  exif: {                  // 暂时使用默认值
    camera: string
    lens: string
    settings: string
    location: string
  }
}
```

## 🛠️ 故障排查

### 常见问题

1. **无法连接到后端 API**
   - 确保后端服务在 `localhost:8888` 运行
   - 检查防火墙设置
   - 查看浏览器控制台错误信息

2. **照片无法显示**
   - 确保后端上传了照片文件
   - 检查照片文件路径是否正确
   - 确认静态文件服务正常

3. **分类显示错误**
   - 检查后端是否有分类数据
   - 确认分类 ID 关联正确

### 调试技巧

1. **查看 API 状态**
   - 开发环境右下角有 API 状态指示器
   - 绿色表示连接正常，红色表示连接失败

2. **查看网络请求**
   - 打开浏览器开发者工具
   - 切换到 Network 标签
   - 查看 API 请求和响应

3. **切换到 Mock API**
   - 如果后端有问题，可以临时切换到 Mock API 继续开发
   - 修改 `NEXT_PUBLIC_USE_REAL_API=false`

## 📈 性能优化

### 缓存策略

- 照片列表缓存 5 分钟
- 分类列表缓存 10 分钟
- 单张照片数据根据需要缓存

### 图片优化

- 使用后端提供的缩略图 (thumbnail_path)
- 懒加载大图
- 支持多种图片格式

## 🔒 安全考虑

### API 认证

目前前端支持 JWT 认证：

- Token 存储在 localStorage
- 自动在请求头添加 Authorization
- Token 过期自动跳转登录页

### 跨域配置

后端需要配置 CORS 允许前端域名访问。

## 📚 相关文档

- [后端 API 文档](../backend/CLAUDE.md)
- [前端开发文档](./CLAUDE.md)
- [部署文档](../docs/deployment/CLAUDE.md)

## 🎯 下一步计划

1. **完善照片元数据**: 添加 EXIF 信息显示
2. **标签系统**: 实现照片标签功能
3. **高级搜索**: 支持按分类、标签、日期搜索
4. **用户系统**: 添加用户认证和权限管理
5. **性能优化**: 图片懒加载、虚拟滚动等

---

*此文档随项目更新，如有问题请查看具体模块的 CLAUDE.md 文件*