# 源码目录结构

`src` 按“仿真、核心逻辑、通信、现场部署”的边界组织，而不是按临时实验文件组织。

## 目录说明

- `apps/`
  面向操作人员的工具和界面原型。

- `communication/`
  ROS 2 接口包、TCP 帧协议、车间工控机到车端电脑的 gateway。这个层应该同时服务于仿真和现场部署。

- `core/`
  标定流程和标定算法，包括 `workshop_orchestrator`、底盘标定、运控标定、传感器标定、车辆参数管理等可复用核心逻辑。

- `simulation/`
  部署前仿真验证代码。Isaac 车间、仿真车辆、仿真车端 agent、仿真传感器、仿真标定靶和旧版仿真包都放在这里。

- `deployment/`
  部署 profile、数据集索引转换工具和从仿真迁移到现场前的检查清单。这里放配置基准，不放算法实现。

- `docs/`
  源码树内的设计说明、边界说明和迁移规则。

- `site_deployment/`
  真实现场部署代码，例如真实车端电脑适配器、真实车辆 SDK、PLC/CAN 或厂商控制器对接代码。

## 边界规则

- Isaac API 只放在 `simulation/`。
- 真实车辆 SDK、PLC、CAN、厂商控制器相关代码只放在 `site_deployment/`。
- ROS 2 接口、TCP 协议和 gateway 放在 `communication/`。
- 编排流程和标定算法放在 `core/`。
- 部署 profile 放在 `deployment/`。
- 设计说明和迁移边界说明放在 `docs/`。

## 文档入口

- `docs/sim_to_site_code_boundary.md`
  仿真代码、可复用核心代码和真实现场部署代码的边界。

- `docs/algorithm_template_contract.md`
  标定算法模板合同，定义模板维护者和算法实现者的责任边界、可修改文件、输入输出字段和 smoke 验证要求。

## 主要入口

本地数据输入回归测试：

```bash
./run_local_data_input_smoke.sh
```

Isaac 车间仿真：

```bash
python3 src/simulation/isaac_workshop_sim/scripts/build_calibration_room.py
```

仿真车端 agent：

```bash
python3 src/simulation/vehicle_agent_sim/scripts/isaac_vehicle_agent_sim.py
```

按 profile 启动完整仿真链路：

```bash
python3 src/simulation/tools/launch_sim_stack.py
```

这条链路中，车间工控机与车端电脑之间的底盘、运控、外部真值位姿和传感器数据都通过 TCP/WiFi6 仿真边界传输；Isaac topic 只留在仿真内部。

车间 gateway 和 `workshop_orchestrator` 仍然按 ROS 2 包名启动；源码分别在 `communication/` 和 `core/` 下。
