wms_mp_weixin/我的页面-分类入口改造-分析与任务清单.md
2026-09-30 18:14:16 +08:00

44 KiB
Raw Permalink Blame History

「我的」页 · 页面分类入口改造 —— 分析与下一步任务清单

状态:决策已定(D1-A / D2-A / D3-A / D4-B / D5-A)+ 前端已落地实现并过程序校验; 数据库已同步(§3.2,2026-09-25 执行);待端上走查 日期:2026-09-25(分析 + 同日实现 + 数据同步) 范围:d:\xiao\wechat(uni-app 微信小程序) 数据源:数据库 wms(wms-kaifa)· 表 wms_permission / wms_role / wms_employee_role 参考:D:\project\new3(web 端顶部导航)、D:\project\new3\workflows\api-doc-system\apidata\data.json(web 端 user.info 真实响应)


0. 结论速览(TL;DR)

  1. 页面信息只有一个来源:user.info → data.menus[](后端按 wms_permission.type='miniprogram_pages' ∩ 当前角色权限过滤后下发的树)。 项目里没有独立的「页面 / page」接口,src/api/ 下只有 user/user.ts。
  2. 你新增的 630(分类,根)/ 631(页面,子) 结构天然匹配「分类标题 + 页面入口」的目标形态 —— entries.ts 会把「有子节点的根」当分组、把「无子节点的节点」当页面叶子。
  3. 但现在还显示不出来,卡在 4 个硬阻塞:
    # 阻塞 影响
    ① path 命名约定不一致:628 是 /test/index,630/631 是 wechat_external_stocks / wechat_external_stock_pages 前端 key 必须与 DB path 逐字符相等,约定不先定就写不了 PAGE_REGISTRY
    ② 631 对应的物理页面文件不存在,pages.json 也未注册 先登记 PAGE_REGISTRY 会立刻违反 npm run check:pages 规则①,用户点进去必失败
    ③ 角色未授权:货主管理员(role 5)权限列表不含 628/630/631 用该身份登录 → menus 为空 → 「我的」页入口区空白
    ④ 「我的」页目前既不拉 user.info、也不渲染任何入口 冷启动直接进「我的」页时 store 为空,无内容可渲染
  4. 执行顺序:定 path 约定 → 建页面文件 + pages.json → 登记 PAGE_REGISTRY → 抽公共 composable/组件 → 改「我的」页 UI → 验证。 前端 + 数据库均已于 2026-09-25 完成(见 §3.1 / §3.2),剩端上走查(§4 的 T17–T21)。

1. 现状盘点(实测,非推测)

1.1 前端渲染链路

flowchart LR
  A["App.onLaunch<br/>有 token 则拉一次"] --> B["userStore.getInfo()"]
  B --> C["apiGetInfo()<br/>POST /system?method=user.info"]
  C --> D["data.menus[]<br/>后端页面树"]
  D --> E["userStore.fetchInfo()<br/>→ permissionStore.loadFromMenus(menus)"]
  E --> F["generateEntries(menus)<br/>menus × PAGE_REGISTRY 求交集"]
  G["PAGE_REGISTRY<br/>逻辑路径→物理页面"] --> F
  F --> H["permissionStore.entries<br/>EntryGroup / EntryLeaf"]
  H --> I["toSections()<br/>拍平成一层分组"]
  I --> J["首页九宫格 / 我的页入口区"]
文件 职责 关键约束(务必遵守)
src/router/pages.ts PAGE_REGISTRY 静态路由表(key / path / title / icon / auth / tabBar / hidden) ① key 必须与后端 wms_permission.path(type='miniprogram_pages')逐字符一致
② path 必须与 pages.json 一致
③ 只登记真实存在的页面
src/router/entries.ts generateEntries(menus):菜单树 × 注册表 → 可见入口树;toSections() 拍平成「一层分组」;LOCAL_PUBLIC_ENTRIES 未登录兜底 collectLeaves() 用 node.path 原样查表(不做父路径拼接);未命中 → 记入 missing 并忽略;hidden 过滤;分组子项全未命中 → 整组丢弃;连续顶层叶子合并成 title: '' 的无标题段
src/store/modules/permission.ts menus / entries / missing / loaded;loadFromMenus() / reset() 由 userStore 在 user.info 成功后调用;resetToken() / 401 → reset()
src/store/modules/user.ts getInfo(force) 带并发复用+缓存;fetchInfo() 写 state 未绑定微信态(is_bound=false)直接 return,不灌菜单;hasUserInfo = infoLoaded
src/pages/index/index.vue 首页:卡「常用功能」+ toSections(entries) 渲染「段标题 + 3 列九宫格」;onShow 在 store 无数据时补拉;空态区分未登录 / 未绑定 / 失败 与「我的」页共用 toSections 口径
src/pages/mine/mine.vue 「我的」页:仅头部 profile + 一张卡(用户信息 / 清除本地缓存)+ auth-modal ❗没有入口渲染、没有 loadEntries;onShow 只同步 token
src/pagesA/test/index.vue 测试页:排障面板(逻辑/物理路径、后端数据源、menus 根节点数、missing) 改完直接用它核对后端是否下发了新节点
src/pages.json pages 5 个;subPackages 只有 pagesA(demo/public、demo/required、test/index) pagesB / pagesC 目前只有 .gitkeep
scripts/check-pages.mjs npm run check:pages:①path 必须存在于 pages.json ②key 不重复 ③pages.json 有但注册表没有 → 告警 ④需登录页是否挂 <auth-modal/> → 告警 从 pages.ts 用正则提取,条目须保持「单引号字面量对象」写法

