liufumingren 8f1a8b7ddb feat(miniprogram): 新增 uni-app + Vue3 + TS 微信小程序
- 登录:微信一键登录(code2Session)+ 账号登录双 tab;个人中心为整页登录,其它页走抽屉
- 协议:登录前必须阅读并同意,版本号随登录上报落库
- 不强制登录:启动不弹窗,点功能或遇到 401 才提示(符合小程序审核)
- 页面:首页统计 / 扫码记录 / 个人中心;H5 预览端口 7304

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-21 00:47:16 +08:00

117 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 云仓视频溯源 · 微信小程序
uni-app + Vue3 + TypeScript + Vite 的微信小程序,复用后端 `backend/` 的用户端接口(`/api/web/*`)。
当前是基础脚手架:底部抽屉登录、首页统计、扫码记录、个人中心。
## 运行
```bash
cd miniprogram
npm install
npm run dev:mp-weixin # 产物在 dist/dev/mp-weixin,watch 模式
```
微信开发者工具 → 导入项目 → 选 `miniprogram/dist/dev/mp-weixin`,AppID 用你自己的(或测试号)。
本地联调时在「详情 → 本地设置」勾选 **不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书**。
发布:
```bash
npm run build:mp-weixin # 产物在 dist/build/mp-weixin
```
小程序 AppID 填在 [`src/manifest.json`](src/manifest.json) 的 `mp-weixin.appid`(`appid` 留空时开发者工具会让你选测试号)。
## 后端地址
小程序没有 Vite 同源代理,必须请求完整地址。`src/api/client.ts` 的规则:
- 配了 `VITE_API_BASE` → 用它;
- 没配 → 默认 `http://127.0.0.1:7300`(本机后端)。
本地需要改地址时,复制 [`.env.example`](.env.example) 为 `.env.development`(已被根 `.gitignore` 忽略):
```ini
VITE_API_BASE=http://127.0.0.1:7300
```
发布时用 `.env.production` 指向 **https** 域名,并在小程序后台「开发设置 → 服务器域名」把它加入 `request` 合法域名
(微信要求域名已备案,且不能带端口/路径)。
## 登录时机(小程序审核要求)
**不允许一打开就强制登录**,登录只在「用户点了需要登录的功能」或「接口真的返回 401」时出现。
策略集中在 [`src/config/auth.ts`](src/config/auth.ts):
| 配置 | 默认 | 说明 |
| --- | --- | --- |
| `pageGuards` | `['pages/records/index']` | 必须登录才能使用的页面 |
| `autoPromptOnEnter` | `true` | 进入 `pageGuards` 页面时弹一次登录(同一次进入不重复弹) |
| `apiRequireAuth` | `true` | 业务接口是否必须登录 |
| `promptOnUnauthorized` | `true` | 请求拿到 401 时是否自动弹登录 |
配套行为:
- `App.vue` 启动时**不做任何拦截**;首页对游客展示功能介绍 + 「登录 / 注册」按钮;
- 个人中心游客态展示欢迎卡片,点「登录 / 注册」跳整页登录(不自动跳转);
- 扫码记录属于 `pageGuards`:切到该 tab 才弹抽屉(关掉后本页不再自动弹,可点「登录查看」);
- 游客页面不会发需要登录的业务请求,所以不会出现「一进来就 401 → 弹窗」;
- 令牌过期(401)会清登录态并按 `promptOnUnauthorized` 弹登录。
## 页面与接口
| 页面 | 路径 | 游客可用 | 登录后接口 |
| --- | --- | --- | --- |
| 首页(统计) | `pages/index/index` | 是(功能介绍) | `GET /api/web/subjects`、`GET /api/web/stats` |
| 扫码记录 | `pages/records/index` | 否(`pageGuards`) | `GET /api/web/records`、`GET /api/web/devices` |
| 个人中心 | `pages/profile/index` | 是(欢迎卡片) | `GET /api/web/me`、`PUT /api/web/me`、`GET /api/web/subjects` |
| 登录(整页兜底) | `pages/login/index` | 是 | `GET /api/agreements/current`、`POST /api/web/auth/login`、`POST /api/web/auth/wechat/login` |
| 登录抽屉 | `components/LoginDrawer.vue` | 是 | 同上(与整页登录共用 `LoginPanel`) |
登录没有独立页面:它是一张从底部弹出的抽屉卡片([`src/components/LoginDrawer.vue`](src/components/LoginDrawer.vue)),
在首页 / 记录两个 tab 页各引入一次,状态由 [`src/composables/useLoginDrawer.ts`](src/composables/useLoginDrawer.ts) 共享。
**不会一进入小程序就弹出**:只有点页面里的「登录」按钮、进入需要登录的页面、或接口返回 401 时才弹(见上面「登录时机」)。
打开时隐藏原生 tabBar,登录成功后关闭并留在当前页。
登录面板有两个 tab([`src/components/LoginPanel.vue`](src/components/LoginPanel.vue)):
- **微信登录(默认,优先)**:点「微信一键登录」→ `uni.login()` 拿 code → `POST /api/web/auth/wechat/login`;
首次登录后端按 openid 自动建账号(`firstTime`),提示「已为你创建账号」;
- **账号登录**:用户名 / 手机号 / 邮箱 + 密码。
H5 / 开发者工具里 `uni.login` 拿不到 code,可设 `VITE_WX_MOCK_OPENID=<openid>` 走后端 mock(仅本地联调)。
H5 预览时接口走 Vite 的 `/api` 反代(`vite.config.ts` 的 `server.proxy`),不需要后端开 CORS。
**个人中心例外**:那里的「登录」跳整页登录 [`src/pages/login/index.vue`](src/pages/login/index.vue)(`navigateTo`),
用于抽屉在某些真机 / 低版本基础库上弹不出来的兜底;登录成功 `navigateBack` 回到个人中心并自动刷新。
个人中心页没有挂 `LoginDrawer`,401 也统一跳到整页登录(`useLoginDrawer` 里按当前路由判断)。
表单逻辑只有一份:[`src/components/LoginPanel.vue`](src/components/LoginPanel.vue)(抽屉与整页登录共用)。
登录前必须同意协议:
- 面板只显示一行「我已阅读并同意《用户协议》v1.0.0」,点协议名弹出**独立的协议弹窗**
[`src/components/AgreementDialog.vue`](src/components/AgreementDialog.vue)(不占登录面板高度);
- 弹窗正文是 `scroll-view`,**「我已阅读并同意」按钮在正文末尾**,不滑到最后点不到;
- 点完才打勾,勾选前登录按钮不可用;每次打开登录面都会清空勾选,需要重新阅读同意;
- 登录请求带 `client: 'mini_program'` + `agreements: [{ code, versionId }]`,后端校验版本并写入 `user_agreements`;
- 服务端返回 428 `agreement_required`(协议版本更新)时,面板会自动拉新正文并要求重新勾选。
## 约定
- 令牌与用户存在本地:`packs_token` / `packs_user`;当前主体 id 存在 `packs_subject_id`。
- 业务接口都会带 `Authorization: Bearer <user JWT>` 和 `X-Subject-Id`(见 `src/api/client.ts`)。
- 401 清令牌,并按 `AUTH_POLICY.promptOnUnauthorized` 弹登录(不跳页);`400 subject_required` / `403 subject_expired` 由页面自己提示。
- 登录 / 退出后 `authVersion` 自增,页面 `watch` 它刷新或清空数据。
- 主体(租户)是设备与扫码记录的归属单位:小程序里只做切换,创建主体仍在 Web 端。
- 微信一键登录走小程序自己的后端模块(`/api/web/auth/wechat/*`),与公众号扫码登录(`wechat_oauth`)分开;视频回放仍未接入。
## H5 预览(可选,方便不装开发者工具时看页面)
```bash
npm run dev:h5 # http://127.0.0.1:7304
npm run build:h5
```
H5 页面同样直连 `VITE_API_BASE`(后端未开 CORS,浏览器跨域会被拦;仅用于看静态样式)。