【Java项目-企悦抽】02-AI赋能产品需求规格说明书

声明：本文档AI辅助完成，内容仅供参考

✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨ 🎯 你正在阅读「Java项目-企悦抽」系列文章 🎯 ✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨

🔥 弹简特 个人主页

❄️ 个人专栏直通车：

• 🔌 接口测试从入门到跑路
• ☕ 一个后端的 JavaEE 续命指南
• 🛜 网络原理续命手册
• ☕ Java项目-轻聊

✨ 靠热爱去书写自己，靠勇敢去书写生活！ ✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨

🌟 博主简介:

文章目录：

• 企悦抽-产品需求规格说明书
• • 修订记录
  • 1. 引言
  • • 1.1 编写目的
    • 1.2 文档关系
  • 2. 系统概述
  • • 2.1 系统名称
    • 2.2 技术栈规格
    • 2.3 模块划分
  • 3. 系统架构规格
  • • 3.1 逻辑架构
    • 3.2 抽奖异步链路规格
    • 3.3 缓存规格
  • 4. 数据规格
  • • 4.1 数据库表
    • 4.2 枚举规格
    • 4.3 字段校验规格
    • 4.4 加密规格
  • 5. 功能规格详述
  • • 5.1 FR-001 ~ FR-005 用户与认证
    • • 5.1.1 注册（FR-001）
      • 5.1.2 发送验证码（FR-004）
      • 5.1.3 密码登录（FR-002）
      • 5.1.4 短信登录（FR-003）
      • 5.1.5 登录拦截（FR-005）
    • 5.2 FR-006 ~ FR-007 人员管理
    • • 5.2.1 创建普通用户（FR-006）
      • 5.2.2 用户列表（FR-007）
    • 5.3 FR-008 ~ FR-010 奖品管理
    • • 5.3.1 创建奖品（FR-008）
      • 5.3.2 奖品分页列表（FR-009）
      • 5.3.3 奖品全量列表（FR-010）
    • 5.4 FR-011 ~ FR-013 活动管理
    • • 5.4.1 创建活动（FR-011）
      • 5.4.2 活动列表（FR-012）
      • 5.4.3 活动详情（FR-013）
    • 5.5 FR-014 ~ FR-016 抽奖与结果
    • • 5.5.1 提交抽奖（FR-014）
      • 5.5.2 查询中奖记录（FR-015）
      • 5.5.3 抽奖大屏（FR-016）
    • 5.6 FR-017 ~ FR-018 通知
    • • 5.6.1 中奖邮件（FR-017）
      • 5.6.2 中奖短信（FR-018）
  • 6. 接口规格索引
  • 7. 前端页面规格
  • • 7.1 实现说明
    • 7.2 页面清单
    • 7.3 通用前端约定
  • 8. 状态机规格
  • • 8.1 状态扭转顺序
    • 8.2 抽奖正向扭转
    • 8.3 异常回滚
  • 9. 安全规格
  • 10. 异常与容错规格
  • • 10.1 MQ 重试
    • 10.2 死信队列
    • 10.3 校验失败静默返回
  • 11. 验收标准
  • • 11.1 功能验收
    • 11.2 非功能验收

企悦抽-产品需求规格说明书

修订记录

1. 引言

1.1 编写目的

本文档在 PRD 基础上，将产品需求转化为可实施、可验证的功能规格、数据规格、状态规则与验收标准，供研发与测试直接使用。

1.2 文档关系

PRD（为什么做、做什么）
↓
PRS（怎么做、做到什么标准） ← 本文档
↓
接口设计文档（接口级定义）
↓
接口测试需求文档（测试用例输入）

2. 系统概述

2.1 系统名称

• 产品名：企悦抽
• 工程名：lottery-system
• 默认端口（开发用）：8080

2.2 技术栈规格

2.3 模块划分

3. 系统架构规格

3.1 逻辑架构

3.2 抽奖异步链路规格

3.3 缓存规格

4. 数据规格

4.1 数据库表

4.2 枚举规格

用户身份 UserIdentityEnum

活动状态 ActivityStatusEnum

活动奖品状态 ActivityPrizeStatusEnum

活动用户状态 ActivityUserStatusEnum

奖品等级 ActivityPrizeTiersEnum

4.3 字段校验规格

4.4 加密规格

5. 功能规格详述

5.1 FR-001 ~ FR-005 用户与认证

5.1.1 注册（FR-001）

输入：name、mail、phoneNumber、password（管理员必填）、identity（ADMIN/NORMAL）

处理逻辑：

输出：{ userId }

页面：register.html；管理员后台创建时 admin=false&jumpList=true

5.1.2 发送验证码（FR-004）

输入：Query 参数 phone

处理逻辑：

输出：{ code:200, data:true }

5.1.3 密码登录（FR-002）

输入：loginName（手机/邮箱）、password、mandatoryIdentity（可选）

处理逻辑：

输出：{ token, identity }

5.1.4 短信登录（FR-003）

输入：loginMobile、verificationCode、mandatoryIdentity（可选）

处理逻辑：

5.1.5 登录拦截（FR-005）

白名单（无需 Token）：

• 静态资源 /**/*.html、/css/**、/js/**、/pic/** 等
• /**/login（含 /password/login、/message/login）
• /register
• /verification-code/send
• /winning-records/show

鉴权失败：HTTP 401，无 JSON Body

5.2 FR-006 ~ FR-007 人员管理

5.2.1 创建普通用户（FR-006）

与注册共用 /register，identity=NORMAL，不传密码。

5.2.2 用户列表（FR-007）

输入：Query identity（可选，ADMIN/NORMAL，空则全部）

