# 产品需求文档 (PRD) - “蚊子”传播系统

**版本**: 1.3 (已优化)
**日期**: 2026年2月6日

---

## 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与内部账户系统打通，完成积分/优惠券发放。 | **中** |

### 6.5. 管理后台（Admin 前端演示版）
| 用户故事 | 验收标准 | 优先级 |
| :--- | :--- | :--- |
| **作为管理员**，我希望管理后台具备演示模式，以便在无后端的情况下预览全流程。 | 1. 提供“一键登录（演示管理员）”。<br>2. 未登录自动进入演示模式。<br>3. 演示数据不依赖后端。 | **高** |
| **作为管理员**，我希望后台支持角色权限与审批流，以便控制权限变更风险。 | 1. 角色分为管理员/运营/只读。<br>2. 角色变更需提交审批并记录结果。<br>3. 操作进入审计日志。 | **高** |
| **作为运营**，我希望在后台完成活动全流程闭环，以便提升执行效率。 | 1. 支持创建→配置→上线/暂停/下线。<br>2. 展示活动指标与榜单预览。<br>3. 支持导出活动摘要与明细。 | **高** |
| **作为管理员**，我希望列表支持搜索/筛选/分页/批量操作，以提升日常操作效率。 | 1. 支持名称/状态/时间范围筛选。<br>2. 批量启用/禁用/发放/审批等操作。 | **高** |
| **作为管理员**，我希望可以查看审计日志与通知中心，以便追踪关键操作与异常。 | 1. 审计日志可搜索、导出。<br>2. 通知支持筛选与批量已读。 | **中** |
| **作为管理员**，我希望在后台查看活动邀请用户列表，以便分析邀请效果。 | 1. 支持按活动选择查看邀请用户。<br>2. 支持从后端接口拉取数据。 | **中** |

***技术流程说明***: *第三方注册回调的数据流如下：*
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后台管理功能。
    - **(新增)** Admin 前端演示模式（RBAC/审批/审计/批量操作）。
    - 标准化的用户端邀请页面。
    - **(新增)** 用于确认注册成功的服务端回调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页面承载。
    - **(新增)** Admin 真实鉴权与后端权限校验（当前仅前端演示）。

## 8. 风险与假设 (Risks and Assumptions)

- **假设**:
    - **用户分享意愿**: 假设在合理的奖励激励下，用户愿意主动分享。
    - **技术可行性**: 假设内部账户系统有稳定、可用的API用于发放奖励。
    - **(新增)** **客户集成能力**: 假设客户的开发团队有能力对接我们的回调API。
- **风险**:
    - **防刷风险**: 简单的防刷机制可能被专业羊毛党绕过，导致活动成本失控。
    - **数据准确性风险**: 高并发下，数据追踪可能存在延迟或丢失，影响分析和奖励发放。
    - **用户隐私风险**: 邀请关系链涉及用户数据，需严格遵守隐私政策，否则可能引发法务风险。
    - **(新增)** **集成复杂性风险**: 如果API设计不佳或文档不清晰，可能导致客户集成失败或意愿降低，从而影响产品推广。

## 9. 非功能性需求 (Non-Functional Requirements)

- **性能**: 邀请链接的跳转响应时间应低于200ms。活动高峰期，核心API需支持至少500 QPS。
- **可扩展性**: 奖励模块、活动模板应设计为可插拔、可扩展的架构。
- **安全性**: 保护用户数据隐私，防止数据泄露；所有关键操作需有不可篡改的日志记录；对外开放的API必须有可靠的认证和授权机制。
- **易用性**: 管理后台应做到“无代码”配置，运营人员通过引导式表单即可完成90%的配置工作。
- **(新增)** **文档完备性**: 必须提供清晰、准确、对开发者友好的API文档，包含代码示例。
- **(新增)** **可演示性**: Admin 前端在无后端时可完整演示流程，避免空白页或崩溃。

## 10. 成功指标 (Success Metrics)

- **北极星指标**: **K-Factor** (每个参与用户平均带来的新用户数)。目标 > 1。
- **核心业务指标**: **用户获客成本 (CAC)** (`总活动成本 / 新增用户数`)。
- **产品体验指标**: **活动配置时长** (从创建到发布一个活动的平均耗时)，**转化率** (`注册数 / 点击UV`)。
- **(新增)** **平台采纳度指标**: **API调用成功率**，**已集成应用的客户数**。

## 11. 未来规划 (Future Roadmap)

- **Phase 2 (优化与拓展)**:
    - **A/B 测试框架**: 支持对活动文案、奖励机制进行分组测试，科学优化转化率。
    - **更多奖励类型**: 引入实物、话费、现金等更多奖励选项。
    - **与社交平台集成**: 优化在微信、微博等平台的分享体验。
    - **Admin 真实鉴权与权限中心**: 接入统一登录与后端权限校验。

## 安全与运维

- 缓存失效管理
  - 管理令牌：所有缓存失效接口需通过 `X-Admin-Token` 传入，服务端读取 `app.cache.admin-token` 进行校验。
  - 限流：对缓存失效接口按 IP 进行限流（默认每分钟 60 次，可通过 `app.cache.rate-limit-per-minute` 配置）。
  - 审计：对缓存清空与键失效操作记录 token 指纹与来源 IP（日志）。

- API Key 安全
  - 生成：仅返回一次明文；服务端使用 PBKDF2 + Salt 存储哈希，并保存 `key_prefix` 便于快速定位。
  - 校验：支持两种方式——按 ID 校验（`POST /api/v1/api-keys/{id}/use`）与仅凭明文校验（`POST /api/v1/api-keys/validate`）。成功更新 `last_used_at`；吊销后或错误密钥返回 401 `INVALID_API_KEY`。
  - 审计字段：`created_at / last_used_at / revoked_at`。

- 运行与构建
  - 构建与单测：`mvn -B -DskipTests=false clean verify`（集成覆盖率门禁）。
  - 运行（开发）：`mvn spring-boot:run`；生产建议以 `prod` profile 运行并配置外部 Redis/DB。
  - 关键配置：
    - `REDIS_HOST / REDIS_PORT`（生产）、`spring.redis.port`（测试嵌入式端口注入）。
    - `app.cache.admin-token`、`app.cache.rate-limit-per-minute`。
    - 数据源与 Flyway 迁移相关环境变量。
- **Phase 3 (智能化与平台化)**:
    - **智能推荐**: 基于用户画像，向最有可能参与活动的用户进行智能推送。
    - **与CRM/MA工具深度集成**: 实现用户标签和数据的双向同步。
    - **开放平台**: 允许第三方开发者基于本系统开发自定义的活动插件。