1.2 数据库现状

wms_permission 列:id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, sort, status, type, created_at, update_at

type 分布(status=1):

type 条数 根节点数 sort 范围
api 261 171 0
web_pages 89 16 0–401
pda_pages 46 8 0
block 12 12 0
workerstation_pages 3 3 1–3
miniprogram_pages 3 2 0

miniprogram_pages 全量 3 条:

id path name parent_id sort meta_title meta_icon component 判定
628 /test/index /test/index NULL 0 测试页 grid NULL ✅ 根叶子 → 前端表现为无标题段里的一个页面
630 wechat_external_stocks WechatExteralStock NULL 0 小程序外仓商品 NULL NULL ⚠️ 有子节点 → 会被当分组(分类),其 path 不参与注册表匹配
631 wechat_external_stock_pages WechatExternalStockPages 630 0 小程序外仓商品页面 NULL NULL ⚠️ 叶子 → 其 path 就是前端 key

📌 上表是**分析时(改动前)**的快照;2026-09-25 已按 §3.2 规范化 path / meta_title / sort,当前值见 §3.2。

⚠️ 代码注释 / 测试页 UI 里写的「后端数据源 wms_permission id=627」是错的: 627 是 api 权限(order.wave.confirmPrintScan),测试页真正的数据源是 id=628。

web_pages 的既有约定(对照用,来自 data.json + DB 实测):

角色 约定 实例
根(分组) 绝对路径 + component='Layout' + sort 1..14 /stock(商品)、/storage(库存)
子(页面) 相对路径(不含前导 /)+ component='@/views/...' + sort 0..n external_stock(外仓商品,sort=3,parent_id=13)

关键实测结论:后端 menus 是原样下发 DB 里的 path(data.json 里 /stock 的子节点 path 就是 external_stock,没有拼成 /stock/external_stock)。web 端能跳转是因为 new3 的 router/resolveComponent 里做了「父路径 + 相对路径」拼接;小程序端 entries.ts 没有这个拼接。

→ 所以 630/631 现在的写法(根 wechat_external_stocks 无前导斜杠、子 wechat_external_stock_pages 像相对路径)同时偏离了两种约定,必须先定死再往下走(见 §3 D1)。

角色授权现状(wms_role.permissions = '*' 或 id JSON 数组):

角色 id permissions 含 628/630/631? 关联身份(wms_employee_role)
货主管理员 5 30 个 id([13,18,48,...]) ❌ 都不含 employee 33(测试货主1111)← data.json 里 token 的 current_role_id=33
仓库管理员 2 '*'(全量) ✅ 自动包含 employee 34(天豹云仓)
超级管理员 7 '*'(全量) ✅ 自动包含 employee 31(测试仓)

1.3 参考基线:new3 顶部导航

D:\project\new3\src\layout\component\TopMenu.vue 的关键实现与小程序端同源思想:

  • 数据来自 permissionStore.routes(由后端菜单生成),只过滤 hidden;
  • 「分类」= 一级菜单,「页面」= 其下的子项/下拉项;
  • 差异点:web 是运行时动态注册路由,小程序必须编译期注册在 pages.json + 前端持有「逻辑路径 → 物理页面」映射(即 PAGE_REGISTRY)。

2. 关键发现与风险

编号 发现 影响 建议
F1 PAGE_REGISTRY.key 必须与 DB path 逐字符相等,但 628(/test/index)与 630/631(wechat_xxx)风格不一致 命名混乱会使后续维护者误以为两者语义不同;也影响是否要做父路径拼接 D1 先定约定,再统一
F2 entries.ts 不做父路径拼接,而 web 子节点是相对路径 若沿用 web 相对风格,小程序端必须改 entries.ts 加拼接逻辑(改公共代码,影响首页) 建议 DB 一律写前端可直接用的 key
F3 630 有子节点 → 被识别为分组,其 path 不参与 PAGE_REGISTRY 匹配 ✅ 好消息:分类节点不需要页面文件、不必登记注册表 分类节点随便不随便其实不影响跳转,但建议仍用规范 path(见 D1)
F4 628 是根叶子 → toSections() 给它生成 title: '' 的无标题段 「我的」页目标形态是「分类标题 + 页面」,无标题段与之不符(首页现在就是「常用功能」卡下直接一个「测试页」格子) D2:无分组叶子兜一个默认分类名(如「其他」),或让后端给 628 补一个分类父节点
F5 630 / 631 / 628 sort 全是 0 同 sort 时顺序由后端(多半 sort, id)决定,不可控、加页面后顺序易乱 分类用 1..n,子页面用 0..n(对齐 web 约定)
F6 630/631 meta_icon 为 NULL;630 是分组、分组标题在首页本来就不显示图标 影响小:叶子图标回退 'grid' 需要区分视觉就补 meta_icon(值取自 uview-plus 图标名,如 bag / list)
F7 630 的 name 拼写错误:WechatExteralStock(少一个 n) name 仅在 path 为空时作分组 key 兜底 → 低风险 顺手修正;name 建议保持 PascalCase 无拼写错
F8 631 的 meta_title「小程序外仓商品页面」是占位式描述,会直接显示为格子文字 用户看到的是「小程序外仓商品页面」而不是「外仓商品」 改成真实业务名,如「外仓商品」;前缀「小程序」也不必带(本端就是小程序)
F9 631 对应物理页面不存在(pagesA 下无 external-stock 目录) 登记 PAGE_REGISTRY → check:pages 报错;强行上线 → 点击跳转失败(只在真机暴露) 顺序:建页面 → pages.json 注册 → 再登记注册表
F10 授权缺口:role 5(货主管理员)不含 628/630/631 用该身份登录 → menus 空 → 「我的」页入口区空白,容易被误判为「前端 bug」 明确测试身份,或给业务角色补授权(permissions 是 id 数组,需追加 630/631)
F11 「我的」页 onShow 只同步 token,不拉 user.info 冷启动直接切到「我的」→ store 空 → 无分类可渲染 抽公共 composable,与首页共用 loadEntries(force)
F12 首页与「我的」都用 permissionStore.entries → 内容完全相同 没有「常用 / 全部」的区分,「我的」页会变成首页的复制品 D4 决定:接受重复 / 本地加 common 标记 / 后端再加一类
F13 platform 请求头是权限过滤维度(platform: miniProgram → 取 miniprogram_pages),且必须与 token 内 platform_code 一致 头不合法 → HTTP 400 + 空响应体,极难定位 沿用 .env 的 VITE_APP_PLATFORM,不要硬编码
F14 always_show 字段前端完全未使用(vue-element-admin 里它的语义是「只有一个子路由时也显示父级」) 若后端想用它控制「分类只有一个页面时是否显示分类标题」,当前无效 明确是否需要,需要则加前端支持;不需要就别配
F15 分组 component 为 NULL(web 的分组是 'Layout') 未知后端序列化是否对分组 component 有要求(628 是根叶子且 component=NULL 能下发,说明 NULL 本身不致命) 列入 §6 向后端确认;若要求,630 补 component='Layout'

