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

specs/001-activity-management/plan.md

@@ -0,0 +1,86 @@
+# 实施计划: 001 - 活动管理
+
+本文档为“活动管理”功能规格的技术实施计划。
+
+## 1. 总体思路
+
+采用前后端分离的架构。后端负责提供RESTful API，处理所有业务逻辑和数据持久化。前端负责提供一个响应式的、用户友好的管理界面，供管理员创建和配置活动。
+
+## 2. 后端开发任务 (Backend Tasks)
+
+### 2.1. 数据库 Schema 设计
+
+需要设计以下数据表来支持活动管理功能：
+
+- **`activities` (活动表)**
+    - `id` (主键)
+    - `name` (活动名称, string)
+    - `start_time_utc` (开始时间, datetime)
+    - `end_time_utc` (结束时间, datetime)
+    - `target_users_config` (目标用户配置, json) - 存储用户ID列表或标签
+    - `page_content_config` (页面内容配置, json) - 存储文案和图片URL
+    - `reward_calculation_mode` (奖励计算模式, enum: `delta`, `cumulative`)
+    - `status` (活动状态, enum: `draft`, `active`, `ended`)
+
+- **`activity_rewards` (阶梯奖励规则表)**
+    - `id` (主键)
+    - `activity_id` (外键, 关联 `activities`)
+    - `invite_threshold` (邀请人数阈值, integer)
+    - `reward_type` (奖励类型, enum: `points`, `coupon`)
+    - `reward_value` (奖励值, string) - 积分数量或优惠券批次ID
+    - `skip_validation` (跳过校验, boolean)
+
+- **`multi_level_reward_rules` (多级奖励规则表)**
+    - `id` (主键)
+    - `activity_id` (外键, 关联 `activities`)
+    - `level` (奖励层级, integer, e.g., 2, 3)
+    - `coefficient_percent` (衰减系数-百分比, integer)
+
+- **`api_keys` (API密钥表)**
+    - `id` (主键)
+    - `key_hash` (密钥的哈希值, string) - **绝不存储明文密钥**
+    - `scope_type` (范围类型, enum: `account`, `activity`)
+    - `scope_id` (范围ID, integer) - 对应账户ID或活动ID
+    - `created_at` (创建时间, datetime)
+    - `last_used_at` (最后使用时间, datetime, 可选)
+
+### 2.2. API Endpoint 设计
+
+设计以下RESTful API接口：
+
+- `POST /api/v1/activities`: **创建新活动**
+    - Request Body: 包含活动所有配置信息。
+    - Response: 返回创建成功的活动详情。
+
+- `PUT /api/v1/activities/{id}`: **更新活动**
+    - Request Body: 包含需要更新的活动配置。
+    - Response: 返回更新后的活动详情。
+
+- `GET /api/v1/activities/{id}`: **获取活动详情**
+    - Response: 返回指定ID的活动完整配置。
+
+- `POST /api/v1/api-keys`: **创建API密钥**
+    - Request Body: `{ scope_type, scope_id }`
+    - Response: 返回新生成的API Key (仅此一次)。
+
+- `DELETE /api/v1/api-keys/{id}`: **吊销API密钥**
+    - Response: 成功状态码。
+
+## 3. 前端开发任务 (Frontend Tasks)
+
+### 3.1. UI 组件设计
+
+需要开发一系列Vue组件来构建活动创建/编辑表单：
+
+- **`ActivityEditor.vue`**: 主表单容器，管理整个活动配置的状态。
+- **`GeneralSettings.vue`**: 用于配置活动名称、时间（需处理UTC与本地时间的转换）。
+- **`TargetingEditor.vue`**: 用于配置目标用户，支持文本输入或文件上传。
+- **`PageContentEditor.vue`**: 富文本编辑器及图片上传/链接组件（处理30MB大小限制和格式校验）。
+- **`RewardRuleEditor.vue`**: 核心组件，用于配置阶梯奖励和多级奖励，包含奖励模式切换和计算示例的实时预览。
+- **`ApiKeyManager.vue`**: 用于展示API密钥列表（不显示密钥本身）、生成新密钥（弹窗显示一次）、吊销密钥。
+
+### 3.2. 状态管理与API集成
+
+- 使用 `Pinia` 等状态管理库来管理复杂的表单数据。
+- 创建一个API客户端模块 (`apiClient.js`)，封装所有对后端API的请求。
+- 在组件中调用API，并处理加载（loading）和错误（error）状态，提供流畅的用户体验。

