This commit is contained in:
yin 2026-09-25 18:00:10 +08:00
parent 2458987224
commit 55123b6f8e
16 changed files with 1658 additions and 163 deletions

99
src/api/index/index.ts Normal file
View File

@ -0,0 +1,99 @@
/**
* 通用下拉数据(后端 `index.*` 模块)
*
* 目前用于「外仓商品」页的**货主 / 仓库**筛选。等第二个页面也需要时,再考虑把它
* 与具体业务解耦(现在放这里就够了,避免过早抽象)。
*
* ⚠️ **响应结构不统一**(2026-09-25 实测 `index.loadStores`):
*
* ```json
* { "flag":"success", "code":200, "message":"ok",
* "stores":[{ "value":1000147, "label":"广州天豹云仓" }, ...], "timestamp":1790326225 }
* ```
*
* 1. 业务字段在**响应顶层**(**没有 `data` 包裹**,与 `wechat.getMyLoginCode` 同类)
* 2. 列表键名是模块化的:货主 `stores`、仓库 `warehouses`
* 3. 项已经是 `{ value, label }`(后端归一化好了,直接用)
*
* 所以下面用 `pickRows()` 依次兼容:顶层模块键 → `list`/`items` → `data` 包裹 → 直接数组;
* 项则先认 `value`/`label`,没有才回退到各表自己的字段名。
* 仓库接口的返回结构尚未实测,同样走这套容错。
*
* 权限点:`index.loadStores`(wms_permission id=444);未授权时接口失败并由 request 层统一 toast,
* 页面只显示「全部」。
*/
import request from '@/utils/request'
import { SYSTEM_URL, gatewayParams } from '@/utils/gateway'
/** 下拉选项:`value` 为后端 id;空字符串留给页面自己加的「全部」项 */
export interface SelectOption {
value: string | number
label: string
}
/** 从响应里取出列表数组(兼容顶层模块键 / list / items / data 包裹 / 直接数组) */
function pickRows(payload: any, rowKeys: string[]): any[] {
if (Array.isArray(payload)) return payload
for (const key of rowKeys) {
if (Array.isArray(payload?.[key])) return payload[key]
}
// 兼容「data 包裹」的写法({ data: { stores: [...] } })
const inner = payload?.data
if (inner && inner !== payload) return pickRows(inner, rowKeys)
return []
}
/** 把列表项归一化成 `{ value, label }` */
function toOptions(rows: any[], idKeys: string[], nameKeys: string[]): SelectOption[] {
return rows
.map((item: any) => {
const value =
item?.value ??
idKeys.map((key) => item?.[key]).find((v) => v !== undefined && v !== null && v !== '')
const label =
[item?.label, ...nameKeys.map((key) => item?.[key])].find(
(v) => typeof v === 'string' && v.trim()
)
return { value, label: label || (value !== undefined ? `#${value}` : '') }
})
.filter(
(option: SelectOption) =>
option.value !== undefined && option.value !== null && !!option.label
)
}
/** 货主列表(`index.loadStores`) */
export async function fetchStoreOptions(): Promise<SelectOption[]> {
const res = await request<any>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('index.loadStores'),
data: {},
auth: true
})
return toOptions(
pickRows(res, ['stores', 'list', 'items']),
['store_id', 'id'],
['store_name', 'name', 'company_name']
)
}
/** 仓库列表(`index.loadWarehouses`) */
export async function fetchWarehouseOptions(): Promise<SelectOption[]> {
const res = await request<any>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('index.loadWarehouses'),
data: {},
auth: true
})
return toOptions(
pickRows(res, ['warehouses', 'list', 'items']),
['warehouse_id', 'id'],
['warehouse_name', 'warehouse_remask', 'name']
)
}

View File

@ -0,0 +1,137 @@
/**
* 外仓商品列表(`stock.warehouse.externalList`)
*
* 与 new3 Web 端 `src/views/stock/external_stock/index.vue` **同一个接口、同一套参数结构**:
*
* ```
* body = {
* warehouse_id?: number, // 顶层(new3 已验证可用)
* pagination: { page, pageSize },
* where: { keyword?, store_id? }, // 通用过滤条件
* sort?: { sortField, sortOrder } // 小程序端不用(见下)
* }
* 返回 data = { list: [...], pagination: { total }, summary?: {...} }
* ```
*
* 小程序端只取 3 个字段展示(商品图片 / 商品名称 / 可用库存),并且**去掉**了排序、
* 每页条数选择、页码跳转等不适合移动端的交互 —— 分页改为「上拉加载」,
* 见 `pagesA/external-stock/list.vue`。
*
* ⚠️ **`store_id` 的位置尚未与后端确认**:new3 只用了 `where.keyword` 与顶层
* `warehouse_id`,没有货主过滤。小程序端按「通用过滤条件」的语义放进 `where.store_id`。
* 联调时若货主筛选不生效,**只改 `buildBody()` 一处**(例如提到顶层与 `warehouse_id` 并列)。
*/
import request from '@/utils/request'
import type { BizResponse } from '@/utils/request'
import { SYSTEM_URL, gatewayParams } from '@/utils/gateway'
/** 每页条数:移动端不做「每页条数」选择器,固定即可(与 new3 默认值一致) */
export const EXTERNAL_STOCK_PAGE_SIZE = 20
/** 列表项(只声明小程序用到的字段,其余用索引签名兜住) */
export interface ExternalStockItem {
id?: number
/** 商品编码 */
item_code?: string
/** 商品名称 */
item_name?: string
/** 图片地址数组(列表只取第一张作封面) */
images?: string[] | string | null
/** 可用库存:优先后端算好的这个字段 */
available_quantity?: number | null
/** 库存数量(`available_quantity` 缺失时用它减锁定库存兜底) */
quantity?: number | null
/** 订单锁定库存 */
locked_quantity?: number | null
/** 库存单位 */
stock_unit?: string
[key: string]: any
}
/** 列表响应体 `data` */
export interface ExternalStockPayload {
list?: ExternalStockItem[]
total?: number
pagination?: { page?: number; pageSize?: number; total?: number }
[key: string]: any
}
/** 查询条件(页面传入) */
export interface ExternalStockQuery {
page?: number
pageSize?: number
/** 关键词(商品名称 / 编码),空字符串表示不过滤 */
keyword?: string
/** 货主 id,空字符串表示全部 */
store_id?: number | string
/** 仓库 id,空字符串表示全部 */
warehouse_id?: number | string
}
function isFilled(value: unknown): boolean {
return value !== undefined && value !== null && value !== ''
}
/** 组装请求体(⚠️ 货主过滤位置要调整时改这里) */
function buildBody(query: ExternalStockQuery): Record<string, any> {
const { page = 1, pageSize = EXTERNAL_STOCK_PAGE_SIZE, keyword, store_id, warehouse_id } = query
const where: Record<string, any> = {}
if (keyword && String(keyword).trim()) where.keyword = String(keyword).trim()
if (isFilled(store_id)) where.store_id = store_id
return {
...(isFilled(warehouse_id) ? { warehouse_id } : {}),
pagination: { page, pageSize },
where
}
}
/** 外仓商品列表(分页) */
export function externalStockList(
query: ExternalStockQuery = {}
): Promise<BizResponse<ExternalStockPayload>> {
return request<ExternalStockPayload>({
url: SYSTEM_URL,
method: 'POST',
params: gatewayParams('stock.warehouse.externalList'),
data: buildBody(query),
// 需要登录:未登录时不发请求,直接弹登录抽屉
auth: true
})
}
/** 总数:后端放在 `pagination.total`(也可能在顶层 `total`) */
export function readTotal(payload: ExternalStockPayload | undefined | null): number {
const total = payload?.pagination?.total ?? payload?.total ?? 0
const num = Number(total)
return Number.isFinite(num) && num > 0 ? num : 0
}
/** 列表项的封面图(`images` 可能是数组、字符串或空) */
export function readCover(item: ExternalStockItem | undefined | null): string {
const images = item?.images
if (Array.isArray(images)) return images.find((url) => !!url) || ''
if (typeof images === 'string') return images
return ''
}
/**
* 可用库存
*
* 优先后端算好的 `available_quantity`;缺失时用 `quantity - locked_quantity` 兜底
* (两者是同一张表 `wms_stock_warehouse` 上的字段)。
* 返回 `null` 表示后端没给数据,页面显示 `—`(**不要显示 0**,那会被误读成「没库存」)。
*/
export function readAvailableQuantity(item: ExternalStockItem | undefined | null): number | null {
if (isFilled(item?.available_quantity)) {
const value = Number(item?.available_quantity)
if (Number.isFinite(value)) return value
}
const quantity = Number(item?.quantity)
if (!Number.isFinite(quantity)) return null
const locked = Number(item?.locked_quantity)
return quantity - (Number.isFinite(locked) ? locked : 0)
}

