66 KiB
WMS 微信小程序 · 开发清单
项目:
wms_mp_weixin(仓储管理系统 · 微信小程序端) 技术栈:uni-app 3(Vue 3 + Vite)+ TypeScript + uview-plus 3.8 主目标平台:微信小程序(同时可选编译 H5) 生成日期:2026-09-18
0. 当前状态速览
| 项 | 状态 | 说明 |
|---|---|---|
| uni-app + Vue3 + TS 工程 | ✅ 已完成 | CLI/Vite 工程,TS 6 + vue-tsc 3 |
| uview-plus UI 框架 | ✅ 已完成 | easycom 按需引入,实测仅打包所用组件 |
| 类型检查 / 双端构建 | ✅ 通过 | type-check、build:mp-weixin、build:h5 |
| 微信 AppID | ✅ 已配置 | wx31f8d1ee127bc64b,已实测写入产物 project.config.json |
| 应用名称 | ✅ 已配置 | WMS 小程序 |
| 按需注入 / 分包优化 | ✅ 已开启 | 产物 app.json 已含 lazyCodeLoading |
| 目录结构(第 2 节) | ✅ 已完成 | 已建 api / components / composables / store / utils / 分包目录 |
| 页面框架(tabBar) | ✅ 已完成 | 2 个底部 Tab:首页 / 我的(纯文字);「任务」「库存」页已按要求移除 |
| tabBar 图标 | ❌ 待补充 | 需本地图片 ≤ 40KB、81×81px |
| 分包(pages.json 注册) | 🚧 部分注册 | pagesA 已注册(当前放框架示例页);pagesB / pagesC 待业务页一起注册 |
| 请求封装(第 5 节) | ✅ 已完成 | utils/request.ts,对齐 new3,含 token 注入 / 响应头续期 / 401 处理 |
| 登录鉴权(第 6 节) | ✅ 已完成 | 账号密码登录 + 注册;登录入口在「我的」页头部(启动页为首页,不强制登录);401 按需引导登录 |
| 「我的」页结构 | ✅ 已完成(2026-09-22,10-17 增协议入口) | 菜单 + 二级页面:本页只留「登录入口 + 菜单 + 协议与隐私」;细项全收进 pages/mine/user-info(用户信息 / 待绑定 WMS 账号 / 微信资料 / 电脑端登录码 / 退出登录)。⚠️ 用户须知 / 隐私保护指引 不依赖登录,所以不能放二级页(未登录进不去),统一放本页 |
| Pinia 状态管理(第 8 节) | ✅ 已完成 | pinia@2.1.7(Vue 3.4 兼容版),见 store/modules/user.ts |
| 环境变量(第 11 节) | ✅ 已完成 | .env.development / .env.production:VITE_APP_BASE_API / VITE_APP_PLATFORM / VITE_APP_PROJECT |
| 静态路由表(阶段 1) | ✅ 已完成 | src/router/pages.ts:PAGE_REGISTRY(逻辑路径 → 物理页面 + auth 策略)+ PAGE_MAP;配置 npm run check:pages 一致性校验 |
| 菜单/权限 store(阶段 2) | ✅ 已完成 | src/router/entries.ts(菜单 × 路由表 → 入口树)+ store/modules/permission.ts;getInfo() 触发时机收口到「登录成功 / 启动带 token / 切换身份」 |
| 三态渲染组件(阶段 3) | ✅ 已完成 | composables/usePageAuth.ts + components/auth-gate/(public / optional / required)+ components/empty-state/(统一空态文案 + 重试);「去登录」收口到 goLogin() |
| 页面接入(阶段 4) | ✅ 已完成 | 首页九宫格改为 store 驱动(分组标题 + 子项两层渲染,空态走 empty-state);「我的」新增功能菜单 |
| 首页入口分段(2026-10-14,段名 10-17 改为「辅助工具」) | ✅ 已完成 | 动态菜单段(在前)+ 本地「辅助工具」段(固定在后),合成逻辑在 router/entries.ts 的 toHomeSections();「辅助工具」段 = common: true 的页面(计算器 / 条形码),与登录态、后端菜单、接口无关 ⇒ 未登录也一定显示(微信审核要求)。已删除原 pagesA/demo/public.vue(被计算器页取代) |
| 页面渲染框架 | 🚧 开发中(阶段 1、2、2.5、3、4 已完成) | 见第 12 节与《页面渲染框架-设计与任务清单.md》 |
| 身份(角色/仓库)展示 | ✅ 已完成 | 「我的」页登录后显示:姓名 / 身份类型 / 所属组织 / 员工 ID / 授权到期;数据来自 user.info 的 employees[],不改数据库 |
身份切换 changeRole |
🚧 已实现待联调 | 入口在「我的」页(多身份时出现);接口已实测存在,返回结构待后端确认 |
| 微信一键登录 | ✅ 已完成 | wechat.loginByCode(不是 user.loginByCode);AppID 运行时取(wx.getAccountInfoSync,适配开放平台模板多仓库);token 立即落地(未绑定也算免登录态);绑定可跳过、入口常驻「我的」页 |
| 微信资料(昵称/头像) | ✅ 已完成(2026-09-22) | wechat.updateInfo(改昵称)+ wechat.uploadHeadimg(传头像);走微信「头像昵称填写能力」(chooseAvatar + input type=nickname),头像经 utils/avatar.ts 裁剪转 PNG(<500K)后上传;入口仅未绑定态可见 |
| 我的登录码(电脑端登录) | ✅ 已完成(2026-09-22) | wechat.getMyLoginCode(无入参,码稳定不变);入口在「我的」页(需微信登录态);同时新增登录渠道记录 login_channel |
| 用户须知(协议文案) | ✅ 已完成(2026-09-23) | 弹窗抽为共享组件 components/agreement-modal/(agree 勾选 / view 只读);入口两处:登录面板勾选区 + 「我的」页(2026-10-17 由「用户信息」页移来,因为未登录时二级页不可达);正文后端下发(免登录按 AppID / 已登录按仓库),本地常量仅兜底 |
📄 配套文档:
页面渲染框架-设计与任务清单.md—— 菜单 / 权限 / 页面渲染的决策与任务清单(第 12 节为摘要) ⚠️ 已知坑:同时跑两个dev:mp-weixin进程会写坏产物,导致预览报ENOENT ... common/assets.js。详见第 9 节。
1. 工程与构建配置
-
填写微信 AppID ✅ 位置:
src/manifest.json→mp-weixin.appid,已填wx31f8d1ee127bc64b> 实测确认已写入产物dist/build/mp-weixin/project.config.json的appid字段。 -
补充应用基础信息 ✅
name=WMS 小程序、description=仓储管理系统 · 微信小程序端;versionName/versionCode保持1.0.0/100。 > 注意:manifest.json顶层的appid是 DCloud 应用标识,与微信 AppID 不是一个东西,保持为空即可。 -
确认
mp-weixin.projectname✅ 已设为wms_mp_weixin,实测已同步到产物project.config.json。 -
不要在
src下创建project.wx.json(实测结论,原「建议创建」已推翻) ⚠️ 文档提到src/project.wx.json(或src/project.config.json)可“自定义微信项目配置”, 但实测结论是「整体替换」而非「合并」:一旦创建该文件, uni-app 生成的project.config.json会被它完全覆盖, 连appid、setting、compileType、condition都会一并丢失, 后果是微信开发者工具里项目没有 AppID,无法预览。实测记录(uni-app 3.0.0-5020420260813003 CLI): | 状态 | 产物 `project.config.json` | |---|---| | 无该文件 | `appid` / `setting` / `compileType` / `projectname` / `condition` 全部正常生成 ✅ | | 有该文件 | **仅剩文件里写的字段**,其余全部丢失 ❌ | **结论:本项目不启用该文件,以 `manifest.json` 的 `mp-weixin` 节点作为唯一配置来源。** 如确需配置 manifest 未覆盖的字段(如 `packOptions.ignore`、`libVersion`), 必须把完整配置(含 `appid`、`setting`、`compileType`)全部写进去, 并接受 appid 两处维护的漂移风险。 -
开启小程序按需注入 ✅
src/manifest.json→mp-weixin.lazyCodeLoading: "requiredComponents"> 实测确认产物app.json已包含"lazyCodeLoading": "requiredComponents"。 -
开启分包优化 ✅
src/manifest.json→mp-weixin.optimization.subPackages: true注意:字段名是subPackages(驼峰),写成subpackages无效。 作用:分包目录下的静态资源与仅被单个分包引用的 js 不再计入主包体积。 > 当前尚无分包,实际收益需等第 3 节划分分包后体现。 -
确认
setting各项 ✅| 项 | 值 | 说明 | |---|---|---| | `urlCheck` | `false` | 仅控制**开发者工具内**是否校验安全域名。**不影响上传后的线上行为** —— 真机与线上始终由微信服务端校验域名白名单,所以提审不需要改它 | | `es6` | `true` | ES6 转 ES5(使用手势组件会被强制开启) | | `postcss` | `true` | 上传代码时样式自动补全 | | `minified` | `true` | 上传代码时自动压缩(不影响本地调试编译) | | `bigPackageSizeSupport` | `true` | 预览/真机调试时包体积上限提升到 4M | > 实测确认这 5 项均已写入产物 `project.config.json` 的 `setting`。 -
transformPx保持false✅ 该选项已废弃,仅部分平台生效,新项目不推荐开启(当前已是false,保持即可)。 -
配置
sitemap.json✅ 2026-10-17src/sitemap.json(构建后原样拷到产物根目录,已实测)→ 全部页面disallow: 内部仓储工具不应被微信搜索收录,也避免业务页面被外部检索到。json { "rules": [{ "action": "disallow", "page": "*" }] } -
不要提交个人调试配置 ✅ 微信开发者工具会在打开的产物目录生成
project.private.config.json; 因产物位于dist/(已在.gitignore中),无需额外处理。 若改为直接在src下调试,则需追加忽略规则。
2. 目录结构规范
2.1 当前结构
d:\wechat\
├── index.html # H5 端入口模板
├── package.json # 依赖与多端编译脚本
├── tsconfig.json # TS 配置
├── vite.config.ts # Vite 配置(挂载 uni 插件)
├── 微信小程序开发清单.md # 本清单
├── scripts/
│ └── check-pages.mjs # 静态路由表 ↔ pages.json 一致性校验
└── src/
├── main.ts # 应用入口
├── App.vue # 根组件(全局样式 + 应用生命周期)
├── pages.json # 路由 / tabBar / easycom
├── manifest.json # 各端打包配置(微信端唯一来源)
├── uni.scss # 全局 SCSS 变量
├── env.d.ts # 类型声明
├── shims-uni.d.ts # 生命周期类型扩展(已修正拼写)
├── api/ # 接口层
│ └── user/user.ts # 登录 / 注册 / 用户信息 / 退出(/system 网关)
├── components/ # 全局组件(easycom 扫描)
│ ├── auth-gate/auth-gate.vue # 三态渲染(public / optional / required)
│ ├── empty-state/empty-state.vue # 统一空态/失败提示 + 「重试」
│ └── login-panel/login-panel.vue # 登录 / 注册面板组件
├── composables/ # 组合式函数
│ └── usePageAuth.ts # 页面登录策略与「去登录」(弹登录抽屉)
├── router/ # 静态路由表与入口树生成
│ ├── pages.ts # PAGE_REGISTRY / PAGE_MAP / PAGE_BY_PATH / isTabBarPage
│ └── entries.ts # generateEntries():菜单 × 路由表 → 可见入口树(纯函数)
├── store/ # 状态管理(Pinia)
│ └── modules/ # user.ts(登录态/身份/权限点)、permission.ts(菜单与可见入口)
├── utils/ # 工具函数
│ ├── auth.ts # token 本地存取(唯一写入方)
│ ├── auth-guard.ts # 登录跳转(LOGIN_PAGE / redirectToLogin,不做全局拦截)
│ ├── barcode.ts # Code128(B) 编码(输出条空宽度序列,供工具页渲染)
│ ├── calculator.ts # 四则运算求值(自写解析器,不用 eval)
│ ├── debug-log.ts # 开发期日志(生产构建自动空转)
│ ├── navigate.ts # 统一跳转(自动区分 switchTab / navigateTo)
│ └── request.ts # uni.request 封装
├── pages/ # 主包页面(启动页 + tabBar 页)
│ ├── login/login.vue # 登录 / 注册页(非启动页,仅 401 兜底 / 直接访问)
│ ├── index/index.vue # 首页(启动页):动态菜单段 + 本地「辅助工具」段
│ └── mine/mine.vue # 我的
├── sitemap.json # 禁止微信搜索索引(全部 disallow)
├── pagesA/ # 分包 A(已注册)
│ ├── tools/ # 计算器 / 条形码(公共工具页,`common: true` → 首页「辅助工具」段)
│ └── external-*/ # 业务页(外仓商品 / 外部仓库 / 收货单 / 库存报表 / 入库单 / 商品流水)
├── pagesB/ # 分包 B(规划:出库,待注册)
├── pagesC/ # 分包 C(规划:库存/盘点,待注册)
└── static/ # 静态资源
└── logo.png
空目录下均有
.gitkeep占位(git 不跟踪空目录),内容行标注了该目录用途。 实测确认.gitkeep不会被打进小程序产物。
2.2 目录职责说明
-
按业务域补齐目录 ✅(已创建,见 2.1)
| 目录 | 职责 | 约定 | |---|---|---| | `api/` | 接口定义,按业务模块拆分 | `request.ts` 为请求实例;后续按入库/出库/库存拆文件(第 5 节) | | `components/` | 全局自定义组件 | ⚠️ 必须符合 `组件名/组件名.vue` 才会被 easycom 自动扫描 | | `composables/` | 组合式函数 | 命名 `useXxx` | | `pages/` | 主包页面:tabBar 页 + 启动必需页 | 必须在 `pages.json` 的 `pages` 中注册 | | `pagesA/` `pagesB/` `pagesC/` | 分包页面 | 路径相对 `root`;需在 `pages.json` 的 `subPackages` 中注册(第 3 节) | | `static/` | 静态资源 | 唯一保证原样拷贝、不参与编译的目录 | | `store/` | 状态管理(Pinia) | 需引入 Pinia 并注册(第 8 节) | | `utils/` | 纯工具函数 | `auth` / `scan` / `format` 等(第 6 节) | > 分包目录名 `pagesA/B/C` 与业务映射(入库/出库/库存)是**按 WMS 常见划分提的方案**。 > 若你们已有既定模块划分,现在改成本极低(尚无页面文件),只需重命名目录。 -
遵守 uni-app 目录约定 ✅ - 页面必须同时在
pages.json中注册,新增/删除页面都要同步维护该数组 - 页面路径不含后缀,uni-app 自动寻找.vue-static/是唯一保证原样拷贝、不参与编译的目录,图片/字体放这里 - 每一层pages目录的第一项为该包的入口页(主包第一项即小程序首页) -
清理工程历史遗留 ✅ - 根目录
shims-uni.d.ts不在tsconfig.json的include(仅src/**)范围内,是死代码 → 已删除 -src/shime-uni.d.ts文件名拼写有误 → 已重命名为src/shims-uni.d.ts> 两者功能重复,保留src/shims-uni.d.ts(declare module "vue"方式对 Vue 3 才是正确写法)。 > 重命名后已实测:type-check+ 双端构建均通过。
3. 包体积与分包(微信硬性限制)
-
牢记体积红线 | 限制项 | 上限 | |---|---| | 单个分包 / 主包 | 2 MB | | 所有分包 + 主包总计 | 20 MB | | 本地存储单个 key | 1 MB | | 本地存储总量 | 10 MB |
-
规划分包(
src/pages.json→subPackages)—— 🚧 已注册pagesA(放框架示例页) 原则:主包只放 tabBar 页 + 启动必需页 + 公共资源;业务模块全部下沉到分包。 ✅ 已实测:产物app.json含subPackages,页面落在dist/build/mp-weixin/pagesA/**;npm run check:pages能校验分包页的可达性(PAGE_REGISTRY.path用pagesA/demo/public这种全路径)。 待办:pagesB(出库)/pagesC(库存/盘点)随业务页一起注册。jsonc "subPackages": [ { "root": "pagesA", "pages": [ { "path": "inbound/list", "style": { ... } } ] } ]注意:分包内pages的路径是相对root的相对路径,不是全路径。 -
配置分包预下载(
preloadRule) 在进入某页面时提前下载后续可能用到的分包,减少二次跳转等待。packages取分包root或name;__APP__代表主包;network可选all/wifi。 -
图片资源策略 体积大的图片、图标一律走 CDN 或对象存储,不要打进代码包。 包内仅保留 tabBar 图标、少量占位图。
-
构建产物体积巡检 每次发版前用微信开发者工具的「代码依赖分析」查看主包/分包体积,确认无越线。
4. 页面与导航
-
配置 tabBar ✅(2 个纯文字 Tab:首页 / 我的)
| Tab | 页面路径 | 页面内容 | |---|---|---| | 首页 | `pages/index/index` | 业务入口九宫格(未登录取本地公共入口;登录后取后端菜单,支持「分组标题 + 子项」两层)+ 运行信息 | | 我的 | `pages/mine/mine` | 未登录:点头部用户信息区弹登录抽屉;已登录:登录态展示 + 退出登录;另有运行信息 + 清除缓存 | 约定(务必遵守): - `list` 最少 2 个、最多 5 个;**tabBar 页必须在主包**,不能放分包 - 跳转到 tabBar 页只能用 `uni.switchTab`,**不能**用 `navigateTo` / `redirectTo` - tabBar 页首次进入触发 `onLoad` + `onShow`,之后切换**只触发 `onShow`**(数据刷新放 `onShow`) > 实测确认:产物 `app.json` 已包含完整 `tabBar` 配置与 3 个页面(index / mine / login); > 各页面 `usingComponents` 只包含自己用到的组件,按需引入正常。 > > 📌 **2026-09-19 页面精简**:按需求移除「任务」「库存」两个 tab 页 > (`pages/task/task.vue`、`pages/inventory/inventory.vue` 已删除, > `pages.json` 的 `pages` / `tabBar.list` / `condition.list` 三处已同步清理)。 > 首页九宫格里的「库存查询」入口是**规划中的分包页面占位**(见 `pagesC`), > 与已移除的「库存」tab 不是同一个东西,故保留。 -
补充 tabBar 图标(待办) 当前为纯文字 Tab(
iconPath是可选字段,不带图标也能正常运行)。 微信要求图标为本地图片:≤ 40 KB,建议 81 × 81 px,不支持网络图片与字体图标。 补齐方式:把图标放入src/static/tabbar/(每个 Tab 需选中/未选中两张), 再在pages.json的tabBar.list各项目补上iconPath与selectedIconPath。 -
确认首页与标题 ✅ 标题已由模板默认值
uni-app改为实际业务名:首页 / 我的 / 登录;globalStyle兜底标题为WMS 小程序。 启动页由pages数组第一项决定,当前为pages/index/index(首页)。 ⚠️ 不得把登录页设为首项:微信审核要求打开小程序不能直接强制登录 (未登录也必须有可浏览的内容)。登录页pages/login/login排在末位, 由用户从「我的」页主动进入,详见第 6 节。 -
配置页面级启动模式(开发提效) ✅
src/pages.json→condition已配置 3 个编译模式(首页 / 登录 / 我的),仅开发期生效。 微信开发者工具顶部「编译模式」下拉即可直达对应页面。 -
约定页面生命周期用法 ✅(已在页面中示范) - 页面级:
onLoad(取参、初始化)、onShow(刷新数据)、onReachBottom(分页加载)、onPullDownRefresh(下拉刷新) - 组合式 API 下从@dcloudio/uni-app引入对应 Hook - 开启下拉刷新需同时设置enablePullDownRefresh: true并调用uni.stopPullDownRefresh()>pages/mine/mine.vue示范了在onShow刷新登录态; > 各 tabBar 页的onShow已留好接口接入位置(第 5 节)。 -
列表性能(待接口接入后落实) 长列表(如库存明细)使用
scroll-view+ 虚拟列表,避免一次性渲染上千节点。
5. 网络请求
-
配置请求合法域名 微信公众平台 → 开发管理 → 开发设置 → 服务器域名,配置
request/uploadFile/downloadFile合法域名。 必须 HTTPS,且证书有效;域名不能使用 IP 或非标准端口。 -
封装请求实例 ✅ 位置:
src/utils/request.ts(基于uni.request二次封装,行为对齐 new3 的 axios 封装)。 已覆盖:baseURL(.env的VITE_APP_BASE_API)、超时、platform/project请求头、Authorization: Bearer <token>注入、响应头新 token 自动回写(续期场景)、 业务成败判定走flag/success(不能用code,见下条)、错误码文案映射、 HTTP 401 → 清登录态并带来源页回登录页、可选loading文案、失败统一 toast。 > 注:new3 里的isSystemApi标记在 Web 端从未被消费(死字段),未移植。 -
后端 /system 网关契约(实测,务必遵守) ✅
| 项 | 实测结果 | |---|---| | `platform` 请求头 | **网关校验**,非白名单 → HTTP 400 且响应体为空。白名单:`web` / `app` / `wx` / **`miniProgram`**(**大小写不敏感**);本项目固定 `miniProgram` | | `project` 请求头 | 同样校验。白名单:`all` / `wms`;本项目固定 `all` | | 未登录 / token 失效 | **HTTP 401 + 空响应体**(不是业务码) | | 业务成功 | `{flag:"success", success:true, code: 200 或 1, data}` | | 业务失败 | `{flag:"failure", success:false, code: 0, message, data:null}` | ⚠️ **四个坑(已踩并修复)**: 1. **不要用 uni-app 的平台名 `mp-weixin` 当 `platform`** —— 网关直接返回 400 + 空 body, 前端只能显示通用「请求参数错误」,根因极难定位。故平台编码统一放 `.env`(`VITE_APP_PLATFORM` / `VITE_APP_PROJECT`),不在代码里硬编码。 2. **`code` 不能用来判成败** —— 失败响应 `code` 恒为 `0`,而 new3 的 `SUCCESS_CODES = [200, 20000, 1, 0]` 把 `0` 当成功,**会把失败静默当成成功** (表现为密码错也不报错)。本项目已改为看 `flag` / `success`。 3. `50008 / 50012 / 50014` 是 vue-element-admin 的遗留码,后端并不使用; 真正的登录失效信号是 **HTTP 401**。 4. **401 后必须 `removeToken()`** —— 否则跳登录页后,登录页 `onShow` 里的 `if (getToken()) goAfterLogin()` 会把用户**立刻弹回**刚才那个页面 → 再次 401 → **死循环**。现已收口为 `utils/request.ts` 的 `clearSession()`(`removeToken()` + 清空权限 store 缓存)+ 跳登录页。 > 排查手法(有效):直接用 PowerShell `Invoke-WebRequest` 打后端,逐变量对比状态码; > 用假账号探测能区分「参数被拒(400)」与「账号错误(200 + business message)」。 -
控制并发 微信小程序
wx.request并发上限 10 个,批量场景(如批量提交盘点)需自行排队或分批。 -
配置超时
src/manifest.json→networkTimeout(request/connectSocket/uploadFile/downloadFile),默认 60000 ms(与微信对齐)。 -
弱网与异常兜底 断网提示、请求重试、超时兜底文案;建议封装统一的错误提示(可复用
uni.$u.toast)。
6. 登录、鉴权与用户信息
-
登录流程(账号密码版,对齐 new3) ✅ 入口:任意页面就地弹登录抽屉(
components/auth-modal/,内容components/login-panel/)→store/modules/user.ts的login()→api/user/user.ts的user.login(POST /system?method=user.login&v=1.0×tamp=...,body{ username, password, device }) → 响应data.token写入utils/auth.ts。 注册走同一网关的user.register(username/email/real_name/password), 成功后回到登录页并回填账号(与 new3 一致,不自动登录)。 -
微信一键登录(
uni.login→wechat.loginByCode) ✅ ⚠️ 接口是wechat.loginByCode,不是user.loginByCode(后者接的是 ye4s base64 登录码, 走loginByYe4sCode,与小程序无关)—— 已核对后端app/service/systems/wechat.js。链路: 1. `uni.login({ provider: 'weixin' })` 取临时 `code`(一次性,5 分钟有效) 2. `wechat.loginByCode`,入参 `{ code, appid }` - `appid` = **运行时**真实 AppID(`wx.getAccountInfoSync().miniProgram.appId`) - 不写进 `.env`:代码作为**开放平台第三方平台模板**发布,各仓库授权后 AppID 不同 - 后端 `resolveWechatApp()` 按 appid 反查 `wms_wechat_app` 授权记录(已支持 app_id 主键 / appid 字符串两种入参) 3. 后端 `jscode2session` 换 openid/session_key → 查/建 `wms_user_oauth` → 签发 token (`id = 0` 表示该微信尚未绑定 WMS 账号) 4. **token 立即落地存储**(含 `id = 0` 的未绑定态)—— 它是有效的免登录凭证 5. 再调 `user.info` 探测绑定状态:未绑定时后端**不返回 401**,而是下发 `is_bound: false` + 微信层信息(openid / unionid / oauth_id),见后端 `systems/auth/user.js` 的 `info()` - ⚠️ `user.info` 入参已**新增 `wechat_appId`**(`string`,运行时真实 AppID,与 `loginByCode` 的 `appid` 同源)—— 未绑定态也要让后端知道「是哪个小程序发起的请求」; 非小程序端 / 拿不到 AppID 时**不带该参数**(`store/modules/user.ts` 的 `fetchInfo`) 未绑定的处理(产品要求:只提示一次、可跳过、不阻断): - 登录页展示绑定步骤(`components/wechat-bind-form/`),**可跳过** - 跳过**不清 token**:仍是免登录态,下次打开小程序直接进首页,不重复提示登录 - 绑定入口在「用户信息」二级页(`pages/mine/user-info`):`isWechatUnbound` 为真时显示 「待绑定 WMS 账号」卡片 + 弹窗绑定(原先直接堆在「我的」页上) - 绑定成功:`wechat.bindUser` 换发正式 token(`user.id` = 真实账号 ID)并重拉 `user.info` 前端落点:`utils/wechat.ts`(原生能力 + 条件编译)、`api/user/user.ts`(两个接口)、 `store/modules/user.ts`(`wechatLogin` / `wechatBind` / `getInfo` / `isWechatUnbound`)、 `components/wechat-bind-form/`(绑定表单,登录页与「我的」页共用)、`components/login-panel/`(按钮)。 ⚠️ 绑定状态的判定依据是 `user.info` 的 **`is_bound`**,不是 `wechat.loginByCode` 返回的 `user.id` (后者只是签发那一刻的快照;已绑定用户的 `user.info` 里**没有** `is_bound` 字段,为 `undefined`)。 ⚠️ 仅登录表单展示入口,且整段包在 `#ifdef MP-WEIXIN` 内(H5 产物中已剔除)。 -
微信资料维护(
wechat.updateInfo+wechat.uploadHeadimg) ✅ 2026-09-22 ⚠️ 两个接口都是微信登录态中间层(带微信登录态 token 即可), 且wechat.updateInfo后端仅允许未绑定真实用户的微信账号修改 —— 故入口条件是user.info的is_bound === false(store 的canEditWechatProfile,只此一处判断)。接口参数 / 返回(来源:new3 接口工具的 `module/wechat/module.json`): - `wechat.updateInfo`:入参 `{ nickname?, headimgurl? }`(**可部分更新**, nickname ≤255 字符、headimgurl ≤500 字符)→ 返回 `{ oauth_id, nickname, headimgurl }` - `wechat.uploadHeadimg`:入参 `{ image }` = **PNG 的 base64**(支持 `data:image/png;base64,` 前缀, **限制 < 500K**)→ 返回 `{ oauth_id, url, headimgurl }`(后端校验 PNG 魔数 → COS,回写 `wms_user_oauth.headimgurl`) ⚠️ 合规:微信自 2022-10 回收 `getUserProfile`,头像昵称**只能由用户主动提供**: 头像 = `<button open-type="chooseAvatar">`,昵称 = `<input type="nickname">`。 ⚠️ 头像不能直接上传:`chooseAvatar` 给的是**临时文件路径**且格式 / 体积都不受控。 本地规整统一在 `utils/avatar.ts` 的 `avatarFileToPngBase64()`: cover 居中裁剪 → 转 PNG → 按 `SIZE_STEPS`(400→120)逐级缩小,直到估算字节数 < 500K。 两个坑:① 用旧版 `canvas-id` API(`uni.createCanvasContext`), **必须传页面实例**且页面要**真实渲染**画布(故画布放屏外,不能 `v-if`); ② PNG 体积取决于画面复杂度、不可预估,所以是「试到手为止」而非写死一个尺寸。 前端落点:`api/user/user.ts`(两个接口封装)、 `store/modules/user.ts`(`wechatNickname` / `headimgurl` / `canEditWechatProfile` + `updateWechatProfile()` / `uploadWechatHeadimg()`)、 `utils/avatar.ts`(头像规整)、`pages/mine/user-info.vue`(「微信资料」卡片 + 编辑弹窗)。 ⚠️ 昵称 / 头像改完**不重拉 `user.info`**:直接把接口返回值合并进 `store.user` (`applyWechatProfile()`),既不冲掉 `infoLoaded` 缓存语义,界面也立即刷新。 -
我的登录码(
wechat.getMyLoginCode) ✅ 2026-09-22 用途:反方向的扫码登录 —— 小程序把自己的登录码展示给用户, 电脑端凭它走user.loginByCode(ye4s 登录码链路)直接登录为本账号,无需在电脑上输密码。 (与第 13.4 节相反:那里是 PC 出码、小程序确认;这里是 小程序出码、PC 登录。)接口参数 / 返回(来源:new3 接口工具的 `module/wechat/module.json`): - 入参:**无**(后端从 token 的 `oauth_id` 取当前微信用户) - 返回:登录码 = `uuid={id}_{6位随机}`、`form=wechat` 的 JSON base64 ⚠️ 后端文档**未列出**返回字段名:代码按 `login_code` 声明, 并在 store 做兼容取值(`login_code` / `loginCode` / `code`),取不到就报错而不是展示 `undefined` - 鉴权:**微信登录态**(JWT 含 `oauth_id`)—— 账号密码登录的 token 会被拒 ⚠️ 语义是「**没有才生成**、已有则原样返回」⇒ 同一个微信账号的码**稳定不变**(不是一次性), 故前端拿到后存进 store 反复展示 / 复制,不重复请求;退出登录时随登录态清掉。 ⚠️ 入口条件 = `userStore.canGetMyLoginCode`,三个信号取并集(单看任一个都不可靠): 本地登录渠道为 `wechat`、或 `user.info` 的 `is_bound === false`、或回传了 `oauth_id`。 前端落点:`api/user/user.ts`(`wechatGetMyLoginCode()`)、 `store/modules/user.ts`(`canGetMyLoginCode` / `myLoginCode` + `getMyLoginCode()`)、 `pages/mine/user-info.vue`(「电脑端登录码」卡片 + 登录码弹窗 + 一键复制)。 -
token 与登录态 ✅ 统一存于
utils/auth.ts(小程序无 Cookie,故用uni.getStorageSync,key =token)。 同时记录登录渠道(storage key =login_channel,值wechat/account,与 token 同生命周期): token 本身看不出登录方式,而已绑定的微信登录态在user.info里又没有is_bound字段, 靠它才能区分「微信登录态」;部分微信中间层接口(如登录码)只认微信登录态,界面据此控入口。 token 失效由utils/request.ts统一兜底(清存储 →reLaunch登录页)。 -
登录入口与取消(微信审核要求,务必遵守) ✅ ⚠️ 打开小程序不得直接跳登录页,登录必须由用户主动触发: - 启动页 = 首页(
pages/index/index),未登录可正常浏览 - 登录入口 = 「我的」页头部的用户信息区(未登录时文案「点击登录后使用完整功能」+ 右侧箭头; 点击就地弹登录抽屉)—— 不再放独立的「登录 / 注册」按钮 - 未绑定时点头部区(或菜单「用户信息」行)→ 进二级页,在那里绑定 (各业务功能都不可用,这里最需要操作) - 登录页有「取消」:页面栈有上一页则navigateBack返回来源页, 否则退回redirect指定页 / 首页 - 登录成功:回跳redirect指定页(tabBar 页用switchTab,其余用redirectTo) - 退出登录:入口在「用户信息」二级页(pages/mine/user-info)底部, 退出后停留在本页并切回未登录引导态,不强制跳登录页 -
未登录访问控制(改为按需,不做全局拦截) ✅
utils/auth-guard.ts只保留LOGIN_PAGE/getCurrentRoute()/redirectToLogin()。 已移除原先用uni.addInterceptor拦截 4 个跳转 API、未登录一律导向登录页的做法 —— 那等价于「一打开就强制登录」,会被审核驳回。 现在的兜底是「按需触发」:请求命中 HTTP 401 时(见utils/request.ts) 带着来源页跳登录,重新登录后自动回到刚才的页面。 若后续需要给个别页面做前置校验,在页面内用userStore.isLogin自行判断并引导, 不要恢复全局拦截。 -
不要使用
getUserProfile✅ 2026-09-22 该接口自 2022 年 10 月起已被微信回收,返回匿名数据。 获取头像昵称已改用 头像昵称填写能力(<button open-type="chooseAvatar">+<input type="nickname">), 见第 6 节的「微信资料维护」(wechat.updateInfo/wechat.uploadHeadimg)。 -
手机号获取 需通过
<button open-type="getPhoneNumber">,且账号需具备相应权限(通常需企业主体)。
7. 权限与隐私合规(提审重点)
-
梳理隐私接口清单 ✅ 2026-10-17 全仓搜索确认实际只用两个隐私能力(其余定位/相册/相机/麦克风/通讯录/蓝牙/手机号均未使用,
manifest也没有permission/requiredPrivateInfos,与实际一致):| 用到的能力 | 代码位置 | 官方清单归属 | |---|---|---| | `<button open-type="chooseAvatar">` + `<input type="nickname">` | `pages/mine/user-info.vue` | **收集你的昵称、头像** | | `uni.setClipboardData`(复制登录码 / 计算结果 / 条码内容) | `user-info.vue`、`tools/calculator.vue`、`tools/barcode.vue` | **读取你的剪切板**(官方清单把 `setClipboardData` 也归在这里) | -
配置《小程序用户隐私保护指引》(平台后台,必须做) 微信公众平台 → 设置 → 服务内容声明 → 用户隐私保护指引,至少勾选: 1. 「收集你的昵称、头像」(否则
chooseAvatar被禁用 → 点头像无反应、input type=nickname降级为普通输入框) 2. 「读取你的剪切板」(否则 3 处复制全部失败,报errno 112 / api scope is not declared) > 补充声明 5 分钟后生效。未声明不是「体验差」而是接口直接不可用。 > 代码侧已提供入口:「我的」页 → 「隐私保护指引」→wx.openPrivacyContract()(条件编译 MP-WEIXIN, > 逻辑收口在composables/useLegalLinks.ts;该入口不依赖登录)。 > 项目未接wx.onNeedPrivacyAuthorization,依赖微信 2023-10-17 后强制的官方隐私弹窗; > 用户拒绝时 3 处复制会失败并提示「请确认已同意《隐私保护指引》」。 -
处理授权被拒的分支 用户拒绝授权后应有降级方案与引导(引导至
uni.openSetting重新开启),不能白屏或静默失败。 -
位置相关接口 若使用定位,需在
src/manifest.json→mp-weixin.permission中填写用途说明, 并在mp-weixin.requiredPrivateInfos中声明所用地理位置接口。 > 注意:位置权限描述配置在 manifest 中,不是pages.json(这是常见误区)。 -
后台能力声明 如需后台播放音频等,配置
mp-weixin.requiredBackgroundModes。 -
合规红线 不得诱导分享/关注、不得收集与业务无关的个人信息、不得使用未备案域名。
8. 样式与开发约定
-
尺寸单位统一用
rpx(750 设计稿基准);manifest.json的transformPx保持false,不要依赖 px 自动转换。 -
不做深色模式(浅色主题锁) ✅ 2026-10-17 本项目配色全部写死为浅色(
#f5f6fa底 /#ffffff卡片 /#303133文字),不做深色适配。 但 uview-plus 会跟随系统深色模式把文字变白、弹层变黑(白底白字),所以做了三件事: 1.main.ts→uni.$u.setThemePreference('light')(管 JS 算出来的颜色:弹层背景 / 输入框文字) 2.App.vue全局page { --up-* / --up-light-* }钉回浅色原值(管 CSS 变量驱动的颜色,如up-cell) 3.manifest.json → mp-weixin.darkmode = false(产物app.json已含,原生导航栏/ tabBar 不变深) > 若将来真要支持深色:改darkmode: true+ 配置themeLocation,并逐页改造写死的颜色(工作量大,不建议半做)。 -
品牌色与主题变量集中管理 在
src/uni.scss中覆盖 uview-plus 的$u-*变量(theme.scss内变量均为!default,放在文件末尾即可覆盖)。 ⚠️ 严禁把uview-plus/index.scss引入uni.scss(会破坏按需引入并导致包体积暴涨),它只能写在App.vue。 -
组件统一使用
up-前缀 easycom 已配置^up-/^u--/^u-三条规则,推荐统一up-,避免与 uni-app 内置组件(如u-slider)重名冲突。 注意:修改easycom规则不会热更新,需重启编译。 -
自定义组件规范 放
src/components/组件名/组件名.vue才会被 easycom 自动扫描; 组件内样式默认隔离,跨组件需要穿透时用:deep()或styleIsolation相关配置。 -
条件编译 平台差异逻辑用条件编译(
#ifdef MP-WEIXIN/#ifndef H5),不要用运行时if判断平台。 -
状态管理 ✅ 已引入 Pinia(
pinia@2.1.7)并在main.ts注册,登录态见store/modules/user.ts。 ⚠️ 两个实测要点: 1. uni-app 小程序端createApp()必须把Pinia一并return,否则各页面拿到的不是同一实例; 2. 装 Pinia 需要--legacy-peer-deps:pinia@2.3+要求 Vue ≥ 3.5.11, 而 uni-app 锁定vue@3.4.21;且vue-demi的可选 peer@vue/composition-api会让 npm 误判为冲突。故选用pinia@2.1.7。
9. 调试与测试
-
开发调试流程 ✅(已实测走通)
npm run dev:mp-weixin→ 微信开发者工具导入dist/dev/mp-weixin目录。 产物目录一旦导入过,后续编译会自动刷新,无需重复导入。⚠️ **同一时间只能有一个 `dev:mp-weixin` 进程在跑**(已踩坑) 两个编译进程同时写 `dist/dev/mp-weixin` 会互相删除/覆盖对方的 chunk, 导致开发者工具点预览报: `Error: ENOENT: no such file or directory, open '...\common\assets.js'` > 识别技巧:**正常产物只有 `common/vendor.js`,根本不会生成 `common/assets.js`**。 > 只要看到报这个文件名,几乎就是产物写坏 / 历史残留。 排查与修复: 1. 查残留编译进程: `Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object { $_.CommandLine -match 'dcloudio|uni\.js' } | Select ProcessId, CreationDate, CommandLine` 2. 杀掉多余进程 → 删除 `dist` → **只跑一个** `npm run dev:mp-weixin` 3. 注意:微信开发者工具的 `wxfilewatcher_x64.exe` 会锁住产物目录, 此时 `Remove-Item dist` 报「正由另一进程使用」是**正常现象**,不影响写入文件 验证产物完整性(比只看「构建成功」可靠得多): 扫描产物所有 `.js` 里的 `require("...")`,逐个确认目标文件存在,应为 **0 缺失**: ```powershell $root="dist\dev\mp-weixin"; $missing=0; $total=0 Get-ChildItem $root -Recurse -File -Include *.js | ForEach-Object { $f=$_; $c=Get-Content $f.FullName -Raw foreach ($m in [regex]::Matches($c,'require\("([^"]+)"\)')) { $total++ if (-not (Test-Path (Join-Path $f.DirectoryName $m.Groups[1].Value))) { $missing++ } } } "引用 $total 个,缺失 $missing 个" ``` -
真机调试必做项 授权弹窗、扫码、上传、扫码枪/蓝牙硬件、ios 与 android 差异、弱网表现。
-
隐私与授权前置验证 在未同意隐私协议的干净账号下走一遍主流程,确认无接口被静默拦截。
-
真机 vs 模拟器差异 部分能力(如
backgroundColorContent、分包预下载、部分隐私接口)模拟器表现与真机不一致,以真机为准。 -
构建前类型检查
npm run type-check(vue-tsc)纳入提交前检查,避免类型错误进入仓库。
10. 发布上线流程
-
上传前自检(代码侧已就绪 2026-10-17) - ✅ 已删除测试入口页:
pagesA/test/index.vue(含 628 诊断页数据)与pagesA/demo/required.vue均已删除,并同步清理pages.json(含condition)/PAGE_REGISTRY; 产物pagesA只剩tools+ 业务页 - ✅console.log已收口到utils/debug-log.ts(生产构建空转,产物已验证为function(){}); 登录码 / token / 用户对象一律不打印(confirm-login、bindUser、入口场景均已清理) - ✅sitemap.json已配置(全部disallow) - ⬜ 仍需手动:manifest.json → mp-weixin.setting.urlCheck改回true(本地联调要连局域网 接口,平时保持false;该项只影响开发者工具校验,不影响上传包) - ⬜ 仍需手动:切换正式环境接口地址 / 正式 AppID - ✅ 包体积:主包 ≈ 0.44MB、总计 ≈ 0.54MB(限额 2MB / 20MB) -
版本管理
manifest.json→versionName(如 1.0.0)/versionCode(递增整数) -
上传与提审 微信开发者工具「上传」→ 公众平台「版本管理」→ 提交审核。 提审需填写:功能页面、测试账号、类目与资质、隐私指引。
-
审核常见驳回点 - 隐私协议缺失或与实际收集信息不符 - 未提供可用的测试账号 / 测试路径 - 存在需登录才能看到任何内容但未提供账号 - 使用未备案或不可访问的接口域名
-
(可选)CI 自动化上传 使用
miniprogram-ci在流水线中自动上传,需在公众平台生成上传密钥。 -
发布后验证 体验版验证 → 全量发布 → 线上巡检(登录、主流程、关键接口)
11. 接口与环境配置
-
区分环境 ✅ 已建
.env.development(http://192.168.11.56:6060/,与 new3 开发环境同一后端) 与.env.production(https://qimen.wms.gztbyc.com/,⚠️ 上线前按实际情况确认)。 业务代码统一走import.meta.env.VITE_APP_BASE_API;VITE_APP_PLATFORM(miniProgram)/VITE_APP_PROJECT(all)为后端网关校验的请求头(契约见第 5 节)。 > 实测验证:生产构建产物utils/request.js只含生产域名,开发地址未被混入。 > 待补:.env.staging(测试环境)暂未配置,需要时按同样方式新增即可。 -
禁止敏感信息入库 密钥、私钥、上传密钥等一律不入 git;如需配置模板,提交
.env.example而非真实.env。
12. 页面渲染框架(配套文档摘要)
菜单 / 权限 / 页面渲染的设计与任务清单独立维护在 页面渲染框架-设计与任务清单.md,
本节只记录与本清单强相关的已确认结论,避免两处漂移。
| 项 | 结论 |
|---|---|
| 页面渲染驱动 | 后端 user.info 的 menus(页面树)+ permissions(权限点);小程序不能动态注册路由,靠本地静态路由表映射 |
| 静态路由表 | ✅ 已实现:src/router/pages.ts 的 PAGE_REGISTRY(key = 逻辑路径 ↔ path = 物理页面,带 auth / tabBar / hidden);只登记 pages.json 里真实存在的页面 |
| 防漂移 | npm run check:pages:校验 PAGE_REGISTRY.path 已在 pages.json 注册、key 不重复;有未登记页面则告警 |
| 权限 store | ✅ 已实现(阶段 2):src/store/modules/permission.ts(menus / entries / missing / loaded,动作 loadFromMenus() / reset()) |
| 入口树生成 | ✅ 已实现:src/router/entries.ts 的 generateEntries();未命中路由表的菜单项忽略并计入 missing,分组无子项则整组丢弃,输出固定两层 |
getInfo() 触发时机 |
✅ 已收口:登录成功(login())/ 启动带 token(App.onLaunch)/ 切换身份(changeRole());resetToken() 联动清空权限 store |
| 三态渲染 | ✅ 已实现(阶段 3):页面用 <auth-gate auth="..."> 包裹即可,页面内不再写 if (isLogin);usePageAuth() 的 auth 参数可省略(自动按当前页从 PAGE_REGISTRY 取) |
| 「去登录」唯一实现 | ✅ usePageAuth.goLogin():弹登录抽屉(不跳页、不带 redirect);未登录一律不自动跳转 |
| 本地公共入口 | LOCAL_PUBLIC_ENTRIES(router/entries.ts)= auth === 'public' && !tabBar && !hidden;当前为空数组 → 首页走空态文案(预期) |
| 空态组件 | ✅ components/empty-state/:默认文案「服务器出差了,请稍后再试」+ 「重试」,可再挂一个「去登录」动作位 |
| 可见性口径 | isEntryVisible(meta) = !tabBar && !hidden,本地公共清单与后端菜单共用(避免两处规则不一致) |
| 首页入口渲染 | ✅ 已接入(阶段 4):loading → sections(分组标题 + 子项九宫格)→ empty-state(含重试,未登录额外给「去登录」);数据源:未登录 = LOCAL_PUBLIC_ENTRIES,已登录 = permissionStore.entries |
| 「我的」功能菜单 | ❌ 2026-09-22 已移除:功能菜单只在首页九宫格,「我的」页不再重复展示(同批移除「当前版本」「运行平台」两行信息) |
| 统一跳转 | ✅ utils/navigate.ts:按 PAGE_REGISTRY 自动决定 switchTab / navigateTo,失败提示「暂未开放」 |
| 框架示例页 | pagesA/demo/public(public,未登录九宫格可见)、pagesA/demo/required(required + 按钮级权限示例);已加入开发编译模式,业务页上线后可删 |
| 页面归属 | 「首页」public、「我的」optional —— 两者都是公共页面(无需登录即可访问,不被拦截); |
「用户信息」pages/mine/user-info 也是 optional + hidden(仅从「我的」页菜单进入) |
|
后端菜单 path |
用逻辑路径(如 /inbound/list),由前端映射到物理页面 |
| 未登录九宫格 | 仅显示公共入口;为空/请求失败时渲染空态文案(详见《页面渲染框架》§3.5.1) |
| 空态文案(已确认) | 「未登录且为空」与「已登录拿不到数据」统一使用「服务器出差了,请稍后再试」+ 「重试」按钮 |
required 页未登录 |
页内「请先登录」+ 按钮,不自动跳转 |
| 角色/仓库切换 | user.changeRole({ roleId }),roleId = user.info 的 employees[].id;✅ 接口已实测存在(无 token 调用 → 401) |
| 当前身份状态 | userStore 已含 employees / currentEmployeeId;默认身份:本地已选 > 后端会话 employees_id > is_primary > 授权未过期 > 第一个 |
| 身份展示 | ✅ 已完成(2026-09-19):「我的」页登录后显示身份信息卡片(姓名/类型/组织/员工 ID/授权到期) |
| 身份切换 | 🚧 已实现待联调(2026-09-19):多身份时「我的」页出现「切换身份」行,选后调 user.changeRole → 换 token → 重拉 user.info |
| 请求头 | platform: miniProgram / project: all(见第 5 节契约) |
13. 扫码入口与场景参数(spm)
小程序被扫码 / 链接 / 分享唤起时,微信给的入口参数形态各不相同,必须在一层归一化后再分发。
实现:src/utils/entry.ts(解析)+ src/router/scenes.ts(分发)+ composables/useEntryScene.ts(消费)。
13.1 三种入口来源(都要处理,少一种就漏)
| 来源 | 参数位置 | 特点 |
|---|---|---|
| 扫普通链接二维码 | options.q |
URL 编码的完整路径;要正则抠参,且「原文 / 解码后」两个候选都要试 |
| 小程序码带参 | options.scene |
最长 31 字符,约定 k=v 形式,需 split('=') 拆解 |
⚠️ 坑:只能认
options.query.scene。options.scene是微信的场景值(纯数字,如 1001 = 发现栏主入口、1011 = 扫描二维码),没有业务含义;把它当场景码会在启动时报「未识别的场景码:1001」。 | 分享 / 后台下发 |options.xxx平铺 | 直接取;options.page为服务端指定的落地页 |
13.2 spm 约定(与后端对齐用)
沿用 G:\uni\数据(shopro)的点分段位方案:全数字、位置表意、可无限往后加段。
spm = [userId].[scene].[code].[platform].[from].[extra...]
| 段 | 名称 | 本项语义 | 特殊值 |
|---|---|---|---|
| 第 1 段 | userId |
发起方用户 ID(PC / 工作台的操作账号) | 0 = 无 |
| 第 2 段 | scene |
场景码(数字):3=打开页面 4=确认登录(wechat.pushLoginCode);1、2、5、6… 预留,后续继续编号 |
— |
| 第 3 段 | code |
随机码(登录码 / 绑定码)/ 业务标识 | 0 = 无 |
| 第 4 段 | platform |
渠道:1=H5 2=公众号 3=小程序 4=App |
同 shopro |
| 第 5 段 | from |
来源:1=直接转发 2=海报 3=链接 |
同 shopro |
| 第 6 段起 | extra |
预留扩展,按场景解释 | — |
- 全数字 +
0占位:用不上的段填0,参数最短(B 码scene上限 31 字符) code约定不含.(否则破坏段位切分;base64 字符集A-Za-z0-9+/=是安全的)- 新增场景只需在
router/scenes.ts的SCENE_TABLE加一行(继续编号),后端不用改格式
示例:spm=0.4.989432.3.2
= 无发起人 · 确认登录 · 登录码 989432 · 小程序 · 二维码
13.3 时序(为什么「捕获」与「消费」要分开)
graph LR
A["App.onLaunch / onShow<br/>只捕获 + 暂存"] -->|storage| B["首页 onShow<br/>useEntryScene 消费"]
B --> C["解析场景 → 调接口 / 查表跳转"]
- 捕获点放在 App:
onLaunch时页面栈还没就绪,navigateTo会失败 - 冷启动走
onLaunch,热启动(后台被扫码唤起)走onShow—— 两处都必须接 - 暂存用 storage 而非内存变量:热启动不经过
onLaunch,且 App / 页面的初始化顺序不可控 - 同一入口只消费一次(取出即清)
⚠️ 组合式
onShow的类型声明不带参数(uni-app 类型未跟上微信的实际行为),App.vue里做了一次类型断言 —— 见该文件注释。
13.4 场景 4「确认登录」流程(已实现)
⚠️ 扫码后不直接推送:扫码是误触高发动作,直接把账号授权出去风险太大。
所以 spm 只负责解析参数 + 跳页,真正的授权由用户在确认页显式点击触发 —— 防误扫。
这与 G:\uni\数据(shopro)的做法一致(它的 spm 也只解析参数 + router.replace(page))。
graph TD
A["PC / 工作台<br/>展示二维码 spm=0.4.{登录码}"] --> B["用户微信扫码"]
B --> C["跳转确认页<br/>pages/login/confirm-login?code=xxx"]
C --> D{"已登录且已绑定?"}
D -->|是| E["展示「授权账号 + 登录码」<br/>用户点「确认授权登录」"]
D -->|否| F["提示先登录<br/>用户点「去登录」→ 弹抽屉"]
E --> G["wechat.pushLoginCode({code})"]
F --> H["暂存登录码<br/>→ 登录 / 绑定成功后自动补推送"] --> G
G --> I["后端标记 success + 记录当前账号"]
I --> J["PC / 工作台轮询取回 → 登录为该账号"]
关键实现点:
- 确认页
pages/login/confirm-login:PAGE_REGISTRY登记为auth: 'public'+hidden(未登录也能进、页内引导登录,但不作为任何菜单入口) - 不点「确认授权登录」→ 不会有任何推送(防误扫的核心)
- 未登录 / 未绑定时点「去登录」:就地弹登录抽屉(
showAuthModal('wechat')), 不跳登录页 —— 本页是扫码「带进来」的,跳走之后要一路返回才能回来;抽屉关掉仍停留本页, 登录成功后canConfirm会自动变为 true - 登录码先暂存(
utils/entry.ts的savePendingLoginCode),登录 / 绑定成功后由 store 的flushPendingLoginCode()自动补推送,用户无需回到确认页 - 自动补推送后不会重复引导:
pushLoginCode成功会把码记到 store 的pushedLoginCode, 页面据此切到「已授权」态;否则登录后isLogin变 true 会重新渲染出「确认授权登录」按钮, 而同一个码再推一次必然报「不存在或已过期」 - 失败态判定必须同时命中「登录码 + 过期/不存在」两个特征:否则未绑定时后端返回的 「用户不存在或已被删除」会误触发失败态
pushLoginCode需登录(网关用 HTTP 401 表达),故 api 层为其关掉了redirectOn401, 避免用户点一下就被踢到登录页;失败只 toast 后端原因- 登录码 TTL:生成后 300s、确认后待领取 120s
(后端
LOGIN_CODE_TTL_SECONDS/LOGIN_CODE_SUCCESS_TTL_SECONDS) - 接口只用已调通的两个:
wechat.pushLoginCode(确认授权)、wechat.getLoginWechatCode(生成 / 轮询)
13.5 其它待办
- 扫码绑定(
scene=2预留):现有wechat.bindUser走账号密码;bindAccountByTempCode在开放 API 且需ye4s_user_id(是 ye4s 后端对 WMS 的机对机调用)→ 小程序侧需后端补一个网关方法 - 个人中心「我的二维码」(工作台扫描获取用户信息)—— 反向链路,待设计
✅ 2026-09-22:其中登录码部分已实现(
wechat.getMyLoginCode+ 「我的」页展示 / 复制,见第 6 节); 二维码生成与「工作台扫码取用户信息」仍未做
14. 登录交互:半屏抽屉 + 接口级鉴权
14.1 为什么用抽屉而不是跳登录页
| 跳登录页 | 半屏抽屉(现方案) | |
|---|---|---|
| 触发 | 页面级拦截 / 401 跳转 | 碰到需要登录的接口 / 用户主动点按钮 |
| 浏览 | 被打断,登录完要回跳(redirect) |
不打断,登录完留在原页面 |
| 状态 | 页面栈变化 | store 一个字段(authView) |
参照 G:\uni\数据(shopro):用一个字段既当开关又当视图选择器。
14.2 三层结构
| 层 | 位置 | 职责 |
|---|---|---|
| 状态 | store/modules/user.ts:authView + showAuthModal() / closeAuthModal() |
'' = 关闭;'wechat' | 'account' | 'register' = 打开并指定视图 |
| 容器 | components/auth-modal/(up-popup mode="bottom") |
半屏抽屉;v-if 让每次打开重新挂载(视图与协议勾选自动复位) |
| 内容 | components/login-panel/ |
tab(第一个是微信登录)+ 协议勾选 + 注册视图 + 绑定步骤 |
挂载:uni-app 的 App.vue 没有模板 → 需在页面里各引一次 <auth-modal />
(当前:首页、「我的」、用户信息 pages/mine/user-info、确认登录、pagesA/demo/required、pagesA/test/index)。
⚠️ 漏挂是个很坑的 bug(2026-09-23 实测踩过):goLogin() 是「就地弹抽屉」而不是跳页,
它只把 store 的 authView 置上,真正渲染抽屉的是页面自己的 <auth-modal />。
漏挂的症状是「点『去登录』毫无反应,切到别的页面反而弹出登录框」——
因为状态是全局的,谁挂了谁显示。
现已加自动校验:npm run check:pages 会扫描所有 .vue,
凡用了 goLogin() / requireLogin() / showAuthModal() / <auth-gate> 却没挂 <auth-modal /> 的一律告警
(App.vue 与抽屉/auth-gate 组件自身已排除)。
⚠️ 原生 tabBar 必须手动藏:微信小程序的 tabBar 是原生组件,层级恒在
position: fixed 之上 —— 抽屉弹出时会被它切掉一截(看起来没贴到屏幕底部),改 z-index 无效。
App.vue 里 watch authVisible → 打开时 uni.hideTabBar() / 关闭时 uni.showTabBar()
(非 tabBar 页面调用会 fail,用空 fail 吞掉);onShow 再兜底同步一次,
避免出现「抽屉已关、tabBar 没回来」。
14.3 接口级鉴权(“克制”的关键)
| 能力 | 实现 |
|---|---|
| 接口声明 | RequestOptions.auth:需登录的接口传 true(user.info / user.changeRole / user.logout / wechat.pushLoginCode) |
| 请求前预判 | request.ts:auth && !token → 不发请求,直接弹抽屉(省一次无意义往返) |
| 响应兜底 | HTTP 401 / 业务码 401 → 清登录态 + 弹抽屉(不再跳页) |
| 解耦 | utils/auth-notify.ts:request 层发布、App.vue 注册处理(避开 request → store → api → request 循环依赖) |
| 中间态例外 | 微信绑定 / 确认登录传 redirectOn401: false:只提示,不清登录态、不弹抽屉 |
14.4 协议勾选
- 微信登录 / 账号登录 / 注册都必须同意《用户须知》才能提交,否则 toast「请先阅读并同意《用户须知》」
- 每次打开抽屉重新挂载 → 同意状态自动复位(不记忆,合规更稳)
- 勾选区任何位置(checkbox / 「我已阅读并同意」/《用户须知》)点击都只做一件事:打开须知弹窗 —— 不能直接打勾;勾只能在弹窗里「滑到底 + 点同意」之后才置上
- 必须滑到最底部才能同意:靠
scroll-view的scrolltolower到底才放行; 没到底时按钮呈灰态(is-disabled,仍可点,点了会 toast 说明原因)+ 橙色 ↓ 提示「请向下滑动阅读至底部」- 内容不足一屏时(
.agreement__inner高度 ≤.agreement__body)在打开后自动算已读 —— 否则短文案永远触发不了scrolltolower,用户会被卡在「点不了同意」上 - 已同意过再打开则不要求再滑一遍(
agreementRead = agreed)
- 内容不足一屏时(
- 文案改为后端下发(2026-09-23),本地常量降为兜底:
- 弹窗抽为共享组件
components/agreement-modal/,两种模式:mode="agree"(登录前勾选,必须滑到底才能同意)/mode="view"(已登录后只读查看,不要求滑动) - 两个入口:① 登录面板的协议勾选区;② 「我的」页的「用户须知」/「隐私保护指引」行 (2026-10-17 从「用户信息」页移来:一级页常驻、未登录也能查阅,合规更稳)
- 主链路:
wechat.getUserAgreementText({ appId })—— 免登录,按当前小程序运行时 AppID 取; 登录抽屉里就要看须知(此时未登录),所以必须走这条 - 已业务登录时优先:
wechat.getUserAgreement—— 按登录仓库取启用小程序,另带小程序昵称; 失败(如仓库未绑定小程序 / 未授权 / 仓库无协议配置)自动落回上一条- ⚠️ 所以已登录时会看到「两个接口都调了」:第一个失败才会走第二个(成功则提前 return)
- 失败时打
console.warn('[agreement] ...')并记下warehouseUnavailable, 本次会话不再重复探测(否则每次打开须知都白跑一趟必失败的请求);load(true)/reset()会清标记重试
- ⚠️ 登录后要升级:先拿到的是「按 AppID」的版本(
source='appid'), 登录后仓库维度才是权威 ⇒load()发现来源不是warehouse时会再拉一次覆盖, 否则因为loaded缓存短路,仓库维度那条永远轮不上(2026-09-23 实测发现) - ⚠️ 两条都失败时用组件内的
AGREEMENT_FALLBACK_TEXT: 须知接口挂了不能让用户连登录都做不到(协议勾选是登录前置条件) - api 层两个接口都
toastError: false(静默降级,不打扰用户)+redirectOn401: false - 渲染:后端是 longText 富文本 ⇒ 出现 HTML 标签走
<rich-text>,纯文本仍走<text>(保住中文排版) - 文案变化(兜底 → 后端)会重新量高度并重置已读:否则在很短的兜底文案上就把已读置真, 等长正文回来用户不滑也能同意(合规缺口)
- 状态在
store/modules/agreement.ts:会话内内存缓存 + 并发复用,load(true)可强刷 - 弹窗高度固定 460rpx + 内部滚动,文案变长变短都不用改结构
- 未使用:
wechat.setUserAgreement(设置端在 PC 后台,小程序端只读)
- 弹窗抽为共享组件
14.5 登录页保留
pages/login/login 仍保留(401 兜底 + 直接访问),内容已精简为「全屏登录面板」
(与抽屉共用 login-panel),去掉了品牌区 / logo / 底部功能说明。
注:
usePageAuth的goLogin()已改为弹抽屉(不再跳页、不再带redirect);requlreLogin()仍先弹确认框(用户确认后再弹抽屉),保持“登录由用户主动触发”。
14.6 面板排版约定(login-panel)
| 元素 | 位置 / 处理 | 原因 |
|---|---|---|
| tab(微信登录 / 账号登录) | 头部靠左 | 拇指热区,且关闭按钮独占右侧 |
| 关闭按钮 | 头部靠右(showCancel 时显示) |
符合系统弹窗习惯 |
| 取消按钮 | 已移除底部取消,仅保留右上关闭 | 减少一屏内两个“退出”入口 |
| 账号密码表单 | 无 label,只用 placeholder(请输入账号 / 请输入密码) |
省两行高度 |
| 注册表单 | 同样无 label,5 个字段靠 placeholder + 左侧图标区分(account / account-fill / email / lock / lock-fill) |
省掉 5 行;label 是注册表单最大的一笔高度浪费 |
| 两个 tab 的高度 | .login-panel__body { min-height: 370rpx } + 居中 |
切换 tab 时抽屉高度不跳动(实测差 ≤2px) |
| 面板最大高度 | .login-panel { max-height: 82vh; overflow-y: auto } |
注册字段多,小屏(如 560px 高)下内部滚动,保证「注册」按钮与协议勾选始终可达 |
| 绑定时 | 头部显示标题(绑定 WMS 账号 / 注册账号)而非 tab;隐藏协议勾选与底部“注册账号”链接 |
绑定是中间步骤,不该给“换个方式登录”的出口 |
附录 A:常用命令
| 命令 | 作用 |
|---|---|
npm run dev:mp-weixin |
开发编译(微信小程序),产物 dist/dev/mp-weixin |
npm run build:mp-weixin |
生产构建(微信小程序),产物 dist/build/mp-weixin |
npm run dev:h5 |
H5 开发调试 |
npm run build:h5 |
H5 生产构建 |
npm run type-check |
类型检查(vue-tsc) |
npm run check:pages |
静态路由表一致性校验(PAGE_REGISTRY ↔ pages.json),出错返回退出码 1 |
附录 B:关键文件职责速查
| 文件 | 职责 | 常改内容 |
|---|---|---|
src/pages.json |
路由、窗口样式、tabBar、分包、easycom | 新增页面、分包、tabBar |
src/manifest.json |
各端打包配置(mp-weixin 节点是微信端唯一来源) |
AppID、setting、权限声明、平台优化项 |
src/App.vue |
应用生命周期 + 全局样式 | uview-plus 基础样式引入 |
src/main.ts |
应用实例创建 | 全局插件注册(UI、状态管理) |
src/uni.scss |
全局 SCSS 变量 | 主题色、uview-plus 变量覆盖 |
附录 C:参考文档
- uni-app
pages.json:https://uniapp.dcloud.net.cn/collocation/pages.html - uni-app
manifest.json:https://uniapp.dcloud.net.cn/collocation/manifest.html - uview-plus 文档:https://uview-plus.jiangruyi.com
- 微信小程序开发文档:https://developers.weixin.qq.com/miniprogram/dev/framework/
- 微信小程序运营规范:https://developers.weixin.qq.com/miniprogram/product/
说明:本清单中标注 ✅ 的项已完成并经过实测验证;标注 ❌ 或未勾选的项待处理。 微信平台规则会不定期调整(尤其是隐私合规与审核规范),相关条目请以微信官方最新文档为准。