feat: decode user_id

api/v1/analytics/handler.go

@@ -37,6 +37,14 @@ func (h *AnalyticsHandler) TrackEvent(c *gin.Context) {
 		return
 	}
 
+	userID, err := common.GetUserIDFromContext(c)
+	if err != nil {
+		log.Error(c.Request.Context(), "get user id failed", "error", err)
+		c.JSON(http.StatusOK, common.ErrorResponse(c, common.CodeUnauthorized, "unauthorized"))
+		return
+	}
+	req.UserID = userID
+
 	if err := h.analyticsService.TrackEvent(c.Request.Context(), &req); err != nil {
 		log.Error(c.Request.Context(), "track event failed", "error", err)
 		c.JSON(http.StatusOK, common.ErrorResponse(c, common.CodeSystemError, "failed to track event"))

frontend-sdk/API_EXAMPLES.md

@@ -0,0 +1,284 @@
+# 数据埋点 API 调用示例
+
+## 基础信息
+
+- **接口路径**: `/doc_ai/v1/analytics/track`
+- **请求方法**: `POST`
+- **Content-Type**: `application/json`
+- **认证**: 可选（Bearer Token）
+
+## 1. 基础埋点事件（最小参数）
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": 12345,
+    "event_name": "button_click"
+  }'
+```
+
+## 2. 完整埋点事件（包含所有字段）
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "user_id": 12345,
+    "event_name": "formula_recognition_start",
+    "properties": {
+      "file_name": "math_formula.png",
+      "file_size": 102400,
+      "file_type": "image/png",
+      "upload_method": "drag_drop"
+    },
+    "device_info": {
+      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+      "screen_width": 1920,
+      "screen_height": 1080,
+      "language": "zh-CN",
+      "timezone": "Asia/Shanghai",
+      "platform": "MacIntel"
+    },
+    "meta_data": {
+      "task_id": "task_123456",
+      "timestamp": 1706342400000
+    }
+  }'
+```
+
+## 3. 页面浏览事件
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": 12345,
+    "event_name": "page_view",
+    "properties": {
+      "page_url": "https://example.com/home",
+      "page_title": "首页",
+      "page_name": "home",
+      "referrer": "https://example.com/login"
+    },
+    "device_info": {
+      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+      "screen_width": 1920,
+      "screen_height": 1080
+    }
+  }'
+```
+
+## 4. 任务相关事件
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "user_id": 12345,
+    "event_name": "task_create",
+    "properties": {
+      "task_type": "formula_recognition",
+      "file_name": "equation.png",
+      "file_size": 204800
+    },
+    "meta_data": {
+      "task_id": "task_789012"
+    }
+  }'
+```
+
+## 5. 任务完成事件
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": 12345,
+    "event_name": "task_complete",
+    "properties": {
+      "duration_seconds": 5.2,
+      "success": true,
+      "result_type": "latex"
+    },
+    "meta_data": {
+      "task_id": "task_789012"
+    }
+  }'
+```
+
+## 6. 表单提交事件
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": 12345,
+    "event_name": "form_submit",
+    "properties": {
+      "form_name": "user_registration",
+      "form_fields": ["email", "password", "phone"],
+      "success": true,
+      "validation_errors": 0
+    }
+  }'
+```
+
+## 7. 文件上传事件
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": 12345,
+    "event_name": "file_upload",
+    "properties": {
+      "file_name": "document.pdf",
+      "file_size": 5242880,
+      "file_type": "application/pdf",
+      "upload_source": "drag_drop",
+      "upload_duration_ms": 1200
+    }
+  }'
+```
+
+## 8. 错误追踪事件
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": 12345,
+    "event_name": "error_occurred",
+    "properties": {
+      "error_type": "network_error",
+      "error_message": "Failed to fetch data",
+      "error_code": "NET_001",
+      "page_url": "https://example.com/tasks",
+      "user_action": "click_submit_button"
+    }
+  }'
+```
+
+## 9. 使用环境变量（推荐）
+
+```bash
+# 设置环境变量
+export API_BASE_URL="http://localhost:8080"
+export JWT_TOKEN="YOUR_JWT_TOKEN"
+export USER_ID=12345
+
+# 调用接口
+curl -X POST ${API_BASE_URL}/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer ${JWT_TOKEN}" \
+  -d "{
+    \"user_id\": ${USER_ID},
+    \"event_name\": \"button_click\",
+    \"properties\": {
+      \"button_name\": \"submit\",
+      \"button_position\": \"bottom\"
+    }
+  }"
+```
+
+## 10. 使用 JSON 文件
+
+创建 `event.json` 文件：
+```json
+{
+  "user_id": 12345,
+  "event_name": "custom_event",
+  "properties": {
+    "action": "click",
+    "element": "button",
+    "value": "submit"
+  },
+  "device_info": {
+    "user_agent": "Mozilla/5.0",
+    "screen_width": 1920,
+    "screen_height": 1080
+  },
+  "meta_data": {
+    "task_id": "task_123"
+  }
+}
+```
+
+然后执行：
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d @event.json
+```
+
+## 11. 批量埋点接口
+
+```bash
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track/batch \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "events": [
+      {
+        "user_id": 12345,
+        "event_name": "page_view",
+        "properties": {
+          "page_name": "home"
+        }
+      },
+      {
+        "user_id": 12345,
+        "event_name": "button_click",
+        "properties": {
+          "button_name": "start"
+        }
+      }
+    ]
+  }'
+```
+
+## 响应示例
+
+### 成功响应
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": null
+}
+```
+
+### 错误响应
+```json
+{
+  "code": 400,
+  "message": "invalid request",
+  "data": null
+}
+```
+
+## 注意事项
+
+1. **user_id** 和 **event_name** 是必填字段
+2. **properties**、**device_info**、**meta_data** 都是可选字段，类型为 JSON 对象
+3. 如果提供了 Authorization header，token 中的 user_id 会被设置到上下文中，但请求体中的 user_id 仍然需要提供
+4. 建议在生产环境中始终使用 HTTPS
+5. 批量接口最多支持 100 个事件
+
+## 测试命令（本地开发）
+
+```bash
+# 最简单的测试
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": 1, "event_name": "test_event"}'
+
+# 查看响应详情
+curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": 1, "event_name": "test_event"}' \
+  -v
+```

internal/model/analytics/request.go

@@ -4,7 +4,8 @@ import "time"
 
 // TrackEventRequest 埋点事件请求
 type TrackEventRequest struct {
-	UserID     int64                  `json:"user_id" binding:"required"`
+	TaskNo     string                 `json:"task_no" binding:"required"`
+	UserID     int64                  `json:"user_id"`
 	EventName  string                 `json:"event_name" binding:"required"`
 	Properties map[string]interface{} `json:"properties"`
 	DeviceInfo map[string]interface{} `json:"device_info"`