View File

@ -7,17 +7,7 @@
import request from '@/utils/request'
import type { BizResponse } from '@/utils/request'
/** /system 网关统一入口 */
const SYSTEM_URL = '/system'
/**
* 构造 /system 网关的公共 query 参数
* 与 new3 完全一致:method + v + timestamp
*/
function gatewayParams(method: string): Record<string, any> {
return { method, v: '1.0', timestamp: Date.now() }
}
import { SYSTEM_URL, gatewayParams } from '@/utils/gateway'
// ────────────────────────────── 类型 ──────────────────────────────

View File

@ -0,0 +1,76 @@
<template>
<view class="sections">
<view v-for="section in sections" :key="section.key" class="section">
<view v-if="section.title" class="section__title">{{ section.title }}</view>
<view class="grid">
<view
v-for="item in section.leaves"
:key="item.key"
class="grid__item"
@click="emit('select', item)"
>
<up-icon :name="item.icon || 'grid'" color="#2979ff" size="26"></up-icon>
<text class="grid__item-text">{{ item.title }}</text>
</view>
</view>
</view>
</view>
</template>
<script setup lang="ts">
/**
* 入口区展示组件:**段标题 + 子项九宫格**(多段)
*
* 只做展示与事件上抛,**不做任何取数 / 登录判断**:
* - 数据由 `useEntrySections()` 提供(首页与「我的」页共用同一份口径)
* - 点击后「要不要登录、跳哪个 API」由父页面的 `onEntry` 决定
*
* 用法:
* ```vue
* <entry-sections :sections="sections" @select="onEntry" />
* ```
*/
import type { EntryLeaf, EntrySection } from '@/router/entries'
defineProps<{
/** 由 `toSections()` 产出(已按分类分段) */
sections: EntrySection[]
}>()
const emit = defineEmits<{ (e: 'select', leaf: EntryLeaf): void }>()
</script>
<style lang="scss" scoped>
.sections {
padding-bottom: 8rpx;
}
.section {
&__title {
padding: 16rpx 32rpx 0;
font-size: 26rpx;
color: #909399;
}
}
.grid {
display: flex;
flex-wrap: wrap;
padding: 8rpx 0 24rpx;
&__item {
width: 33.333%;
display: flex;
flex-direction: column;
align-items: center;
padding: 24rpx 0;
}
&__item-text {
margin-top: 12rpx;
font-size: 26rpx;
color: #606266;
}
}
</style>

View File

@ -0,0 +1,115 @@
/**
* 首页入口区渲染状态
*
* 首页的入口区 = **本地「常用功能」列表**(`LOCAL_COMMON_ENTRIES`,前端写死)+ 后端菜单段
* (`user.info` 的 menus × `PAGE_REGISTRY`),两段形态一致、并排展示,合成逻辑在 `toHomeSections()`。
*
* 这个 composable 负责把「取数 / 加载态 / 空态文案 / 点击跳转」收口在一处,
* 页面只负责 `onShow` 调一次 `loadEntries()`,然后把 `sections` 交给模板。
*
* 登录态差异:未登录时后端菜单为空 ⇒ 只剩下「常用功能」段(公开页仍可浏览,满足微信审核要求)。
*/
import { computed, ref } from 'vue'
import type { ComputedRef, Ref } from 'vue'
import { useUserStore } from '@/store/modules/user'
import { usePermissionStore } from '@/store/modules/permission'
import { usePageAuth } from '@/composables/usePageAuth'
import { toHomeSections } from '@/router/entries'
import type { EntryLeaf, EntrySection } from '@/router/entries'
import type { AuthMode } from '@/router/pages'
import { navigateToPath } from '@/utils/navigate'
export interface UseEntrySectionsOptions {
/** 无分组叶子的兜底段标题(默认「其他」) */
looseTitle?: string
}
export interface UseEntrySectionsReturn {
/** 是否已登录 */
isLogin: ComputedRef<boolean>
/** 页面直接 `v-for` 渲染的分段(段标题 + 九宫格) */
sections: ComputedRef<EntrySection[]>
/** 是否正在拉取 `user.info` */
loading: Ref<boolean>
/**
* 拉取用户信息(= 菜单 + 权限点)
* @param force 是否强制刷新(「重试」按钮用;`onShow` 不传,避免切 Tab 就重拉)
*/
loadEntries: (force?: boolean) => Promise<void>
/** 点击入口:需登录而未登录 → 页内引导;否则按 tabBar 与否跳转 */
onEntry: (leaf: EntryLeaf) => void
/** 唤起登录(**就地弹抽屉**,不跳页) */
goLogin: () => void
/** 去「我的」页(绑定账号 / 查看全部功能) */
goMine: () => void
/** `empty-state` 组件的属性(未绑定账号时会覆盖默认文案) */
emptyStateProps: ComputedRef<Record<string, unknown>>
}
/**
* @param auth 本页在 `PAGE_REGISTRY` 里声明的登录策略(首页为 `'public'`)
*/
export function useEntrySections(
auth: AuthMode,
options: UseEntrySectionsOptions = {}
): UseEntrySectionsReturn {
const { looseTitle } = options
const userStore = useUserStore()
const permissionStore = usePermissionStore()
const { isLogin, goLogin, requireLogin } = usePageAuth(auth)
const loading = ref(false)
/** 本地「常用功能」段 + 后端菜单段(未登录时后端段为空,只剩下常用功能) */
const sections = computed(() => toHomeSections(permissionStore.entries, { looseTitle }))
const emptyStateProps = computed<Record<string, unknown>>(() => {
if (userStore.isWechatUnbound) {
return { text: '微信已登录,绑定 WMS 账号后即可使用各功能', icon: 'account' }
}
// 返回空对象不覆盖 empty-state 的默认值(默认文案 = 服务器出差了,请稍后再试)
return {}
})
const loadEntries = async (force = false): Promise<void> => {
if (!userStore.isLogin) return
// `user.info` 已由 App 启动统一拉取并存在 store;这里只在没有数据时补拉或显式重试
if (userStore.hasUserInfo && !force) return
// 未绑定的微信登录态没有菜单可拉(绑定后 user.info 会重新灌菜单)
if (userStore.isWechatUnbound && !force) return
loading.value = true
try {
await userStore.getInfo(force)
} catch {
// 失败 → sections 为空 → 走空态文案 + 「重试」(提示由 request 层统一 toast)
} finally {
loading.value = false
}
}
const onEntry = (leaf: EntryLeaf): void => {
if (leaf.auth === 'required' && !isLogin.value) {
requireLogin(`「${leaf.title}」需要登录后使用`)
return
}
navigateToPath(leaf.path, leaf.title)
}
const goMine = (): void => {
uni.switchTab({ url: '/pages/mine/mine' })
}
return {
isLogin,
sections,
loading,
loadEntries,
onEntry,
goLogin,
goMine,
emptyStateProps
}
}

