FT546-WCS/docs/superpowers/specs/2026-07-30-wcs-real-queue-history-replay-design.md

WCS 真实队列历史离线回放测试设计

1. 背景

现有 javaTest 已具备纯内存 P0-B1 SHADOW 领域内核和 60 条人工安全场景，但人工场景不便于业务人员理解，也不能体现 FT546 现场队列的真实任务号、车辆、站点、路径和时间分布。

FT546-wcs 数据库中 dbo.wcs_srgv_queue_finish 当前包含 17,136 条四向车历史队列记录，时间范围为 2026-03-01 至 2026-07-21，涉及 3 台车、531 个起点和 484 个终点；其中 11,943 条包含非空路径。该数据量足以建立真实历史队列离线回放，但历史表没有保存每个调度周期的完整 PLC 快照、资源账本和 LEGACY 决策，因此结果不能描述为真实现场 SHADOW 验收。

2. 目标

在不修改生产模块、不写数据库、不连接 PLC 的前提下：

1. 只读提取 FT546 四向车真实历史队列记录。
2. 保留原始任务号、车辆号、站点号和路径，便于数据库回查。
3. 对全部历史记录执行数据质量、时间一致性和安全风险扫描。
4. 从路径完整记录中确定性选取不少于 200 条代表性任务，重建历史并发窗口。
5. 把历史路径转换为 SHADOW 可理解的节点和无向边资源，执行离线冲突分析与确定性回放。
6. 生成业务人员可读的表格，明确区分数据库事实、推导事实和算法结果。
7. 保留现有 60 条人工边界场景，真实历史回放作为补充而不是替代。

3. 明确边界

3.1 范围内

• 数据库只读查询。
• wcs_srgv_queue_finish 全量统计和确定性样本导出。
• wcs_srgv_map 站点存在性校验。
• 原始任务号、车辆号、站点号、路径、状态和时间保留。
• 历史任务生命周期、路径节点、无向边、并发窗口和潜在冲突推导。
• 纯内存离线 SHADOW 分析。
• JSON/CSV/Excel/Markdown 证据输出。

3.2 范围外

• 对 FT546-wcs 执行 INSERT、UPDATE、DELETE、DDL 或存储过程写操作。
• 使用当前 device_srgv 三行实时状态冒充历史 PLC 快照。
• 推断历史记录中不存在的 bootId、ACK、故障、载货寄存器或资源释放事实。
• 根据“任务最终完成”反推当时某轮调度决定一定正确。
• 现场 SHADOW、PLC 模拟器、HIL、ACTIVE 或生产验收。
• 修改 ruoyi-* 生产代码。

4. 方案选择

采用“只读导出快照＋版本化离线回放”：

FT546-wcs 只读查询
        │
        ▼
原始历史快照 JSON/CSV
        │ SHA-256、查询口径、抽取时间
        ▼
历史记录规范化
        │
        ├── 数据质量扫描
        ├── 时间窗口重建
        ├── 路径节点/无向边资源化
        └── 确定性代表样本选择
        ▼
纯内存 SHADOW 历史回放
        │
        ▼
可读报告和机器可审计结果

不采用测试运行时直接依赖数据库的方案，因为数据库内容持续变化会导致测试结果不可复现。数据库查询只负责生成带摘要的输入快照；Maven 测试只读取已固化快照。

5. 数据来源与只读约束

5.1 主数据表

dbo.wcs_srgv_queue_finish 使用以下字段：

• 标识：guid、task_no、agv_id
• 分类：task_type、priority、cargo、issued、execution_status
• 路径：start_site、end_site、the_floor、path_info
• 时间：create_date、start_date、finish_date
• 业务补充：cargo_pick_site、cargo_place_site、trun_path、up_down_site、default02 至 default08

5.2 地图校验表

dbo.wcs_srgv_map 使用：

• site_id
• x、y、z
• axy
• warehouse、space_area

地图表只用于判断路径站点是否存在和提供可读坐标，不据此自动推断交通容量、冲突资源或安全等待点。

