06 首页与动态菜单一句话职责作为 App 冷启动后的常驻「首页」Tab承载问候头、家底台账、待办聚合、公告便签、最新消息与功能中心宫格并负责按登录角色拉取/兜底动态菜单入口。入口底部 Tab「首页」MainScaffold的selectedTab home权限无独立权限宫格按后端下发的action集合决定可见性普通角色默认只给自助入口对接后端接口数MenuApi1 HomeApi1 StatsApi2 4另并行拉取的消息未读/列表、公告首页经MessageRepository/NoticeRepository端点归属 16 / 15 篇源码范围源文件一句话职责ui/main/MainScaffold.kt无 NavHost 的页内导航状态机首页HomeScreen、宫格分派onRoute、FAB 与各类覆盖层切换、底部栏显隐ui/main/MainViewModel.kt首页UiState、动态菜单加载、大盘并行刷新身份/存量/未读/消息/公告/待办domain/menu/AppMenuConfig.kt离线兜底菜单、itemsForRoles并集语义、mergeScanEntries扫码入口归一化domain/menu/MenuIcons.kt宫格图标代码 → 矢量图标 的两级兜底目录data/repository/MenuRepository.ktGET /system/menu/app拉取快捷入口失败透传data/repository/HomeSummaryRepository.ktGET /system/home/todo待办聚合data/repository/StatsRepository.ktGET /archive/stats/overview存量总览GET /archive/stats/borrow-trend借阅趋势已封装未使用data/remote/MenuApi.kt动态菜单接口定义data/remote/HomeApi.kt首页待办聚合接口定义data/remote/StatsApi.kt统计总览 / 借阅趋势接口定义data/remote/model/AppMenuVO.kt动态菜单项视图id/title/icon/action/sortdata/remote/model/HomeTodoVO.kt待办聚合借出未还 / 待审批 / 临期 / 盘点进行中data/remote/model/ArchiveOverviewVO.kt档案存量总览四类实体 电子 盒 合计1. 模块概述本模块是 App 的信息中枢与导航起点承担两块职责动态菜单功能中心宫格入口真相源是后端GET /system/menu/app按登录角色裁剪后下发本地AppMenuConfig仅为离线兜底保证老版本后端 / 离线 / 异常时 App 不白屏。宫格点击经onRoute分派到各业务页或覆盖层。首页大盘四区块问候头、家底台账、待办、公告便签加「最新消息」与「功能中心宫格」数据由MainViewModel.refreshHome()并行拉取单项失败只隐藏该项不阻塞其它模块。角色可见性宫格可见项来自后端返回或兜底配置首页顶部「扫一扫登录」与右上角铃铛常驻所有角色HOME_GRID_HIDDEN_ACTIONS固定排除notice.list/message.list/scan.login/scan.search使它们不占宫格。中央 FAB「扫码办理」仅在持有borrow.handle/borrow.scan/borrow.approve.scan之一时显示。2. 页面与状态MainUiState关键字段items宫格项、fromRemote是否后端来源、loading、realName/username/department、stockTotal/stockBox家底台账、unread、latestMessages、latestNotice/noticePublisher/noticeTime/noticeLevel、todo待办聚合、homeRefreshing。四个区块的数据来源与刷新时机区块数据来源刷新时机问候头姓名/角色/部门/未读角标本地SessionStore身份messageRepo.unreadCount()进入首页、切回首页 Tab 时refreshHome()家底台账库存档案/在库档案盒/借出未还/待我审批statsRepo.overview()total/boxhomeRepo.todo()lendOutCnt/approveCnt/dueSoonCnt同上公告便签单行条noticeRepo.page(page1,pageSize1)取首条同上功能中心宫格menuRepo.appMenu()后端或AppMenuConfig兜底load(roles)在 roles 变化时切回首页不重拉菜单只重刷大盘四态处理加载中进入时loading置 trueHomeScreen在骨架区表现为骨架/占位家底台账数字为…。空公告便签仅在latestNotice非空时渲染消息区仅在latestMessages非空时显示宫格为空时首页无功能中心极端兜底。错误单个接口失败不抛全屏错误各字段保持 null/0对应区域回落为灰显或隐藏如待办todonull时借出未还/待我审批两行显示◐ 待接口灰显槽位。无权限无专用空态缺字段即不显示对应数字。3. 数据与接口调用链MainScaffold → MainViewModel → MenuRepository / HomeSummaryRepository / StatsRepository → *Api。端点清单本篇直接覆盖的三个 Api方法路径用途关键参数GET/system/menu/app按当前登录角色返回可见快捷入口无查询参数返回ListAppMenuVO每项含action/title/icon/sortGET/system/home/todo首页待办聚合无返回HomeTodoVOlendOutCnt/approveCnt/dueSoonCnt/inventoryCntGET/archive/stats/overview档案存量总览无返回ArchiveOverviewVOpersonnelEntity/contractEntity/deviceEntity/reportEntity/electronic/box/totalGET/archive/stats/borrow-trend借阅趋势按月聚合Query(months)默认 12返回ListBorrowTrendVO注refreshHome()还并行调用messageRepo.unreadCount()与messageRepo.list(page1, pageSize20)取返回的list前 3 条作「最新消息」预览以及noticeRepo.page()其端点归属 16 消息中心、15 公告篇本篇不重复列。StatsApi.borrow-trend已在StatsRepository封装但端上没有任何 UI 消费见第 7 节。4. 关键设计决策与实现要点4.1 动态菜单多角色并集 兜底链后端GET /system/menu/app的语义是「按当前用户全部角色取入口并集并按sort升序返回」。App 侧处理MainViewModel.load调menuRepo.appMenu()成功且解析出非空mapped→ 用后端数据fromRemotetrue成功但为空数组 → 回落AppMenuConfig.itemsForRoles(roles)fromRemotefalse网络/HTTP 失败含 404走 Retrofit 抛异常被MenuRepository吞为Result.failure → 回落本地兜底fromRemotefalse。渲染前MainScaffold用AppMenuConfig.mergeScanEntries(...)归一化扫码入口再按HOME_GRID_HIDDEN_ACTIONS过滤。App 不二次排序直接按后端返回顺序渲染本地兜底itemsForRoles取并集按action去重高权限优先但不含sort排序顺序由层级常量决定。4.2mergeScanEntries的三分支规则归一化「扫码办理」入口把老后端同时下发的borrow.scan/borrow.approve.scan合并为borrow.handle分支一已含borrow.handle→ 若残留borrow.scan/borrow.approve.scan则过滤掉原样保留其余否则原样返回。分支二不含borrow.handle且borrow.scan/borrow.approve.scan只存在其一 → 不合并避免给出无权限按钮原样返回。分支三不含borrow.handle但两者都有典型 admin/leader 双权限 → 合并为borrow.handle落在原borrow.scan的位置丢弃borrow.approve.scan。4.3 宫格图标解析链MenuIcons.forItem(item) of(item.icon) ?: ofAction(item.action)两级兜底按icon代码如box映射到 Material 矢量图标代码缺失/仍是 emoji/空串 → 按action兜底如archive.search→Search仍无匹配 → 通用格Icons.Default.Apps。用矢量图标而非 emoji 的原因sys_app_menu.icon存的是代码Web 端与 App 共用同一套代码映射emoji 跨 ROM / 跨系统版本字形不一致低端机易显示成豆腐块。两级兜底保证任何取不到的图标都落到矢量图标绝不渲染 emoji。4.4 宫格点击分派与「功能开发中」HomeScreen.onRoute(item)用when(item.action)分派archive.search→开检索、各borrow.*→对应覆盖层、box.list→开档案盒、inventory.task/appraisal.task→对应页等命中else分支时弹 Toast「【标题】功能开发中」避免点出空白页。底部中央 FAB 复用「扫码办理」按navFabScanItem的 action 决定走HANDLE/VERIFY/APPROVE哪种扫码模式。4.5 待办计数字段为何用LongHomeTodoVO的lendOutCnt/approveCnt/dueSoonCnt声明为Long 0、inventoryCnt为Long? null档案总量可达十万级用Long防止Int溢出非空的Long 0默认值使后端缺字段时不触发空相关崩溃配合 UI 的?./?:兜底如todo?.lendOutCnt?.takeIf { it 0 }把 null 安全降级为「不显示角标 / 灰显槽位」而非异常。4.6 家底台账数字与大盘刷新库存档案 overview().total在库档案盒 overview().box借出未还 todo.lendOutCnt待我审批 todo.approveCnt临期提示 todo.dueSoonCnt仅 0 时在台账头显示「临期 N」。refreshHome()在load()与每次切回首页 TabLaunchedEffect(selectedTab)命中home时调用内部并行拉取身份、存量、未读、消息、公告、待办互不阻塞。5. 部署打包gradlew assembleDebugWindowsgradlew.bat assembleDebug。安装adb install -r app/build/outputs/apk/debug/app-debug.apk。必须改的配置项data/remote/Constants.kt的BASE_URL只写 host端口根路径如http://192.168.200.178/不要带/api模拟器宿主机用http://10.0.2.2:8080/。同一文件API_PREFIX经 nginx 前缀/api时填/api直连后端填。res/xml/network_security_config.xml明文 HTTP 需在domain-config加入后端 IP默认已含192.168.200.178、10.0.2.2否则 Android 9 拦截。依赖的后端能力 / 需准备的数据后端GET /system/menu/app需按角色返回action集合/system/home/todo、/archive/stats/overview可用。需在后端sys_app_menu配好各角色的功能入口sort决定宫格顺序。如需离线兜底一致后端改菜单时同步更新AppMenuConfig与MenuIcons两套代码映射。6. 验证清单6.1 后端下发新菜单后 App 不发版即可见步骤操作预期观察点前置后端 admin 给当前角色新增/调整sys_app_menu项并设好sort—后端sys_app_menu表1杀进程冷启 App登录该角色宫格出现新入口、顺序与后端一致首页「功能中心」右上角标「按角色下发」logcat 出现/system/menu/appMainUiState.fromRemotetrue2进入首页后不重启让后端改菜单仅下次冷启/重新加载菜单才变化宫格不在切 Tab 时重拉onRoute分派到新action成功落地6.2 兜底路径验证步骤操作预期观察点1临时把API_PREFIX改错或断网后登录宫格仍可用本地AppMenuConfig兜底标「本地离线配置」MainUiState.fromRemotefalse2后端对/system/menu/app返回空数组[]同样回落本地兜底首页功能中心为默认角色入口MainViewModel.load的mapped.isEmpty()分支3后端返回 404走Result.failure→ 本地兜底不白屏logcat 网络错误宫格正常显示6.3 首页大盘与待办步骤操作预期观察点前置后端archive_stats有存量数据、有借出未还单据、有待审批—后端统计表1登录后看家底台账库存档案/在库档案盒显示数字有借出或待审批时对应行显示角标「去签批 ›」overview().total/boxtodo.lendOutCnt/approveCnt2切到其它 Tab 再切回首页大盘重新并行刷新LaunchedEffect(selectedTab)命中home3临时停掉/system/home/todo借出未还/待我审批两行显示◐ 待接口灰显其余区块不受影响todonull回落分支失败排查表现象可能原因排查宫格空白API_PREFIX导致/system/menu/app404比对API_PREFIX与 nginx 前缀家底台账全是…overview接口异常或全部失败logcat 看/archive/stats/overview待办两行灰显后端无/system/home/todo或老版本检查后端是否有该端点新菜单不出现仅改了 Web 端、未改后端sys_app_menu后端菜单表是否生效7. 已知边界与未实现GET /archive/stats/borrow-trend借阅趋势已在StatsRepository封装但端上无报表页消费属已封装未使用不编造报表页。宫格点击未命中onRoute的动作一律提示「功能开发中」不跳转。本地兜底菜单不含sort排序若后端未排序兜底顺序按角色层级常量固定排列。公告便签仅取首条完整公告列表/详情走 15 公告篇的覆盖层。