# 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. 方案选择

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

```text
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 领域模型：

```text
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 并发窗口

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

```text
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 条人工安全场景继续通过。

验证命令：

```bash
mvn -f javaTest/pom.xml clean test
```

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

## 12. 交付物

```text
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-*` 生产代码。