gqt/venue-miniapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: relocate docs into miniprogram/docs

Browse Source
This commit is contained in:
gqt
2026-07-12 19:57:37 +08:00
parent 2d7ecab28b
commit d17b646ae0
3 changed files with 0 additions and 2172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/merged-miniapp-verification.md
-77
View File
@@ -1,77 +0,0 @@
# 合并版场馆小程序验证记录
## 构建
- 命令：`npm run build:mp-weixin`
- 结果：通过，命令退出码为 0
- 产物：`miniprogram/dist/build/mp-weixin`
- 备注：构建日志包含 uni-app 版本提示和 uview-plus/Sass 弃用警告，未出现编译错误。
## 路由隔离
- 检查旧的无前缀页面路径：通过
- 冰场馆页面前缀：`pages/ice`
- 综合场馆页面前缀：`pages/comprehensive`
- `pages.json` 首个页面：`pages/venue-select/index`
- `pages.json` 页面数量：30
- 综合场馆页面数量：19
- 冰场馆页面数量：10
- 全局 `tabBar`：未配置
## API 隔离
- 冰场馆 baseURL：`VITE_ICE_API_BASE_URL`
- 综合场馆 baseURL：`VITE_COMPREHENSIVE_API_BASE_URL`
- 旧 `VITE_API_BASE_URL`：未使用
- 旧全局 API import：未发现
## 登录态隔离
- 冰场馆 token：`ICE_MEMBER_TOKEN`
- 冰场馆 token 过期时间：`ICE_MEMBER_TOKEN_EXPIRES_AT`
- 综合场馆 token：`COMPREHENSIVE_VENUE_TOKEN`
## 支付隔离
- `uni.requestPayment` 仅出现在 `pages/comprehensive/pay/index.vue`
- 综合场馆支付接口仅出现在 `modules/comprehensive/api/order.js`
- 冰场馆模块未引用综合场馆支付页或支付 API
## 自动化检查命令
```bash
cd /Volumes/ExternalStorageA/project/2026.5/体育场馆/场馆小程序/miniprogram
npm run build:mp-weixin
```
```bash
cd /Volumes/ExternalStorageA/project/2026.5/体育场馆/场馆小程序
rg -n "@/api|@/stores/session|@/utils/(date|money|status)|@/components/StatePanel.vue" miniprogram/src/pages miniprogram/src/modules
rg -n '\x27/pages/(home|courses|bookings|profile|activities|private|tickets|orders|pay)|"/pages/(home|courses|bookings|profile|activities|private|tickets|orders|pay)|`/pages/(home|courses|bookings|profile|activities|private|tickets|orders|pay)' miniprogram/src/pages
rg -n "VITE_API_BASE_URL" miniprogram/src/modules miniprogram/.env miniprogram/.env.example miniprogram/vite.config.js
node -e "const fs=require('fs'); const p=JSON.parse(fs.readFileSync('miniprogram/src/pages.json','utf8')); const paths=p.pages.map(x=>x.path); console.log(JSON.stringify({first: paths[0], total: paths.length, comprehensive: paths.filter(x=>x.startsWith('pages/comprehensive/')).length, ice: paths.filter(x=>x.startsWith('pages/ice/')).length, hasTabBar: Boolean(p.tabBar)}, null, 2));"
```
## 微信开发者工具烟测
当前终端环境未直接打开微信开发者工具执行人工烟测。上线或提审前需要在微信开发者工具中打开：
```text
/Volumes/ExternalStorageA/project/2026.5/体育场馆/场馆小程序/miniprogram/dist/build/mp-weixin
```
人工检查项：
- 首次进入展示“选择场馆”。
- 选择“冰场馆”进入 `pages/ice/home/index`。
- 选择“综合场馆”进入 `pages/comprehensive/home/index`。
- 两个模块的“会员中心/我的”可返回 `pages/venue-select/index` 切换场馆。
- 冰场馆页面请求域名为 `https://venue.test.chatgqt.top`。
- 综合场馆页面请求域名为 `https://venue2.test.chatgqt.top`。
- 综合场馆支付页仍由综合场馆后端生成支付参数。
## 上线前人工检查
- 微信 request 合法域名包含 `venue.test.chatgqt.top`。
- 微信 request 合法域名包含 `venue2.test.chatgqt.top`。
- 综合场馆支付商户、回调和综合场馆后端配置保持现状。
docs/superpowers/plans/2026-06-08-merged-venue-miniapp.md
-1683
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/specs/2026-06-08-merged-venue-miniapp-design.md
-412
View File
@@ -1,412 +0,0 @@
# 合并版场馆小程序设计
## 背景
当前有两套独立系统：
- 冰场馆小程序：前端为 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
```
它可以独立构建微信小程序。用户首次进入选择场馆，后续可在小程序内切换；两个场馆后端、登录态、支付和业务数据仍完全隔离。