# CAD 与物理语义规范 v0.1

> 目标：agent 可以自由地写 CAD；只要按这份规范补上物理语义，评测系统就能对它做真正的仿真计算。缺了哪种语义，对应的需求就给出 `UNVERIFIABLE`，并且说明缺什么。

## 1. 坐标系和单位

| 项 | 约定 |
|---|---|
| 装配坐标系 | x 指向机尾（向后），y 指向右侧，z 向上，和 AeroSandbox 一致；原点由设计者自定，所有零件都画在同一个装配坐标系里 |
| CAD 长度单位 | **mm**（build123d 默认）；导入的 STEP 默认按 mm 处理，可以用 `unit=` 声明 |
| IR 和语义里的数值 | **SI**（m、kg、N、s）；角度用度；SDK 接受 `"900 mm"` 这类写法并自动换算 |
| 对称 | 对称件只画一半（y ≥ 0 的右半边），并声明 `symmetric=True`；评测系统负责镜像 |

## 2. 几何

每个 `Part` 是一个实体（solid），或者一组实体的组合（compound），几何来源有三种：

| 来源 | 写法 | 能做的计算 |
|---|---|---|
| CAD 代码 | `Part(..., cad=<build123d 形体>)` | 全部 |
| STEP 导入 | `Part(..., step="path.step")` | 全部 |
| 原语生成 | 比如 `LiftingSurface(...)` | 由原语决定（v0.1 的原语用近似公式估算质量） |

- 设计运行时把几何导出成 BRep 文件，按**内容哈希**存储，IR 里只记录哈希。评估器从文件重新读取几何、自己计算，不信任设计运行时算出的任何几何量。
- 几何必须是封闭、有效的实体；无效时，依赖几何的需求给出 `UNVERIFIABLE（invalid_ir）`，并指出是哪个零件。

## 3. 每个零件必须有的语义

| 字段 | 含义 | 用途 |
|---|---|---|
| `material` | 材料库 ID | 密度、强度、刚度、价格 |
| `process` | 工艺类型和工艺参数 | 可制造性规则、工艺偏差、成本 |
| `role`（可选） | 品类角色，比如 `lifting_surface` | 决定由哪些品类评估器来处理 |

**质量**：有几何的零件，质量 = 实体体积 × 材料密度；重心取实体的体心。板材类材料（比如 KT 板）的密度 = 面密度 ÷ 板厚。

## 4. 几何引用（选择器）

语义里引用几何时，用**和 CAD 内核无关的几何选择器**，在装配坐标系里给出，单位是 m：

| 选择器 | 用法 |
|---|---|
| `Point(x, y, z)` | 安装点、加载点；引用离它最近的面 |
| `Axis(origin, direction)` | 转动关节轴、铰链线、推力线 |
| `Plane(origin, normal)` | 对称面、切割面 |
| `Region(min, max)` | 一个包围盒，引用盒内的面（比如固定面、加载面） |

这样设计参数变化、拓扑重新生成之后，引用仍然有效；对导入的 STEP 也同样适用。

## 5. 核心物理语义

| 语义 | 字段 | v0.1 状态 |
|---|---|---|
| `Component` | 库引用（`type:name@version`）、位置、`on`（挂在哪个元件上） | 已实现 |
| `Port(type="payload")` | 位置、`mass_kg` | 已实现 |
| `Mount`（`core.physics`） | 零件、`Region`；v0.1 固定全部平动自由度 | **已实现**（静力 FEA） |
| `Load`（`core.physics`） | 零件、`Region`、力向量（N，装配坐标系）、工况 ID；力按面积均匀分布在选中的面上 | **已实现**（静力 FEA） |
| `Joint` | 类型（fixed / revolute / prismatic / ball / flexure）、`Axis`、限位、刚度和阻尼 | 规范已定，多体仿真尚未实现 |
| `Fastener` | 类型（螺丝、热熔铜螺母、销）、`Point` 列表 | 规范已定 |
| `Contact` | 零件对、摩擦系数 | 规范已定 |

## 6. 固定翼品类语义

| 语义 | 写法 | 系统做什么 |
|---|---|---|
| 升力面（原语） | `LiftingSurface(sections=[Section(...)])` | 直接用给定的截面 |
| **升力面（自由 CAD）** | `tag_lifting_surface(part, symmetric=..., vertical=..., n_sections=...)` | 沿展向（水平面是 y，垂直面是 z）把实体切成若干截面，提取每个截面的前缘点、弦长、扭转、**真实翼型坐标**，交给气动计算 |
| 舵面 | `ControlSurface(on=<升力面 id>, function=..., chord_frac, span, deflection)` | 加到对应展向范围的截面上 |
| 翼梁 | `Spar(material, span_frac)`；CAD 升力面在 `tag_lifting_surface(..., spar=Spar(...))` 里给出 | 结构强度 |
| 推进 | 库内的电机、桨、电池、电调 | 动力模型 |

**截面提取的有效域**：每个截面必须是单个封闭轮廓，且弦向尺寸远大于厚度。不满足时（比如切到了不规则的形状），这个升力面的气动需求给出 `UNVERIFIABLE（out_of_domain）`，并指出是哪个展向位置。

## 7. 将要加入的计算（同一份语义，不同的评估器）

| 计算 | 使用的语义 |
|---|---|
| 结构 FEA：**v0.1 已实现**，gmsh 四面体网格 + scikit-fem 二次单元，线弹性静力；用悬臂梁解析解验证，挠度误差 < 5%；CalculiX 以后作为交叉验证后端 | 几何、材料（E、ν、强度）、`Mount`、`Load`；FDM 件还用到打印方向（层间拉伸强度单独校核）和填充率 |
| 多体动力学（MuJoCo / Newton） | 几何（质量和惯量）、`Joint`、执行器、`Contact` |
| 可打印性（切片软件） | 几何、FDM 工艺参数 |
| 公差蒙特卡洛 | 几何、工艺偏差模型 |

## 8. FEA 的语义细节（v0.1）

- 每个有 `Load` 的零件单独做线弹性静力分析；同一零件的不同 `case` 分别求解，指标取最坏情况。
- 选面规则：边界三角形的三个顶点都落在 `Region` 内（容差 0.5 mm），这个三角形就被选中。没有选中任何面时，给出 `UNVERIFIABLE（missing_semantics）`，并提示检查坐标（单位是 m）。
- 安全系数 = min(层内强度 ÷ 99 分位的 von Mises 应力, 层间强度 ÷ 99 分位的层间拉应力)。用 99 分位而不是最大值，是为了避开尖角处的应力奇异；最大值作为证据一并给出。
- FDM 件的有效刚度和强度按「壳层比例 + 填充率」折减（占位模型，待实测校准）。
- 打印件强度的批次散布（±8%）在蒙特卡洛里只作用于安全系数，不重复做 FEA。
- 有效域：最大位移超过零件尺寸的 5% 时，可信度降到 0.3，并提示线性假设不成立。