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

2025-09-30 16:39:51 +08:00
commit 8a7afc8a00
76 changed files with 5091 additions and 0 deletions
--- a/docs/PRD.md
+++ b/docs/PRD.md
@@ -0,0 +1,132 @@
+# 产品需求文档 (PRD) - “蚊子”传播系统
+
+**版本**: 1.2 (已优化)
+**日期**: 2025年9月27日
+
+---
+
+## 1. 执行摘要 (Executive Summary)
+
+“蚊子”传播系统是一个SaaS工具，旨在解决企业在口碑营销中面临的**传播路径黑盒、激励缺失、效果无法量化**的核心痛点。本产品通过提供一套可视化的、自动激励的病毒式营销活动管理平台，帮助企业系统化地规划、执行和分析裂变增长活动。我们的目标是将客户的平均用户获客成本（CAC）降低50%以上，并显著提升K因子，实现可控、高效的用户增长。
+
+## 2. 产品愿景 (Product Vision)
+
+让每一次用户分享都如“蚊子”一般，具备**精准定位、快速裂变、可追踪、可激励**的特性。我们致力于将不可控的“口碑”转化为可量化的“增长引擎”，成为企业进行病毒式营销的首选工具。
+
+## 3. 背景与问题陈述 (Background & Problem Statement)
+
+在当前获客成本日益增高的市场环境下，基于社交关系的病毒式营销是最低成本、高转化的增长方式。然而，企业普遍面临以下问题：
+- **传播路径黑盒**：无法清晰了解用户分享的路径，不知道谁是关键传播节点（KOL）。
+- **激励机制缺失**：难以对高价值的传播者进行有效、自动化的奖励，挫伤用户分享积极性。
+- **效果无法量化**：无法准确衡量一场裂变活动的ROI，如K因子、转化率、获客成本等。
+- **活动管理复杂**：创建和管理一场裂变活动流程繁琐，需要开发人员深度介入。
+
+## 4. 产品目标 (Product Goals)
+
+- **业务目标**: 将平均用户获客成本（CAC）降低50%以上，使核心活动的K因子（每个现有用户带来的新用户数）大于1。
+- **产品目标**: 提供一套完整的邀请裂变管理工具，帮助运营人员无需开发介入即可轻松发起、管理和复盘病毒式营销活动。
+- **用户目标**:
+    - **管理员**: 获得高效、低成本的拉新手段，并通过直观数据支持决策。
+    - **传播者**: 获得简单明了的邀请方式、实时的成果反馈和及时的奖励。
+
+## 5. 用户画像 (User Personas)
+
+### 5.1. 活动管理员 (运营/市场经理)
+- **画像**: 负责公司产品的用户增长，关注KPI如新增用户、活跃度、成本等。
+- **痛点**: 希望有更高效、低成本的拉新手段，需要直观的数据来支持决策和汇报。
+
+### 5.2. 终端用户 (传播者/邀请者)
+- **画像**: 产品或服务的现有用户，愿意分享给朋友以获取奖励或社交资本。
+- **痛点**: 分享后不知道有谁通过自己的链接注册，也无法方便地获得承诺的奖励。
+
+## 6. 核心功能 V1.0 (User Stories for V1.0)
+
+### 6.1. 活动管理
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **作为管理员**，我希望能创建一个有时限的邀请活动，以便于策划和管理营销节奏。 | 1. 可设定活动名称、开始时间、结束时间。<br>2. 活动到期后自动停止。 | **高** |
+| **作为管理员**，我希望可以设定活动仅对特定用户群体开放，以便于进行精准营销。 | 1. 可配置活动参与的用户标签或ID列表。 | **高** |
+| **作为管理员**，我希望可以自定义邀请页面的文案和图片，以匹配不同的活动主题和品牌风格。 | 1. 支持富文本编辑器修改文案。<br>2. 支持上传/链接图片。 | **高** |
+| **作为管理员**，我希望设置阶梯式奖励规则，以便激励用户完成更高挑战。 | 1. 可配置多个奖励档位，如“邀请3人得A奖励，邀请10人得B奖励”。 | **高** |
+| **作为管理员**，我希望设置带有衰减系数的多级邀请奖励，以鼓励用户发展下线，扩大传播范围。 | 1. 可配置奖励层级（最多如3级）。<br>2. 可配置每一级奖励的比例或固定值。 | **高** |
+| **作为管理员**，我希望奖励类型可以支持积分和优惠券，以适应不同运营场景。 | 1. 可选择奖励类型为积分或优惠券。<br>2. 可填写对应的积分数量或优惠券批次ID。 | **高** |
+| **(新增)** 作为管理员，我希望能为我的应用生成和管理API密钥，以便安全地将我的系统与“蚊子”系统对接。 | 1. 后台提供API Key生成、查看、重置和禁用的功能。<br>2. 密钥与具体活动或账户关联。 | **高** |
+
+### 6.2. 数据与分析
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **作为管理员**，我希望在后台看到活动的核心数据仪表盘，以便实时监控活动健康度。 | 1. 仪表盘展示PV, UV, 参与人数, 新增注册数, K因子, CAC。<br>2. 数据支持按天查看。 | **高** |
+| **作为管理员**，我希望以网络图的形式查看用户裂变路径，以便快速定位关键传播节点（KOL）。 | 1. 图形化展示用户间的邀请关系。<br>2. 节点可点击，并显示该用户的关键信息（如直接/间接邀请数）。 | **高** |
+| **作为管理员**，我希望能看到一个按邀请数排序的“超级传播者”榜单，以便对他们进行额外奖励或运营。 | 1. 榜单展示用户昵称、头像、总邀请人数。<br>2. 支持导出榜单。 | **中** |
+
+### 6.3. 用户端体验
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **作为参与者**，我希望能方便地获取专属的邀请链接和海报，以便分享给朋友。 | 1. 页面显著位置提供“一键复制链接”按钮。<br>2. 可生成带专属二维码的分享海报。 | **高** |
+| **作为参与者**，我希望在个人中心看到我的邀请记录和奖励明细，以便了解我的贡献和收益。 | 1. 列表展示我邀请的好友（及其状态，如已注册）。<br>2. 列表展示我获得的每一笔奖励。 | **高** |
+
+### 6.4. 系统能力与集成
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **(新增)** 作为第三方应用，当一个新用户通过邀请链接完成注册后，我希望能通过API通知“蚊子”系统，以便为邀请者记功和发放奖励。 | 1. 提供一个安全的、基于API Key认证的回调API。<br>2. API需接收一个在邀请链接中传递的唯一追踪ID。<br>3. API有清晰的成功/失败返回码。 | **高** |
+| **作为系统**，需要能初步识别和拦截刷单行为，以保证活动的公平性和数据准确性。 | 1. 基于IP、设备指纹等信息进行基础的防刷校验。<br>2. 对回调API进行速率限制和来源IP校验。 | **高** |
+| **作为系统**，需要能自动完成奖励发放，以降低运营成本和提升用户体验。 | 1. 可通过API与内部账户系统打通，完成积分/优惠券发放。 | **中** |
+
+***技术流程说明***: *第三方注册回调的数据流如下：*
+1.  *用户A从“蚊子”系统获取邀请链接，链接中包含唯一追踪ID (如 `tracking_id=xyz`)。*
+2.  *用户B点击链接，访问“蚊子”服务器。“蚊子”系统记录点击事件和`tracking_id`，然后将用户重定向到第三方应用的目标页面，并在URL参数中带上`tracking_id`。*
+3.  *用户B在第三方应用完成注册。*
+4.  *第三方应用的后端服务，使用预先生成的API Key，调用“蚊子”系统的回调API，并传入`tracking_id`。*
+5.  *“蚊子”系统验证API Key和`tracking_id`，确认转化成功，为用户A记功并触发奖励机制。*
+
+## 7. 范围与边界 (Scope and Boundaries for V1.0)
+
+- **IN SCOPE (范围内)**:
+    - SaaS后台管理功能。
+    - 标准化的用户端邀请页面。
+    - **(新增)** 用于确认注册成功的服务端回调API (Server-to-Server Callback API)。
+    - 支持积分、优惠券两种奖励类型。
+    - 基础的防刷单机制。
+- **OUT OF SCOPE (范围外)**:
+    - **现金奖励**：V1.0不处理现金发放，流程复杂，风险高。
+    - **A/B 测试框架**：活动级别的A/B测试将在后续版本考虑。
+    - **与外部CRM/MA工具的深度集成**：V1.0仅支持数据导出。
+    - **客户端SDK**: V1.0不提供嵌入App的SDK，通过H5页面承载。
+
+## 8. 风险与假设 (Risks and Assumptions)
+
+- **假设**:
+    - **用户分享意愿**: 假设在合理的奖励激励下，用户愿意主动分享。
+    - **技术可行性**: 假设内部账户系统有稳定、可用的API用于发放奖励。
+    - **(新增)** **客户集成能力**: 假设客户的开发团队有能力对接我们的回调API。
+- **风险**:
+    - **防刷风险**: 简单的防刷机制可能被专业羊毛党绕过，导致活动成本失控。
+    - **数据准确性风险**: 高并发下，数据追踪可能存在延迟或丢失，影响分析和奖励发放。
+    - **用户隐私风险**: 邀请关系链涉及用户数据，需严格遵守隐私政策，否则可能引发法务风险。
+    - **(新增)** **集成复杂性风险**: 如果API设计不佳或文档不清晰，可能导致客户集成失败或意愿降低，从而影响产品推广。
+
+## 9. 非功能性需求 (Non-Functional Requirements)
+
+- **性能**: 邀请链接的跳转响应时间应低于200ms。活动高峰期，核心API需支持至少500 QPS。
+- **可扩展性**: 奖励模块、活动模板应设计为可插拔、可扩展的架构。
+- **安全性**: 保护用户数据隐私，防止数据泄露；所有关键操作需有不可篡改的日志记录；对外开放的API必须有可靠的认证和授权机制。
+- **易用性**: 管理后台应做到“无代码”配置，运营人员通过引导式表单即可完成90%的配置工作。
+- **(新增)** **文档完备性**: 必须提供清晰、准确、对开发者友好的API文档，包含代码示例。
+
+## 10. 成功指标 (Success Metrics)
+
+- **北极星指标**: **K-Factor** (每个参与用户平均带来的新用户数)。目标 > 1。
+- **核心业务指标**: **用户获客成本 (CAC)** (`总活动成本 / 新增用户数`)。
+- **产品体验指标**: **活动配置时长** (从创建到发布一个活动的平均耗时)，**转化率** (`注册数 / 点击UV`)。
+- **(新增)** **平台采纳度指标**: **API调用成功率**，**已集成应用的客户数**。
+
+## 11. 未来规划 (Future Roadmap)
+
+- **Phase 2 (优化与拓展)**:
+    - **A/B 测试框架**: 支持对活动文案、奖励机制进行分组测试，科学优化转化率。
+    - **更多奖励类型**: 引入实物、话费、现金等更多奖励选项。
+    - **与社交平台集成**: 优化在微信、微博等平台的分享体验。
+- **Phase 3 (智能化与平台化)**:
+    - **智能推荐**: 基于用户画像，向最有可能参与活动的用户进行智能推送。
+    - **与CRM/MA工具深度集成**: 实现用户标签和数据的双向同步。
+    - **开放平台**: 允许第三方开发者基于本系统开发自定义的活动插件。
--- a/docs/api.md
+++ b/docs/api.md
@@ -0,0 +1,99 @@
+# API 文档
+
+本文档详细说明了活动管理和API密钥管理相关的API端点。
+
+## 1. 活动管理 (Activities)
+
+### 1.1 创建活动
+
+- **Endpoint**: `POST /api/v1/activities`
+- **描述**: 创建一个新的营销活动。
+- **请求体**: `application/json`
+
+  ```json
+  {
+    "name": "春季特惠活动",
+    "startTime": "2025-03-01T10:00:00+08:00",
+    "endTime": "2025-03-31T23:59:59+08:00"
+  }
+  ```
+
+- **成功响应 (201 Created)**:
+
+  ```json
+  {
+    "id": 1,
+    "name": "春季特惠活动",
+    "startTime": "2025-03-01T10:00:00+08:00",
+    "endTime": "2025-03-31T23:59:59+08:00",
+    // ... 其他活动属性
+  }
+  ```
+
+- **失败响应**:
+  - `400 Bad Request`: 如果请求数据无效（例如，名称为空或结束时间早于开始时间）。
+
+### 1.2 更新活动
+
+- **Endpoint**: `PUT /api/v1/activities/{id}`
+- **描述**: 更新一个已存在的活动。
+- **路径参数**: `id` (long) - 活动的唯一标识符。
+- **请求体**: `application/json`
+
+  ```json
+  {
+    "name": "春季特惠活动（升级版）",
+    "startTime": "2025-03-01T10:00:00+08:00",
+    "endTime": "2025-04-15T23:59:59+08:00"
+  }
+  ```
+
+- **成功响应 (200 OK)**: 返回更新后的活动对象。
+- **失败响应**:
+  - `400 Bad Request`: 如果请求数据无效。
+  - `404 Not Found`: 如果指定的 `id` 不存在。
+
+### 1.3 获取活动详情
+
+- **Endpoint**: `GET /api/v1/activities/{id}`
+- **描述**: 获取指定ID的活动详情。
+- **路径参数**: `id` (long) - 活动的唯一标识符。
+- **成功响应 (200 OK)**: 返回活动对象。
+- **失败响应**:
+  - `404 Not Found`: 如果指定的 `id` 不存在。
+
+## 2. API密钥管理 (API Keys)
+
+### 2.1 创建API密钥
+
+- **Endpoint**: `POST /api/v1/api-keys`
+- **描述**: 为指定的活动创建一个新的API密钥。密钥仅在本次响应中明文返回，请立即保存。
+- **请求体**: `application/json`
+
+  ```json
+  {
+    "activityId": 1,
+    "name": "我的第一个密钥"
+  }
+  ```
+
+- **成功响应 (201 Created)**:
+
+  ```json
+  {
+    "apiKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
+  }
+  ```
+
+- **失败响应**:
+  - `400 Bad Request`: 如果请求数据无效（例如，`activityId` 或 `name` 为空）。
+  - `404 Not Found`: 如果 `activityId` 不存在。
+
+### 2.2 吊销API密钥
+
+- **Endpoint**: `DELETE /api/v1/api-keys/{id}`
+- **描述**: 吊销（删除）一个API密钥。
+- **路径参数**: `id` (long) - API密钥的唯一标识符。
+- **成功响应 (204 No Content)**: 无响应体。
+- **失败响应**:
+  - `404 Not Found`: 如果指定的 `id` 不存在。
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,64 @@
+# 技术架构说明: “蚊子”传播系统
+
+## 1. 概述
+
+本文档旨在为“蚊子”传播系统定义清晰、统一的技术架构，以指导后续的开发和运维工作。项目将遵循前后端分离的现代Web应用架构模式。
+
+- **后端**: 基于 **Spring Boot 3** 的微服务架构，负责所有业务逻辑、数据处理和API输出。
+- **前端**: 基于 **Vue 3** 的单页面应用（SPA），负责提供给“活动管理员”的管理后台界面和“终端参与者”的用户中心界面。
+
+## 2. 技术选型 (Tech Stack)
+
+| 领域 | 技术选型 | 备注 |
+| :--- | :--- | :--- |
+| **后端框架** | Spring Boot 3.x | 使用Java 17, 提供强大的生态和快速开发能力。 |
+| **前端框架** | Vue 3.x | 使用 Composition API 和 `<script setup>` 语法，提升代码可读性和复用性。 |
+| **构建工具** | Maven (后端), Vite (前端) | Vite提供极速的开发服务器和构建体验。 |
+| **数据库** | PostgreSQL | 功能强大的开源关系型数据库，支持JSON等复杂数据类型。 |
+| **数据访问** | Spring Data JPA / Hibernate | 简化数据库操作，实现ORM。 |
+| **API安全** | Spring Security | 处理API Key认证及未来可能的用户认证。 |
+| **消息队列** | RabbitMQ | 用于奖励发放等异步任务处理，通过Spring AMQP集成。 |
+| **缓存** | Redis | 用于缓存热点数据，如排行榜。 |
+| **UI组件库** | Element Plus | 成熟、丰富的Vue 3组件库。 |
+| **前端状态管理**| Pinia | Vue 3官方推荐的状态管理库，轻量且直观。 |
+| **API客户端** | Axios | 成熟的HTTP客户端，用于前后端交互。 |
+
+## 3. 系统架构图
+
+```mermaid
+graph TD
+    subgraph 用户端
+        A[浏览器/移动端] --> B{前端应用 (Vue 3)};
+    end
+
+    subgraph 服务端
+        B --> C{API网关/负载均衡};
+        C --> D[后端主应用 (Spring Boot)];
+        D -- JDBC --> E[PostgreSQL数据库];
+        D -- AMQP --> F[RabbitMQ消息队列];
+        D -- Redis Client --> G[Redis缓存];
+        H[奖励发放Worker] -- AMQP --> F;
+    end
+
+    subgraph 第三方服务
+        D --> I{第三方奖励系统 API};
+        J[客户应用] --> C;
+    end
+```
+
+## 4. 核心模块设计思路
+
+- **活动管理 (Activity Management)**: 后端提供完整的CRUD API，前端通过表单驱动，实现活动的动态配置。
+- **数据分析 (Data Analytics)**: 后端通过定时任务（`@Scheduled`）预先计算和聚合每日统计数据，存入统计表，避免前端查询时实时计算的性能瓶颈。
+- **用户端体验 (User Experience)**: 
+    - **短链接**: 后端提供一个专门的服务，负责长链接到短链接的转换和重定向。
+    - **海报生成**: 后端使用Java图像处理库（如 `thumbnailator`）生成海报，并设计降级方案，在高负载时仅返回数据由前端`canvas`进行渲染。
+- **系统集成 (System Integration)**: 
+    - **回调API**: 通过Spring Security的过滤器链实现`X-API-Key`的认证和速率限制。
+    - **异步奖励**: 采用消息队列实现核心业务（回调处理）与非核心业务（奖励发放）的解耦，提高系统的响应速度和可靠性。
+
+## 5. 部署与运维 (DevOps)
+
+- **容器化**: 前后端应用都将被打包成Docker镜像。
+- **CI/CD**: 设立GitHub Actions工作流，在代码推送到主分支时，自动运行测试、构建Docker镜像并推送到镜像仓库。
+- **部署**: 推荐使用Kubernetes (K8s) 或云服务商提供的容器服务（如 AWS ECS, Google Cloud Run）进行部署，以实现弹性伸缩和高可用性。
--- a/docs/data-model.md
+++ b/docs/data-model.md
@@ -0,0 +1,93 @@
+# 数据模型设计
+
+本文档描述了项目核心领域的数据模型和数据库表结构。
+
+## 1. 领域模型 (Domain Models)
+
+### 1.1 Activity.java
+
+代表一个营销活动。这是活动管理功能的核心实体。
+
+- `id` (Long): 活动的唯一标识符，主键。
+- `name` (String): 活动的名称。
+- `startTime` (ZonedDateTime): 活动的开始时间。
+- `endTime` (ZonedDateTime): 活动的结束时间。
+- `targetUserIds` (Set<Long>): 允许参加活动的用户ID集合。如果为空，则表示对所有用户开放。
+- `rewardTiers` (List<RewardTier>): 奖励规则的层级列表。
+- `rewardMode` (RewardMode): 奖励模式（`CUMULATIVE` - 叠加, `DIFFERENTIAL` - 补差）。
+- `multiLevelRewardRules` (List<MultiLevelRewardRule>): 多级邀请奖励规则。
+
+### 1.2 ApiKey.java
+
+代表一个API密钥，用于授权外部系统访问特定活动的API。
+
+- `id` (Long): 密钥的唯一标识符，主键。
+- `activityId` (Long): 关联的活动ID。
+- `name` (String): 方便用户识别的密钥名称。
+- `keyHash` (String): 经过哈希加盐处理的API密钥值。
+- `salt` (String): 用于哈希计算的盐值，Base64编码存储。
+
+## 2. 数据库表设计 (Database Schema)
+
+### 2.1 activities 表
+
+由 `V1__Create_activities_table.sql` 创建。
+
+```sql
+CREATE TABLE activities (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    start_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    end_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    -- 其他字段将根据需求添加
+);
+```
+
+### 2.2 activity_rewards 表
+
+由 `V2__Create_activity_rewards_table.sql` 创建。
+
+```sql
+CREATE TABLE activity_rewards (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    activity_id BIGINT NOT NULL,
+    threshold INT NOT NULL,
+    reward_type VARCHAR(50) NOT NULL,
+    points INT,
+    coupon_batch_id VARCHAR(255),
+    FOREIGN KEY (activity_id) REFERENCES activities(id)
+);
+```
+
+### 2.3 multi_level_reward_rules 表
+
+由 `V3__Create_multi_level_reward_rules_table.sql` 创建。
+
+```sql
+CREATE TABLE multi_level_reward_rules (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    activity_id BIGINT NOT NULL,
+    level INT NOT NULL,
+    decay_coefficient DECIMAL(5, 4) NOT NULL,
+    FOREIGN KEY (activity_id) REFERENCES activities(id),
+    UNIQUE (activity_id, level)
+);
+```
+
+### 2.4 api_keys 表
+
+由 `V4__Create_api_keys_table.sql` 创建。
+
+```sql
+CREATE TABLE api_keys (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    key_hash VARCHAR(255) NOT NULL UNIQUE,
+    salt VARCHAR(255) NOT NULL,
+    created_at TIMESTAMP NOT NULL,
+    revoked_at TIMESTAMP NULL,
+    last_used_at TIMESTAMP NULL
+);
+
+CREATE INDEX idx_api_keys_key_hash ON api_keys(key_hash);
+```
--- a/docs/tech-choices.md
+++ b/docs/tech-choices.md
@@ -0,0 +1,35 @@
+# 技术选型与决策
+
+本文档记录了项目在开发过程中所做的主要技术选型和架构决策，以便团队成员理解其背后的原因。
+
+## 1. 核心框架与语言
+
+- **Java 17**: 选用 Java 17 是因为它是一个长期支持（LTS）版本，提供了现代化的语言特性（如 Records, Sealed Classes 等），并拥有稳定的生态系统。
+- **Spring Boot 3**: 作为业界主流的Java开发框架，Spring Boot 极大地简化了配置和部署，通过其强大的自动配置和依赖管理能力，使我们能快速构建健壮的、生产级的Web服务。
+- **Maven**: 作为项目管理和构建工具，Maven 提供了标准的项目结构、强大的依赖管理和一致的构建流程。
+
+## 2. API与Web层
+
+- **RESTful API**: 我们选择构建RESTful风格的API，这是当前Web服务的标准实践，具有无状态、易于理解和前后端分离的优点。
+- **DTO (Data Transfer Object)**: 在Controller层，我们引入了DTO模式（例如 `CreateActivityRequest`）。
+  - **决策依据**: 将API的请求/响应结构与内部的领域模型（Domain Model）解耦。这样做的好处是：
+    1.  **API稳定性**: 内部领域模型的变化不会直接影响外部API的结构。
+    2.  **安全性**: 可以避免意外暴露领域模型中的敏感字段。
+    3.  **专用性**: 可以为特定的API端点定制数据结构，使其更清晰、更高效。
+- **Bean Validation**: 通过引入 `spring-boot-starter-validation` 并在DTO上使用 `@Valid` 和相关约束注解（如 `@NotBlank`），我们在Controller层实现了声明式的输入验证。这是一种标准的、非侵入性的验证方式，能保持业务逻辑的纯净。
+
+## 3. 数据库与持久化
+
+- **Flyway**: 用于数据库迁移管理。它通过版本化的SQL脚本来管理数据库结构演进，确保了在任何环境下（开发、测试、生产）数据库结构的一致性和可追溯性。
+- **H2 Database (用于测试)**: H2是一个轻量级的内存数据库，非常适合在单元测试和集成测试中使用。它启动速度快，无需外部依赖，可以确保测试环境的纯净和可重复性。
+- **PostgreSQL (用于生产)**: 在 `pom.xml` 中预先定义了依赖。PostgreSQL 是一个功能强大、稳定可靠的开源关系型数据库，适用于生产环境。
+
+## 4. 安全
+
+- **API密钥存储**: 采用哈希加盐（Salted Hashing）的方式存储API密钥。
+  - **决策依据**: 直接在数据库中存储明文API密钥是极不安全的。通过为每个密钥生成一个唯一的盐（Salt），并将其与密钥组合后进行哈希（SHA-256），我们只存储盐和哈希值。即使数据库被泄露，攻击者也无法直接反推出原始密钥，大大提高了安全性。
+
+## 5. 异常处理
+
+- **自定义异常**: 我们创建了业务特定的异常类，如 `ActivityNotFoundException` 和 `ApiKeyNotFoundException`。
+  - **决策依据**: 这使得代码的意图更清晰，并且可以利用 `@ResponseStatus` 注解将特定的业务异常直接映射到HTTP状态码（如 `404 Not Found`），简化了全局异常处理逻辑。
--- a/docs/test-plan.md
+++ b/docs/test-plan.md
@@ -0,0 +1,37 @@
+# 测试方案
+
+本文档概述了针对后端API所采用的测试策略、工具和覆盖范围。
+
+## 1. 测试策略
+
+我们采用分层测试的策略，以确保代码质量和功能正确性。
+
+### 1.1 单元测试 (Unit Tests)
+
+- **目标**: 验证单个服务（Service）或组件内部的业务逻辑是否正确。
+- **范围**: 主要针对 `ActivityService` 中的公共方法。
+- **实现**: 测试用例位于 `ActivityServiceTest.java` 中。在此层面，所有外部依赖（如数据库、其他服务）都应被模拟（Mock），以保证测试的独立性和速度。
+- **覆盖场景**:
+  - 业务规则校验（如活动时间合法性）。
+  - 边界条件（如各种奖励计算的临界值）。
+  - 异常路径（如当依赖的服务失败时，是否抛出预期的异常）。
+
+### 1.2 集成测试 (Integration Tests)
+
+- **目标**: 验证从API端点到服务层的完整请求-响应流程是否通畅。
+- **范围**: 主要针对 `controller` 包下的所有API控制器。
+- **实现**: 测试用例位于 `ActivityControllerTest.java` 和 `ApiKeyControllerTest.java` 中。我们使用 Spring Boot 的 `@WebMvcTest` 配合 `MockMvc` 来实现。
+  - `@WebMvcTest` 提供了一个轻量级的测试环境，只加载Web层相关的Bean（如Controller, `ObjectMapper`等），而不加载完整的Spring应用上下文，从而加快测试速度。
+  - `ActivityService` 在此层被 `@MockBean` 模拟，使我们能专注于测试Controller的行为，如URL映射、HTTP方法、请求/响应的序列化/反序列化、参数验证和正确的HTTP状态码返回。
+- **覆盖场景**:
+  - **成功路径**: 验证有效的请求是否能被正确处理并返回 `2xx` 状态码和预期的响应体。
+  - **验证失败路径**: 验证无效的请求体（如字段为空）是否会触发Bean Validation并返回 `400 Bad Request`。
+  - **资源未找到路径**: 验证请求一个不存在的资源（如 `GET /api/v1/activities/999`）是否返回 `404 Not Found`。
+
+## 2. 测试工具
+
+- **JUnit 5**: Java世界中最主流的测试框架。
+- **Mockito**: 用于创建和配置模拟对象（Mock），以实现测试的隔离。
+- **Spring Boot Test**: 提供了与Spring生态无缝集成的测试支持，包括 `@SpringBootTest`, `@WebMvcTest`, `@MockBean` 等核心功能。
+- **MockMvc**: 用于在不启动真实HTTP服务器的情况下，对Spring MVC控制器进行端到端的调用和验证。
+- **H2 Database**: 一个内存数据库，用于在运行单元测试时快速执行数据库迁移（Flyway），确保SQL脚本的语法正确性。