specs/001-activity-management/spec.md

@@ -0,0 +1,33 @@
+# 功能规范: 001 - 活动管理
+
+本文档定义了“蚊子”传播系统中与“活动管理”相关的功能。
+
+## 1. 关键实体 (Key Entities)
+
+- **活动 (Activity)**: 营销活动的核心载体，包含生命周期、规则、奖励等信息。
+- **用户 (User)**: 系统的参与者，分为`管理员`和`传播者`两种角色。
+- **奖励 (Reward)**: 用于激励用户的物品，V1.0支持`积分`和`优惠券`。
+- **邀请 (Invitation)**: 用户之间的推荐关系，是构成裂变网络的基础。
+- **API密钥 (API Key)**: 用于第三方系统与本系统认证的凭证。
+- **追踪ID (Tracking ID)**: 标识单次邀请-注册流程的唯一ID。
+
+## 2. 用户故事与验收标准 (User Stories & Acceptance Criteria)
+
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **作为管理员**，我希望能创建一个有时限的邀请活动，以便于策划和管理营销节奏。 | 1. 可设定活动名称、开始时间、结束时间。<br>2. 活动到期后自动停止。<br>3. **(澄清)** 当结束时间早于开始时间时，系统应阻止保存并给出明确提示。 | **高** |
+| **作为管理员**，我希望可以设定活动仅对特定用户群体开放，以便于进行精准营销。 | 1. 可配置活动参与的用户标签或ID列表。<br>2. **(澄清)** 非目标用户访问活动链接时，应被重定向到一个友好的引导页面（如“该活动仅对部分用户开放”）。 | **高** |
+| **作为管理员**，我希望可以自定义邀请页面的文案和图片，以匹配不同的活动主题和品牌风格。 | 1. 支持富文本编辑器修改文案。<br>2. 支持上传/链接图片。<br>3. **(澄清)** 上传图片大小超过30MB或格式不被支持时，应给出明确提示：“暂不支持，请重新上传”。 | **高** |
+| **作为管理员**，我希望设置阶梯式奖励规则，以便激励用户完成更高挑战。 | 1. 可配置多个奖励档位，如“邀请3人得A奖励，邀请10人得B奖励”。<br>2. **(澄清)** 管理员可选择奖励计算模式：“补差”（默认）或“叠加”。 | **高** |
+| **作为管理员**，我希望设置带有衰减系数的多级邀请奖励，以鼓励用户发展下线，扩大传播范围。 | 1. 可配置奖励层级（最多如3级）。<br>2. 可配置每一级奖励的比例或固定值。<br>3. **(澄清)** 衰减系数默认为百分比，设置界面需提供一个实时计算示例以便查看。 | **高** |
+| **作为管理员**，我希望奖励类型可以支持积分和优惠券，以适应不同运营场景。 | 1. 可选择奖励类型为积分或优惠券。<br>2. 可填写对应的积分数量或优惠券批次ID。<br>3. **(澄清)** 系统默认会校验优惠券批次ID的有效性，管理员可选择跳过校验。 | **高** |
+| **作为管理员**，我希望能为我的应用生成和管理API密钥，以便安全地将我的系统与“蚊子”系统对接。 | 1. **(澄清)** 后台提供API Key生成功能，密钥仅在生成时显示一次，后续不可查看，只能重置。<br>2. 密钥与具体活动或账户关联。 | **高** |
+
+## 3. 澄清与边缘场景 (Clarifications & Edge Cases)
+
+- **时区**: 所有时间均以 **UTC** 为准进行存储和计算，在前端展示时，应根据用户浏览器设置转换为本地时间。
+- **阶梯奖励模式**: 
+    - **补差 (默认)**: 用户达到更高奖励等级时，获得的奖励为该等级奖励与已获得奖励的差值。
+    - **叠加**: 用户达到更高奖励等级时，直接获得该等级的全部奖励，不扣除低等级奖励。
+- **多级奖励计算示例**: 在设置界面需提供一个实时计算示例，例如：`原始奖励: 100积分, L2衰减: 50%, L3衰减: 20% -> L2获得: 50积分, L3获得: 20积分`。
+- **API密钥范围**: 密钥默认为“**活动级**”。同时，管理员可在账户设置中生成“**账户级**”密钥，并在创建活动时选择使用账户级密钥或创建新的活动级密钥。

