仓储首页看板口径.md 44 KB

仓储首页看板口径

依据 2026-10-22 的 V2.3/V2.4 变更记录实施;随附文档虽然标为 V2.2,正文中旧版的六卡、库位地图和五类动态说明不再适用。

  • 首页为四格单行待办、四张 KPI(编号 01、02、03、04)、近 30 天出入库柱状与净趋势、分类横条,以及库龄环图、预警 TOP5、四类最近作业动态。质检通过率卡片已删除,C6 仍供质检明细页使用。
  • 仓库筛选只用已授权仓库,默认全部授权仓库;首页不再有「基本单位」筛选(请求入参 unit 与筛选项里的单位列表、默认单位均已删除),库存数量跨基本单位汇总为单一数值。库存数量、分类、库龄均扣锁。
  • 库存总量、库存金额及库存分类分布的“查看台账”和图表点击均打开现有 /warehouseManagement/stockLedger 列表;首页不再提供自建台账明细视图。分类横条点击会带 categoryLevelId(分类层级 id)打开台账并预选左侧树节点,口径见 D2。
  • 呆滞占比按批次数,不按金额;库存周转按数量快照计算并剔除调拨出库。C2 没有核实的移动加权不含税成本源时显示“—”,切勿把入库价估值当成账面金额。
  • 库存总量卡片的「较上周」=本期数量 − 7 天前日末同刻快照(后端 weekOverWeekQuantity/comparisonBaseAt;weekOverWeekUnit 已删除),数量跨基本单位汇总,两侧快照齐全即可比;缺基准或后端未上线该字段时显示 comparisonReason(缺省“暂无上周同时点可比快照”),差值不得以 0 代替。
  • 库存数量跨基本单位直接汇总为单一数值(如 12,000 个与 3,400 kg 相加后给出一个总量),不再有卡片内分单位小计,响应里的 units 字段已删除;汇总只做数量相加,不做单位换算。
  • 锁定数量为跨基本单位汇总的单一值,不再逐单位分列;lockedQuantity 为 0 是真实零按“0”显示,为 null 表示口径缺失显示“—”。
  • 文档中 B2 计数指向出库单,但下钻指定 V14 入总库申请,两类单据数据源不同。代码暂按文档保留“待出库单”计数与 V14 跳转;待业务确认后再统一口径。
  • 安全库存预警的三色分级、缺口量/缺口金额、影响生产工单、防重复下单与超储调拨预填口径见 A1。预警可用量与其它 KPI 不同源(含待检),共享片段 batchRows/costRows 不得改动,理由写在 A1。

当前只做 Vue 模板/脚本、MyBatis XML 与差异静态校验;实际数据对账和浏览器布局仍需在有授权数据的环境核验。

D1 出入库动态图

  • 横轴窗口=近 30 天滚动窗口(含今日,共 30 天),卡片副标必须写明窗口名与起止日期,不得显示成自然月或固定周期。
  • 柱体=数量,Y 轴为跨基本单位汇总的数量;后端 /wms/index/home-summary 的 trend 只返回有作业的日期,缺的日期前端补 null、绝不用 0 冒充。
  • 无作业日=当日入库与出库都无数据;只要任一方向有数据(含真实的 0)就不算无作业日。无作业日不画柱,给浅灰 markArea 底纹,hover 提示「该日无作业」,净趋势在该日断线。
  • 净趋势=当日前端重算的「入库量 − 出库量」,紫色虚线 #9B7DF7,绑右侧第二 Y 轴「单日净差」,与左侧数量轴分开,读数不混用刻度。
  • 连续同号风险:取窗口末尾最近连续同号段(末尾无作业日跳过),>= 2 天时提示——连续为正=积压风险(橙)、连续为负=缺货风险(红);0(持平)与中间的无作业日都打断连续段,没有连续段不提示。
  • 点击柱体与无作业日都带该日 startTime=00:00:00/endTime=23:59:59 打开 V4 出入库动态;无作业日列表为空态,但日期照带。
  • 卡片右上角「查看动态 ›」跳系统菜单真实路由 /warehouseManagement/inboundRequests(出入库申请,独立页签),不是首页内嵌的 ioapp 视图、也不是自建的 V4 动态列表:HomeOverview.vue 发 $emit('navigate', '/warehouseManagement/inboundRequests', { warehouseId }),由 dashboard.vue 的 @navigate="navigate" 走 $router.push。只带当前仓库,状态/时间/页签全部交给目标页自己的默认值(search.vue 的 defaultWhere.status='' 即全部状态,默认入库页签);不得带 dashboard=1,否则会误开看板的批量收货勾选列。V4 仍由「最近作业动态 › 全部动态」、趋势柱体与无作业日、以及调拨行的「查看单据」进入,入口不丢。
  • 口径实现集中在 dashboard-utils.js:TREND_WINDOW_DAYS、trendWindowDates、trendQuantity、isIdleTrendDay、trendNetOf、buildTrendWindow、trendStreak、trendRisk,由 scripts/check-warehouse-dashboard.cjs 静态断言守护。