View File

@ -60,6 +60,15 @@
"style": {
"navigationBarTitleText": "测试页"
}
},
{
"path": "external-stock/list",
"style": {
"navigationBarTitleText": "外仓商品",
"enablePullDownRefresh": true,
"backgroundTextStyle": "dark",
"onReachBottomDistance": 80
}
}
]
}
@ -110,6 +119,10 @@
{
"name": "测试页",
"path": "pagesA/test/index"
},
{
"name": "外仓商品",
"path": "pagesA/external-stock/list"
}
]
},

View File

@ -6,34 +6,21 @@
<view class="hero__desc">{{ heroDesc }}</view>
</view>
<!-- 业务入口:未登录取本地公共入口,登录后取后端菜单(分组标题 + 子项九宫格) -->
<!-- 功能入口:本地「常用功能」列表 + 后端菜单分类段(两段形态一致,见 toHomeSections) -->
<view class="card">
<view class="card__title">常用功能</view>
<!-- 登录后菜单尚未取到时的加载态(避免闪一下空态文案) -->
<view v-if="loading" class="loading">
<up-loading-icon mode="circle" size="18" text="加载中"></up-loading-icon>
</view>
<!-- 有入口:分组标题 + 子项九宫格 -->
<view v-else-if="sections.length" class="sections">
<view v-for="section in sections" :key="section.key" class="section">
<view v-if="section.title" class="section__title">{{ section.title }}</view>
<view class="grid">
<view
v-for="item in section.leaves"
:key="item.key"
class="grid__item"
@click="onEntry(item)"
>
<up-icon :name="item.icon || 'grid'" color="#2979ff" size="26"></up-icon>
<text class="grid__item-text">{{ item.title }}</text>
</view>
</view>
</view>
</view>
<!-- 「常用功能」段(本地)+ 后端分类段(如「外仓商品」);重复的 key 会自动去重 -->
<entry-sections
v-else-if="sections.length"
:sections="sections"
@select="onEntry"
></entry-sections>
<!-- 无内容 / 接口失败:统一空态文案,不白屏(§3.5.1) -->
<!-- 兜底空态:正常走不到(「常用功能」至少有公开页),只要不白屏即可 -->
<empty-state v-else v-bind="emptyStateProps" @retry="loadEntries(true)">
<!-- 未登录 → 去登录 -->
<template v-if="!isLogin" #action>
@ -52,7 +39,7 @@
shape="circle"
size="small"
text="去绑定账号"
@click="goBind"
@click="goMine"
></up-button>
</template>
</empty-state>
@ -76,32 +63,26 @@
import { computed, ref } from 'vue'
import { onShow } from '@dcloudio/uni-app'
import { useUserStore } from '@/store/modules/user'
import { usePermissionStore } from '@/store/modules/permission'
import { usePageAuth } from '@/composables/usePageAuth'
import { useEntrySections } from '@/composables/useEntrySections'
import { useEntryScene } from '@/composables/useEntryScene'
import AuthModal from '@/components/auth-modal/auth-modal.vue'
import { LOCAL_PUBLIC_ENTRIES, toSections } from '@/router/entries'
import type { EntryLeaf } from '@/router/entries'
import { navigateToPath } from '@/utils/navigate'
import EntrySections from '@/components/entry-sections/entry-sections.vue'
const version = ref(uni.$u.config.v)
const platform = ref(uni.getSystemInfoSync().uniPlatform)
const userStore = useUserStore()
const permissionStore = usePermissionStore()
// 本页是 public:未登录也能正常浏览
const { isLogin, goLogin, requireLogin } = usePageAuth('public')
const loading = ref(false)
/**
* 入口来源(见《页面渲染框架》§3.5):
* - 未登录 → 本地公共入口清单(确定性,不依赖后端是否配置)
* - 已登录 → 后端菜单 × PAGE_REGISTRY 的可见入口树
* 入口区状态(与后端菜单解耦,见 `useEntrySections`)
*
* - 「常用功能」段 = **本地列表**(`PageMeta.common === true` 的页面:公开示例 + 测试页)
* → 不受登录态 / 授权 / 接口故障影响,开发联调随时能进测试页
* - 其后是后端菜单段(`user.info` 的 menus × `PAGE_REGISTRY`,如「外仓商品」分类)
* - 未登录时后端段为空,只剩下「常用功能」(公开页仍可浏览)
*/
const sections = computed(() =>
toSections(isLogin.value ? permissionStore.entries : LOCAL_PUBLIC_ENTRIES)
)
const { isLogin, sections, loading, loadEntries, onEntry, goLogin, goMine, emptyStateProps } =
useEntrySections('public')
const heroDesc = computed(() => {
if (!isLogin.value) return 'WMS 仓储管理 · 微信小程序端'
@ -115,52 +96,7 @@ const heroDesc = computed(() => {
return parts.length ? parts.join(' · ') : 'WMS 仓储管理 · 微信小程序端'
})
/**
* 空态文案 / 图标:未绑定与接口失败必须区分
*
* 返回空对象时不覆盖 `empty-state` 的默认值(默认是「服务器出差了,请稍后再试」),
* 否则未绑定用户会误以为是网络故障。
*/
const emptyStateProps = computed(() =>
userStore.isWechatUnbound
? { text: '微信已登录,绑定 WMS 账号后即可使用各功能', icon: 'account' }
: {}
)
/** 引导去「我的」页绑定(那里是常驻的绑定入口;登录页因已有 token 会直接放行) */
const goBind = () => {
uni.switchTab({ url: '/pages/mine/mine' })
}
/**
* 拉取用户信息(= 菜单 + 权限点,失败提示由 request 层统一 toast)
* @param force 是否强制刷新(“重试”按钮用;onShow 不传,避免切 Tab 就重拉)
*/
const loadEntries = async (force = false) => {
if (!userStore.isLogin) return
// `user.info` 已由 App 启动统一拉取并存在 store;这里只在没有数据时补拉或显式重试
if (userStore.hasUserInfo && !force) return
// 未绑定的微信登录态没有菜单可拉(绑定后 user.info 会重新灌菜单)
if (userStore.isWechatUnbound && !force) return
loading.value = true
try {
await userStore.getInfo(force)
} catch {
// 失败 → sections 为空 → 走空态文案 + 「重试」
} finally {
loading.value = false
}
}
/** 点击入口:需登录而未登录 → 页内引导(不自动跳转);否则按 tabBar 与否跳转 */
const onEntry = (item: EntryLeaf) => {
if (item.auth === 'required' && !isLogin.value) {
requireLogin(`「${item.title}」需要登录后使用`)
return
}
navigateToPath(item.path, item.title)
}
/* 空态文案、取数(loadEntries)、点击跳转(onEntry)均收口在 useEntrySections */
// onShow:tabBar 页切换只触发 onShow、不触发 onLoad;
// 已加载过会直接返回,所以放在这里既能在冷启动补拉,也不会重复请求
@ -210,17 +146,7 @@ useEntryScene()
}
}
.sections {
padding-bottom: 8rpx;
}
.section {
&__title {
padding: 16rpx 32rpx 0;
font-size: 26rpx;
color: #909399;
}
}
/* 段标题 + 九宫格的样式在 components/entry-sections(首页与「我的」共用,勿在此重复定义) */
.loading {
display: flex;
@ -228,24 +154,4 @@ useEntryScene()
justify-content: center;
padding: 56rpx 0;
}
.grid {
display: flex;
flex-wrap: wrap;
padding: 8rpx 0 24rpx;
&__item {
width: 33.333%;
display: flex;
flex-direction: column;
align-items: center;
padding: 24rpx 0;
}
&__item-text {
margin-top: 12rpx;
font-size: 26rpx;
color: #606266;
}
}
</style>