输出：[{ userId, userName, identity }]

5.3 FR-008 ~ FR-010 奖品管理

5.3.1 创建奖品（FR-008）

Content-Type：multipart/form-data

处理：图片存本地 pic.local-path，文件名 UUID+后缀；imageUrl 存文件名

输出：奖品 ID（Long）

5.3.2 奖品分页列表（FR-009）

输入：currentPage（默认 1）、pageSize（默认 10）

输出：{ total, records:[{ prizeId, prizeName, description, price, imageUrl }] }

5.3.3 奖品全量列表（FR-010）

输出：[{ prizeId, prizeName }]

5.4 FR-011 ~ FR-013 活动管理

5.4.1 创建活动（FR-011）

输入：

{
"activityName": "string, 必填",
"description": "string, 必填",
"activityPrizeList": [
{ "prizeId": "long", "prizeAmount": "long", "prizeTiers": "FIRST_PRIZE|SECOND_PRIZE|THIRD_PRIZE" }
],
"activityUserList": [
{ "userId": "long", "userName": "string" }
]
}

校验：

• 奖品 ID、用户 ID 均存在于主表
• 参与人数 ≥ 奖品总数
• 奖品等级合法

事务：写 activity + activity_prize + activity_user，初始状态分别为 RUNNING、INIT、INIT

缓存：组装 ActivityDetailDTO 写入 Redis

输出：{ activityId }

5.4.2 活动列表（FR-012）

输出字段 valid：status == RUNNING 为 true

前端行为：

• valid=true → 「活动进行中，去抽奖」
• valid=false → 「活动已完成，查看中奖名单」

5.4.3 活动详情（FR-013）

输入：Query activityId

输出：

读取顺序：Redis → MySQL 多表组装 → 回写 Redis

5.5 FR-014 ~ FR-016 抽奖与结果

5.5.1 提交抽奖（FR-014）

输入：

{
"activityId": "long, 必填",
"prizeId": "long, 必填",
"winningTime": "Date, 必填",
"winnerList": [
{ "userId": "long, 必填", "userName": "string, 必填" }
]
}

同步行为：仅发送 RabbitMQ 消息，不做业务落库

MQ 消费校验（失败则 return 或回滚）：

• 活动、活动奖品存在
• 活动非 COMPLETED
• 奖品非 COMPLETED
• winnerList.size() == prizeAmount

5.5.2 查询中奖记录（FR-015）

输入：activityId（必填）、prizeId（可选）

逻辑：

• 无 prizeId：查活动维度全量
• 有 prizeId：查该奖品维度

读取：Redis → MySQL → 回写 Redis

免登录：在白名单中

5.5.3 抽奖大屏（FR-016）

URL 参数：activityId、activityName、valid（true/false）

权限：

• valid=true 且 localStorage user_identity=ADMIN：可抽奖
• valid=true 且非 ADMIN：弹窗提示，不可操作
• valid=false：直接展示全量中奖名单

刷新恢复：已抽完奖品（valid=false）点击开始 → 直接查 /winning-records/show?prizeId= 展示名单

分享：复制链接，附加 valid=false&hideButton=true，隐藏操作按钮

5.6 FR-017 ~ FR-018 通知

5.6.1 中奖邮件（FR-017）

触发：MQ 消费成功后，线程池异步执行

模板（实际代码）：

Hi，{winnerName}！
有个好消息要告诉你：你在【{activityName}】活动中，获得了{prizeTier中文}的惊喜福利：{prizeName}！
福利发放时间：{HH:mm:ss}，快来领取你的专属惊喜吧~

收件人：中奖用户邮箱

5.6.2 中奖短信（FR-018）

状态：V1.0 未实现，MqReceiver.sendMessage 仅打印日志

6. 接口规格索引

注：标注 * 的接口 Controller 使用 @RequestMapping，未限定 HTTP 方法；前端实际使用 POST（JSON）或 GET（Query）。

7. 前端页面规格

7.1 实现说明

本项目 Web 前端（src/main/resources/static）在页面结构、样式与部分交互实现上 借助 AI 辅助完成，设计取向为 美观、现代化视觉与现场展示效果，而非传统 B 端「功能优先、样式从简」风格。典型体现包括：

• 登录/注册页：分栏布局、渐变背景与表单视觉优化
• 管理后台：iframe 导航 + 统一卡片/表格样式
• 抽奖大屏（draw.html）：全屏背景、奖品展示、人名滚动动效、中奖确认交互

规格边界：本文档对前端的约束以 页面路由、功能行为、Token 传递、接口调用 为准；颜色、间距、动效细节以当前 AI 辅助产出为基线，不作为像素级设计稿验收项。后端 REST 接口规格不受 UI 实现方式影响。

7.2 页面清单

7.3 通用前端约定

Token 存储：localStorage.user_token、localStorage.user_identity

请求头：user_token: {JWT}

8. 状态机规格

8.1 状态扭转顺序

ActivityStatusManagerImpl.handlerEvent：

8.2 抽奖正向扭转

8.3 异常回滚

9. 安全规格

10. 异常与容错规格

10.1 MQ 重试

• spring.rabbitmq.listener.simple.retry.enabled=true
• max-attempts=5

10.2 死信队列

• 正常队列：DirectQueue → 死信交换机 DlxDirectExchange
• 死信消费者 DlxReceiver 重新投递到正常队列

10.3 校验失败静默返回

checkDrawPrizeParam 返回 false 时，MqReceiver 直接 return，不抛异常（消息被 ACK）

11. 验收标准

11.1 功能验收

11.2 非功能验收

文档结束，下一文档我们将手动实现数据库的设计。