# 云仓视频溯源 · 微信小程序 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` | | 登录抽屉 | `components/LoginDrawer.vue` | 是 | 同上(与整页登录共用 `LoginPanel`) | 登录没有独立页面:它是一张从底部弹出的抽屉卡片([`src/components/LoginDrawer.vue`](src/components/LoginDrawer.vue)), 在首页 / 记录两个 tab 页各引入一次,状态由 [`src/composables/useLoginDrawer.ts`](src/composables/useLoginDrawer.ts) 共享。 **不会一进入小程序就弹出**:只有点页面里的「登录」按钮、进入需要登录的页面、或接口返回 401 时才弹(见上面「登录时机」)。 打开时隐藏原生 tabBar,登录成功后关闭并留在当前页。 登录面板([`src/components/LoginPanel.vue`](src/components/LoginPanel.vue))只有一种登录方式: - **账号登录**:用户名 / 手机号 / 邮箱 + 密码。 - 小程序的「微信一键登录」(`uni.login()` → `POST /api/web/auth/wechat/login`)已下线:后端移除了 `wechat_mp_accounts` 表与整套小程序 code2Session 逻辑,微信侧接入统一走 Web 端的「微信登录网关」(扫码登录 / 绑定微信)。 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 ` 和 `X-Subject-Id`(见 `src/api/client.ts`)。 - 401 清令牌,并按 `AUTH_POLICY.promptOnUnauthorized` 弹登录(不跳页);`400 subject_required` / `403 subject_expired` 由页面自己提示。 - 登录 / 退出后 `authVersion` 自增,页面 `watch` 它刷新或清空数据。 - 主体(租户)是设备与扫码记录的归属单位:小程序里只做切换,创建主体仍在 Web 端。 - 微信扫码登录 / 绑定微信走 Web 端的登录网关(`/api/web/auth/wechat-gateway/*`),小程序里没有扫码入口;视频回放仍未接入。 ## H5 预览(可选,方便不装开发者工具时看页面) ```bash npm run dev:h5 # http://127.0.0.1:7304 npm run build:h5 ``` H5 页面同样直连 `VITE_API_BASE`(后端未开 CORS,浏览器跨域会被拦;仅用于看静态样式)。