D2 库存分类分布图

  • 卡片副标固定写明「按物料分类 TOP8(前 7 + 其他兜底)」;只做数量口径(跨基本单位汇总),不做「数量/金额」切换。
  • 行数据来自后端 categories:{ id, name, quantity, ratio }。id 是物料分类根层级 t_main_category_level.id(字符串),可直接作为 V2 台账的 categoryLevelId;「其他」聚合行的 id 固定为字符串 'other',不是任何真实分类层级。
  • 点击非「其他」条形:HomeOverview.categorySelect(row) 发 open('stockLedger', { categoryLevelId: row.id }),dashboard.vue 的 open() 把 extra 经 cleanQuery 合并进路由 query(path 仍是 /warehouseManagement/stockLedger),台账页据此选中左侧树并过滤右侧列表。
  • 点击「其他」:只打开台账、不带分类,绝不把聚合兜底行下钻成具体物料。
  • 台账接受 query.categoryLevelId:树加载完成后在 treeList 中递归查找 id 匹配的节点,$nextTick 后 treeRef.setCurrentKey(id) 并展开祖先;current 置为 { id, data } 的形状,同时满足 item-list 的 current.id(首屏 datasource)与 current.data?.id(reload)两种读取。
  • 降级策略:树里找不到该 id(分类停用、无权限、树接口异常)时不报错、不白屏,清空选中回到台账默认的「不过滤」,并打印一条 [wms-stock-ledger] 说明日志;台账页日志前缀不得复用首页的 [wms-home]。
  • tooltip 口径:分类名 / 在库数量(恒为跨基本单位汇总的数量口径,不拼基本单位后缀;图表组件不再接收单位入参)/ 占比%,并提示「点击进入台账」;占比或数量缺失显示「—」,不以 0 冒充。
  • 断言守护:scripts/check-warehouse-dashboard.cjs 覆盖「非 other 行带 categoryLevelId」「other 行不带」「open('stockLedger', extra) 把 query 传给 router」「台账页含 categoryLevelId 处理与递归查找」「tooltip 恒为数量口径」——脚本改为禁止 DashboardChart.vue 出现 this.unit,并断言分类 tooltip 固定「在库数量:」、环形图中心副标题固定「在库总量」。

A1 安全库存预警

本节固化安全库存预警改造后的唯一口径。后端实现在 WmsHomeMapper.xml 的 alertRows 片段;前端只做归一、配色兜底与文案,不复算任何阈值。回归守卫见 scripts/check-warehouse-dashboard.cjs 的 F1 断言块。

触发条件与短路顺序

alertRows 对每个「(仓库,物料)」行按下列顺序判定,命中即停:

  1. unknown(待核实):没有唯一的有效阈值配置(缺精确仓库配置、同仓同物料存在多条、阈值或基本单位不可核实),或可用量为负(锁定量超过余额)。
  2. critical(缺料):可用量 < 安全库存 secure_inventory。
  3. warning(偏低):安全库存 ≤ 可用量 < 安全库存 × K1。
  4. excess(超储):可用量 > COALESCE(最大库存, 安全库存 × K2)。
  5. normal(正常):其余全部。
  • 系数:K1=偏低系数 wms.home.alert.warning-ratio(默认 1.2)、K2=超储兜底系数 wms.home.alert.excess-ratio(默认 3)。两者由 WmsHomeAlertRatioConfig 解析后以 Mapper 参数 #{warningRatio}/#{excessRatio} 下发,非法值回落默认并打 WARN。前端不得内置 1.2/3——写死会让改系数后前后端静默分叉。
  • 最低库存 min_inventory 只作展示列,不参与任何触发判定。用最低库存判缺料是本次废弃的旧口径,不得回退。
  • 超储兜底只在最大库存为空时生效:配了最大库存时超储线就是最大库存本身,COALESCE 的第二项不会被用到;把 K2 当成「最大库存之外再加一层」是错的。

可用量口径(与 batchRows 不同源,必须长期并存)

  • 预警可用量在 alertRows 内一个独立的 av 子查询里算:SUM(stock_count_base) − SUM(COALESCE(lock_count_base,0)),按(仓库,物料)聚合,批次过滤条件与预警行集一致。含待检、未放行批次,不套 pre_warehousing/quality_control 过滤。
  • 其它 KPI(库存总量、分类分布、库龄、周转)走 batchRows 投影的 availableQuantity,定义是 available_count_base − COALESCE(lock_count_base,0),会把未放行/待检批次减掉。
  • 为什么两套口径要并存:预警判的是「这个物料还能不能发料」,锁定量才是真实占用,未放行批次仍在库里、后续会放行,把它当成不存在会漏报缺料;库存/库龄口径回答的是「现在可动用的量」,必须排除未放行。两者目的不同,强行统一只会让一边算错。
  • 护栏:batchRows 与 costRows 片段不得改动。 batchRows 的 availableQuantity 被库存总量、分类分布、库龄、周转等四个既有消费者同时读取,costRows 是库存金额(C2)的单价定义;为了预警去改这两处,会静默改掉四个 KPI 的数字且没有任何报错。预警需要不同口径时只能新增独立子查询,不能复用或改写共享片段。
  • 单价侧相反:costUnitPriceRows(从 costRows 抽出)与库存金额共享同一定义,缺价时保持 NULL,不兜底成 0。
  • 断言:F1-(5) 直接读 WmsHomeMapper.xml,校验 batchRows 的 available_count_base-COALESCE(b.lock_count_base,0) 与 alertRows 的 SUM(...)−SUM(...) 同时存在,且 alertRows 内不得出现 available_count_base(出现即意味着预警复用了排除未放行的口径)。

缺口量与缺口金额

  • 缺口量 gapQuantity = GREATEST(安全库存 − 可用量, 0),只在 critical/warning 行有意义,其余状态为 0。
  • 缺口金额 gapAmount = gapQuantity × 移动加权不含税单价(单价取 costUnitPriceRows,与库存金额同源)。
  • 缺价语义:单价不可用时 gapAmount 为 NULL 并下发 gapAmountReason,前端显示「金额待补价」且打一条去重日志,绝不用 0 冒充——0 会被读成「缺口不值钱」,直接误导补货优先级。真实 0 照实显示 0.00 元;底层格式化层对缺失给「—」、对 0 给 0.00。
  • 行文案统一由 alertGapText 生成:缺口 <数量><单位> / <金额>,缺价/缺口量缺失分别落到「金额待补价」与「—」。

