wms_mp_weixin/微信小程序开发清单.md
2026-10-17 18:05:39 +08:00

66 KiB
Raw Permalink Blame History

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-17 src/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&timestamp=...,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:参考文档


说明:本清单中标注 ✅ 的项已完成并经过实测验证;标注 ❌ 或未勾选的项待处理。 微信平台规则会不定期调整(尤其是隐私合规与审核规范),相关条目请以微信官方最新文档为准。