docs: 完善项目文档并清理过时文件

新增文档： - API_INTEGRATION_GUIDE.md: API集成指南（快速开始、SDK示例、常见场景） - DEPLOYMENT_GUIDE.md: 部署指南（环境要求、生产部署、Docker部署） - CONFIGURATION_GUIDE.md: 配置指南（环境配置、数据库、Redis、安全） - DEVELOPMENT_GUIDE.md: 开发指南（环境搭建、项目结构、开发规范）文档更新： - api.md: 补充8个缺失的API端点（分享跟踪、回调、用户奖励）文档清理： - 归档18个过时文档到 docs/archive/2026-03-04-cleanup/ - 删除3个调试文档（ralph-loop-*）代码清理： - 删除4个.bak备份文件 - 删除1个.disabled测试文件文档结构优化： - 从~40个文档精简到12个核心文档 - 建立清晰的文档导航体系 - 完善文档间的交叉引用
2026-03-04 10:41:38 +08:00
parent e79d69f0af
commit 0eed01e9eb
31 changed files with 3229 additions and 1476 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -375,3 +375,380 @@
 - 配置：`GET /api/v1/me/poster/config`
 - Query: `activityId`, `userId`, `template`（`template` 可选）
 - 描述：图片/HTML 端点返回二进制或 HTML；配置端点返回 `ApiResponse<PosterConfigDto>`，`data` 包含 `template`、`imageUrl`、`htmlUrl`。
