wenzi/docs/api.md

API 文档

本文档详细说明了活动管理和API密钥管理相关的API端点。

统一响应封装

除图片/HTML/CSV等非 JSON 响应外，所有接口返回 ApiResponse：

• 成功响应：

  {
    "code": 200,
    "message": "success",
    "data": {},
    "meta": {
      "pagination": {
        "page": 0,
        "size": 20,
        "total": 100,
        "totalPages": 5,
        "hasNext": true,
        "hasPrevious": false
      }
    },
    "timestamp": "2025-09-30T12:34:56",
    "traceId": "trace-id"
  }
  

• 错误响应：

  {
    "code": 400,
    "message": "请求参数校验失败",
    "error": {
      "message": "activityId 不能为空",
      "details": { "activityId": "must not be null" },
      "code": "VALIDATION_ERROR"
    },
    "timestamp": "2025-09-30T12:34:56",
    "traceId": "trace-id"
  }
  

认证与鉴权

• /api/** 需要 X-API-Key。
• /api/v1/me/**、/api/v1/activities/**、/api/v1/api-keys/**、/api/v1/share/** 需要 Authorization: Bearer <token>。
• /r/**、/actuator/** 不需要认证。

错误码

• VALIDATION_ERROR → 400：请求参数校验失败（字段缺失/格式不符）。
• BAD_REQUEST → 400：业务数据不合法（如结束时间早于开始时间、上传文件不支持）。
• FORBIDDEN → 403：无权访问资源或操作。
• NOT_FOUND → 404：资源不存在（活动、API密钥等）。
• INTERNAL_ERROR → 500：服务器内部错误。
• INVALID_API_KEY → 401：提供的 API 密钥无效或已吊销。

1. 活动管理 (Activities)

1.1 创建活动

• Endpoint: POST /api/v1/activities

• 描述: 创建一个新的营销活动。

• 请求体: application/json

  {
    "name": "春季特惠活动",
    "startTime": "2025-03-01T10:00:00+08:00",
    "endTime": "2025-03-31T23:59:59+08:00"
  }
  

• 成功响应 (201 Created):

  {
    "code": 201,
    "message": "success",
    "data": {
      "id": 1,
      "name": "春季特惠活动",
      "startTime": "2025-03-01T10:00:00+08:00",
      "endTime": "2025-03-31T23:59:59+08:00"
    },
    "timestamp": "2025-03-01T10:00:00"
  }
  

• 失败响应:

  • 400 Bad Request: 如果请求数据无效（例如，名称为空或结束时间早于开始时间）。

1.2 更新活动

• Endpoint: PUT /api/v1/activities/{id}

• 描述: 更新一个已存在的活动。

• 路径参数: id (long) - 活动的唯一标识符。

• 请求体: application/json

  {
    "name": "春季特惠活动（升级版）",
    "startTime": "2025-03-01T10:00:00+08:00",
    "endTime": "2025-04-15T23:59:59+08:00"
  }
  

• 成功响应 (200 OK): ApiResponse<Activity>，data 为更新后的活动对象。

• 失败响应:

  • 400 Bad Request: 如果请求数据无效。
  • 404 Not Found: 如果指定的 id 不存在。

1.3 获取活动详情

• Endpoint: GET /api/v1/activities/{id}
• 描述: 获取指定ID的活动详情。
• 路径参数: id (long) - 活动的唯一标识符。
• 成功响应 (200 OK): ApiResponse<Activity>，data 为活动对象。
• 失败响应:
  • 404 Not Found: 如果指定的 id 不存在。

2. API密钥管理 (API Keys)

2.1 创建API密钥

• Endpoint: POST /api/v1/api-keys

• 描述: 为指定的活动创建一个新的API密钥。密钥仅在本次响应中明文返回，请立即保存。

• 请求体: application/json

  {
    "activityId": 1,
    "name": "我的第一个密钥"
  }
  

• 成功响应 (201 Created):

  {
    "code": 201,
    "message": "success",
    "data": {
      "apiKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
    },
    "timestamp": "2025-03-01T10:00:00"
  }
  

• 失败响应:

  • 400 Bad Request: 如果请求数据无效（例如，activityId 或 name 为空）。
  • 404 Not Found: 如果 activityId 不存在。

2.2 吊销API密钥

• Endpoint: DELETE /api/v1/api-keys/{id}
• 描述: 吊销（删除）一个API密钥。
• 路径参数: id (long) - API密钥的唯一标识符。
• 成功响应 (200 OK): ApiResponse<Void>，data 为 null。
• 失败响应:
  • 404 Not Found: 如果指定的 id 不存在。

2.3 使用/校验 API 密钥

• Endpoint: POST /api/v1/api-keys/{id}/use

• 描述: 校验提供的明文 API 密钥是否与 id 对应的密钥匹配；校验成功将更新 last_used_at。

• 请求体: application/json

  {
    "apiKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
  

• 成功响应 (200 OK): ApiResponse<Void>，data 为 null。

• 失败响应:

  • 401 Unauthorized + INVALID_API_KEY：密钥错误或已吊销。
  • 404 Not Found：id 不存在。

2.4 通过前缀校验 API 密钥（无需 ID）

• Endpoint: POST /api/v1/api-keys/validate

• 描述: 仅凭明文 API 密钥进行校验（服务端使用前缀快速定位候选密钥，再进行哈希校验）。校验成功将更新 last_used_at。

• 请求体: application/json

  {
    "apiKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
  

• 成功响应 (200 OK): ApiResponse<Void>，data 为 null。

• 失败响应:

  • 401 Unauthorized + INVALID_API_KEY：密钥错误或已吊销。

3. 缓存管理 (Cache)

3.1 清空某类缓存

• Endpoint: DELETE /api/v1/cache/{cacheName}
• 描述: 清空指定缓存空间（如 leaderboards、activities、activity_stats、activity_graph）。
• 成功响应 (204 No Content)

3.2 失效某个缓存键

• Endpoint: DELETE /api/v1/cache/{cacheName}/{key}
• 描述: 失效指定缓存空间下的某个键。
• 成功响应 (204 No Content)

4. 数据分析 (Analytics)

4.1 获取排行榜

• Endpoint: GET /api/v1/activities/{id}/leaderboard

• 描述: 返回指定活动的排行榜（已启用缓存 leaderboards）。支持分页与 TopN。

• 查询参数:

  • topN 可选：只取前 N 名（先截断再分页）。
  • page 可选，默认 0：页码（从 0 开始）。
  • size 可选，默认 20：每页条数。

• 成功响应 (200 OK):

  {
    "code": 200,
    "message": "success",
    "data": [
      { "userId": 1, "userName": "用户A", "score": 1500 },
      { "userId": 2, "userName": "用户B", "score": 1200 }
    ],
    "meta": {
      "pagination": {
        "page": 0,
        "size": 20,
        "total": 2,
        "totalPages": 1,
        "hasNext": false,
        "hasPrevious": false
      }
    }
  }
  

4.2 导出排行榜CSV

• Endpoint: GET /api/v1/activities/{id}/leaderboard/export

• 描述: 导出排行榜为CSV文件并下载。支持 topN 仅导出前 N 名。

• 成功响应 (200 OK): 响应头 Content-Type: text/csv;charset=UTF-8，Content-Disposition: attachment; filename="leaderboard_{id}.csv"

• CSV示例:

  userId,userName,score
  1,用户A,1500
  2,用户B,1200
  

4.3 获取裂变网络图

• Endpoint: GET /api/v1/activities/{id}/graph

• 描述: 返回指定活动的裂变网络图。支持以某个用户为根、限定层级与结果规模。

• 查询参数:

  • rootUserId 可选：作为根节点的用户ID；为空则返回全量图（受 limit 限制）。
  • maxDepth 可选，默认 3：最大层级深度（从根出发，1 表示仅直推）。
  • limit 可选，默认 1000：返回的最大边数（超出将截断）。

• 成功响应 (200 OK):

  {
    "code": 200,
    "message": "success",
    "data": {
      "nodes": [ { "id": "1", "label": "用户1" } ],
      "edges": [ { "from": "1", "to": "2" } ]
    }
  }
  

4.4 获取仪表盘统计

• Endpoint: GET /api/v1/activities/{id}/stats

• 描述: 汇总 daily_activity_stats 表的数据（已启用缓存 activity_stats）。participants 对应每日新增注册数聚合。

• 成功响应 (200 OK):

  {
    "code": 200,
    "message": "success",
    "data": {
      "totalParticipants": 220,
      "totalShares": 110,
      "dailyStats": [
        { "date": "2025-09-28", "participants": 100, "shares": 50 },
        { "date": "2025-09-29", "participants": 120, "shares": 60 }
      ]
    }
  }
  

5. 短链接 (Short Links)

5.1 生成短链接（内部）

• Endpoint: POST /api/v1/internal/shorten

• 描述: 生成短链接记录，仅供内部服务或管理端调用。

• 请求体:

  { "originalUrl": "https://example.com/landing?ref=abc" }
  

• 成功响应 (201 Created):

  {
    "code": 201,
    "message": "success",
    "data": { "code": "abc12345", "path": "/r/abc12345", "originalUrl": "https://example.com/landing?ref=abc" }
  }
  

5.2 短链接重定向（公开）

• Endpoint: GET /r/{code}
• 描述: 302 跳转到短链对应的原始地址。
• 成功响应 (302 Found): 响应头 Location: <originalUrl>

6. 用户端体验 (User Experience)

6.1 获取用户专属邀请信息

• Endpoint: GET /api/v1/me/invitation-info

• 描述: 返回当前用户的专属短链接（示例以 query 参数的 activityId/userId 代替鉴权）。

• Query: activityId, userId

• 成功响应 (200 OK):

  {
    "code": 200,
    "message": "success",
    "data": { "code": "inv12345", "path": "/r/inv12345", "originalUrl": "https://example.com/landing?activityId=1&inviter=2" }
  }
  

6.2 获取邀请好友列表（分页）

• Endpoint: GET /api/v1/me/invited-friends

• Query: activityId, userId, page（默认0）, size（默认20）

• 成功响应 (200 OK):

  {
    "code": 200,
    "message": "success",
    "data": [ { "nickname": "用户10", "maskedPhone": "138****0010", "status": "registered" } ],
    "meta": {
      "pagination": {
        "page": 0,
        "size": 20,
        "total": 1,
        "totalPages": 1,
        "hasNext": false,
        "hasPrevious": false
      }
    }
  }
  

6.3 生成海报

• 图片：GET /api/v1/me/poster/image
• HTML：GET /api/v1/me/poster/html
• 配置：GET /api/v1/me/poster/config
• Query: activityId, userId, template（template 可选）
• 描述：图片/HTML 端点返回二进制或 HTML；配置端点返回 ApiResponse<PosterConfigDto>，data 包含 template、imageUrl、htmlUrl。