qs_xinchun2026_h5/api/API_DOCUMENTATION.md

# H5海报项目 API 文档

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

## 基础信息

- **Base URL**: `http://localhost:8080` (开发环境) / 生产环境使用相对路径
- **Content-Type**: `application/json`
- **超时时间**: 60秒

## 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
}
```

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

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

#### 使用说明
- 每次用户访问页面时调用此API
- 系统会自动记录用户的IP地址
- 如果数据库不可用，API会返回500错误
- 建议在页面加载完成后异步调用，不影响用户体验

---

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

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

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

#### 请求参数

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| name | string | 是 | 用户姓名 |
| phone | string | 是 | 用户手机号码 |
| address | string | 是 | 用户地址 |
| msg | string | 是 | 用户留言或备注信息，最多200字 |

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

#### 响应信息

**成功响应** (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个字符，用于用户留言或备注
- 系统会自动记录创建时间
- 建议在前端进行基础的数据验证（如手机号格式）

---

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

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

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

#### 请求参数

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| title | string | 是 | 两个汉字，用于生成对联（如"新春"） |

#### 请求示例
```json
{
  "title": "新春"
}
```

#### 响应信息

**成功响应** (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在出错时都会返回相应的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)
  }
}
```