44 KiB
「我的」页 · 页面分类入口改造 —— 分析与下一步任务清单
状态:决策已定(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)
- 页面信息只有一个来源:
user.info→data.menus[](后端按wms_permission.type='miniprogram_pages'∩ 当前角色权限过滤后下发的树)。 项目里没有独立的「页面 / page」接口,src/api/下只有user/user.ts。 - 你新增的 630(分类,根)/ 631(页面,子) 结构天然匹配「分类标题 + 页面入口」的目标形态 ——
entries.ts会把「有子节点的根」当分组、把「无子节点的节点」当页面叶子。 - 但现在还显示不出来,卡在 4 个硬阻塞:
# 阻塞 影响 ① path 命名约定不一致:628 是 /test/index,630/631 是wechat_external_stocks/wechat_external_stock_pages前端 key必须与 DBpath逐字符相等,约定不先定就写不了PAGE_REGISTRY② 631 对应的物理页面文件不存在, pages.json也未注册先登记 PAGE_REGISTRY会立刻违反npm run check:pages规则①,用户点进去必失败③ 角色未授权:货主管理员(role 5)权限列表不含 628/630/631 用该身份登录 → menus为空 → 「我的」页入口区空白④ 「我的」页目前既不拉 user.info、也不渲染任何入口冷启动直接进「我的」页时 store 为空,无内容可渲染 - 执行顺序:定 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 → 通过。
两个需要注意的行为变化:
- 「测试页」
common: false→ 不再出现在首页「常用功能」,改到「我的」页;想改回去只需删掉pages.ts里那一行(一行回退)。 - 若某账号的入口全是非
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;
仍未做:
component保持NULL(web 分组用'Layout',小程序是否要求非空待 §6 答复;628 为 NULL 也能下发,说明不致命)。- 角色授权——给「货主管理员」(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 告警。
两条新约定(重要)
- 想让某个页面常驻首页 → 在
PAGE_REGISTRY里标common: true(不依赖后端配置与授权)。 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×tamp=...
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:pages9/9、0 告警;产物list.js/json/wxml/wxss已生成, 引用完整性 110 个引用 / 0 缺失
2026-09-28 调整(筛选条件与卡片字段):
- 筛选区改为 仓库 / SN管理 / 批次管理(移除货主筛选)
- 胶囊未选中时显示筛选项名(仓库 / SN管理 / 批次管理),选中后显示具体值(仓库名 / 是 / 否);
选「全部…」时回到筛选项名;筛选项多了,筛选行改为允许换行(
flex-wrap) - SN管理 / 批次管理 取值
'Y'/'N',走where的裸值 (与 new3handleConditionChange一致:它会把 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×tamp=...
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 }):维度 字段 取值 收货状态 statusreceiving 收货中 / completed 已完成 / cancelled 已作废 入库状态 storage_statuswaiting 待入库 / 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:pages10/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×tamp=...
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. 待向后端 / 产品确认
→ ✅ 已实测确认:原样下发(2026-09-25 测试页面板显示menus是否原样下发 DB 的pathwechat_external_stocks/wechat_external_stock_pages,未拼父路径)。D1-A 的实现方式正确。- 分组节点(
parent_id IS NULL且有子节点)的component是否必须非空?web 用'Layout',小程序新增的 630 是NULL,是否会被序列化过滤掉? miniprogram_pages是否也需要像 web 一样给分组节点填component,还是后端对type='miniprogram_pages'走独立逻辑?- 授权的推荐做法:新页面是逐个给角色勾选 id,还是把常用角色设为
'*'?若角色数多,是否有后台批量授权入口(避免每次加页面都要改 DB)。 - 产品侧:「首页常用功能」与「我的全部功能」的划分口径是什么?(决定 D4)