+
+## 7. 分享跟踪 (Share Tracking)
+
+### 7.1 创建分享跟踪
+
+- **Endpoint**: `POST /api/v1/share/track`
+- **描述**: 创建分享跟踪记录，用于追踪用户分享行为
+- **请求体**: `application/json`
+
+  ```json
+  {
+    "activityId": 1,
+    "inviterUserId": 123,
+    "source": "wechat",
+    "utm": "campaign-spring"
+  }
+  ```
+
+- **成功响应 (200 OK)**:
+
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": {
+      "trackingId": "track-abc123",
+      "shortCode": "xyz789",
+      "shareUrl": "https://example.com/r/xyz789",
+      "activityId": 1,
+      "inviterUserId": 123
+    }
+  }
+  ```
+
+### 7.2 获取分享指标
+
+- **Endpoint**: `GET /api/v1/share/metrics`
+- **描述**: 获取指定活动的分享统计指标
+- **查询参数**:
+  - `activityId` (必需): 活动ID
+  - `startTime` (可选): 开始时间 (ISO 8601格式)
+  - `endTime` (可选): 结束时间 (ISO 8601格式)
+
+- **成功响应 (200 OK)**:
+
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": {
+      "activityId": 1,
+      "totalClicks": 1500,
+      "uniqueVisitors": 800,
+      "sourceDistribution": {
+        "wechat": 600,
+        "weibo": 400,
+        "direct": 200
+      },
+      "hourlyDistribution": {
+        "0": 50,
+        "1": 30,
+        "2": 20
+      },
+      "startTime": "2025-03-01T00:00:00Z",
+      "endTime": "2025-03-31T23:59:59Z"
+    }
+  }
+  ```
+
+### 7.3 获取顶级分享链接
+
+- **Endpoint**: `GET /api/v1/share/top-links`
+- **描述**: 获取分享次数最多的链接列表
+- **查询参数**:
+  - `activityId` (必需): 活动ID
+  - `limit` (可选，默认10): 返回数量
+
+- **成功响应 (200 OK)**:
+
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": [
+      {
+        "shortCode": "abc123",
+        "clickCount": 500,
+        "inviterUserId": 123
+      },
+      {
+        "shortCode": "def456",
+        "clickCount": 300,
+        "inviterUserId": 456
+      }
+    ]
+  }
+  ```
+
+### 7.4 获取转化漏斗
+
+- **Endpoint**: `GET /api/v1/share/funnel`
+- **描述**: 获取分享转化漏斗数据
+- **查询参数**:
+  - `activityId` (必需): 活动ID
+  - `startTime` (可选): 开始时间
+  - `endTime` (可选): 结束时间
+
+- **成功响应 (200 OK)**:
+
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": {
+      "totalClicks": 1000,
+      "withReferer": 800,
+      "withUserAgent": 950,
+      "refererRate": 0.8,
+      "topReferers": {
+        "google.com": 300,
+        "facebook.com": 200,
+        "twitter.com": 150
+      }
+    }
+  }
+  ```
+
+### 7.5 获取分享元数据
+
+- **Endpoint**: `GET /api/v1/share/share-meta`
+- **描述**: 获取分享相关的元数据配置
+- **查询参数**:
+  - `activityId` (必需): 活动ID
+  - `userId` (必需): 用户ID
+  - `template` (可选，默认"default"): 模板名称
+
+- **成功响应 (200 OK)**:
+
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": {
+      "title": "春季特惠活动",
+      "description": "邀请好友，赢取大奖",
+      "imageUrl": "https://example.com/poster.png",
+      "shareUrl": "https://example.com/r/abc123"
+    }
+  }
+  ```
+
+### 7.6 注册分享来源
+
+- **Endpoint**: `POST /api/v1/share/register-source`
+- **描述**: 注册用户的分享来源渠道
+- **请求体**: `application/json`
+
+  ```json
+  {
+    "activityId": 1,
+    "userId": 123,
+    "channel": "wechat",
+    "params": "utm_source=campaign1"
+  }
+  ```
+
+- **成功响应 (200 OK)**:
+
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": {
+      "trackingId": "track-xyz",
+      "shortCode": "abc789",
+      "shareUrl": "https://example.com/r/abc789",
+      "activityId": 1,
+      "inviterUserId": 123
+    }
+  }
+  ```
+
+## 8. 回调管理 (Callbacks)
+
+### 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"
+  }
+  ```
+
+- **成功响应 (200 OK)**:
+
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": {
+      "callbackId": "cb-123456",
+      "activityId": 1,
+      "callbackUrl": "https://your-domain.com/webhook",
+      "status": "active"
+    }
+  }
+  ```
+
+- **回调事件格式**:
+
+  ```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"
+  }
+  ```
+
+## 9. 用户奖励 (User Rewards)
+
+### 9.1 获取用户奖励列表
+
+- **Endpoint**: `GET /api/v1/me/rewards`
+- **描述**: 获取当前用户的奖励记录（分页）
+- **查询参数**:
+  - `activityId` (必需): 活动ID
+  - `userId` (必需): 用户ID
+  - `page` (可选，默认0): 页码
+  - `size` (可选，默认20): 每页数量
+
+- **成功响应 (200 OK)**:
+
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": [
+      {
+        "type": "invite_reward",
+        "points": 100,
+        "createdAt": "2025-03-01T10:00:00Z"
+      },
+      {
+        "type": "share_reward",
+        "points": 50,
+        "createdAt": "2025-03-02T15:30:00Z"
+      }
+    ],
+    "meta": {
+      "pagination": {
+        "page": 0,
+        "size": 20,
+        "total": 2,
+        "totalPages": 1,
+        "hasNext": false,
+        "hasPrevious": false
+      }
+    }
+  }
+  ```
+
+## 10. 速率限制
+
+所有API端点都受到速率限制保护：
+
+- **默认限制**: 每分钟100次请求（基于API Key）
+- **超出限制响应 (429 Too Many Requests)**:
+
+  ```json
+  {
+    "code": 429,
+    "message": "Rate limit exceeded",
+    "error": {
+      "message": "Too many requests, please try again later",
+      "code": "RATE_LIMIT_EXCEEDED"
+    }
+  }
+  ```
+
+- **响应头**:
+  - `X-RateLimit-Limit`: 速率限制值
+  - `X-RateLimit-Remaining`: 剩余请求次数
+  - `Retry-After`: 重试等待秒数
+
+## 11. API版本控制
+
+- **当前版本**: v1
+- **版本指定**: 通过URL路径 `/api/v1/...`
+- **版本协商**: 可通过 `X-API-Version` 请求头指定版本（可选）
+- **响应头**: `X-API-Version` 返回实际使用的API版本
+
+## 12. 最佳实践
+
+### 12.1 错误处理
+
+```javascript
+try {
+  const response = await fetch('/api/v1/activities/1', {
+    headers: {
+      'X-API-Key': 'your-api-key',
+      'Authorization': 'Bearer your-token'
+    }
+  });
+  
+  const result = await response.json();
+  
+  if (result.code !== 200) {
+    console.error('API Error:', result.error);
+    // 处理业务错误
+  }
+} catch (error) {
+  console.error('Network Error:', error);
+  // 处理网络错误
+}
+```
+
+### 12.2 分页处理
+
+```javascript
+async function fetchAllPages(activityId) {
+  let page = 0;
+  let allData = [];
+  let hasNext = true;
+  
+  while (hasNext) {
+    const response = await fetch(
+      `/api/v1/activities/${activityId}/leaderboard?page=${page}&size=100`,
+      { headers: { 'X-API-Key': 'your-key' } }
+    );
+    const result = await response.json();
+    
+    allData = allData.concat(result.data);
+    hasNext = result.meta.pagination.hasNext;
+    page++;
+  }
+  
+  return allData;
+}
+```
+
+### 12.3 速率限制处理
+
+```javascript
+async function apiCallWithRetry(url, options, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    const response = await fetch(url, options);
+    
+    if (response.status === 429) {
+      const retryAfter = response.headers.get('Retry-After') || 60;
+      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
+      continue;
+    }
+    
+    return response;
+  }
+  
+  throw new Error('Max retries exceeded');
+}
+```
+
+---
+
+**文档版本**: 2.0
+**最后更新**: 2026-03-04
+**维护者**: 技术团队