View File

@ -45,6 +45,9 @@
* - 头部用户信息区 = **唯一的登录入口**(未登录点击弹抽屉;已登录进「用户信息」页)
* - 菜单里的细项(身份信息 / 待绑定 / 微信资料 / 电脑端登录码 / **退出登录**)全部移到
* 二级页 `pages/mine/user-info`,本页不再堆卡片
*
* ⚠️ 功能入口(九宫格)统一放在**首页** = 本地「常用功能」列表 + 后端菜单分类段;
* 本页不再渲染页面列表(2026-09-25 调整)。
*/
import { computed } from 'vue'
import { onShow } from '@dcloudio/uni-app'

View File

@ -10,13 +10,13 @@
<view class="card">
<view class="card__title">这页验证什么</view>
<view class="text">
它在 PAGE_REGISTRY 里声明为 auth: 'public' 且未设 hidden,因此会
<text class="text--strong">自动出现在未登录时的首页九宫格</text>
里(LOCAL_PUBLIC_ENTRIES)。
它在 PAGE_REGISTRY 里声明为 auth: 'public' 且
<text class="text--strong">common: true</text>,因此会出现在首页
<text class="text--strong">「常用功能」段</text>里(LOCAL_COMMON_ENTRIES),**未登录也能看到**。
</view>
<view class="text">
这正是「未登录也必须有可浏览内容」这条微信审核要求的落点:
公共入口由前端本地清单决定,不依赖后端菜单是否配置。
「常用功能」由前端本地清单决定,不依赖后端菜单是否配置。
</view>
</view>
</view>

View File

