docs: add merged venue miniapp spec and plan
This commit is contained in:
gqt
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,412 @@
|
|||||||
|
# 合并版场馆小程序设计
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
|
||||||
|
当前有两套独立系统：
|
||||||
|
|
||||||
|
- 冰场馆小程序：前端为 uni-app 微信小程序，后端为 Django，部署在 `https://venue.test.chatgqt.top/`。
|
||||||
|
- 综合场馆小程序：前端为 uni-app 微信小程序，后端为 Django，部署在 `https://venue2.test.chatgqt.top/`。
|
||||||
|
|
||||||
|
两个项目的后端、数据库、Django admin、CI/CD 都保持独立。本次只合并小程序端，在 `/Volumes/ExternalStorageA/project/2026.5/体育场馆/场馆小程序` 下新增合并版小程序项目。
|
||||||
|
|
||||||
|
两套旧小程序当前都配置同一个微信小程序 `appid`：`wx516b3e0d9940c788`。合并版继续沿用该 `appid`，不引入新的微信小程序身份。
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
|
||||||
|
构建一个合并版 uni-app 微信小程序：
|
||||||
|
|
||||||
|
- 用户首次进入时选择“冰场馆”或“综合场馆”。
|
||||||
|
- 小程序内可以切换当前场馆。
|
||||||
|
- 两个场馆的业务页面、登录态、API 请求和后端数据完全隔离。
|
||||||
|
- 不合并、不改造两个 Django 后端、数据库、Django admin 和后端 CI/CD。
|
||||||
|
- 新项目能独立安装依赖并构建微信小程序产物。
|
||||||
|
|
||||||
|
## 非目标
|
||||||
|
|
||||||
|
- 不统一两个后端接口协议。
|
||||||
|
- 不迁移或合并会员数据、订单数据、课程数据、会员卡数据。
|
||||||
|
- 不改造 Django admin。
|
||||||
|
- 不新增统一后台或网关服务。
|
||||||
|
- 不强制保留旧小程序的底部四个 Tab 结构。
|
||||||
|
- 不重做业务页面视觉设计，只做必要的入口、切换和隔离改造。
|
||||||
|
|
||||||
|
## 推荐方案
|
||||||
|
|
||||||
|
采用“模块隔离合并”方案。
|
||||||
|
|
||||||
|
新项目保留两个业务模块：
|
||||||
|
|
||||||
|
- `ice`：冰场馆模块。
|
||||||
|
- `comprehensive`：综合场馆模块。
|
||||||
|
|
||||||
|
每个模块保留自己的页面、API、状态管理、业务工具和资源。公共层只负责场馆选择、当前场馆持久化、跨模块跳转和基础应用配置。
|
||||||
|
|
||||||
|
该方案的核心取舍是：牺牲一部分目录重复，换取后端隔离、登录态隔离、支付隔离和后续维护清晰度。
|
||||||
|
|
||||||
|
## 工程结构
|
||||||
|
|
||||||
|
新项目目录：
|
||||||
|
|
||||||
|
```text
|
||||||
|
/Volumes/ExternalStorageA/project/2026.5/体育场馆/场馆小程序/
|
||||||
|
miniprogram/
|
||||||
|
package.json
|
||||||
|
vite.config.js
|
||||||
|
.env
|
||||||
|
.env.example
|
||||||
|
src/
|
||||||
|
App.vue
|
||||||
|
main.js
|
||||||
|
manifest.json
|
||||||
|
pages.json
|
||||||
|
uni.scss
|
||||||
|
pages/
|
||||||
|
venue-select/
|
||||||
|
index.vue
|
||||||
|
ice/
|
||||||
|
home/
|
||||||
|
courses/
|
||||||
|
bookings/
|
||||||
|
profile/
|
||||||
|
activities/
|
||||||
|
comprehensive/
|
||||||
|
home/
|
||||||
|
courses/
|
||||||
|
bookings/
|
||||||
|
profile/
|
||||||
|
activities/
|
||||||
|
private/
|
||||||
|
tickets/
|
||||||
|
orders/
|
||||||
|
pay/
|
||||||
|
modules/
|
||||||
|
ice/
|
||||||
|
api/
|
||||||
|
stores/
|
||||||
|
utils/
|
||||||
|
comprehensive/
|
||||||
|
api/
|
||||||
|
stores/
|
||||||
|
utils/
|
||||||
|
components/
|
||||||
|
stores/
|
||||||
|
venue.js
|
||||||
|
utils/
|
||||||
|
venue.js
|
||||||
|
styles/
|
||||||
|
variables.scss
|
||||||
|
static/
|
||||||
|
ice/
|
||||||
|
comprehensive/
|
||||||
|
```
|
||||||
|
|
||||||
|
`pages` 放小程序实际路由页面，`modules` 放模块专属 API、状态和工具。页面通过模块专属路径导入业务能力，避免复用同名全局 API。
|
||||||
|
|
||||||
|
## 路由设计
|
||||||
|
|
||||||
|
`pages.json` 的第一个页面为：
|
||||||
|
|
||||||
|
```text
|
||||||
|
pages/venue-select/index
|
||||||
|
```
|
||||||
|
|
||||||
|
旧页面迁移时统一加场馆前缀：
|
||||||
|
|
||||||
|
```text
|
||||||
|
pages/ice/home/index
|
||||||
|
pages/ice/courses/index
|
||||||
|
pages/ice/courses/detail
|
||||||
|
pages/ice/bookings/index
|
||||||
|
pages/ice/bookings/detail
|
||||||
|
pages/ice/profile/index
|
||||||
|
pages/ice/profile/cards
|
||||||
|
pages/ice/profile/card-history
|
||||||
|
pages/ice/profile/detail
|
||||||
|
pages/ice/activities/detail
|
||||||
|
|
||||||
|
pages/comprehensive/home/index
|
||||||
|
pages/comprehensive/courses/index
|
||||||
|
pages/comprehensive/courses/detail
|
||||||
|
pages/comprehensive/courses/confirm
|
||||||
|
pages/comprehensive/bookings/index
|
||||||
|
pages/comprehensive/bookings/course-detail
|
||||||
|
pages/comprehensive/bookings/private-detail
|
||||||
|
pages/comprehensive/profile/index
|
||||||
|
pages/comprehensive/profile/detail
|
||||||
|
pages/comprehensive/profile/orders
|
||||||
|
pages/comprehensive/profile/tickets
|
||||||
|
pages/comprehensive/profile/balance
|
||||||
|
pages/comprehensive/activities/index
|
||||||
|
pages/comprehensive/activities/detail
|
||||||
|
pages/comprehensive/private/index
|
||||||
|
pages/comprehensive/private/confirm
|
||||||
|
pages/comprehensive/tickets/index
|
||||||
|
pages/comprehensive/orders/detail
|
||||||
|
pages/comprehensive/pay/index
|
||||||
|
```
|
||||||
|
|
||||||
|
页面内所有 `uni.navigateTo`、`uni.redirectTo`、`uni.reLaunch`、`uni.switchTab` 目标都改为带模块前缀的路径。
|
||||||
|
|
||||||
|
由于用户没有要求保留旧 Tab，合并版可以先不配置全局 `tabBar`。模块内通过页面入口和按钮跳转完成导航。这样能避免一个小程序只能有一套全局 tabBar 带来的耦合。
|
||||||
|
|
||||||
|
## 场馆选择与切换
|
||||||
|
|
||||||
|
公共场馆状态使用 Pinia store 和本地存储：
|
||||||
|
|
||||||
|
```text
|
||||||
|
CURRENT_VENUE_KEY = "CURRENT_VENUE"
|
||||||
|
```
|
||||||
|
|
||||||
|
可选值：
|
||||||
|
|
||||||
|
```text
|
||||||
|
ice
|
||||||
|
comprehensive
|
||||||
|
```
|
||||||
|
|
||||||
|
流程：
|
||||||
|
|
||||||
|
1. 用户首次进入 `pages/venue-select/index`。
|
||||||
|
2. 如果本地已有 `CURRENT_VENUE`，页面可以展示当前场馆并提供继续进入或切换。
|
||||||
|
3. 用户选择场馆后，写入 `CURRENT_VENUE`。
|
||||||
|
4. 根据场馆跳转到对应首页：
|
||||||
|
- 冰场馆：`/pages/ice/home/index`
|
||||||
|
- 综合场馆：`/pages/comprehensive/home/index`
|
||||||
|
5. 小程序内的切换入口跳回 `pages/venue-select/index` 或直接调用公共切换方法。
|
||||||
|
6. 切换当前场馆不清除另一套 token，用户切回原场馆后保持该后端的登录态。
|
||||||
|
|
||||||
|
建议在两个模块的“我的/会员中心”页面添加“切换场馆”入口，跳转到 `/pages/venue-select/index`。
|
||||||
|
|
||||||
|
## API 与环境变量
|
||||||
|
|
||||||
|
两个后端使用独立 baseURL：
|
||||||
|
|
||||||
|
```text
|
||||||
|
VITE_ICE_API_BASE_URL=https://venue.test.chatgqt.top
|
||||||
|
VITE_COMPREHENSIVE_API_BASE_URL=https://venue2.test.chatgqt.top
|
||||||
|
```
|
||||||
|
|
||||||
|
冰场馆请求封装放在：
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/modules/ice/api/request.js
|
||||||
|
```
|
||||||
|
|
||||||
|
综合场馆请求封装放在：
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/modules/comprehensive/api/request.js
|
||||||
|
```
|
||||||
|
|
||||||
|
两个模块都可以继续使用后端现有响应协议 `{ code, data, message }`，但错误归一化逻辑不共用。这样可以保留冰场馆对 `40002` 资料完善、`40003` 绑定冲突等错误码的处理，也保留综合场馆上传、支付、订单相关的现有处理。
|
||||||
|
|
||||||
|
Vite H5 开发代理可配置两个前缀：
|
||||||
|
|
||||||
|
```text
|
||||||
|
/ice-api -> VITE_ICE_API_BASE_URL
|
||||||
|
/comprehensive-api -> VITE_COMPREHENSIVE_API_BASE_URL
|
||||||
|
```
|
||||||
|
|
||||||
|
微信小程序构建时直接使用完整后端 URL。
|
||||||
|
|
||||||
|
## 登录态隔离
|
||||||
|
|
||||||
|
冰场馆保留：
|
||||||
|
|
||||||
|
```text
|
||||||
|
ICE_MEMBER_TOKEN
|
||||||
|
ICE_MEMBER_TOKEN_EXPIRES_AT
|
||||||
|
```
|
||||||
|
|
||||||
|
综合场馆保留：
|
||||||
|
|
||||||
|
```text
|
||||||
|
COMPREHENSIVE_VENUE_TOKEN
|
||||||
|
```
|
||||||
|
|
||||||
|
两个模块各自调用 `uni.login({ provider: "weixin" })`。登录得到的 code 只提交给当前模块对应后端：
|
||||||
|
|
||||||
|
- 冰场馆：`https://venue.test.chatgqt.top/api/auth/wechat-login`
|
||||||
|
- 综合场馆：`https://venue2.test.chatgqt.top/api/auth/wechat-login`
|
||||||
|
|
||||||
|
因为合并版沿用旧项目共同的 `appid`，不需要为新 `appid` 改两个后端微信登录配置。
|
||||||
|
|
||||||
|
## 支付隔离
|
||||||
|
|
||||||
|
综合场馆的 `pages/comprehensive/pay/index` 继续只使用综合场馆模块 API。微信支付参数由综合场馆后端生成，前端只调用 `uni.requestPayment`。
|
||||||
|
|
||||||
|
冰场馆模块不复用综合场馆订单和支付 API。任何支付相关跳转都必须保持在 `pages/comprehensive/*` 路由内。
|
||||||
|
|
||||||
|
## 样式与资源
|
||||||
|
|
||||||
|
全局 `styles/variables.scss` 采用两套项目共有变量，并以综合场馆版本为基础补齐冰场馆需要的变量和 mixin：
|
||||||
|
|
||||||
|
- `$bg-color-main`
|
||||||
|
- `$bg-color-soft`
|
||||||
|
- `$bg-color-hover`
|
||||||
|
- `$bg-color-panel`
|
||||||
|
- `$text-color-*`
|
||||||
|
- `$color-primary`
|
||||||
|
- `$color-success`
|
||||||
|
- `$color-warning`
|
||||||
|
- `$color-danger`
|
||||||
|
- `$border-*`
|
||||||
|
- `$spacing-*`
|
||||||
|
- `minimal-card`
|
||||||
|
- `text-ellipsis`
|
||||||
|
|
||||||
|
全局 `App.vue` 保留基础页面样式、按钮 reset、容器类、状态 badge、固定底部操作栏等公共规则。页面级样式随页面复制，减少重写成本。
|
||||||
|
|
||||||
|
静态资源按模块隔离：
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/static/ice/tab/*
|
||||||
|
src/static/comprehensive/tab/*
|
||||||
|
```
|
||||||
|
|
||||||
|
如果不配置全局 tabBar，旧 tab 图标只作为后续模块内导航备用资源。
|
||||||
|
|
||||||
|
## 文件迁移策略
|
||||||
|
|
||||||
|
复制时排除：
|
||||||
|
|
||||||
|
- `node_modules`
|
||||||
|
- `dist`
|
||||||
|
- `.git`
|
||||||
|
- `.idea`
|
||||||
|
- `.DS_Store`
|
||||||
|
- 后端目录
|
||||||
|
- 旧项目 `.env` 中的临时 frp 地址
|
||||||
|
|
||||||
|
优先以综合场馆小程序为工程基线，因为它已有 Pinia store、上传、支付、订单等更完整能力。冰场馆页面和 API 迁入独立模块。
|
||||||
|
|
||||||
|
所有旧的 `@/api/<module>` 导入都改为模块路径：
|
||||||
|
|
||||||
|
```text
|
||||||
|
@/modules/ice/api/<module>
|
||||||
|
@/modules/comprehensive/api/<module>
|
||||||
|
```
|
||||||
|
|
||||||
|
综合场馆 `defineStore("session")` 改为专属 ID：
|
||||||
|
|
||||||
|
```text
|
||||||
|
defineStore("comprehensiveVenueSession")
|
||||||
|
```
|
||||||
|
|
||||||
|
如果冰场馆新增 store，也使用 `iceVenueSession`、`iceVenueProfile` 这类 `iceVenue` 前缀。
|
||||||
|
|
||||||
|
## 错误处理
|
||||||
|
|
||||||
|
场馆选择页：
|
||||||
|
|
||||||
|
- 本地值不是 `ice` 或 `comprehensive` 时视为未选择。
|
||||||
|
- 跳转失败时展示 toast，并停留在选择页。
|
||||||
|
|
||||||
|
API 请求：
|
||||||
|
|
||||||
|
- 401 或后端登录过期错误只清理当前模块 token。
|
||||||
|
- 网络错误只影响当前模块页面。
|
||||||
|
- 切换场馆不触发任何后端请求，避免误清理另一模块登录态。
|
||||||
|
|
||||||
|
登录：
|
||||||
|
|
||||||
|
- `uni.login` 未返回 code 时提示用户重试。
|
||||||
|
- 后端返回绑定冲突、资料未完善等错误时沿用模块现有页面状态处理。
|
||||||
|
|
||||||
|
支付：
|
||||||
|
|
||||||
|
- 支付失败或取消只影响综合场馆订单页面。
|
||||||
|
- 不新增跨场馆支付状态。
|
||||||
|
|
||||||
|
## 测试与验收
|
||||||
|
|
||||||
|
基础验证：
|
||||||
|
|
||||||
|
- 在 `场馆小程序/miniprogram` 执行 `npm install`。
|
||||||
|
- 执行 `npm run build:mp-weixin`，确认能生成微信小程序产物。
|
||||||
|
|
||||||
|
路由验证：
|
||||||
|
|
||||||
|
- 首次进入展示场馆选择页。
|
||||||
|
- 选择冰场馆后进入 `/pages/ice/home/index`。
|
||||||
|
- 选择综合场馆后进入 `/pages/comprehensive/home/index`。
|
||||||
|
- 两个模块内主要页面跳转不再引用旧的 `/pages/home/index` 等无前缀路径。
|
||||||
|
|
||||||
|
API 验证：
|
||||||
|
|
||||||
|
- 冰场馆页面请求使用 `VITE_ICE_API_BASE_URL`。
|
||||||
|
- 综合场馆页面请求使用 `VITE_COMPREHENSIVE_API_BASE_URL`。
|
||||||
|
- 冰场馆 token 不会出现在综合场馆请求头中。
|
||||||
|
- 综合场馆 token 不会出现在冰场馆请求头中。
|
||||||
|
|
||||||
|
登录验证：
|
||||||
|
|
||||||
|
- 冰场馆登录后写入 `ICE_MEMBER_TOKEN`。
|
||||||
|
- 综合场馆登录后写入 `COMPREHENSIVE_VENUE_TOKEN`。
|
||||||
|
- 切换场馆不会删除另一场馆 token。
|
||||||
|
|
||||||
|
支付验证：
|
||||||
|
|
||||||
|
- 综合场馆支付页仍只调用综合场馆订单和支付 API。
|
||||||
|
- 冰场馆页面没有误跳到综合支付页。
|
||||||
|
|
||||||
|
微信后台上线前检查：
|
||||||
|
|
||||||
|
- 微信小程序 request 合法域名包含 `venue.test.chatgqt.top`。
|
||||||
|
- 微信小程序 request 合法域名包含 `venue2.test.chatgqt.top`。
|
||||||
|
- 如综合场馆支付上线，需要确认微信支付商户、回调和综合场馆后端配置保持现状。
|
||||||
|
|
||||||
|
## 难度
|
||||||
|
|
||||||
|
整体难度为中等偏上。
|
||||||
|
|
||||||
|
主要工作量不是新增业务，而是批量迁移：
|
||||||
|
|
||||||
|
- 页面路径加模块前缀。
|
||||||
|
- 页面内跳转路径同步修改。
|
||||||
|
- API import 路径改为模块专属路径。
|
||||||
|
- 两套样式和公共组件合并。
|
||||||
|
- 验证两个模块的登录态、请求、支付不会串线。
|
||||||
|
|
||||||
|
## 风险与缓解
|
||||||
|
|
||||||
|
路由漏改：
|
||||||
|
|
||||||
|
- 使用全文搜索检查旧路径：`/pages/home`、`/pages/courses`、`/pages/bookings`、`/pages/profile`、`/pages/pay`。
|
||||||
|
- 构建后通过主要路径手动跳转验证。
|
||||||
|
|
||||||
|
API 串线：
|
||||||
|
|
||||||
|
- 禁止使用全局 `src/api/request.js`。
|
||||||
|
- 每个模块保留独立 `request.js` 和独立 env 变量。
|
||||||
|
- 验证请求 URL 和 Authorization token。
|
||||||
|
|
||||||
|
登录态污染：
|
||||||
|
|
||||||
|
- 保留并强化 token key 命名空间。
|
||||||
|
- 401 只清理当前模块 token。
|
||||||
|
|
||||||
|
样式互相影响：
|
||||||
|
|
||||||
|
- 公共样式只放基础 reset 和共用工具类。
|
||||||
|
- 模块页面样式尽量保留在单文件组件内。
|
||||||
|
|
||||||
|
支付误接：
|
||||||
|
|
||||||
|
- 支付页面只存在于 `pages/comprehensive/pay/index`。
|
||||||
|
- 支付 API 只从 `src/modules/comprehensive/api/order.js` 导入。
|
||||||
|
|
||||||
|
微信后台配置遗漏：
|
||||||
|
|
||||||
|
- 上线前将两个后端域名都加入合法域名。
|
||||||
|
- 因沿用旧 `appid`，不新增后端微信登录配置变更。
|
||||||
|
|
||||||
|
## 交付结果
|
||||||
|
|
||||||
|
完成后应得到一个新的合并版小程序项目：
|
||||||
|
|
||||||
|
```text
|
||||||
|
/Volumes/ExternalStorageA/project/2026.5/体育场馆/场馆小程序/miniprogram
|
||||||
|
```
|
||||||
|
|
||||||
|
它可以独立构建微信小程序。用户首次进入选择场馆，后续可在小程序内切换；两个场馆后端、登录态、支付和业务数据仍完全隔离。
|
||||||
Reference in New Issue
Block a user