【Java项目-企悦抽】04-项目演示+项目源码+AI赋能整理接口文档

弹简特2026-07-05 10:57

声明：本期的接口文档由AI辅助完成
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨

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

✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨

🔥 弹简特 个人主页

❄️ 个人专栏直通车：

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

✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨

🌟 博主简介:

文章目录：

  • 一、前言
  • 二、项目演示
  • [三、企悦抽 --- 接口设计文档(AI赋能)](#三、企悦抽 — 接口设计文档(AI赋能))
    • 修订记录
    • [1. 通用约定](#1. 通用约定)
      • [1.1 协议与编码](#1.1 协议与编码)
      • [1.2 前端与接口关系说明](#1.2 前端与接口关系说明)
      • [1.3 Content-Type](#1.3 Content-Type)
      • [1.4 HTTP 方法说明](#1.4 HTTP 方法说明)
      • [1.5 接口清单总览](#1.5 接口清单总览)
    • [2. 统一响应结构](#2. 统一响应结构)
      • [2.1 CommonResult](#2.1 CommonResult)
      • [2.2 成功判定](#2.2 成功判定)
      • [2.3 业务异常响应](#2.3 业务异常响应)
      • [2.4 鉴权失败](#2.4 鉴权失败)
    • [3. 认证与鉴权](#3. 认证与鉴权)
      • [3.1 JWT 传递](#3.1 JWT 传递)
      • [3.2 JWT 载荷（Claims）](#3.2 JWT 载荷（Claims）)
      • [3.3 白名单（无需 Token）](#3.3 白名单（无需 Token）)
    • [4. 用户模块接口](#4. 用户模块接口)
      • [4.1 API-01 用户注册](#4.1 API-01 用户注册)
      • [4.2 API-02 发送验证码](#4.2 API-02 发送验证码)
      • [4.3 API-03 密码登录](#4.3 API-03 密码登录)
      • [4.4 API-04 短信验证码登录](#4.4 API-04 短信验证码登录)
      • [4.5 API-05 查询用户列表](#4.5 API-05 查询用户列表)
    • [5. 奖品模块接口](#5. 奖品模块接口)
      • [5.1 API-06 上传图片](#5.1 API-06 上传图片)
      • [5.2 API-07 创建奖品](#5.2 API-07 创建奖品)
      • [5.3 API-08 奖品分页列表](#5.3 API-08 奖品分页列表)
      • [5.4 API-09 奖品全量列表](#5.4 API-09 奖品全量列表)
    • [6. 活动模块接口](#6. 活动模块接口)
      • [6.1 API-10 创建活动](#6.1 API-10 创建活动)
      • [6.2 API-11 活动分页列表](#6.2 API-11 活动分页列表)
      • [6.3 API-12 活动详情](#6.3 API-12 活动详情)
    • [7. 抽奖模块接口](#7. 抽奖模块接口)
      • [7.1 API-13 提交抽奖结果](#7.1 API-13 提交抽奖结果)
      • [7.2 API-14 查询中奖记录](#7.2 API-14 查询中奖记录)
    • [8. 错误码说明](#8. 错误码说明)
      • [8.1 HTTP 层](#8.1 HTTP 层)
      • [8.2 响应 code 字段](#8.2 响应 code 字段)
      • [8.3 业务错误信息（msg）](#8.3 业务错误信息（msg）)
    • [9. 枚举与数据字典](#9. 枚举与数据字典)
      • [9.1 identity 用户身份](#9.1 identity 用户身份)
      • [9.2 prizeTiers 奖品等级](#9.2 prizeTiers 奖品等级)
      • [9.3 活动/奖品/用户状态（库表）](#9.3 活动/奖品/用户状态（库表）)
    • [10. MQ 消息格式（内部）](#10. MQ 消息格式（内部）)
      • [10.1 交换机与队列](#10.1 交换机与队列)
      • [10.2 消息体](#10.2 消息体)
  • 四、项目源码

一、前言

我们上一期将数据设计完毕之后，我们按理来说进入编码阶段了，但是在编码之前，我们得需要参考自己的项目接口文档，所以本期我们就先演示出我们的项目，然后借助AI完成接口文档的编写，最后再分享我们的项目源码。

二、项目演示

注意：本项目的CSS样式借助AI完成美观的效果，我们后续的核心是自己完成后端以及前端的JS逻辑。

1、注册

2、登录

3、人员管理

4、奖品管理

5、开始抽奖

企悦抽演示

6、中奖

三、企悦抽 --- 接口设计文档(AI赋能)

文档属性 内容
产品名称 企悦抽（QiYueChou）
文档类型 接口设计文档（API Design）
文档版本 V1.0
编写日期 2025-07-03
上游文档 PRD V1.0、PRS V1.0
代码基线 lottery-system（com.zhongge.lotterysystem）
服务地址 http://{host}:8080
文档状态 已定稿

修订记录

版本 日期 修订说明
V1.0 2025-07-03 首版，与 lottery-system 源码逐接口对齐

1. 通用约定

1.1 协议与编码

项目 约定
协议 HTTP/HTTPS
字符编码 UTF-8
日期时间 JSON 序列化为 ISO-8601 或毫秒时间戳（Jackson 默认）
时区 服务器本地时区

1.2 前端与接口关系说明

Web 前端页面位于 src/main/resources/static，UI 层借助 AI 辅助设计与实现，主打美观、现代化视觉呈现（尤其登录页与抽奖大屏）。本文档仅定义后端 REST 接口契约；前端如何组织页面、样式与动效不在接口文档范围内，但各接口的入参/出参、鉴权方式须与前端实际调用保持一致（见各接口「前端调用页面」说明，如有）。

1.3 Content-Type

场景 Content-Type
JSON 请求 application/json
文件上传 multipart/form-data
JSON 响应 application/json（CommonResult 接口）

1.4 HTTP 方法说明

本项目 Controller 大量使用 @RequestMapping 且未限定 method，Spring 默认接受 GET/POST 等。下表「推荐方法」为前端实际调用方式；测试时可优先使用推荐方法。

1.5 接口清单总览

编号 推荐方法 路径 需要 Token Controller
API-01 POST /register 否 UserController
API-02 GET /verification-code/send 否 UserController
API-03 POST /password/login 否 UserController
API-04 POST /message/login 否 UserController
API-05 GET /base-user/find-list 是 UserController
API-06 POST /pic/upload 是 PrizeController
API-07 POST /prize/create 是 PrizeController
API-08 GET /prize/find-list 是 PrizeController
API-09 GET /prize/find-listAll 是 PrizeController
API-10 POST /activity/create 是 ActivityController
API-11 GET /activity/find-list 是 ActivityController
API-12 GET /activity-detail/find 是 ActivityController
API-13 POST /draw-prize 是 DrawPrizeController
API-14 POST /winning-records/show 否 DrawPrizeController

2. 统一响应结构

2.1 CommonResult

除 API-06 外，业务接口均返回 CommonResult<T>：

json 复制代码 
{
  "code": 200,
  "data": {},
  "msg": ""
}
字段 类型 说明
code Integer 200=成功；500=失败（GlobalException 统一包装）
data T 成功时业务数据；失败时一般为 null
msg String 成功时通常为空字符串；失败时为错误描述

2.2 成功判定

javascript 复制代码 
result.code === 200  // 前端判定方式

2.3 业务异常响应

GlobalException 捕获 ServiceException / ControllerException：

json 复制代码 
{
  "code": 500,
  "data": null,
  "msg": "具体业务错误信息"
}

2.4 鉴权失败

LoginInterceptor 拦截：HTTP Status 401 ，无 JSON Body。

3. 认证与鉴权

3.1 JWT 传递

项目 值
Header 名称 user_token
示例 user_token: eyJhbGciOiJIUzI1NiJ9...

3.2 JWT 载荷（Claims）

登录成功后 Token 中包含：

Claim 类型 说明
id Long/Integer 用户 ID
identity String ADMIN / NORMAL

有效期：3600 秒（1 小时）

3.3 白名单（无需 Token）

配置来源：AppConfig.excludes

模式 说明
/**/*.html 静态 HTML
/css/**、/js/**、/pic/** 静态资源
/*.jpg、/*.png 图片
/**/login 含 /password/login、/message/login
/register 注册
/verification-code/send 验证码
/winning-records/show 中奖记录查询

4. 用户模块接口

4.1 API-01 用户注册

项目 内容
路径 /register
方法 POST （@PostMapping）
鉴权 否
Controller UserController.userRegister

Request Body

json 复制代码 
{
  "name": "张三",
  "mail": "zhangsan@example.com",
  "phoneNumber": "13188888888",
  "password": "123456",
  "identity": "ADMIN"
}
字段 类型 必填 说明
name String 是 用户姓名，@NotBlank
mail String 是 邮箱
phoneNumber String 是 手机号
password String 条件 管理员必填；普通用户不传
identity String 是 ADMIN 或 NORMAL

Response data

json 复制代码 
{
  "userId": 22
}

业务错误 msg 示例

msg 触发条件
注册信息为空 param 为空
邮箱错误 格式不合法
手机号错误 格式不合法
身份错误 identity 非法或管理员无密码
邮箱被使用了 邮箱重复
手机号被使用了 手机号重复

4.2 API-02 发送验证码

项目 内容
路径 /verification-code/send
方法 GET
鉴权 否

Query 参数

参数 类型 必填 说明
phone String 是 手机号（注意：参数名为 phone，非 phoneNumber）

请求示例

复制代码 
GET /verification-code/send?phone=13188888888

Response data

json 复制代码 
true

实现说明

  • 验证码：4 位数字（MyCaptchaUtil.getCaptcha(4)）
  • Redis Key：VERIFICATION_CODE_{phone}，TTL 60 秒
  • 短信通道：Spug （SMSUtil.sendSms，非阿里云）

4.3 API-03 密码登录

项目 内容
路径 /password/login
方法 POST（推荐）
鉴权 否

Request Body

json 复制代码 
{
  "loginName": "13188888888",
  "password": "123456",
  "mandatoryIdentity": "ADMIN"
}
字段 类型 必填 说明
loginName String 是 手机号或邮箱
password String 是 明文密码（后端 SHA256 比对）
mandatoryIdentity String 否 强制身份：ADMIN / NORMAL

Response data

json 复制代码 
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "identity": "ADMIN"
}

业务错误 msg 示例

msg 触发条件
登录信息不存在 参数类型不匹配
登录方式不存在 loginName 既非手机也非邮箱
用户信息为空 用户不存在
身份错误 mandatoryIdentity 不匹配
身份错误 密码错误（代码中 PASSWORD_ERROR 文案为「身份错误」）

4.4 API-04 短信验证码登录

项目 内容
路径 /message/login
方法 POST（推荐）
鉴权 否

Request Body

json 复制代码 
{
  "loginMobile": "13188888888",
  "verificationCode": "1234",
  "mandatoryIdentity": "ADMIN"
}
字段 类型 必填 说明
loginMobile String 是 手机号
verificationCode String 是 4 位验证码
mandatoryIdentity String 否 ADMIN / NORMAL

Response data：同 API-03

业务错误 msg 示例

msg 触发条件
验证码校验失败 Redis 中无验证码或不匹配

4.5 API-05 查询用户列表

项目 内容
路径 /base-user/find-list
方法 GET
鉴权 是

Query 参数

参数 类型 必填 说明
identity String 否 ADMIN / NORMAL；不传返回全部

Response data

json 复制代码 
[
  {
    "userId": 15,
    "userName": "郭靖",
    "identity": "NORMAL"
  }
]

5. 奖品模块接口

5.1 API-06 上传图片

项目 内容
路径 /pic/upload
方法 POST
鉴权 是
响应格式 纯文本 String（非 CommonResult）

Request

参数 类型 说明
file MultipartFile 表单字段名 file

Response Body 示例

复制代码 
e606c8db-218a-40c2-8946-0d9f8570626d.jpg

说明 ：返回文件名；访问路径为静态资源映射 file:${pic.local-path}

5.2 API-07 创建奖品

项目 内容
路径 /prize/create
方法 POST
鉴权 是
Content-Type multipart/form-data

Form Data

字段名 类型 必填 说明
param String (JSON) 是 奖品信息 JSON 字符串
prizePic File 是 奖品图片

param JSON 结构

json 复制代码 
{
  "prizeName": "吹风机",
  "description": "家用吹风机",
  "price": 199.00
}
字段 类型 必填
prizeName String 是
description String 否
price BigDecimal 是

Response data

json 复制代码 
17

类型为 Long，奖品 ID。

5.3 API-08 奖品分页列表

项目 内容
路径 /prize/find-list
方法 GET
鉴权 是

Query 参数

参数 类型 默认 说明
currentPage Integer 1 当前页
pageSize Integer 10 每页条数

Response data

json 复制代码 
{
  "total": 3,
  "records": [
    {
      "prizeId": 17,
      "prizeName": "吹风机",
      "description": "家用吹风机",
      "price": 199.00,
      "imageUrl": "e606c8db-218a-40c2-8946-0d9f8570626d.jpg"
    }
  ]
}

5.4 API-09 奖品全量列表

项目 内容
路径 /prize/find-listAll
方法 GET
鉴权 是

Response data

json 复制代码 
[
  {
    "prizeId": 17,
    "prizeName": "吹风机"
  }
]

6. 活动模块接口

6.1 API-10 创建活动

项目 内容
路径 /activity/create
方法 POST
鉴权 是

Request Body

json 复制代码 
{
  "activityName": "2026年会抽奖",
  "description": "年终福利抽奖活动",
  "activityPrizeList": [
    {
      "prizeId": 13,
      "prizeAmount": 1,
      "prizeTiers": "FIRST_PRIZE"
    },
    {
      "prizeId": 12,
      "prizeAmount": 2,
      "prizeTiers": "SECOND_PRIZE"
    }
  ],
  "activityUserList": [
    {
      "userId": 25,
      "userName": "郭靖"
    },
    {
      "userId": 23,
      "userName": "杨康"
    }
  ]
}
字段 类型 必填 说明
activityName String 是 活动名称
description String 是 活动描述
activityPrizeList Array 是 至少 1 项
activityPrizeList\[\].prizeId Long 是 奖品 ID
activityPrizeList\[\].prizeAmount Long 是 奖品数量
activityPrizeList\[\].prizeTiers String 是 FIRST_PRIZE / SECOND_PRIZE / THIRD_PRIZE
activityUserList Array 是 至少 1 项
activityUserList\[\].userId Long 是 用户 ID
activityUserList\[\].userName String 是 用户姓名

Response data

json 复制代码 
{
  "activityId": 23
}

业务错误 msg 示例

msg 触发条件
创建的活动信息为空 param 为空
活动关联的人员异常 用户 ID 不存在
活动关联的奖品异常 奖品 ID 不存在
活动关联的奖品及人员数量设置异常 人数 < 奖品总数
活动奖品等奖设置错误 prizeTiers 非法

6.2 API-11 活动分页列表

项目 内容
路径 /activity/find-list
方法 GET
鉴权 是

Query 参数

参数 类型 默认
currentPage Integer 1
pageSize Integer 10

Response data

json 复制代码 
{
  "total": 10,
  "records": [
    {
      "activityId": 23,
      "activityName": "2026年会抽奖",
      "description": "年终福利抽奖活动",
      "valid": true
    }
  ]
}
字段 说明
valid true=进行中(RUNNING)；false=已完成(COMPLETED)

6.3 API-12 活动详情

项目 内容
路径 /activity-detail/find
方法 GET
鉴权 是

Query 参数

参数 类型 必填
activityId Long 是

Response data

json 复制代码 
{
  "activityId": 24,
  "activityName": "2026年会抽奖",
  "description": "年终福利抽奖活动",
  "valid": true,
  "prizes": [
    {
      "prizeId": 18,
      "name": "手机",
      "description": "智能手机",
      "price": 5000.00,
      "imageUrl": "e606c8db-218a-40c2-8946-0d9f8570626d.jpg",
      "prizeAmount": 1,
      "prizeTierName": "一等奖",
      "valid": true
    }
  ],
  "users": [
    {
      "userId": 44,
      "userName": "郭靖",
      "valid": true
    }
  ]
}

字段语义

字段 true 含义 false 含义
活动 valid RUNNING COMPLETED
奖品 valid INIT（未抽取） COMPLETED（已抽取）
用户 valid INIT（未中奖） COMPLETED（已中奖）

排序：奖品按等级 code 升序（一等奖在前）

activityId 为空：返回 code=500，msg=「查询活动详细信息失败」

7. 抽奖模块接口

7.1 API-13 提交抽奖结果

项目 内容
路径 /draw-prize
方法 POST
鉴权 是
说明 同步仅发 MQ，落库由消费者异步完成

Request Body

json 复制代码 
{
  "activityId": 23,
  "prizeId": 13,
  "winningTime": "2026-07-03T10:30:00.000+00:00",
  "winnerList": [
    {
      "userId": 15,
      "userName": "张三"
    }
  ]
}
字段 类型 必填 说明
activityId Long 是 活动 ID
prizeId Long 是 奖品 ID
winningTime Date 是 中奖时间
winnerList Array 是 至少 1 人
winnerList\[\].userId Long 是 中奖用户 ID
winnerList\[\].userName String 是 中奖用户姓名

注意：源码中 无 prizeTiers 字段（已注释）。

Response data

json 复制代码 
true

异步消费校验规则 （checkDrawPrizeParam）

条件 失败行为
活动或活动奖品不存在 消费 return，不落库
活动 status=COMPLETED 消费 return
奖品 status=COMPLETED 消费 return
winnerList.size() ≠ prizeAmount 消费 return

消费成功后续：状态扭转 → 写 winning_record → 缓存 → 异步邮件

7.2 API-14 查询中奖记录

项目 内容
路径 /winning-records/show
方法 POST
鉴权 否（白名单）

Request Body

json 复制代码 
{
  "activityId": 23,
  "prizeId": 13
}
字段 类型 必填 说明
activityId Long 是 活动 ID
prizeId Long 否 不传=活动全量；传=指定奖品

Response data

json 复制代码 
[
  {
    "winnerId": 15,
    "winnerName": "张三",
    "prizeName": "手机",
    "prizeTier": "一等奖",
    "winningTime": "2026-07-03T10:30:00.000+00:00"
  }
]
字段 说明
prizeTier 中文描述（非枚举名）

空结果 ：返回 data: []（code 仍为 200）

8. 错误码说明

8.1 HTTP 层

HTTP Status 场景
200 正常（含业务失败 code=500）
401 Token 缺失或无效

8.2 响应 code 字段

code 含义
200 成功
500 失败（GlobalErrorCodeConstants.INTERNAL_SYSTEM_ERROR）

8.3 业务错误信息（msg）

Service 层错误码常量（通过 GlobalException 输出 msg）：

模块 典型 msg
用户 注册信息为空、邮箱错误、手机号错误、身份错误、邮箱被使用了、手机号被使用了、登录信息不存在、登录方式不存在、用户信息为空、验证码校验失败
活动 创建的活动信息为空、活动关联的人员异常、活动关联的奖品异常、活动关联的奖品及人员数量设置异常、活动奖品等奖设置错误、活动相关状态转换失败
抽奖 MQ 消费校验失败时静默 return，不返回给前端
图片 图片上传失败

Controller 层异常 msg：

msg 接口
注册失败 /register
登录失败 登录接口
查询奖品列表失败 奖品列表
创建活动失败 /activity/create
获取活动列表错误 /activity/find-list
查询活动详细信息失败 /activity-detail/find

9. 枚举与数据字典

9.1 identity 用户身份

值 说明
ADMIN 管理员
NORMAL 普通用户

9.2 prizeTiers 奖品等级

值 中文
FIRST_PRIZE 一等奖
SECOND_PRIZE 二等奖
THIRD_PRIZE 三等奖

9.3 活动/奖品/用户状态（库表）

表 字段 status 取值
activity status RUNNING, COMPLETED
activity_prize status INIT, COMPLETED
activity_user status INIT, COMPLETED

10. MQ 消息格式（内部）

10.1 交换机与队列

名称 常量值
交换机 DirectExchange
路由键 DirectRouting
队列 DirectQueue
死信交换机 DlxDirectExchange
死信队列 DlxDirectQueue

10.2 消息体

json 复制代码 
{
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "messageData": "{\"activityId\":23,\"prizeId\":13,\"winningTime\":\"...\",\"winnerList\":[...]}"
}
字段 说明
messageId UUID 字符串
messageData DrawPrizeParam 的 JSON 字符串

四、项目源码

本项目源码已上传至Gitee码云仓库✨，有需要的小伙伴可自行拉取，方便对照操作复现完整项目流程～

项目👉企悦抽项目源码

到这里项目文档就全部整理好咯📄！下一期直接上手实操，手把手带大家做完项目，多多关注，后面还有超多实用干货～

相关推荐
Scott9999HH17 小时前
【IIoT流量实战】蒸汽管道阀门全关却仍有流量？用 Python 实现涡街信号 FFT 频谱分析与温压全补偿积算网关，深度拆解靠谱的涡街流量计厂家硬核技术标准
开发语言·python
腻害兔17 小时前
【若依项目-产品经理视角】深度拆解 RuoYi-Vue-Pro 商城模块：从商品管理到交易引擎，50 张表撑起一整套电商系统
java·大数据·vue.js·产品经理·ai编程
码智社18 小时前
AES加密原理详解及Java实现加解密实战
java·开发语言
AI云海18 小时前
python 列表、元组、集合和字典
开发语言·python
萧瑟余晖19 小时前
JDK 26 新特性详解
java·开发语言
马优晨19 小时前
Freemarker 完整讲解（后端 Java 模板引擎）
java·开发语言·freemarker·freemarker 完整讲解·freemarker模板引擎
人邮异步社区21 小时前
怎么把C语言学到精通？
c语言·开发语言
心平气和量大福大1 天前
C#-WPF-控件-TextBox 数据绑定
开发语言·c#·wpf
ttwuai1 天前
Cursor 生成 CRUD 后，Go 后台接口别只测 200：JWT、RBAC 和 tenant_id 怎么验
开发语言·后端·golang
维天说1 天前
CLI-Switch 2026年3月版历史设计：Hook、TTY 隔离与 JSON 状态
java·服务器·json
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02GitHub 镜像站点032026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片04AI科技热点日报 | 2026年07月01日05国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路07幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南082026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10【解构】DeepSeek V4 发布：技术报告深度解读 + 横向对比六大开源模型，我们的判断是……