reducers/backend/docs/topology-json-authoring-guide.md

构型 JSON 填写说明

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

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

1. 文件位置和命名

每个构型族一个目录：

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

例子：

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

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

simple_2k_h
simple_2k_h_cascade
compound_planet
differential_planet

2. 顶层结构

一个构型 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 表示构型里有哪些构件或参考对象。

节点格式：

{
  "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 节点，并设置：

"repeat": "planet_count"

程序会自动展开。

4. relations 怎么填

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

关系格式：

{
  "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. 常见关系填写规则

外啮合

太阳轮和行星轮外啮合：

{
  "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，表示啮合是在行星架参考系下建立运动方程。

内啮合

内齿圈和行星轮内啮合：

{
  "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。

行星轮转动副

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

{
  "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"
}

同轴

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

{
  "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"
}

通常至少要写：

sun -> main_axis
ring -> main_axis
carrier -> main_axis

固定

齿圈固定到壳体：

{
  "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。

刚性连接

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

{
  "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 示例

这是最常见结构：

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

必须包含节点：

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

必须包含关系：

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

对应文件参考：

src/configurations/simple_2k_h/topology.template.json

7. 两级串联 simple_2k_h_cascade 示例

两级串联可以理解为：

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

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

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

对应文件参考：

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 中写齿数和模数	构型和参数耦合，无法复用