niuniu/wenzi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f815fdf5b846a17cd88e950489e9762e11212db1
wenzi/docs/PRD.md
Your Name 91a0b77f7a test(cache): 修复CacheConfigTest边界值测试 
- 修改 shouldVerifyCacheManager_withMaximumIntegerTtl 为 shouldVerifyCacheManager_withMaximumAllowedTtl
- 使用正确的最大TTL值（10080分钟，7天）而不是 Integer.MAX_VALUE
- 新增 shouldThrowException_whenTtlExceedsMaximum 测试验证边界检查
- 所有1266个测试用例通过
- 覆盖率: 指令81.89%, 行88.48%, 分支51.55%

docs: 添加项目状态报告
- 生成 PROJECT_STATUS_REPORT.md 详细记录项目当前状态
- 包含质量指标、已完成功能、待办事项和技术债务
2026-03-02 13:31:54 +08:00

14 KiB
Raw Blame History

产品需求文档 (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. 可设定活动名称、开始时间、结束时间。
2. 活动到期后自动停止。		 高
作为管理员，我希望可以设定活动仅对特定用户群体开放，以便于进行精准营销。 1. 可配置活动参与的用户标签或ID列表。 高
作为管理员，我希望可以自定义邀请页面的文案和图片，以匹配不同的活动主题和品牌风格。 1. 支持富文本编辑器修改文案。
2. 支持上传/链接图片。		 高
作为管理员，我希望设置阶梯式奖励规则，以便激励用户完成更高挑战。 1. 可配置多个奖励档位，如“邀请3人得A奖励，邀请10人得B奖励”。 高
作为管理员，我希望设置带有衰减系数的多级邀请奖励，以鼓励用户发展下线，扩大传播范围。 1. 可配置奖励层级（最多如3级）。
2. 可配置每一级奖励的比例或固定值。		 高
作为管理员，我希望奖励类型可以支持积分和优惠券，以适应不同运营场景。 1. 可选择奖励类型为积分或优惠券。
2. 可填写对应的积分数量或优惠券批次ID。		 高
(新增) 作为管理员，我希望能为我的应用生成和管理API密钥，以便安全地将我的系统与“蚊子”系统对接。 1. 后台提供API Key生成、查看、重置和禁用的功能。
2. 密钥与具体活动或账户关联。		 高

6.2. 数据与分析

用户故事 验收标准 优先级
作为管理员，我希望在后台看到活动的核心数据仪表盘，以便实时监控活动健康度。 1. 仪表盘展示PV, UV, 参与人数, 新增注册数, K因子, CAC。
2. 数据支持按天查看。		 高
作为管理员，我希望以网络图的形式查看用户裂变路径，以便快速定位关键传播节点（KOL）。 1. 图形化展示用户间的邀请关系。
2. 节点可点击，并显示该用户的关键信息（如直接/间接邀请数）。		 高
作为管理员，我希望能看到一个按邀请数排序的“超级传播者”榜单，以便对他们进行额外奖励或运营。 1. 榜单展示用户昵称、头像、总邀请人数。
2. 支持导出榜单。		 中

6.3. 用户端体验

用户故事 验收标准 优先级
作为参与者，我希望能方便地获取专属的邀请链接和海报，以便分享给朋友。 1. 页面显著位置提供“一键复制链接”按钮。
2. 可生成带专属二维码的分享海报。		 高
作为参与者，我希望在个人中心看到我的邀请记录和奖励明细，以便了解我的贡献和收益。 1. 列表展示我邀请的好友（及其状态，如已注册）。
2. 列表展示我获得的每一笔奖励。		 高

6.4. 系统能力与集成

用户故事 验收标准 优先级
(新增) 作为第三方应用，当一个新用户通过邀请链接完成注册后，我希望能通过API通知“蚊子”系统，以便为邀请者记功和发放奖励。 1. 提供一个安全的、基于API Key认证的回调API。
2. API需接收一个在邀请链接中传递的唯一追踪ID。
3. API有清晰的成功/失败返回码。		 高
作为系统，需要能初步识别和拦截刷单行为，以保证活动的公平性和数据准确性。 1. 基于IP、设备指纹等信息进行基础的防刷校验。
2. 对回调API进行速率限制和来源IP校验。		 高
作为系统，需要能自动完成奖励发放，以降低运营成本和提升用户体验。 1. 可通过API与内部账户系统打通，完成积分/优惠券发放。 中

6.5. 管理后台（Admin 前端演示版）

用户故事 验收标准 优先级
作为管理员，我希望管理后台具备演示模式，以便在无后端的情况下预览全流程。 1. 提供“一键登录（演示管理员）”。
2. 未登录自动进入演示模式。
3. 演示数据不依赖后端。		 高
作为管理员，我希望后台支持角色权限与审批流，以便控制权限变更风险。 1. 角色分为管理员/运营/只读。
2. 角色变更需提交审批并记录结果。
3. 操作进入审计日志。		 高
作为运营，我希望在后台完成活动全流程闭环，以便提升执行效率。 1. 支持创建→配置→上线/暂停/下线。
2. 展示活动指标与榜单预览。
3. 支持导出活动摘要与明细。		 高
作为管理员，我希望列表支持搜索/筛选/分页/批量操作，以提升日常操作效率。 1. 支持名称/状态/时间范围筛选。
2. 批量启用/禁用/发放/审批等操作。		 高
作为管理员，我希望可以查看审计日志与通知中心，以便追踪关键操作与异常。 1. 审计日志可搜索、导出。
2. 通知支持筛选与批量已读。		 中
作为管理员，我希望在后台查看活动邀请用户列表，以便分析邀请效果。 1. 支持按活动选择查看邀请用户。
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工具深度集成: 实现用户标签和数据的双向同步。
    • 开放平台: 允许第三方开发者基于本系统开发自定义的活动插件。
Reference in New Issue View Git Blame Copy Permalink