买家前端设计文档 - H15058218452-rgb/Software-Engineering-Experimental-Group GitHub Wiki
一、买家前端概述与角色权限
1.1 文档目的
本文档用于定义《在线购物系统 MVP》第一迭代中买家前端的页面结构、功能需求、交互规则、表单字段、异常提示和业务流程，为后续 Vue3 前端开发以及前后端接口联调提供统一依据。
本系统采用：
- 单卖家
- 单商品
- 买家免注册
- 线下交易
- 购买意向排队
- 卖家手动确认交易结果
买家无需注册和登录，即可浏览当前商品并提交购买意向。
1.2 买家角色
买家属于匿名普通用户。 买家可以：
- 浏览当前商品
- 查看商品详情
- 提交购买意向
- 获取系统生成的口令码
- 凭口令码查询自己的购买意向
- 查看当前排队位次
- 在排队阶段修改姓名和联系电话
- 在排队阶段撤销购买意向
- 在交易阶段查看交易状态
1.3 买家权限
| 操作 | 是否允许 | 说明 |
|---|---|---|
| 浏览商品 | 是 | 无需注册和登录 |
| 查看商品详情 | 是 | 在售、冻结状态均可查看 |
| 提交购买意向 | 是 | 仅商品处于在售状态时允许 |
| 修改姓名 | 是 | 仅排队阶段允许 |
| 修改联系电话 | 是 | 仅排队阶段允许 |
| 查看排队位次 | 是 | 仅能查看自己的意向 |
| 撤销意向 | 是 | 仅排队阶段允许 |
| 交易中修改信息 | 否 | 进入交易后不可修改 |
| 交易中撤销意向 | 否 | 进入交易后不可自主撤销 |
| 查看其他买家信息 | 否 | 买家之间信息隔离 |
| 查看卖家后台 | 否 | 卖家专用 |
1.4 核心业务原则
买家端必须遵循以下核心规则： 提交购买意向 ≠ 进入交易 ≠ 商品冻结
具体流程为： 买家提交意向 → 进入排队 → 卖家选择队首买家开始交易 → 买家进入交易 → 商品自动冻结
因此，买家提交购买意向后，商品仍然处于“在售”状态，可以继续接受其他买家的购买意向。
二、买家前端页面与原型设计
2.1 页面清单
| 页面编号 | 页面名称 | 主要功能 |
|---|---|---|
| BUY‑01 | 买家商品浏览首页 | 查看当前商品 |
| BUY‑02 | 商品详情页 | 查看商品详细信息 |
| BUY‑03 | 购买意向提交页 | 填写并提交购买意向 |
| BUY‑04 | 意向提交成功页 | 展示一次性口令码 |
| BUY‑05 | 意向口令码管理页 | 输入口令码查询意向 |
| BUY‑06 | 意向详情/状态页 | 查看状态、修改、撤销 |
2.2 BUY‑01 买家商品浏览首页
页面功能：买家无需注册和登录即可访问。 由于系统采用单商品 MVP 模式，因此页面只展示当前商品，不展示商品列表。
商品信息包括：
- 商品名称
- 商品描述
- 商品图片
- 商品价格
- 商品状态
商品在售
当商品状态为“在售”时，显示提交购买意向按钮，点击后进入 BUY‑03。
商品冻结
当商品状态为“已冻结（交易中）”时，商品仍可以查看，但不能提交购买意向。按钮置灰，并显示：商品交易中，暂时无法提交购买意向。
没有在售商品
当系统当前没有在售商品时，显示：暂无在售商品，请稍后再来。同时提供管理购买意向入口，使已经提交过意向的买家仍可以查询自己的状态。
商品已下架 已经交易成功或被卖家手动下架的商品，不再作为当前商品展示。
2.3 BUY‑02 商品详情页
| 信息 | 是否展示 |
|---|---|
| 商品名称 | 是 |
| 商品描述 | 是 |
| 商品图片 | 是 |
| 商品价格 | 是 |
| 商品状态 | 是 |
| 提交购买意向按钮 | 根据状态决定 |
- 在售：显示
提交购买意向按钮。 - 已冻结（交易中）：显示商品详细信息，但提交按钮不可用，提示：
商品交易中，暂时无法提交购买意向。
2.4 BUY‑03 购买意向提交页
| 字段名 | 是否必填 | 前端校验规则 |
|---|---|---|
| 买家姓名 | 是 | 去除首尾空白后不能为空，长度 1~20 字符 |
| 联系电话 | 是 | 去除首尾空白后不能为空 |
联系电话本版本只校验是否为空，不验证号码真实性。
点击提交后：
- 前端执行表单校验
- 校验通过后发送请求
- 提交按钮进入加载状态，防止重复点击
- 后端再次检查商品状态和重复意向
2.5 BUY‑04 意向提交成功页
提交成功后，系统即时生成唯一口令码。 页面显示：
意向提交成功！ 请妥善保存下方口令码，口令码仅展示一次，丢失无法找回。
同时展示：商品名称、商品价格、提交时间、当前状态、口令码。 口令码只在提交成功页面展示一次，不发送短信，不提供找回功能。
2.6 BUY‑05 意向口令码管理页
买家从首页进入管理购买意向，输入购买意向口令码，点击查询意向。
系统根据口令码查询本人购买意向。
如果口令码不存在或已经失效：口令码已失效，无对应意向信息，不得展示其他买家的信息。
2.7 BUY‑06 意向详情/状态页
排队中
展示：商品名称、商品价格、意向状态、当前排队位次、提交时间、买家姓名、联系电话。
提供：修改联系信息、撤销购买意向按钮。
正在交易
显示：当前已进入交易流程，请等待卖家确认交易结果。
此时不允许修改姓名、不允许修改联系电话、不允许撤销意向。
交易失败并重新排队
显示：交易暂未完成，您的意向已重新进入排队队列，原口令码继续有效，买家可以查看新的排队位次。
意向失效
如果买家撤销、卖家作废、交易成功或者商品下架导致意向终结：当前购买意向已失效，无法继续管理。
三、表单校验、口令码与意向管理规则
3.1 表单校验
| 编号 | 场景 | 提示信息 |
|---|---|---|
| MSG‑01 | 姓名为空 | 姓名不能为空，请填写买家姓名 |
| MSG‑02 | 电话为空 | 联系电话不能为空，请填写联系电话 |
| MSG‑03 | 姓名超过20字符 | 姓名长度不能超过20个字符 |
| MSG‑04 | 商品冻结 | 商品交易中，暂时无法提交购买意向 |
| MSG‑05 | 重复提交 | 您已提交过该商品的购买意向，请勿重复提交 |
| MSG‑06 | 口令码无效 | 口令码已失效，无对应意向信息 |
| MSG‑07 | 修改失败 | 姓名、联系电话不能为空，请重新填写 |
| MSG‑08 | 撤销确认 | 确认撤销本次购买意向？撤销后将退出排队，无法恢复 |
| MSG‑09 | 交易中撤销 | 当前已进入交易流程，无法自主撤销意向 |
| MSG‑10 | 提交成功 | 意向提交成功！请妥善保存下方口令码，口令码仅展示一次，丢失无法找回 |
| MSG‑11 | 网络异常 | 网络请求失败，请检查网络后重试 |
| MSG‑12 | 商品状态变化 | 商品状态已发生变化，请刷新页面后重试 |
| MSG‑13 | 修改成功 | 联系信息修改成功，您的排队顺序不变 |
| MSG‑14 | 撤销成功 | 购买意向已撤销，您已退出排队 |
| MSG‑15 | 正在交易 | 当前已进入交易流程，请等待卖家确认交易结果 |
| MSG‑16 | 重新排队 | 交易暂未完成，您的意向已重新进入排队队列 |
| MSG‑17 | 意向作废 | 当前购买意向已失效，无法继续管理 |
3.2 重复意向规则
系统允许同一个手机号提交不同商品的购买意向。 但是：同一商品 + 同一手机号只能存在一条有效购买意向。
| 商品 | 手机号 | 结果 |
|---|---|---|
| 商品A | 138xxxx | 允许 |
| 商品B | 138xxxx | 允许 |
| 商品A | 138xxxx 再次提交 | 拒绝 |
最终限制由后端负责，前端负责展示错误提示。
3.3 排队规则
买家提交购买意向后立即进入排队。 排队按照提交时间正序执行，先提交者优先。
| 买家 | 提交时间 | 排队位次 |
|---|---|---|
| A | 10:01 | 1 |
| B | 10:03 | 2 |
| C | 10:05 | 3 |
修改姓名或联系电话不会改变排队位次。
3.4 买家撤销规则
只有排队中状态允许撤销。 撤销后：
- 买家退出队列
- 后续买家位次前移
- 原口令码失效
买家撤销意向不会直接改变商品状态。
3.5 口令码生命周期
生效：提交购买意向成功后立即生效。
持续有效：排队中、正在交易、交易失败重新排队。
失效：买家主动撤销；卖家将意向作废；交易成功；商品下架导致意向终结。
四、买家端业务流程与状态设计
4.1 买家主要业务流程
flowchart TD
A["访问买家商品首页"] --> B{"当前是否存在商品"}
B -- "否" --> C["暂无在售商品，请稍后再来"]
B -- "是" --> D["查看当前商品"]
D --> E{"商品状态"}
E -- "在售" --> F["点击提交购买意向"]
E -- "已冻结" --> G["按钮置灰，提示商品交易中"]
F --> H["填写姓名和联系电话"]
H --> I{"前端校验"}
I -- "失败" --> H
I -- "通过" --> J["提交购买意向"]
J --> K{"后端校验"}
K -- "失败" --> L["显示业务错误提示"]
K -- "成功" --> M["生成唯一口令码"]
M --> N["一次性展示口令码"]
N --> O["买家保存口令码"]
O --> P["进入购买意向队列"]
P --> Q["等待卖家处理"]
Q --> R["卖家选择队首买家开始交易"]
R --> S["买家进入交易状态"]
S --> T["商品自动冻结"]
T --> U{"卖家确认交易结果"}
U -- "成功" --> V["商品下架"]
U -- "失败并作废" --> W["当前意向作废"]
U -- "失败并重新排队" --> X["当前意向进入队尾"]
X --> Y{"队列是否还有其他意向"}
Y -- "有" --> Z["自动递补队首进入交易"]
Y -- "无" --> AA["商品恢复在售"]
4.2 商品状态
| 状态 | 含义 | 买家能否查看 | 能否提交意向 |
|---|---|---|---|
| 在售 | 商品正常销售 | 是 | 是 |
| 已冻结（交易中） | 正在进行线下交易 | 是 | 否 |
| 已下架 | 商品已经结束销售 | 否 | 否 |
4.3 商品状态转换
stateDiagram-v2
[*] --> 在售
在售 --> 已冻结: 卖家开始与队首买家交易
已冻结 --> 已下架: 卖家确认交易成功
已冻结 --> 在售: 交易失败且队列为空
已冻结 --> 已冻结: 交易失败后自动递补下一位
在售 --> 已下架: 卖家手动下架
注：卖家手动冻结属于后台操作。买家端只体现为商品暂时不能提交购买意向。交易中的商品禁止手动解冻。
4.4 买家意向状态
| 状态 | 说明 | 查询 | 修改 | 撤销 |
|---|---|---|---|---|
| 排队中 | 等待进入交易 | 是 | 是 | 是 |
| 正在交易 | 已进入线下交易 | 是 | 否 | 否 |
| 重新排队 | 交易失败后进入队尾 | 是 | 是 | 是 |
| 已撤销 | 买家主动退出 | 否 | 否 | 否 |
| 已作废 | 卖家终结意向 | 否 | 否 | 否 |
| 已成功 | 交易成功 | 否 | 否 | 否 |
4.5 买家意向状态转换
stateDiagram-v2
[*] --> 排队中: 提交购买意向
排队中 --> 正在交易: 卖家开始交易
排队中 --> 已撤销: 买家主动撤销
正在交易 --> 已成功: 卖家确认交易成功
正在交易 --> 已作废: 卖家确认失败并作废
正在交易 --> 重新排队: 卖家确认失败并重新排队
重新排队 --> 排队中: 进入队尾
五、异常场景与边界处理
5.1 页面打开后商品状态发生变化
场景： 买家打开页面，页面显示商品在售；卖家在后台开始与队首买家交易，商品进入冻结状态；原买家点击提交购买意向。
处理：
后端必须重新判断商品状态。如果商品已经冻结，拒绝本次提交。
前端提示：商品状态已发生变化，请刷新页面后重试。
5.2 多名买家同时提交意向
系统按照后端实际成功处理的提交时间确定先后顺序。 后端负责并发控制、商品状态校验、排队顺序、重复意向控制。 买家不需要了解其他买家的具体信息。
5.3 买家重复点击提交
- **前端：**点击后按钮进入加载状态，禁止重复点击。
- **后端：**再次检查是否已经存在有效意向。即使前端重复请求，也不能产生两条有效意向。
5.4 买家长时间不完成线下交易
买家进入交易状态后：
- 商品保持冻结
- 买家不能修改信息
- 买家不能自行撤销
由卖家最终确认交易成功或者交易失败。
5.5 交易失败并重新排队
卖家标记交易失败后，可以将当前意向重新排队，该意向进入队尾。
- 队列还有其他买家：自动递补下一位队首买家进入交易，商品继续保持冻结状态。
- 队列为空：商品恢复在售，等待新的买家提交购买意向。
5.6 交易失败并作废
卖家选择作废，当前意向终结，口令码失效。系统继续检查其他排队意向。
5.7 商品交易成功
卖家确认交易成功后：
- 商品进入已下架状态
- 商品进入历史商品
- 当前意向交易成功
- 相关未完成意向终结
- 相关口令码失效
- 买家不能再提交该商品购买意向
六、页面导航与前后端职责
6.1 页面导航关系
flowchart LR
A["BUY‑01 商品浏览首页"] --> B["BUY‑02 商品详情页"]
B --> C["BUY‑03 购买意向提交页"]
C --> D["BUY‑04 提交成功页"]
D --> E["BUY‑05 意向口令码管理页"]
A --> E
E --> F["BUY‑06 意向详情/状态页"]
F --> E
6.2 页面跳转说明
| 当前页面 | 操作 | 目标页面 |
|---|---|---|
| BUY‑01 | 查看商品详情 | BUY‑02 |
| BUY‑02 | 提交购买意向 | BUY‑03 |
| BUY‑03 | 提交成功 | BUY‑04 |
| BUY‑04 | 管理购买意向 | BUY‑05 |
| BUY‑01 | 管理购买意向 | BUY‑05 |
| BUY‑05 | 口令码验证成功 | BUY‑06 |
| BUY‑06 | 返回 | BUY‑05 |
6.3 前端职责
买家前端负责：
- 页面展示
- 表单输入
- 基础表单校验
- 商品状态展示
- 按钮状态控制
- 错误提示
- 口令码一次性展示
- 排队位次展示
- 页面跳转
- 防止重复提交
6.4 后端职责
后端负责：
- 商品状态最终校验
- 购买意向创建
- 同商品同手机号重复意向限制
- 队列管理
- 先到先得排序
- 口令码生成
- 口令码验证
- 买家意向状态管理
- 商品状态流转
- 交易结果处理
- 失败后的自动递补
- 数据持久化
- 并发控制
七、本次迭代范围与验收标准
7.1 本次迭代完成内容
本次迭代属于：需求分析 & 原型设计阶段
本次完成：
- 买家角色与权限定义
- 买家页面清单
- 页面功能设计
- 页面交互规则
- 表单字段定义
- 表单校验规则
- 异常提示文案
- 口令码机制
- 购买意向排队机制
- 商品状态设计
- 买家意向状态设计
- 买家业务流程
- 异常场景
- 页面导航
- 前后端职责划分
- 买家端验收标准
7.2 买家端验收标准
| 编号 | 验收内容 | 预期结果 |
|---|---|---|
| BUY‑AC‑01 | 匿名访问首页 | 无需注册和登录即可访问 |
| BUY‑AC‑02 | 查看当前商品 | 正确显示名称、描述、图片和价格 |
| BUY‑AC‑03 | 商品在售 | 可以提交购买意向 |
| BUY‑AC‑04 | 商品冻结 | 可以查看但不能提交意向 |
| BUY‑AC‑05 | 无在售商品 | 显示暂无在售商品 |
| BUY‑AC‑06 | 姓名为空 | 阻止提交并提示 |
| BUY‑AC‑07 | 电话为空 | 阻止提交并提示 |
| BUY‑AC‑08 | 正常提交成功 | 生成唯一口令码 |
| BUY‑AC‑09 | 重复提交 | 同商品同手机号不能重复提交 |
| BUY‑AC‑10 | 查询口令码 | 正确查询本人意向 |
| BUY‑AC‑11 | 查看排队位次 | 正确显示本人位次 |
| BUY‑AC‑12 | 修改联系信息 | 修改成功且排队顺序不变 |
| BUY‑AC‑13 | 排队中撤销 | 成功退出队列 |
| BUY‑AC‑14 | 交易中修改 | 系统拒绝修改 |
| BUY‑AC‑15 | 交易中撤销 | 系统拒绝撤销 |
| BUY‑AC‑16 | 交易失败重新排队 | 原口令码继续有效并进入队尾 |
| BUY‑AC‑17 | 交易失败作废 | 当前意向和口令码失效 |
| BUY‑AC‑18 | 交易成功 | 商品下架 |
| BUY‑AC‑19 | 商品状态发生变化 | 后端重新校验并返回最新状态 |
| BUY‑AC‑20 | 重复点击提交 | 不产生重复有效意向 |
| BUY‑AC‑21 | 网络异常 | 显示错误提示并允许重试 |
八、需求边界与最终总结
8.1 本版本明确不包含
本 MVP 买家端不包含：
- 买家注册
- 买家登录
- 在线支付
- 物流配送
- 商品评价
- 消息通知
- 短信通知
- 口令码找回
- 买家之间的信息查看
- 自动刷新商品状态
8.2 关键业务约束总结
商品 同一时间只允许一件商品处于在售状态。 商品成功交易后下架，卖家才可以继续发布下一件商品。
买家 买家无需注册，通过口令码管理购买意向。
排队 购买意向按照提交时间先后顺序排队。卖家无权跳过队首买家选择其他买家进行交易。
冻结 商品不会因为买家提交意向而立即冻结。 只有卖家手动选择队首买家开始交易后：队首买家进入交易 + 商品自动冻结。
交易失败 交易失败后：卖家决定当前意向“作废”或“重新排队”。 重新排队后：当前意向进入队尾，原口令码继续有效。
- 如果还有其他买家：系统自动递补下一位队首买家进入交易。
- 如果没有其他买家：商品恢复在售。
交易成功 交易成功后：商品下架，当前交易完成，相关意向终结。
8.3 买家端最终业务流程
flowchart TD
A["匿名浏览当前商品"] --> B{商品是否在售?}
B -- 是 --> C["填写姓名 + 联系电话"]
C --> D["提交购买意向"]
D --> E["生成一次性口令码"]
E --> F["进入排队"]
F --> G["等待卖家处理"]
G --> H["卖家选择队首买家开始交易"]
H --> I["买家进入交易"]
I --> J["商品自动冻结"]
J --> K["线下交易"]
K --> L{交易结果}
L -- 成功 --> M["商品下架"]
L -- 失败 --> N["卖家处理当前意向"]
N --> O{"处理方式"}
O -- 作废 --> P["意向终结"]
O -- 重新排队 --> Q["进入队尾"]
Q --> R["自动递补下一位"]
R --> S{"队列是否有人"}
S -- 有 --> H
S -- 无 --> T["商品恢复在售"]
8.4 最终设计原则
本次买家前端设计最终遵循以下核心原则： 免注册、单商品、先到先得、线下交易、卖家控制交易、系统自动维护状态。
其中最重要的业务关系为：
- 提交购买意向 ≠ 商品冻结
- 卖家开始交易 = 队首买家进入交易 + 商品自动冻结
- 交易失败 = 作废或重新排队
- 重新排队 = 原口令码继续有效 + 进入队尾
- 交易成功 = 商品下架 + 当前意向终结