FT546-WCS/docs/superpowers/plans/2026-08-04-standard-four-way-shuttle-wcs-roadmap.md

Standard Four-Way Shuttle WCS Roadmap Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 在 FT546 的 optimize/wcs 工作树中，以 RuoYi 为基础逐步交付可独立运行的标准四向车 WCS，并最终由标准内核承担 FT546 的任务、调度、设备协同和恢复。

Architecture: 实施拆成五份可独立验收的子计划，依赖顺序固定为“内核基础 → 拓扑与交通 → 执行与恢复 → FT546 适配 → 产品验收”。每份计划结束时都产生可运行代码、自动化测试和独立提交；后续计划只依赖前一计划声明的稳定接口。

Tech Stack: Java 8, Spring Boot 2.5.15, RuoYi 3.8.9, Maven Reactor, MyBatis/MyBatis-Plus, SQL Server, JUnit 5, ArchUnit, Vue 2, Element UI.

Global Constraints

• 继续使用 RuoYi；新增 ruoyi-wcs Maven 模块，不另建 FT546 专用中间模块。
• Maven 依赖只能是 ruoyi-admin -> ruoyi-wcs -> ruoyi-common；ruoyi-wcs 不依赖 ruoyi-admin。
• 一个部署只运行一个项目和一个仓库，不建设多租户平台。
• Java 版本固定为 1.8，Spring Boot 固定为 2.5.15。
• 首版不修改 FT546 PLC 控制流程、安全联锁和既有寄存器语义。
• 项目 PLC 地址、IP、站点编码、WMS 字段和业务 URL 只能存在于 Admin 适配器或项目配置中。
• Admin 不得直接写 WCS 核心表，设备适配器不得推进任务状态或释放资源。
• UNKNOWN 命令禁止自动重发；未知资源禁止按超时释放。
• 业务订单、执行步骤、设备命令和资源预约保持独立状态机。
• 现有 FT546 代码、表和 javaTest 只作为证据与验收语料，不作为新内核包结构模板。
• 本计划只描述目标版本实现和验收，不设计旧表迁移、灰度切换或双写流程。
• 每个行为先写失败测试，确认 RED 后再写最小实现。
• 每个任务完成后运行聚焦测试、相关模块测试和 git diff --check，然后独立提交。
• 保留用户现有未跟踪 HTML 文件，不暂存、不修改、不删除。

---

Plan Sequence

Plan 1: WCS Core Foundation and Task Workflow

文件：docs/superpowers/plans/2026-08-04-standard-wcs-core-foundation.md

交付：

• ruoyi-wcs Maven 模块和测试基础。
• 架构依赖门禁。
• TransportOrder、WorkflowInstance、TaskStep 状态机。
• WMS 标准入站用例和出站事件端口。
• 第一版核心表脚本和持久化边界。

验收命令：

mvn -pl ruoyi-wcs -am test
mvn -pl ruoyi-admin -am test

Plan 2: Topology, Dispatch, and Traffic Control

文件：docs/superpowers/plans/2026-08-04-standard-wcs-topology-dispatch-traffic.md

依赖：Plan 1 的订单、步骤、仓储端口和模块边界。

交付：

• 版本化拓扑和设备能力模型。
• 路径规划、车辆选择和稳定评分。
• 资源账本、预约、死锁预防、HOLD/YIELD。
• 调度应用服务和决策审计。

验收命令：

mvn -pl ruoyi-wcs -am -Dtest='*Topology*,*Assignment*,*Traffic*,*Dispatch*' test

Plan 3: Execution, Equipment Coordination, and Recovery

文件：docs/superpowers/plans/2026-08-04-standard-wcs-execution-recovery.md

依赖：Plan 2 的车辆绑定、路线和资源预约。

交付：

• DeviceCommand、Outbox、设备事件和快照对账。
• 四向车、提升机、输送线和充电协同状态机。
• RecoveryCase、启动恢复、局部隔离和人工接管审计。
• 核心查询 DTO、指标和关联日志。

验收命令：

mvn -pl ruoyi-wcs -am -Dtest='*Command*,*Coordinator*,*Recovery*,*Outbox*' test

Plan 4: FT546 Project Adapters and Operations UI

文件：docs/superpowers/plans/2026-08-04-standard-wcs-ft546-adapters.md

依赖：Plan 3 的设备端口、恢复端口和 QueryService。

