195 lines
13 KiB
Markdown
195 lines
13 KiB
Markdown
# 需求文档：贩卖机移动端APP
|
||
|
||
## 简介
|
||
|
||
本文档定义贩卖机管理系统移动端APP的功能需求。该APP基于UniApp + Vue3技术栈开发，目标平台为Android和iOS，需上架Google Play和App Store。APP主要功能包括：会员管理、优惠券兑换、积分管理、节日印花活动、会员二维码展示（用于贩卖机扫码对接），以及Google Pay/Apple Pay支付集成。后端API已完善，移动端需对接现有REST API接口。
|
||
|
||
## 术语表
|
||
|
||
- **APP**：贩卖机移动端应用程序，基于UniApp + Vue3开发
|
||
- **用户**：使用APP的终端用户
|
||
- **会员**：已购买会员服务的用户
|
||
- **积分**：用户在贩卖机消费后按比例获得的虚拟货币，可用于兑换优惠券或赠送他人
|
||
- **优惠券**：可在贩卖机消费时抵扣金额的电子券，分为满减券和抵扣券
|
||
- **印花优惠券**：节假日活动中赠送给会员的特殊优惠券，需手动兑换
|
||
- **会员二维码**：包含用户token的二维码，有效期5分钟，供贩卖机扫码识别用户身份
|
||
- **Banner**：首页顶部轮播图，后台可配置图片和跳转链接
|
||
- **入口图片**：首页中可点击跳转的功能入口图片，后台可配置
|
||
- **JWT**：JSON Web Token，用于API接口认证的令牌
|
||
- **多语言系统**：支持简体中文、繁体中文、英文三种语言的国际化系统
|
||
- **订阅会员**：通过Google Play/App Store订阅机制实现的每月自动续费会员服务
|
||
|
||
## 需求
|
||
|
||
### 需求1：多语言国际化支持
|
||
|
||
**用户故事：** 作为用户，我希望能够切换APP语言，以便使用我熟悉的语言操作APP。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE 多语言系统 SHALL 支持简体中文、繁体中文、英文三种语言
|
||
2. WHEN 用户切换语言时，THE APP SHALL 立即更新所有界面文字为所选语言
|
||
3. THE APP SHALL 在API请求头中携带当前语言标识，以获取对应语言的后台配置内容
|
||
4. WHEN APP启动时，THE 多语言系统 SHALL 加载用户上次选择的语言，若无历史记录则使用设备系统语言对应的支持语言
|
||
5. THE 多语言系统 SHALL 将用户的语言选择持久化存储到本地
|
||
|
||
### 需求2：用户认证
|
||
|
||
**用户故事：** 作为用户，我希望通过手机号验证码登录APP，以便安全地使用各项功能。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 用户输入手机号并点击发送验证码时，THE APP SHALL 调用 POST /api/user/send-code 接口发送验证码
|
||
2. THE 登录页 SHALL 支持用户更换手机区号
|
||
3. WHEN 用户输入验证码并点击登录时，THE APP SHALL 检测用户是否已勾选同意用户协议和隐私政策
|
||
4. IF 用户未勾选同意协议，THEN THE APP SHALL 弹出提示"请阅读并同意协议"，阻止登录操作
|
||
5. WHEN 用户已勾选协议并点击登录时，THE APP SHALL 调用 POST /api/user/login 接口完成登录，并将返回的JWT Token存储到本地
|
||
6. WHEN 登录成功后，THE APP SHALL 在所有需要认证的API请求头中自动携带JWT Bearer Token
|
||
7. WHEN 用户点击退出登录时，THE APP SHALL 调用 POST /api/user/logout 接口，清除本地Token，并返回未登录状态
|
||
8. IF JWT Token过期或无效，THEN THE APP SHALL 清除本地Token并引导用户重新登录
|
||
|
||
### 需求3：首页
|
||
|
||
**用户故事：** 作为用户，我希望在首页看到Banner、功能入口和可兑换优惠券列表，以便快速访问各项功能。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 首页加载时，THE APP SHALL 调用 GET /api/content/banners 获取Banner列表，并在顶部展示轮播图
|
||
2. WHEN 用户点击Banner时，THE APP SHALL 根据配置的跳转链接导航到内部页面或打开外部链接
|
||
3. WHEN 首页加载时，THE APP SHALL 调用 GET /api/content/entries 获取入口图片列表，展示"成为会员"、"节日印花"、"会员二维码"、"使用说明"等入口
|
||
4. WHEN 用户点击"成为会员"入口时，THE APP SHALL 跳转至会员页
|
||
5. WHEN 用户点击"节日印花"入口时，THE APP SHALL 跳转至节日印花页
|
||
6. WHEN 用户点击"会员二维码"入口时，THE APP SHALL 调用 GET /api/membership/info 判断用户是否为会员
|
||
7. WHILE 用户为会员状态，WHEN 用户点击"会员二维码"入口时，THE APP SHALL 弹出会员二维码弹窗
|
||
8. WHILE 用户为非会员状态，WHEN 用户点击"会员二维码"入口时，THE APP SHALL 跳转至会员页
|
||
9. WHEN 用户点击"使用说明"入口时，THE APP SHALL 调用 GET /api/content/coupon-guide 获取文案并弹出优惠券使用说明弹窗
|
||
10. WHEN 首页加载时，THE APP SHALL 调用 GET /api/coupon/redeemable 获取可兑换优惠券列表，展示优惠券名称、到期时间、兑换所需积分和兑换按钮
|
||
11. WHEN 用户点击优惠券的兑换按钮时，THE APP SHALL 弹出确认兑换弹窗，展示优惠券信息和所需积分
|
||
12. WHEN 用户在确认弹窗中点击确定兑换时，THE APP SHALL 调用 POST /api/coupon/redeem/{couponId} 接口执行兑换
|
||
13. IF 兑换成功，THEN THE APP SHALL 关闭弹窗并弹出系统提示"兑换成功"，刷新优惠券列表
|
||
14. IF 用户积分不足，THEN THE APP SHALL 关闭弹窗并弹出系统提示"积分不足，无法兑换"
|
||
15. IF 优惠券已下架，THEN THE APP SHALL 关闭弹窗并弹出系统提示"优惠券已下架"
|
||
|
||
### 需求4：会员二维码
|
||
|
||
**用户故事：** 作为会员，我希望展示会员二维码，以便在贩卖机上扫码获取积分和使用优惠券。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 会员二维码弹窗打开时，THE APP SHALL 生成包含用户token的二维码图片
|
||
2. THE 会员二维码 SHALL 设置5分钟有效期，到期后自动刷新生成新的二维码
|
||
3. WHEN 二维码有效期剩余时间不足时，THE APP SHALL 展示倒计时提示
|
||
4. WHEN 二维码过期时，THE APP SHALL 自动生成新的二维码并更新显示
|
||
|
||
### 需求5：会员服务
|
||
|
||
**用户故事：** 作为用户，我希望购买会员服务，以便享受会员专属权益。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 会员页加载时，THE APP SHALL 调用 GET /api/content/membership-banner 获取会员宣传长图并展示
|
||
2. WHEN 会员页加载时，THE APP SHALL 调用 GET /api/membership/products 获取会员商品列表（含价格和生效时长）
|
||
3. WHILE 用户为非会员状态，WHEN 用户点击"开通会员"按钮时，THE APP SHALL 根据设备平台拉起Google Pay或Apple Pay支付流程
|
||
4. WHEN 支付成功后，THE APP SHALL 调用 POST /api/membership/purchase 接口通知后端，并强制刷新会员页
|
||
5. WHILE 用户已开通单月会员，THE 会员页 SHALL 将按钮文字更改为"会员已开通"，按钮处于灰色不可点击状态
|
||
6. WHEN 用户点击"订阅会员"按钮时，THE APP SHALL 通过Google Play/App Store订阅机制发起每月自动续费订阅
|
||
7. WHEN 订阅成功后，THE APP SHALL 调用 POST /api/membership/subscribe 接口通知后端，并刷新页面
|
||
8. WHILE 用户已购买单月会员，THE 会员页 SHALL 隐藏单月会员购买按钮，仅显示订阅会员购买按钮
|
||
9. WHILE 用户已购买订阅会员，THE 会员页 SHALL 将按钮文字更改为"已购买订阅会员"，按钮处于灰色不可点击状态
|
||
10. THE APP SHALL 调用 GET /api/membership/subscription-status 获取订阅状态以确定按钮显示逻辑
|
||
|
||
### 需求6：节日印花
|
||
|
||
**用户故事：** 作为会员，我希望在节假日兑换印花优惠券，以便获得消费优惠。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 节日印花页加载时，THE APP SHALL 调用 GET /api/content/stamp-banner 获取印花Banner图并展示
|
||
2. WHEN 节日印花页加载时，THE APP SHALL 调用 GET /api/coupon/stamps 获取印花优惠券列表
|
||
3. WHILE 用户为会员状态，WHEN 用户点击印花优惠券的兑换按钮时，THE APP SHALL 调用 POST /api/coupon/stamps/redeem/{stampCouponId} 接口执行兑换
|
||
4. WHILE 用户为非会员状态，WHEN 用户点击印花优惠券的兑换按钮时，THE APP SHALL 跳转至会员页
|
||
5. WHEN 印花优惠券兑换成功后，THE APP SHALL 将该优惠券的兑换按钮替换为"已兑换"灰色不可点击状态
|
||
6. THE 节日印花页 SHALL 对每张印花优惠券每人限制兑换1次，已兑换的优惠券显示"已兑换"状态
|
||
|
||
### 需求7：个人中心
|
||
|
||
**用户故事：** 作为用户，我希望在"我的"页面管理个人信息、积分、优惠券和APP设置。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHILE 用户未登录，THE 我的页 SHALL 展示默认头像和登录按钮
|
||
2. WHEN 未登录用户点击登录按钮时，THE APP SHALL 跳转至登录页
|
||
3. WHILE 用户已登录，THE 我的页 SHALL 调用 GET /api/user/info 获取用户信息，展示默认昵称（"用户"+随机6位数字）和UID
|
||
4. WHILE 用户已登录，THE 我的页 SHALL 调用 GET /api/points/balance 获取并展示剩余积分
|
||
5. WHEN 用户点击积分区域时，THE APP SHALL 跳转至我的积分页
|
||
6. WHEN 用户点击赠送积分按钮时，THE APP SHALL 弹出赠送积分弹窗，包含UID输入框和积分数量输入框
|
||
7. WHEN 用户在赠送积分弹窗中点击赠送按钮时，THE APP SHALL 调用 POST /api/points/gift 接口执行赠送
|
||
8. IF 赠送成功，THEN THE APP SHALL 关闭弹窗并弹出系统提示"积分已赠送"，刷新积分余额
|
||
9. IF 用户剩余积分不足，THEN THE APP SHALL 弹出系统提示"剩余积分不足，无法赠送"
|
||
10. WHEN 用户点击我的优惠券按钮时，THE APP SHALL 跳转至我的优惠券页
|
||
11. WHEN 用户点击切换语言按钮时，THE APP SHALL 弹出语言选择列表（简体中文、繁体中文、英文）
|
||
12. WHEN 用户点击用户协议按钮时，THE APP SHALL 跳转至用户协议页
|
||
13. WHEN 用户点击隐私政策按钮时，THE APP SHALL 跳转至隐私政策页
|
||
14. WHEN 用户点击关于按钮时，THE APP SHALL 跳转至关于页
|
||
15. WHEN 用户点击退出登录按钮时，THE APP SHALL 弹出确认退出弹窗
|
||
|
||
### 需求8：积分管理
|
||
|
||
**用户故事：** 作为用户，我希望查看积分的获取和使用记录，以便了解积分变动情况。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE 我的积分页 SHALL 提供"获取记录"和"使用记录"两个Tab页签
|
||
2. WHEN 用户切换到获取记录Tab时，THE APP SHALL 调用 GET /api/points/earn-records 获取积分获取记录，展示积分来源、获取时间、增加数量
|
||
3. WHEN 用户切换到使用记录Tab时，THE APP SHALL 调用 GET /api/points/spend-records 获取积分使用记录，展示积分使用方式、使用时间、减少数量
|
||
4. THE 我的积分页 SHALL 支持分页加载，滚动到底部时自动加载下一页数据
|
||
|
||
### 需求9：优惠券管理
|
||
|
||
**用户故事：** 作为用户，我希望查看我的优惠券列表和使用状态，以便管理我的优惠券。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE 我的优惠券页 SHALL 提供"可使用"、"已使用"、"已过期"三个Tab页签
|
||
2. WHEN 用户切换Tab时，THE APP SHALL 调用 GET /api/coupon/my 并传入对应状态参数获取优惠券列表
|
||
3. THE 我的优惠券页 SHALL 在已使用的优惠券上显示"已使用"标识图标
|
||
4. THE 我的优惠券页 SHALL 在已过期的优惠券上显示"已过期"标识图标
|
||
|
||
### 需求10：内容展示页
|
||
|
||
**用户故事：** 作为用户，我希望查看用户协议、隐私政策和关于信息，以便了解APP相关条款和版本信息。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 用户协议页加载时，THE APP SHALL 调用 GET /api/content/agreement 获取用户协议内容并展示
|
||
2. WHEN 隐私政策页加载时，THE APP SHALL 调用 GET /api/content/privacy-policy 获取隐私政策内容并展示
|
||
3. THE 关于页 SHALL 展示APP的LOGO、当前版本号和注销账号按钮
|
||
4. WHEN 用户点击注销账号按钮时，THE APP SHALL 弹出确认注销弹窗
|
||
5. WHEN 用户在确认弹窗中点击确定时，THE APP SHALL 调用 DELETE /api/user/account 接口注销账号
|
||
6. WHEN 注销成功后，THE APP SHALL 清除本地登录状态，返回首页，并弹出系统提示"已注销"
|
||
|
||
### 需求11：网络请求与状态管理
|
||
|
||
**用户故事：** 作为开发者，我希望APP具备统一的网络请求封装和状态管理，以便高效对接后端API。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE APP SHALL 封装统一的HTTP请求模块，自动在请求头中携带JWT Token和语言标识
|
||
2. THE APP SHALL 实现统一的API响应处理，根据后端返回的success字段判断请求结果
|
||
3. IF API返回401未授权状态码，THEN THE APP SHALL 自动清除本地Token并跳转至登录页
|
||
4. THE APP SHALL 使用集中式状态管理（如Pinia）管理用户登录状态、会员信息和语言设置
|
||
5. IF 网络请求失败，THEN THE APP SHALL 展示友好的错误提示信息
|
||
|
||
### 需求12：平台适配与支付集成
|
||
|
||
**用户故事：** 作为用户，我希望在Android和iOS设备上获得一致的使用体验，并能通过平台原生支付方式完成会员购买。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE APP SHALL 适配Android和iOS两个平台的UI展示和交互行为
|
||
2. WHILE 运行在Android平台，WHEN 需要支付时，THE APP SHALL 调用Google Pay支付接口
|
||
3. WHILE 运行在iOS平台，WHEN 需要支付时，THE APP SHALL 调用Apple Pay支付接口
|
||
4. THE APP SHALL 封装统一的支付接口，内部根据平台自动选择对应的支付渠道
|
||
5. IF 支付过程中发生错误，THEN THE APP SHALL 展示明确的错误提示并允许用户重试
|
||
6. THE APP SHALL 满足Google Play和App Store的上架要求
|