Главная Обзор Помощь
Вход
yangyi
/
ui_template
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Ветка: feature/forum-core
Ветки Метки
ui_template
/
demand.md

demand.md 15 KB
Постоянная ссылка История Исходник

咕咕嘎嘎论坛前端详细设计文档（v2.0）

修订说明：根据最新需求调整，底部导航变更为“首页”、“我的订单”、“我的信息”、“我的账户”。打赏支付仅使用钱包余额，采用即时扣款模式。细化帖子详情（专家信息、标签、往期命中）及订单状态逻辑。

1. 引言

本文档为“咕咕嘎嘎论坛”用户端前端的详细设计，基于最新确认的需求编写，指导开发人员使用 Vue 3 + Element Plus 进行工程实现。文档覆盖项目架构、路由、组件拆分、状态管理、样式、接口对接及关键业务流程。

2. 技术栈

类别 选型 说明
框架 Vue 3 (Composition API) 组合式 API，逻辑复用与类型推断
UI 组件库 Element Plus 提供统一的企业级 UI 组件
状态管理 Pinia Vue 3 官方推荐，模块化、TypeScript 友好
路由 Vue Router 4 SPA 路由管理
HTTP 客户端 Axios 拦截器封装、统一错误处理
CSS 预处理器 SCSS 变量、混入、嵌套
图标库 Element Plus Icons / 自定义 SVG 导航及功能图标
构建工具 Vite 快速开发与打包
适配方案 postcss-px-to-viewport (可选) H5 移动端适配，按需启用

3. 项目结构

4. 路由设计

底部导航四个主 Tab 对应路由，使用 meta.tab 标识：

路径 页面组件 Tab 标识 说明
/ Home home 首页（帖子列表、搜索）
/orders Orders orders 我的订单（打赏订单）
/notifications Notifications notifications 我的信息（系统消息）
/profile Profile profile 我的账户（个人中心）
/post/:id PostDetail - 帖子详情（从首页进入）
/wallet Wallet - 钱包（余额/充值/提现）
/edit-profile EditProfile - 修改个人信息
/page/privacy StaticPage - 隐私协议
/page/complaint StaticPage - 投诉反馈
/page/contact StaticPage - 联系客服
/page/faq StaticPage - 常见问题

注意：PostDetail 由首页点击进入，不在底部导航，返回时保留浏览位置。

5. 全局状态管理（Pinia）

userStore

  • state: userInfo (id, username, avatar, mobile, role, level, balance, isRealname), token
  • actions: fetchUserInfo(), updateBalance(amount), updateProfile(data), logout()
  • getters: isLoggedIn, levelBadge (黄金/钻石/大师)

postStore

  • state: posts, currentStatus (全部/公开/在售/命中/未命中), searchKeyword, pagination
  • actions: fetchPosts(status, keyword), fetchPostDetail(id), loadMore()

orderStore

  • state: orders, activeFilter (全部/未支付/已取消/已完成)
  • actions: fetchOrders(filter), createAndPayOrder(postId) (创建并即时支付), cancelOrder(id)

notificationStore

  • state: messages, unreadCount
  • actions: fetchNotifications(), markRead(id)

6. 组件设计

6.1 公共组件

BottomNav.vue

  • 底部固定栏，四个入口：首页、我的订单、我的信息、我的账户。
  • 图标使用 Element Plus Icons 或自定义 SVG，激活时高亮。
  • 监听 route.meta.tab 切换激活样式。

PostCard.vue

  • Props: post { id, title, expertName, tags, price, publishTime, viewCount, status, isTodayNew }
  • UI: 卡片展示标题、发布专家（可点击）、帖子标签（el-tag 列表）、价格、发布时间（相对时间）、查看人数图标。当日帖子显示“最新”角标。
  • 点击卡片跳转 /post/:id。

ExpertInfoCard.vue

  • Props: expert { name, avatar, level, realnameVerified, brief }
  • UI: 在详情页顶部展示专家头像、名称、等级徽章、实名认证标识、简介。可带关注按钮（暂不做）。

PayConfirm.vue

  • Props: visible, postTitle, amount, balance
  • Events: @confirm, @cancel
  • UI: el-dialog 模态框，标题“确认打赏”，展示内容：帖子标题、打赏金额、当前钱包余额。确认按钮带 loading，避免重复提交。不允许点击遮罩关闭。

CountdownTimer.vue

  • Props: endTime (时间戳)
  • Events: @timeout
  • UI: 显示 mm:ss 倒计时，归零触发事件。用于订单未支付倒计时（若存在）。

GlassBanner.vue

  • Props: text
  • UI: 毛玻璃效果欢迎语区域，背景半透明模糊。

MarqueeNotice.vue

  • Props: noticeText
  • UI: 水平滚动公告栏，点击弹出论坛声明弹窗（含“我已知晓”按钮）。

