kd-aiot-frontend-wms/docs/仓储首页重构实施说明.md

仓储首页重构实施说明

更新日期：2026-10-16。

首页继续嵌套在 EleAdmin 页面内容区，保留原系统菜单、页头及标签栏。仅移除看板自身重复的顶部品牌/筛选栏和左侧导航，展示用户截图红框内的数据总览。看板主内容使用内容区可用宽度并随内容增长，根节点不得使用视口级 fixed/inset/z-index 或强制系统布局全屏。保留首页卡片下钻、明细筛选和返回首页入口；仓库/单位继续从现有路由参数及接口默认值读取。此约定以用户最新确认的“嵌套在页面里面、需要之前系统菜单”为准。

页面与组件

普通及宇信首页通过 warehouseManagement/index/index.vue、common.vue、yuxin.vue 嵌套进入 dashboard.vue。三个历史入口都保留原路径，避免新增“点击首页”才能打开的独立看板路由。入口组合首页、9个统计视图、待我审批和4个原业务视图，共15个视图；首页不保留快捷新建按钮，新增单据从出入库列表进入。

文件	职责
index/dashboard.vue	路由筛选、真实请求、刷新生命周期、报表导出、业务导航及批量收货队列
index/components/HomeOverview.vue	待办、指标、图表、预警与动态展示，事件上抛到入口
index/components/DashboardChart.vue	ECharts绘图、点击下钻、尺寸适配与实例销毁
index/detail.vue、dashboard-screens.js	真实明细列、筛选、分页、操作和统计口径
index/components/DashboardActions.vue	阈值、采购需求、处置、财务登记与逐单结果
api/warehouseManagement/dashboard.js	统一鉴权请求和业务响应校验，身份保留字符串

dashboardView取值：home/ledger/dead/io/todo/age/alerts/turnover/locations/qc/flow/addin/addout/ioapp/inapp。筛选保存在路由查询中，显式空unit表示不自动选默认单位。月份初值使用本地月份完整首末日，接口以服务端规则再次校验。

首页以外的14个配套视图如下：

视图	路由值
库存台账	ledger
呆滞品分析	dead
出入库动态	io
待办单据	todo
批次库龄	age
安全库存预警	alerts
周转分析	turnover
库位地图	locations
入库质检	qc
待我审批	flow
新增入库单	addin
新增出库单	addout
出入库申请	ioapp
入总库申请	inapp

数据口径与刷新

• 使用/wms/index/home-options、home-summary、home-detail及home-alert-config，不保留原型示例数字。
• 不同基本单位不相加。库存含待检与锁定；库存总量、分类、库龄、周转等 KPI 的可用量扣锁并排除未放行（batchRows 的available_count_base−锁定量）。安全库存预警是唯一例外：预警可用量＝在库量−锁定量、含待检与未放行，走alertRows 的独立子查询，与上述 KPI 不同源；batchRows／costRows 两个共享片段因此不得改动，理由见《仓储首页看板口径.md》A1。金额按可核实入库价估值，缺价不显示为零。
• 呆滞认定要求首次入库及最近实际消耗均超过180天，占比使用呆滞估值与全部库存估值。日期或估值不足时展示原因。
• summary.capturedAt显示为“服务端查询时间”；7日前日末实际采集时间由comparisonReason说明，不能将本次接口时间当作日结时间。
• 总统计15分钟、预警5分钟、动态30秒刷新；后两类通过section=alerts/activities更新对应区块。请求序号及生命周期世代阻止旧响应覆盖新筛选；页面停用、销毁后清理定时器。
• 明细真实分页，导出沿当前筛选逐页读取。空值保留未知语义，缺日期显示“日期待核实”。

原业务链路