specs/001-activity-management/tasks.md

@@ -0,0 +1,38 @@
+# 开发任务列表: 001 - 活动管理
+
+基于实施计划，为“活动管理”功能分解出以下开发任务。
+
+## 后端 (Backend)
+
+### 数据库 (Database)
+
+- [x] **BE-DB-01**: 创建 `activities` 表的数据库迁移（migration）脚本。
+- [x] **BE-DB-02**: 创建 `activity_rewards` 表的数据库迁移脚本。
+- [x] **BE-DB-03**: 创建 `multi_level_reward_rules` 表的数据库迁移脚本。
+- [x] **BE-DB-04**: 创建 `api_keys` 表的数据库迁移脚本，确保 `key_hash` 字段已建立索引。
+
+### API & 业务逻辑
+
+- [x] **BE-API-01**: 实现创建活动 (`POST /api/v1/activities`) 的业务逻辑，包括输入验证。
+- [x] **BE-API-02**: 实现更新活动 (`PUT /api/v1/activities/{id}`) 的业务逻辑。
+- [x] **BE-API-03**: 实现获取活动详情 (`GET /api/v1/activities/{id}`) 的业务逻辑。
+- [x] **BE-API-04**: 实现API密钥的创建 (`POST /api/v1/api-keys`) 与安全存储（哈希加盐）。
+- [x] **BE-API-05**: 实现API密钥的吊销 (`DELETE /api/v1/api-keys/{id}`) 逻辑。
+- [x] **BE-TEST-01**: 为所有 `activities` 和 `api-keys` 相关的API Endpoints 编写单元测试和集成测试。
+
+## 前端 (Frontend)
+
+### UI 组件
+
+- [ ] **FE-UI-01**: 开发 `ActivityEditor` 核心布局组件。
+- [ ] **FE-UI-02**: 开发 `GeneralSettings` 组件，包含名称、时间选择器和客户端验证逻辑。
+- [ ] **FE-UI-03**: 开发 `TargetingEditor` 组件，用于配置目标用户。
+- [ ] **FE-UI-04**: 开发 `PageContentEditor` 组件，集成富文本编辑器和图片上传功能（包含客户端校验）。
+- [ ] **FE-UI-05**: 开发 `RewardRuleEditor` 组件，处理复杂的阶梯和多级奖励配置，并提供实时计算预览。
+- [ ] **FE-UI-06**: 开发 `ApiKeyManager` 组件，包括密钥列表（屏蔽密钥）、生成和吊销功能。
+
+### 状态管理与集成
+
+- [ ] **FE-STATE-01**: 配置 Redux/Zustand store，用于管理 `ActivityEditor` 的全局状态。
+- [ ] **FE-API-01**: 创建一个API客户端服务，用于封装所有与后端交互的fetch请求。
+- [ ] **FE-INT-01**: 将API客户端服务集成到所有相关UI组件中，并妥善处理加载（Loading）、错误（Error）和成功（Success）的UI状态反馈。