EmptyState.vue

  • Props: description
  • UI: 复用 el-empty，自定义图片与文字。

6.2 页面组件

Home.vue

  • 布局: 顶部 Logo 及论坛名（动态配置）→ 欢迎语（GlassBanner）→ 滚动公告（MarqueeNotice）→ 搜索栏与状态筛选 → 帖子列表（PostCard 列表）
  • 搜索栏: el-input 支持标题关键字，el-select 选择状态（全部/公开/在售/命中/未命中），搜索按钮或回车触发。
  • 帖子列表: 滚动加载（v-infinite-scroll）或分页，空状态使用 EmptyState。
  • 数据加载: onMounted 调用 postStore.fetchPosts。

PostDetail.vue

  • 路由参数: id
  • 布局: 专家信息卡片 → 帖子详情（标题、内容简介、免责声明）→ 付费内容区域（未打赏显示遮罩与锁图标，已打赏显示完整内容）→ 立即打赏按钮（余额足够时）→ 往期帖子列表
  • 专家信息: 使用 ExpertInfoCard 展示。
  • 立即打赏:
    • 点击时校验余额 userStore.balance >= post.price，不足则 ElMessage.warning('余额不足，请先充值') 并引导去钱包。
    • 余额充足则打开 PayConfirm 弹窗，确认后调用 orderStore.createAndPayOrder(postId)。
    • 支付成功：关闭弹窗，刷新帖子详情（付费内容可见），更新余额，提示“打赏成功”。
    • 支付失败（如并发余额不足）：弹窗提示错误信息，关闭弹窗。
  • 往期帖子列表: 展示该专家所有已过时效的帖子，每个条目显示标题、日期及命中性标签（el-tag：已命中/未命中）。

Orders.vue (我的订单)

  • 筛选栏: el-radio-group 或 el-tabs，选项：全部、未支付、已取消、已完成。
  • 订单列表: 每个订单卡片显示帖子标题、专家名、金额、状态、创建时间。对于状态为“未支付”且未超时的订单，可显示倒计时并提供“去支付”按钮（调用支付流程，但本项目打赏基本即时完成，此状态极少出现，保留以兼容未来扩展）。
  • 空状态: 无订单时使用 EmptyState。
  • 订单过期处理: 若存在未支付订单且已超时，自动显示“已过期”并置灰操作。

Notifications.vue (我的信息)

  • 消息类型: 系统通知，包括打赏成功、充值成功/失败、提现发起/成功/失败等。
  • 列表: 按时间倒序，每条消息显示图标、标题、内容摘要、时间戳。未读显示红点。
  • 交互: 点击消息可标记已读，无跳转。
  • 空状态: 无消息时“暂无任何消息通知”。

Profile.vue (我的账户)

  • 用户信息卡片: 头像（el-avatar）、用户名称、等级徽章、用户ID（右侧复制按钮，使用 navigator.clipboard.writeText）。
  • 功能菜单:
    • 钱包 → 路由 /wallet
    • 隐私协议 → /page/privacy
    • 投诉反馈 → /page/complaint
    • 联系客服 → /page/contact
    • 常见问题 → /page/faq
    • 修改我的信息 → /edit-profile
    • 设置（预留入口，可跳转至占位页面）
  • 使用 el-cell-group 构建菜单。

Wallet.vue

  • 余额展示: 大号字体，el-statistic 组件。
  • 充值/提现按钮: 点击后弹出 el-dialog，输入金额（充值：模拟增加余额；提现：提交申请，需后台审核，前端仅展示交互）。
  • 资金明细: 列表/表格显示时间、金额、类型（充值/提现/打赏支出）。无记录时显示空状态。
  • 充值/提现流程:
    • 充值：输入金额 → 确认 → 调接口（模拟支付）→ 成功后更新余额并记录明细。
    • 提现：输入金额 → 确认 → 调用提现申请接口 → 提示“提现申请已提交，等待处理”。
  • 注意：钱包页面展示充值订单和提现记录，不展示打赏订单（打赏订单在“我的订单”页）。

EditProfile.vue

  • 表单字段：头像（可上传）、名称、手机号码、修改密码（原密码、新密码、确认密码）、实名认证（如未认证显示认证入口，已认证显示已认证状态）。
  • 使用 el-form，提交后调用更新用户信息接口。
  • 头像上传：使用 el-upload 组件，限制大小和格式。

StaticPage.vue

  • 动态路由参数 type，根据类型渲染不同静态内容（隐私协议等）。目前为占位，内容由后端配置或前端硬编码占位文本。