• 待入/出库、入总库按本月整单待办打开，默认状态0；清除首页物料、单位筛选，避免与整单计数口径冲突。入总库原API在每次查询时固定type=1，重置筛选不会混入出库申请。
• 批量收货从真实WMS申请列表选择，逐单打开原入库表单，完成原校验和包装明细组装后暂存请求，全部核对后调用/wms/dashboard/action/batch-receive。来源为/wms/applystoragedetail/listByAppIds；extInfo.dashboardApplyDetailId保留申请明细ID，采购来源sourceReceiveProductId原样保留。
• 批量收货确认期间阻止重复请求；旧表单事件必须与当前inId匹配。成功项移除，失败项保留完整请求及原requestKey供重试。成功表示保存并提交原审批或质检，库存变动仍取决于原流程。
• 库存盘点入口默认type=inventory；待审批使用真实当前任务分页及逐单审批返回值。业务身份禁止转成JavaScript数值。
• 阈值按仓库与物料基本单位配置，要求0≤最低≤安全≤最高且精度4位；历史单位不一致时提示核对。采购需求保存为EOM草稿，需在原需求详情核对并提交。
• 呆滞处置依次保存草稿、提交真实审批、执行原调拨或出库、登记独立财务凭证。驳回/撤销可重新提交；审批本身不变动库存。财务附件复用原上传组件。
• 库位用途字段为allocationPurpose=ordinary/repair/temporary/virtual，启停字段为enabled=0/1；新货位普通且启用，历史空值保留待核实。

跨系统与权限

从当前用户授权菜单解析门户同源入口。WT接收warehouseScope/warehouseId/month/taskId后，先按真实任务ID和授权范围查询，再打开原审批容器。WT新增stagnantDisposal/detailDialog.vue读取真实处置申请，submit.vue复用现有审批意见、通过与驳回处理。EOM通过requirementId打开原采购需求详情。

本地没有QMS前端项目，质检操作仅标“打开检验工作台”，传批次参数；未证明目标工作台消费这些参数，不宣称可精确打开质检报告。

WMS/WT/EOM在dashboard=1时启用深色Element主题。WMS样式限制在页面内容区及看板专用弹层：DashboardActions使用wms-dashboard-dialog，其选择框使用wms-dashboard-popper；不得直接覆盖整个body下的Element组件。系统页头部门、角色输入框及选项面板保持原白色样式。接口仍由服务端校验授权仓库及业务权限，不以隐藏前端按钮代替鉴权。

验证与验收边界

最终定向检查：WMS 22个、WT 5个、EOM 3个改动的Vue/JS/SCSS文件，模板编译、Babel脚本解析及看板Sass编译均无失败；三个前端仓库git diff --check通过。WT处置审批另用Vue实际选项合并断言，确认无独立模板的子组件继承原渲染函数、审批方法、任务参数，且后端两个组件路径均指向本地现存文件。

上述重构检查未执行完整前端构建、Maven、浏览器或设备验证，也未调用真实写接口。Sass仅出现现有旧JS API弃用提示。新增文档和断言脚本均未被忽略规则排除，未暂存或提交本次改动。

2026-10-16展示范围修正：实际本地浏览器确认首页位于.ele-admin-content内，系统菜单、页头和标签栏可见；部门、角色输入框和展开的选项面板计算背景均为rgb(255, 255, 255)。卡片进入库存台账及返回首页已验证。修正后的布局、看板及操作弹层模板和脚本解析、三份看板SCSS编译、现有业务断言和git diff --check通过；系统布局文件无最终差异。本次未执行完整构建、设备验证或真实写操作。

运行node scripts/check-warehouse-dashboard.cjs可重复验证月份边界、空值/零值、大整数身份、授权菜单路径、整单待办筛选、“其他”分组下钻、重复收货事件与失败项幂等重试；脚本直接加载现有组件方法，使用请求桩，不访问数据库。

部署前须在目标环境联调真实响应、菜单路径、弹层布局、审批模型及权限、采购草稿、批量收货审批/质检、处置执行与财务附件。日末数据需等真实采集积累，缺失历史不能用样例或补造值替代。后端表结构与模型准备参见后端项目docs/仓储管理首页重构-统计与数据核验.md及影响地图。

2026-10-16首页入口约定：本次将“白色字典背景”暂按“白色字体”处理，标题“仓储管理总览”和“下午好，xxx”使用白色字体，保留看板深色背景；库存总量、库存金额、库存分类“查看台账”及分类图点击统一跳转原库存台账/warehouseManagement/stockLedger，待入库与入库管理使用/warehouseManagement/stockManagement，待出库与出库管理使用/warehouseManagement/outgoingManagement，不进入首页自建台账或出入库列表。原系统入口不携带dashboard=1；ledger事件与stockLedger事件统一分流，避免其他统计页的“查看库存”再次进入自建台账。前文重构记录中的台账下钻约定以本条为准。原台账未读取首页分类查询参数，本次仅保证进入原页面，不宣称自动选中分类。