3. 目标形态与已决策

目标形态(你描述的「常用功能」-「测试页」结构)

┌ 我的 ────────────────────────────┐
│ [头像] 昵称 / 身份·组织        >  │   ← 现状 profile 卡,不变
├──────────────────────────────────┤
│ 用户信息                  已登录  │   ← 现状卡,不变
│ 清除本地缓存                   >  │
├──────────────────────────────────┤
│ 全部功能                          │   ← 卡片标题(可自定义)
│                                  │
│   外仓商品                        │   ← 分类标题 = 分组 meta_title
│   ┌────┐ ┌────┐                  │
│   │ 📦 │ │ 📋 │   ...            │   ← 页面入口九宫格 = 叶子
│   │外仓│ │ ...│                  │
│   └────┘ └────┘                  │
│                                  │
│   测试页 / 其他                    │   ← D2:无分组叶子的兜底段
│   ┌────┐                         │
│   │ ⬚  │                         │
│   │测试│                         │
│   └────┘                         │
└──────────────────────────────────┘

已决策记录(2026-09-25 定稿,按推荐方案执行)

编号 决策点 选项 ✅ 结论
D1 path 约定 A 统一绝对且等于前端 key:630 → /external-stock,631 → /external-stock/list;
B 沿用 web「根绝对 + 子相对」:631 → external_stock,前端 entries.ts 增加父路径拼接
A:entries.ts / pages.ts 都不用动,只改 DB 两个字段值(B 需改公共代码并回归首页)
D2 无分组叶子的兜底分类 A 前端兜底:toSections() 按分类分段 + 未分类段;
B 后端补一个分类父节点把 628 收进去
A:已实现(仅当结果里确实有分组时才给散落叶子加标题「其他」,全是散落叶子时仍无标题,首页不会凭空多一段)
D3 「我的」页渲染形态 A 一张「功能」卡内多段(段标题 + 九宫格);
B 每个分类一张独立卡
A:「全部功能」卡内多段,与首页共用 toSections() + entry-sections 组件
D4 首页 vs 我的 的关系 A 两页相同;
B 「我的」= 全部,「首页」= 常用 → 本地 common?: boolean;
C 后端新增 type='miniprogram_common'
B:PageMeta.common(默认 true = 常用);首页 onlyCommon: true,「我的」不过滤。当前把「测试页」设为 common: false(排障页不占首页格子)
D5 「我的」页未登录时的入口区 A 整块隐藏,只留头部登录引导;
B 显示本地公共入口 + 去登录按钮
A:fallbackToLocalPublic: false + v-if="isLogin";已确保任何状态都不会自动跳登录页

3.1 已落地改动(2026-09-25,第一版)

⚠️ 本节的首页入口结构已在同日下午按 §3.3 二次调整(「常用功能」改为本地列表、 撤掉「我的」页的页面列表);下表保留供对照,当前实现以 §3.3 为准。

结论:前端已可按「分类标题 + 页面入口」渲染;数据侧只要按 §3.2 改两条 path 并授权,入口就会出现在「我的」页与首页。