7. 样式与主题

  • Element Plus 主题覆盖: SCSS 变量修改主色、圆角、阴影等，论坛风格偏向暖色或深蓝，具体与 UI 设计对齐。
  • 玻璃效果: 通过 backdrop-filter: blur(12px) 配合半透明背景实现。
  • 底部导航: 高度 50px，图标大小 24px，安全区适配 (padding-bottom: env(safe-area-inset-bottom))。
  • 帖子卡片: 轻微阴影 box-shadow: 0 2px 8px rgba(0,0,0,0.08)，圆角 8px。
  • 响应式: 最大宽度 750px 居中，适配移动端，PC 端显示居中窄版。

8. 网络请求封装 (Axios)

api/request.ts:

  • baseURL 来自环境变量。
  • 请求拦截器添加 Authorization token。
  • 响应拦截器：统一处理 code，非正常时 ElMessage.error；401 清除登录态并跳转登录页。
  • 封装通用 get/post/put/delete 方法。

9. 关键业务流程

9.1 搜索与状态筛选

  • 状态使用 el-select，选项：全部、公开、在售、命中、未命中。
  • 关键字使用 el-input，支持防抖 (300ms)。
  • 任一条件变化重新请求帖子列表，重置分页。
  • URL 同步 query 参数：?status=在售&keyword=xx。

9.2 打赏支付流程（钱包余额即时扣款）

  1. 详情页点击“立即打赏” → 前端判断余额是否充足。
  2. 充足则打开 PayConfirm 弹窗，展示价格和余额。
  3. 用户确认 → 调用 POST /api/orders/pay-direct (或合并创建与支付) 传入 postId，请求头携带幂等键 X-Request-Id。
  4. 后端原子操作：创建订单，扣减余额，记录流水，返回订单状态已完成。
  5. 前端处理：更新余额，关闭弹窗，刷新帖子详情使付费内容可见，显示“打赏成功”。
  6. 异常处理：余额不足或其他错误，后端返回 code 对应消息，前端提示，不关闭弹窗或关闭后提示。

由于是即时扣款，订单状态直接为“已完成”，不存在未支付状态，因此“订单过期时间”不适用。

9.3 我的订单状态展示

  • 筛选栏支持全部、未支付、已取消、已完成。
  • 正常打赏订单为“已完成”。
  • 若系统未来扩展其他支付方式或出现异常未支付订单，列表会包含相应状态。倒计时仅对未支付且有过期时间的订单显示。
  • 点击订单可查看详情（暂定不可操作）。

9.4 系统通知（我的信息）

  • 后端在某些操作后推送通知（如打赏成功、充值成功、提现状态变更）。
  • 前端定期拉取或使用轮询（或 WebSocket 但初期可简化为接口拉取）。
  • 未读消息数显示在底部导航“我的信息”Tab 上（el-badge）。
  • 点击消息标记已读。

9.5 钱包充值/提现

  • 充值：输入金额 → 确认 → 调用模拟支付接口 → 成功则增加余额并生成资金明细。
  • 提现：输入金额 → 确认 → 调用提现申请接口 → 后台审核，前端仅提示已提交。
  • 资金明细接口返回流水列表，支持分页。

9.6 “我已知晓”声明弹窗

  • 首次进入首页时，若无 localStorage 标记，自动弹出声明弹窗；点击“我已知晓”后标记并关闭。

10. 接口对接规范

所有接口返回统一结构：{ code: 200, message: "success", data: {...} }

关键接口列表：

接口 方法 说明
/api/posts GET 获取帖子列表，参数：status, keyword, page, size
/api/posts/:id GET 帖子详情，包含付费内容（如果已购买）
/api/posts/:id/pay POST 创建订单并支付，请求体：{ postId } (可省略)，header: X-Request-Id
/api/orders GET 我的订单列表，参数：status (all/unpaid/cancelled/completed)
/api/notifications GET 系统消息列表
/api/notifications/:id/read PUT 标记消息已读
/api/user/profile GET/PUT 获取/更新个人信息
/api/user/balance GET 获取余额
/api/wallet/recharge POST 充值，请求体：{ amount }
/api/wallet/withdraw POST 提现申请，请求体：{ amount }
/api/wallet/transactions GET 资金明细，参数：page, size
/api/config/site GET 获取网站名称、logo、公告等动态配置

分页格式：{ list: [], total: 100, page: 1, pageSize: 10 }

11. 错误处理与状态展示

  • 网络异常: Axios 拦截器统一 ElMessage.error('网络异常，请稍后重试')。
  • 业务错误: 如余额不足，在 catch 中解析 message 并提示。
  • 加载态: 列表使用 v-loading 或骨架屏 el-skeleton；按钮点击后 loading 禁止重复提交。
  • 空状态: 所有列表和数据区域使用 EmptyState 组件。
  • 认证失效: 401 时清除 token 并跳转登录页（登录页需补充实现，假定需登录）。

文档版本：v2.0
编写日期：2026-06-14
状态：待评审