排序与 TOP5

  • 预警列表与首页卡片共用同一条 ORDER BY gapAmount IS NULL, gapAmount DESC, FIELD(status,'critical','warning','excess','normal','unknown'), id:缺口金额倒序、缺价行(NULL)排最后、再按状态严重度、最后 id 稳定收尾(分页时同额同状态的行不会跳位)。显式写 gapAmount IS NULL 是为了让排序意图不依赖 MySQL DESC 的隐式 NULL 规则。
  • 首页卡片只展示前 ALERT_TOP_LIMIT = 5 条;超出部分由 buildAlertRows 返回 overflow 并在控制台 warn 一次,total 仍是后端原始条数,右上角「全部 N 项」取 alertCount。
  • 前端不重排:dashboard-utils 的比较器只用于核对后端顺序、偏离时 warn,不改变渲染顺序——清单是分页的,页内重排会让「第 2 页第一条」错位。

影响生产工单

  • 口径:预警物料作为 BOM 子件,经 BOM 主表/明细关联到成品,再关联 t_mes_work_order;未完工定义固定为 deleted=0 AND status IN (4 待生产, 5 生产中, 7 已延期),已完工(6)/待下达(8)/暂停(9)/终止(10) 都不算影响生产,不得放宽。
  • 汇总条 alertWorkOrderCount=全部缺料(critical)行关联工单跨行去重后的计数(同一张工单被多个缺料物料影响只算一张);算不出时为 null + alertWorkOrderCountReason,前端显示「—」并给原因,绝不当 0。
  • 行级 workOrderCount 用 CASE WHEN status='critical' THEN ... END:非缺料行为 NULL 而不是 0(0 会被读成「确定没有工单受影响」)。
  • 下钻:点「影响生产工单」按 level=critical 打开缺料清单,保证数字与清单同源。

已生成申请(防重复下单台账)

  • 行级 purchaseRequestCode/purchaseRequestId 来自 t_wms_dashboard_command(command_type='PURCHASE',command_key = warehouseId:categoryId),business_id 用 CAST AS CHAR——大整数不得进 JS number。
  • 列表侧 detail.vue 的 alertActionOf 优先级:unknown→「核对阈值」(不给补货入口,阈值不成立时补货只会被后端拒绝);excess→「发起调拨」;有 purchaseRequestCode→「打开采购需求」,绝不出现「生成采购申请」;critical/warning 且无单号→「生成采购申请」;normal→不给动作。
  • 弹层侧 DashboardActions.vue 的 purchaseLocked 三重拦截:数量输入禁用、提交按钮禁用并改文案「已生成申请,禁止重复提交」、submit 内再拦一次并打 [wms-home] warn;后端 hasReplenishmentAlert 与新缺料口径同源,是最后一道。

超储调拨预填

  • 超储行的闭环是把多的调给缺的:目标仓库=缺口最大的缺料行所在仓库(只认 critical/warning,按 gapAmount 降序、缺价行最后,再按 gapQuantity 降序),目标库区=该仓第一个启用库区,并显式标注「默认库区,请核对」。
  • 无缺料行时目标仓库与库区留空并给提示,不拿超储行自己的仓库/库区冒充目标。

补货与阈值弹层

  • 补货默认数量=positiveQuantity(row.gapQuantity):非正数留空,不得用安全库存或最大库存冒充缺口量。
  • 阈值弹层:最高库存非必填,留空提交 maxInventory: null;后端 insert/update 均 jdbcType=DECIMAL 无条件写,留空写 NULL(为空即走 ×K2 兜底)。

汇总数字口径

  • alertCount 只含 critical + warning + excess;alertUnknownCount 单列且不计入 alertCount(卡片显示「待核实 X 项(不计入 N 项)」)。
  • alertGapAmount = Σ gapAmount;全缺价时后端给 null + alertGapAmountReason,前端显示「—」。
  • 前端不用可见行数自算合计:自己加总只能得到「当前可见行」的合计,与清单页条数、缺价排除规则立刻分叉。F1-(1) 用「alerts 给 3 行但 alertCount 为 null → 显示「—」而不是 3」守住这条。

上线前必须核对的数据库前置项

  • t_main_category_wms.max_inventory 必须允许 NULL。本口径依赖「最大库存为空 → 按安全库存 × K2 兜底」;列若是 NOT NULL,留空保存会直接失败,超储兜底这条分支永远触发不到。
  • 本会话无数据库连接,该列的 NULL 属性未能在本环境验证,上线前必须在目标库核对:

    SHOW COLUMNS FROM t_main_category_wms LIKE 'max_inventory';
    
  • 判读:Null 必须是 YES。若为 NO,先做列可空迁移——用 SHOW CREATE TABLE t_main_category_wms 取现有精度与注释后,再执行形如 ALTER TABLE t_main_category_wms MODIFY COLUMN max_inventory DECIMAL(24,4) NULL COMMENT '最高库存,为空表示未配置(超储判定按安全库存×K2 兜底)'; 的变更,否则「留空保存」整条不可用。

  • 顺带核对:secure_inventory/min_inventory 的存在与可空性(阈值缺失会落到 unknown);t_wms_dashboard_command 上 (tenant_id, command_type, command_key) 是否有可用索引(防重复下单的查询走这条路)。

断言守护清单

F1 断言块覆盖:statusLabel/color 优先级与三色兜底(normal 不造色)、缺价「金额待补价」而 0→「0.00 元」、TOP5 截断与 overflow、状态不复算、汇总条全 null→「—」且不自算合计、alertActionOf 五分支(含「有单号绝不出现生成采购申请」「unknown 不给补货入口」)、卡片模板守卫(三色点、影响生产工单、已生成申请、金额待补价)、screens.alerts 文案守卫(含待检/偏低系数/超储兜底,且不得再出现「排除未放行」)、后端 SQL 静态守卫(critical 判定行不得引用 minInventory、必须用 secureInventory、K1/K2 走参数、gapAmount DESC、batchRows 与 av 子查询两条护栏)。后端仓库不在同级目录时该组打印 SKIP 并说明原因,不判失败。