文件 改动
src/router/pages.ts 新增 PageMeta.common(是否进首页「常用功能」,默认 true);登记新页面 key: '/external-stock/list' → path: 'pagesA/external-stock/list'(auth: 'required');「测试页」标 common: false;修正注释里的错误 id 627 → 628
src/router/entries.ts EntryLeaf 增加 common;新增 ToSectionsOptions(onlyCommon / looseTitle);toSections() 支持「常用过滤 + 兜底分类名 + 过滤后空分组丢弃」
src/composables/useEntrySections.ts 新增:入口区取数与状态收口(sections / loading / loadEntries(force) / onEntry / 空态文案 / notCommonOnly)
src/components/entry-sections/entry-sections.vue 新增:段标题 + 3 列九宫格展示组件(纯展示,点击上抛 select)
src/pages/index/index.vue 改用上述 composable + 组件(UI 不变),新增一种空态:有入口但都不是常用 → 「常看全部」引导去「我的」
src/pages/mine/mine.vue 新增「全部功能」卡(v-if="isLogin"):分类标题 + 页面九宫格 + 加载态 + 4 种空态;onShow 补拉
src/pagesA/external-stock/list.vue 新增:外仓商品页面占位(auth-gate auth="required" + <auth-modal/>)
src/pages.json subPackages[pagesA] 注册 external-stock/list;condition.list 加调试入口
src/store/modules/permission.ts 更新陈旧注释(后端已不是 0 条)

校验结果:npm run check:pages → 9 条注册表 / 9 个已注册页面 / 0 告警;npm run type-check → 通过。

两个需要注意的行为变化:

  1. 「测试页」common: false → 不再出现在首页「常用功能」,改到「我的」页;想改回去只需删掉 pages.ts 里那一行(一行回退)。
  2. 若某账号的入口全是非 common,首页会显示「常用功能暂未配置,可到「我的」页查看全部功能」(而不是伪装成「服务器出差」)。

3.2 数据库变更(✅ 已于 2026-09-25 执行)

联调实测(测试页面板截图):后端 menus 是「原样下发」DB 的 path —— 面板里就是 wechat_external_stocks / wechat_external_stock_pages(未拼父路径),与前端注册表 /external-stock/list 不一致 ⇒ 表现恰好是「可见入口数 1 / 未登记 key 1 个」(那个 1 = 测试页命中, 外仓商品子节点进 missing)。§6 问题 1 至此实测确认。

已执行(库 wms,表 wms_permission,type='miniprogram_pages'):

id 字段 改前 改后
630 path wechat_external_stocks /external-stock
630 name WechatExteralStock(拼写错) ExternalStock
630 meta_title 小程序外仓商品 外仓商品(= 首页的分类标题)
630 meta_icon / sort NULL / 0 bag / 1
631 path wechat_external_stock_pages /external-stock/list(= PAGE_REGISTRY.key)
631 name WechatExternalStockPages ExternalStockList
631 meta_title 小程序外仓商品页面 外仓商品(= 九宫格格子文字)
631 meta_icon / sort NULL / 0 bag / 0
628 sort 0 9(避免与分类同 sort,否则顺序不可控)

当前状态(复查 SQL 结果):

id path parent_id sort meta_title
631 /external-stock/list 630 0 外仓商品
630 /external-stock — 1 外仓商品
628 /test/index — 9 测试页

→ 首页将渲染:分类标题「外仓商品」+ 格子「外仓商品」(common 默认 = 常用); 「我的」页渲染:「外仓商品」段 + 「其他」段(测试页,common: false)。

回退 SQL(如需恢复原样):

UPDATE wms_permission SET path='wechat_external_stocks', name='WechatExteralStock',
       meta_title='小程序外仓商品', meta_icon=NULL, sort=0 WHERE id=630;
UPDATE wms_permission SET path='wechat_external_stock_pages', name='WechatExternalStockPages',
       meta_title='小程序外仓商品页面', meta_icon=NULL, sort=0 WHERE id=631;
UPDATE wms_permission SET sort=0 WHERE id=628;

仍未做:

  1. component 保持 NULL(web 分组用 'Layout',小程序是否要求非空待 §6 答复;628 为 NULL 也能下发,说明不致命)。
  2. 角色授权——给「货主管理员」(role 5)追加 630/631:
UPDATE wms_role
SET permissions = JSON_ARRAY_APPEND(permissions, '$', 630, 631)
WHERE id = 5 AND permissions <> '*' AND permissions NOT LIKE '%630%';

更推荐直接在后端管理后台的角色权限树里勾选(走业务校验、可审计);上面的 SQL 只适合开发库快速验证。 permissions 是 JSON 字符串,手改务必保证 JSON_VALID(permissions) 为 1。 已确认:当前实测身份(仓库管理员 / 273 权限点 / role *)无需授权即可看到新页面。

生效方式:user.info 结果缓存在内存(userStore.infoLoaded)⇒ 改完 DB 需重新编译小程序 (冷启动 App.onLaunch 会重新拉 user.info)或退出重进;若仍不生效,排查后端是否有菜单级缓存。

3.3 二次调整(2026-09-25):入口结构改为「本地常用 + 后端分类段」

需求:「常用功能」不再作为分类 / 不再由后端 common 过滤得岀,而是一个本地维护的页面列表 (目前放「测试页」「公开页」),与后端「外仓商品」分类及其页面入口形态一致、并列展示; 并移除「我的」页的页面列表。

首页最终结构