交付：

• FT546 WMS 适配器，保留既有接口 URL 和回调语义。
• 四向车、提升机、输送线和充电桩旧 PLC Profile 与适配器。
• 项目配置表、协议样本测试和启动 wiring。
• 标准任务、设备、资源、命令和恢复页面。
• 新调度入口接管，旧 BaseSRgvThread 不再创建、调度或完成标准任务。

验收命令：

mvn -pl ruoyi-admin -am test
cd ruoyi-ui && npm run build:prod

Plan 5: Simulation, Historical Replay, and Product Acceptance

文件：docs/superpowers/plans/2026-08-04-standard-wcs-simulation-acceptance.md

依赖：Plan 4 的完整 FT546 适配链和真实核心构建产物。

交付：

• 使用真实 Adapter 契约的确定性模拟器与故障注入。
• 第二套合成仓库配置，证明不修改核心即可运行。
• FT546 历史任务与 PLC 报文回放。
• 真实 PLC/HIL 的受控协议门禁与能力证据。
• 重启恢复、性能基线和 72 小时/100000 任务验收入口。
• 人工接管审计、可观测性证据、可审计报告、manifest 和最终验收索引。

验收命令：

mvn -pl ruoyi-wcs,ruoyi-admin -am test
cd javaTest && mvn clean test

Release Gates

1. Plan 1 未通过时，不创建真实设备适配器。
2. Plan 2 的资源容量和非法状态指标非零时，不进入执行协同。
3. Plan 3 的 UNKNOWN、恢复和 Outbox 测试未通过时，不接 FT546 PLC。
4. Plan 4 的协议回归未通过时，不允许旧调度入口退出。
5. Plan 5 的安全不变量、第二仓配置、历史回放、能力证据和 FT546 HIL 门禁未通过时，不宣称标准产品完成或 FT546 可投产。

Approved Design Coverage Map

总体设计章节	实施落点
1-4 背景、目标、边界、首版范围	本路线图全局约束；Plan 1 模块边界；Plan 4 FT546 项目边界
5 总体架构与 Maven 依赖	Plan 1 Task 1、Task 7
6 六个核心领域	Plan 1 任务/流程；Plan 2 拓扑/调度/交通；Plan 3 协同/执行/恢复
7 核心安全不变量	Plan 1 状态机与幂等；Plan 2 资源容量/等待图；Plan 3 UNKNOWN/恢复；Plan 5 全量不变量验收
8 端到端任务流	Plan 1 Task 5；Plan 2 Task 7；Plan 3 Task 3；Plan 4 Task 6、Task 8
9 核心状态机	Plan 1 Task 3-4；Plan 2 Task 5；Plan 3 Task 1、Task 6
10 数据所有权	Plan 1 Task 6-7；Plan 2 Task 7；Plan 3 Task 7；Plan 4 Task 1
11 适配器契约	Plan 1 WMS 端口；Plan 2 ConfigurationUseCase；Plan 3 设备端口；Plan 4 全部项目 Adapter
12 PLC 能力策略	Plan 4 Task 1、Task 3；Plan 5 Task 4-5
13 调度、交通、提升机、输送线、充电	Plan 2 Task 2-7；Plan 3 Task 4-5
14 恢复、人工接管、可观测性	Plan 3 Task 6-8；Plan 4 Task 7；Plan 5 Task 6、Task 8
15 测试与模拟器	Plan 5 Task 1-6
16 验收门槛与产物	Plan 5 Task 7-8；本路线图 Final Definition of Done
17 建议代码结构	五份子计划各 Task 的精确 Files 清单
18 与现有 FT546 文档关系	本路线图“旧代码仅作证据”和“不讨论迁移”约束；Plan 4 Legacy Profile 边界
19 设计完成定义	本路线图 Release Gates 和 Final Definition of Done

Final Definition of Done

• ruoyi-wcs 构建产物在 FT546 和第二套合成仓库配置下完全相同。
• FT546 Admin 只包含项目接口、协议、流程定义、策略、配置和页面。
• 旧调度线程不再拥有标准任务创建、选车、路径、完成和充电调度权。
• 所有核心表只由 ruoyi-wcs Repository 写入。
• 所有安全不变量测试为 0 违规。
• FT546 历史回放、PLC 样本契约、真实 PLC/HIL、重启恢复、人工接管、可观测性和性能报告齐全。