# 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 标准入站用例和出站事件端口。
- 第一版核心表脚本和持久化边界。

验收命令：

```bash
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。
- 调度应用服务和决策审计。

验收命令：

```bash
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、指标和关联日志。

验收命令：

```bash
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` 不再创建、调度或完成标准任务。

验收命令：

```bash
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 和最终验收索引。

验收命令：

```bash
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、重启恢复、人工接管、可观测性和性能报告齐全。