┌ 首页 ────────────────┐
│ [hero] 昵称·身份        │
├───────────────────────┤
│  常用功能              │ ← 本地列表(common: true)
│  ┌────┐ ┌────┐        │
│  │测试页│ │公开示例│    │
│  └────┘ └────┘        │
│                        │
│  外仓商品              │ ← 后端分类(menus 里的分组节点)
│  ┌────┐               │
│  │外仓商品│            │
│  └────┘               │
└───────────────────────┘
  • 两段形态完全一致(标题 + 3 列九宫格),只是数据来源不同:
    • 本地段 = LOCAL_COMMON_ENTRIES(PageMeta.common === true 且可见)
    • 后端段 = permissionStore.entries(user.info 的 menus × PAGE_REGISTRY)
  • 去重:本地段已有的 key 从后端段剔除(否则「测试页」会显示两次)
  • 本地段固定在最前:不受登录态 / 授权 / 接口故障影响,开发联调随时能进测试页
  • 未登录时后端段为空 ⇒ 只剩下「常用功能」,其中「公开示例」保证「未登录也能浏览」(微信审核要求)
  • 卡片不再有「常用功能」标题(它现在是段标题,避免两层重复)

涉及改动

文件 改动
src/router/pages.ts common 语义改为显式 opt-in(=== true 才进,不设=不进);「测试页」「公开示例」标 common: true;删掉 common: false 用法
src/router/entries.ts LOCAL_PUBLIC_ENTRIES → LOCAL_COMMON_ENTRIES;新增 toHomeSections()(本地段在前 + 后端段去重)与 COMMON_SECTION_TITLE;EntryLeaf.common 字段与 toSections({ onlyCommon }) 一并移除;toSections 仅保留 looseTitle(兜底「其他」段)
src/composables/useEntrySections.ts 选项收敛为 { looseTitle };sections = toHomeSections(permissionStore.entries);移除 onlyCommon / fallbackToLocalPublic / notCommonOnly
src/pages/index/index.vue 删除卡片标题「常用功能」;移除「查看全部」分支(已无意义)
src/pages/mine/mine.vue 移除「全部功能」卡及其全部引用,恢复为「头部登录入口 + 菜单卡 + 清缓存」
src/pagesA/demo/public.vue 示例文案改指 LOCAL_COMMON_ENTRIES / 「常用功能」段

校验:npm run type-check 通过;npm run check:pages → 9 条注册表 / 9 个已注册页面 / 0 告警。

两条新约定(重要)

  1. 想让某个页面常驻首页 → 在 PAGE_REGISTRY 里标 common: true(不依赖后端配置与授权)。
  2. auth: 'public' 的页面请一并标 common: true —— 否则未登录时首页可能一个入口都没有 (首页未登录时只剩本地「常用功能」段)。

3.4 外仓商品页面实现(2026-09-25)

参考 new3 Web 端 src/views/stock/external_stock/index.vue,同一个接口实现小程序列表页, 交互按移动端重做。

接口(src/api/stock/external-stock.ts)

POST {base}/system?method=stock.warehouse.externalList&v=1.0&timestamp=...
body = { warehouse_id?, pagination: { page, pageSize }, where: { keyword?, store_id? } }
返回 data = { list: [...], pagination: { total }, summary? }   // total 也读顶层兜底
  • 实测(不带 token 探测,401 = 方法存在):stock.warehouse.externalList、index.loadStores、 index.loadWarehouses、index.getImages 均存在。
  • ⚠️ where.store_id(货主过滤)尚未与后端确认:new3 只用了 where.keyword + 顶层 warehouse_id, 没做货主过滤。若联调发现不生效,只改 buildBody() 一处(例如提到顶层与 warehouse_id 并列)。

Web → 小程序的交互取舍

Web 端 小程序端 原因
工具栏 + 高级筛选字段树(ScanBox) 顶部吸顶筛选区:关键词输入 + 搜索按钮 + 货主 / 仓库胶囊 + 重置 移动端没有横向空间摆字段树;胶囊点击唤起底部选择器
底部页码 / 每页条数 / 跳页 / 多列排序 上拉自动加载 + 底部一行状态(加载中 / 没有更多了 / 加载失败点击重试),顶部「共 N 件商品 · 已加载 M」 手机上点页码不现实;多列排序 UI 在移动端不可用 → 直接去掉
表格 20+ 列 卡片:只展示 商品图片 / 商品名称 / 可用库存 按需求裁剪;名称两行截断、图片 160rpx 方形
刷新按钮 下拉刷新(enablePullDownRefresh) 移动端原生习惯
上下分栏详情面板 暂未做(点卡片无跳转) 后续可加二级详情页

其它实现要点

  • 新增 src/utils/gateway.ts(SYSTEM_URL + gatewayParams);api/user/user.ts 改为复用它(去掉重复实现)
  • 新增 src/api/index/index.ts:fetchStoreOptions() / fetchWarehouseOptions(), 返回结构做了容错归一化(list/data/直接数组;store_id/warehouse_id/id;*_name/name/company_name)
  • 可用库存:优先 available_quantity,缺失用 quantity - locked_quantity 兜底, 都没有时显示 —(不回退成 0,否则会被误读成「没库存」)
  • pages.json 本页新增 enablePullDownRefresh / backgroundTextStyle / onReachBottomDistance: 80
  • 校验:npm run type-check 通过;check:pages 9/9、0 告警;产物 list.js/json/wxml/wxss 已生成, 引用完整性 110 个引用 / 0 缺失