5.3 查询安全

• 仅允许单条 SELECT 或 CTE。
• 查询账户和工具保持只读。
• 禁止存储过程、临时写表、锁表提示和破坏性并发测试。
• 每次抽取记录数据库名、表名、查询口径、抽取时间、行数和 SHA-256。
• 原始快照不得包含数据库口令、IP、Token 或连接串。

6. 历史记录规范化

新增独立历史回放包，不把数据库字段直接泄漏到 SHADOW 领域模型：

com.ft546.wcs.shadow.history/
├── HistoricalQueueRecord
├── HistoricalQueueDataset
├── HistoricalQueueNormalizer
├── HistoricalWindowBuilder
├── HistoricalPathProjector
├── HistoricalReplayAnalyzer
└── HistoricalReplayResult

6.1 字段语义

• task_no + agv_id + create_date + start_site + end_site 形成可读记录标识；guid 保留用于回查。
• path_info 按逗号拆分，去除空尾项，但不改变节点顺序。
• 路径第一个和最后一个有效节点分别与 start_site、end_site 比较并记录差异。
• create_date 和 finish_date 按固定格式解析；无法解析时标为数据问题，不伪造时间。
• start_date 为空不阻断回放，因为现有历史记录普遍缺少该值；并发窗口使用 [create_date, finish_date)，并明确标记为推导口径。
• 同一 task_no 的多条记录按时间和路径段分别保留，不擅自合并成一条物理行程。

6.2 路径资源投影

每条完整路径转换为：

• 每个路径点：NODE:{siteId}
• 每对相邻点：规范化 EDGE:{smallerSiteId}:{largerSiteId}

历史地图没有正式发布的冲突资源容量和安全点签字，因此不自动生成 CONFLICT、提升机容量或 YIELD 安全点。end_site=tsj 且路径为空的记录只参与数据质量和生命周期统计，不参与路径冲突裁决。

7. 并发窗口和样本选择

7.1 并发窗口

若两条记录满足以下条件，则视为“历史生命周期可能重叠”：

A.create < B.finish && B.create < A.finish

并发窗口是根据队列生命周期推导的候选集合，不等同于两车在同一秒真实占用对应路径节点。报告必须使用“潜在并发”“路径交集”或“离线推演”，不能写成“现场发生碰撞”。

7.2 全量扫描

全部 17,136 条记录至少检查：

• 必填标识缺失；
• 时间无法解析、完成早于创建；
• 同一车辆生命周期重叠；
• 起终点与路径首尾不一致；
• 路径节点不在地图中；
• 相邻重复节点和路径自环；
• 空路径占比和场景分布；
• 任务类型、车辆、楼层、起终点和时长分布。

7.3 代表样本

从路径完整记录中确定性选择至少 200 条：

1. 每台车均有覆盖。
2. 每种实际任务类型均有覆盖。
3. 不同楼层、路径长度和任务时长分层覆盖。
4. 包含并发窗口、共享节点、共享无向边和无冲突样本。
5. 包含同一任务号多段记录。
6. 固定排序和选择规则，重复抽取产生相同样本。

若某类真实数据不足，报告显示实际数量，不复制记录凑数。

8. 回放分析

历史回放不直接把一条已完成任务标成 GRANT。每个并发窗口执行：

1. 冻结窗口内记录和地图站点集合。
2. 按数据库原始优先级、创建时间、任务号、车辆号稳定排序。
3. 把路径前缀投影为候选节点和无向边资源。
4. 使用内存账本依次检查资源容量 1 的节点和无向边。
5. 输出：
   • NO_CONFLICT：与窗口内其他记录无路径资源交集；
   • POTENTIAL_NODE_CONFLICT：共享节点；
   • POTENTIAL_OPPOSITE_EDGE：对向使用同一无向边；
   • SAME_VEHICLE_OVERLAP：同车生命周期重叠；
   • INSUFFICIENT_DATA：路径或时间不足；
   • REPLAY_GRANT/HOLD：在明确投影口径下的 SHADOW 推演结果。
