# 咕咕嘎嘎论坛前端详细设计文档（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 **状态**：待评审