diff --git a/api/API_DOCUMENTATION.md b/api/API_DOCUMENTATION.md index c3327bd..f366cce 100644 --- a/api/API_DOCUMENTATION.md +++ b/api/API_DOCUMENTATION.md @@ -7,6 +7,26 @@ - **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端点 @@ -39,7 +59,8 @@ ```json { "message": "Page visit recorded successfully", - "id": 123 + "id": 123, + "uuid": "550e8400-e29b-41d4-a716-446655440000" } ``` @@ -50,6 +71,20 @@ } ``` +**错误响应** (409 Conflict) +```json +{ + "error": "该手机号码已经提交过用户信息,请勿重复提交" +} +``` + +**错误响应** (409 Conflict) +```json +{ + "error": "该页面访问已经提交过用户信息,请勿重复提交" +} +``` + **错误响应** (500 Internal Server Error) ```json { @@ -62,6 +97,7 @@ - 系统会自动记录用户的IP地址 - 如果数据库不可用,API会返回500错误 - 建议在页面加载完成后异步调用,不影响用户体验 +- **重要**: 返回的UUID需要保存,后续的couplets和user-info接口需要使用这个UUID进行关联 --- @@ -81,6 +117,7 @@ | phone | string | 是 | 用户手机号码 | | address | string | 是 | 用户地址 | | msg | string | 是 | 用户留言或备注信息,最多200字 | +| page_visit_uuid | string | 是 | 页面访问UUID,用于关联页面访问记录 | #### 请求示例 ```json @@ -88,7 +125,8 @@ "name": "张三", "phone": "13800138000", "address": "北京市朝阳区xxx街道xxx号", - "msg": "希望能够获得精美礼品,谢谢!" + "msg": "希望能够获得精美礼品,谢谢!", + "page_visit_uuid": "550e8400-e29b-41d4-a716-446655440000" } ``` @@ -122,6 +160,8 @@ - msg字段最多支持200个字符,用于用户留言或备注 - 系统会自动记录创建时间 - 建议在前端进行基础的数据验证(如手机号格式) +- **重要**: 必须使用之前从`/api/page-visit`获得的UUID作为`page_visit_uuid`参数 +- **防重复提交**: 系统会检查手机号和页面访问UUID的唯一性,如果发现重复提交会返回409错误 --- @@ -138,11 +178,13 @@ | 参数名 | 类型 | 必需 | 描述 | |--------|------|------|------| | title | string | 是 | 两个汉字,用于生成对联(如"新春") | +| page_visit_uuid | string | 是 | 页面访问UUID,用于关联页面访问记录 | #### 请求示例 ```json { - "title": "新春" + "title": "新春", + "page_visit_uuid": "550e8400-e29b-41d4-a716-446655440000" } ``` @@ -178,6 +220,7 @@ - 返回的`image_url`可以直接用于显示海报 - 返回的`share_url`可以用于分享功能 - 如果AI服务不可用,系统会使用默认对联 +- **重要**: 必须使用之前从`/api/page-visit`获得的UUID作为`page_visit_uuid`参数 --- diff --git a/components/LotteryFormModal.vue b/components/LotteryFormModal.vue index ba343ab..264c70f 100644 --- a/components/LotteryFormModal.vue +++ b/components/LotteryFormModal.vue @@ -1,5 +1,5 @@