45 KiB
小程序页面渲染框架 · 设计与下一步任务清单
项目:
wms_mp_weixin(WMS 微信小程序端) 参考:new3(Web 管理端,动态路由)、cankao(shopro 小程序,后端菜单驱动) 状态:决策已确认,开发中。阶段 1、2、3、4 与阶段 2.5 已完成;阶段 2.5 待联调,阶段 5 待验证。 编写日期:2026-09-19 变更记录:
- 2026-09-19 页面精简 —— 仅保留「首页」「我的」两个 tab 页,「任务」「库存」页已移除
- 2026-09-19 决策确认 —— 见 §4;「工作台」更名为「首页」;
platform定为miniProgram- 2026-09-19 契约补充 ——
user.changeRole入参确认为employees[].id;空态文案见 §3.5.1- 2026-09-19 空态文案确认 —— 「未登录且为空」与「已登录拿不到数据」统一使用「服务器出差了,请稍后再试」
- 2026-09-19 开发进度 ——
userStore新增身份状态(employees/currentEmployeeId)+「我的」页身份信息卡片已实现(不改数据库)- 2026-09-19 阶段 2.5 完成 ——
user.changeRole+userStore.changeRole()+ 「我的」页切换身份入口; 实测网关确认 接口已存在(无 token 调用 → HTTP 401;不存在的方法 → HTTP 500),返回结构仍待后端确认- 2026-09-19 阶段 1 完成 —— 新增
src/router/pages.ts(PAGE_REGISTRY/PAGE_MAP/PAGE_BY_PATH+ 查询小工具) 与npm run check:pages一致性校验脚本;新增hidden字段用于区分「公共页面」与「可作为九宫格入口的页面」- 2026-09-19 阶段 2 完成 —— 新增
router/entries.ts(菜单 × 路由表 → 入口树,纯函数) 与store/modules/permission.ts;getInfo()触发时机收口到「登录成功 / 启动带 token / 切换身份」,resetToken()联动permissionStore.reset(); 顺带修掉一个真 bug:401 时未清 token,导致登录页onShow把用户弹回原页 → 401 死循环- 2026-09-19 阶段 3 完成 —— 新增
composables/usePageAuth.ts、components/auth-gate/(三态渲染)、components/empty-state/(统一空态文案 + 重试);LOCAL_PUBLIC_ENTRIES落在router/entries.ts; 「去登录」收口到usePageAuth.goLogin(),mine.vue已改用它- 2026-09-19 阶段 4 完成 —— 首页九宫格改为权限 store 驱动(分组标题 + 子项九宫格两层渲染); 「我的」新增功能菜单;新增
pagesA/demo/public(public)与pagesA/demo/required(required+ 按钮级权限示例); 新增utils/navigate.ts统一跳转;修掉一个真缺陷:本地路由表的hidden未被后端菜单口径遵守
0. 结论摘要(TL;DR)
- 后端的权限体系已经完全支持多端:
wms_permission.type枚举里已经预留miniprogram_pages(小程序页面),小程序不需要新建任何表。 - 但该类型目前是 0 条数据 —— 这是"等待后端补充设计"的核心内容,需要后端补页面数据 + 给角色授权。
user.info返回的两块数据就是渲染框架的全部输入:data.menus→ 菜单树(Web 端样本对应type='web_pages')data.permissions→ 权限点字符串数组(=type='api'的path,已逐条验证)
- 小程序端不能照搬 new3 的动态路由(
router.addRoute):小程序所有页面必须编译期注册在pages.json。 正确做法 = 本地静态路由表 + 后端菜单只做筛选/排序/可见性(即 cankao 的思路)。 - 登录策略遵循微信审核要求:未登录也能浏览,登录由用户从「我的」主动触发(现已实现)。
页面按
public/optional/required三态渲染,未登录时页内提示而非强制跳转。 - 决策点已全部确认(详见 §4):
- 「首页」「我的」为公共页面(无需登录即可访问)
- 后端
path用逻辑路径;未登录时九宫格仅显示公共入口 required页未登录 → 页内「请先登录」+ 按钮(不自动跳转)- 本期做
changeRole(角色/仓库切换) - 请求头固定
platform: miniProgram/project: all;登录后用user.info获取菜单与权限
1. 已核实的数据契约(含证据)
1.1 wms_permission 表结构(实测)
-- 数据库 wms
id int PK
path varchar 路由路径 / **API 方法名**(随 type 变化,见下表)
component varchar 组件路径(web 端为 Layout 或 @/views/xxx;非 web 端多为空)
name varchar 路由名称(有索引 MUL)
redirect varchar 重定向路径
meta_title varchar 页面标题
meta_icon varchar 图标
hidden tinyint 0 显示 / 1 隐藏
always_show tinyint 是否始终显示
parent_id int 父级 ID(根节点为 NULL)
sort int 排序
status tinyint 0 禁用 / 1 启用
type enum **权限类型**(见下)
created_at / update_at
type 枚举原文:
web_pages:电脑端页面 pda_pages:PDA页面 btns:按钮权限 api:接口权限
miniprogram_pages:小程序页面 block:功能模块 workerstation_pages:工作台菜单
1.2 各类型现有数据量(实测)
| type | 条数 | 启用 | path 字段含义 |
|---|---|---|---|
api |
259 | 259 | API 方法名,如 warehouse.create、store.getStoreRoles |
web_pages |
89 | 89 | Web 路由路径,如 /order、/storage |
pda_pages |
47 | 46 | PDA 页面路径 |
block |
12 | 12 | 功能模块标识 |
workerstation_pages |
3 | 3 | 工作台菜单路径,如 /order、/catchWeight |
miniprogram_pages |
0 | — | ⚠️ 待后端补充 |
参照
workerstation_pages的形态:component为空字符串(分组/入口节点不需要组件), 可直接作为miniprogram_pages的建模模板。
1.3 权限链路(实测表结构)
wms_account 登录账号(id/username/phone/email/password_hash/real_name/status/last_login_ip)
│
▼
wms_account_store_employee 账号在某个货主下的员工身份(id/store_id/is_primary/real_name/auth_end/role_type)
│ ← 即 user.info 返回的 data.employees[]
▼
wms_employee_role employee_id ↔ role_id
│
▼
wms_role 角色(id/role_code/role_name/role_type/scope/is_system/status/store_id/pid/**permissions**)
│ permissions = '*'(全量) 或 '[13,18,48,...]'(wms_permission.id 列表)
▼
wms_permission 按 type 过滤出「该端的页面」+「api 权限点」
关键点:wms_role.permissions 存的是 wms_permission.id 的 JSON 数组(或 *),
不是权限点字符串。后端负责把它展开成最终结果返回给前端。
1.4 user.info 返回结构(取自 new3 真实抓包样本)
{
"flag": "success", "code": 200, "message": "获取成功{}", "success": true,
"data": {
"id": 3, "status": 1, "avatar": "...",
"auth_end": "2099-12-26",
"employees_id": 34, "employees_name": "殷建铭",
"loginIp": "...", "store_id": 1000028, "store_name": "天豹云仓",
"store_type": "warehouse", // warehouse | store ...
"userRole": "customer",
"platform_code": "web", // ★ 与请求头 platform 对应
"employees": [ // 该账号在多个货主下的身份
{ "id": 34, "store_id": 1000028, "store_name": "天豹云仓",
"is_primary": 0, "real_name": "殷建铭", "auth_end": "2099-12-26", "role_type": "warehouse" }
],
"menus": [ // ★ 页面树(渲染框架的核心输入)
{
"path": "/order", "component": "Layout", "name": "Order",
"redirect": "", "hidden": false, "alwaysShow": false,
"meta": { "title": "订单", "icon": null },
"children": [ /* 递归同构 */ ]
}
],
"permissions": [ // ★ 接口权限点(= type='api' 的 path)
"dashboard.hotOrderRank", "store.getStoreRoles", "store.auditApply"
]
}
}
已验证的对应关系(逐条比对,非推测):
| 结论 | 证据 |
|---|---|
menus = type='web_pages' 的树(样本 platform_code='web') |
样本 16 个根节点与 web_pages 中 parent_id IS NULL 的 16 行完全一致(path/component/name/meta_title/sort 逐条对上) |
permissions = type='api' 的 path 列表 |
样本含 store.getStoreRoles、store.auditApply,正是 wms_permission 中 id=52、53 两行的 path |
父节点 component='Layout',叶子为 @/views/... |
样本 /order → Layout;/auth/approve → @/views/auth/approve |
| 菜单是真树(children 非空) | 样本 /storage children=15、/setting children=12、/auth/approve children=0 |
⇒ 结论:user.info 按请求头 platform 决定用哪个 type 过滤页面:
platform: web → web_pages;platform: miniProgram → miniprogram_pages。
这解释了为什么网关卡会校验 platform(它不是统计标记,而是权限过滤维度)。
本项目固定取值(已确认):
| 请求头 | 取值 | 实测说明 |
|---|---|---|
platform |
miniProgram |
网关卡白名单为 web / app / wx / miniProgram,且大小写不敏感 |
project |
all |
白名单 all / wms;其余值(含空)直接 400 |
配置位置:.env.development / .env.production 的 VITE_APP_PLATFORM / VITE_APP_PROJECT,
代码侧见 utils/request.ts 的 PLATFORM / PROJECT 常量(仅作 .env 缺失时的兜底)。
⚠️ 排查提示:若登录后
menus为空且permissions异常,先把VITE_APP_PLATFORM改成全小写miniprogram试一次 —— 排除后端platform_code精确匹配(大小写敏感)的可能。 网关卡两种写法都放行,改一行.env即可。
2. 参考项目的设计对比
| 维度 | new3(Web,Vue3 + vue-router) | cankao(小程序,uni-app Vue2) | wechat 应取 |
|---|---|---|---|
| 页面注册 | router.addRoute() 运行时动态注册 |
pages.json 编译期静态注册 |
✅ cankao |
| 后端菜单作用 | transformMenusToRoutes(menus) 生成路由 |
common.pages 返回菜单树 → 首页九宫格渲染 |
✅ 折中(见第 3 节) |
| 菜单 → 页面映射 | router/map.ts 的 componentMap(字符串键 → 动态 import) |
后端直接给 url,前端 navigateTo |
✅ new3 的映射表思想 |
| 兜底策略 | 未命中 componentMap → import.meta.glob → 再未命中 → 404.vue |
无兜底 | ✅ new3 思想(改为"忽略 + 告警") |
| 页面准入 | router.beforeEach 白名单 + getToken(),未登录重定向 /login?redirect= |
pages.json 的 meta.auth + 全局守卫 → 弹登录框 + next(false) |
✅ cankao(页内提示,不跳转) |
| 布局 | Layout + Sidebar + TopMenu + Breadcrumb + TaskView 页签 + keep-alive 缓存 |
小程序原生 tabBar + 页面内导航 | ❌ 全部不搬 |
| 图标 | SvgIcon + vite-plugin-svg-icons |
uview 图标 | ❌ 用 uview-plus up-icon |
| 进度条 | nprogress |
无 | ❌ 不适用 |
小程序硬约束(决定了不能照搬 new3)
- 所有页面必须编译期注册在
pages.json,app.json里没有的页面运行时不复存在 →addRoute无对应能力。 - 没有全局路由守卫:
uni.addInterceptor只能拦 JS 跳转 API,拦不住 tabBar 点击与启动页。 (且上一轮已按审核要求移除全局强制登录拦截。) - 没有 keep-alive / 页签:用原生页面栈 + tabBar 替代。
- 没有 DOM:
Layout/Sidebar这类基于 DOM 的布局组件不适用。
3. 小程序端渲染框架设计(方案)
3.1 分层
flowchart TD
A["user.info<br/>menus(树) + permissions(权限点)"] --> B["store/modules/permission.ts"]
B --> C["generateEntries(menus)<br/>菜单 × PAGE_REGISTRY → 可见入口树"]
C --> D1["首页:入口九宫格"]
C --> D2["我的页:功能菜单"]
C --> D3["任意页面:入口/按钮可见性"]
B --> E["hasPermission(code)<br/>权限点判断"]
F["router/pages.ts<br/>PAGE_REGISTRY(静态路由表)"] --> C
G["composables/usePageAuth.ts<br/>+ components/auth-gate"] --> H["页面级三态渲染<br/>public / optional / required"]
B --> G
3.2 静态路由表 PAGE_REGISTRY(替代 pages.json 的运行时元数据)
pages.json 只为编译服务(微信只认 pages/style/subPackages/tabBar),
在代码里它读不出来。因此新增一份运行时可用的页面清单:
// src/router/pages.ts(✅ 已实现,2026-09-19)
export type AuthMode = 'public' | 'optional' | 'required'
export interface PageMeta {
/** 逻辑路径:与后端 wms_permission.path 对齐 */
key: string
/** 小程序物理页面路径(必须与 pages.json 一致,不带前导 /) */
path: string
title: string
icon?: string
auth: AuthMode
/** tabBar 页:跳转必须用 switchTab */
tabBar?: boolean
/** 不进导航入口(可被跳转,但不进九宫格/功能菜单) */
hidden?: boolean
}
export const PAGE_REGISTRY: PageMeta[] = [
{ key: '/home', path: 'pages/index/index', title: '首页', icon: 'home', auth: 'public', tabBar: true, hidden: true },
{ key: '/mine', path: 'pages/mine/mine', title: '我的', icon: 'account', auth: 'optional', tabBar: true, hidden: true },
{ key: '/login', path: 'pages/login/login', title: '登录 / 注册', icon: 'account-fill', auth: 'public', hidden: true },
// 业务页(分包):待页面文件 + pages.json.subPackages 就绪后再启用(当前为注释示例)
]
export const PAGE_MAP = new Map(PAGE_REGISTRY.map((p) => [p.key, p])) // key → meta
export const PAGE_BY_PATH = new Map(PAGE_REGISTRY.map((p) => [p.path, p])) // path → meta
// 附带 getPageByKey() / getPageByPath() / isTabBarPage() 三个小工具
为什么多了一个 hidden 字段:阶段 3 的 LOCAL_PUBLIC_ENTRIES 若简单等于
「所有 auth === 'public' 的页面」,会把「首页」也塞进九宫格。因此「能不能作为入口」被抽成
isEntryVisible(meta) = !meta.tabBar && !meta.hidden,两个来源(本地公共清单 / 后端菜单)共用它。
只登记真实存在的页面(重要):pagesA/B/C 目前只有 .gitkeep 占位,所以没有登记它们
—— 登记了 pages.json 里没有的页面,用户点进去必然失败。示例条目以注释形式留在文件里,
待页面建好 + 注册到 pages.json.subPackages 后再启用。
与 new3 的
componentMap是同一个思想:后端只给逻辑标识,前端持有"标识 → 真实页面"的映射。 好处:页面从主包挪到分包、改目录名,都只改前端一处;后端不必知道编译期路径。
防漂移(已实现):新增 npm run check:pages(scripts/check-pages.mjs),校验三件事:
① PAGE_REGISTRY[].path 必须已注册在 pages.json;② key 不重复;
③ pages.json 已注册但未登记的页面 → 告警(不阻断)。
已实测:正常时打印「PAGE_REGISTRY 3 条 / 已注册 3 个页面」;故意插入未注册页面时报错并退出码 1。
(实现为 Node 正则解析 pages.ts,所以条目要保持「字面量对象 + 单引号」写法;
反过来,pages.json 里允许写注释 —— 解析器是按字符状态机去注释的。)
3.3 权限 store + 入口树生成(✅ 已实现)
拆成两个文件,职责分离(菜单 → 路由表的映射属路由域,不塞进 store):
| 文件 | 职责 |
|---|---|
src/router/entries.ts |
纯函数 generateEntries(menus) → { entries, missing };类型 MenuNode / EntryLeaf / EntryGroup / EntryNode |
src/store/modules/permission.ts |
持有 menus / entries / missing / loaded;动作 loadFromMenus() / reset() |
// src/store/modules/permission.ts
state: {
menus: MenuNode[] // 后端原始菜单树(排障用)
entries: EntryNode[] // 经 PAGE_REGISTRY 过滤后的可见入口树(供 UI 渲染)
missing: string[] // 后端下发但本地未注册的 key(用于告警/排查)
loaded: boolean // 区分「未加载」与「加载后确实为空」
}
getters: { hasEntries, leafCount }
actions: {
loadFromMenus(menus) // userStore.getInfo() 成功后调用
reset() // 退出登录 / 401 / 清缓存时调用
}
入口树固定两层:EntryGroup.children 的类型就是 EntryLeaf[] ——
首页是「分组标题 + 子项九宫格」(决策点 4),所以后端菜单即使嵌套更深,
也会被拉平到所属根分组,UI 不必处理任意深度。
触发时机(统一收口,已实现)
| 场景 | 触发点 |
|---|---|
| 登录成功 | userStore.login() 末尾 await this.getInfo()(失败不阻塞登录) |
| 启动时带 token | App.vue 的 onLaunch:有 token 就 getInfo() |
| 切换身份后 | userStore.changeRole() 末尾重调 getInfo() |
| 退出 / 401 / 清缓存 | userStore.resetToken() → permissionStore.reset() |
401 额外修复了一个真 bug:utils/request.ts 在 401 时原本只跳登录页、不删 token,
而登录页 onShow 里有 if (getToken()) goAfterLogin() → 用户被立刻送回刚才那个页面
→ 再次 401 → 死循环。现改为 clearSession()(removeToken() + permissionStore.reset())+ 跳登录页。
request 层仍不引入 userStore(会形成 request → userStore → api → request 循环引用); 但权限 store 只依赖
router/entries、不依赖 api,所以引入它是安全的、不构成循环。
generateEntries() 的兜底规则(对齐 new3 resolveComponent 的兜底思想):
| 情况 | 处理 |
|---|---|
菜单项 key 命中 PAGE_REGISTRY |
收进 entries,携带 title/icon/auth |
| 未命中 | 忽略该项,记入 missing 并 console.warn |
| 分组节点无子项命中 | 整组丢弃(避免空分组) |
菜单项 hidden = 1 |
不进导航入口(但可能仍需被 permissions 引用) |
页面上标了 hidden 或 tabBar(本地路由表) |
同样不进入口 —— 与公共清单共用 isEntryVisible(meta) 口径 |
全部为 0 条(如后端还没配 miniprogram_pages) |
entries 为空 → UI 回退到本地公共入口清单(见 3.5) |
| 最终仍为空 / 接口失败 | 渲染统一兜底文案「服务器出差了,请稍后再试」(见 3.5.1) |
上述规则已逐条用用例验证(把 entries.ts 编译为 CJS 后用 Node 跑,16 项断言全通过):
命中 → 收进并带本地 path/auth;未命中 → 进 missing 且不影响其它入口;
分组全空 → 整组丢弃;hidden=1 → 剔除且不记 missing(是「隐藏」不是「没登记」);
同 key 重复 → 去重;menus 为 null / undefined / [] → 不抛错;
后端未给 meta.title/meta.icon → 回退本地路由表;分组节点自身的 path 不进 missing。
⚠️ 实测提醒(当前的预期行为):后端现在下发的是
web_pages路径(如/order、/storage), 与小程序本地登记的逻辑路径(/home等)必然全部不匹配 →entries为空 +console.warn列出全部 missing → UI 走空态文案。 这不是 bug,等后端补上miniprogram_pages(§6 第 1、2 条)后自动生效,前端无需改动。
3.4 页面三态渲染:public / optional / required
这是"有些页面登录前和登录后显示不同内容、有些页面未登录也能显示"的统一解法:
把策略声明在页面清单里,把判断收口到一个组件里,页面内不再散落 if (isLogin)。
「公共页面」的定义(已确认):无需登录即可访问。
public和optional都属于公共页面,二者都不会被 auth-gate 拦截, 区别只在「未登录时是否显示不同内容」。
| auth | 需登录才能访问? | 未登录时 | 已登录时 | 典型页面 |
|---|---|---|---|---|
public |
❌ 不需要 | 正常渲染完整内容 | 正常渲染(可附加个性化) | 首页、公告/帮助、公开查询页 |
optional |
❌ 不需要 | 渲染占位/引导内容(空态、"登录后查看") | 渲染真实数据 | 我的、个人数据看板 |
required |
✅ 需要 | 渲染**「请先登录」**提示 + 「去登录」按钮(不自动跳转) | 正常渲染 | 作业页(入库/出库/盘点) |
配套三个小件(✅ 已实现):
<!-- src/components/auth-gate/auth-gate.vue -->
<auth-gate auth="required">
<template #default><!-- 已登录内容 --></template>
</auth-gate>
<auth-gate auth="optional">
<template #default><!-- 已登录内容 --></template>
<template #guest><!-- 未登录自定义占位,不传则用内置引导 --></template>
</auth-gate>
// src/composables/usePageAuth.ts
const { isLogin, canRender, needLogin, goLogin, requireLogin } = usePageAuth('required')
// 省略参数 → 自动按当前页在 PAGE_REGISTRY 里的声明判定(策略只有一处声明)
const { canRender } = usePageAuth()
<!-- src/components/empty-state/empty-state.vue -->
<empty-state @retry="load" />
<empty-state @retry="load"> <!-- 未登录时可再挂一个「去登录」 -->
<template #action><up-button text="去登录" /></template>
</empty-state>
| 实现决策 | 说明 |
|---|---|
usePageAuth(auth?) 参数可省略 |
省略时按 getCurrentRoute() 从 PAGE_REGISTRY 取 auth;未登记页面按 required 兜底 + console.warn(宁可多提示,不可漏保护) |
| 未登录不自动跳转 | redirectToLogin() 只在 401 时用;页面内的引导一律走 requireLogin()(弹框确认后才跳)或 goLogin()(用户点按钮) |
| 「去登录」只有一条实现 | usePageAuth.goLogin() 内部复用 LOGIN_PAGE 并自动带 redirect 回本页;pages/mine/mine.vue 已改用它,不再自己拼 URL |
❌ 不单独建 guest-placeholder 组件 |
auth-gate 的内置引导已覆盖两种语气(required → 「请先登录」;optional → 「登录后查看」),再拆一个组件只会多一层间接 |
✅ 新增 empty-state 组件 |
§3.5.1 的空态/失败文案 + 「重试」按钮需多页复用(首页、我的),且要能再挂一个「去登录」动作位,所以这里值得独立组件 |
编译验证:用临时用法把两个组件接进首页跑了一次
build:mp-weixin,产物里auth-gate.wxml的三分支(默认 slot /guestslot / 内置引导)与empty-state.wxml的slot name="action"条件渲染都正确生成; 移除临时用法后两个组件不再进包(easycom 按需引入生效)。
3.5 未登录态的入口渲染(关键设计)
微信审核要求:未登录也必须有可浏览的内容,且不能自动跳登录页。
未登录:
首页九宫格 ← LOCAL_PUBLIC_ENTRIES(前端本地维护的公共入口清单,只含 auth: 'public' 的页面)
✅ 当前有 1 个(pagesA/demo/public 示例页);若一个都没有 → 渲染空态文案(见 3.5.1),不白屏
tabBar 2 个 Tab(首页 / 我的)正常可用(两者都是公共页面)
「我的」显示「登录 / 注册」按钮
点 required 入口 → 页内「请先登录」+ 去登录按钮
已登录:
首页九宫格 ← permissionStore.entries(后端菜单 × PAGE_REGISTRY,按角色/权限过滤)
⚠️ 后端未配 miniprogram_pages 时 entries 为空 → 同样走空态文案 + 「重试」
「我的」显示身份信息(姓名/类型/组织/员工 ID/授权到期)+ 功能菜单(仅 entries 非空时)+ 退出登录
点 required 入口 → 正常进入
为什么公共入口用本地清单而不是后端?
- 保证"未登录可见"是确定性的,不依赖后端是否配置、不受网络/接口故障影响(审核时更可控)
- 后端
miniprogram_pages只需描述"登录后能看到什么" - 若将来需要运营侧控制公共入口,再让后端加字段(见 §6 建议)
3.5.1 九宫格空态 / 失败提示文案(已确认)
| 场景 | 展示文案 |
|---|---|
| 未登录 + 九宫格为空 | 「服务器出差了,请稍后再试」(✅ 已确认) |
已登录 + 菜单为空(后端未配 miniprogram_pages) |
同上 |
| 已登录 + 接口失败 / 返回空数据 | 同上 |
统一要求:不能白屏;文案下方配套一个「重试」按钮(未登录场景可同时给「去登录」)。
✅ 已确认(2026-09-19):客户拍板——两种场景统一用同一句「服务器出差了,请稍后再试」, 不做「未登录引导文案」的区分(即上表即为最终行为)。
3.6 渲染调用链(最终形态)
sequenceDiagram
participant U as 用户
participant P as 页面
participant S as permissionStore
participant R as request
Note over U,S: 未登录
U->>P: 打开小程序(启动页=首页)
P->>S: 读取 entries
S-->>P: 空 → 回退 LOCAL_PUBLIC_ENTRIES
P-->>U: 渲染公共入口 + 正常可浏览
Note over U,R: 登录
U->>P: 我的 → 登录 / 注册
P->>R: user.login
R-->>P: data.token
P->>R: user.info
R-->>S: menus + permissions
S->>S: generateEntries(menus) × PAGE_REGISTRY
S-->>P: 可见入口树
P-->>U: 首页/我的 按权限渲染
Note over U,R: token 失效
R->>S: 401 → reset()
R->>P: 回未登录态(带 redirect 跳登录)
3.7 复用现有代码的接入点(已经就绪)
| 已有 | 位置 | 在框架中的角色 |
|---|---|---|
userStore.getInfo() |
store/modules/user.ts |
已能拉到 menus / permissions(类型已声明 menus?: any[]) |
userStore.permissions / checkPermission() |
同上 | 权限点判断,可直接用 |
redirectToLogin(redirect?) |
utils/auth-guard.ts |
401 时带来源页跳登录 |
| 「我的」页登录入口 + 登录页「取消」 | pages/mine/mine.vue、pages/login/login.vue |
已符合审核要求,无需改动 |
LOGIN_PAGE 常量 |
utils/auth-guard.ts |
跳登录页的唯一来源 |
需要调整的一处:目前 getInfo() 只在「我的」页 onShow 里触发。
✅ 已调整(阶段 2):改为「登录成功 login() / 启动时带 token App.onLaunch / 切换身份 changeRole()」
统一触发;「我的」页的 onShow 保留为兑底重试(仅在信息未拉到时才请求)。
4. 已确认的决策(2026-09-19 拍板)
| # | 决策点 | 确认结论 | 对实现的影响 |
|---|---|---|---|
| 1 | 未登录可见的入口清单由谁定义 | 前端本地清单 LOCAL_PUBLIC_ENTRIES |
未登录渲染不依赖后端/网络,审核可控;后端 guest_visible 作为将来可选升级 |
| 2 | 后端菜单 path 形态 |
逻辑路径(如 /inbound/list) |
前端维护 PAGE_REGISTRY;页面挪分包/改目录不用改数据库 |
| 3 | required 页未登录交互 |
页内「请先登录」+ 按钮(不自动跳转) | 需 auth-gate 组件 + usePageAuth() |
| 4 | 首页菜单分组呈现 | 分组标题 + 子项九宫格(cankao 形态) | 首页需支持"分组 → 子项"两层渲染 |
| 5 | 角色/仓库切换 changeRole |
本期做 | 新增切换接口 + 切换后重建菜单/权限,见 §4.2 |
| 6 | platform → type 映射 |
platform: **miniProgram** / project: **all** |
已在 .env 落地;实测网关卡大小写不敏感 |
| 7 | 未登录九宫格内容 | 仅公共入口 | 未登录时可能为空 → 必须做空态引导 |
选择理由(简述)
- 1:本地清单保证"未登录一定有内容可看",不依赖后端进度与网络;后端字段将来可作为覆盖(本地兜底 + 后端覆盖)
- 2:"页面在主包还是分包"是构建期决策,后端不该感知;同一套菜单模型可复用到 PDA / 工作台端
- 3:审核最稳;跳转式登录在审核员视角接近"强制登录"
- 4:与 cankao 一致,实现成本最低;待入口真多到一屏放不下再升级为分组 Tab
- 5:本期一并做,避免以后把"是否登录"模型二次返工成"以哪个身份登录"
- 7:规避"诱导登录"判定
4.1 页面归属(已确认)
| 页面 | 物理路径 | 是否公共页面 | auth | 说明 |
|---|---|---|---|---|
| 首页 | pages/index/index |
✅ 是 | public |
tabBar 第 1 项(启动页);内容与登录态无关 |
| 我的 | pages/mine/mine |
✅ 是 | optional |
tabBar 第 2 项;页面可访问,内容分登录前/后 |
| 登录页 | pages/login/login |
— | — | 非 tabBar;由用户从「我的」主动进入 |
两者都是公共页面(无需登录、无需权限即可显示),因此不会出现登录拦截。
4.2 changeRole 实现要点(本期新增)
数据来源:user.info 返回的 data.employees[] —— 一个账号在多个货主/仓库下的身份。
| 项 | 说明 |
|---|---|
| 可切换项 | employees[](id / store_id / store_name / real_name / role_type / is_primary / auth_end) |
| 切换入口 | 「我的」页(仅登录后可见):展示当前身份 + 「切换」;多身份时该行出现,点开用 uni.showActionSheet 选(当前身份标「(当前)」) |
| 调用接口 | user.changeRole({ roleId, device })✅ 入参已确认: roleId = employees[].id(与 new3 一致)✅ 接口已实测存在(无 token 调用 → HTTP 401;而不存在的方法 → HTTP 500) |
| 返回处理 | new3:返回 data.user + data.token → 换发 token、重设 user✅ 已按“两种都可能”兼容实现:有 token 则写新 token(未回传则沿用旧 token);有 user 先落库,最后统一重拉 user.info 为准 |
| 切换后必做 | ① 写新 token ✅;② 重调 user.info 重建 menus/permissions ✅;③ permissionStore.reset() 后重建 entries ✅(阶段 2 已接入);④ 首页九宫格 / 我的菜单刷新 ⏳(待阶段 4) |
| 失败处理 | ✅ 只有切换接口本身失败才回滚已选身份;后续 getInfo 失败不回滚(此时后端已切换,回滚反而造成前后端不一致) |
| 默认身份 | 优先级:① 本地已选身份仍在列表中 → 保留;② user.info 的 employees_id(后端会话身份)在列表中 → 以其为准;③ 都没有 → 主身份(is_primary)→ 授权未过期 → 第一个✅ 已实现( setEmployees / pickDefaultEmployeeId)⚠️ 保留“本地优先”的原因:本地指针只会被“后端下发的值”或“已确认成功的 changeRole”写入;若改成完全以后端为准,一旦 changeRole 成功后 employees_id 未及时更新,界面会立刻弹回旧身份 |
5. 下一步任务清单
阶段 0 · 契约确认(前后端对齐,不写业务代码)
- 确认
platform头 →wms_permission.type的映射表 ✅ 已确认:web→web_pages,miniProgram→miniprogram_pages(app→ 待补) - 确认小程序端应使用的
platform取值 ✅ 已确认:miniProgram(网关卡大小写不敏感,wx亦放行,但以miniProgram为准) - 确认
user.info在platform=miniprogram时返回的menus是否取自miniprogram_pages - 确认
permissions[]是否仍返回type='api'的全集(小程序端是否需要按端过滤) - 与后端敲定小程序页面
path的命名规范(逻辑路径 vs 物理路径,见决策点 2) - 与后端敲定分组节点的表示(参照
workerstation_pages:component留空) - 确认
hidden在小程序端的语义(不进导航但可被跳转?)
阶段 1 · 前端静态路由表
- 新增
src/router/pages.ts:PageMeta类型 +PAGE_REGISTRY+PAGE_MAP(另附PAGE_BY_PATH)✅ 2026-09-19 - 盘点现有 2 个 tabBar 页(首页 / 我的)+ 已规划的分包页,登记
key / path / title / icon / auth / tabBar✅ 已登记 3 个真实存在的页面(首页 / 我的 / 登录)。分包页pagesA/B/C目前只有.gitkeep, 故意不登记(登记不存在的页面 = 点击必失败),示例以注释形式留在文件里 - (可选)加一致性校验脚本:
PAGE_REGISTRY.path必须存在于pages.json,否则构建告警 ✅ 已实现:npm run check:pages(scripts/check-pages.mjs);实测能检出未注册页面并返回退出码 1 - (可选)给
pages.json各页面补meta: { title, auth }—— ❌ 决定不做:pages.json是编译期文件、运行时读不出来,补 meta 只会形成第二份真相、必然漂移
阶段 2 · 权限 store
- 新增
src/store/modules/permission.ts:menus/entries/missing/loaded✅ 2026-09-19 - 实现
generateEntries(menus):菜单树 ×PAGE_REGISTRY→ 可见入口树(含未命中告警、空分组剔除) ✅ 放在src/router/entries.ts(纯函数);16 项断言用例全通过(见 §3.3) - 实现
reset():退出登录、401、清缓存时调用 ✅ 2026-09-19 userStore.logout()/resetToken()里联动调用permissionStore.reset()✅(logout走resetToken)- 把
getInfo()的调用时机改为登录成功后 + 启动时带 token 统一触发(不再只在「我的」页) ✅ 登录 →login()内;启动 →App.vueonLaunch;切换身份 →changeRole()内 getInfo()成功后把menus/permissions灌进 permission store ✅menus→permissionStore.loadFromMenus();permissions仍在userStore(checkPermission()),本期不动
阶段 2.5 · 角色/仓库切换 changeRole(本期确认要做)
- 确认
user.changeRole入参:roleId=employees[].id(与 new3 一致)✅ api/user/user.ts新增changeRole({ roleId, device })✅ 2026-09-19userStore新增changeRole(action):换发 token → 重设user→ 重调getInfo()→ 重建权限 ✅ 2026-09-19userStore新增「当前身份」状态(employees[]+currentEmployeeId+setEmployees()默认身份选择)✅ 2026-09-19userStore新增setCurrentEmployee()切换方法(配合changeRole调用)✅ 2026-09-19permissionStore.reset()后重建entries(避免旧身份的菜单残留)✅ 2026-09-19(阶段 2 完成后已接入)- 「我的」页新增身份展示(姓名 / 身份类型 / 所属组织 / 员工 ID / 授权到期)✅ 2026-09-19
- 「我的」页新增「切换身份 / 仓库」入口(仅登录后显示,多身份时出现)✅ 2026-09-19
- 验证:切换后首页九宫格 / 我的菜单立即按新身份刷新;旧身份入口不残留 —— ⏳ 待阶段 4 页面接入后联调
阶段 3 · 登录态与页面渲染策略
- 新增
src/composables/usePageAuth.ts:按auth返回isLogin/canRender/requireLogin()✅ 2026-09-19(auth可省略,自动按当前页从PAGE_REGISTRY取;额外提供goLogin/needLogin) - 新增
src/components/auth-gate/auth-gate.vue:三态渲染 + 内置「请先登录」+「去登录」按钮 ✅ 2026-09-19 - (可选)新增
src/components/guest-placeholder/:未登录占位(骨架/空态/引导) ❌ 决定不建 —— 已折进auth-gate的内置引导(两种语气); 改为新增components/empty-state/,承担 §3.5.1 的空态/失败文案 + 「重试」按钮 LOCAL_PUBLIC_ENTRIES:本地公共入口清单(只含auth: 'public'的页面) ✅ 定义在src/router/entries.ts(筛选auth === 'public' && !tabBar && !hidden); 当前为空数组(3 个已登记页面都不满足)→ 首页会走空态文案,属预期- 首页九宫格空态 / 失败提示:按 §3.5.1 的文案规范渲染(含「重试」按钮),不能白屏
✅ 已提供
components/empty-state/(默认文案即 §3.5.1 那句,可挂「去登录」动作位);首页接入在阶段 4 - 统一「去登录」的跳转:带
redirect回本页(复用LOGIN_PAGE,不新造路径) ✅usePageAuth.goLogin()为唯一实现;pages/mine/mine.vue已改用(删掉自己拼 URL 的写法)
阶段 4 · 页面接入
pages/index/index.vue:九宫格改为 permission store 驱动,且支持**「分组标题 + 子项九宫格」两层渲染**; 未登录回退LOCAL_PUBLIC_ENTRIES;无内容 / 请求失败时按 §3.5.1 渲染空态文案 ✅ 2026-09-19:三个分支(loading→sections→empty-state); 分组/叶子拍平由toSections()统一处理pages/mine/mine.vue:已登录时展示**「身份信息」卡片**(数据来自user.info的employees[],不改数据库)✅ 2026-09-19 ↳ 2026-09-22 已迁入二级页pages/mine/user-info.vue(见下)- 2026-09-22 「我的」页改为「菜单 + 二级页」结构:
-
pages/mine/mine.vue只留「登录入口 / 菜单 / 退出登录」(缓解 tabBar 页堆卡片) - 新增pages/mine/user-info.vue(key=/mine/user-info,auth: optional+hidden: true): 用户信息(身份信息 + 切换身份)、待绑定 WMS 账号、微信资料、电脑端登录码、退出登录 - 跳转统一走getPageByKey()+navigateToPath():物理路径只有PAGE_REGISTRY一份,页面里不写死 - 未登录进入二级页时渲染页内引导(empty-state+ 「去登录」),不自动跳转 ✅ 2026-09-19:与首页同源(pages/mine/mine.vue:已登录时展示「功能菜单」(来自 entries)toSections(permissionStore.entries)); ❌ 2026-09-22 已移除:功能菜单只留在首页九宫格,「我的」页只放与账号相关的项 (身份信息 / 清除本地缓存 / 退出登录);同批移除「当前版本」「运行平台」两行- 新增一个未登录可用的公开页作为
public示例(原计划的「库存」tab 已于 2026-09-19 精简移除) ✅pagesA/demo/public(分包,auth: 'public',不设hidden) - 至少再造 1 个
required页示例,验证「页内请先登录」体验 ✅pagesA/demo/required(分包,auth: 'required');已加入pages.json的condition开发编译模式,微信开发者工具下拉即可直达 - 页面按钮级权限:用
checkPermission('xxx.yyy')控制显隐(示例 1~2 处) ✅pagesA/demo/required.vue:store.getStoreRoles有权限才渲染按钮, 否则显示一句说明;该页还列出当前账号的权限点(前 20 个)作联调参照
阶段 4 额外做了两件事(不在原清单里,但属工程必需): ①
pages.json注册了subPackages(root: pagesA)—— 顺便销掉了《开发清单》第 3 节的「分包未注册」; ② 新增utils/navigate.ts统一跳转(自动区分switchTab/navigateTo),首页与我的共用。
阶段 5 · 验证与文档
- 未登录:启动进首页 → 可正常浏览 → 「我的」看到登录入口 → 点登录 → 可取消返回 🔧 可用微信开发者工具的编译模式直达:首页 / 我的 / 登录 / 公开示例页 / 需登录示例页
- 登录后:九宫格按后端菜单出现 → 无权限项不出现 → 「我的」显示姓名/身份类型/所属组织
- 后端未配
miniprogram_pages时(现状):不白屏、不报错,回退公共入口 + 控制台告警 - 空态:九宫格为空 / 接口失败时展示 §3.5.1 的文案,不出现白屏或裸露报错
- 401 / token 过期:回退未登录态、清空 permission store、带
redirect跳登录可正常回跳 ⚠️ 该路径已顺带修了一个死循环 bug(401 未清 token → 登录页把人弹回原页),待真机复验 - 退出登录:permission store 清空、「我的」切回未登录态
- 更新《微信小程序开发清单.md》(新增"页面渲染框架"章节)
6. 给后端的补充需求清单
这些是"等待后端补充设计接入功能"的具体内容。
必需
- 补充
wms_permission中type='miniprogram_pages'的页面数据(当前 0 条)- 字段建议(参照
workerstation_pages):字段 小程序端用法建议 path小程序页面逻辑路径(如 /home、/inbound/list)—— 已确认用逻辑路径,前端负责映射到物理页面component分组节点留空;叶子节点可留空(小程序无需组件路径) name唯一标识(用于日志/排查) meta_title菜单显示名 meta_icon图标名(建议直接给 uview-plus 合法图标名) parent_id分组层级(NULL 为根) sort排序 status启用/禁用 type'miniprogram_pages'
- 字段建议(参照
- 给角色授权:在
wms_role.permissions中加入上述wms_permission.id - 确认并固化
platform头 →type的映射:platform: web→web_pages;platform: miniProgram→miniprogram_pages。 本项目已固定platform: miniProgram/project: all(网关卡实测大小写不敏感)。 - 明确
user.info在小程序端返回menus的来源(按platform过滤type) user.changeRole接口:✅ 已实测存在(POST /system?method=user.changeRole无 token 调用返回 HTTP 401; 对照不存在的方法返回 HTTP 500)。入参 ✅ 已确认roleId=employees[].id; ⏳ 仍需后端确认返回结构:是否返回data.user+data.token(用于换发 token)。 前端已按“两种都可能”实现:有token就换、有user就落库,最后统一重调user.info(见 §4.2)
建议(可选,能省掉前端硬编码)
wms_permission增加guest_visible(tinyint) 字段 → 由运营侧控制"未登录可见"的页面, 前端即可去掉LOCAL_PUBLIC_ENTRIES硬编码(对应 §4 决策点 1 的平滑升级路径)user.info的data增加authMode或直接返回guestVisible,让页面三态由后端驱动- 后续如需按端裁剪
permissions[](减少下发体积),建议增加platform维度过滤
7. 明确排除项(从 new3 移植清单中剔除)
| 排除项 | 原因 |
|---|---|
router.addRoute() / transformMenusToRoutes 动态注册 |
小程序页面编译期固定,运行时不支持 |
router/map.ts 的 () => import('@/views/...') 动态 import |
小程序无此机制;改为 PAGE_REGISTRY 的静态映射 |
import.meta.glob('@/views/**/*.vue') 兜底 |
同上;改为"忽略 + 告警 + 回退公共入口" |
layout/**(Layout/AppMain/Navbar/TopMenu) |
无 DOM,且小程序布局是页面自带的 |
Sidebar/* + Breadcrumb |
小程序导航靠 tabBar + 页面标题 |
TaskView 页签 + tagsView store + keep-alive 缓存 |
小程序用原生页面栈,无页签/缓存概念 |
SvgIcon + vite-plugin-svg-icons |
统一用 uview-plus 的 up-icon |
nprogress |
小程序无浏览器进度条 |
/redirect 软刷新页 |
小程序无 vue-router 刷新语义 |
用户偏好 userPreference / 域名品牌 frontBrand / 多语言 |
已由 new3 移植清单 §6 排除,本期继续不做 |
8. 附:一条已经踩过的坑(供设计时参考)
platform 请求头不是"统计标记",而是权限过滤维度。
- 网关卡对
platform做白名单校验:实测放行web/app/wx/miniProgram(且大小写不敏感:miniProgram/MiniProgram/MINIPROGRAM/miniprogram全部 200), 其余(含 uni-app 的平台名mp-weixin)直接返回 HTTP 400 + 空响应体, 前端只能显示通用「请求参数错误」,极难定位。 - 本次已排查并修复(详见《微信小程序开发清单》第 5 节"后端 /system 网关契约")。
- 设计启示:平台编码必须与权限模型的
type维度一致,建议把映射关系固化在后端文档里, 前端只通过.env的VITE_APP_PLATFORM配置(本项目当前值miniProgram)。