chore: sync local latest state and repository cleanup

docs/api.md

@@ -46,9 +46,57 @@
 
 ## 认证与鉴权
 
-- `/api/**` 需要 `X-API-Key`。
-- `/api/v1/me/**`、`/api/v1/activities/**`、`/api/v1/api-keys/**`、`/api/v1/share/**` 需要 `Authorization: Bearer <token>`。
-- `/r/**`、`/actuator/**` 不需要认证。
+### 认证矩阵
+
+| 路径模式 | 认证方式 | 说明 |
+|----------|----------|------|
+| `/r/**` | 无需认证 | 短链接跳转 |
+| `/actuator/**` | 无需认证 | Spring Boot Actuator |
+| `/api/v1/callback/**` | X-API-Key | 第三方回调接口 |
+| `/api/v1/share/**` | X-API-Key + Bearer Token | 分享跟踪接口 |
+| `/api/v1/me/**` | Bearer Token | 用户中心接口 |
+| `/api/v1/activities/**` | Bearer Token | 用户端活动接口 |
+| `/api/v1/activities/admin/**` | Bearer Token + 权限校验 | 管理后台活动接口 |
+| `/api/v1/rewards/admin/**` | Bearer Token + 权限校验 | 管理后台奖励接口 |
+| `/api/v1/roles/**` | Bearer Token + 权限校验 | 角色管理接口 |
+| `/api/v1/departments/**` | Bearer Token + 权限校验 | 部门管理接口 |
+| `/api/v1/approval/**` | Bearer Token + 权限校验 | 审批中心接口 |
+| `/api/v1/users/**` | Bearer Token + 权限校验 | 用户管理接口 |
+| `/api/v1/permissions/**` | Bearer Token + 权限校验 | 权限管理接口 |
+| `/api/v1/invites/**` | Bearer Token + 权限校验 | 邀请管理接口 |
+| `/api/v1/notifications/**` | Bearer Token + 权限校验 | 通知管理接口 |
+| `/api/v1/risk/**` | Bearer Token + 权限校验 | 风险管理接口 |
+| `/api/v1/audit/**` | Bearer Token + 权限校验 | 审计日志接口 |
+| `/api/v1/system/**` | Bearer Token + 权限校验 | 系统管理接口 |
+| `/api/v1/dashboard/**` | Bearer Token + 权限校验 | 仪表盘接口 |
+| `/api/v1/api-keys/**` | Bearer Token + 权限校验 | API密钥管理接口 |
+
+### 认证示例
+
+**回调接口（仅需API Key）：**
+```http
+POST /api/v1/callback/register
+X-API-Key: a1b2c3d4-e5f6-7890-1234-567890abcdef
+Content-Type: application/json
+
+{"trackingId": "track-abc123", "externalUserId": "user456", "timestamp": 1699999999999}
+```
+
+**分享跟踪接口（需要API Key + Bearer Token）：**
+```http
+POST /api/v1/share/track
+X-API-Key: a1b2c3d4-e5f6-7890-1234-567890abcdef
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+
+{"activityId": 1, "inviterUserId": "user123", "source": "wechat"}
+```
+
+**管理后台接口（仅需Bearer Token）：**
+```http
+GET /api/v1/activities/admin?page=0&size=20
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
 
 ## 错误码
 
@@ -128,7 +176,7 @@
 ### 2.1 创建API密钥
 
 - **Endpoint**: `POST /api/v1/api-keys`
-- **描述**: 为指定的活动创建一个新的API密钥。密钥仅在本次响应中明文返回，请立即保存。
+- **描述**: 为指定的活动创建一个新的API密钥。该操作需要审批，密钥创建后会进入审批流程。返回 `pendingId` 用于查询审批状态，`recordId` 用于追踪审批记录。
 - **请求体**: `application/json`
 
   ```json
@@ -145,12 +193,21 @@
     "code": 201,
     "message": "success",
     "data": {
-      "apiKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
+      "pendingId": 123,
+      "recordId": 456,
+      "status": "PENDING",
+      "activityId": 1,
+      "name": "我的第一个密钥"
     },
     "timestamp": "2025-03-01T10:00:00"
   }
   ```
 
+- **响应字段说明**:
+  - `pendingId`: 待审批的API密钥ID
+  - `recordId`: 审批记录ID，可用于查询审批进度
+  - `status`: 审批状态 (`PENDING` = 待审批, `APPROVED` = 已通过, `REJECTED` = 已拒绝)
+
 - **失败响应**:
   - `400 Bad Request`: 如果请求数据无效（例如，`activityId` 或 `name` 为空）。
   - `404 Not Found`: 如果 `activityId` 不存在。
@@ -559,18 +616,31 @@
 
 ## 8. 回调管理 (Callbacks)
 
-### 8.1 注册回调
+### 8.1 用户追踪注册
 
 - **Endpoint**: `POST /api/v1/callback/register`
-- **描述**: 注册业务回调，用于接收活动相关事件通知
+- **描述**: 用户参与活动时进行追踪注册上报，用于记录用户来源和设备信息
 - **请求体**: `application/json`
 
   ```json
   {
-    "activityId": 1,
-    "callbackUrl": "https://your-domain.com/webhook",
-    "events": ["user.registered", "user.invited", "reward.granted"],
-    "secret": "your-webhook-secret"
+    "trackingId": "活动创建的追踪ID",
+    "externalUserId": "外部用户ID（可选）",
+    "timestamp": 1699999999999,
+    "deviceFingerprint": "设备指纹（可选）",
+    "ip": "客户端IP（可选）"
+  }
+  ```
+
+  或使用下划线格式:
+
+  ```json
+  {
+    "tracking_id": "活动创建的追踪ID",
+    "external_user_id": "外部用户ID（可选）",
+    "timestamp": 1699999999999,
+    "device_fingerprint": "设备指纹（可选）",
+    "ip": "客户端IP（可选）"
   }
   ```
 
@@ -581,29 +651,20 @@
     "code": 200,
     "message": "success",
     "data": {
-      "callbackId": "cb-123456",
+      "registered": true,
+      "trackingId": "活动创建的追踪ID",
       "activityId": 1,
-      "callbackUrl": "https://your-domain.com/webhook",
-      "status": "active"
+      "rewardStatus": "pending"
     }
   }
   ```
 
-- **回调事件格式**:
-
-  ```json
-  {
-    "eventType": "user.registered",
-    "eventId": "evt-abc123",
-    "timestamp": "2025-03-01T10:00:00Z",
-    "data": {
-      "activityId": 1,
-      "userId": 123,
-      "inviterUserId": 456
-    },
-    "signature": "sha256-hash-of-payload"
-  }
-  ```
+- **字段说明**:
+  - `trackingId` / `tracking_id`: 活动创建的追踪ID（必填）
+  - `externalUserId` / `external_user_id`: 外部系统用户ID（可选）
+  - `timestamp`: 时间戳（可选）
+  - `deviceFingerprint` / `device_fingerprint`: 设备指纹（可选，用于风控）
+  - `ip`: 客户端IP地址（可选，用于风控）
 
 ## 9. 用户奖励 (User Rewards)