@ -0,0 +1,615 @@
<template>
<view class="page">
<!-- required 未登录:页内「请先登录」+ 去登录,**不自动跳转** -->
<auth-gate auth="required">
<template #default>
<!-- 筛选区(吸顶):关键词 + 搜索;货主 / 仓库用胶囊按钮唤起底部选择器 -->
<view class="filter">
<view class="filter__row">
<view class="filter__input">
<up-input
v-model="form.keyword"
color="#303133"
placeholder-style="color: #c0c4cc"
placeholder="搜索商品名称 / 编码"
prefix-icon="search"
border="none"
clearable
confirm-type="search"
@confirm="onSearch"
></up-input>
</view>
<up-button
type="primary"
shape="circle"
size="small"
text="搜索"
@click="onSearch"
></up-button>
</view>
<view class="filter__row filter__row--chips">
<view
class="chip"
:class="{ 'chip--active': isFilled(form.store_id) }"
@click="openPicker('store')"
>
<text class="chip__text">{{ storeLabel }}</text>
<up-icon
name="arrow-down"
size="12"
:color="isFilled(form.store_id) ? '#2979ff' : '#909399'"
></up-icon>
</view>
<view
class="chip"
:class="{ 'chip--active': isFilled(form.warehouse_id) }"
@click="openPicker('warehouse')"
>
<text class="chip__text">{{ warehouseLabel }}</text>
<up-icon
name="arrow-down"
size="12"
:color="isFilled(form.warehouse_id) ? '#2979ff' : '#909399'"
></up-icon>
</view>
<view v-if="hasFilter" class="filter__reset" @click="onReset">重置</view>
</view>
</view>
<!-- 首屏加载 -->
<view v-if="loading" class="loading">
<up-loading-icon mode="circle" size="18" text="加载中"></up-loading-icon>
</view>
<template v-else-if="list.length">
<!-- 结果统计:移动端不给页码 / 跳页,只给总量与已加载数 -->
<view class="count">
共 {{ total }} 件商品<text v-if="total > list.length"> · 已加载 {{ list.length }}</text>
</view>
<!-- 商品条目:小程序只展示 图片 / 名称 / 可用库存 三个字段 -->
<view
v-for="(item, index) in list"
:key="item.id ?? item.item_code ?? index"
class="goods"
>
<image
v-if="coverOf(item)"
class="goods__img"
:src="coverOf(item)"
mode="aspectFill"
></image>
<view v-else class="goods__img goods__img--empty">
<up-icon name="photo" color="#c0c4cc" size="28"></up-icon>
</view>
<view class="goods__main">
<view class="goods__name">{{ item.item_name || '未命名商品' }}</view>
<view class="goods__qty">
可用库存
<text class="goods__qty-num">{{ qtyTextOf(item) }}</text>
</view>
</view>
</view>
<!--
移动端分页器(替掉 Web 的 页码 / 每页条数 / 跳页):
上拉自动加载;点这一行也能加载或重试(解决部分容器 onReachBottom 不触发)
-->
<view class="more" @click="onTapMore">
<up-loading-icon
v-if="loadingMore"
mode="circle"
size="16"
text="加载中"
></up-loading-icon>
<text v-else-if="failed" class="more__retry">加载失败,点击重试</text>
<text v-else-if="noMore" class="more__end">没有更多了</text>
<text v-else class="more__text">上拉加载更多</text>
</view>
</template>
<!-- 空态:首次加载失败 / 无数据(有筛选条件时文案不同) -->
<empty-state v-else v-bind="emptyStateProps" @retry="load(true)"></empty-state>
</template>
</auth-gate>
<!-- 选择器(货主 / 仓库):底部弹层,避免移动端多层级选择 -->
<up-popup :show="pickerVisible" mode="bottom" :round="16" @close="closePicker">
<view class="picker">
<view class="picker__title">{{ pickerTitle }}</view>
<!-- 选项多时(如货主 100+)给个名称搜索,不然要在长列表里划很久 -->
<view v-if="pickerSearchable" class="picker__search">
<up-input
v-model="pickerKeyword"
color="#303133"
placeholder-style="color: #c0c4cc"
:placeholder="`搜索${pickerKind === 'store' ? '货主' : '仓库'}名称`"
prefix-icon="search"
border="none"
clearable
></up-input>
</view>
<scroll-view class="picker__list" scroll-y>
<view
v-for="option in pickerOptions"
:key="String(option.value)"
class="picker__item"
:class="{ 'picker__item--active': option.value === pickerValue }"
@click="chooseOption(option)"
>
<text class="picker__item-text">{{ option.label }}</text>
<up-icon
v-if="option.value === pickerValue"
name="checkmark"
color="#2979ff"
size="16"
></up-icon>
</view>
<view v-if="pickerLoading" class="picker__tip">加载中…</view>
<view v-else-if="pickerOptions.length <= 1" class="picker__tip">
{{ pickerKeyword ? '没有匹配的名称' : '暂无可选项' }}
</view>
</scroll-view>
<view class="picker__cancel" @click="closePicker">取消</view>
</view>
</up-popup>
<!-- 登录抽屉:点「去登录」或碰需要登录的接口时就地弹出(不跳页) -->
<auth-modal></auth-modal>
</view>
</template>
<script setup lang="ts">
/**
* 外仓商品(列表)
*
* 接口与 new3 Web 端 `views/stock/external_stock/index.vue` **同源**
* (`stock.warehouse.externalList`,见 `api/stock/external-stock.ts`),
* 但交互按**移动端**重做:
*
* | Web 端 | 小程序端(本页) |
* |---|---|
* | 工具栏 + 高级筛选字段树 | 顶部固定筛选区:关键词 + 搜索 + 货主 / 仓库 |
* | 底部页码 / 每页条数 / 跳页 / 多列排序 | **上拉自动加载**,底部一行状态(加载中 / 没有更多 / 点击重试) |
* | 表格多列(编码 / 品牌 / 单位 / 管理属性…) | 卡片,**只展示 商品图片 / 商品名称 / 可用库存** |
* | 刷新按钮 | 下拉刷新(`enablePullDownRefresh`) |
*
* ⚠️ 三条必须保持一致,改任意一处都要同步另两处(`npm run check:pages` 会校验):
* 1. 本文件的物理路径 `pagesA/external-stock/list`
* 2. `src/pages.json` 里 `subPackages[pagesA]` 的注册
* 3. `src/router/pages.ts` 的 `PAGE_REGISTRY`(key = 后端 `wms_permission.path`)
*/
import { computed, reactive, ref, watch } from 'vue'
import { onLoad, onPullDownRefresh, onReachBottom } from '@dcloudio/uni-app'
import { usePageAuth } from '@/composables/usePageAuth'
import AuthModal from '@/components/auth-modal/auth-modal.vue'
import { fetchStoreOptions, fetchWarehouseOptions } from '@/api/index/index'
import type { SelectOption } from '@/api/index/index'
import {
EXTERNAL_STOCK_PAGE_SIZE,
externalStockList,
readAvailableQuantity,
readCover,
readTotal
} from '@/api/stock/external-stock'
import type { ExternalStockItem } from '@/api/stock/external-stock'
/** 本页是 required:未登录时只做页内提示,不自动跳登录 */
const { isLogin } = usePageAuth('required')
/** 筛选条件(关键词回车 / 点搜索才生效,避免每输入一个字就请求) */
const form = reactive({
keyword: '',
store_id: '' as string | number,
warehouse_id: '' as string | number
})
const list = ref<ExternalStockItem[]>([])
/** 后端总数(用于「共 N 件」与判断是否到底) */
const total = ref(0)
/** 已加载到第几页(0 = 还没加载过) */
const page = ref(0)
const loading = ref(false)
const loadingMore = ref(false)
const noMore = ref(false)
const failed = ref(false)
const isFilled = (value: unknown): boolean =>
value !== undefined && value !== null && value !== ''
const hasFilter = computed(
() => !!form.keyword.trim() || isFilled(form.store_id) || isFilled(form.warehouse_id)
)
/** 可用库存文案:后端没给数据显示 `—`(**不能回退成 0**,会被误读成「没库存」) */
const qtyTextOf = (item: ExternalStockItem): string => {
const value = readAvailableQuantity(item)
return value === null ? '—' : String(value)
}
const coverOf = (item: ExternalStockItem): string => readCover(item)
/**
* 拉取列表
* @param reset true = 回到第 1 页(首次 / 搜索 / 筛选 / 下拉刷新);false = 加载下一页
*/
const load = async (reset = false): Promise<void> => {
if (!isLogin.value) return
if (loading.value || loadingMore.value) return
if (!reset && noMore.value) return
// 失败时不推进 page,所以「重试」会重发同一页
const target = reset ? 1 : page.value + 1
if (reset) loading.value = true
else loadingMore.value = true
failed.value = false
try {
const res = await externalStockList({
page: target,
pageSize: EXTERNAL_STOCK_PAGE_SIZE,
keyword: form.keyword,
store_id: form.store_id,
warehouse_id: form.warehouse_id
})
const payload = res?.data
const rows = payload?.list || []
list.value = reset ? rows : [...list.value, ...rows]
total.value = readTotal(payload)
page.value = target
// 后端没给 total 时(readTotal = 0)用「本页不满一页」兜底判到底
noMore.value =
rows.length < EXTERNAL_STOCK_PAGE_SIZE ||
(total.value > 0 && list.value.length >= total.value)
} catch {
// 失败提示由 request 层统一 toast;这里只管状态:首屏失败 → 空态可重试;加载更多 → 底部可重试
if (reset) {
list.value = []
total.value = 0
page.value = 0
}
failed.value = true
} finally {
loading.value = false
loadingMore.value = false
uni.stopPullDownRefresh()
}
}
const onSearch = (): void => {
load(true)
}
const onReset = (): void => {
form.keyword = ''
form.store_id = ''
form.warehouse_id = ''
storeLabel.value = '全部货主'
warehouseLabel.value = '全部仓库'
load(true)
}
/** 点底部状态行:加载更多 / 重试(到底了就什么都不做) */
const onTapMore = (): void => {
if (noMore.value) return
load(false)
}
// ── 货主 / 仓库选择器(底部弹层,一个组件复用于两个维度)──
type PickerKind = 'store' | 'warehouse'
const pickerVisible = ref(false)
const pickerKind = ref<PickerKind>('store')
const pickerLoading = ref(false)
/** 弹层内的名称搜索(选项多时才有意义,见 pickerSearchable) */
const pickerKeyword = ref('')
const storeOptions = ref<SelectOption[]>([])
const warehouseOptions = ref<SelectOption[]>([])
/** 胶囊上显示的名称(选中后显示具体名称,未选显示「全部…」) */
const storeLabel = ref('全部货主')
const warehouseLabel = ref('全部仓库')
const pickerTitle = computed(() => (pickerKind.value === 'store' ? '选择货主' : '选择仓库'))
const pickerValue = computed(() =>
pickerKind.value === 'store' ? form.store_id : form.warehouse_id
)
/** 选项超过这个数量才出搜索框(选项少时搜索框是干扰) */
const pickerSearchable = computed(
() =>
(pickerKind.value === 'store' ? storeOptions.value : warehouseOptions.value).length > 12
)
const pickerOptions = computed<SelectOption[]>(() => {
const allOption: SelectOption = {
value: '',
label: pickerKind.value === 'store' ? '全部货主' : '全部仓库'
}
const source = pickerKind.value === 'store' ? storeOptions.value : warehouseOptions.value
const keyword = pickerKeyword.value.trim().toLowerCase()
// 「全部」不参与过滤,永远置顶
const matched = keyword
? source.filter((option) => option.label.toLowerCase().includes(keyword))
: source
return [allOption, ...matched]
})
/** 首次打开某个维度时才拉它的选项(拉过就缓存,不重复请求) */
const ensureOptions = async (kind: PickerKind): Promise<void> => {
const target = kind === 'store' ? storeOptions : warehouseOptions
if (target.value.length) return
pickerLoading.value = true
try {
const options = kind === 'store' ? await fetchStoreOptions() : await fetchWarehouseOptions()
target.value = options
} catch {
// 失败提示由 request 层统一 toast;这里保持空列表(弹层里只剩「全部」+ 提示)
} finally {
pickerLoading.value = false
}
}
const openPicker = (kind: PickerKind): void => {
pickerKind.value = kind
pickerKeyword.value = ''
pickerVisible.value = true
ensureOptions(kind)
}
const closePicker = (): void => {
pickerVisible.value = false
}
const chooseOption = (option: SelectOption): void => {
if (pickerKind.value === 'store') {
form.store_id = option.value
storeLabel.value = option.label
} else {
form.warehouse_id = option.value
warehouseLabel.value = option.label
}
closePicker()
load(true)
}
/** 空态文案:有筛选条件时不能用「服务器出差了」这种口气 */
const emptyStateProps = computed(() =>
hasFilter.value ? { text: '没有符合条件的商品,试试换个关键词或筛选条件' } : {}
)
// ── 生命周期 ──
onLoad(() => {
load(true)
})
// 未登录进来是空态(页内有登录引导);登录成功后自动拉一次
watch(isLogin, (value) => {
if (value && !list.value.length) load(true)
})
// 下拉刷新:替代 Web 端的「刷新」按钮
onPullDownRefresh(() => {
load(true)
})
// 上拉加载下一页:替代 Web 端底部的页码控件
onReachBottom(() => {
load(false)
})
</script>
<style lang="scss" scoped>
.page {
min-height: 100vh;
background-color: #f5f6fa;
padding-bottom: 24rpx;
}
/* 筛选区:吸顶。部分低版本基础库不支持 sticky 就退化为普通块,不影响使用 */
.filter {
position: sticky;
top: 0;
z-index: 10;
padding: 16rpx 24rpx 12rpx;
background-color: #ffffff;
border-bottom: 1rpx solid #ebeef5;
&__row {
display: flex;
align-items: center;
&--chips {
margin-top: 12rpx;
}
}
&__input {
flex: 1;
/* flex 子项里的输入框必须允许收缩,否则长占位符会把搜索按钮挤出去 */
min-width: 0;
margin-right: 16rpx;
padding: 0 20rpx;
background-color: #f5f6fa;
border-radius: 999rpx;
}
&__reset {
padding: 8rpx 8rpx 8rpx 16rpx;
font-size: 24rpx;
color: #2979ff;
}
}
.chip {
display: flex;
align-items: center;
max-width: 320rpx;
margin-right: 16rpx;
padding: 10rpx 20rpx;
background-color: #f5f6fa;
border-radius: 999rpx;
&--active {
background-color: rgba(41, 121, 255, 0.1);
}
&__text {
margin-right: 6rpx;
font-size: 24rpx;
color: #606266;
/* 货主名可能很长:截断而不是把筛选行撑破 */
max-width: 240rpx;
overflow: hidden;
white-space: nowrap;
text-overflow: ellipsis;
}
}
.loading {
display: flex;
align-items: center;
justify-content: center;
padding: 96rpx 0;
}
.count {
padding: 20rpx 32rpx 0;
font-size: 24rpx;
color: #909399;
}
.goods {
display: flex;
margin: 20rpx 24rpx 0;
padding: 20rpx;
background-color: #ffffff;
border-radius: 16rpx;
&__img {
flex-shrink: 0;
width: 160rpx;
height: 160rpx;
border-radius: 12rpx;
background-color: #f5f6fa;
&--empty {
display: flex;
align-items: center;
justify-content: center;
}
}
&__main {
flex: 1;
min-width: 0;
margin-left: 20rpx;
display: flex;
flex-direction: column;
justify-content: space-between;
}
&__name {
font-size: 28rpx;
line-height: 1.5;
color: #303133;
/* 两行截断:长商品名不把卡片撑高,列表扫视更整齐 */
display: -webkit-box;
-webkit-box-orient: vertical;
-webkit-line-clamp: 2;
overflow: hidden;
}
&__qty {
font-size: 24rpx;
color: #909399;
}
&__qty-num {
margin-left: 8rpx;
font-size: 32rpx;
font-weight: 600;
color: #2979ff;
}
}
/* 底部状态行 = 移动端的分页器(见模板注释) */
.more {
display: flex;
align-items: center;
justify-content: center;
padding: 32rpx 24rpx;
font-size: 24rpx;
color: #909399;
&__retry {
color: #2979ff;
}
}
.picker {
padding-top: 24rpx;
&__title {
padding: 0 32rpx 16rpx;
font-size: 30rpx;
font-weight: 600;
color: #303133;
}
&__list {
/* scroll-view 需要高度上限,否则长列表会顶出屏幕 */
max-height: 60vh;
}
&__search {
margin: 0 32rpx 12rpx;
padding: 0 20rpx;
background-color: #f5f6fa;
border-radius: 999rpx;
}
&__item {
display: flex;
align-items: center;
justify-content: space-between;
padding: 26rpx 32rpx;
font-size: 28rpx;
color: #303133;
&--active {
color: #2979ff;
}
}
&__item-text {
flex: 1;
margin-right: 16rpx;
overflow: hidden;
white-space: nowrap;
text-overflow: ellipsis;
}
&__tip {
padding: 32rpx;
text-align: center;
font-size: 26rpx;
color: #909399;
}
&__cancel {
padding: 24rpx;
text-align: center;
font-size: 28rpx;
color: #606266;
border-top: 1rpx solid #f2f3f5;
}
}
</style>