6. 对完全相同输入执行两次，决策和原因必须一致。

算法输出与历史事实分别保存。历史事实是“数据库记录已完成”；SHADOW 输出是“按当前离线模型推演的决定”。两者不建立虚假的正确率比较。

9. 可读报告

报告至少包含四张表：

9.1 总览

• 数据库、表、时间范围和抽取时间
• 总记录数、完整路径数、车辆数、站点数
• 代表样本数、并发窗口数
• 数据质量问题数
• 潜在节点/对向边/同车重叠数
• 回放 GRANT/HOLD 数和确定性结果

9.2 业务可读明细

时间	车辆	任务号	从哪里到哪里	实际历史结果	SHADOW 推演	原因

9.3 路径与冲突明细

• 原始完整路径
• 路径长度
• 同期车辆和任务号
• 共享节点或边
• 数据来源字段

9.4 数据问题

• 记录标识
• 问题类型
• 原始值
• 是否影响回放
• 处理方式

表格保留筛选、冻结表头、中文说明和原始编号。报告首页必须醒目标注“真实历史队列离线回放，不是现场 SHADOW 验收”。

10. 错误处理

• 数据库不可用：停止抽取，不使用空数据生成成功报告。
• 返回 0 行：测试失败。
• 快照行数、摘要或字段结构变化：测试失败并提示重新抽取。
• 日期解析失败：记录数据问题，不猜测时间。
• 路径节点未知：标为 UNKNOWN_MAP_SITE，不把未知资源视为空闲。
• 路径为空：标为 INSUFFICIENT_DATA，不进入路径裁决。
• 同一原始记录重复：按 guid 和业务复合键报告，不静默删除。
• 报告生成失败：保留机器可读结果和错误日志。

11. 测试策略

新增测试至少覆盖：

1. 快照结构、行数和 SHA-256 校验。
2. 真实日期、空日期和非法日期解析。
3. 逗号尾项、空路径、重复节点和未知站点。
4. 同任务号多段记录保持独立。
5. 生命周期重叠和边界不重叠。
6. 共享节点、同向边、对向边和无交集路径。
7. 同车重叠检测。
8. 200 条以上代表样本覆盖约束。
9. 相同输入两次回放结果一致。
10. SHADOW 回放零数据库写、零 PLC 写、零业务状态写。
11. 现有 60 条人工安全场景继续通过。

验证命令：

mvn -f javaTest/pom.xml clean test

验收读取 Surefire XML，要求测试数大于 0、Failures 为 0、Errors 为 0，并单独汇总真实历史回放用例数。

12. 交付物

javaTest/src/test/resources/shadow/history/
├── manifest.json
├── queue-history.json
└── map-sites.json

javaTest/src/main/java/com/ft546/wcs/shadow/history/
javaTest/src/test/java/com/ft546/wcs/shadow/HistoricalQueueReplayTest.java

outputs/wcs-shadow-history-replay-{runId}/
├── summary.json
├── readable-report.xlsx
├── replay-results.csv
├── data-quality-issues.csv
└── manifest.sha256

原始快照可保留原始业务编号，但不包含数据库连接信息。输出目录按运行 ID 新建，不覆盖先前失败证据。

13. 验收标准

1. 数据库查询全程只读，生产表无写入。
2. 快照记录数和 SHA-256 可复核。
3. 全部历史记录完成数据质量和风险扫描。
4. 至少 200 条真实路径记录完成确定性离线回放。
5. 原始任务号、车辆号、站点号和路径可在报告中回查。
6. 数据库事实、推导事实和算法结果清晰分栏。
7. 未知或缺失数据不会产生虚假 GRANT。
8. 现有 60 条人工边界场景和全部原有测试无回归。
9. 报告不把离线历史回放描述为真实现场 SHADOW、HIL 或 ACTIVE 证据。
10. 不修改 ruoyi-* 生产代码。