2026-09-28 调整(筛选条件与卡片字段):

  • 筛选区改为 仓库 / SN管理 / 批次管理(移除货主筛选)
  • 胶囊未选中时显示筛选项名(仓库 / SN管理 / 批次管理),选中后显示具体值(仓库名 / 是 / 否); 选「全部…」时回到筛选项名;筛选项多了,筛选行改为允许换行(flex-wrap)
  • SN管理 / 批次管理 取值 'Y'/'N',走 where 的裸值 (与 new3 handleConditionChange 一致:它会把 ScanBox 的 {operator,value} 剥成裸值再传)
  • 卡片新增商品编码行(item_code)

3.5 收货单页面实现(2026-09-26)

后端新增小程序页面权限:632 /external-inventory「外仓库存」(分类)、 633 /external-inventory/receiving「收货单」(632 的子)。

接口(src/api/storage/receiving.ts)

POST {base}/system?method=storage.receiving.getStoreReceivingList&v=1.0&timestamp=...
body = { pagination: { page, pageSize }, where: { <字段>: { operator, value } } }
返回 data = { list: [...], pagination: { total } }
  • 实测:方法存在(不带 token → 401)。
  • ⚠️ where 的形状与「外仓商品」不同:这里是 { operator, value } (new3 ScanBox 契约,见其 applyWarehouseToWhere() / normalizeToWhere()), 不是 where.keyword = 'xxx' 那种裸值 —— 两套別混。
  • 收货单号模糊搜索用 receiving_number: { operator: 'like', value }(new3 字段配置声明支持 like / contains / starts_with;若后端只支持其中一个,改 buildBody() 一行)。

页面(pagesA/external-inventory/receiving.vue)

顶部吸顶筛选(收货单号 + 搜索 + 货主 / 收货状态胶囊 + 重置)+ 卡片列表 + 下拉刷新 + 空态。 卡片展示 4 项:收货单号 + 收货状态(按状态着色:收货中/已完成/已作废)/ 商品(N 种 · M 件)/ 车牌号(有才显示)/ 创建时间。

分页器(2026-09-26 调整,对齐 Web 的 el-pagination 功能):

  • 每页固定 50 条,不可改(RECEIVING_PAGE_SIZE;去掉 Web 的每页条数选择器)
  • 显示 总条数 + 当前页码(共 128 条 · 第 2/3 页;加载中显示「加载中…」)
  • 4 个按钮:首页 / 上一页 / 下一页 / 尾页,到边界或加载中自动置灰
  • 分页器 固定在屏幕底部、一行放下(position: fixed + env(safe-area-inset-bottom))—— 50 条一页不必滑到底才能翻页;按钮刻意做小(padding: 8rpx 16rpx / font-size: 22rpx, 与总数页码同行),.page 留 140rpx 底部空白避免盖住最后一张卡; 总数/页码文字可收缩省略,保证四个按钮永远完整可见
  • 翻页与筛选后 uni.pageScrollTo 回顶部
  • 去掉了上拉加载(onReachBottom):本页是整页替换,与「外仓商品」的流式追加不同
  • 下拉刷新 = 重拉当前页;若当前页已越界(总数变少)则自动回第 1 页

顺带:选择器抽成公共组件

新增 src/components/option-picker/option-picker.vue(底部弹层选择器):

  • 页面只负责拼 options(含「全部…」项)与处理 @select;组件负责列表、打勾、取消、空/加载提示
  • 选项超过 12 个自动出名称搜索框(货主 124 个,纯滚动不可用),每次打开清空上次搜索词
  • 「全部…」(value === '')永远置顶且不参与过滤
  • 「外仓商品」页已改用它(删掉页内 60 行弹层代码与样式),「收货单」页直接复用

