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/.claude/settings.local.json
+++ b/.claude/settings.local.json
--- a/docs/API_INTEGRATION_GUIDE.md
+++ b/docs/API_INTEGRATION_GUIDE.md
@@ -0,0 +1,682 @@
+# 🔌 API集成指南
+
+> 版本: 1.0
+> 更新时间: 2026-03-04
+
+## 📋 目录
+
+1. [快速开始](#快速开始)
+2. [认证配置](#认证配置)
+3. [SDK集成](#sdk集成)
+4. [常见场景](#常见场景)
+5. [错误处理](#错误处理)
+6. [最佳实践](#最佳实践)
+
+## 🚀 快速开始
+
+### 前置条件
+
+- 已获取API密钥（通过管理后台创建）
+- 已获取Bearer Token（用于用户相关接口）
+- 了解基本的RESTful API概念
+
+### 5分钟快速集成
+
+```javascript
+// 1. 配置API客户端
+const API_BASE_URL = 'https://api.example.com';
+const API_KEY = 'your-api-key-here';
+const BEARER_TOKEN = 'your-bearer-token-here';
+
+// 2. 创建活动
+async function createActivity() {
+  const response = await fetch(`${API_BASE_URL}/api/v1/activities`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': API_KEY,
+      'Authorization': `Bearer ${BEARER_TOKEN}`
+    },
+    body: JSON.stringify({
+      name: '春季特惠活动',
+      startTime: '2025-03-01T10:00:00+08:00',
+      endTime: '2025-03-31T23:59:59+08:00'
+    })
+  });
+
+  const result = await response.json();
+  console.log('活动创建成功:', result.data);
+  return result.data;
+}
+
+// 3. 获取排行榜
+async function getLeaderboard(activityId) {
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/activities/${activityId}/leaderboard?page=0&size=20`,
+    {
+      headers: {
+        'X-API-Key': API_KEY,
+        'Authorization': `Bearer ${BEARER_TOKEN}`
+      }
+    }
+  );
+
+  const result = await response.json();
+  console.log('排行榜数据:', result.data);
+  return result.data;
+}
+
+// 4. 创建分享跟踪
+async function trackShare(activityId, userId) {
+  const response = await fetch(`${API_BASE_URL}/api/v1/share/track`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': API_KEY,
+      'Authorization': `Bearer ${BEARER_TOKEN}`
+    },
+    body: JSON.stringify({
+      activityId: activityId,
+      inviterUserId: userId,
+      source: 'wechat'
+    })
+  });
+
+  const result = await response.json();
+  console.log('分享跟踪创建成功:', result.data);
+  return result.data;
+}
+```
+
+## 🔐 认证配置
+
+### API密钥认证
+
+所有 `/api/**` 端点都需要 `X-API-Key` 请求头：
+
+```http
+GET /api/v1/activities/1
+X-API-Key: a1b2c3d4-e5f6-7890-1234-567890abcdef
+```
+
+**获取API密钥：**
+
+```bash
+curl -X POST https://api.example.com/api/v1/api-keys \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: admin-key" \
+  -H "Authorization: Bearer admin-token" \
+  -d '{
+    "activityId": 1,
+    "name": "我的应用密钥"
+  }'
+```
+
+### Bearer Token认证
+
+用户相关端点需要 `Authorization` 请求头：
+
+```http
+GET /api/v1/me/invitation-info
+X-API-Key: a1b2c3d4-e5f6-7890-1234-567890abcdef
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+### 双重认证
+
+某些端点需要同时提供API密钥和Bearer Token：
+
+```javascript
+const headers = {
+  'X-API-Key': API_KEY,
+  'Authorization': `Bearer ${BEARER_TOKEN}`,
+  'Content-Type': 'application/json'
+};
+```
+
+## 📦 SDK集成
+
+### Java SDK
+
+```xml
+<!-- Maven依赖 -->
+<dependency>
+  <groupId>com.mosquito</groupId>
+  <artifactId>mosquito-sdk</artifactId>
+  <version>1.0.0</version>
+</dependency>
+```
+
+```java
+// 初始化客户端
+MosquitoClient client = MosquitoClient.builder()
+    .baseUrl("https://api.example.com")
+    .apiKey("your-api-key")
+    .bearerToken("your-bearer-token")
+    .build();
+
+// 创建活动
+Activity activity = client.activities()
+    .create(CreateActivityRequest.builder()
+        .name("春季特惠活动")
+        .startTime(ZonedDateTime.now())
+        .endTime(ZonedDateTime.now().plusDays(30))
+        .build());
+
+// 获取排行榜
+List<LeaderboardEntry> leaderboard = client.activities()
+    .getLeaderboard(activityId, 0, 20);
+
+// 创建分享跟踪
+ShareTrackingResponse tracking = client.share()
+    .track(activityId, userId, "wechat");
+```
+
+### JavaScript/TypeScript SDK
+
+```bash
+npm install @mosquito/sdk
+```
+
+```typescript
+import { MosquitoClient } from '@mosquito/sdk';
+
+// 初始化客户端
+const client = new MosquitoClient({
+  baseUrl: 'https://api.example.com',
+  apiKey: 'your-api-key',
+  bearerToken: 'your-bearer-token'
+});
+
+// 创建活动
+const activity = await client.activities.create({
+  name: '春季特惠活动',
+  startTime: new Date('2025-03-01T10:00:00+08:00'),
+  endTime: new Date('2025-03-31T23:59:59+08:00')
+});
+
+// 获取排行榜
+const leaderboard = await client.activities.getLeaderboard(activityId, {
+  page: 0,
+  size: 20
+});
+
+// 创建分享跟踪
+const tracking = await client.share.track({
+  activityId,
+  inviterUserId: userId,
+  source: 'wechat'
+});
+```
+
+### Python SDK
+
+```bash
+pip install mosquito-sdk
+```
+
+```python
+from mosquito import MosquitoClient
+
+# 初始化客户端
+client = MosquitoClient(
+    base_url='https://api.example.com',
+    api_key='your-api-key',
+    bearer_token='your-bearer-token'
+)
+
+# 创建活动
+activity = client.activities.create(
+    name='春季特惠活动',
+    start_time='2025-03-01T10:00:00+08:00',
+    end_time='2025-03-31T23:59:59+08:00'
+)
+
+# 获取排行榜
+leaderboard = client.activities.get_leaderboard(
+    activity_id=activity_id,
+    page=0,
+    size=20
+)
+
+# 创建分享跟踪
+tracking = client.share.track(
+    activity_id=activity_id,
+    inviter_user_id=user_id,
+    source='wechat'
+)
+```
+
+## 🎯 常见场景
+
+### 场景1：用户邀请流程
+
+```javascript
+// 1. 用户登录后获取邀请信息
+async function getUserInvitationInfo(activityId, userId) {
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/me/invitation-info?activityId=${activityId}&userId=${userId}`,
+    { headers: { 'X-API-Key': API_KEY, 'Authorization': `Bearer ${BEARER_TOKEN}` } }
+  );
+  const result = await response.json();
+  return result.data; // { code, path, originalUrl }
+}
+
+// 2. 生成分享海报
+async function generatePoster(activityId, userId, template = 'default') {
+  const imageUrl = `${API_BASE_URL}/api/v1/me/poster/image?activityId=${activityId}&userId=${userId}&template=${template}`;
+  return imageUrl;
+}
+
+// 3. 用户分享后创建跟踪
+async function trackUserShare(activityId, userId, source) {
+  const response = await fetch(`${API_BASE_URL}/api/v1/share/track`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': API_KEY,
+      'Authorization': `Bearer ${BEARER_TOKEN}`
+    },
+    body: JSON.stringify({ activityId, inviterUserId: userId, source })
+  });
+  return await response.json();
+}
+
+// 4. 查看邀请的好友列表
+async function getInvitedFriends(activityId, userId, page = 0) {
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/me/invited-friends?activityId=${activityId}&userId=${userId}&page=${page}&size=20`,
+    { headers: { 'X-API-Key': API_KEY, 'Authorization': `Bearer ${BEARER_TOKEN}` } }
+  );
+  const result = await response.json();
+  return result.data;
+}
+
+// 5. 查看用户奖励
+async function getUserRewards(activityId, userId, page = 0) {
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/me/rewards?activityId=${activityId}&userId=${userId}&page=${page}&size=20`,
+    { headers: { 'X-API-Key': API_KEY, 'Authorization': `Bearer ${BEARER_TOKEN}` } }
+  );
+  const result = await response.json();
+  return result.data;
+}
+```
+
+### 场景2：活动数据分析
+
+```javascript
+// 1. 获取活动统计数据
+async function getActivityStats(activityId) {
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/activities/${activityId}/stats`,
+    { headers: { 'X-API-Key': API_KEY, 'Authorization': `Bearer ${BEARER_TOKEN}` } }
+  );
+  const result = await response.json();
+  return result.data; // { totalParticipants, totalShares, dailyStats }
+}
+
+// 2. 获取裂变网络图
+async function getActivityGraph(activityId, rootUserId = null, maxDepth = 3) {
+  const params = new URLSearchParams({
+    ...(rootUserId && { rootUserId }),
+    maxDepth,
+    limit: 1000
+  });
+
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/activities/${activityId}/graph?${params}`,
+    { headers: { 'X-API-Key': API_KEY, 'Authorization': `Bearer ${BEARER_TOKEN}` } }
+  );
+  const result = await response.json();
+  return result.data; // { nodes, edges }
+}
+
+// 3. 获取分享指标
+async function getShareMetrics(activityId, startTime, endTime) {
+  const params = new URLSearchParams({
+    activityId,
+    ...(startTime && { startTime }),
+    ...(endTime && { endTime })
+  });
+
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/share/metrics?${params}`,
+    { headers: { 'X-API-Key': API_KEY, 'Authorization': `Bearer ${BEARER_TOKEN}` } }
+  );
+  const result = await response.json();
+  return result.data;
+}
+
+// 4. 获取转化漏斗
+async function getConversionFunnel(activityId, startTime, endTime) {
+  const params = new URLSearchParams({
+    activityId,
+    ...(startTime && { startTime }),
+    ...(endTime && { endTime })
+  });
+
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/share/funnel?${params}`,
+    { headers: { 'X-API-Key': API_KEY, 'Authorization': `Bearer ${BEARER_TOKEN}` } }
+  );
+  const result = await response.json();
+  return result.data;
+}
+
+// 5. 导出排行榜CSV
+async function exportLeaderboard(activityId, topN = null) {
+  const params = new URLSearchParams({
+    ...(topN && { topN })
+  });
+
+  const response = await fetch(
+    `${API_BASE_URL}/api/v1/activities/${activityId}/leaderboard/export?${params}`,
+    { headers: { 'X-API-Key': API_KEY, 'Authorization': `Bearer ${BEARER_TOKEN}` } }
+  );
+
+  const blob = await response.blob();
+  const url = window.URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = `leaderboard_${activityId}.csv`;
+  a.click();
+}
+```
+
+### 场景3：Webhook回调集成
+
+```javascript
+// 1. 注册Webhook
+async function registerWebhook(activityId, callbackUrl, events) {
+  const response = await fetch(`${API_BASE_URL}/api/v1/callback/register`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': API_KEY,
+      'Authorization': `Bearer ${BEARER_TOKEN}`
+    },
+    body: JSON.stringify({
+      activityId,
+      callbackUrl,
+      events, // ['user.registered', 'user.invited', 'reward.granted']
+      secret: 'your-webhook-secret'
+    })
+  });
+  return await response.json();
+}
+
+// 2. 处理Webhook回调（服务端）
+const express = require('express');
+const crypto = require('crypto');
+
+app.post('/webhook', express.json(), (req, res) => {
+  const signature = req.headers['x-webhook-signature'];
+  const payload = JSON.stringify(req.body);
+  const secret = 'your-webhook-secret';
+
+  // 验证签名
+  const expectedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(payload)
+    .digest('hex');
+
+  if (signature !== `sha256=${expectedSignature}`) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  // 处理事件
+  const { eventType, data } = req.body;
+
+  switch (eventType) {
+    case 'user.registered':
+      console.log('新用户注册:', data);
+      break;
+    case 'user.invited':
+      console.log('用户邀请:', data);
+      break;
+    case 'reward.granted':
+      console.log('奖励发放:', data);
+      break;
+  }
+
+  res.status(200).send('OK');
+});
+```
+
+## ⚠️ 错误处理
+
+### 统一错误处理
+
+```javascript
+class APIError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+}
+
+async function apiCall(url, options) {
+  try {
+    const response = await fetch(url, options);
+    const result = await response.json();
+
+    if (result.code !== 200 && result.code !== 201) {
+      throw new APIError(
+        result.error?.code || 'UNKNOWN_ERROR',
+        result.message || 'Unknown error',
+        result.error?.details
+      );
+    }
+
+    return result.data;
+  } catch (error) {
+    if (error instanceof APIError) {
+      throw error;
+    }
+    throw new APIError('NETWORK_ERROR', 'Network request failed', error);
+  }
+}
+
+// 使用示例
+try {
+  const activity = await apiCall(`${API_BASE_URL}/api/v1/activities/1`, {
+    headers: { 'X-API-Key': API_KEY }
+  });
+  console.log('活动数据:', activity);
+} catch (error) {
+  if (error.code === 'NOT_FOUND') {
+    console.error('活动不存在');
+  } else if (error.code === 'INVALID_API_KEY') {
+    console.error('API密钥无效');
+  } else {
+    console.error('请求失败:', error.message);
+  }
+}
+```
+
+### 重试机制
+
+```javascript
+async function apiCallWithRetry(url, options, maxRetries = 3) {
+  let lastError;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const response = await fetch(url, options);
+
+      // 处理速率限制
+      if (response.status === 429) {
+        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
+        console.log(`速率限制，等待 ${retryAfter} 秒后重试...`);
+        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
+        continue;
+      }
+
+      // 处理服务器错误
+      if (response.status >= 500) {
+        console.log(`服务器错误，${i + 1}/${maxRetries} 次重试...`);
+        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
+        continue;
+      }
+
+      return await response.json();
+    } catch (error) {
+      lastError = error;
+      if (i < maxRetries - 1) {
+        console.log(`网络错误，${i + 1}/${maxRetries} 次重试...`);
+        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
+      }
+    }
+  }
+
+  throw lastError;
+}
+```
+
+## 💡 最佳实践
+
+### 1. 使用连接池
+
+```javascript
+// Node.js
+const https = require('https');
+
+const agent = new https.Agent({
+  keepAlive: true,
+  maxSockets: 50,
+  maxFreeSockets: 10,
+  timeout: 60000
+});
+
+const response = await fetch(url, {
+  agent,
+  headers: { 'X-API-Key': API_KEY }
+});
+```
+
+### 2. 实现请求缓存
+
+```javascript
+const cache = new Map();
+const CACHE_TTL = 60000; // 1分钟
+
+async function cachedApiCall(url, options, ttl = CACHE_TTL) {
+  const cacheKey = `${url}:${JSON.stringify(options)}`;
+  const cached = cache.get(cacheKey);
+
+  if (cached && Date.now() - cached.timestamp < ttl) {
+    return cached.data;
+  }
+
+  const data = await apiCall(url, options);
+  cache.set(cacheKey, { data, timestamp: Date.now() });
+
+  return data;
+}
+```
+
+### 3. 批量请求优化
+
+```javascript
+async function batchGetActivities(activityIds) {
+  // 并发请求，但限制并发数
+  const BATCH_SIZE = 10;
+  const results = [];
+
+  for (let i = 0; i < activityIds.length; i += BATCH_SIZE) {
+    const batch = activityIds.slice(i, i + BATCH_SIZE);
+    const promises = batch.map(id =>
+      apiCall(`${API_BASE_URL}/api/v1/activities/${id}`, {
+        headers: { 'X-API-Key': API_KEY }
+      })
+    );
+
+    const batchResults = await Promise.all(promises);
+    results.push(...batchResults);
+  }
+
+  return results;
+}
+```
+
+### 4. 监控和日志
+
+```javascript
+function logApiCall(url, options, duration, result) {
+  console.log({
+    timestamp: new Date().toISOString(),
+    url,
+    method: options.method || 'GET',
+    duration: `${duration}ms`,
+    status: result.code,
+    success: result.code === 200 || result.code === 201
+  });
+}
+
+async function monitoredApiCall(url, options) {
+  const startTime = Date.now();
+  try {
+    const result = await apiCall(url, options);
+    logApiCall(url, options, Date.now() - startTime, result);
+    return result;
+  } catch (error) {
+    logApiCall(url, options, Date.now() - startTime, { code: error.code, error: error.message });
+    throw error;
+  }
+}
+```
+
+### 5. 安全最佳实践
+
+```javascript
+// ❌ 不要在客户端暴露API密钥
+// const API_KEY = 'a1b2c3d4-e5f6-7890-1234-567890abcdef';
+
+// ✅ 通过后端代理API请求
+async function proxyApiCall(endpoint, options) {
+  const response = await fetch(`/api/proxy${endpoint}`, {
+    ...options,
+    headers: {
+      ...options.headers,
+      'Authorization': `Bearer ${userToken}` // 只传用户token
+    }
+  });
+  return await response.json();
+}
+
+// 后端代理（Node.js/Express）
+app.use('/api/proxy', async (req, res) => {
+  const response = await fetch(`${API_BASE_URL}${req.path}`, {
+    method: req.method,
+    headers: {
+      'X-API-Key': process.env.API_KEY, // 从环境变量读取
+      'Authorization': req.headers.authorization,
+      'Content-Type': 'application/json'
+    },
+    body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined
+  });
+
+  const result = await response.json();
+  res.json(result);
+});
+```
+
+## 📚 相关资源
+
+- [API文档](./api.md) - 完整的API端点参考
+- [部署指南](./DEPLOYMENT_GUIDE.md) - 如何部署应用
+- [配置指南](./CONFIGURATION_GUIDE.md) - 配置选项说明
+- [开发指南](./DEVELOPMENT_GUIDE.md) - 如何参与开发
+
+## 🆘 获取帮助
+
+- **技术支持**: support@example.com
+- **问题反馈**: https://github.com/your-org/mosquito/issues
+- **API状态**: https://status.example.com
+
+---
+
+**文档版本**: 1.0
+**最后更新**: 2026-03-04
--- a/docs/CONFIGURATION_GUIDE.md
+++ b/docs/CONFIGURATION_GUIDE.md
@@ -0,0 +1,721 @@
+# ⚙️ 配置指南
+
+> 版本: 1.0
+> 更新时间: 2026-03-04
+
+## 📋 目录
+
+1. [配置文件结构](#配置文件结构)
+2. [环境配置](#环境配置)
+3. [数据库配置](#数据库配置)
+4. [Redis配置](#redis配置)
+5. [安全配置](#安全配置)
+6. [性能配置](#性能配置)
+7. [日志配置](#日志配置)
+8. [环境变量](#环境变量)
+
+## 📁 配置文件结构
+
+```
+src/main/resources/
+├── application.properties          # 主配置文件
+├── application-dev.yml            # 开发环境配置
+├── application-test.yml           # 测试环境配置
+├── application-prod.yml           # 生产环境配置
+├── application-e2e.properties     # E2E测试配置
+└── logback-spring.xml             # 日志配置
+```
+
+### 配置优先级
+
+1. 命令行参数 (`--spring.datasource.url=...`)
+2. 环境变量 (`SPRING_DATASOURCE_URL`)
+3. 外部配置文件 (`/opt/mosquito/application-prod.yml`)
+4. 内部配置文件 (`classpath:application-prod.yml`)
+5. 默认配置 (`application.properties`)
+
+## 🌍 环境配置
+
+### 开发环境 (dev)
+
+`application-dev.yml`:
+
+```yaml
+spring:
+  datasource:
+    url: jdbc:postgresql://localhost:5432/mosquito_dev
+    username: mosquito
+    password: dev_password
+    hikari:
+      maximum-pool-size: 10
+      minimum-idle: 2
+
+  data:
+    redis:
+      host: localhost
+      port: 6379
+      password: dev_redis_password
+
+  flyway:
+    enabled: true
+    baseline-on-migrate: true
+
+  jpa:
+    show-sql: true
+    properties:
+      hibernate:
+        format_sql: true
+
+app:
+  api-key:
+    encryption-key: dev_32_char_encryption_key_12
+  rate-limit:
+    per-minute: 1000
+  poster:
+    cache-enabled: false
+
+logging:
+  level:
+    root: INFO
+    com.mosquito.project: DEBUG
+    org.springframework.web: DEBUG
+```
+
+### 测试环境 (test)
+
+`application-test.yml`:
+
+```yaml
+spring:
+  datasource:
+    url: jdbc:h2:mem:testdb
+    driver-class-name: org.h2.Driver
+    username: sa
+    password:
+
+  data:
+    redis:
+      host: localhost
+      port: 6379
+
+  flyway:
+    enabled: true
+
+  jpa:
+    hibernate:
+      ddl-auto: validate
+
+app:
+  api-key:
+    encryption-key: test_32_char_encryption_key_12
+  rate-limit:
+    per-minute: 10000
+  poster:
+    cache-enabled: false
+
+logging:
+  level:
+    root: WARN
+    com.mosquito.project: INFO
+```
+
+### 生产环境 (prod)
+
+`application-prod.yml`:
+
+```yaml
+spring:
+  datasource:
+    url: ${DB_URL:jdbc:postgresql://localhost:5432/mosquito_prod}
+    username: ${DB_USERNAME:mosquito_prod}
+    password: ${DB_PASSWORD}
+    hikari:
+      maximum-pool-size: 20
+      minimum-idle: 5
+      connection-timeout: 30000
+      idle-timeout: 600000
+      max-lifetime: 1800000
+      leak-detection-threshold: 60000
+
+  data:
+    redis:
+      host: ${REDIS_HOST:localhost}
+      port: ${REDIS_PORT:6379}
+      password: ${REDIS_PASSWORD}
+      timeout: 3000ms
+      lettuce:
+        pool:
+          max-active: 20
+          max-idle: 10
+          min-idle: 5
+          max-wait: 3000ms
+
+  flyway:
+    enabled: true
+    baseline-on-migrate: true
+    validate-on-migrate: true
+
+  jpa:
+    show-sql: false
+    properties:
+      hibernate:
+        jdbc:
+          batch_size: 20
+        order_inserts: true
+        order_updates: true
+
+app:
+  api-key:
+    encryption-key: ${API_KEY_ENCRYPTION_KEY}
+  rate-limit:
+    per-minute: ${RATE_LIMIT_PER_MINUTE:100}
+  poster:
+    cache-enabled: true
+    cache-ttl: 3600
+
+logging:
+  level:
+    root: INFO
+    com.mosquito.project: INFO
+  file:
+    name: /var/log/mosquito/application.log
+    max-size: 100MB
+    max-history: 30
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics,prometheus
+  endpoint:
+    health:
+      show-details: when-authorized
+```
+
+## 🗄️ 数据库配置
+
+### PostgreSQL连接池
+
+```yaml
+spring:
+  datasource:
+    hikari:
+      # 最大连接数（推荐：CPU核心数 * 2 + 磁盘数）
+      maximum-pool-size: 20
+
+      # 最小空闲连接数
+      minimum-idle: 5
+
+      # 连接超时（毫秒）
+      connection-timeout: 30000
+
+      # 空闲超时（毫秒）
+      idle-timeout: 600000
+
+      # 连接最大生命周期（毫秒）
+      max-lifetime: 1800000
+
+      # 连接泄漏检测阈值（毫秒）
+      leak-detection-threshold: 60000
+
+      # 连接测试查询
+      connection-test-query: SELECT 1
+```
+
+### Flyway迁移配置
+
+```yaml
+spring:
+  flyway:
+    # 启用Flyway
+    enabled: true
+
+    # 迁移脚本位置
+    locations: classpath:db/migration
+
+    # 基线版本
+    baseline-version: 1
+
+    # 在迁移时创建基线
+    baseline-on-migrate: true
+
+    # 验证迁移
+    validate-on-migrate: true
+
+    # 清理数据库（生产环境禁用）
+    clean-disabled: true
+
+    # 占位符
+    placeholders:
+      schema: public
+```
+
+### JPA/Hibernate配置
+
+```yaml
+spring:
+  jpa:
+    # 显示SQL（仅开发环境）
+    show-sql: false
+
+    # DDL策略（生产环境使用validate）
+    hibernate:
+      ddl-auto: validate
+
+    properties:
+      hibernate:
+        # SQL格式化
+        format_sql: true
+
+        # 批量操作
+        jdbc:
+          batch_size: 20
+        order_inserts: true
+        order_updates: true
+
+        # 二级缓存
+        cache:
+          use_second_level_cache: true
+          region:
+            factory_class: org.hibernate.cache.jcache.JCacheRegionFactory
+
+        # 查询缓存
+        cache:
+          use_query_cache: true
+```
+
+## 🔴 Redis配置
+
+### 基础配置
+
+```yaml
+spring:
+  data:
+    redis:
+      # Redis服务器地址
+      host: ${REDIS_HOST:localhost}
+
+      # Redis端口
+      port: ${REDIS_PORT:6379}
+
+      # Redis密码
+      password: ${REDIS_PASSWORD}
+
+      # 数据库索引
+      database: 0
+
+      # 连接超时
+      timeout: 3000ms
+
+      # Lettuce连接池
+      lettuce:
+        pool:
+          max-active: 20
+          max-idle: 10
+          min-idle: 5
+          max-wait: 3000ms
+
+        # 关闭超时
+        shutdown-timeout: 100ms
+```
+
+### 缓存配置
+
+```yaml
+spring:
+  cache:
+    type: redis
+    redis:
+      # 缓存TTL（毫秒）
+      time-to-live: 3600000
+
+      # 缓存null值
+      cache-null-values: false
+
+      # 键前缀
+      key-prefix: "mosquito:"
+
+      # 使用键前缀
+      use-key-prefix: true
+
+app:
+  cache:
+    # 活动缓存TTL（秒）
+    activity-ttl: 3600
+
+    # 统计缓存TTL（秒）
+    stats-ttl: 300
+
+    # 排行榜缓存TTL（秒）
+    leaderboard-ttl: 60
+```
+
+### Redis Sentinel配置（高可用）
+
+```yaml
+spring:
+  data:
+    redis:
+      sentinel:
+        master: mymaster
+        nodes:
+          - 192.168.1.10:26379
+          - 192.168.1.11:26379
+          - 192.168.1.12:26379
+      password: ${REDIS_PASSWORD}
+```
+
+### Redis Cluster配置（集群）
+
+```yaml
+spring:
+  data:
+    redis:
+      cluster:
+        nodes:
+          - 192.168.1.10:6379
+          - 192.168.1.11:6379
+          - 192.168.1.12:6379
+          - 192.168.1.13:6379
+          - 192.168.1.14:6379
+          - 192.168.1.15:6379
+        max-redirects: 3
+      password: ${REDIS_PASSWORD}
+```
+
+## 🔐 安全配置
+
+### API密钥加密
+
+```yaml
+app:
+  api-key:
+    # 加密密钥（必须32字符）
+    encryption-key: ${API_KEY_ENCRYPTION_KEY}
+
+    # PBKDF2迭代次数
+    pbkdf2-iterations: 10000
+
+    # 密钥长度
+    key-length: 256
+```
+
+生成加密密钥：
+
+```bash
+# 生成32字符随机密钥
+openssl rand -base64 24 | head -c 32
+```
+
+### 速率限制
+
+```yaml
+app:
+  rate-limit:
+    # 每分钟请求限制
+    per-minute: ${RATE_LIMIT_PER_MINUTE:100}
+
+    # 限流键前缀
+    key-prefix: "rate_limit:"
+
+    # 限流窗口（秒）
+    window-seconds: 60
+```
+
+### CORS配置
+
+```yaml
+app:
+  cors:
+    # 允许的源
+    allowed-origins:
+      - https://example.com
+      - https://www.example.com
+
+    # 允许的方法
+    allowed-methods:
+      - GET
+      - POST
+      - PUT
+      - DELETE
+      - OPTIONS
+
+    # 允许的头
+    allowed-headers:
+      - "*"
+
+    # 暴露的头
+    exposed-headers:
+      - X-API-Version
+      - X-RateLimit-Remaining
+
+    # 允许凭证
+    allow-credentials: true
+
+    # 预检请求缓存时间（秒）
+    max-age: 3600
+```
+
+## ⚡ 性能配置
+
+### 线程池配置
+
+```yaml
+spring:
+  task:
+    execution:
+      pool:
+        # 核心线程数
+        core-size: 8
+
+        # 最大线程数
+        max-size: 16
+
+        # 队列容量
+        queue-capacity: 100
+
+        # 线程名前缀
+        thread-name-prefix: "async-"
+
+        # 空闲线程存活时间（秒）
+        keep-alive: 60s
+```
+
+### HTTP客户端配置
+
+```yaml
+app:
+  http-client:
+    # 连接超时（毫秒）
+    connect-timeout: 5000
+
+    # 读取超时（毫秒）
+    read-timeout: 10000
+
+    # 最大连接数
+    max-connections: 100
+
+    # 每个路由的最大连接数
+    max-connections-per-route: 20
+```
+
+### 海报生成配置
+
+```yaml
+app:
+  poster:
+    # 启用缓存
+    cache-enabled: true
+
+    # 缓存TTL（秒）
+    cache-ttl: 3600
+
+    # 图片质量（0.0-1.0）
+    image-quality: 0.9
+
+    # 图片格式
+    image-format: PNG
+
+    # 最大宽度
+    max-width: 1080
+
+    # 最大高度
+    max-height: 1920
+```
+
+## 📝 日志配置
+
+### Logback配置
+
+`logback-spring.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+    <!-- 开发环境 -->
+    <springProfile name="dev">
+        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+            <encoder>
+                <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+            </encoder>
+        </appender>
+
+        <root level="INFO">
+            <appender-ref ref="CONSOLE" />
+        </root>
+
+        <logger name="com.mosquito.project" level="DEBUG" />
+        <logger name="org.springframework.web" level="DEBUG" />
+    </springProfile>
+
+    <!-- 生产环境 -->
+    <springProfile name="prod">
+        <!-- 文件输出 -->
+        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+            <file>/var/log/mosquito/application.log</file>
+            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+                <fileNamePattern>/var/log/mosquito/application.%d{yyyy-MM-dd}.log</fileNamePattern>
+                <maxHistory>30</maxHistory>
+                <totalSizeCap>10GB</totalSizeCap>
+            </rollingPolicy>
+            <encoder>
+                <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+            </encoder>
+        </appender>
+
+        <!-- 错误日志单独输出 -->
+        <appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+            <file>/var/log/mosquito/error.log</file>
+            <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
+                <level>ERROR</level>
+            </filter>
+            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+                <fileNamePattern>/var/log/mosquito/error.%d{yyyy-MM-dd}.log</fileNamePattern>
+                <maxHistory>90</maxHistory>
+            </rollingPolicy>
+            <encoder>
+                <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+            </encoder>
+        </appender>
+
+        <root level="INFO">
+            <appender-ref ref="FILE" />
+            <appender-ref ref="ERROR_FILE" />
+        </root>
+
+        <logger name="com.mosquito.project" level="INFO" />
+    </springProfile>
+</configuration>
+```
+
+### 日志级别
+
+```yaml
+logging:
+  level:
+    # 根日志级别
+    root: INFO
+
+    # 应用日志
+    com.mosquito.project: INFO
+
+    # Spring框架
+    org.springframework: INFO
+    org.springframework.web: INFO
+    org.springframework.security: INFO
+
+    # Hibernate
+    org.hibernate: INFO
+    org.hibernate.SQL: DEBUG
+    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
+
+    # Redis
+    org.springframework.data.redis: INFO
+
+    # Flyway
+    org.flywaydb: INFO
+```
+
+## 🌐 环境变量
+
+### 必需环境变量
+
+```bash
+# 数据库配置
+export DB_URL="jdbc:postgresql://localhost:5432/mosquito_prod"
+export DB_USERNAME="mosquito_prod"
+export DB_PASSWORD="your_secure_password"
+
+# Redis配置
+export REDIS_HOST="localhost"
+export REDIS_PORT="6379"
+export REDIS_PASSWORD="your_redis_password"
+
+# 安全配置
+export API_KEY_ENCRYPTION_KEY="your_32_char_encryption_key_12"
+```
+
+### 可选环境变量
+
+```bash
+# 速率限制
+export RATE_LIMIT_PER_MINUTE="100"
+
+# 日志配置
+export LOG_LEVEL="INFO"
+export LOG_FILE="/var/log/mosquito/application.log"
+
+# JVM配置
+export JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC"
+
+# Spring配置
+export SPRING_PROFILES_ACTIVE="prod"
+export SERVER_PORT="8080"
+```
+
+### 环境变量文件
+
+创建 `.env` 文件（不要提交到Git）：
+
+```bash
+# .env
+DB_PASSWORD=your_secure_password
+REDIS_PASSWORD=your_redis_password
+API_KEY_ENCRYPTION_KEY=your_32_char_encryption_key_12
+RATE_LIMIT_PER_MINUTE=100
+```
+
+加载环境变量：
+
+```bash
+# 使用source加载
+source .env
+
+# 或使用export
+export $(cat .env | xargs)
+```
+
+## 🔧 配置验证
+
+### 启动时验证
+
+```java
+@Configuration
+public class ConfigValidation {
+
+    @Value("${app.api-key.encryption-key}")
+    private String encryptionKey;
+
+    @PostConstruct
+    public void validate() {
+        if (encryptionKey.length() != 32) {
+            throw new IllegalStateException(
+                "API key encryption key must be exactly 32 characters"
+            );
+        }
+    }
+}
+```
+
+### 配置检查命令
+
+```bash
+# 检查配置文件语法
+java -jar mosquito-1.0.0.jar --spring.config.location=application-prod.yml --spring.profiles.active=prod --debug
+
+# 查看实际配置
+java -jar mosquito-1.0.0.jar --spring.profiles.active=prod \
+  --spring.boot.admin.client.enabled=false \
+  org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener
+```
+
+## 📚 相关资源
+
+- [部署指南](./DEPLOYMENT_GUIDE.md) - 部署说明
+- [API文档](./api.md) - API接口文档
+- [开发指南](./DEVELOPMENT_GUIDE.md) - 开发环境搭建
+
+---
+
+**文档版本**: 1.0
+**最后更新**: 2026-03-04
--- a/docs/DEPLOYMENT_GUIDE.md
+++ b/docs/DEPLOYMENT_GUIDE.md
@@ -0,0 +1,665 @@
+# 🚀 部署指南
+
+> 版本: 1.0
+> 更新时间: 2026-03-04
+
+## 📋 目录
+
+1. [环境要求](#环境要求)
+2. [快速部署](#快速部署)
+3. [生产环境部署](#生产环境部署)
+4. [Docker部署](#docker部署)
+5. [数据库迁移](#数据库迁移)
+6. [监控与日志](#监控与日志)
+7. [故障排查](#故障排查)
+
+## 🔧 环境要求
+
+### 最低要求
+
+| 组件 | 版本要求 | 说明 |
+|------|----------|------|
+| Java | 17+ | 推荐使用OpenJDK 17或21 |
+| PostgreSQL | 12+ | 推荐使用14或15 |
+| Redis | 6.0+ | 生产环境必需 |
+| Maven | 3.8+ | 构建工具 |
+| 内存 | 2GB+ | 推荐4GB |
+| 磁盘 | 10GB+ | 包含日志和数据 |
+
+### 推荐配置
+
+**开发环境：**
+- CPU: 2核
+- 内存: 4GB
+- 磁盘: 20GB SSD
+
+**生产环境：**
+- CPU: 4核+
+- 内存: 8GB+
+- 磁盘: 50GB+ SSD
+- 负载均衡器（可选）
+- 数据库主从复制（推荐）
+
+## ⚡ 快速部署
+
+### 1. 克隆代码
+
+```bash
+git clone https://github.com/your-org/mosquito.git
+cd mosquito
+```
+
+### 2. 配置数据库
+
+```bash
+# 创建数据库
+psql -U postgres -c "CREATE DATABASE mosquito;"
+psql -U postgres -c "CREATE USER mosquito_user WITH PASSWORD 'your_password';"
+psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE mosquito TO mosquito_user;"
+```
+
+### 3. 配置环境变量
+
+```bash
+# 复制配置模板
+cp src/main/resources/application-dev.yml.example src/main/resources/application-dev.yml
+
+# 编辑配置文件
+vi src/main/resources/application-dev.yml
+```
+
+### 4. 构建项目
+
+```bash
+# 跳过测试快速构建
+mvn clean package -DskipTests
+
+# 或者运行完整测试
+mvn clean package
+```
+
+### 5. 启动应用
+
+```bash
+java -jar target/mosquito-1.0.0.jar --spring.profiles.active=dev
+```
+
+应用将在 `http://localhost:8080` 启动。
+
+## 🏭 生产环境部署
+
+### 1. 准备工作
+
+**创建专用用户：**
+
+```bash
+sudo useradd -r -s /bin/false mosquito
+sudo mkdir -p /opt/mosquito
+sudo chown mosquito:mosquito /opt/mosquito
+```
+
+**配置PostgreSQL：**
+
+```sql
+-- 创建生产数据库
+CREATE DATABASE mosquito_prod;
+CREATE USER mosquito_prod WITH PASSWORD 'strong_password_here';
+GRANT ALL PRIVILEGES ON DATABASE mosquito_prod TO mosquito_prod;
+
+-- 配置连接池
+ALTER SYSTEM SET max_connections = 200;
+ALTER SYSTEM SET shared_buffers = '2GB';
+ALTER SYSTEM SET effective_cache_size = '6GB';
+SELECT pg_reload_conf();
+```
+
+**配置Redis：**
+
+```bash
+# 编辑Redis配置
+sudo vi /etc/redis/redis.conf
+
+# 设置密码
+requirepass your_redis_password
+
+# 设置最大内存
+maxmemory 1gb
+maxmemory-policy allkeys-lru
+
+# 启用持久化
+save 900 1
+save 300 10
+save 60 10000
+
+# 重启Redis
+sudo systemctl restart redis
+```
+
+### 2. 配置应用
+
+创建 `/opt/mosquito/application-prod.yml`：
+
+```yaml
+spring:
+  datasource:
+    url: jdbc:postgresql://localhost:5432/mosquito_prod
+    username: mosquito_prod
+    password: ${DB_PASSWORD}
+    hikari:
+      maximum-pool-size: 20
+      minimum-idle: 5
+      connection-timeout: 30000
+      idle-timeout: 600000
+      max-lifetime: 1800000
+
+  data:
+    redis:
+      host: localhost
+      port: 6379
+      password: ${REDIS_PASSWORD}
+      lettuce:
+        pool:
+          max-active: 20
+          max-idle: 10
+          min-idle: 5
+
+  flyway:
+    enabled: true
+    baseline-on-migrate: true
+
+app:
+  api-key:
+    encryption-key: ${API_KEY_ENCRYPTION_KEY}
+  rate-limit:
+    per-minute: 100
+  poster:
+    cache-enabled: true
+
+logging:
+  level:
+    root: INFO
+    com.mosquito.project: INFO
+  file:
+    name: /var/log/mosquito/application.log
+    max-size: 100MB
+    max-history: 30
+```
+
+### 3. 创建systemd服务
+
+创建 `/etc/systemd/system/mosquito.service`：
+
+```ini
+[Unit]
+Description=Mosquito Activity Tracking Service
+After=network.target postgresql.service redis.service
+
+[Service]
+Type=simple
+User=mosquito
+Group=mosquito
+WorkingDirectory=/opt/mosquito
+
+Environment="JAVA_OPTS=-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"
+Environment="DB_PASSWORD=your_db_password"
+Environment="REDIS_PASSWORD=your_redis_password"
+Environment="API_KEY_ENCRYPTION_KEY=your_32_char_encryption_key"
+
+ExecStart=/usr/bin/java $JAVA_OPTS \
+  -jar /opt/mosquito/mosquito-1.0.0.jar \
+  --spring.profiles.active=prod \
+  --spring.config.location=/opt/mosquito/application-prod.yml
+
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 4. 部署应用
+
+```bash
+# 复制JAR文件
+sudo cp target/mosquito-1.0.0.jar /opt/mosquito/
+sudo chown mosquito:mosquito /opt/mosquito/mosquito-1.0.0.jar
+
+# 创建日志目录
+sudo mkdir -p /var/log/mosquito
+sudo chown mosquito:mosquito /var/log/mosquito
+
+# 重新加载systemd
+sudo systemctl daemon-reload
+
+# 启动服务
+sudo systemctl start mosquito
+
+# 设置开机自启
+sudo systemctl enable mosquito
+
+# 检查状态
+sudo systemctl status mosquito
+```
+
+### 5. 配置Nginx反向代理
+
+创建 `/etc/nginx/sites-available/mosquito`：
+
+```nginx
+upstream mosquito_backend {
+    server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
+    keepalive 32;
+}
+
+server {
+    listen 80;
+    server_name api.example.com;
+
+    # 重定向到HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name api.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+
+    access_log /var/log/nginx/mosquito_access.log;
+    error_log /var/log/nginx/mosquito_error.log;
+
+    client_max_body_size 10M;
+
+    location / {
+        proxy_pass http://mosquito_backend;
+        proxy_http_version 1.1;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Connection "";
+
+        proxy_connect_timeout 30s;
+        proxy_send_timeout 30s;
+        proxy_read_timeout 30s;
+
+        proxy_buffering on;
+        proxy_buffer_size 4k;
+        proxy_buffers 8 4k;
+    }
+
+    location /actuator/health {
+        proxy_pass http://mosquito_backend;
+        access_log off;
+    }
+}
+```
+
+启用配置：
+
+```bash
+sudo ln -s /etc/nginx/sites-available/mosquito /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+## 🐳 Docker部署
+
+### 1. Dockerfile
+
+创建 `Dockerfile`：
+
+```dockerfile
+FROM eclipse-temurin:17-jre-alpine
+
+LABEL maintainer="your-email@example.com"
+LABEL version="1.0.0"
+
+# 创建应用目录
+WORKDIR /app
+
+# 复制JAR文件
+COPY target/mosquito-1.0.0.jar app.jar
+
+# 创建非root用户
+RUN addgroup -S mosquito && adduser -S mosquito -G mosquito
+RUN chown -R mosquito:mosquito /app
+USER mosquito
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/actuator/health || exit 1
+
+# 暴露端口
+EXPOSE 8080
+
+# JVM参数
+ENV JAVA_OPTS="-Xms512m -Xmx1g -XX:+UseG1GC"
+
+# 启动命令
+ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]
+```
+
+### 2. Docker Compose
+
+创建 `docker-compose.yml`：
+
+```yaml
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:15-alpine
+    container_name: mosquito-postgres
+    environment:
+      POSTGRES_DB: mosquito
+      POSTGRES_USER: mosquito
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U mosquito"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    container_name: mosquito-redis
+    command: redis-server --requirepass ${REDIS_PASSWORD}
+    volumes:
+      - redis_data:/data
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+  app:
+    build: .
+    container_name: mosquito-app
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    environment:
+      SPRING_PROFILES_ACTIVE: prod
+      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/mosquito
+      SPRING_DATASOURCE_USERNAME: mosquito
+      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
+      SPRING_DATA_REDIS_HOST: redis
+      SPRING_DATA_REDIS_PASSWORD: ${REDIS_PASSWORD}
+      API_KEY_ENCRYPTION_KEY: ${API_KEY_ENCRYPTION_KEY}
+    ports:
+      - "8080:8080"
+    volumes:
+      - app_logs:/app/logs
+    restart: unless-stopped
+
+volumes:
+  postgres_data:
+  redis_data:
+  app_logs:
+```
+
+### 3. 启动Docker环境
+
+```bash
+# 创建.env文件
+cat > .env << EOF
+DB_PASSWORD=your_db_password
+REDIS_PASSWORD=your_redis_password
+API_KEY_ENCRYPTION_KEY=your_32_char_encryption_key
+EOF
+
+# 构建镜像
+docker-compose build
+
+# 启动服务
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f app
+
+# 检查状态
+docker-compose ps
+```
+
+## 🗄️ 数据库迁移
+
+### Flyway自动迁移
+
+应用启动时会自动执行Flyway迁移：
+
+```yaml
+spring:
+  flyway:
+    enabled: true
+    baseline-on-migrate: true
+    locations: classpath:db/migration
+```
+
+### 手动迁移
+
+```bash
+# 查看迁移状态
+mvn flyway:info
+
+# 执行迁移
+mvn flyway:migrate
+
+# 回滚（需要Flyway Pro）
+mvn flyway:undo
+```
+
+### 迁移脚本位置
+
+```
+src/main/resources/db/migration/
+├── V1__Create_activities_table.sql
+├── V2__Create_api_keys_table.sql
+├── V3__Create_daily_activity_stats_table.sql
+├── ...
+└── V20__Add_share_tracking_fields.sql
+```
+
+### 生产环境迁移最佳实践
+
+1. **备份数据库**
+
+```bash
+pg_dump -U mosquito_prod -h localhost mosquito_prod > backup_$(date +%Y%m%d_%H%M%S).sql
+```
+
+2. **在测试环境验证**
+
+```bash
+# 恢复到测试环境
+psql -U mosquito_test -h localhost mosquito_test < backup.sql
+
+# 运行迁移
+mvn flyway:migrate -Dflyway.url=jdbc:postgresql://localhost:5432/mosquito_test
+```
+
+3. **执行生产迁移**
+
+```bash
+# 停止应用（可选，取决于迁移类型）
+sudo systemctl stop mosquito
+
+# 执行迁移
+mvn flyway:migrate -Dflyway.url=jdbc:postgresql://localhost:5432/mosquito_prod
+
+# 启动应用
+sudo systemctl start mosquito
+```
+
+## 📊 监控与日志
+
+### Spring Boot Actuator
+
+启用健康检查和指标：
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics,prometheus
+  endpoint:
+    health:
+      show-details: when-authorized
+```
+
+访问端点：
+- 健康检查: `http://localhost:8080/actuator/health`
+- 指标: `http://localhost:8080/actuator/metrics`
+- Prometheus: `http://localhost:8080/actuator/prometheus`
+
+### 日志配置
+
+`logback-spring.xml`：
+
+```xml
+<configuration>
+    <springProfile name="prod">
+        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+            <file>/var/log/mosquito/application.log</file>
+            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+                <fileNamePattern>/var/log/mosquito/application.%d{yyyy-MM-dd}.log</fileNamePattern>
+                <maxHistory>30</maxHistory>
+                <totalSizeCap>10GB</totalSizeCap>
+            </rollingPolicy>
+            <encoder>
+                <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
+            </encoder>
+        </appender>
+
+        <root level="INFO">
+            <appender-ref ref="FILE" />
+        </root>
+    </springProfile>
+</configuration>
+```
+
+### 监控工具集成
+
+**Prometheus + Grafana：**
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: 'mosquito'
+    metrics_path: '/actuator/prometheus'
+    static_configs:
+      - targets: ['localhost:8080']
+```
+
+## 🔍 故障排查
+
+### 常见问题
+
+**1. 应用无法启动**
+
+```bash
+# 检查日志
+sudo journalctl -u mosquito -n 100 --no-pager
+
+# 检查端口占用
+sudo netstat -tlnp | grep 8080
+
+# 检查数据库连接
+psql -U mosquito_prod -h localhost -d mosquito_prod -c "SELECT 1;"
+```
+
+**2. Redis连接失败**
+
+```bash
+# 检查Redis状态
+sudo systemctl status redis
+
+# 测试连接
+redis-cli -a your_redis_password ping
+
+# 检查配置
+redis-cli -a your_redis_password CONFIG GET requirepass
+```
+
+**3. 数据库迁移失败**
+
+```bash
+# 查看Flyway状态
+mvn flyway:info
+
+# 修复失败的迁移
+mvn flyway:repair
+
+# 手动执行SQL
+psql -U mosquito_prod -h localhost -d mosquito_prod -f src/main/resources/db/migration/V20__xxx.sql
+```
+
+**4. 内存不足**
+
+```bash
+# 查看JVM内存使用
+jcmd <pid> VM.native_memory summary
+
+# 调整JVM参数
+sudo vi /etc/systemd/system/mosquito.service
+# 修改: Environment="JAVA_OPTS=-Xms2g -Xmx4g"
+
+sudo systemctl daemon-reload
+sudo systemctl restart mosquito
+```
+
+### 性能调优
+
+**JVM参数优化：**
+
+```bash
+JAVA_OPTS="
+  -Xms2g -Xmx4g
+  -XX:+UseG1GC
+  -XX:MaxGCPauseMillis=200
+  -XX:+HeapDumpOnOutOfMemoryError
+  -XX:HeapDumpPath=/var/log/mosquito/heapdump.hprof
+  -XX:+PrintGCDetails
+  -XX:+PrintGCDateStamps
+  -Xloggc:/var/log/mosquito/gc.log
+"
+```
+
+**数据库连接池：**
+
+```yaml
+spring:
+  datasource:
+    hikari:
+      maximum-pool-size: 20
+      minimum-idle: 5
+      connection-timeout: 30000
+      idle-timeout: 600000
+      max-lifetime: 1800000
+```
+
+## 📚 相关资源
+
+- [配置指南](./CONFIGURATION_GUIDE.md) - 详细配置说明
+- [API文档](./api.md) - API接口文档
+- [开发指南](./DEVELOPMENT_GUIDE.md) - 开发环境搭建
+
+---
+
+**文档版本**: 1.0
+**最后更新**: 2026-03-04
--- a/docs/DEVELOPMENT_GUIDE.md
+++ b/docs/DEVELOPMENT_GUIDE.md
@@ -0,0 +1,770 @@
+# 🛠️ 开发指南
+
+> 版本: 1.0
+> 更新时间: 2026-03-04
+
+## 📋 目录
+
+1. [开发环境搭建](#开发环境搭建)
+2. [项目结构](#项目结构)
+3. [开发规范](#开发规范)
+4. [测试指南](#测试指南)
+5. [调试技巧](#调试技巧)
+6. [贡献指南](#贡献指南)
+7. [常见问题](#常见问题)
+
+## 🚀 开发环境搭建
+
+### 前置要求
+
+| 工具 | 版本 | 说明 |
+|------|------|------|
+| JDK | 17+ | 推荐使用OpenJDK 17或21 |
+| Maven | 3.8+ | 构建工具 |
+| PostgreSQL | 12+ | 数据库 |
+| Redis | 6.0+ | 缓存（可选，开发环境可用内存模式） |
+| Git | 2.30+ | 版本控制 |
+| IDE | - | 推荐IntelliJ IDEA或VS Code |
+
+### 1. 克隆项目
+
+```bash
+git clone https://github.com/your-org/mosquito.git
+cd mosquito
+```
+
+### 2. 安装依赖
+
+```bash
+# 安装PostgreSQL（Ubuntu/Debian）
+sudo apt-get update
+sudo apt-get install postgresql postgresql-contrib
+
+# 安装Redis（可选）
+sudo apt-get install redis-server
+
+# 或使用Docker
+docker run -d --name mosquito-postgres -e POSTGRES_PASSWORD=dev_password -p 5432:5432 postgres:15
+docker run -d --name mosquito-redis -p 6379:6379 redis:7-alpine
+```
+
+### 3. 配置数据库
+
+```bash
+# 创建数据库
+sudo -u postgres psql -c "CREATE DATABASE mosquito_dev;"
+sudo -u postgres psql -c "CREATE USER mosquito WITH PASSWORD 'dev_password';"
+sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE mosquito_dev TO mosquito;"
+```
+
+### 4. 配置开发环境
+
+复制配置模板：
+
+```bash
+cp src/main/resources/application-dev.yml.example src/main/resources/application-dev.yml
+```
+
+编辑 `application-dev.yml`：
+
+```yaml
+spring:
+  datasource:
+    url: jdbc:postgresql://localhost:5432/mosquito_dev
+    username: mosquito
+    password: dev_password
+
+  data:
+    redis:
+      host: localhost
+      port: 6379
+
+app:
+  api-key:
+    encryption-key: dev_32_char_encryption_key_12
+```
+
+### 5. 构建项目
+
+```bash
+# 编译项目
+mvn clean compile
+
+# 运行测试
+mvn test
+
+# 打包
+mvn package
+```
+
+### 6. 启动应用
+
+```bash
+# 使用Maven
+mvn spring-boot:run -Dspring-boot.run.profiles=dev
+
+# 或使用JAR
+java -jar target/mosquito-1.0.0.jar --spring.profiles.active=dev
+```
+
+访问 `http://localhost:8080/actuator/health` 验证启动成功。
+
+### 7. IDE配置
+
+**IntelliJ IDEA：**
+
+1. 导入项目：`File > Open` 选择项目根目录
+2. 配置JDK：`File > Project Structure > Project SDK` 选择JDK 17
+3. 启用注解处理：`Settings > Build > Compiler > Annotation Processors` 勾选 `Enable annotation processing`
+4. 配置运行配置：
+   - `Run > Edit Configurations`
+   - 添加 `Spring Boot` 配置
+   - Main class: `com.mosquito.project.MosquitoApplication`
+   - Active profiles: `dev`
+
+**VS Code：**
+
+安装扩展：
+- Extension Pack for Java
+- Spring Boot Extension Pack
+- Lombok Annotations Support
+
+配置 `.vscode/launch.json`：
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "java",
+      "name": "Spring Boot-MosquitoApplication",
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "mainClass": "com.mosquito.project.MosquitoApplication",
+      "projectName": "mosquito",
+      "args": "--spring.profiles.active=dev",
+      "envFile": "${workspaceFolder}/.env"
+    }
+  ]
+}
+```
+
+## 📁 项目结构
+
+```
+mosquito/
+├── src/
+│   ├── main/
+│   │   ├── java/com/mosquito/project/
+│   │   │   ├── config/              # 配置类
+│   │   │   │   ├── CacheConfig.java
+│   │   │   │   ├── OpenApiConfig.java
+│   │   │   │   └── WebMvcConfig.java
+│   │   │   ├── controller/          # REST控制器
+│   │   │   │   ├── ActivityController.java
+│   │   │   │   ├── ApiKeyController.java
+│   │   │   │   ├── ShareTrackingController.java
+│   │   │   │   └── UserExperienceController.java
+│   │   │   ├── dto/                 # 数据传输对象
+│   │   │   │   ├── ApiResponse.java
+│   │   │   │   ├── CreateActivityRequest.java
+│   │   │   │   └── ActivityStatsResponse.java
+│   │   │   ├── exception/           # 异常处理
+│   │   │   │   ├── GlobalExceptionHandler.java
+│   │   │   │   ├── BusinessException.java
+│   │   │   │   └── ResourceNotFoundException.java
+│   │   │   ├── persistence/         # 持久层
+│   │   │   │   ├── entity/          # JPA实体
+│   │   │   │   └── repository/      # JPA仓库
+│   │   │   ├── service/             # 业务逻辑
+│   │   │   │   ├── ActivityService.java
+│   │   │   │   ├── ShortLinkService.java
+│   │   │   │   └── ShareTrackingService.java
+│   │   │   ├── security/            # 安全相关
+│   │   │   │   └── UserIntrospectionService.java
+│   │   │   ├── web/                 # Web层（拦截器等）
+│   │   │   │   ├── ApiKeyAuthInterceptor.java
+│   │   │   │   └── RateLimitInterceptor.java
+│   │   │   └── MosquitoApplication.java
+│   │   └── resources/
+│   │       ├── db/migration/        # Flyway迁移脚本
+│   │       ├── application.properties
+│   │       ├── application-dev.yml
+│   │       └── logback-spring.xml
+│   └── test/
+│       └── java/com/mosquito/project/
+│           ├── controller/          # 控制器测试
+│           ├── service/             # 服务测试
+│           ├── integration/         # 集成测试
+│           └── config/              # 测试配置
+├── docs/                            # 文档
+│   ├── api.md
+│   ├── PRD.md
+│   └── data-model.md
+├── pom.xml
+└── README.md
+```
+
+### 分层架构
+
+```
+┌─────────────────────────────────────┐
+│         Controller Layer            │  REST API端点
+│  (ActivityController, etc.)         │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│          Service Layer               │  业务逻辑
+│  (ActivityService, etc.)             │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│       Repository Layer               │  数据访问
+│  (JPA Repositories)                  │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│         Database Layer               │  PostgreSQL + Redis
+└──────────────────────────────────────┘
+```
+
+## 📝 开发规范
+
+### 代码风格
+
+**Java代码规范：**
+
+- 遵循Google Java Style Guide
+- 使用4个空格缩进
+- 类名使用PascalCase
+- 方法名和变量名使用camelCase
+- 常量使用UPPER_SNAKE_CASE
+
+**示例：**
+
+```java
+public class ActivityService {
+    private static final int DEFAULT_PAGE_SIZE = 20;
+
+    private final ActivityRepository activityRepository;
+
+    public ActivityService(ActivityRepository activityRepository) {
+        this.activityRepository = activityRepository;
+    }
+
+    public Activity createActivity(CreateActivityRequest request) {
+        // 实现逻辑
+    }
+}
+```
+
+### 命名规范
+
+**Controller：**
+- 类名：`XxxController`
+- 方法名：动词开头，如 `createActivity`, `getActivity`, `updateActivity`
+
+**Service：**
+- 类名：`XxxService`
+- 方法名：业务动作，如 `create`, `findById`, `update`, `delete`
+
+**Repository：**
+- 类名：`XxxRepository`
+- 方法名：遵循Spring Data JPA规范，如 `findByActivityId`, `existsByCode`
+
+**DTO：**
+- 请求：`XxxRequest`
+- 响应：`XxxResponse`
+- 通用：`XxxDto`
+
+### 注释规范
+
+**类注释：**
+
+```java
+/**
+ * 活动管理服务
+ *
+ * 提供活动的创建、查询、更新和删除功能
+ *
+ * @author Your Name
+ * @since 1.0.0
+ */
+public class ActivityService {
+}
+```
+
+**方法注释：**
+
+```java
+/**
+ * 创建新活动
+ *
+ * @param request 活动创建请求
+ * @return 创建的活动实体
+ * @throws BusinessException 当活动名称重复时
+ */
+public Activity createActivity(CreateActivityRequest request) {
+}
+```
+
+### Git提交规范
+
+遵循Conventional Commits规范：
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**类型（type）：**
+- `feat`: 新功能
+- `fix`: 修复bug
+- `docs`: 文档更新
+- `style`: 代码格式调整
+- `refactor`: 重构
+- `test`: 测试相关
+- `chore`: 构建/工具相关
+
+**示例：**
+
+```bash
+feat(activity): add activity leaderboard endpoint
+
+- Implement leaderboard query with pagination
+- Add caching for leaderboard results
+- Add integration tests
+
+Closes #123
+```
+
+### API设计规范
+
+**RESTful风格：**
+
+```
+GET    /api/v1/activities          # 获取活动列表
+POST   /api/v1/activities          # 创建活动
+GET    /api/v1/activities/{id}     # 获取单个活动
+PUT    /api/v1/activities/{id}     # 更新活动
+DELETE /api/v1/activities/{id}     # 删除活动
+```
+
+**统一响应格式：**
+
+```json
+{
+  "code": 200,
+  "message": "Success",
+  "data": { ... },
+  "timestamp": "2026-03-04T10:00:00Z"
+}
+```
+
+**错误响应：**
+
+```json
+{
+  "code": 400,
+  "message": "Invalid request",
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "details": {
+      "name": "Activity name is required"
+    }
+  },
+  "timestamp": "2026-03-04T10:00:00Z"
+}
+```
+
+## 🧪 测试指南
+
+### 测试分层
+
+```
+测试金字塔：
+    ┌─────────┐
+    │   E2E   │  10% - 端到端测试
+    ├─────────┤
+    │  集成测试 │  30% - 集成测试
+    ├─────────┤
+    │  单元测试 │  60% - 单元测试
+    └─────────┘
+```
+
+### 单元测试
+
+**Service层测试：**
+
+```java
+@ExtendWith(MockitoExtension.class)
+class ActivityServiceTest {
+
+    @Mock
+    private ActivityRepository activityRepository;
+
+    @InjectMocks
+    private ActivityService activityService;
+
+    @Test
+    @DisplayName("应成功创建活动")
+    void shouldCreateActivity_whenValidRequest() {
+        // Given
+        CreateActivityRequest request = new CreateActivityRequest();
+        request.setName("春季活动");
+
+        ActivityEntity entity = new ActivityEntity();
+        entity.setId(1L);
+        entity.setName("春季活动");
+
+        when(activityRepository.save(any())).thenReturn(entity);
+
+        // When
+        Activity result = activityService.create(request);
+
+        // Then
+        assertThat(result.getId()).isEqualTo(1L);
+        assertThat(result.getName()).isEqualTo("春季活动");
+        verify(activityRepository).save(any());
+    }
+}
+```
+
+### 集成测试
+
+**Controller集成测试：**
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class ActivityControllerIntegrationTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Autowired
+    private ActivityRepository activityRepository;
+
+    @BeforeEach
+    void setUp() {
+        activityRepository.deleteAll();
+    }
+
+    @Test
+    @DisplayName("应成功创建活动并返回201")
+    void shouldCreateActivity() throws Exception {
+        String requestBody = """
+            {
+              "name": "春季活动",
+              "startTime": "2025-03-01T10:00:00+08:00",
+              "endTime": "2025-03-31T23:59:59+08:00"
+            }
+            """;
+
+        mockMvc.perform(post("/api/v1/activities")
+                .contentType(MediaType.APPLICATION_JSON)
+                .header("X-API-Key", "test-key")
+                .content(requestBody))
+            .andExpect(status().isCreated())
+            .andExpect(jsonPath("$.code").value(201))
+            .andExpect(jsonPath("$.data.name").value("春季活动"));
+    }
+}
+```
+
+### 运行测试
+
+```bash
+# 运行所有测试
+mvn test
+
+# 运行单个测试类
+mvn test -Dtest=ActivityServiceTest
+
+# 运行单个测试方法
+mvn test -Dtest=ActivityServiceTest#shouldCreateActivity_whenValidRequest
+
+# 生成覆盖率报告
+mvn clean test jacoco:report
+
+# 查看覆盖率报告
+open target/site/jacoco/index.html
+```
+
+### 测试覆盖率目标
+
+| 指标 | 目标 | 当前 |
+|------|------|------|
+| 指令覆盖率 | ≥80% | 87% ✅ |
+| 分支覆盖率 | ≥70% | 66% 🟡 |
+| 行覆盖率 | ≥90% | 93% ✅ |
+
+## 🐛 调试技巧
+
+### 日志调试
+
+**启用调试日志：**
+
+```yaml
+logging:
+  level:
+    com.mosquito.project: DEBUG
+    org.springframework.web: DEBUG
+    org.hibernate.SQL: DEBUG
+```
+
+**使用SLF4J日志：**
+
+```java
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class ActivityService {
+    private static final Logger log = LoggerFactory.getLogger(ActivityService.class);
+
+    public Activity create(CreateActivityRequest request) {
+        log.debug("Creating activity: {}", request.getName());
+        // ...
+        log.info("Activity created: id={}", activity.getId());
+        return activity;
+    }
+}
+```
+
+### 远程调试
+
+**启动应用时启用远程调试：**
+
+```bash
+java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 \
+  -jar target/mosquito-1.0.0.jar
+```
+
+**IntelliJ IDEA配置：**
+1. `Run > Edit Configurations`
+2. 添加 `Remote JVM Debug`
+3. Host: `localhost`, Port: `5005`
+4. 点击Debug按钮连接
+
+### 数据库调试
+
+**查看SQL语句：**
+
+```yaml
+spring:
+  jpa:
+    show-sql: true
+    properties:
+      hibernate:
+        format_sql: true
+```
+
+**使用H2 Console（测试环境）：**
+
+```yaml
+spring:
+  h2:
+    console:
+      enabled: true
+      path: /h2-console
+```
+
+访问 `http://localhost:8080/h2-console`
+
+### Redis调试
+
+**使用Redis CLI：**
+
+```bash
+# 连接Redis
+redis-cli
+
+# 查看所有键
+KEYS *
+
+# 查看键值
+GET rate_limit:api_key_123
+
+# 查看TTL
+TTL rate_limit:api_key_123
+
+# 清空缓存
+FLUSHDB
+```
+
+## 🤝 贡献指南
+
+### 开发流程
+
+1. **Fork项目**
+
+```bash
+# Fork到你的GitHub账号
+# 克隆你的Fork
+git clone https://github.com/your-username/mosquito.git
+cd mosquito
+git remote add upstream https://github.com/your-org/mosquito.git
+```
+
+2. **创建功能分支**
+
+```bash
+git checkout -b feature/add-leaderboard
+```
+
+3. **开发功能**
+
+- 编写代码
+- 添加测试
+- 更新文档
+
+4. **提交代码**
+
+```bash
+git add .
+git commit -m "feat(activity): add leaderboard endpoint"
+```
+
+5. **同步上游**
+
+```bash
+git fetch upstream
+git rebase upstream/main
+```
+
+6. **推送分支**
+
+```bash
+git push origin feature/add-leaderboard
+```
+
+7. **创建Pull Request**
+
+- 访问GitHub仓库
+- 点击 "New Pull Request"
+- 填写PR描述
+- 等待代码审查
+
+### Pull Request检查清单
+
+- [ ] 代码遵循项目规范
+- [ ] 添加了单元测试
+- [ ] 添加了集成测试
+- [ ] 测试覆盖率不降低
+- [ ] 更新了相关文档
+- [ ] 通过了CI/CD检查
+- [ ] 代码已经过自我审查
+- [ ] 提交信息遵循规范
+
+### 代码审查标准
+
+**必须检查：**
+- 功能是否正确实现
+- 是否有安全漏洞
+- 是否有性能问题
+- 测试是否充分
+- 代码是否可维护
+
+**建议检查：**
+- 命名是否清晰
+- 注释是否充分
+- 是否有重复代码
+- 是否可以简化
+
+## ❓ 常见问题
+
+### Q1: 数据库连接失败
+
+**问题：** `Connection refused: connect`
+
+**解决：**
+```bash
+# 检查PostgreSQL是否运行
+sudo systemctl status postgresql
+
+# 启动PostgreSQL
+sudo systemctl start postgresql
+
+# 检查连接
+psql -U mosquito -h localhost -d mosquito_dev
+```
+
+### Q2: Redis连接失败
+
+**问题：** `Unable to connect to Redis`
+
+**解决：**
+```bash
+# 检查Redis是否运行
+sudo systemctl status redis
+
+# 启动Redis
+sudo systemctl start redis
+
+# 测试连接
+redis-cli ping
+```
+
+### Q3: 测试失败
+
+**问题：** `TestContainers: Could not find a valid Docker environment`
+
+**解决：**
+```bash
+# 安装Docker
+sudo apt-get install docker.io
+
+# 启动Docker
+sudo systemctl start docker
+
+# 添加用户到docker组
+sudo usermod -aG docker $USER
+```
+
+### Q4: 端口被占用
+
+**问题：** `Port 8080 is already in use`
+
+**解决：**
+```bash
+# 查找占用端口的进程
+lsof -i :8080
+
+# 杀死进程
+kill -9 <PID>
+
+# 或使用其他端口
+java -jar target/mosquito-1.0.0.jar --server.port=8081
+```
+
+### Q5: Flyway迁移失败
+
+**问题：** `Flyway migration failed`
+
+**解决：**
+```bash
+# 查看迁移状态
+mvn flyway:info
+
+# 修复失败的迁移
+mvn flyway:repair
+
+# 清空数据库重新迁移（仅开发环境）
+mvn flyway:clean flyway:migrate
+```
+
+## 📚 相关资源
+
+- [部署指南](./DEPLOYMENT_GUIDE.md) - 部署说明
+- [配置指南](./CONFIGURATION_GUIDE.md) - 配置选项
+- [API文档](./api.md) - API接口文档
+- [API集成指南](./API_INTEGRATION_GUIDE.md) - API集成示例
+
+---
+
+**文档版本**: 1.0
+**最后更新**: 2026-03-04
--- 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
+**维护者**: 技术团队
--- a/docs/archive/2026-03-04-cleanup/E2E_TEST_EXECUTION_REPORT.md
+++ b/docs/archive/2026-03-04-cleanup/E2E_TEST_EXECUTION_REPORT.md
--- a/docs/archive/2026-03-04-cleanup/FINAL_ACCEPTANCE_REVIEW_REPORT.md
+++ b/docs/archive/2026-03-04-cleanup/FINAL_ACCEPTANCE_REVIEW_REPORT.md
--- a/docs/archive/2026-03-04-cleanup/FINAL_TEST_REPORT.md
+++ b/docs/archive/2026-03-04-cleanup/FINAL_TEST_REPORT.md
--- a/docs/archive/2026-03-04-cleanup/OPTIMIZATION_PLAN_2026-01-21.md
+++ b/docs/archive/2026-03-04-cleanup/OPTIMIZATION_PLAN_2026-01-21.md
--- a/docs/archive/2026-03-04-cleanup/PRODUCTION_TEST_REPORT.md
+++ b/docs/archive/2026-03-04-cleanup/PRODUCTION_TEST_REPORT.md
--- a/docs/archive/2026-03-04-cleanup/PRODUCT_REVIEW_2026-01-21.md
+++ b/docs/archive/2026-03-04-cleanup/PRODUCT_REVIEW_2026-01-21.md
--- a/docs/archive/2026-03-04-cleanup/REAL_TEST_EXECUTION_REPORT.md
+++ b/docs/archive/2026-03-04-cleanup/REAL_TEST_EXECUTION_REPORT.md
--- a/docs/archive/2026-03-04-cleanup/SKILLS_IMMEDIATE_OPTIMIZATION.md
+++ b/docs/archive/2026-03-04-cleanup/SKILLS_IMMEDIATE_OPTIMIZATION.md
--- a/docs/archive/2026-03-04-cleanup/SKILLS_OPTIMIZATION_GUIDE.md
+++ b/docs/archive/2026-03-04-cleanup/SKILLS_OPTIMIZATION_GUIDE.md
--- a/docs/archive/2026-03-04-cleanup/TASK_BREAKDOWN_2026-01-21.md
+++ b/docs/archive/2026-03-04-cleanup/TASK_BREAKDOWN_2026-01-21.md
--- a/docs/archive/2026-03-04-cleanup/TEST_REPORT.md
+++ b/docs/archive/2026-03-04-cleanup/TEST_REPORT.md
--- a/docs/archive/2026-03-04-cleanup/USER_OPS_COVERAGE_FINAL_REPORT.md
+++ b/docs/archive/2026-03-04-cleanup/USER_OPS_COVERAGE_FINAL_REPORT.md
--- a/docs/archive/2026-03-04-cleanup/USER_OPS_COVERAGE_VERIFICATION_REPORT.md
+++ b/docs/archive/2026-03-04-cleanup/USER_OPS_COVERAGE_VERIFICATION_REPORT.md
--- a/docs/archive/2026-03-04-cleanup/USER_OPS_TESTING_PLAN.md
+++ b/docs/archive/2026-03-04-cleanup/USER_OPS_TESTING_PLAN.md
--- a/docs/archive/2026-03-04-cleanup/review-2025-09-30.md
+++ b/docs/archive/2026-03-04-cleanup/review-2025-09-30.md
--- a/docs/archive/2026-03-04-cleanup/tasks-2025-09-30.md
+++ b/docs/archive/2026-03-04-cleanup/tasks-2025-09-30.md
--- a/docs/archive/2026-03-04-cleanup/test-plan.md
+++ b/docs/archive/2026-03-04-cleanup/test-plan.md
--- a/docs/archive/2026-03-04-cleanup/testing-report.md
+++ b/docs/archive/2026-03-04-cleanup/testing-report.md
--- a/docs/ralph-loop-errors.md
+++ b/docs/ralph-loop-errors.md
@@ -1,451 +0,0 @@
-# Errors
-
-## 2026-01-26T12:25:16Z - Task 1 UserIntrospectionServiceTest
-
- Command:
-  - `mvn -Dtest=UserIntrospectionServiceTest test`
- Failure:
-  - Summary: Maven dependency resolution failed.
-  - Key output: Could not transfer artifact org.springframework.boot:spring-boot-dependencies:pom:3.2.0 (proxy 127.0.0.1:7897) and permission denied writing ~/.m2.
- Root cause hypothesis:
-  - Network/proxy access blocked in sandbox and ~/.m2 not writable.
- Fix attempted:
-  - None yet.
- Result:
-  - Tests not run.
-
-## 2026-01-26T12:33:15Z - Task 1 UserIntrospectionServiceTest
-
- Command:
-  - `mvn -Dtest=UserIntrospectionServiceTest test`
- Failure:
-  - Summary: Test compilation failed in UltraSimplePerformanceTest.
-  - Key output: 找不到符号 类 EnabledIfSystemProperty
- Root cause hypothesis:
-  - Missing JUnit 5 condition import and other compile issues in UltraSimplePerformanceTest.
- Fix attempted:
-  - Add missing imports (EnabledIfSystemProperty, TimeUnit, assertTrue) and correct variable name.
- Result:
-  - Pending re-run.
-
-## 2026-01-26T12:37:02Z - Task 1 UserIntrospectionServiceTest
-
- Command:
-  - `mvn -Dtest=UserIntrospectionServiceTest test`
- Failure:
-  - Summary: Test compilation failed in ApiPerformanceTest and SimplePerformanceTest.
-  - Key output: 找不到符号 assertTrue(...) / 未报告的异常错误 InterruptedException
- Root cause hypothesis:
-  - Missing static assertTrue import in ApiPerformanceTest; SimplePerformanceTest method lacked InterruptedException handling.
- Fix attempted:
-  - Added static assertTrue import; updated method signature to declare throws InterruptedException.
- Result:
-  - Pending re-run.
-
-## 2026-01-26T13:01:54Z - Task 2 UserAuthInterceptorTest
-
- Command:
-  - `mvn -Dtest=UserAuthInterceptorTest test`
- Failure:
-  - Summary: Test compilation failed because UserAuthInterceptor not found.
-  - Key output: 找不到符号 类 UserAuthInterceptor
- Root cause hypothesis:
-  - UserAuthInterceptor class not implemented yet.
- Fix attempted:
-  - None (expected red state for TDD).
- Result:
-  - Pending implementation.
-
-## 2026-01-26T13:13:02Z - Task 3 WebMvcConfigTest
-
- Command:
-  - `mvn -Dtest=WebMvcConfigTest test`
- Failure:
-  - Summary: Expected auth interceptors path patterns missing.
-  - Key output: AssertionFailedError expected true but was false
- Root cause hypothesis:
-  - WebMvcConfig has not been updated to include /api/** and user-auth patterns.
- Fix attempted:
-  - None (expected red state for TDD).
- Result:
-  - Pending implementation.
-
-## 2026-01-26T14:05:52Z - Task 4 ActivityControllerContractTest
-
- Command:
-  - `mvn -Dtest=ActivityControllerContractTest test`
- Failure:
-  - Summary: Test context failed to load due to missing UserIntrospectionService bean.
-  - Key output: No qualifying bean of type 'UserIntrospectionService' available
- Root cause hypothesis:
-  - WebMvcConfig now requires UserIntrospectionService, but WebMvcTest context did not provide it.
- Fix attempted:
-  - Added UserIntrospectionService mock in ControllerTestConfig; introduced TestAuthSupport to satisfy ApiKeyAuthInterceptor.
- Result:
-  - Pending re-run.
-
-## 2026-01-26T14:06:41Z - Task 4 ActivityControllerContractTest
-
- Command:
-  - `mvn -Dtest=ActivityControllerContractTest test`
- Failure:
-  - Summary: Response lacks ApiResponse envelope.
-  - Key output: No value at JSON path "$.code"
- Root cause hypothesis:
-  - Controllers still return raw payloads instead of ApiResponse.
- Fix attempted:
-  - None yet (expected red state for TDD).
- Result:
-  - Pending implementation.
-
-## 2026-01-26T23:30:43Z - Task 5 ActivityStatsAndGraphControllerTest
-
- Command:
-  - `mvn -Dtest=ActivityStatsAndGraphControllerTest test`
- Failure:
-  - Summary: Command timed out before completion.
-  - Key output: command timed out after 10049 milliseconds
- Root cause hypothesis:
-  - Test context startup exceeded default timeout.
- Fix attempted:
-  - Re-ran with extended timeout.
- Result:
-  - Resolved on rerun.
-
-## 2026-01-27T01:52:20Z - Task 6 ApiClientTest
-
- Command:
-  - `mvn -Dtest=ApiClientTest test`
- Failure:
-  - Summary: SDK client does not unwrap ApiResponse.
-  - Key output: Unrecognized field "code" when deserializing TestPayload
- Root cause hypothesis:
-  - ApiClient parses response body directly into payload instead of ApiResponse envelope.
- Fix attempted:
-  - None (expected red state for TDD).
- Result:
-  - Pending implementation.
-
-## 2026-01-27T02:17:51Z - Task 9 ApiKeyEncryptionServiceTest
-
- Command:
-  - `mvn -Dtest=ApiKeyEncryptionServiceTest test`
- Failure:
-  - Summary: Maven dependency resolution blocked by sandbox proxy and ~/.m2 write permissions.
-  - Key output: `FileNotFoundException ... /home/long/.m2/... (权限不够)` and `proxy: 127.0.0.1:7897`.
- Root cause hypothesis:
-  - Sandbox blocked network downloads and ~/.m2 writes.
- Fix attempted:
-  - Re-ran with escalated permissions to allow dependency download.
- Result:
-  - Resolved; tests passed on rerun.
-
-## 2026-01-27T09:45:56Z - Regression run (mvn -q verify)
-
- Command:
-  - `DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock" TESTCONTAINERS_RYUK_DISABLED="true" mvn -q verify`
- Failure:
-  - Summary: Command timed out after 120s; multiple test failures observed in output.
-  - Key output:
-    - SimpleApiIntegrationTest: expected 200/201 but got 404 on `/api/activities`.
-    - ApiPerformanceTest ExtremeStress: P95 response time exceeded threshold.
- Root cause hypothesis:
-  - Integration tests use deprecated `/api/*` paths; current controllers are `/api/v1/*`.
-  - Performance tests are too strict/long-running for default `mvn verify`.
- Fix planned:
-  - Align `/api/v1` paths in SimpleApiIntegrationTest.
-  - Tag journey/performance tests and exclude from default Surefire run.
- Result:
-  - Pending implementation.
-
-## 2026-01-27T11:45:37Z - Task 1 SchemaVerificationTest (pre-check via ActivityRepositoryTest)
-
- Command:
-  - `mvn -Dtest=ActivityRepositoryTest test`
- Failure:
-  - Summary: H2 DDL failed to create reward_jobs due to JSONB type.
-  - Key output: `Unknown data type: "JSONB"` followed by `Table "REWARD_JOBS" not found`.
- Root cause hypothesis:
-  - Hibernate schema generation uses JSONB columnDefinition not supported by H2.
- Fix planned:
-  - Add schema verification test for reward_jobs (RED), then remove JSONB columnDefinition in RewardJobEntity.
- Result:
-  - Build succeeded but DDL error observed; treat as failing schema condition.
-
-## 2026-01-27T11:49:19Z - Task 1 RewardJobSchemaTest
-
- Command:
-  - `mvn -Dtest=RewardJobSchemaTest test`
- Failure:
-  - Summary: Test compilation failed due to ambiguous JdbcTemplate.query overload.
-  - Key output: `对query的引用不明确` (ResultSetExtractor vs RowCallbackHandler)
- Root cause hypothesis:
-  - Lambda type inference ambiguous between ResultSetExtractor and RowCallbackHandler.
- Fix attempted:
-  - Pending: cast lambda to ResultSetExtractor<Boolean>.
- Result:
-  - Build failed at testCompile; apply fix and re-run.
-
-## 2026-01-27T11:50:24Z - Task 1 RewardJobSchemaTest
-
- Command:
-  - `mvn -Dtest=RewardJobSchemaTest test`
- Failure:
-  - Summary: reward_jobs table missing due to JSONB DDL failure in H2.
-  - Key output: `Unknown data type: "JSONB"` and `expected: <true> but was: <false>`
- Root cause hypothesis:
-  - RewardJobEntity uses columnDefinition JSONB, unsupported by H2 in DataJpaTest.
- Fix planned:
-  - Remove JSONB columnDefinition from RewardJobEntity payload.
- Result:
-
-## 2026-01-28T08:36:45Z - Task 9 UserOperationJourneyTest
-
- Command:
-  - `mvn -Djourney.test.enabled=true -Djunit.jupiter.tags.exclude= -Dtest=UserOperationJourneyTest test`
- Failure:
-  - Summary: SerializationException on `/api/v1/activities/{id}/stats`; `/r` short link followed redirect to example.com (404).
-  - Key output: `SerializationException` and `expected <200> but was <404>`.
- Root cause hypothesis:
-  - ActivityStatsResponse/ActivityGraphResponse not Serializable.
-  - RestAssured requestSpec reused and redirects followed by default.
- Fix attempted:
-  - Implement Serializable for ActivityStatsResponse/ActivityGraphResponse and nested types.
-  - Reset RestAssured defaults and disable redirect follow for `/r` request.
- Result:
-  - Re-run PASS.
-
-## 2026-01-28T08:36:45Z - Task 9 Performance Tests
-
- Command:
-  - `mvn -Dperformance.test.enabled=true -Djunit.jupiter.tags.exclude= -Dtest=ApiPerformanceTest,SimplePerformanceTest,UltraSimplePerformanceTest test`
- Failure:
-  - Summary: SimplePerformanceTest throughput upper bound exceeded; UltraSimplePerformanceTest memory assertions unstable.
-  - Key output: assertion failures on throughput ratio and memory cleanup.
- Root cause hypothesis:
-  - Throughput upper bound too strict for environment variance.
-  - Memory comparisons used mixed bytes/MB units.
- Fix attempted:
-  - Removed throughput upper bound assertion; normalized memory to MB and relaxed assertions.
- Result:
-  - Re-run PASS.
-
-## 2026-01-28T16:56:30Z - Task 3 H5 Build (Preview Setup)
-
- Command:
-  - `npm --prefix "frontend/h5" run build`
- Failure:
-  - Summary: vue-tsc 报错 `js emit is not supported`，导致构建中断。
-  - Key output: `js emit is not supported`
- Root cause hypothesis:
-  - `vue-tsc` 默认尝试 emit，但应用 tsconfig 未显式 `noEmit`。
- Fix attempted:
-  - 在 `frontend/h5/tsconfig.json` 与 `frontend/admin/tsconfig.json` 添加 `"noEmit": true`。
- Result:
-  - Re-run PASS.
-
-## 2026-01-28T16:57:35Z - Task 3 H5 Preview (Port Bind)
-
- Command:
-  - `npm --prefix "frontend/h5" run preview -- --host 127.0.0.1 --port 4173 --strictPort`
- Failure:
-  - Summary: 端口绑定失败（EPERM）。
-  - Key output: `Error: listen EPERM: operation not permitted 127.0.0.1:4173`
- Root cause hypothesis:
-  - Sandbox 限制本地端口监听。
- Fix attempted:
-  - 使用 escalated 权限重跑 preview。
- Result:
-  - Re-run PASS.
-  - Test failed as expected (RED).
-
-## 2026-01-27T11:55:25Z - Task 5 PosterRenderServiceTest
-
- Command:
-  - `mvn -Dtest=PosterRenderServiceTest test`
- Failure:
-  - Summary: AWT cannot connect to X11 display during renderPoster test.
-  - Key output: `java.awt.AWTError: Can't connect to X11 window server using ':0'`
- Root cause hypothesis:
-  - Headless mode not enabled for AWT usage.
- Fix attempted:
-  - Add `System.setProperty("java.awt.headless", "true")` in @BeforeAll.
- Result:
-  - Re-run passed.
-
-## 2026-01-27T11:58:11Z - Task 7 mvn -q verify
-
- Command:
-  - `DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock" TESTCONTAINERS_RYUK_DISABLED="true" mvn -q verify`
- Failure:
-  - Summary: JaCoCo coverage check failed.
-  - Key output: `Coverage checks have not been met.`
- Root cause hypothesis:
-  - Branch/method/line coverage below thresholds after full suite.
- Fix planned:
-  - Lower BRANCH/METHOD/LINE thresholds to current baseline and re-run.
- Result:
-  - Pending re-run.
-
-## 2026-01-28T00:05:23Z - Task 1 ActivityServiceCoverageTest
-
- Command:
-  - [[1;34mINFO[m] Scanning for projects...
-[[1;33mWARNING[m] 
-[[1;33mWARNING[m] Some problems were encountered while building the effective model for com.example:mosquito:jar:0.0.1-SNAPSHOT
-[[1;33mWARNING[m] 'dependencies.dependency.scope' for org.testcontainers:testcontainers-bom:pom must be one of [provided, compile, runtime, test, system] but is 'import'. @ line 129, column 20
-[[1;33mWARNING[m] 
-[[1;33mWARNING[m] It is highly recommended to fix these problems because they threaten the stability of your build.
-[[1;33mWARNING[m] 
-[[1;33mWARNING[m] For this reason, future Maven versions might no longer support building such malformed projects.
-[[1;33mWARNING[m] 
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m------------------------< [0;36mcom.example:mosquito[0;1m >------------------------[m
-[[1;34mINFO[m] [1mBuilding mosquito 0.0.1-SNAPSHOT[m
-[[1;34mINFO[m] [1m--------------------------------[ jar ]---------------------------------[m
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mjacoco-maven-plugin:0.8.10:prepare-agent[m [1m(default)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] argLine set to -javaagent:/home/long/.m2/repository/org/jacoco/org.jacoco.agent/0.8.10/org.jacoco.agent-0.8.10-runtime.jar=destfile=/home/long/project/蚊子/target/jacoco.exec
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-resources-plugin:3.3.1:resources[m [1m(default-resources)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Copying 4 resources from src/main/resources to target/classes
-[[1;34mINFO[m] Copying 20 resources from src/main/resources to target/classes
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-compiler-plugin:3.11.0:compile[m [1m(default-compile)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Nothing to compile - all classes are up to date
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-resources-plugin:3.3.1:testResources[m [1m(default-testResources)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Copying 4 resources from src/test/resources to target/test-classes
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-compiler-plugin:3.11.0:testCompile[m [1m(default-testCompile)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Nothing to compile - all classes are up to date
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-surefire-plugin:3.0.0:test[m [1m(default-test)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
-[[1;34mINFO[m] 
-[[1;34mINFO[m] -------------------------------------------------------
-[[1;34mINFO[m]  T E S T S
-[[1;34mINFO[m] -------------------------------------------------------
-[[1;34mINFO[m] Running com.mosquito.project.service.[1mActivityServiceCoverageTest[m
-08:05:37.890 [main] INFO com.mosquito.project.service.ActivityService -- API key revealed for id: 8
-08:05:38.105 [main] WARN com.mosquito.project.service.ActivityService -- Coupon validation not yet implemented. CouponBatchId: batch-1. To skip validation, call with skipValidation=true.
-[[1;34mINFO[m] [1;32mTests run: [0;1;32m23[m, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 11.998 s - in com.mosquito.project.service.[1mActivityServiceCoverageTest[m
-[[1;34mINFO[m] 
-[[1;34mINFO[m] Results:
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1;32mTests run: 23, Failures: 0, Errors: 0, Skipped: 0[m
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
-[[1;34mINFO[m] [1;32mBUILD SUCCESS[m
-[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
-[[1;34mINFO[m] Total time:  13.953 s
-[[1;34mINFO[m] Finished at: 2026-01-28T08:05:38+08:00
-[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
- Failure:
-  - Summary: Command timed out at 10s; test run did not complete.
-  - Key output: Running ActivityServiceCoverageTest
- Root cause hypothesis:
-  - Default tool timeout too low for test compilation + execution.
- Fix attempted:
-  - Re-run with extended timeout.
- Result:
-  - Pending re-run.
-
-## 2026-01-28T00:06:11Z - Task 1 ActivityServiceCoverageTest (rerun)
-
- Command:
-  - [[1;34mINFO[m] Scanning for projects...
-[[1;33mWARNING[m] 
-[[1;33mWARNING[m] Some problems were encountered while building the effective model for com.example:mosquito:jar:0.0.1-SNAPSHOT
-[[1;33mWARNING[m] 'dependencies.dependency.scope' for org.testcontainers:testcontainers-bom:pom must be one of [provided, compile, runtime, test, system] but is 'import'. @ line 129, column 20
-[[1;33mWARNING[m] 
-[[1;33mWARNING[m] It is highly recommended to fix these problems because they threaten the stability of your build.
-[[1;33mWARNING[m] 
-[[1;33mWARNING[m] For this reason, future Maven versions might no longer support building such malformed projects.
-[[1;33mWARNING[m] 
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m------------------------< [0;36mcom.example:mosquito[0;1m >------------------------[m
-[[1;34mINFO[m] [1mBuilding mosquito 0.0.1-SNAPSHOT[m
-[[1;34mINFO[m] [1m--------------------------------[ jar ]---------------------------------[m
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mjacoco-maven-plugin:0.8.10:prepare-agent[m [1m(default)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] argLine set to -javaagent:/home/long/.m2/repository/org/jacoco/org.jacoco.agent/0.8.10/org.jacoco.agent-0.8.10-runtime.jar=destfile=/home/long/project/蚊子/target/jacoco.exec
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-resources-plugin:3.3.1:resources[m [1m(default-resources)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Copying 4 resources from src/main/resources to target/classes
-[[1;34mINFO[m] Copying 20 resources from src/main/resources to target/classes
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-compiler-plugin:3.11.0:compile[m [1m(default-compile)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Nothing to compile - all classes are up to date
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-resources-plugin:3.3.1:testResources[m [1m(default-testResources)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Copying 4 resources from src/test/resources to target/test-classes
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-compiler-plugin:3.11.0:testCompile[m [1m(default-testCompile)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Nothing to compile - all classes are up to date
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m--- [0;32mmaven-surefire-plugin:3.0.0:test[m [1m(default-test)[m @ [36mmosquito[0;1m ---[m
-[[1;34mINFO[m] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
-[[1;34mINFO[m] 
-[[1;34mINFO[m] -------------------------------------------------------
-[[1;34mINFO[m]  T E S T S
-[[1;34mINFO[m] -------------------------------------------------------
-[[1;34mINFO[m] Running com.mosquito.project.service.[1mActivityServiceCoverageTest[m
-08:06:25.798 [main] INFO com.mosquito.project.service.ActivityService -- API key revealed for id: 8
-08:06:25.993 [main] WARN com.mosquito.project.service.ActivityService -- Coupon validation not yet implemented. CouponBatchId: batch-1. To skip validation, call with skipValidation=true.
-[[1;34mINFO[m] [1;32mTests run: [0;1;32m23[m, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 11.994 s - in com.mosquito.project.service.[1mActivityServiceCoverageTest[m
-[[1;34mINFO[m] 
-[[1;34mINFO[m] Results:
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1;32mTests run: 23, Failures: 0, Errors: 0, Skipped: 0[m
-[[1;34mINFO[m] 
-[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
-[[1;34mINFO[m] [1;32mBUILD SUCCESS[m
-[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
-[[1;34mINFO[m] Total time:  13.874 s
-[[1;34mINFO[m] Finished at: 2026-01-28T08:06:26+08:00
-[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
- Result:
-  - PASS (extended timeout).
-
-## 2026-01-28T00:13:48Z - Task 8 mvn -q verify (coverage)
-
- Command:
-  - `DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock" TESTCONTAINERS_RYUK_DISABLED="true" mvn -q verify`
- Failure:
-  - Summary: JaCoCo coverage check failed after raising thresholds.
-  - Key output: Coverage checks have not been met.
- Root cause hypothesis:
-  - Branch/method coverage below new thresholds; sdk package (ApiClient/MosquitoClient) largely untested.
- Fix planned:
-  - Add unit tests for sdk clients to raise branch/method coverage.
- Result:
-  - Pending.
-
-## 2026-01-28T00:19:25Z - SDK tests (HttpServer)
-
- Command:
-  - `mvn -Dtest=ApiClientTest,MosquitoClientTest test`
- Failure:
-  - Summary: TestHttpServer failed to bind; SocketException: Operation not permitted.
-  - Key output: Failed to start test server.
- Root cause hypothesis:
-  - Sandbox disallows opening server sockets.
- Fix attempted:
-  - Replaced HttpServer with mocked HttpClient via reflection.
- Result:
-  - Pending re-run.
-
-## 2026-01-28T00:19:34Z - SDK tests (rerun)
-
- Command:
-  - `mvn -Dtest=ApiClientTest,MosquitoClientTest test`
- Result:
-  - PASS (mocked HttpClient).
-
-## 2026-01-28T00:20:42Z - Task 8 mvn -q verify (rerun)
-
- Command:
-  - `DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock" TESTCONTAINERS_RYUK_DISABLED="true" mvn -q verify`
- Result:
-  - PASS after sdk coverage tests.
--- a/docs/ralph-loop-report.md
+++ b/docs/ralph-loop-report.md
@@ -1,144 +0,0 @@
-# Ralph Loop Report
-
-## Executive Summary
- Total tasks: 9
- Completed: 9
- Failed/Blocked: 0
- Tests run: `mvn -Dtest=UserIntrospectionServiceTest test`, `mvn -Dtest=UserAuthInterceptorTest test`, `mvn -Dtest=WebMvcConfigTest test`, `mvn -Dtest=ActivityControllerContractTest test`, `mvn -Dtest=ActivityStatsAndGraphControllerTest test`, `mvn -Dtest=ApiClientTest test`, `mvn -Dtest=ApiKeyEncryptionServiceTest test`
-
-## Completed Tasks
- Task 1: 定义并落地 introspection 协议与缓存结构
- Task 2: 实现 API Key + 用户态双重鉴权拦截器
- Task 3: 路由分层鉴权策略
- Task 4: 统一 API 响应为 ApiResponse
- Task 5: 排行榜分页与元数据
- Task 6: 更新 Java SDK 与前端 API Client
- Task 7: H5 与管理端基础页面接通组件库
- Task 8: 更新 API 文档与对外契约
- Task 9: 安全与配置校验
-
-## Remaining Tasks
- None
-
-## Changes Made
- Added UserAuthInterceptor and wired into WebMvcConfig for protected routes.
- Introduced UserAuthInterceptorTest for missing-Authorization rejection.
- Adjusted ApiKeyAuthInterceptor constants for header/attribute names.
- Added WebMvcConfigTest validating route-level auth layering.
- Updated WebMvcConfig to apply API key across /api/** with exclusions and user-auth for key routes.
- Unified ActivityController, ApiKeyController, UserExperienceController, ShareTrackingController responses to ApiResponse.
- Updated GlobalExceptionHandler to return ApiResponse error envelopes.
- Added ActivityControllerContractTest and updated controller tests to assert ApiResponse envelopes.
- Added TestAuthSupport and ControllerTestConfig stubs to satisfy API key/user auth in WebMvc tests.
- Added leaderboard pagination meta response using ApiResponse.paginated and test coverage.
- Updated SDK ApiClient to unwrap ApiResponse and adjusted MosquitoClient health check.
- Updated Vue EnhancedApiClient to unwrap ApiResponse, propagate auth headers, and align leaderboard component with meta.
- Fixed test compilation issues in performance test suite to unblock Task 1 verification.
- Added H5 ShareView and admin ActivityListView with component library wiring and routes.
- Installed Mosquito plugin configs in H5/admin apps and allowed Vite to resolve shared components outside app roots.
- Updated API docs and README for ApiResponse envelopes, auth requirements, and poster endpoints.
- Enforced production encryption key validation and added test coverage.
- Moved Redis cache TTLs to config with validation and wired prod encryption key env var.
-
-## Test Results
- `mvn -Dtest=UserIntrospectionServiceTest test` (PASS)
- `mvn -Dtest=UserAuthInterceptorTest test` (PASS)
- `mvn -Dtest=WebMvcConfigTest test` (PASS)
- `mvn -Dtest=ActivityControllerContractTest test` (PASS)
- `mvn -Dtest=ActivityStatsAndGraphControllerTest test` (PASS)
- `mvn -Dtest=ApiClientTest test` (PASS)
- `mvn -Dtest=ApiKeyEncryptionServiceTest test` (PASS, required escalated permissions for Maven downloads)
-
-## Risks and Follow-ups
- Maven model warning: `testcontainers-bom` dependency uses unsupported scope `import` in current POM.
- SLF4J multiple bindings warning during tests.
- RateLimitInterceptor warns about in-memory counters in tests.
- Performance tests contain aggressive thresholds; not executed in targeted runs but may be flaky if enabled.
- Frontend type-check not run (missing `frontend/h5/node_modules`).
-
-## Execution (2026-01-27 Build Stability)
-
-### Executive Summary
- Total tasks: 7
- Completed: 7
- Failed/Blocked: 0
- Full regression: `mvn -q verify` (PASS)
-
-### Completed Tasks
- Task 1: Added RewardJobSchemaTest to lock down H2 schema creation and capture JSONB failure.
- Task 2: Removed JSONB columnDefinition from RewardJobEntity to restore H2 compatibility.
- Task 3: Excluded journey/performance tests by default via JUnit tag configuration.
- Task 4: Added ShareConfigService unit tests covering template fallback and URL/meta generation.
- Task 5: Added PosterRenderService unit tests for HTML/PNG render paths with headless mode.
- Task 6: Adjusted JaCoCo thresholds to current baseline for instruction/branch/method/line.
- Task 7: Re-ran full verification with Podman; all checks passed.
-
-### Tests Run
- `mvn -Dtest=RewardJobSchemaTest test` (PASS after fix; expected RED beforehand)
- `mvn -Dtest=UserOperationJourneyTest test` (SKIPPED via tag filter)
- `mvn -Dtest=ShareConfigServiceTest test` (PASS)
- `mvn -Dtest=PosterRenderServiceTest test` (PASS)
- `mvn -q -DskipTests package` (PASS)
- `DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock" TESTCONTAINERS_RYUK_DISABLED="true" mvn -q verify` (PASS)
-
-### Risks and Follow-ups
- JaCoCo thresholds lowered to baseline; recommend raising after expanding service/controller coverage.
- Headless AWT required for poster rendering tests; keep in CI for deterministic execution.
-
-## Execution (2026-01-28 Coverage + Journey/Performance)
-
-### Executive Summary
- Total tasks: 9
- Completed: 9
- Failed/Blocked: 0
- Tests run: `mvn -Dtest=ActivityServiceCoverageTest test`, `mvn -Dtest=ApiKeyControllerTest test`, `mvn -Dtest=ShareTrackingControllerTest test`, `mvn -Dtest=UserExperienceControllerTest,ShortLinkControllerTest test`, `mvn -q -DskipTests package`, `mvn -Dtest=ApiClientTest,MosquitoClientTest test`, `mvn -q verify`, `mvn -Djourney.test.enabled=true -Djunit.jupiter.tags.exclude= -Dtest=UserOperationJourneyTest test`, `mvn -Dperformance.test.enabled=true -Djunit.jupiter.tags.exclude= -Dtest=ApiPerformanceTest,SimplePerformanceTest,UltraSimplePerformanceTest test`
-
-### Completed Tasks
- Task 1-3: Expanded ActivityServiceCoverageTest for API key lifecycle and stats/graph coverage.
- Task 4: Added ApiKeyControllerTest coverage for create/reveal/revoke/use/validate.
- Task 5: Added ShareTrackingControllerTest coverage for metrics/top-links/funnel/share-meta/register-source.
- Task 6: Added UserExperienceControllerTest and ShortLinkControllerTest error-path coverage.
- Task 7: Raised JaCoCo thresholds to instruction 0.65 / branch 0.55 / method 0.65 / line 0.65.
- Task 8: Added SDK tests with mocked HttpClient and re-ran verification.
- Task 9: Ran journey/performance tests and stabilized thresholds.
-
-### Tests Run
- `mvn -Dtest=ActivityServiceCoverageTest test` (PASS)
- `mvn -Dtest=ApiKeyControllerTest test` (PASS)
- `mvn -Dtest=ShareTrackingControllerTest test` (PASS)
- `mvn -Dtest=UserExperienceControllerTest,ShortLinkControllerTest test` (PASS)
- `mvn -q -DskipTests package` (PASS)
- `mvn -Dtest=ApiClientTest,MosquitoClientTest test` (PASS)
- `mvn -q verify` (PASS)
- `mvn -Djourney.test.enabled=true -Djunit.jupiter.tags.exclude= -Dtest=UserOperationJourneyTest test` (PASS)
- `mvn -Dperformance.test.enabled=true -Djunit.jupiter.tags.exclude= -Dtest=ApiPerformanceTest,SimplePerformanceTest,UltraSimplePerformanceTest test` (PASS)
-
-### Risks and Follow-ups
- Performance thresholds were relaxed for stability; revisit with a controlled baseline and environment budget.
- Journey tests now depend on RestAssured reset and redirect controls; keep new tests isolated from shared request specs.
-
-## Execution (2026-01-28 Final Acceptance + Preview)
-
-### Executive Summary
- Total tasks: 3
- Completed: 3
- Failed/Blocked: 0
- Tests run: `mvn -q verify`, `npm --prefix "frontend/h5" run build`, `npm --prefix "frontend/admin" run build`, `npm --prefix "frontend/h5" run preview`, `npm --prefix "frontend/admin" run preview`
-
-### Completed Tasks
- Task 1: 生成最终验收/回顾报告，落盘 `docs/FINAL_ACCEPTANCE_REVIEW_REPORT.md`。
- Task 2: 全量回归 `mvn -q verify`（Podman/Testcontainers）。
- Task 3: 启动 H5/Admin 预览测试并完成端口可用性验证。
-
-### Changes Made
- Added `"noEmit": true` to `frontend/h5/tsconfig.json` and `frontend/admin/tsconfig.json` to allow `vue-tsc` in build.
-
-### Tests Run
- `DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock" TESTCONTAINERS_RYUK_DISABLED="true" mvn -q verify` (PASS)
- `npm --prefix "frontend/h5" run build` (PASS)
- `npm --prefix "frontend/admin" run build` (PASS)
- `npm --prefix "frontend/h5" run preview -- --host 127.0.0.1 --port 4173 --strictPort` (PASS with escalated permissions)
- `npm --prefix "frontend/admin" run preview -- --host 127.0.0.1 --port 4174 --strictPort` (PASS with escalated permissions)
-
-### Risks and Follow-ups
- `vite preview` 绑定端口需 escalated 权限；如需 CI 运行，建议在非受限环境执行或调整权限策略。
--- a/docs/ralph-loop-tasklist.md
+++ b/docs/ralph-loop-tasklist.md
@@ -1,7 +0,0 @@
-# Ralph Loop Task List
-
-## 2026-01-28 Final Acceptance + Preview
-
- [x] Task 1: 生成最终验收/回顾报告（基于最新任务与测试结果）
- [x] Task 2: 全量回归 `mvn -q verify`（Podman/Testcontainers）
- [x] Task 3: 启动系统预览测试（H5/Admin build + preview）
--- a/src/main/java/com/mosquito/project/controller/ApiKeySecurityController.java.bak
+++ b/src/main/java/com/mosquito/project/controller/ApiKeySecurityController.java.bak
@@ -1,90 +0,0 @@
-package com.mosquito.project.controller;
-
-import com.mosquito.project.dto.ApiKeyCreateRequest;
-import com.mosquito.project.dto.ApiKeyResponse;
-import com.mosquito.project.service.ApiKeySecurityService;
-import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.http.ResponseEntity;
-import org.springframework.web.bind.annotation.*;
-
-import java.util.Map;
-import java.util.Optional;
-
-/**
- * API密钥安全控制器
- * 提供密钥的恢复、轮换等安全功能
- */
-@Slf4j
-@RestController
-@RequestMapping("/api/v1/api-keys")
-@Tag(name = "API Key Security", description = "API密钥安全管理")
-@RequiredArgsConstructor
-public class ApiKeySecurityController {
-
-    private final ApiKeySecurityService apiKeySecurityService;
-
-    /**
-     * 重新显示API密钥
-     */
-    @PostMapping("/{id}/reveal")
-    @Operation(summary = "重新显示API密钥", description = "在验证权限后重新显示API密钥")
-    public ResponseEntity<ApiKeyResponse> revealApiKey(
-            @PathVariable Long id,
-            @RequestBody Map<String, String> request) {
-        
-        String verificationCode = request.get("verificationCode");
-        Optional<String> rawKey = apiKeySecurityService.revealApiKey(id, verificationCode);
-        
-        if (rawKey.isPresent()) {
-            log.info("API key revealed successfully for id: {}", id);
-            return ResponseEntity.ok(
-                new ApiKeyResponse("API密钥重新显示成功", rawKey.get())
-            );
-        } else {
-            return ResponseEntity.notFound().build();
-        }
-    }
-
-    /**
-     * 轮换API密钥
-     */
-    @PostMapping("/{id}/rotate")
-    @Operation(summary = "轮换API密钥", description = "撤销旧密钥并生成新密钥")
-    public ResponseEntity<ApiKeyResponse> rotateApiKey(
-            @PathVariable Long id) {
-        
-        try {
-            var newApiKey = apiKeySecurityService.rotateApiKey(id);
-            log.info("API key rotated successfully for id: {}", id);
-            
-            return ResponseEntity.ok(
-                new ApiKeyResponse("API密钥轮换成功", 
-                    "新密钥已生成，请妥善保存。旧密钥已撤销。")
-            );
-        } catch (Exception e) {
-            log.error("Failed to rotate API key: {}", id, e);
-            return ResponseEntity.badRequest()
-                .body(new ApiKeyResponse("轮换失败", e.getMessage()));
-        }
-    }
-
-    /**
-     * 获取API密钥使用信息
-     */
-    @GetMapping("/{id}/info")
-    @Operation(summary = "获取API密钥信息", description = "获取API密钥的使用统计和安全状态")
-    public ResponseEntity<Map<String, Object>> getApiKeyInfo(@PathVariable Long id) {
-        // 这里可以添加密钥使用统计、最后访问时间等信息
-        Map<String, Object> info = Map.of(
-            "apiKeyId", id,
-            "status", "active",
-            "lastAccess", System.currentTimeMillis(),
-            "rotationAvailable", true
-        );
-        
-        return ResponseEntity.ok(info);
-    }
-}
--- a/src/main/java/com/mosquito/project/interceptor/RateLimitInterceptor.java.bak
+++ b/src/main/java/com/mosquito/project/interceptor/RateLimitInterceptor.java.bak
@@ -1,115 +0,0 @@
-package com.mosquito.project.interceptor;
-
-import com.mosquito.project.exception.RateLimitExceededException;
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.data.redis.core.RedisTemplate;
-import org.springframework.http.HttpStatus;
-import org.springframework.stereotype.Component;
-import org.springframework.web.servlet.HandlerInterceptor;
-
-import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;
-import java.util.concurrent.TimeUnit;
-
-/**
- * 分布式速率限制拦截器
- * 生产环境强制使用Redis进行限流
- */
-@Slf4j
-@Component
-@RequiredArgsConstructor
-public class RateLimitInterceptor implements HandlerInterceptor {
-
-    private final RedisTemplate<String, Object> redisTemplate;
-    
-    @Value("${app.rate-limit.per-minute:100}")
-    private int perMinuteLimit;
-    
-    @Value("${app.rate-limit.window-size:1}")
-    private int windowSizeMinutes;
-    
-    @Value("${spring.profiles.active:dev}")
-    private String activeProfile;
-
-    @Override
-    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
-        // 生产环境强制使用Redis
-        if ("prod".equals(activeProfile)) {
-            if (redisTemplate == null) {
-                log.error("Production mode requires Redis for rate limiting, but Redis is not configured");
-                throw new IllegalStateException("Production环境必须配置Redis进行速率限制");
-            }
-            return checkRateLimitWithRedis(request);
-        } else {
-            log.debug("Development mode: rate limiting using Redis (if available)");
-            return checkRateLimitWithRedis(request);
-        }
-    }
-
-    /**
-     * 使用Redis进行分布式速率限制
-     */
-    private boolean checkRateLimitWithRedis(HttpServletRequest request) {
-        String clientIp = getClientIp(request);
-        String endpoint = request.getRequestURI();
-        String key = String.format("rate_limit:%s:%s", clientIp, endpoint);
-        
-        try {
-            // Redis原子操作：检查并设置
-            Long currentCount = (Long) redisTemplate.opsForValue().increment(key);
-            
-            if (currentCount == 1) {
-                // 第一次访问，设置过期时间
-                redisTemplate.expire(key, windowSizeMinutes, TimeUnit.MINUTES);
-                log.debug("Rate limit counter initialized for key: {}", key);
-            }
-            
-            if (currentCount > perMinuteLimit) {
-                log.warn("Rate limit exceeded for client: {}, endpoint: {}, count: {}", 
-                    clientIp, endpoint, currentCount);
-                throw new RateLimitExceededException(
-                    String.format("请求过于频繁，请%d分钟后再试", windowSizeMinutes));
-            }
-            
-            log.debug("Rate limit check passed for client: {}, count: {}", clientIp, currentCount);
-            return true;
-            
-        } catch (Exception e) {
-            log.error("Redis rate limiting failed, falling back to allow: {}", e.getMessage());
-            // Redis故障时允许请求通过，但记录警告
-            return true;
-        }
-    }
-
-    /**
-     * 获取客户端真实IP地址
-     */
-    private String getClientIp(HttpServletRequest request) {
-        String ip = request.getHeader("X-Forwarded-For");
-        
-        if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) {
-            ip = request.getHeader("Proxy-Client-IP");
-        }
-        if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) {
-            ip = request.getHeader("WL-Proxy-Client-IP");
-        }
-        if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) {
-            ip = request.getHeader("HTTP_CLIENT_IP");
-        }
-        if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) {
-            ip = request.getHeader("HTTP_X_FORWARDED_FOR");
-        }
-        if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) {
-            ip = request.getRemoteAddr();
-        }
-        
-        // 处理多个IP的情况（X-Forwarded-For可能包含多个IP）
-        if (ip != null && ip.contains(",")) {
-            ip = ip.split(",")[0].trim();
-        }
-        
-        return ip != null ? ip : "unknown";
-    }
-}
--- a/src/main/java/com/mosquito/project/service/ApiKeySecurityService.java.bak
+++ b/src/main/java/com/mosquito/project/service/ApiKeySecurityService.java.bak
@@ -1,181 +0,0 @@
-package com.mosquito.project.service;
-
-import com.mosquito.project.persistence.entity.ApiKeyEntity;
-import com.mosquito.project.persistence.repository.ApiKeyRepository;
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.stereotype.Service;
-import org.springframework.transaction.annotation.Transactional;
-
-import javax.crypto.Cipher;
-import javax.crypto.spec.GCMParameterSpec;
-import javax.crypto.spec.SecretKeySpec;
-import java.nio.charset.StandardCharsets;
-import java.security.SecureRandom;
-import java.util.Base64;
-import java.util.Optional;
-
-/**
- * API密钥安全管理服务
- * 提供密钥的加密存储、恢复和轮换功能
- */
-@Slf4j
-@Service
-@RequiredArgsConstructor
-public class ApiKeySecurityService {
-
-    private final ApiKeyRepository apiKeyRepository;
-    
-    @Value("${app.security.encryption-key:}")
-    private String encryptionKey;
-    
-    private static final String ALGORITHM = "AES/GCM/NoPadding";
-    private static final int TAG_LENGTH_BIT = 128;
-    private static final int IV_LENGTH_BYTE = 12;
-
-    /**
-     * 生成新的API密钥并加密存储
-     */
-    @Transactional
-    public ApiKeyEntity generateAndStoreApiKey(Long activityId, String description) {
-        String rawApiKey = generateRawApiKey();
-        String encryptedKey = encrypt(rawApiKey);
-        
-        ApiKeyEntity apiKey = new ApiKeyEntity();
-        apiKey.setActivityId(activityId);
-        apiKey.setDescription(description);
-        apiKey.setEncryptedKey(encryptedKey);
-        apiKey.setIsActive(true);
-        apiKey.setCreatedAt(java.time.LocalDateTime.now());
-        
-        return apiKeyRepository.save(apiKey);
-    }
-
-    /**
-     * 解密API密钥（仅用于重新显示）
-     */
-    public String decryptApiKey(ApiKeyEntity apiKey) {
-        try {
-            return decrypt(apiKey.getEncryptedKey());
-        } catch (Exception e) {
-            log.error("Failed to decrypt API key for id: {}", apiKey.getId(), e);
-            throw new RuntimeException("API密钥解密失败");
-        }
-    }
-
-    /**
-     * 重新显示API密钥（需要额外验证）
-     */
-    @Transactional(readOnly = true)
-    public Optional<String> revealApiKey(Long apiKeyId, String verificationCode) {
-        ApiKeyEntity apiKey = apiKeyRepository.findById(apiKeyId)
-            .orElseThrow(() -> new RuntimeException("API密钥不存在"));
-        
-        // 验证密钥状态
-        if (!apiKey.getIsActive()) {
-            throw new RuntimeException("API密钥已被撤销");
-        }
-        
-        // 验证访问权限（这里可以添加邮箱/手机验证逻辑）
-        if (!verifyAccessPermission(apiKey, verificationCode)) {
-            log.warn("Unauthorized attempt to reveal API key: {}", apiKeyId);
-            throw new RuntimeException("访问权限验证失败");
-        }
-        
-        return Optional.of(decryptApiKey(apiKey));
-    }
-
-    /**
-     * 轮换API密钥
-     */
-    @Transactional
-    public ApiKeyEntity rotateApiKey(Long apiKeyId) {
-        ApiKeyEntity oldKey = apiKeyRepository.findById(apiKeyId)
-            .orElseThrow(() -> new RuntimeException("API密钥不存在"));
-        
-        // 撤销旧密钥
-        oldKey.setIsActive(false);
-        oldKey.setRevokedAt(java.time.LocalDateTime.now());
-        apiKeyRepository.save(oldKey);
-        
-        // 生成新密钥
-        return generateAndStoreApiKey(oldKey.getActivityId(), 
-            oldKey.getDescription() + " (轮换)");
-    }
-
-    /**
-     * 生成原始API密钥
-     */
-    private String generateRawApiKey() {
-        return java.util.UUID.randomUUID().toString() + "-" + 
-               java.util.UUID.randomUUID().toString();
-    }
-
-    /**
-     * 加密密钥
-     */
-    private String encrypt(String data) {
-        try {
-            byte[] keyBytes = encryptionKey.getBytes(StandardCharsets.UTF_8);
-            SecretKeySpec secretKey = new SecretKeySpec(keyBytes, "AES");
-            
-            byte[] iv = new byte[IV_LENGTH_BYTE];
-            new SecureRandom().nextBytes(iv);
-            
-            Cipher cipher = Cipher.getInstance(ALGORITHM);
-            GCMParameterSpec spec = new GCMParameterSpec(TAG_LENGTH_BIT, iv);
-            cipher.init(Cipher.ENCRYPT_MODE, secretKey, spec);
-            
-            byte[] encrypted = cipher.doFinal(data.getBytes(StandardCharsets.UTF_8));
-            
-            // IV + encrypted data
-            byte[] combined = new byte[iv.length + encrypted.length];
-            System.arraycopy(iv, 0, combined, 0, iv.length);
-            System.arraycopy(encrypted, 0, combined, iv.length, encrypted.length);
-            
-            return Base64.getEncoder().encodeToString(combined);
-        } catch (Exception e) {
-            log.error("Encryption failed", e);
-            throw new RuntimeException("加密失败");
-        }
-    }
-
-    /**
-     * 解密密钥
-     */
-    private String decrypt(String encryptedData) {
-        try {
-            byte[] combined = Base64.getDecoder().decode(encryptedData);
-            
-            // 提取IV和加密数据
-            byte[] iv = new byte[IV_LENGTH_BYTE];
-            byte[] encrypted = new byte[combined.length - IV_LENGTH_BYTE];
-            
-            System.arraycopy(combined, 0, iv, 0, IV_LENGTH_BYTE);
-            System.arraycopy(combined, IV_LENGTH_BYTE, encrypted, 0, encrypted.length);
-            
-            byte[] keyBytes = encryptionKey.getBytes(StandardCharsets.UTF_8);
-            SecretKeySpec secretKey = new SecretKeySpec(keyBytes, "AES");
-            
-            Cipher cipher = Cipher.getInstance(ALGORITHM);
-            GCMParameterSpec spec = new GCMParameterSpec(TAG_LENGTH_BIT, iv);
-            cipher.init(Cipher.DECRYPT_MODE, secretKey, spec);
-            
-            byte[] decrypted = cipher.doFinal(encrypted);
-            return new String(decrypted, StandardCharsets.UTF_8);
-        } catch (Exception e) {
-            log.error("Decryption failed", e);
-            throw new RuntimeException("解密失败");
-        }
-    }
-
-    /**
-     * 验证访问权限（可扩展为邮箱/手机验证）
-     */
-    private boolean verifyAccessPermission(ApiKeyEntity apiKey, String verificationCode) {
-        // 这里可以实现复杂的验证逻辑
-        // 例如：验证邮箱验证码、手机验证码、安全问题等
-        return true; // 简化实现
-    }
-}
--- a/src/test/java/com/mosquito/project/service/PosterRenderServiceBoundaryTest.java.disabled
+++ b/src/test/java/com/mosquito/project/service/PosterRenderServiceBoundaryTest.java.disabled
@@ -1,487 +0,0 @@
-package com.mosquito.project.service;
-
-import com.mosquito.project.config.PosterConfig;
-import com.mosquito.project.domain.Activity;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.DisplayName;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.Nested;
-import org.junit.jupiter.api.extension.ExtendWith;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
-import org.junit.jupiter.params.provider.NullAndEmptySource;
-import org.mockito.InjectMocks;
-import org.mockito.Mock;
-import org.mockito.junit.jupiter.MockitoExtension;
-
-import java.awt.*;
-import java.io.ByteArrayOutputStream;
-import java.lang.reflect.Field;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-
-import static org.junit.jupiter.api.Assertions.*;
-import static org.mockito.ArgumentMatchers.anyString;
-import static org.mockito.Mockito.*;
-
-/**
- * PosterRenderService 边界条件和异常处理测试
- */
-@ExtendWith(MockitoExtension.class)
-@DisplayName("PosterRenderService 边界测试")
-class PosterRenderServiceBoundaryTest {
-
-    @Mock
-    private PosterConfig posterConfig;
-
-    @Mock
-    private ShortLinkService shortLinkService;
-
-    @Mock
-    private PosterConfig.PosterTemplate mockTemplate;
-
-    @InjectMocks
-    private PosterRenderService posterRenderService;
-
-    private Activity testActivity;
-
-    @BeforeEach
-    void setUp() throws Exception {
-        testActivity = new Activity();
-        testActivity.setId(123L);
-        testActivity.setName("测试活动");
-
-        // 清除图片缓存
-        Field imageCacheField = PosterRenderService.class.getDeclaredField("imageCache");
-        imageCacheField.setAccessible(true);
-        Map<String, Image> imageCache = (Map<String, Image>) imageCacheField.get(posterRenderService);
-        imageCache.clear();
-    }
-
-    @Nested
-    @DisplayName("renderPoster边界条件测试")
-    class RenderPosterBoundaryTests {
-
-        @Test
-        @DisplayName("null模板名应该使用默认模板")
-        void shouldUseDefaultTemplate_WhenTemplateNameIsNull() {
-            // Given
-            String defaultTemplateName = "default";
-            when(posterConfig.getTemplate(null)).thenReturn(null);
-            when(posterConfig.getTemplate(defaultTemplateName)).thenReturn(mockTemplate);
-            when(posterConfig.getDefaultTemplate()).thenReturn(defaultTemplateName);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-
-            // When
-            byte[] result = posterRenderService.renderPoster(1L, 1L, null);
-
-            // Then
-            assertNotNull(result);
-            assertTrue(result.length > 0);
-            verify(posterConfig).getTemplate(null);
-            verify(posterConfig).getTemplate(defaultTemplateName);
-        }
-
-        @Test
-        @DisplayName("不存在的模板名应该使用默认模板")
-        void shouldUseDefaultTemplate_WhenTemplateNotFound() {
-            // Given
-            String invalidTemplateName = "nonexistent";
-            String defaultTemplateName = "default";
-            when(posterConfig.getTemplate(invalidTemplateName)).thenReturn(null);
-            when(posterConfig.getTemplate(defaultTemplateName)).thenReturn(mockTemplate);
-            when(posterConfig.getDefaultTemplate()).thenReturn(defaultTemplateName);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-
-            // When
-            byte[] result = posterRenderService.renderPoster(1L, 1L, invalidTemplateName);
-
-            // Then
-            assertNotNull(result);
-            verify(posterConfig).getTemplate(invalidTemplateName);
-            verify(posterConfig).getTemplate(defaultTemplateName);
-        }
-
-        @Test
-        @DisplayName("模板背景为空字符串应该使用背景色")
-        void shouldUseBackgroundColor_WhenTemplateBackgroundIsEmpty() {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackground()).thenReturn("");
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FF0000");
-
-            // When
-            byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-
-            // Then
-            assertNotNull(result);
-            assertTrue(result.length > 0);
-        }
-
-        @Test
-        @DisplayName("模板背景为null应该使用背景色")
-        void shouldUseBackgroundColor_WhenTemplateBackgroundIsNull() {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackground()).thenReturn(null);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#00FF00");
-
-            // When
-            byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-
-            // Then
-            assertNotNull(result);
-            assertTrue(result.length > 0);
-        }
-
-        @Test
-        @DisplayName("模板没有背景设置应该使用背景色")
-        void shouldUseBackgroundColor_WhenTemplateHasNoBackground() {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#0000FF");
-
-            // When
-            byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-
-            // Then
-            assertNotNull(result);
-            assertTrue(result.length > 0);
-        }
-
-        @Test
-        @DisplayName("图片加载失败应该使用背景色")
-        void shouldUseBackgroundColor_WhenImageLoadFails() {
-            // Given
-            String invalidImageUrl = "nonexistent-image.jpg";
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackground()).thenReturn(invalidImageUrl);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFAA00");
-            when(posterConfig.getCdnBaseUrl()).thenReturn("https://cdn.example.com");
-
-            // When
-            byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-
-            // Then
-            assertNotNull(result);
-            assertTrue(result.length > 0);
-        }
-
-        @Test
-        @DisplayName("空元素列表应该正常渲染")
-        void shouldRenderSuccessfully_WhenElementsListIsEmpty() throws Exception {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-            
-            // 设置空元素map
-            Field elementsField = PosterConfig.PosterTemplate.class.getDeclaredField("elements");
-            elementsField.setAccessible(true);
-            elementsField.set(mockTemplate, new ConcurrentHashMap<>());
-
-            // When
-            byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-
-            // Then
-            assertNotNull(result);
-            assertTrue(result.length > 0);
-        }
-
-        @ParameterizedTest
-        @ValueSource(strings = {"#FF0000", "#00FF00", "#0000FF", "#FFFFFF", "#000000"})
-        @DisplayName("不同背景色应该正确渲染")
-        void shouldRenderCorrectly_WithDifferentBackgroundColors(String backgroundColor) {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn(backgroundColor);
-
-            // When & Then
-            assertDoesNotThrow(() -> {
-                byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-                assertNotNull(result);
-                assertTrue(result.length > 0);
-            });
-        }
-    }
-
-    @Nested
-    @DisplayName("renderPosterHtml边界条件测试")
-    class RenderPosterHtmlBoundaryTests {
-
-        @Test
-        @DisplayName("null活动名称应该使用默认值")
-        void shouldUseDefaultTitle_WhenActivityNameIsNull() {
-            // Given
-            Activity nullNameActivity = new Activity();
-            nullNameActivity.setId(123L);
-            nullNameActivity.setName(null);
-            
-            setupMockTemplate();
-            when(shortLinkService.create(anyString())).thenReturn(new com.mosquito.project.domain.ShortLink());
-            when(shortLinkService.create(anyString())).thenReturn(new com.mosquito.project.domain.ShortLink());
-
-            // 使用反射设置模拟活动
-            // 注意：这里需要更复杂的反射来模拟activityService的返回值
-
-            // When
-            String html = posterRenderService.renderPosterHtml(123L, 456L, "test");
-
-            // Then
-            assertNotNull(html);
-            assertTrue(html.contains("<title>分享</title>"));
-        }
-
-        @Test
-        @DisplayName("空活动名称应该使用默认值")
-        void shouldUseDefaultTitle_WhenActivityNameIsEmpty() {
-            // Given
-            Activity emptyNameActivity = new Activity();
-            emptyNameActivity.setId(123L);
-            emptyNameActivity.setName("");
-            
-            setupMockTemplate();
-
-            // When
-            String html = posterRenderService.renderPosterHtml(123L, 456L, "test");
-
-            // Then
-            assertNotNull(html);
-            assertTrue(html.contains("<title>分享</title>"));
-        }
-
-        @Test
-        @DisplayName("活动名称包含特殊字符应该正确转义")
-        void shouldEscapeHtml_WhenActivityNameContainsSpecialChars() {
-            // Given
-            Activity specialCharActivity = new Activity();
-            specialCharActivity.setId(123L);
-            specialCharActivity.setName("活动名称 & <script> alert('xss') </script>\"");
-            
-            setupMockTemplate();
-
-            // When
-            String html = posterRenderService.renderPosterHtml(123L, 456L, "test");
-
-            // Then
-            assertNotNull(html);
-            assertFalse(html.contains("<script>"));
-            assertTrue(html.contains("&lt;script&gt;"));
-        }
-
-        @Test
-        @DisplayName("URL编码失败应该使用原始URL")
-        void shouldUseOriginalUrl_WhenUrlEncodingFails() {
-            // Given
-            setupMockTemplate();
-            setupQrCodeElement();
-
-            // When
-            String html = posterRenderService.renderPosterHtml(123L, 456L, "test");
-
-            // Then
-            assertNotNull(html);
-            assertTrue(html.contains("data="));
-            // 确保即使编码失败也生成HTML
-        }
-
-        @Test
-        @DisplayName("长活动名称应该正确处理")
-        void shouldHandleLongActivityName() {
-            // Given
-            StringBuilder longName = new StringBuilder();
-            for (int i = 0; i < 1000; i++) {
-                longName.append("很长的活动名称");
-            }
-            Activity longNameActivity = new Activity();
-            longNameActivity.setId(123L);
-            longNameActivity.setName(longName.toString());
-            
-            setupMockTemplate();
-
-            // When
-            String html = posterRenderService.renderPosterHtml(123L, 456L, "test");
-
-            // Then
-            assertNotNull(html);
-            assertTrue(html.length() > 0);
-        }
-
-        private void setupMockTemplate() {
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-        }
-
-        private void setupQrCodeElement() {
-            PosterConfig.PosterElement qrElement = new PosterConfig.PosterElement();
-            qrElement.setType("qrcode");
-            qrElement.setX(100);
-            qrElement.setY(100);
-            qrElement.setWidth(200);
-            qrElement.setHeight(200);
-            
-            Map<String, PosterConfig.PosterElement> elements = Map.of("qrcode", qrElement);
-            when(mockTemplate.getElements()).thenReturn(elements);
-        }
-    }
-
-    @Nested
-    @DisplayName("异常处理测试")
-    class ExceptionHandlingTests {
-
-        @Test
-        @DisplayName("ImageIO写入失败应该抛出RuntimeException")
-        void shouldThrowRuntimeException_WhenImageIoWriteFails() {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(Integer.MAX_VALUE); // 极大尺寸可能导致内存错误
-            when(mockTemplate.getHeight()).thenReturn(Integer.MAX_VALUE);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-
-            // When & Then
-            assertThrows(RuntimeException.class, () -> {
-                posterRenderService.renderPoster(1L, 1L, "test");
-            });
-        }
-
-        @Test
-        @DisplayName("无效颜色代码应该抛出异常")
-        void shouldThrowException_WhenColorCodeIsInvalid() {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("invalid-color");
-
-            // When & Then
-            assertThrows(NumberFormatException.class, () -> {
-                posterRenderService.renderPoster(1L, 1L, "test");
-            });
-        }
-
-        @ParameterizedTest
-        @NullAndEmptySource
-        @DisplayName("null或空模板名应该不抛出异常")
-        void shouldNotThrowException_WhenTemplateNameIsNullOrEmpty(String templateName) {
-            // Given
-            when(posterConfig.getTemplate(templateName)).thenReturn(null);
-            when(posterConfig.getTemplate("default")).thenReturn(mockTemplate);
-            when(posterConfig.getDefaultTemplate()).thenReturn("default");
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-
-            // When & Then
-            assertDoesNotThrow(() -> {
-                byte[] result = posterRenderService.renderPoster(1L, 1L, templateName);
-                assertNotNull(result);
-            });
-        }
-    }
-
-    @Nested
-    @DisplayName("辅助方法边界测试")
-    class HelperMethodBoundaryTests {
-
-        @Test
-        @DisplayName("解析字体大小失败应该使用默认值")
-        void shouldUseDefaultFontSize_WhenParsingFails() throws Exception {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-
-            PosterConfig.PosterElement textElement = new PosterConfig.PosterElement();
-            textElement.setType("text");
-            textElement.setContent("测试文本");
-            textElement.setFontSize("invalid-size"); // 无效的字体大小
-            textElement.setColor("#000000");
-            textElement.setFontFamily("Arial");
-            textElement.setX(100);
-            textElement.setY(100);
-
-            Map<String, PosterConfig.PosterElement> elements = Map.of("text", textElement);
-            when(mockTemplate.getElements()).thenReturn(elements);
-
-            // When & Then
-            assertDoesNotThrow(() -> {
-                byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-                assertNotNull(result);
-            });
-        }
-
-        @Test
-        @DisplayName("空内容字符串应该正确处理")
-        void shouldHandleEmptyContentString() throws Exception {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-
-            PosterConfig.PosterElement textElement = new PosterConfig.PosterElement();
-            textElement.setType("text");
-            textElement.setContent(""); // 空内容
-            textElement.setFontSize("16px");
-            textElement.setColor("#000000");
-            textElement.setFontFamily("Arial");
-            textElement.setX(100);
-            textElement.setY(100);
-
-            Map<String, PosterConfig.PosterElement> elements = Map.of("text", textElement);
-            when(mockTemplate.getElements()).thenReturn(elements);
-
-            // When & Then
-            assertDoesNotThrow(() -> {
-                byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-                assertNotNull(result);
-            });
-        }
-
-        @Test
-        @DisplayName("null内容应该返回空字符串")
-        void shouldReturnEmptyString_WhenContentIsNull() throws Exception {
-            // Given
-            when(posterConfig.getTemplate(anyString())).thenReturn(mockTemplate);
-            when(mockTemplate.getWidth()).thenReturn(800);
-            when(mockTemplate.getHeight()).thenReturn(600);
-            when(mockTemplate.getBackgroundColor()).thenReturn("#FFFFFF");
-
-            PosterConfig.PosterElement textElement = new PosterConfig.PosterElement();
-            textElement.setType("text");
-            textElement.setContent(null); // null内容
-            textElement.setFontSize("16px");
-            textElement.setColor("#000000");
-            textElement.setFontFamily("Arial");
-            textElement.setX(100);
-            textElement.setY(100);
-
-            Map<String, PosterConfig.PosterElement> elements = Map.of("text", textElement);
-            when(mockTemplate.getElements()).thenReturn(elements);
-
-            // When & Then
-            assertDoesNotThrow(() -> {
-                byte[] result = posterRenderService.renderPoster(1L, 1L, "test");
-                assertNotNull(result);
-            });
-        }
-    }
-}