E3 最近作业动态

本节固化首页「最近作业动态」卡片的唯一口径。数据由 /wms/index/home-summary 的 activities 下发,取数在后端 WmsHomeMapper.xml 的 recentActivities(WmsHomeMapper.xml:226-248),前端归一在 dashboard-utils.js 的 E3 段(dashboard-utils.js:597-925),模板在 HomeOverview.vue 的 feed 块(HomeOverview.vue:118-157)。

聚合范围与数据来源

  • 只聚合四类:入库单、出库单(同为 activityType=io,按 direction 1/2 区分,dashboard-utils.js:767-773)、调拨单(activityType=transfer)、盘点任务(activityType=inventory,取自 t_wms_plan_order,WmsHomeMapper.xml:240-246)。入/出/调拨行来自 ioRows 共享片段(WmsHomeMapper.xml:177-202)。后端没给的类型不许在前端补一条。
  • 「旧版五类动态说明不再适用」是本文件开头第 3 行的既有结论(「正文中旧版的六卡、库位地图和五类动态说明不再适用」)。含义有两层:不许按旧口径补第五类(质检、审批之类),也不许把旧五类的取数沿用过来;四类就是当前契约。
  • 调拨的识别写在 SQL 里(WmsHomeMapper.xml:235-236:出库方向 biz_type=2 或入库方向 biz_type=15),前端只认后端给的 activityType,不得自己按 businessType 再猜一遍——两套判据迟早分叉。
  • 时间窗:盘点分支只取近 30 天(WmsHomeMapper.xml:246),入/出/调拨沿用 ioRows 的 30 天滚动窗(WmsHomeMapper.xml:196-197),刷新时由服务层清空 startTime/endTime 免得被首页筛选改写(WmsIndexServiceImpl.java:1547-1550;请求入参 unit 已随后端契约删除)。

已知限制:定义里的部分状态在当前契约下不可达

  • ioRows 把「已完成」硬编码成主单审核通过(AND o.verify_status=2,WmsHomeMapper.xml:190)。该片段同时被 D1 趋势(WmsHomeMapper.xml:221)、V4 明细 io 页签(WmsHomeMapper.xml:817)、E3(WmsHomeMapper.xml:237)共用,是「已完成」的唯一定义点(WmsHomeMapper.xml:166-171)。因此入/出/调拨行恒为「已完成/绿」(dashboard-utils.js:748-749),盘点只有 status 0/1/2 → 待执行/进行中/已完成(dashboard-utils.js:740-744)。
  • 结论:状态定义里的「待质检/待审批/已驳回」以及「超时角标」在当前契约下不可达。 它们只存在于色表(dashboard-utils.js:611-618)与兜底分支(dashboard-utils.js:751-756),而兜底只在后端新增了未识别 activityType 且同时下发中文状态词时才生效。今天唯一可能被标超时的行是盘点 status=0「待执行」(dashboard-utils.js:829-830)。
  • 前端已做前向兼容:状态词表 + neutral 中性回落(dashboard-utils.js:608-619、621-626),后端一旦扩展取数即可直接生效;但不得为了凑出橙色/红色在前端伪造状态——伪造的「待审批」会让用户去催一个不存在的审批,比不显示更糟。
  • 未来若要覆盖这些状态,必须新增 E3 专用查询,绝不能改 ioRows。 动共享片段等于静默改掉 D1 的柱子和 V4 明细的数字,且一条报错都不会有;同理调拨剔除只能留在 trend 语句(WmsHomeMapper.xml:212-213),不能下沉进片段。

四段结构与对应纯函数

  • ①时间(formatActivityTime,dashboard-utils.js:711-720):今日 今日 HH:mm(:717)、昨日 昨日(:718)、更早 MM-DD(:719);时间非法或缺失一律 —(:713)并排到最后(:872),绝不用「现在」兜底——那会把一条陈年流水顶到列表最前面。hover 给完整时间(activityTimeTitle,:724-730)。
  • ②单据类型与单号(activityDocTypeOf,dashboard-utils.js:762-775;模板 HomeOverview.vue:142-151):类型名固定「入库单/出库单/调拨单/盘点任务」,未识别回落「作业单」而不是猜成四类之一(猜错会让用户点进错误的单据类型);单号缺失显示「单号待核实」(HomeOverview.vue:150)。单号段单独可点,用 @click.prevent.stop(HomeOverview.vue:148)——少了 .stop 会冒泡到整行的 @click(HomeOverview.vue:138),一次点击触发两次下钻。
  • ③动作描述(activityActionTextOf,dashboard-utils.js:785-815):按类型套模板,见下一节。
  • ④状态(activityStatusOf,dashboard-utils.js:737-757):渲染在 HomeOverview.vue:153,超时角标同格追加。

动作描述模板的两条硬约束

  • 盘点行不得渲染数量。 后端盘点分支把 itemCount 写成占位常量 1(WmsHomeMapper.xml:241,该行第 4 个投影值),它既不是盘点明细行数也不是盘点数量;当数量渲染会得到「盘点 1 项」这种伪造数字。前端对 inventory 直接返回 null(dashboard-utils.js:691),盘点只拼「盘点 · 库区(· 进度 xx%)」(:798-814)。盘点行的 description 是状态词(服务层按 status 拼「已完成/执行中/待处理」,WmsIndexServiceImpl.java:1576-1578),属于第四段,绝不能当动作文案(dashboard-utils.js:793-796),否则一行会读成「单号 → 已完成」。
  • 数量缺失不写「0 项」,进度为 0 或缺失不拼「0%」。 activityItemCount 只认有限且 >0 的数(dashboard-utils.js:688-694),activityProgressOf 对 0、负数、非数字一律返回空串(:699-707)。0 会被读成「这一单没有任何明细」「一点都没做」,与「不知道」是两件事;与 C2 缺价、E1 unknown 同一条铁律——不可核实就省略,绝不用 0 冒充。

