Implementation Roadmap
> Status: NEW · 已对齐 PCR Master Blueprint v1.0 §6 > 目的: 把 Blueprint 四波迁移计划锚定到 Architecture_v2 文档体系。 > 裁定权威: dev_doc/Refactoring/PCR_Master_Blueprint.md §6（本文为索引视图，非二次裁定）
0. 大方向
四波，自下而上，结构先行：
Wave 0 · 目录正骨 + 结构定型（无逻辑变化） ──────► 编译骨架对齐 v1.0
│
▼
Wave 1 · Plant Physics 内核恢复 ──────► force computer + probe + 单 body 弹道
│
▼
Wave 2 · 设备层 + Avionics 闭环 ──────► 全设备 step + 总线单源化 + 模飞测试
│
▼
Wave 3 · FCC + Mission + 全闭环 ──────► FCC 复活 + 三种部署 + closed_loop_full每波都有强制守门测试（bench/trajectory/integration 三级，详见 08_Cross_Cutting/Testing_Framework.md）。
1. Wave 0 · 目录正骨
1.1 目标
把 v0 的目录拓扑改造为 Blueprint §2.1 的 13 库依赖图：
runtime
│
▼
simulation
┌─────────┬─────┴────┬──────┬─────┬──────────┐
▼ ▼ ▼ ▼ ▼ ▼
dynamics_core fcc avionics/ plant bus environment
│ │ devices │ │ │ │
└─────────┴────────┴───────┴─┴─────┴─────────┘
│
▼
contracts
/ | \
types frames monad关键约束：dynamics_core 必须保持业务领域无关（Blueprint §7.16）；simulation 是唯一合法的跨域聚合层（§7.17）；runtime 不持有业务定义（§7.18）。
1.2 行动清单
| # | 行动 | 涉及 v2 文档 |
|---|---|---|
| 1 | 删除 src/plant_model/ / 旧 src/dynamics_core/ / src/plant/interface/ | — |
| 2 | 创建 src/environment/{Atmosphere,GravityField,WindField}.h | 02_Physical_World/Environment_Fields.md |
| 3 | 创建 src/dynamics_core/{ode,algebra,pipeline,state}/ | 05_Dynamics_Core/Universal_ODE_Kernel.md、Forces_Monoid.md、Topology_Algebra.md、SpatialState_and_Frames.md |
| 4 | 创建 src/simulation/{state,env,probe,pipeline}/ 骨架 | 06_Simulation/Dual_Layer_RWS.md、RocketBody_Composite.md、WorldEnv_Assembly.md、Body_World_Tick.md |
| 5 | 创建 src/types/frames/，析出 phantom types | 01_Foundation/Coordinate_Frames.md、Contracts_PerBodyFrames.md |
| 6 | 修 src/bus/{IBus,BusPayloads,TransparentBus}.h include 路径 | 03_Avionics_and_Bus/Semantic_Bus_Pattern.md |
| 7 | src/bus/BusChannel.h + SignalTag 加 [[deprecated]]（Wave 2 删） | 03_Avionics_and_Bus/Semantic_Bus_Pattern.md |
| 8 | dynamics_core/algebra/：class → 模板化自由函数 evolve_topology<Body> | 05_Dynamics_Core/Topology_Algebra.md |
| 9 | dynamics_core/algebra/StageOp.h：enum class WorldStage : uint16_t {} | 05_Dynamics_Core/Topology_Algebra.md §2 |
| 10 | simulation/state/RocketBody.h：device-as-unified-entity 形态 | 06_Simulation/RocketBody_Composite.md |
| 11 | simulation/env/{WorldEnv,BodyEnv}.h：严格只读，强类型环境对象 | 06_Simulation/WorldEnv_Assembly.md |
| 12 | simulation/probe/Probe.h：声明 probe_aero/probe_traj/probe_mass_props | 06_Simulation/WorldEnv_Assembly.md §4 |
| 13 | runtime/ 清空业务定义，保留 Assembler/Runner/IDynChannel | 07_Runtime/Assembler_and_Runner.md、IDynChannel_SIL_HIL.md、PlantScope.md |
1.3 CMake 库划分
每个顶层模块一个 CMake target（详见 Blueprint §6.0.2）：
| Target | 依赖 |
|---|---|
contracts | INTERFACE（header-only） |
environment | types, frames |
plant_model | types, frames, contracts |
plant_hardware | types, frames, contracts |
plant_physics | types, frames, monad, contracts, plant_model, environment |
bus | types, contracts |
avionics_devices | types, contracts, bus, plant_model, plant_hardware |
fcc | types, monad, contracts, bus |
dynamics_core | types, frames, monad, contracts（禁止 link plant/avionics/fcc/bus/environment/simulation） |
simulation | 上面所有 + dynamics_core |
runtime | simulation |
> 强契约：grep -r "plant/\|avionics/\|fcc/\|bus/\|environment/\|simulation/" src/dynamics_core/ → 零命中。
1.4 自底向上逐层编译
1. types + frames + monad 独立编译
2. + contracts
3. + environment + plant/model + plant/hardware
4. + plant/physics
5. + bus
6. + avionics/devices
7. + fcc
8. + dynamics_core
9. + simulation
10. + runtime每层保持上面 N 个 target 链接通过，下面所有 add_subdirectory 暂时注释。
1.5 守门
| 守门 | 必须 |
|---|---|
| 10 个 CMake target 全绿 | ✓ |
| 现有所有测试至少通过编译（功能 stub 可） | ✓ |
dynamics_core 不引用任何业务子域 | ✓ |
runtime/ 无 WorldEnv.h 等业务定义 | ✓ |
2. Wave 1 · Plant Physics 内核恢复
2.1 目标
simulation::body_tick 在相同 BodyEnv 输入下，与 main 力/力矩输出相对误差 ≤ 1e-6。
2.2 准备
- 生成 main golden trajectory：
./build/bin/closed_loop_10s --dump-state ./golden_traj.csv - 此 trajectory 作为 Wave 1 全程的回归基线。
2.3 迁移顺序
| # | 模块 | 来源 | 目标 | 涉及文档 |
|---|---|---|---|---|
| 1 | FlightStateProber | main:pipeline/FlightStateProber.cpp（104 行） | plant/physics/FlightStateProber.{h,cpp} | 02_Physical_World/Plant_Physics_Constitutive.md |
| 2 | compute_drag（上升/下降双模 + 完整 6 分量） | main:pipeline/Drag.cpp（137 行） | plant/physics/Drag.{h,cpp} | 05_Dynamics_Core/Forces_Monoid.md §4 |
| 3 | compute_thrust（三阶段 + EngineForceState） | main:pipeline/Thrust.cpp（158 行） | plant/physics/Thrust.{h,cpp} | 05_Dynamics_Core/Forces_Monoid.md §4 |
| 4 | compute_gravity + ECF→LIC 旋转 | 既有简化版扩展 | plant/physics/Gravity.{h,cpp} | 01_Foundation/Coordinate_Frames.md |
| 5 | probe_aero / probe_traj / probe_mass_props 实现 | 新写 | simulation/probe/Probe.{h,cpp} | 06_Simulation/WorldEnv_Assembly.md §4 |
| 6 | sim::body_tick 雏形：probe → forces → integrate | 新写 | simulation/pipeline/BodyTick.{h,cpp} | 06_Simulation/Body_World_Tick.md §2 |
| 7 | 删除 dynamics/PhysicalRegistry.* | — | — | — |
2.4 守门
bench + trajectory 双级：
| 试验 | 类别 | 期望 |
|---|---|---|
bench_prober_static_sea_level | bench | 4 气动角全 0，q=0 |
bench_prober_above_karman | bench | dyn_pressure=0，mach=0 |
bench_drag_ascending_subsonic | bench | F_x ≈ -Cd·S·q |
bench_drag_descending_gridfin | bench | 含力矩 |
bench_thrust_perturbation | bench | 公式验证 |
bench_thrust_pressure_compensation | bench | ΔF = Sa·101325 |
bench_thrust_off_axis_engine | bench | 旋转方向 |
trajectory_physics_vs_main | trajectory | 力/力矩对 main 相对差 ≤ 1e-6 |
测试组织详见 08_Cross_Cutting/Testing_Framework.md。
3. Wave 2 · 设备层 + Avionics 闭环
3.1 目标
每个 device 独立工作（fidelity=Transparent），FCC 模飞测试（avionics_dry deployment）跑通。
3.2 行动清单
| # | 行动 | 涉及文档 |
|---|---|---|
| 1 | Plant Hardware step 函数：step_engine_mech / step_servo_mech / step_fin_mech | 02_Physical_World/Plant_Hardware_Mech.md |
| 2 | Device step 函数：ecu::step（含 EngineFSM） | 03_Avionics_and_Bus/Sensor_Modeling.md、Device_Dual_Face.md |
| 3 | Device step 函数：scu::step（采样真实摆角） | 03_Avionics_and_Bus/Device_Dual_Face.md |
| 4 | Device step 函数：fin_ctrl::step | 03_Avionics_and_Bus/Device_Dual_Face.md |
| 5 | Device step 函数：imu::step（从 body.aux 读真值） | 03_Avionics_and_Bus/Sensor_Modeling.md §3 |
| 6 | Device step 函数：gps::step（从 body.spatial 读 ECF 真值） | 03_Avionics_and_Bus/Sensor_Modeling.md §4 |
| 7 | Device step 函数：icu::step（计时器 → DiscreteEvent） | 03_Avionics_and_Bus/Sensor_Modeling.md §5 |
| 8 | Bus 单源化：删 BusChannel.h + SignalTag；BusBuffer 挂 RocketBody | 03_Avionics_and_Bus/Semantic_Bus_Pattern.md |
| 9 | sim::body_tick 完整化：avionics step → physics → integrate | 06_Simulation/Body_World_Tick.md §2.2 |
| 10 | DiscreteEvent 解释器：sim::world_tick 末尾把 events → StageOp | 06_Simulation/Body_World_Tick.md §5 |
| 11 | bus::IBus Writer 内化（BusLog） | 03_Avionics_and_Bus/Semantic_Bus_Pattern.md §3 |
3.3 守门
| 试验 | 类别 | 期望 |
|---|---|---|
unit_device_imu_quantization | bench | 真值经 IMU step → bus 上 ImuPayload 量化正确 |
unit_device_ecu_fsm | bench | EngineFSM 状态转移正确 |
unit_device_icu_timer_event | bench | 计时器到期发 DiscreteEvent |
integration_avionics_dry_smoke | integration | physics 冻结，bus traffic 正常，5s 不崩 |
integration_bus_route_local_global | integration | 跨 body 消息从 BusBuffer → IBus → BusBuffer 正确 |
详见 Blueprint §6 Wave 2 原表（v1.0 未改写）。
4. Wave 3 · FCC + Mission + 全闭环
4.1 目标
三种部署都跑通：
sil_monolithic全闭环 10s 无崩溃hil_dyn双进程通信稳定hil_fcc占位（实际 RTOS 板卡接入是后续工作）
4.2 行动清单
| # | 行动 | 涉及文档 |
|---|---|---|
| 1 | FCC 复活：git show main:src/fcc/... 整组迁回 | 04_FCC/Free_Monad_DSL.md、04_FCC/Interpreter_and_RWS.md |
| 2 | 适配 FccInFrame 从 BusMessage 组装（由 sim::body_tick 完成） | 06_Simulation/Body_World_Tick.md §2.2 |
| 3 | FccStage 代数：fcc/stage/FccStageOp.h + evolve_fcc_stage 自由函数 | 04_FCC/FCC_State_Machine.md |
| 4 | Per-stage 预编译：mission profile + Pipeline Factory | 04_FCC/Pipeline_Factory_and_Compilation.md、Static_Compilation_FSM.md |
| 5 | stages.yaml 加载：runtime::Assembler 解析为 FccEnv.stage_table[] | 07_Runtime/Assembler_and_Runner.md §3.2 |
| 6 | Mission YAML：data/input/missions/nominal_ascent.yaml | 07_Runtime/PCR_Configuration.md |
| 7 | Deployment YAML：sil_monolithic.yaml + hil_dyn.yaml + hil_fcc.yaml | 07_Runtime/PlantScope.md §3 |
| 8 | closed_loop_10s.cpp 改名 ballistic_smoke_test.cpp | — |
| 9 | 新建 closed_loop_full.cpp：通过 Runner 跑全闭环 | 07_Runtime/Assembler_and_Runner.md §5 |
| 10 | GNC 算法接入：fcc/algorithms/{nav,guidance,control}/ 实例化 | 08_Cross_Cutting/Algorithm_Integration_Guide.md |
4.3 守门
| 试验 | 类别 | 期望 |
|---|---|---|
integration_sil_full_10s | integration | 全闭环 10s，apogee ≈ 期望值（mission 配置） |
integration_hil_dyn_loopback | integration | localhost UDP，1s 内 50 FCC tick |
integration_avionics_dry_5s | integration | physics 冻结，FCC 完成完整调度循环 |
regression_main_vs_full_loop | regression | 全闭环结果 vs main golden 误差 ≤ 1e-3 |
5. v2 文档完成状态
下表给出 v2 文档当前完成度（这是元信息，与 Wave 进度无关）：
| Batch | 主题 | 状态 |
|---|---|---|
| B1 | 01_Foundation | ✓ (4/4) |
| B2 | 02_Physical_World | ✓ (4/4) |
| B3 | 03_Avionics_and_Bus | ✓ (4/4) |
| B4 | 04_FCC | ✓ (5/5) |
| B5 | 05_Dynamics_Core | ✓ (4/4) |
| B6 | 06_Simulation | ✓ (4/4) |
| B7 | 07_Runtime + 08_Cross_Cutting + Foundation PATCH | ✓ (本批) |
详见 00_Index.md 完整文件列表。
6. 删除 v0 Architecture 目录
v2 完成后，dev_doc/Architecture/ 整体删除（git 是唯一备份）。
删除前确认清单：
- [ ] 所有 v2 文档已 commit
- [ ]
Architecture_v2/与Refactoring/PCR_Master_Blueprint.md引用闭合 - [ ]
dev_doc/AGENTS.md更新（Architecture/路径全部改为Architecture_v2/）
7. C-Distillation Roadmap（远期）
Blueprint §7.12：C-Distillation 软化——不强求一蹴而就，按子域分阶段。
| 阶段 | 目标 | 状态 |
|---|---|---|
| 阶段 1 | fcc/algorithms/ 全部 POD + 无堆分配 | Wave 3 之后启动 |
| 阶段 2 | fcc/interpreter/ 蜕化为 switch-case | TBD |
| 阶段 3 | bus/ 静态 dispatch | TBD |
| 阶段 4 | simulation/pipeline/ 静态 schedule | TBD（HIL 真机部署的前置） |
| 阶段 5 | dynamics_core/ode/ 整数定点版本 | 可选（精度评估后决定） |
每个子域都有自己的 C-Distillation 说明（参见各章节末"C-Distillation 路径"节）。
8. 引用
- Blueprint §5（当前状态迁移基线）、§6（迁移计划四波）、§7.12（C-Distillation 软化）、§7.15–7.19（v1.0 新增裁定）
00_Index.md（v2 文档全索引）- 所有
*/AGENTS.md（子域局部行动指南） 08_Cross_Cutting/Testing_Framework.md（每波守门测试如何组织）08_Cross_Cutting/Symmetric_RWS_Philosophy.md（演化中的不变核心）