chore: initial commit with CI pipeline, review and tasks docs

docs/api.md

@@ -0,0 +1,99 @@
+# 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` 不存在。