状态着色

  • 五档:done 绿 / waiting 橙 / doing 青 / danger 红 / neutral 灰(dashboard-theme.scss:155-159,基础色见 :142-144)。文案与颜色解耦:颜色只认 ACTIVITY_STATUS_STYLES(dashboard-utils.js:608-619),改配色不用改文案,模板里也不许判业务状态。
  • neutral 的用途:未识别状态的兜底,文案「状态待核实」(dashboard-utils.js:625-626)。为什么不能用 done 或 waiting:done 是绿,会被直接读成「已完成」这个业务结论;waiting 是橙,会被读成「在等谁处理」,还会被套上超时角标(:829-830),等于替后端凭空造出一个待办。灰只表达「这里有个状态,前端不认识」,与 E1 库龄 unknown、F1 预警「待核实」是同一种视觉语言;样式见 dashboard-theme.scss:159。
  • 推导规则(唯一来源,组件与模板不得再内联判断):盘点按 status 0/1/2 → 待执行/进行中/已完成(dashboard-utils.js:740-744);调拨恒「已执行」done(:748);出入库恒「已完成」done(:749)。
  • 必须先按 activityType 分流再判 status。 io/transfer 的 status 恒为 NULL(WmsHomeMapper.xml:234),而 Number(null) === 0,先判 status 会把「已完成」显示成「待执行」(dashboard-utils.js:735-736)。未识别的类型或状态值只 warn 一次并回落中性灰(:745-746、:750、:756),不得静默当成 done。

超时角标

  • 只有两条同时成立才标:状态是橙色「待*」(tone === 'waiting')且事件时间早于 now−24h(buildActivityItem,dashboard-utils.js:827-830);阈值 ACTIVITY_OVERDUE_HOURS = 24(:603)。
  • 24 小时与待办条同源:待办条的 overdue 就是 DATE_ADD(a.create_time, INTERVAL 24 HOUR) < NOW()(WmsHomeMapper.xml:509,入总库申请分支同式 :532;盘点行固定不标,:558)。不许在 E3 另立 12h/48h——同一屏上的两个「超时」不能是两个定义。
  • done / doing / danger 不标(dashboard-utils.js:827):绿/青/红套「超时」没有业务含义,别给已完成的单据戴超时帽子。
  • 纯函数计算、幂等:由 operateTime 与 now 现算(:828-830),重复求值不会因为「已经标过一次」而漂移;不得做成「标一次就记住」的有状态标记。

