wms_mp_weixin/页面渲染框架-设计与任务清单.md
2026-09-22 18:10:35 +08:00

45 KiB
Raw Permalink Blame History

小程序页面渲染框架 · 设计与下一步任务清单

项目: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)

  1. 后端的权限体系已经完全支持多端:wms_permission.type 枚举里已经预留 miniprogram_pages(小程序页面),小程序不需要新建任何表。
  2. 但该类型目前是 0 条数据 —— 这是"等待后端补充设计"的核心内容,需要后端补页面数据 + 给角色授权。
  3. user.info 返回的两块数据就是渲染框架的全部输入:
    • data.menus → 菜单树(Web 端样本对应 type='web_pages')
    • data.permissions → 权限点字符串数组(= type='api' 的 path,已逐条验证)
  4. 小程序端不能照搬 new3 的动态路由(router.addRoute):小程序所有页面必须编译期注册在 pages.json。 正确做法 = 本地静态路由表 + 后端菜单只做筛选/排序/可见性(即 cankao 的思路)。
  5. 登录策略遵循微信审核要求:未登录也能浏览,登录由用户从「我的」主动触发(现已实现)。 页面按 public / optional / required 三态渲染,未登录时页内提示而非强制跳转。
  6. 决策点已全部确认(详见 §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)

  1. 所有页面必须编译期注册在 pages.json,app.json 里没有的页面运行时不复存在 → addRoute 无对应能力。
  2. 没有全局路由守卫:uni.addInterceptor 只能拦 JS 跳转 API,拦不住 tabBar 点击与启动页。 (且上一轮已按审核要求移除全局强制登录拦截。)
  3. 没有 keep-alive / 页签:用原生页面栈 + tabBar 替代。
  4. 没有 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 / guest slot / 内置引导)与 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.vue onLaunch;切换身份 → 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-19
  • userStore 新增 changeRole(action):换发 token → 重设 user → 重调 getInfo() → 重建权限 ✅ 2026-09-19
  • userStore 新增「当前身份」状态(employees[] + currentEmployeeId + setEmployees() 默认身份选择)✅ 2026-09-19
  • userStore 新增 setCurrentEmployee() 切换方法(配合 changeRole 调用)✅ 2026-09-19
  • permissionStore.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 + 「去登录」),不自动跳转
  • pages/mine/mine.vue:已登录时展示「功能菜单」(来自 entries) ✅ 2026-09-19:与首页同源(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. 给后端的补充需求清单

这些是"等待后端补充设计接入功能"的具体内容。

必需

  1. 补充 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'
  2. 给角色授权:在 wms_role.permissions 中加入上述 wms_permission.id
  3. 确认并固化 platform 头 → type 的映射: platform: web → web_pages;platform: miniProgram → miniprogram_pages。 本项目已固定 platform: miniProgram / project: all(网关卡实测大小写不敏感)。
  4. 明确 user.info 在小程序端返回 menus 的来源(按 platform 过滤 type)
  5. 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)

建议(可选,能省掉前端硬编码)

  1. wms_permission 增加 guest_visible(tinyint) 字段 → 由运营侧控制"未登录可见"的页面, 前端即可去掉 LOCAL_PUBLIC_ENTRIES 硬编码(对应 §4 决策点 1 的平滑升级路径)
  2. user.info 的 data 增加 authMode 或直接返回 guestVisible,让页面三态由后端驱动
  3. 后续如需按端裁剪 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)。