feat: fulfillment modes, MQ, admin status, docs; scrub compose secrets

Made-with: Cursor
2026-04-03 16:26:38 +08:00
parent 1f16966174
commit b4c5103fb3
56 changed files with 4088 additions and 3742 deletions
--- a/mengyastore-frontend/前端文档.md
+++ b/mengyastore-frontend/前端文档.md
@@ -0,0 +1,143 @@
+# 萌芽小店 · 前端（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`。
+
+## 开发命令
+
+```bash
+npm install
+npm run dev       # :5173
+npm run build     # dist/
+npm run preview
+```
+
+### 环境变量
+
+开发示例（`.env.development`）：
+
+```env
+VITE_API_BASE_URL=http://localhost:8080
+```
+
+生产部署设置实际 API 基地址（或同源反代可不设）。
+
+## 部署（静态资源）
+
+```nginx
+location / {
+    try_files $uri $uri/ /index.html;
+}
+location /api/ {
+    proxy_pass http://127.0.0.1:8080;
+}
+```
+
+---
+
+字体与色板以 `src/assets/styles.css` 及 Tailwind 主题为准；文档若与代码不一致，以仓库当前实现为准。