mengyastore/mengyastore-frontend/前端文档.md

萌芽小店 · 前端（mengyastore-frontend）

基于 Vue 3 + Vite + Tailwind CSS（Vite 插件） 的数字商品前端：商店、结算（含扫码收款演示）、管理后台、收藏、订单、聊天、PWA。

技术依赖

包	用途
vue ^3.x	框架
vite ^5.x	构建
@tailwindcss/vite	工具类样式
vue-router ^4.x	路由
pinia ^2.x	状态（与 reactive 并存）
axios ^1.6	HTTP
markdown-it ^14	商品描述
vite-plugin-pwa	PWA

目录结构

src/
├── assets/
│   ├── styles.css           # 全局样式、.ghost / .page-card / . form-field 等
│   └── payment/             # 支付宝/微信收款码 PNG（import 进 CheckoutPage）
├── router/index.js         # 路由；维护模式 beforeEach
├── modules/
│   ├── shared/
│   │   ├── api.js           # API 封装（含 fetchSystemStatus）
│   │   ├── auth.js          # 登录态、getLoginUrl
│   │   ├── fulfillment.js   # isFixedFulfillment、stockLabel、isSoldOutProduct
│   │   └── useWishlist.js
│   ├── store/
│   │   ├── StorePage.vue
│   │   ├── ProductDetail.vue
│   │   ├── CheckoutPage.vue # 响应式布局、支付渠道 Tab、订单号复制、收款图
│   │   └── components/ProductCard.vue
│   ├── admin/
│   │   ├── AdminPage.vue    # 侧边栏：商品/订单/聊天/设置/系统状态
│   │   └── components/
│   │       ├── AdminProductModal.vue   # 发货方式：卡密 | 固定内容
│   │       ├── AdminProductTable.vue
│   │       ├── AdminOrderTable.vue
│   │       ├── AdminChatPanel.vue
│   │       ├── AdminMaintenanceRow.vue
│   │       ├── AdminSMTPRow.vue
│   │       └── AdminSystemStatusPanel.vue
│   ├── user/MyOrdersPage.vue
│   ├── wishlist/WishlistPage.vue
│   ├── maintenance/MaintenancePage.vue
│   ├── auth/AuthCallback.vue
│   └── chat/ChatWidget.vue
└── App.vue                   # 顶栏：桌面横排导航；移动端汉堡菜单 + 下拉面板

路由

路径	组件	说明
/	StorePage	商品列表
/product/:id	ProductDetail	详情
/checkout/:id	CheckoutPage	结算（路径参数为商品 id）
/my/orders	MyOrdersPage	我的订单（建议登录）
/wishlist	WishlistPage	收藏
/admin	AdminPage	管理后台（token）
/auth/callback	AuthCallback	OAuth 回调
/maintenance	MaintenancePage	维护中

路由守卫

• 请求 GET /api/site/maintenance；维护中时跳转 /maintenance。
• 豁免：/maintenance、/wishlist、/admin、/auth/callback（与 router/index.js 保持一致）。

认证

1. 「萌芽账号登录」→ SproutGate 登录页，callback 回指本站。
2. Token 存 localStorage，authState 共享用户信息。
3. 需登录接口带 Authorization: Bearer <token>。

功能要点

商品与库存展示

• API 字段 fulfillmentType：card | fixed。
• fixed：列表/详情/卡片显示库存为 「不限」，不按 quantity===0 售罄。
• 工具函数：modules/shared/fulfillment.js。

管理后台 · 商品

• 卡密：多行输入，逐条对应 codes。
• 固定内容：大文本 fixedContent；保存后无需维护条数。

结算页（CheckoutPage）

• 栅格与表单单列适配窄屏。
• 下单成功后：应付金额、支付宝/微信/赞赏 本地图片 切换、订单号 一键复制、可选展开服务端 qrCodeUrl。
• 数量上限：卡密=min(库存, 每账号限购)；固定内容=仅每账号限购（若设置）。

顶栏（App.vue）

• md 及以上：横向按钮。
• 以下：汉堡按钮 + 全宽大标题项 + 遮罩；Escape 关闭；打开时锁 body 滚动。

系统状态

• AdminSystemStatusPanel 调用 GET /api/admin/system-status，展示后端/API、MySQL、Redis、RabbitMQ（需管理 Token）。

PWA

• vite-plugin-pwa：registerType: 'autoUpdate'，构建后生成 SW；根组件有更新 Toast 与 SplashScreen。

开发命令

npm install
npm run dev       # :5173
npm run build     # dist/
npm run preview

环境变量

开发示例（.env.development）：

VITE_API_BASE_URL=http://localhost:8080

生产部署设置实际 API 基地址（或同源反代可不设）。

部署（静态资源）

location / {
    try_files $uri $uri/ /index.html;
}
location /api/ {
    proxy_pass http://127.0.0.1:8080;
}

---

字体与色板以 src/assets/styles.css 及 Tailwind 主题为准；文档若与代码不一致，以仓库当前实现为准。