# 构型 JSON 填写说明

本文档给负责构型设计的机械工程师使用。你只需要按照现有 `topology.template.json` 格式创建新的构型 JSON，不需要关心 Python 代码如何实现。

构型 JSON 描述的是“这个传动系统由哪些运动构件组成、构件之间有什么机械关系”。它不填写目标速比、齿数、模数、材料、输出路径，也不填写具体三维坐标。

## 1. 文件位置和命名

每个构型族一个目录：

```text
src/configurations/<family_name>/topology.template.json
```

例子：

```text
src/configurations/simple_2k_h/topology.template.json
src/configurations/simple_2k_h_cascade/topology.template.json
```

`<family_name>` 用小写英文和下划线，例如：

```text
simple_2k_h
simple_2k_h_cascade
compound_planet
differential_planet
```

## 2. 顶层结构

一个构型 JSON 必须包含：

```json
{
  "template_id": "simple_2k_h_v0_1",
  "family": "simple_2k_h",
  "description": "简短描述",
  "nodes": [],
  "relations": []
}
```

字段说明：

| 字段 | 必填 | 怎么填 |
|---|---:|---|
| `template_id` | 是 | 模板唯一编号，建议 `<family>_v0_1` |
| `family` | 是 | 构型族名称，必须和目录名一致 |
| `description` | 是 | 一句话说明构型，不写公式长文 |
| `nodes` | 是 | 构件节点列表 |
| `relations` | 是 | 构件关系列表 |

## 3. nodes 怎么填

`nodes` 表示构型里有哪些构件或参考对象。

节点格式：

```json
{
  "id": "sun",
  "kind": "gear",
  "role": "sun",
  "gear_type": "external",
  "repeat": "single",
  "formula_ref": "nodes.sun",
  "stage_id": null,
  "local_role": "sun"
}
```

字段说明：

| 字段 | 必填 | 可选值 / 填法 | 说明 |
|---|---:|---|---|
| `id` | 是 | 英文唯一名 | 关系里会用它引用节点 |
| `kind` | 是 | `gear` / `carrier` / `housing` / `axis` | 节点类型 |
| `role` | 是 | `sun`、`ring`、`planet`、`carrier` 等 | 机械角色 |
| `gear_type` | 是 | `external` / `internal` / `null` | 只有齿轮填齿轮类型 |
| `repeat` | 是 | `single` / `planet_count` | 是否按行星数量展开 |
| `formula_ref` | 是 | 字符串 | 便于反查来源 |
| `stage_id` | 否 | `null` 或 `s1`、`s2` | 多级构型可用 |
| `local_role` | 否 | `sun`、`ring`、`planet` 等 | stage 内局部角色 |

### kind 选择

| 机械对象 | `kind` |
|---|---|
| 太阳轮、齿圈、行星轮 | `gear` |
| 行星架 | `carrier` |
| 壳体、机架、固定参考 | `housing` |
| 主轴线、参考轴 | `axis` |

### gear_type 选择

| 齿轮 | `gear_type` |
|---|---|
| 太阳轮 | `external` |
| 行星轮 | `external` |
| 内齿圈 | `internal` |
| 非齿轮节点 | `null` |

### repeat 选择

| 情况 | `repeat` |
|---|---|
| 只有一个，例如 sun、ring、carrier、housing | `single` |
| 按行星数量重复，例如 planet | `planet_count` |

注意：不要手写 `planet_1`、`planet_2`、`planet_3`。只写一个 `planet` 节点，并设置：

```json
"repeat": "planet_count"
```

程序会自动展开。

## 4. relations 怎么填

`relations` 表示节点之间有什么机械关系。

关系格式：

```json
{
  "id": "sun_planet_external_mesh",
  "source": "sun",
  "target": "planet",
  "relation_type": "external_mesh",
  "carrier_ref": "carrier",
  "mesh_id": "sun_planet",
  "formula_ref": "relations.sun_planet_external_mesh",
  "stage_id": null
}
```

字段说明：

| 字段 | 必填 | 怎么填 |
|---|---:|---|
| `id` | 是 | 关系唯一名 |
| `source` | 是 | 起点 node id |
| `target` | 是 | 终点 node id |
| `relation_type` | 是 | 见下表 |
| `carrier_ref` | 否 | 行星啮合通常填 `carrier` |
| `mesh_id` | 否 | 同一组啮合的名字 |
| `formula_ref` | 是 | 便于反查来源 |
| `stage_id` | 否 | 多级构型可填 stage 标识 |

当前允许的 `relation_type`：

| relation_type | 含义 | 典型 source -> target |
|---|---|---|
| `external_mesh` | 外齿轮与外齿轮啮合 | `sun -> planet` |
| `internal_mesh` | 内齿圈与外齿轮啮合 | `ring -> planet` |
| `revolute_joint` | 转动副 | `planet -> carrier` |
| `coaxial` | 同轴 | `sun -> main_axis` |
| `fixed` | 固定到壳体或固定参考 | `ring -> housing` |
| `rigid` | 刚性连接，同速转动 | `s1_carrier -> s2_sun` |

## 5. 常见关系填写规则

### 外啮合

太阳轮和行星轮外啮合：

```json
{
  "id": "sun_planet_external_mesh",
  "source": "sun",
  "target": "planet",
  "relation_type": "external_mesh",
  "carrier_ref": "carrier",
  "mesh_id": "sun_planet",
  "formula_ref": "relations.sun_planet_external_mesh"
}
```

要点：

- `source` 和 `target` 都应该是 `gear_type = external`。
- 行星机构里要填 `carrier_ref`，表示啮合是在行星架参考系下建立运动方程。

