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	是	页面名称，用于标识访问的页面

请求示例

{
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X)",
  "page_name": "home"
}

响应信息

成功响应 (200 OK)

{
  "message": "Page visit recorded successfully",
  "id": 123
}

错误响应 (400 Bad Request)

{
  "error": "Invalid request data"
}

错误响应 (500 Internal Server Error)

{
  "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字

请求示例

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

响应信息

成功响应 (200 OK)

{
  "message": "User info saved successfully",
  "id": 456
}

错误响应 (400 Bad Request)

{
  "error": "Invalid request data"
}

错误响应 (500 Internal Server Error)

{
  "error": "Database not available"
}

使用说明

• 用户在表单中填写信息后提交到此API
• 所有字段都是必填项
• msg字段最多支持200个字符，用于用户留言或备注
• 系统会自动记录创建时间
• 建议在前端进行基础的数据验证（如手机号格式）

---

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

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

请求信息

• 方法: POST
• 路径: /api/couplets

请求参数

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

请求示例

{
  "title": "新春"
}

响应信息

成功响应 (200 OK)

{
  "share_url": "http://xcsq.wxinh5.host/share/abc123def456",
  "poster_id": "abc123def456",
  "image_url": "http://xcsq.wxinh5.host/posters/couplet_abc123def456.png"
}

错误响应 (400 Bad Request)

{
  "error": "Invalid request data"
}

错误响应 (500 Internal Server Error)

{
  "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: 服务器内部错误或数据库不可用

错误响应格式：

{
  "error": "错误描述信息"
}

使用建议

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

前端使用示例

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

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)
  }
}