排序、条数与去重

  • 去重:同一单据(orderId,缺失回落 id,两者都没有用行下标兜底)只留事件时间最新一条(buildActivityFeed,dashboard-utils.js:853-867);同刻不覆盖(:865-866)。后端已做 GROUP BY orderId(WmsHomeMapper.xml:238),但前端不能假设这个口径永远不变。
  • 排序:事件时间倒序;同刻按行 key 倒序(dashboard-utils.js:868-879),因此顺序确定、可复现——稳定排序才能让刷新后行不跳位。解析不出时间的行排最后(:872)。
  • 条数:默认 5 条(ACTIVITY_LIMIT = 5,dashboard-utils.js:601;前端截断 :880;后端 LIMIT #{q.limit} 取同一值,WmsHomeMapper.xml:247 与 WmsIndexServiceImpl.java:1546)。双保险的理由:前端还要按 orderId 再去重一次,去重后条数可能变少;后端口径若调整也可能变多,只靠后端 LIMIT 保不住「卡片正好 5 条」这个视觉契约(:598-600)。多出来的条数进 overflow(:881),不静默丢弃。
  • 「全部动态 ›」下钻 V4 出入库动态:HomeOverview.vue:128 发 open('io'),dashboard.vue:84-101 落到 io 屏(dashboard-screens.js:8)。整行与单号点击走 openActivity(HomeOverview.vue:701-705)→ dashboard.vue:214-216 按 activityType 分流:盘点→盘点工单详情、调拨→V4 带单号、io→入/出库单据详情;缺 orderId 时提示核实,不许硬跳到列表首页。

刷新与高亮

  • 30 秒轮询:dashboard.vue:170 的 setInterval(() => this.refreshPart('activities'), 30*1000),只刷 activities 这一片,不整页重算(:164-172)。
  • 新事件只加 is-new 类做 3 秒渐隐(HomeOverview.vue:135 + dashboard-theme.scss:162-163),JS 只负责到点摘类(HomeOverview.vue:679-682)。不移动 DOM、不调用任何滚动 API:30 秒轮询里主动 scrollIntoView/scrollTop 会把用户正在看的位置顶走(HomeOverview.vue:668-669、dashboard-theme.scss:160-161)。
  • 首屏不整屏高亮:diffActivityIds 在 prev 为空(首次加载)时返回空数组(dashboard-utils.js:919),HomeOverview.vue:670-673 因此天然不触发——整屏闪一下等于什么都没强调。
  • 差分只按行 key 比较,绝不按数组引用(dashboard-utils.js:920-924):activities 是计算属性,每次求值都返回新数组,引用比较会让 30 秒轮询把同一批行全判成新增、整屏反复闪。
  • 连续两批新增重置定时器:HomeOverview.vue:675 先 clearTimeout 再起新的 3 秒,只保留最后一轮,避免先到的一批提前被摘掉;组件销毁时同一处清理(:685-688)。

空态

  • 无数据时固定文案「今日暂无作业动态」(HomeOverview.vue:156),禁止空白、禁止只画一个空列表;有 activityReason 时追加「 · 原因」(同处),原因由数据侧给,前端不自造。
  • 注意:后端目前不下发 activityReason(WmsHomeMapper.xml:226-248 无此列,服务层也未拼),该字段实际只在刷新失败时被写入错误信息(dashboard.vue:158、:161)。所以今天的空态基本就是这一句话,不许为它编造「网络异常」之类的原因。

排查日志清单

  • [wms-home] E3 最近作业动态已解析(dashboard-utils.js:907):模块级快照去重(:642、:902-906),只在「总条数/去重数/四类分布/待*数/超时数」任一变化时打一条;每次都打会把控制台刷满、反而看不见真实变化。
  • [wms-home] E3 最近作业动态状态未识别(:636):按「类别 + 值」去重,同一句 warn 只打一次(:631-637),是发现后端口径漂移的第一信号。
  • [wms-home] E3 最近作业动态下钻(HomeOverview.vue:703):只记 id / activityType / orderNo / direction。
  • [wms-home] E3 最近作业动态新增事件(HomeOverview.vue:677):只记新增 id 与条数。
  • 禁止打印整行数据或整包响应(dashboard-utils.js:641):日志只放聚合数字与关键字段,不 console.log(row)、不打印 summary;长列表会淹掉控制台,单号也是敏感数据。日志前缀必须是 [wms-home],其它页面不得复用。

断言守护

E3 的关键口径由 scripts/check-warehouse-dashboard.cjs 的 E3 断言块守护,写法与同文件里 D1、E1、F1 各块一致(check-warehouse-dashboard.cjs:554、:804、结尾 F1-(5) 段)。被守护的关键点:

  • 时间四段文案、「—」兜底、不得出现「现在」兜底;
  • 盘点不渲染数量、数量缺失不写「0 项」、进度 0 或缺失不拼「0%」;
  • 状态推导先按 activityType 分流再判 status,Number(null)===0 的错位必须锁死;
  • 五档 tone 与 neutral 兜底、未识别不得落成 done;
  • 超时只标 waiting 且超过 24h,done/doing/danger 不标;
  • 去重、事件时间倒序、同刻 key 倒序、5 条截断与 overflow;
  • diffActivityIds 首屏返回空、按 id 比较不按引用;
  • 模板守卫:@click.prevent.stop、is-new 类、空态文案;
  • 后端 SQL 静态守卫:ioRows 的 verify_status=2 唯一门槛、盘点分支 itemCount 常量、LIMIT 与 24h 口径。

不写死断言条数:断言块会随口径增补继续加,条数写进文档立刻过期,以脚本实际执行为准。

未验证边界

  • 浏览器实际渲染未核验:.feed-doc 是 inline-flex + text-overflow:ellipsis(dashboard-theme.scss:148),而 ellipsis 作用于块容器的行内内容,对 flex 容器里的裸文本节点({{ item.docType }},HomeOverview.vue:143)未必生效;超长单号(.feed-no,dashboard-theme.scss:149-150)在 overflow:hidden 下可能被硬切而没有省略号。当前只有静态断言,真实宽度下的表现必须在浏览器里看一眼。
  • 真实 summary.activities 数据未对账:本环境无数据库连接,四类分布、itemCount、status 的实际取值只能靠联调确认,上述推断全部来自 Mapper 与前端代码。
  • 已知次要不一致(防御性路径,当前后端不可达):activityActionTextOf(dashboard-utils.js:785-814)在 activityType=io 且 direction 既非 1 也非 2 时把动作词兜底成「入库」,而 activityDocTypeOf(:762-774)对同一情况兜底成「出入库单」并 warn 一次。ioRows 的 direction 取自 t_wms_snapshot.out_type,正常数据非空,只有历史脏值可能命中;命中时同一行会读成「出入库单 RK… · 入库 N 项」。若以后要覆盖,应让两处共用一个方向判定助手,不要各自兜底。
  • progressText 生产环境恒为空:后端 recentActivities 不下发进度字段(WmsHomeMapper.xml:226-248),前端是防御性读取(dashboard-utils.js:696-707)。因此「进度 xx%」今天不会出现,只有后端补了进度列才生效——不得为了让它显示而在前端算一个进度。

2026-11-07 按模块统计与混合单位修订

本节覆盖上文旧版“首页选单位、混合单位图表留空、本月截至昨日周转”的描述。首页默认全部授权仓库,基本单位默认取筛选项的 defaultUnit;曾使用的七模块请求已由下节 13 项首页指标请求替代,切换仓库时清空旧指标以免接口失败后显示别仓数据。库存主卡为可追溯在库批次数,数量仅在单位小计展示;混合单位下分类和库龄图按批次数,趋势按去重已完成单据数(调拨两端剔除),单一已知单位仍展示数量。库存卡下钻至台账时带仓库;盘点待办进 todo 同源清单,待我审批进协同办公仓储流程待办。

周转按上一个完整自然月展示:上月自然天数 ×(上上月末库存+上月末库存)÷ 2 ÷ 上月消耗性出库量;上月无完整日结时值留空。华泰租户 1 的 2026 年 10 月仅有 2 个成功采集日,且所有相关维度的完整标志为 0;库存金额同样因历史成本覆盖不足留空。业务侧需先补齐可核实成本及历史主库存/批次对账,方能展示完整金额与周转。详情见后端 docs/仓储管理首页重构-统计与数据核验.md 第十二节。

2026-11-07 按可见指标独立请求

上述七模块请求已由首页改为 13 个指标请求:B1/B2/B3/B4 为四项待办,C1/C2/C3/C4 为四张 KPI,D1/D2 为两张图,E1/E3 为库龄与最近作业,F1 为安全库存预警。C6 仍保留独立接口供质检明细页使用,首页不请求。接口为 /wms/index/home-summary/metric/{编号};C5 在设计中已取消。每项仅合并自身字段,首屏最多并发 4 项,单项失败不清空其他指标;5 分钟的预警与 30 秒的最近作业刷新分别只请求 F1、E3。仓储首页设计代码使用 B/C/D/E/F 编号,不能与企业运营首页的 M01~M30 混用。旧 /home-summary 仍由后端提供兼容,未使用的七模块路由已移除。前端断言脚本已核对首页 13 项请求、C6 明细请求、并发限制和失败隔离;实际账号权限、HTTP 响应及页面渲染仍须部署后回归。

前端旧整包请求函数已移除;无授权仓库时各单指标接口只回自身空值及原因。华泰 kd-aiot 租户 1 全部有效仓库只读复核:本月待入库/待出库申请均无命中,进行中且未过期盘点为 0;该范围不等同于截图账号的授权仓库。

2026-11-07 首页取消 unit 统计维度

本节覆盖上文「## 2026-11-07 按模块统计与混合单位修订」里关于首页默认基本单位、混合单位下图表退化、数量只在单位小计展示的描述;那段正文按当时事实保留,现行口径以本节为准。

  • 请求入参 unit 与响应字段 units、unitReason、chartUnit、trendUnit、weekOverWeekUnit 全部删除;home-options 的 units/defaultUnit 一并删除。首页与下钻明细都不再出现「单位」筛选控件,也不再有默认单位兜底。
  • 跨基本单位直接相加:C1 库存总量恒为单一数值(周环比同口径),D1 趋势恒为数量序列,D2 分类与 E1 库龄恒按数量统计,C3 周转天数及其较前月差值同样跨单位计算。图表不再有「批次数」退化模式,tooltip/轴名/环形图中心文案恒为数量口径(环形图中心副标题固定「在库总量」)。
  • 明细列表仍按物料自身的单位展示:dashboard-screens.js 的 unit:单位 列保留,前端只渲染后端下发的行值,不因取消筛选而压低口径。
  • home-options 的 warehouses[].name 现为「工厂名-仓库名」,前端按原样渲染,不再自行拼接工厂名。
  • 不变项:F1 安全库存预警的阈值登记单位(阈值仍按「仓库+物料基本单位」配置,前端表单字段见 DashboardActions.vue)与日结快照结构均未改动;预警行与明细行的单位列、缺口量单位后缀照旧取行数据。
  • 前端实现:dashboard.vue 删除单位筛选与默认单位整条链路;HomeOverview.vue 删除分单位小计与图表单位分支;DashboardChart.vue 删除单位入参;dashboard-utils.js 删除分单位小计构造函数;scripts/check-warehouse-dashboard.cjs 的出入库申请、D2、H1 三组断言改为断言「单位链路已不存在」。
  • 验证:formatUnitSubtotals/chartUnit|trendUnit|weekOverWeekUnit|unitReason|defaultUnit/options.units 三类 grep 全为 0;断言脚本 exit 0;git diff --check 通过。未做浏览器实渲染与后端联调。

    2026-11-09 库存总量与库存金额改台账口径(新增库存总量卡)

本节覆盖上文关于「C1 库存总量、C2 库存金额按可追溯批次 + 移动加权不含税成本」的描述中,首页卡片取值部分;后端 inventoryQuantity/inventoryValue 字段与周环比、日结快照、/wms/index/statistics、安全库存缺口金额的成本价口径均未改动,两套口径并存。

  • 首页 KPI 行改 5 卡:01 库存总量、02 在库批次数、03 库存金额、04 库存周转天数、05 呆滞品占比。前两张与第三张分别读新增字段 ledgerInventoryQuantity / ledgerInventoryValue,口径说明统一取 ledgerInventoryReason。
  • 行集与库存台账列表(GET /wms/outindetailtwo/batchPage?includePreWarehousing=true)完全一致:入库明细 out_type=1 + 入库单已审核 + 排除质检拦截 + 批次 LEFT JOIN,含预入库与零库存行;只保留租户与授权仓库过滤,不带「仓库启用 / 主库存关联有效 / 库存>0」的严条件。
  • 库存总量 = Σ 台账「计量数量」stock_count_base(含锁定)。因此与分类分布、库龄结构、呆滞占比、周转天数使用的「在库量 = 总 − 锁定」差一个锁定量,两组数字不可互校;卡片文案已写明差额来源。
  • 库存金额 = Σ(该行在库数量 × 该行单价),按 pricing_way 分支计价(1 数量、2 重量);无批次行或无单价行按 0 计入合计,未计价行数只在口径说明里披露,不把整卡置空。
  • 库存金额卡不再展示「较上周」:历史周环比基准是成本价口径的日末快照,与台账口径不可比,宁可留白也不给假环比;如后续需要台账口径周环比,须先给日结快照新增台账金额列并从上线日起累积基准。
  • 开发库 kd-aiot 租户 1(8 个授权启用仓库)实测:台账行集 113 行 / 库存总量 52,081.93 / 库存金额 2,254,201.00(未计价 57 行,均为库存>0 且无单价);同一库旧口径为 98 个可追溯批次 / 47,905.93,差额来自 15 行不满足首页严口径的台账行。
  • 断言守护:scripts/check-warehouse-dashboard.cjs 已同步为 5 卡(code 01..05、label 顺序)与「库存金额卡无 delta」契约,并新增库存总量卡的 target/unit/null 透传/reason 断言;脚本 exit 0。浏览器实渲染与后端联调仍未验证。

    2026-11-09 首页删除「在库批次数」卡(该维度业务上不存在)

本节推翻 2026-11-09「库存总量与库存金额改台账口径」一节中「首页 KPI 行改 5 卡」的顺序与编号,其余口径结论继续有效。

  • 首页 KPI 行由 5 卡收敛为 4 卡:01 库存总量、02 库存金额、03 库存周转天数、04 呆滞品占比;编号连续、不跳号,改由 src/views/warehouseManagement/index/components/HomeOverview.vue 的 kpis 决定。
  • 删除项只针对首页展示:key:'stock'(label「在库批次数」、unit「批」、value inventoryBatchCount、reason inventoryReason)整条移除,不改成「—」占位,也不把数值改挂到别的卡上。业务上不存在「在库批次数」这个统计维度,因此页面不得再出现该文案与批数口径。
  • 后端与接口未改动:GET /wms/index/home-summary/metric/C1 仍返回 inventoryBatchCount/inventoryReason(以及 inventoryQuantity 等历史字段),因为 C1 同时是剩余「库存总量」「库存金额」两卡 ledgerInventoryQuantity/ledgerInventoryReason 的唯一来源——删掉 C1 会让两张台账口径卡的口径说明被清空。首页仍按 metricKeys.C1 请求一次,多带的下行字段属既有死负载(weekOverWeekQuantity/comparisonReason/historyUnattributed 等本就无人读取)。
  • 呆滞占比不受影响:其分子分母来自 C4 的 stagnantBatchCount/stagnantKnownBatchCount,与 C1 的 inventoryBatchCount 无关,删卡不改变 3÷70=4.29% 这条既有断言。
  • 单点删除反而要防「删了又长回来」:断言脚本改为四卡契约(kpis.length===4、code 01..04、label 顺序),并把原先「key==='stock' 必须下钻台账」正向断言改成三条反向守卫(key 不存在 / label 不含「在库批次数」/ 无 unit:'批' 卡)。
  • 布局无需改样式:.kpi-row .kpi 为 flex:1 1 0,卡片数由数据决定,四卡自动均分;窄屏 calc(50% - 14px) 规则同样与卡数无关。
  • 验证:node scripts/check-warehouse-dashboard.cjs exit 0(19 行输出,含「首页指标拆分断言通过」与四卡断言);grep -rn '在库批次数|inventoryBatchCount|inventoryReason' src/ 仅剩 dashboard.vue 的 C1 字段清单一处(如上,属刻意保留);未做浏览器实渲染,未起后端联调。

2026-11-09 待我审批改为「全部未处理、不限月份」,下钻不再携带 month

  • 口径(业务 2026-11-09 拍板):卡片数字 = 当前经办人 + 入库 out_in_approve / 出库 out_approve / 调拨 wms_allot 三类流程 + 全部未处理(不限任务到达月份) + 流程实例落在授权仓库范围。计数粒度是任务条数,不是单据数(一张单据当前有多个活动节点会算多条)。
  • 为什么改:旧口径多一层「任务创建于本月」。开发库 kd-aiot(tenant=1,2026-11-09 只读核对)三类流程未处理任务 7 条全部创建于 2026-09/10,本月 0 条 —— 旧口径下卡片必然显示 0,而协同办公「流程待办」列表显示 7 条,卡片与列表必然分叉。月份过滤从来不是权限:真正的范围由「当前处理人 + 三类 key + 授权仓库」三条决定。
  • 下钻地址:仍是「当前账号菜单里流程待办入口的 path」+ ?dashboard=1&warehouseId=<看板当前仓库>,不再拼 month(键整个移除,不写成 month=undefined,避免 URL 出现空 month)。dashboard:'1' 绝对不能删:目标页 kd-aiot-frontend-wt/src/views/bpm/todo/index.vue 只有收到它才会把参数切成 warehouseScope=true,丢掉就等于跳到未按仓储范围过滤的全量待办。
  • 后端配套(同批上线,见 aiot202312 根 AGENTS.md 同日条目):WarehouseTaskApi#countTodo(List<Long>) 去掉月份入参;BpmTaskServiceImpl 的 warehouseScope 分支 month 为空即跳过到达时间过滤(key 与实例仓库两条过滤保留,显式传月仍走原严格口径,历史链接兼容);WarehouseTaskApiImpl#approve 与 WmsDashboardBatchApprovePO.month 同步放开月份,批量审批不会因任务是上月到达而报「不在当前月份」。
  • 前端改动(3 文件):dashboard.vue 的 approval-todo 分支删掉 today/month 计算与 query 里的 month;HomeOverview.vue 待办条注释第 4 条改成新口径、并把「target 只当可点击标记用(盘点/审批两张没有 target)」这句旧错描述按事实重写(四张卡都有 target,check → V5 待办单据、approve → 协同办公流程待办);WT bpm/todo/index.vue 的参数行逐字节未动(month 缺失=不限月份),只把「不在当前授权仓库及月份范围内」的提示文案去掉「月份」。
  • 判据:scripts/check-warehouse-dashboard.cjs 没有任何 approval-todo/month 的下钻断言(该脚本只断言 monthRange() 的默认筛选窗口),所以本次改动不会让它变红;实跑 exit=0。
  • 验收口径(联调环境):同一账号、同一时刻,卡片数字 == 下钻列表 total(用任务数对,不要拿单据数比);并抽一条上月到达的任务点进详情,确认能打开、能审批。
  • 未验证边界:未跑前端构建、未做浏览器实渲染;「month 缺失即不限月份」的落地依赖后端同批发布,单独发前端会让卡片按旧口径算、列表按新口径显示,两者仍会差。