校验:type-check 通过;check:pages → 10 条注册表 / 10 个已注册页面 / 0 告警; 产物 pagesA/external-inventory/receiving.{js,json,wxml,wxss} + components/option-picker/* 均已生成, 引用完整性 117 个引用 / 0 缺失。

2026-09-28 调整(筛选条件与卡片字段,对齐 new3 receiving_owner):

  • 筛选区改为 收货状态 / 入库状态 / 审核状态 / 仓库(移除货主筛选 —— new3 货主侧页面也已 .filter(f => f.value !== 'store_id');接口层 store_id 能力保留,可从页面接回)
  • 「全部状态」胶囊更名 「收货状态」(未选中显示筛选项名,选中显示具体值;选「全部」回到筛选项名)
  • 新增筛选取值(都走 { operator: 'eq', value }):
    维度 字段 取值
    收货状态 status receiving 收货中 / completed 已完成 / cancelled 已作废
    入库状态 storage_status waiting 待入库 / none 未入库 / partial 部分入库 / all(筛选写「已入库」、列表写「全部入库」,Web 原样)
    审核状态 is_review 数值 1 已审核 / 0 未审核(页面存字符串,buildBody() 里转数字)
    仓库 warehouse_id 接口 index.loadWarehouses(含「全部仓库」项,选中时才拉、拉过缓存)
  • 卡片新增 3 行:入库状态 / 匹配状态(按状态着色)+ 备注(有值才显示)
  • 顺带:胶囊文案改为算出来(labelOf(kind) = 当前值 → 选项表),不再手工维护 storeLabel / statusLabel 这类 ref,重置不会漏;筛选行加 flex-wrap(4 个胶囊 + 重置会换行)
  • 备好未接线:匹配状态筛选项常量 RECEIVING_DETAIL_OPTIONS(本次只要求「显示」,未加筛选)
  • 校验:type-check 通过;check:pages 10/10、0 告警;产物 17:24 已重建(页面 js 含 storage_status / is_review / warehouse_id,wxml 含「入库状态/匹配状态/备注」,无「全部货主」), 引用完整性 125 个 / 0 缺失
  • ⚠️ 待实测:is_review 不在 new3 货主侧列定义里,筛选是否生效需在工具里点一次确认

3.6 库存报表页面实现(2026-09-30)

后端新增小程序页面权限:637 /external-inventory/report「库存报表」 (632「外仓库存」的子,sort 1 排在「收货单」之后,meta_icon='file-text')。

⚠️ id 不是顺序分配:634/635/636 已被 pda「移库记录」/ web「库存盘点」/ api 权限占用 —— 新增 miniprogram_pages 前先查空闲 id(本次按 634 直接 INSERT 撞过主键)。

接口(src/api/stock/report.ts)

POST {base}/system?method=stock.report.searchStore&v=1.0&timestamp=...
body = { where?: {...}, sort?: {...}, pagination: { page, pageSize } }
返回 data = { list: [...], pagination: { page, pageSize, total } }
  • 与 new3 views/storage/report/store.vue(货主侧)同源;仓库侧是同模块的 stock.report.search(按 store_ids 过滤)—— 别拿错(「收货单」也是走货主侧 getStoreReceivingList)
  • ⚠️ 第三套 where 形状:扁平值(前两套分别是「外仓商品」的裸值、「收货单」的 {operator,value}): where.keyword / where.warehouse_ids = [id](数组,不是 warehouse_id)/ where.start_time / where.end_time;无有效条件时连 where 都不传(new3 同款写法)
  • 货主侧不收 store_ids、不提供 by_space

页面(pagesA/external-inventory/report.vue)

  • 筛选:商品关键字 + 仓库 + 统计区间(→ keyword / warehouse_ids / start_time+end_time)
  • 统计区间用预设(全部 / 今天 / 近 7 天 / 近 30 天 / 本月)代替 Web 的日期范围选择器 —— 移动端拉日历挑区间体验差;默认「全部」= 不传时间条件、跟随后端默认口径; 天数含今天(近 7 天 = 往前推 6 天),格式 YYYY-MM-DD HH:mm:ss(start 00:00:00 / end 23:59:59)
  • 卡片字段(new3 fixedReportColumns 去掉货主侧隐藏的 store_id/store_name): 商品名称 + 仓库 / 编码 · 条码 · SKU / 2×2 四个数量(期初 / 区间内入库 / 区间内出库 / 期末)/ 统计区间(只到日期);数量带千分位(手写分组,不用 toLocaleString:小程序 JSCore 的 locale 支持不稳)
  • 分页:REPORT_PAGE_SIZE = 50 固定,复用公共 page-pager(unit="条明细"),整页替换
  • 未做(Web 能力,移动端刻意不做):SKU 多选、按库位统计、列排序、导出
  • 校验:type-check 通过;check:pages → 11 条注册表 / 11 个已注册页面 / 0 告警; 产物已重建(页面 js/wxml/json/wxss + api/stock/report.js,含 stock.report.searchStore / warehouse_ids;wxml 含四个数量与统计区间标签),引用完整性 131 个 / 0 缺失
  • ✅ 接口存在性已取证:未带 token 请求 stock.report.searchStore → HTTP 401 (对照组:伪造方法名 stock.report.searchStoreXyz → 500)。 待你在工具里确认的是「带 token 能正常返回数据」以及页面字段是否都下发

4. 下一步任务清单

执行状态(2026-09-25):代码类任务 T7–T16 已完成(check:pages / type-check 均通过); T4(path / title / sort 规范化)已执行(§3.2);T5 已确定走前端兜底(D2-A,无需 DB); T6 授权仅对非 * 角色待办(当前实测身份无需)。 T17–T21 是端上 / 真机走查,需你在开发者工具里确认。

阶段 0 · 决策与对齐(无代码产出)

# 任务 产出 验收标准
T1 定 D1:写下 630/631 的最终 path 值与前端 key 对照表 一张「DB path ↔ PAGE_REGISTRY.key」对照表(写进本文件或设计文档) 表里每一行 path 与 key 逐字符相等;631 的值与 630 语义一致(分类/页面能看出来)
T2 定 D2/D3/D4/D5 四项 决策记录(各 1–2 行) 每项有明确选项 + 理由;D3 若选 B 需附上 DOM 结构草稿
T3 与后端确认 §6 的 4 个问题 后端答复 至少确认「menus 是否原样下发 path」与「分组 component=NULL 是否正常」
T4 (DB,你执行)规范 630/631 字段:path(按 T1)、sort(分类 1..n / 子页面 0..n)、meta_title(631 改成业务名)、meta_icon(可选)、修 name 拼写 更新后的两行 SELECT 复查:无 NULL title、sort 不重复、name 无拼写错
T5 (DB,可选)按 D2-B 给 628 补分类父节点,或确认走前端兜底 决策/新行 「我的」页不再出现无标题段
T6 确认测试身份并补授权:给业务角色(如货主管理员 role 5)追加 630/631(permissions 是 id 数组) 更新后的角色 用该身份登录后,测试页面板 menus 根节点数 > 0

阶段 1 · 页面文件与路由登记

# 任务 产出 验收标准
T7 新建物理页面(建议分包 pagesA):src/pagesA/external-stock/list.vue 页面文件 页面挂 <auth-gate auth="required"> + <auth-modal/>;先用占位卡(标题/逻辑路径/物理路径),业务接口后续接
T8 在 src/pages.json 的 subPackages[pagesA].pages 注册该页面;并在 condition.list 加一条调试入口 pages.json 改动 开发者工具「编译模式」里能直接选中该页并正常打开
T9 在 src/router/pages.ts 的 PAGE_REGISTRY 登记条目 注册表条目 key = T1 对照表的 key(逐字符相等);path = pagesA/external-stock/list(与 pages.json 一致);auth: 'required';不设 hidden、不设 tabBar
T10 跑静态校验 命令输出 npm run check:pages:0 错误、0「未登记」告警;npm run type-check:0 错误

阶段 2 · 「我的」页改造

# 任务 产出 验收标准
T11 抽公共 composable useEntrySections():封装 sections(toSections(entries))、loading、loadEntries(force)(含 hasUserInfo 短路、未绑定短路、失败不抛)、空态 props 新文件 src/composables/useEntrySections.ts 首页改用该 composable 后行为不变(回归首页:未登录 / 已登录 / 未绑定 / 接口失败 4 态)
T12 抽公共展示组件 entry-sections(段标题 + 3 列九宫格 + 点击跳转,含 auth: 'required' 未登录时的页内引导) 新组件文件 首页改用它后 UI 与改造前像素级一致;跳转统一走 navigateToPath(tabBar → switchTab)
T13 「我的」页接入入口区(按 D3 形态):onShow 调 loadEntries();登录 → 渲染分类+入口;未登录 → 按 D5 处理;未绑定 → 「去绑定」引导;失败 → 空态 + 重试 src/pages/mine/mine.vue 改动 冷启动直接进「我的」页时,分类与入口能自动出现(无需先逛首页);4 种状态各有正确文案,任何状态都不会自动跳登录页
T14 实现 D2 的兜底分段逻辑(若选 A) src/router/entries.ts 改动(仅 toSections 段) 无分组叶子被归入默认段(如「其他」);toSections 的纯函数性质不变(无网络/无 store 依赖)
T15 实现 D4(若选 B):PageMeta 加 common?: boolean,首页只渲染 common 的段内叶子,空段丢弃 pages.ts / entries.ts 改动 首页与「我的」内容按预期不同;「我的」展示全部
T16 清理文档/代码里的错误引用 改动 pagesA/test/index.vue 与 pages.ts 注释里的「wms_permission id=627」改为 628

阶段 3 · 验证

# 任务 验收标准
T17 静态校验:npm run check:pages + npm run type-check 均 0 错误
T18 小程序端走查(开发者工具 + 真机各一遍) 用 '*' 角色(employee 31/34)登录:测试页面板 menus 含 630/631、missing 为空;「我的」页出现「外仓商品」分类及页面入口;点击能正确跳转
T19 用货主管理员(role 5)身份走查 若已授权 → 应看到入口;若未授权 → 「我的」页显示空态而非白屏(验证 F10 的兜底表现符合预期)
T20 异常态走查:未登录 / 微信未绑定 / 断网失败 3 种情况各有文案与操作按钮,无白屏、无自动跳登录
T21 hidden / always_show 行为确认 把 631 临时设 hidden=1 → 不应出现在「我的」页;恢复后重新出现(这是 DB 侧临时验证,需你确认是否允许)

5. 验证与排查速查

命令(d:\xiao\wechat):

npm run check:pages   # 注册表 × pages.json 一致性
npm run type-check    # vue-tsc

⚠️ 跑 dev:mp-weixin 前先确认没有另一个编译进程在跑(两个进程写同一 dist 会写坏产物,报 common/assets.js 缺失)。

SQL(复查数据,只读):

-- 小程序页面节点(分类 + 页面)
SELECT id, path, name, parent_id, sort, meta_title, meta_icon, hidden, always_show, component, status
FROM wms_permission WHERE type = 'miniprogram_pages' ORDER BY sort, id;

-- 哪些角色能看到这些节点('*' 表示全量)
SELECT r.id, r.role_name, r.permissions = '*' AS is_all, CHAR_LENGTH(r.permissions) AS perms_len
FROM wms_role r WHERE r.status = 1;

端内排查面板:进 pagesA/test/index(逻辑路径 /test/index),可看到

  • 后端菜单(根节点 N 个) → N=0 说明未授权或 platform 头不对
  • 入口解析结果 / 未登记 key → 非空说明 DB 里的 path 与 PAGE_REGISTRY.key 不一致(这是列 F1 最快的自检手段)

6. 待向后端 / 产品确认

  1. menus 是否原样下发 DB 的 path → ✅ 已实测确认:原样下发(2026-09-25 测试页面板显示 wechat_external_stocks / wechat_external_stock_pages,未拼父路径)。D1-A 的实现方式正确。
  2. 分组节点(parent_id IS NULL 且有子节点)的 component 是否必须非空?web 用 'Layout',小程序新增的 630 是 NULL,是否会被序列化过滤掉?
  3. miniprogram_pages 是否也需要像 web 一样给分组节点填 component,还是后端对 type='miniprogram_pages' 走独立逻辑?
  4. 授权的推荐做法:新页面是逐个给角色勾选 id,还是把常用角色设为 '*'?若角色数多,是否有后台批量授权入口(避免每次加页面都要改 DB)。
  5. 产品侧:「首页常用功能」与「我的全部功能」的划分口径是什么?(决定 D4)