# H5海报项目 API 文档

本文档描述了H5海报项目的后端API接口，供前端开发使用。

## 基础信息

- **Base URL**: `http://localhost:8080` (开发环境) / 生产环境使用相对路径
- **Content-Type**: `application/json`
- **超时时间**: 60秒
- **调试模式**: 通过配置文件中的 `debug` 字段控制，默认为 `true`

## UUID关联机制

本系统使用UUID来跟踪用户的完整操作流程：

1. **页面访问** (`/api/page-visit`): 用户首次访问页面时生成唯一的UUID
2. **对联生成** (`/api/couplets`): 使用页面访问的UUID关联海报生成操作
3. **用户信息提交** (`/api/user-info`): 使用相同的UUID关联用户信息提交

这种机制允许系统追踪从页面访问到最终用户提交的完整用户行为路径。

## 调试模式配置

系统支持通过配置文件控制Gin框架的运行模式：

- **debug: true** (默认): Gin运行在调试模式，输出详细的错误信息和日志
- **debug: false**: Gin运行在发布模式，性能更好，错误信息更简洁

建议开发环境使用 `true`，生产环境使用 `false`

## API端点

### 1. 页面访问记录 - `/api/page-visit`

记录用户页面访问信息，用于统计分析。

#### 请求信息
- **方法**: `POST`
- **路径**: `/api/page-visit`

#### 请求参数

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| user_agent | string | 是 | 用户浏览器User-Agent字符串 |
| page_name | string | 是 | 页面名称，用于标识访问的页面 |

#### 请求示例
```json
{
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X)",
  "page_name": "home"
}
```

#### 响应信息

**成功响应** (200 OK)
```json
{
  "message": "Page visit recorded successfully",
  "id": 123,
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}
```

**错误响应** (400 Bad Request)
```json
{
  "error": "Invalid request data"
}
```

**错误响应** (409 Conflict)
```json
{
  "error": "该手机号码已经提交过用户信息，请勿重复提交"
}
```

**错误响应** (409 Conflict)
```json
{
  "error": "该页面访问已经提交过用户信息，请勿重复提交"
}
```

**错误响应** (500 Internal Server Error)
```json
{
  "error": "Database not available"
}
```

#### 使用说明
- 每次用户访问页面时调用此API
- 系统会自动记录用户的IP地址
- 如果数据库不可用，API会返回500错误
- 建议在页面加载完成后异步调用，不影响用户体验
- **重要**: 返回的UUID需要保存，后续的couplets和user-info接口需要使用这个UUID进行关联

---

### 2. 用户信息保存 - `/api/user-info`

保存用户填写的个人信息，用于活动参与或后续联系。

#### 请求信息
- **方法**: `POST`
- **路径**: `/api/user-info`

#### 请求参数

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| name | string | 是 | 用户姓名 |
| phone | string | 是 | 用户手机号码 |
| address | string | 是 | 用户地址 |
| msg | string | 是 | 用户留言或备注信息，最多200字 |
| page_visit_uuid | string | 是 | 页面访问UUID，用于关联页面访问记录 |

#### 请求示例
```json
{
  "name": "张三",
  "phone": "13800138000",
  "address": "北京市朝阳区xxx街道xxx号",
  "msg": "希望能够获得精美礼品，谢谢！",
  "page_visit_uuid": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 响应信息

**成功响应** (200 OK)
```json
{
  "message": "User info saved successfully",
  "id": 456
}
```

**错误响应** (400 Bad Request)
```json
{
  "error": "Invalid request data"
}
```

**错误响应** (500 Internal Server Error)
```json
{
  "error": "Database not available"
}
```

#### 使用说明
- 用户在表单中填写信息后提交到此API
- 所有字段都是必填项
- msg字段最多支持200个字符，用于用户留言或备注
- 系统会自动记录创建时间
- 建议在前端进行基础的数据验证（如手机号格式）
- **重要**: 必须使用之前从`/api/page-visit`获得的UUID作为`page_visit_uuid`参数
- **防重复提交**: 系统会检查手机号和页面访问UUID的唯一性，如果发现重复提交会返回409错误

---

### 3. 对联海报生成 - `/api/couplets`

根据用户输入的两个汉字，使用AI生成对联并创建海报。

#### 请求信息
- **方法**: `POST`
- **路径**: `/api/couplets`

#### 请求参数

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| title | string | 是 | 两个汉字，用于生成对联（如"新春"） |
| page_visit_uuid | string | 是 | 页面访问UUID，用于关联页面访问记录 |

#### 请求示例
```json
{
  "title": "新春",
  "page_visit_uuid": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 响应信息

**成功响应** (200 OK)
```json
{
  "share_url": "http://xcsq.wxinh5.host/share/abc123def456",
  "poster_id": "abc123def456",
  "image_url": "http://xcsq.wxinh5.host/posters/couplet_abc123def456.png"
}
```

**错误响应** (400 Bad Request)
```json
{
  "error": "Invalid request data"
}
```

**错误响应** (500 Internal Server Error)
```json
{
  "error": "Failed to generate couplet poster: API key is not configured"
}
```

#### 使用说明
- 用户需要输入两个汉字作为对联生成的主题
- 系统会调用AI生成对联（上联、下联、横批）
- 生成的对联会制作成海报图片
- 返回的`image_url`可以直接用于显示海报
- 返回的`share_url`可以用于分享功能
- 如果AI服务不可用，系统会使用默认对联
- **重要**: 必须使用之前从`/api/page-visit`获得的UUID作为`page_visit_uuid`参数

---

## 错误处理

所有API在出错时都会返回相应的HTTP状态码和错误信息：

- **400 Bad Request**: 请求参数错误或格式不正确
- **500 Internal Server Error**: 服务器内部错误或数据库不可用

错误响应格式：
```json
{
  "error": "错误描述信息"
}
```

## 使用建议

1. **错误处理**: 前端应该适当处理API返回的错误信息，给用户友好的提示
2. **重试机制**: 对于网络错误，可以考虑实现重试机制
3. **超时处理**: 设置合适的超时时间，避免用户长时间等待
4. **异步调用**: 建议使用异步方式调用API，不影响用户体验

## 前端使用示例

可以参考项目中的API封装文件：`frontend/src/utils/api.js`

```javascript
import axios from 'axios'

const api = axios.create({
  baseURL: 'http://localhost:8080',
  timeout: 60000,
  headers: {
    'Content-Type': 'application/json'
  }
})

// 使用示例
const recordVisit = async () => {
  try {
    const response = await api.post('/api/page-visit', {
      user_agent: navigator.userAgent,
      page_name: 'current_page'
    })
    console.log('Visit recorded:', response.data)
  } catch (error) {
    console.error('Failed to record visit:', error)
  }
}
```