# Topology JSON Authoring Guide

这份说明给只负责创建构型 JSON 的机械工程师使用。构型 JSON 只描述机械构件和关系，不填写齿数、模数、目标速比、三维坐标或输出文件。

## 文件位置

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

`family_name` 必须和 JSON 顶层 `family` 一致。

## 顶层字段

```json
{
  "template_id": "<family>_v0_1",
  "family": "<family>",
  "description": "one sentence",
  "nodes": [],
  "relations": []
}
```

## node 字段

每个 node 表示一个构件或参考对象：

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

填写规则：

- `kind`: `gear`、`carrier`、`housing`、`axis`
- `gear_type`: 外齿轮填 `external`，内齿圈填 `internal`，非齿轮填 `null`
- `repeat`: 单个构件填 `single`，按行星数量重复的行星轮填 `planet_count`
- `stage_id/local_role`: 多级构型用于表达级内角色；单级可以省略或填 `null`

不要在模板里手写 `planet_1..planet_n`。只写一个 `planet`，并设置 `repeat = planet_count`。

## relation 字段

每个 relation 表示构件之间的机械关系：

```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
}
```

允许的 `relation_type`：

```text
external_mesh
internal_mesh
revolute_joint
coaxial
fixed
rigid
```

常用关系：

- `sun --external_mesh--> planet`，`carrier_ref = carrier`
- `ring --internal_mesh--> planet`，`carrier_ref = carrier`
- `planet --revolute_joint--> carrier`
- `sun/ring/carrier --coaxial--> main_axis`
- `ring --fixed--> housing`
- `s1_output --rigid--> s2_input`

## 不要填写的内容

不要在 topology JSON 中填写：

- 目标速比
- 齿数
- 模数
- 行星数量候选
- 坐标和轴线
- STEP 路径
- 材料和颜色
- 验证结果

这些内容分别属于 requirement、参数求解、PlacementPlan、CAD 输出和 validation report。

## 提交前检查

- `template_id` 唯一。
- `family` 和目录名一致。
- 所有 relation 的 `source/target/carrier_ref` 都能在 nodes 中找到。
- 齿轮 `gear_type` 正确。
- 行星轮使用 `repeat = planet_count`。
- 行星啮合填写了 `carrier_ref`。
- 所有主运动构件都有 `coaxial` 到 `main_axis`。
- 固定关系用 `fixed`，刚性连接用 `rigid`。
- 没有使用未注册 relation type。