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

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密钥范围**: 密钥默认为“**活动级**”。同时，管理员可在账户设置中生成“**账户级**”密钥，并在创建活动时选择使用账户级密钥或创建新的活动级密钥。