51 lines
2.5 KiB
Markdown
51 lines
2.5 KiB
Markdown
# 依赖分层与 Trait 边界
|
||
|
||
`config/dependency-policy.toml` 是依赖规则的唯一机器可读来源。crate 名称保持不变，manifest 按 `crates/<layer>/<domain>` 组织，并在 `[package.metadata.sentry-chassis]` 中声明 `layer`。
|
||
|
||
## 单向分层
|
||
|
||
```text
|
||
contract can/imu
|
||
protocol imu/motor/remote
|
||
transport can/serial
|
||
device imu/motor/esc/remote
|
||
control algorithm/chassis/motor
|
||
experiment trace
|
||
model motor
|
||
simulation motor
|
||
tooling tuning
|
||
config chassis
|
||
application bench/daemon/tools/tuning
|
||
verification integration
|
||
```
|
||
|
||
依赖只能从高层指向低层；正常依赖和 dev 依赖都必须如此。跨层集成测试集中在 `verification/integration`，不允许测试回边渗入低层 crate。
|
||
|
||
## Trait 组织
|
||
|
||
- `protocol/motor`：`MotorProtocol`、`EffortScale`、`FeedbackFields`，只处理线上的命令、反馈、帧 ID 和量程。
|
||
- `device/motor`：`MotorSpec`、`MotorFeedback`、`EffortDrive`、`VelocityDrive`、`PositionDrive`、`Disable`，只处理机械型号和设备能力。
|
||
- `device/esc`：`EscConfig<S>`、`EscMotor<S>`、`EscBus<S>` 通过 `MotorSpec::Protocol` 组合协议能力；电流路径要求 `CurrentEscDrive`，GM6020 使用独立的 `VoltageEscDrive` 路径。
|
||
- `model/motor`：`MotorPlant`、`DcMotorPlant<S>`，只处理动态模型和反馈量化。
|
||
|
||
`Gm3508`、`M2006`、`Gm6020` 是 marker type；型号事实、协议族和控制能力由关联类型组合，不在 bus 内用运行时 `match` 判断。
|
||
|
||
## 外部库边界
|
||
|
||
外部依赖必须从根 `workspace.dependencies` 继承，并在 policy 的 `external_roles` 中声明用途。异步/传输库只进入 transport/device；配置和 CLI 库只进入 config/application；搜索、并行、绘图库只进入 tuning/application；`approx`、`proptest` 只允许作为测试依赖。
|
||
|
||
## 审查脚本
|
||
|
||
`scripts/audit-rules.rs` 是单文件 Rust `cargo-script`。脚本通过内嵌 manifest 声明
|
||
`serde`、`serde_json`、`toml` 和 `regex`，不需要额外 Python 工具链。运行时使用
|
||
Nightly 的 `-Zscript`；workspace 本身仍由 `rust-toolchain.toml` 固定 Stable。
|
||
|
||
```sh
|
||
cargo +nightly -Zscript scripts/audit-rules.rs
|
||
cargo +nightly -Zscript scripts/audit-rules.rs --self-test
|
||
```
|
||
|
||
## 变更流程
|
||
|
||
新增 crate、内部边或外部库时，必须同步更新 `config/dependency-policy.toml`、crate 的 layer 声明、架构文档和 `Cargo.lock`。运行 `just audit`，提交时由 `.githooks/pre-commit` 执行同一规则。
|