### 内啮合

内齿圈和行星轮内啮合：

```json
{
  "id": "ring_planet_internal_mesh",
  "source": "ring",
  "target": "planet",
  "relation_type": "internal_mesh",
  "carrier_ref": "carrier",
  "mesh_id": "ring_planet",
  "formula_ref": "relations.ring_planet_internal_mesh"
}
```

要点：

- 内齿圈节点必须是 `gear_type = internal`。
- 行星轮节点必须是 `gear_type = external`。

### 行星轮转动副

行星轮绕行星架销轴转动：

```json
{
  "id": "planet_carrier_pin_revolute",
  "source": "planet",
  "target": "carrier",
  "relation_type": "revolute_joint",
  "carrier_ref": "carrier",
  "mesh_id": null,
  "formula_ref": "relations.planet_carrier_pin_revolute"
}
```

### 同轴

太阳轮、齿圈、行星架和主轴同轴：

```json
{
  "id": "sun_main_axis_coaxial",
  "source": "sun",
  "target": "main_axis",
  "relation_type": "coaxial",
  "carrier_ref": null,
  "mesh_id": null,
  "formula_ref": "relations.sun_main_axis_coaxial"
}
```

通常至少要写：

```text
sun -> main_axis
ring -> main_axis
carrier -> main_axis
```

### 固定

齿圈固定到壳体：

```json
{
  "id": "ring_housing_fixed",
  "source": "ring",
  "target": "housing",
  "relation_type": "fixed",
  "carrier_ref": null,
  "mesh_id": null,
  "formula_ref": "relations.ring_housing_fixed"
}
```

注意：实际哪个构件固定，还会受 requirement 的 `fixed` 字段影响。单级边界变体中，如果 requirement 写 `fixed = sun`，运行时会把 fixed 关系改成 sun 固定到 housing。

### 刚性连接

两级串联中，前一级输出和后一级输入刚性连接：

```json
{
  "id": "stage_output_to_next_input_rigid",
  "source": "stage_carrier",
  "target": "stage_sun",
  "relation_type": "rigid",
  "carrier_ref": null,
  "mesh_id": null,
  "formula_ref": "cascade.relations.output_to_next_input",
  "stage_id": "cascade"
}
```

要点：

- `rigid` 表示两个运动构件角速度相同。
- 多级构型里通常由程序根据 stage 生成真实组件名，例如 `s1_carrier -> s2_sun`。

## 6. 单级 simple_2k_h 示例

这是最常见结构：

```text
sun 输入
ring 固定
carrier 输出
planet 均布
```

必须包含节点：

```text
sun: external gear, single
planet: external gear, planet_count
ring: internal gear, single
carrier: carrier, single
housing: housing, single
main_axis: axis, single
```

必须包含关系：

```text
sun --external_mesh--> planet
ring --internal_mesh--> planet
planet --revolute_joint--> carrier
sun/ring/carrier --coaxial--> main_axis
ring --fixed--> housing
```

对应文件参考：

```text
src/configurations/simple_2k_h/topology.template.json
```

## 7. 两级串联 simple_2k_h_cascade 示例

两级串联可以理解为：

```text
s1 是一个 simple_2k_h
s2 是一个 simple_2k_h
s1.output 刚性连接到 s2.input
```

模板里使用 `stage_sun/stage_planet/stage_ring/stage_carrier` 表示“每一级的局部节点”。程序会展开成：

```text
s1_sun / s1_ring / s1_planet_1..n / s1_carrier
s2_sun / s2_ring / s2_planet_1..n / s2_carrier
```

对应文件参考：

```text
src/configurations/simple_2k_h_cascade/topology.template.json
```

## 8. 填写检查清单

提交新的构型 JSON 前，逐项检查：

- `template_id` 唯一。
- `family` 和目录名一致。
- 每个 `relation.source`、`relation.target` 都能在 `nodes.id` 中找到。
- 齿轮节点的 `gear_type` 正确。
- 非齿轮节点的 `gear_type` 是 `null`。
- 需要重复的行星轮只写一个节点，并设置 `repeat = planet_count`。
- 每组行星啮合关系都填写了正确的 `carrier_ref`。
- 主运动构件都和 `main_axis` 有 `coaxial` 关系。
- 固定关系使用 `fixed`。
- 级间或同轴齿轮组刚性连接使用 `rigid`。
- 没有使用未注册的 `relation_type`。
- 没有在 topology JSON 中填写齿数、模数、速比、坐标、材料或输出路径。

## 9. 不应该写进构型 JSON 的内容

以下内容不要写进 `topology.template.json`：

- `target_ratio`
- `z_sun`、`z_planet`、`z_ring`
- `module_mm`
- `planet_count_candidates`
- `face_width_mm`
- `center_xyz_mm`
- `axis_xyz`
- STEP 文件路径
- 材料、颜色、轴承型号
- validation report 结果

这些属于 requirement、参数求解、placement、CAD 或验证输出，不属于构型模板。

## 10. 常见错误

| 错误 | 后果 |
|---|---|
| 忘记写 `carrier_ref` | 行星啮合运动方程无法正确使用行星架参考系 |
| 把 `planet_1/planet_2/planet_3` 写进模板 | runtime 无法按候选行星数自动展开 |
| 内齿圈写成 `external` | 内啮合验证失败 |
| 非齿轮节点 `gear_type` 没写 `null` | schema 或验证失败 |
| 使用未注册 relation type | 验证器会报 unsupported relation type |
| 在 topology 中写齿数和模数 | 构型和参数耦合，无法复用 |