wenzi/docs/api.md

# API 文档

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

## 1. 活动管理 (Activities)

### 1.1 创建活动

- **Endpoint**: `POST /api/v1/activities`
- **描述**: 创建一个新的营销活动。
- **请求体**: `application/json`

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

- **成功响应 (201 Created)**:

  ```json
  {
    "id": 1,
    "name": "春季特惠活动",
    "startTime": "2025-03-01T10:00:00+08:00",
    "endTime": "2025-03-31T23:59:59+08:00",
    // ... 其他活动属性
  }
  ```

- **失败响应**:
  - `400 Bad Request`: 如果请求数据无效（例如，名称为空或结束时间早于开始时间）。

### 1.2 更新活动

- **Endpoint**: `PUT /api/v1/activities/{id}`
- **描述**: 更新一个已存在的活动。
- **路径参数**: `id` (long) - 活动的唯一标识符。
- **请求体**: `application/json`

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

- **成功响应 (200 OK)**: 返回更新后的活动对象。
- **失败响应**:
  - `400 Bad Request`: 如果请求数据无效。
  - `404 Not Found`: 如果指定的 `id` 不存在。

### 1.3 获取活动详情

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

## 2. API密钥管理 (API Keys)

### 2.1 创建API密钥

- **Endpoint**: `POST /api/v1/api-keys`
- **描述**: 为指定的活动创建一个新的API密钥。密钥仅在本次响应中明文返回，请立即保存。
- **请求体**: `application/json`

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

- **成功响应 (201 Created)**:

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

- **失败响应**:
  - `400 Bad Request`: 如果请求数据无效（例如，`activityId` 或 `name` 为空）。
  - `404 Not Found`: 如果 `activityId` 不存在。

### 2.2 吊销API密钥

- **Endpoint**: `DELETE /api/v1/api-keys/{id}`
- **描述**: 吊销（删除）一个API密钥。
- **路径参数**: `id` (long) - API密钥的唯一标识符。
- **成功响应 (204 No Content)**: 无响应体。
- **失败响应**:
  - `404 Not Found`: 如果指定的 `id` 不存在。