View File

@ -10,11 +10,7 @@
<up-cell-group :border="false">
<up-cell title="逻辑路径" value="/test/index" :border="false"></up-cell>
<up-cell title="物理路径" value="pagesA/test/index" :border="false"></up-cell>
<up-cell
title="后端数据源"
value="wms_permission id=627"
:border="false"
></up-cell>
<up-cell title="后端数据源" value="wms_permission id=628" :border="false"></up-cell>
</up-cell-group>
</view>
@ -42,7 +38,7 @@
</view>
<view v-if="!permissionStore.menus.length" class="text text--warn">
后端没有下发任何菜单 → 说明 platform=miniProgram 时 menus 未取自
miniprogram_pages,或当前账号的角色未授权 627。
miniprogram_pages,或当前账号的角色未授权 628。
</view>
<template v-else>
<view class="text">

View File

@ -11,6 +11,7 @@
* | 未命中 | **忽略该项**,记入 `missing`(不影响其它入口,由调用方告警) |
* | 分组节点无子项命中 | 整组丢弃(避免渲染出空分组) |
* | `hidden = 1` | 不进导航入口 |
* | `common: true` 的本地页面 | 无论后端是否下发,都进首页「常用功能」段(见 `LOCAL_COMMON_ENTRIES`) |
*
* ⚠️ **输出固定为两层**(`EntryGroup.children` 只能是 `EntryLeaf`):
* 小程序首页是「分组标题 + 子项九宫格」(决策点 4),
@ -183,22 +184,19 @@ export function generateEntries(menus: MenuNode[] | null | undefined): GenerateE
}
/**
* 本地公共入口清单 —— 未登录时首页九宫格的**兜底内容**
* 首页「常用功能」—— **本地维护**的页面列表(与后端菜单无关)
*
* 为什么不用后端菜单:这是为了保「未登录可见什么」是**确定性**的 ——
* 不依赖后端是否配置、也不受接口/网络故障影响,微信审核时更可控。
* 后端 `miniprogram_pages` 只需描述「登录后能看到什么」。见《页面渲染框架》§3.5。
* 为什么单独搞一份:这个段要在**任何登录态 / 授权 / 接口故障 / 后端未配置**的情况下都稳定,
* 用来常驻放「必须有」或「随时要进」的页面(公开页关系到微信审核、测试页关系到开发联调)。
* 后端 `miniprogram_pages` 只负责「登录后**还**能看到什么」,在首页以**分类段**追加在其后。
*
* 筛选条件:`auth === 'public'` **且** `isEntryVisible(page)`
* (与「后端菜单」共用同一可见性口径,避免两个来源规则不一致)
* 筛选条件:`common === true`(**显式声明,不设置即不进**)**且** `isEntryVisible(page)`
*
* ⚠️ 当前清单里只有 `pagesA/demo/public`(示例页)。
* 以后新增公开业务页(如公告页),只要在 `PAGE_REGISTRY` 里标 `auth: 'public'`
* 且不设 `hidden`,就会**自动出现**在这里,无需改本文件。
* 若一个满足条件的页面都没有,首页会渲染 §3.5.1 的统一空态文案,而不是白屏。
* ⚠️ `auth: 'public'` 的页面请一并标 `common: true`,否则未登录时首页没有任何入口
*(微信审核要求「未登录也要能看到内容」)。
*/
export const LOCAL_PUBLIC_ENTRIES: EntryLeaf[] = PAGE_REGISTRY.filter(
(page) => page.auth === 'public' && isEntryVisible(page)
export const LOCAL_COMMON_ENTRIES: EntryLeaf[] = PAGE_REGISTRY.filter(
(page) => page.common === true && isEntryVisible(page)
).map((page) => ({
kind: 'leaf' as const,
key: page.key,
@ -218,26 +216,48 @@ export interface EntrySection {
leaves: EntryLeaf[]
}
/**
* `toSections()` / `toHomeSections()` 的可选项
*/
export interface ToSectionsOptions {
/**
* 无分组叶子的兜底段标题(默认「其他」)
*
* 仅当结果里**确实有分组**时才会用上 —— 全是散落叶子时保持无标题,
* 避免首页在「只有散落叶子」这种形态下凭空多出一段标题。
*/
looseTitle?: string
}
/**
* 把入口树拍平成「一层分组」,供页面直接 `v-for` 渲染
*
* - 分组节点 → 一个带标题的 section(「分组标题 + 子项九宫格」里的标题)
* - **连续的**顶层叶子 → 合成一个无标题 section(避免每个叶子各占一行)
*
* 首页与「我的」共用它,保证两处渲染口径一致。
* - 分组节点 → 一个带标题的 section(「分类标题 + 子项九宫格」里的标题)
* - **连续的**顶层叶子 → 合成一个 section;若同时存在分组则带上兜底标题,
* 否则无标题(避免每个叶子各占一行 / 避免凭空多标题)
* - 分组子项为空 → 整组丢弃
*/
export function toSections(nodes: EntryNode[]): EntrySection[] {
export function toSections(nodes: EntryNode[], options: ToSectionsOptions = {}): EntrySection[] {
const { looseTitle = '其他' } = options
const sections: EntrySection[] = []
let loose: EntryLeaf[] = []
const hasGroup = nodes.some((node) => node.kind === 'group' && node.children.length > 0)
const flush = (): void => {
if (!loose.length) return
sections.push({ key: `loose-${sections.length}`, title: '', leaves: loose })
sections.push({
key: `loose-${sections.length}`,
title: hasGroup ? looseTitle : '',
leaves: loose
})
loose = []
}
for (const node of nodes) {
if (node.kind === 'group') {
// 空分组直接丢弃,避免渲染出一个没有子项的标题
if (!node.children.length) continue
flush()
sections.push({ key: node.key, title: node.title, leaves: node.children })
} else {
@ -248,3 +268,39 @@ export function toSections(nodes: EntryNode[]): EntrySection[] {
return sections
}
/** 首页本地列表的段标题(= `PageMeta.common` 选出来的那一组) */
export const COMMON_SECTION_TITLE = '常用功能'
/**
* 首页入口分段 = **本地「常用功能」段** + 后端菜单段
*
* 形态完全一致(都是「标题 + 子项九宫格」),并排展示;
* 差别只在来源:前者前端写死、后者由 `user.info` 的 `menus` 驱动。
*
* - 本地段固定**在最前**:它是每个用户都有的固定入口,位置不该被后端配置左右
* - **去重**:本地列表里已有的 key 从后端段中剔除(否则「测试页」会同时出现在两处)
* - 本地段为空(没有页面标 `common: true`)时不渲染它
*
* 未登录时 `nodes` 为空 ⇒ 结果就是纯粹的「常用功能」,正好担当「未登录可浏览内容」。
*/
export function toHomeSections(
nodes: EntryNode[],
options: ToSectionsOptions = {}
): EntrySection[] {
const sections: EntrySection[] = []
const localKeys = new Set(LOCAL_COMMON_ENTRIES.map((leaf) => leaf.key))
if (LOCAL_COMMON_ENTRIES.length) {
sections.push({ key: 'common', title: COMMON_SECTION_TITLE, leaves: LOCAL_COMMON_ENTRIES })
}
for (const section of toSections(nodes, options)) {
const leaves = section.leaves.filter((leaf) => !localKeys.has(leaf.key))
// 整段都被本地列表覆盖 → 不渲染空标题
if (!leaves.length) continue
sections.push({ ...section, leaves })
}
return sections
}

View File

@ -41,6 +41,18 @@ export interface PageMeta {
tabBar?: boolean
/** 是否不进导航入口(九宫格 / 功能菜单):可被跳转,但不作为入口展示 */
hidden?: boolean
/**
* 是否进首页**本地**「常用功能」列表
*
* - **必须显式写 `common: true` 才会进**(不设置 = 不进)
* - 该列表在 `router/entries.ts` 的 `LOCAL_COMMON_ENTRIES`,**与后端菜单无关**:
* 不受登录态 / 授权 / 接口故障 / 后端是否配置影响 → 用来常驻放测试页、公开页这类页面
* - 后端 `miniprogram_pages` 只负责「登录后**还**能看到什么」,
* 在首页以**分类段**(如「外仓商品」)追加在「常用功能」之后;两处重复的 key 会自动去重
*
* ⚠️ `auth: 'public'` 的页面建议一并标 `common: true` —— 否则未登录时首页可能一个入口都没有
*/
common?: boolean
}
export const PAGE_REGISTRY: PageMeta[] = [
@ -100,8 +112,9 @@ export const PAGE_REGISTRY: PageMeta[] = [
path: 'pagesA/demo/public',
title: '公开示例',
icon: 'info-circle',
auth: 'public'
// 不设 hidden → 未登录时会自动出现在首页九宫格(LOCAL_PUBLIC_ENTRIES)
auth: 'public',
// 未登录也必须有可浏览内容(微信审核要求)→ 常驻首页「常用功能」
common: true
},
{
key: '/demo/required',
@ -117,15 +130,30 @@ export const PAGE_REGISTRY: PageMeta[] = [
path: 'pagesA/test/index',
title: '测试页',
icon: 'grid',
auth: 'required'
// 不设 hidden → 登录后由后端菜单(wms_permission id=627)下发生效,出现在首页「常用功能」
auth: 'required',
// 常驻首页「常用功能」:不依赖后端菜单 / 授权,开发联调随时能进
common: true
// 不设 hidden → 登录后后端菜单(wms_permission id=628)也会下发;
// 与本地列表重复,首页会自动去重(只显示一次)
},
// ─────────────── 业务页(分包):待页面文件就绪后再启用 ───────────────
// ⚠️ pagesA / pagesB / pagesC 目前只有 .gitkeep 占位,**先不登记**:
// ─────────────── 业务页(分包)───────────────
{
key: '/external-stock/list',
path: 'pagesA/external-stock/list',
title: '外仓商品',
icon: 'bag',
auth: 'required'
// ⚠️ 后端 wms_permission 里这条记录的 path(type='miniprogram_pages')
// 必须与上面的 key **逐字符相等**,否则入口会被忽略并进 permissionStore.missing
// 不设 hidden → 登录后由后端菜单下发才出现,首页以「外仓商品」**分类段**展示
// 未设 common → 不进本地「常用功能」(它属于后端菜单那一侧)
}
// ─────────────── 待启用(页面文件就绪后再登记)───────────────
// ⚠️ pagesB / pagesC 目前只有 .gitkeep 占位,**先不登记**:
// 登记了 pages.json 里没有的页面 = 用户点进去必然失败。
// 启用步骤:① 建页面文件 → ② 注册到 pages.json 的 subPackages → ③ 打开下面的注释。
// { key: '/inbound/list', path: 'pagesA/inbound/list', title: '入库', icon: 'bag', auth: 'required' },
// { key: '/outbound/list', path: 'pagesB/outbound/list', title: '出库', icon: 'car', auth: 'required' },
// { key: '/stocktaking/list', path: 'pagesC/stocktaking/list', title: '盘点', icon: 'list', auth: 'required' },
// { key: '/inventory/list', path: 'pagesC/inventory/list', title: '库存查询', icon: 'search', auth: 'required' }

View File

@ -52,8 +52,10 @@ export const usePermissionStore = defineStore('permission', {
/**
* 用 `user.info` 的 menus 重建入口树
*
* 后端当前尚未配置 `miniprogram_pages`(0 条)→ `entries` 会是空数组,
* 这是**预期行为**:UI 回退到本地公共入口 + 空态文案,不报错。
* 后端 `miniprogram_pages` 已开始配置(测试页 628 + 外仓商品分类 630 / 页面 631):
* 命中本地 `PAGE_REGISTRY` 的项成为入口,未命中的进 `missing`(只告警不报错)。
* 若当前角色未授权这些节点,`entries` 会是空数组,这是**预期行为**:
* UI 回退到本地公共入口 + 空态文案,不报错。
*/
loadFromMenus(menus: MenuNode[] | null | undefined): void {
const { entries, missing } = generateEntries(menus)

21
src/utils/gateway.ts Normal file
View File

@ -0,0 +1,21 @@
/**
* `/system` 网关的公共入口与 query 参数
*
* 后端所有业务方法都打同一个网关,方法名放 query 的 `method`,配 `v`(接口版本)与
* `timestamp`;业务参数放 body:
*
* ```
* POST {base}/system?method=stock.warehouse.externalList&v=1.0&timestamp=1690000000000
* ```
*
* 与 new3(Web 端)完全一致 —— 抽到这里是为了让 `api/**` 各模块共用一份,
* 避免每个模块各写一遍(写错一处就多一个「method 名不对 → 500」的坑)。
*/
/** /system 网关统一入口(相对 `VITE_APP_BASE_API`) */
export const SYSTEM_URL = '/system'
/** 构造 /system 网关的公共 query 参数(method + v + timestamp) */
export function gatewayParams(method: string): Record<string, any> {
return { method, v: '1.0', timestamp: Date.now() }
}

View File

@ -0,0 +1,438 @@
# 「我的」页 · 页面分类入口改造 —— 分析与下一步任务清单
> **状态**:决策已定(**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 前端渲染链路
```mermaid
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'`)逐字符一致<br>② `path` **必须**与 `pages.json` 一致<br>③ 只登记真实存在的页面 |
| `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`;<br>**B** 沿用 web「根绝对 + 子相对」:631 → `external_stock`,前端 `entries.ts` 增加父路径拼接 | **A**:`entries.ts` / `pages.ts` 都不用动,只改 DB 两个字段值(B 需改公共代码并回归首页) |
| **D2** | **无分组叶子的兜底分类** | **A** 前端兜底:`toSections()` 按分类分段 + 未分类段;<br>**B** 后端补一个分类父节点把 628 收进去 | **A**:已实现(仅当结果里**确实有分组**时才给散落叶子加标题「其他」,全是散落叶子时仍无标题,首页不会凭空多一段) |
| **D3** | **「我的」页渲染形态** | **A** 一张「功能」卡内多段(段标题 + 九宫格);<br>**B** 每个分类一张独立卡 | **A**:「全部功能」卡内多段,与首页共用 `toSections()` + `entry-sections` 组件 |
| **D4** | **首页 vs 我的 的关系** | **A** 两页相同;<br>**B** 「我的」= 全部,「首页」= 常用 → 本地 `common?: boolean`;<br>**C** 后端新增 `type='miniprogram_common'` | **B**:`PageMeta.common`(默认 `true` = 常用);首页 `onlyCommon: true`,「我的」不过滤。**当前把「测试页」设为 `common: false`**(排障页不占首页格子) |
| **D5** | **「我的」页未登录时的入口区** | **A** 整块隐藏,只留头部登录引导;<br>**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**(如需恢复原样):
```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:
```sql
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 缺失
---
## 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`):
```powershell
npm run check:pages # 注册表 × pages.json 一致性
npm run type-check # vue-tsc
```
> ⚠️ 跑 `dev:mp-weixin` 前先确认**没有另一个编译进程在跑**(两个进程写同一 `dist` 会写坏产物,报 `common/assets.js` 缺失)。
**SQL(复查数据,只读)**:
```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)