11-backend-work-order-rate.md 14 KB
11: 后端执行票 —— 工单状态与处置率读模型对齐
Type: task Status: resolved Label: ready-for-agent Blocked by: 01, 06 Category: backend-execution
来源
- 决策：01 报警—工单闭环读模型与 Gogs 票拆分边界（后端切片 1）、06 异常统计、工单处置率与管理字段词汇
- 规格：10 业务语义规格
状态
已解决（2026-10-08）。诊断 + 口径修订 + 契约测试 + 提交推送全部完成；后端编译通过、Cockpit*Test 299/299 通过。提交：3de679c（本票口径修订，14 文件）+ 9380c1b（既存编译修复，1 文件）→ 已推送 origin/master（5b53a6d..9380c1b）。基线卡片：工单状态与处置率读模型。
收口拆分说明：本票的交付物（代码 + 编译 + 契约测试 + 提交 + 基线卡片登记）已全部达成，故按其自身范围 close。原「部署后真实环境复验」项已移交独立票 17 部署后真实环境复验——该项需要一次真实部署才会发生，留在本票会把「已完成的实现」与「尚未发生的部署」绑在一起，无谓阻塞下游 执行票 12 / 13。基线阶梯的 ③ 判定由票 17 推动。
范围（做什么）
- 工单状态字典对齐：Cockpit 对外字典与运行时
WorkOrderStatusEnum（0–7）逐码对齐；前端已对齐，后端对外字典与真实适配器沿用权威枚举。 - 处置率口径修订：
- 分子＝状态
5（已结案）；分母＝状态0–6工单数之和（状态7取消排除）；范围＝当前行业/片区/时间范围内的全部工单（不要求关联报警/事件）。 - 分母为
0→state=EMPTY（前端据此显示"不适用"）。 basis改为工单分母语义（如CLOSED_WORK_ORDERS_OVER_ELIGIBLE_WORK_ORDERS）；旧CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS与"状态 6 / 事件总数"口径废止。
- 分子＝状态
- 契约测试：覆盖 0–7 字典、分母含 6、状态 7 排除、分母 0、分子 5；事件/设备工单摘要与时间线的状态码一致。
非目标
- 不修改工单创建、派单、接单、处置、验收、延期、取消等操作逻辑。
- 不新增工单写接口。
验收
代码提交 + 编译 + 针对性契约测试 + 联调基线登记（按 05 真实联调基线）；本地联调通过后提交并推送到 Gogs。
| 项 | 状态 | 证据 |
|---|---|---|
| 编译 | 通过 | mvn -o -pl pipe-network-service/zksy-admin -am compile |
| 针对性契约测试 | 通过 | -Dtest=Cockpit*Test → Tests run: 299, Failures: 0, Errors: 0（提交后复跑同样 299/299） |
| 联调基线登记 | 已产出 | 基线卡片 02 |
| 代码提交 | 已完成 | 3de679c fix(cockpit): 工单处置率改为状态 0-6 工单分母口径 |
| 推送到 Gogs | 已完成 | git push origin master → 5b53a6d..9380c1b；远端 master=9380c1b 与本地一致 |
| 部署后真实环境复验 | 已移交 | 抽为独立票 17 部署后真实环境复验（本项需真实部署才发生，不再阻塞本票与下游票） |
诊断（2026-10-08）
诊断手段：只读源码核实（后端 E:\pipe-ner-server）+ 联调环境 http://192.168.110.96:8301 实测复现。
后端基线（实施前）
| 项 | 值 |
|---|---|
| 仓库 / 分支 / 提交 | http://192.168.110.30:3000/shaoy/pipe-ner-server / master / 5b53a6d |
| 远端 | origin/master = 5b53a6d（与本地 HEAD 一致） |
| 工作区 | 本票改动之前有 1 项既存未提交：CockpitFreshnessSemanticsControllerTest.java（与本票无关，未触碰） |
| 联调环境 | http://192.168.110.96:8301 实测可达，只读接口免鉴权 HTTP 200 |
| 工单字典源码 | CockpitWorkOrderStateDictionary 已在 HEAD（提交 903d44d，早于 5b53a6d） |
范围 1 —— 工单状态字典对齐：实施前已满足
CockpitWorkOrderStateDictionary（cockpit/workorder/）已公开 0–7 八态，与运行时 WorkOrderStatusEnum（ops/enums/ 与 api/enums/）逐码逐名一致（0 待派单 / 1 待接单 / 2 已接单 / 3 处理中 / 4 待验收 / 5 已结案 / 6 延期中 / 7 已取消）。实测 workOrderStateCounts 逐态回 8 行，与前端 WORK_ORDER_STATES 对齐。本票新增一条逐码比对运行时枚举的契约测试锁死该对齐，并复用该字典作为处置率口径的唯一权威来源。
范围 2 —— 处置率口径修订：实施前为旧口径，实测复现
实施前 CockpitHandlingEfficiencyService 分母传 scopeTotal = facts.size()（事件数），basis = CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS，分母 0 回 NO_EVENTS。
联调环境实测（GET /api/cockpit/v1/events/handling-efficiency）：
| 请求 | totalEvents | 分子 | 分母 | basis |
|---|---|---|---|---|
ALARM 近 31 天 |
6 | 1 | 6（事件数） | CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS |
WARNING 近 31 天 |
4 | 0 | 4（事件数） | 同上 |
关键缺陷：该 ALARM 组 stateCounts 为 0=1, 5=1（旧口径，按事件回联累加），而响应分母回 6（=totalEvents）——分母是事件数，与工单无关，口径错误被真实数据复现。注意：0=1, 5=1 只能说明「至少涉及 2 张工单」，不能推出新分母恰为 2（旧计数按事件累加、且不含未关联工单；新分母取范围内全部工单）——详见下方勘误。
同族两处（CockpitOverviewWarningSettingsService、CockpitHistoryAnalysisService）同样为事件数分母，经维护者裁定一并修订。
范围 3 —— 契约测试：实施前缺失，且旧断言锁死旧口径
原 CockpitHandlingEfficiencyControllerTest 12 例中断言的就是旧口径（value="0.2500"、denominator=8、旧 basis）。已随口径一并改写，并补足 0–7 字典、分母含 6、状态 7 排除、分母 0、分子 5 的针对性覆盖。
实施（2026-10-08）
维护者裁定（本票 grilling 轮次）：① 授权提权、本会话直接改后端工作树；② 由维护者承担负责人；③ 三处同族分母一并修订；④ 时间维度用 work_order.create_time；⑤ 扩展 snapshot 携带范围内全部工单；⑥ overview 两 family 共用全范围工单读数；⑦ 只改汇总处置率、趋势/行级保持事件桶；⑧ 状态分布改为工单口径。片区（district）过滤留给执行票 12。
后端改动（E:\pipe-ner-server，14 个源文件）
口径单源 CockpitWorkOrderStateDictionary：新增 HANDLING_RATE_BASIS、CLOSED_RATE_CODE=5、CANCELLED_RATE_CODE=7、isRateEligible(code)（0–6）；三个服务的本地状态常量改为引用该单源。
快照扩展（处置率分母来源，均不要求事件回联，按 create_time 界定窗口）：
| 快照 | 新增 |
|---|---|
CockpitHandlingEfficiencySnapshot |
scopeWorkOrders（含 stateCode / createTime / typeCode） |
CockpitHistoryAnalysisSnapshot |
同上 |
CockpitOverviewWarningSettingsSnapshot |
scopeWorkOrders（含 stateCode / createTime） |
BusinessCockpitEventAdapter 新增 devicesById 索引（工单存 device_id，需经设备解析类型）+ efficiencyScopeWorkOrders() / historyScopeWorkOrders()；BusinessCockpitOverviewWarningSettingsAdapter 新增 scopeWorkOrders()。旧构造器保留为委托重载，兼容既有调用点。
三处服务口径修订：
| 服务 / 端点 | 分母 | 备注 |
|---|---|---|
CockpitHandlingEfficiencyService（events/handling-efficiency） |
状态 0–6 工单数 | basis 改名；分母 0 → NO_ELIGIBLE_WORK_ORDERS；workOrderStateCounts 改为工单口径 |
CockpitOverviewWarningSettingsService（overview/warning-settings） |
同上 | 两 family 共用一份全范围读数；workOrderStates 改为工单口径 |
CockpitHistoryAnalysisService（events/history-analysis） |
同上 | 仅汇总处置率；小时桶与 handledCount 仍是事件口径（不同维度） |
效率端点的 linkedWorkOrderCount / missingWorkOrderCount 仍为事件回联口径（事件明细语义未变，仅不再参与分母）。
文档：docs/cockpit/README.md 第 2 节效率口径改写为新 basis 与工单分母定义，并注明历史分析小时桶 / 预警设置日趋势仍是事件桶。
验证
cd E:\pipe-ner-server
mvn -o -pl pipe-network-service/zksy-admin -am compile
mvn -o -pl pipe-network-service/zksy-admin -am test "-Dtest=Cockpit*Test" "-DfailIfNoTests=false" "-Dsurefire.failIfNoSpecifiedTests=false"
结果：编译通过；Tests run: 299, Failures: 0, Errors: 0, Skipped: 0（BUILD SUCCESS）。新增针对性用例：
dictionaryMatchesTheRuntimeWorkOrderStatusEnumCodeForCode（0–7 逐码逐名 + 8 态 +isRateEligible边界）rateDenominatorIncludesDelayingStateSixAndExcludesCancelledSeven（5/6/7/7 → 分母 2、分子 1）cancelledWorkOrdersAreExcludedFromTheRateDenominator（全为 7 → 分母 0 →EMPTY）rateIsAvailableFromWorkOrdersEvenWhenNoEventsFallInTheWindow（窗口无事件仍有处置率 → 分母与事件解耦）summaryNumeratorAndDenominatorMatchTheReportedStateDistribution（sum(0–6) == denominator自洽复算）bothFamiliesShareTheSameWorkOrderScopedRate（overview 两 family 共用）
提交与推送（2026-10-08）
| 提交 | 内容 | 文件数 |
|---|---|---|
3de679c |
fix(cockpit): 工单处置率改为状态 0-6 工单分母口径 |
14（本票全部改动） |
9380c1b |
fix(cockpit): 修复 freshness 契约测试未闭合语句导致测试模块编译失败 |
1（非本票，见下） |
推送：git push origin master → 5b53a6d..9380c1b；远端 master=9380c1b 与本地一致，工作树干净。
9380c1b 的说明：该文件（CockpitFreshnessSemanticsControllerTest.java）的改动是本次会话之前就存在于工作树的既存改动，按纪律本不该并入本票提交。但核实后发现 HEAD 中该文件末句 assertTrue(Arrays.stream(...) 缺少右括号与分号、根本编译不过，即远端 zksy-admin 测试模块原本就是坏的；若只推本票 14 个文件，远端测试模块仍无法编译。故拆成独立提交修复，并在备注中注明与本票口径无关，便于审计与必要时单独回退。
未完成项与补齐条件
- 部署后复验：联调实例运行的是已部署旧构建，本票改动只提交未部署 → 复核基线卡片 §4.1 命令，期望
basis=CLOSED_WORK_ORDERS_OVER_ELIGIBLE_WORK_ORDERS，且sum(workOrderStateCounts[0..6]) == denominator、分母 ≠totalEvents。未复验前不得宣称本票契约已在真实环境生效。
勘误（2026-10-08，本文件早先版本）：本条原写「该 ALARM 组
denominator=2、value=0.5000」，该预期是错的。那个 2 是从旧响应的stateCounts（0=1, 5=1）反推的，而旧stateCounts只统计已关联报警的工单（未关联的直接continue跳过，且按事件累加、同一工单多事件会重复计）；新口径分母取自scopeWorkOrders，含范围内全部工单（含未关联报警者）。因此部署后分母是「窗口内设备类型可映射且状态 0–6 的全部工单数」，通常不等于 2，value也随之改变。正确的复验判据是自洽性（sum(0–6) == denominator、分母≠事件数），而非某个固定数值。详见下方「诊断轮次记录」2026-10-08 勘误条。
- 前端对齐：
contractMocks.js的denominator = total（事件数）、reason: 'NO_EVENTS'与handlingRateHint()文案仍为旧口径 → 归执行票 14–16（规格 10 已把文案改动划在前端域）。
诊断轮次记录
- 2026-10-08：首轮诊断。范围 1 判定已满足；范围 2 在联调环境复现旧口径（ALARM：分母回事件数 6；当次
stateCounts为0=1, 5=1）；范围 3 缺失且旧测试锁死旧口径；识别三项阻断（后端写权限 / 负责人 / 口径边界）。 - 2026-10-08：维护者裁定八项口径问题后实施；编译通过、299/299 测试通过；产出基线卡片 02。未提交、未部署，留票不 close。deck 读写额度本轮被闸，按 决策票 06 先例回落本地 Markdown tracker 落盘。
- 2026-10-08：提交推送完成（
3de679c+9380c1b→origin/master）；提交后复跑Cockpit*Test仍 299/299。因部署实例未更新，票留committed-pending-live-verification不 close。 - 2026-10-08 勘误：早先在本票、基线卡片 02 与票 17 中写入的复验预期「ALARM 组
denominator=2、value=0.5000」错误，已更正。错误成因：该 2 由旧响应stateCounts（0=1, 5=1）反推，而旧stateCounts只累积已关联报警的工单、且按事件累加（同一工单多事件重复计）；新口径分母取自scopeWorkOrders（范围内全部工单，含未关联报警者），两者基数不同，不可互推。复验判据已改为自洽性校验（sum(0–6) == denominator、分母≠totalEvents）。本次实测复核：旧实例 ALARM 近 31 天回basis=CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS、den=6、value=0.1667，sum(0–6)=2（旧口径下的事件回联计数），确证实例尚未部署新构建。
关联
- 上位：本地票 25、Gogs #63
- 下游：执行票 12（后端回联）依赖本票
- 基线：基线卡片 02 工单状态与处置率读模型