likang/reducers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Split project into frontend and backend

Browse Source
This commit is contained in:
李康
2026-08-13 16:24:36 +08:00
commit f051146486
274 changed files with 953932 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/docs/topology-json-authoring-guide.md
+392
View File
@@ -0,0 +1,392 @@
# 构型 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 中写齿数和模数 | 构型和参数耦合，无法复用 |