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/GBT+33923-2017.original.docx
BIN
View File
Binary file not shown.
backend/docs/GBT+33923-2017.pdf
BIN
View File
Binary file not shown.
backend/docs/GBT33923-2017-OCR.md
+7600
View File
File diff suppressed because it is too large Load Diff
backend/docs/configuration-development-standard.md
+219
View File
@@ -0,0 +1,219 @@
# 构型开发规范
本文档说明如何在本项目中新增或维护行星减速器构型。目标是让复合行星、多级串联、差动行星等新构型沿同一套结构扩展，避免把公式、位姿、CAD 和验证逻辑散落到各个模块中。
## 1. 总流程
新增构型必须按以下链路接入：
```text
requirement schema
-> configuration registry
-> topology template/runtime
-> parameter solver
-> kinematics
-> placement solver
-> CAD generator
-> assembly reader
-> validators
-> tests/examples
```
每一步只承担自己的职责：
- requirement 只描述用户目标、边界条件、齿形和候选范围。
- configuration 只描述构型图和构型族专属规则。
- parameter solver 只枚举、过滤、评分，不写死答案。
- kinematics 只从图关系生成运动方程。
- placement solver 只计算零件位姿。
- CAD generator 只按参数和位姿生成真实几何。
- validators 只读取 instance、snapshot、placement 和真实 CAD 输出进行验证。
## 2. 构型目录规范
每个构型族必须有独立目录：
```text
src/configurations/<family_name>/
family.py
topology.template.json
placement_rules.py
input/requirements/reducers/<family_name>/
tests/
```
必须在 `src/configurations/registry.py` 中注册：
```python
CONFIGURATIONS = {
"<family_name>": ConfigurationSpec(
family="<family_name>",
package_dir=CONFIGURATION_ROOT / "<family_name>",
topology_template_path=CONFIGURATION_ROOT / "<family_name>" / "topology.template.json",
),
}
```
禁止在 CLI、CAD generator、validator 中通过硬编码路径读取构型模板。
## 3. topology template 规范
`topology.template.json` 只描述构型，不写死最终齿数或具体输出文件。
节点字段必须遵守：
```text
id
kind: gear / carrier / housing / axis
role
gear_type: external / internal / null
repeat: single / planet_count
formula_ref
stage_id
local_role
```
关系字段必须遵守：
```text
id
source
target
relation_type: external_mesh / internal_mesh / revolute_joint / fixed / rigid / coaxial
carrier_ref
mesh_id
formula_ref
stage_id
```
命名规则：
- 单级构型使用 `sun/ring/planet/carrier/housing/main_axis`。
- 多级构型使用 `s1_sun/s1_ring/s1_planet_1/s1_carrier` 这类 stage 前缀。
- repeated 节点由 runtime 展开，不要在模板里手写 `planet_1..planet_n`。
- 关系 id 必须能反查来源，例如 `sun_to_planet_external_mesh`、`s1_output_to_s2_input_rigid`。
如果要新增 relation type，必须先扩展 relation validator registry 和运动学方程生成逻辑，不能只在模板中写一个新字符串。
## 4. family 规则规范
`family.py` 只放构型族专属逻辑，例如：
- 构型专属齿数闭合公式。
- stage/component 命名辅助。
- 多级构型拓扑构造。
- 构型专属派生参数。
通用逻辑必须放到通用模块：
- 通用参数约束放 `src/parameter_constraints/` 或 parameter solver 的通用规则层。
- 通用运动学关系放 `src/kinematics.py` 和 `src/relation_validators/`。
- 通用工业装配关系放 `src/physical_validators/`。
- 通用齿轮生成放 `src/cad/gear_factory.py`。
禁止事项：
- solver 中不得写死某组齿数作为答案。
- family 规则不得读取旧 `output/runs`。
- validation 不得无条件 `overall_passed=true`。
- SimpleCADAPI/OCP 缺失时不得生成假文件。
## 5. 参数求解规范
每个构型必须明确：
- 候选变量：齿数、模数、行星数、stage 数、齿形参数等。
- 闭合公式：例如 `z_ring = z_sun + 2 * z_planet`。
- 装配条件：例如行星均布、中心距一致、邻近行星间隙。
- 边界条件：input/fixed/output 或 fixed_members。
- 评分依据：ratio_error、外径、间隙、齿数惩罚等。
最终速比必须由图驱动运动学求解得到，不能只用手写传动比公式作为通过依据。手写公式只能用于搜索优化或静态交叉验证。
## 6. PlacementSolver 规范
每个构型必须注册 placement solver，并输出统一 `PlacementPlan`。
每个真实组件必须有 `ComponentPose`：
```text
component_id
frame_id
parent_frame_id
translation_mm
rotation_axis_angle_deg
axis_xyz
center_xyz_mm
source_relation_ids
source_formula_refs
details
```
约束：
- `center_xyz_mm`、`axis_xyz`、`rotation_axis_angle_deg` 必须来自 `PlacementPlan`。
- CAD manifest 中的位姿必须与 `placement_plan.json` 一致。
- CAD generator 不允许重新计算 planet、pin、bearing、spacer、bolt 等坐标。
- stage 构型必须使用 frame + z offset，不要把绝对坐标散落在 CAD 代码里。
## 7. CAD 生成规范
CAD generator 的职责是按参数和 placement 生成真实几何：
- 齿轮使用 `gear_factory`。
- 装配坐标使用 `PlacementPlan`。
- 输出真实 `STEP/model.json/session.json/assembly_manifest.json/build_meta.json`。
- `assembly_manifest.components[*]` 必须能反查 formula node、stage/local_role、tooth_count、module、center、axis、assembled_step_path。
如果某个构型暂时没有 CAD 能力，CLI generate/run 必须明确失败，例如 `unsupported_topology_family_for_cad`，不能生成占位 STEP。
## 8. 验证规范
验证分三层：
```text
relation validators
family validators
geometry/OCP validators
```
relation validators 自动覆盖：
- `external_mesh`
- `internal_mesh`
- `revolute_joint`
- `fixed`
- `rigid`
- `coaxial`
family validators 只写构型族专属公式，例如齿数闭合、stage coupling、复合行星同轴齿轮组等。
几何验证必须读取真实 STEP/component STEP：
- STEP 存在且非空。
- 组件体积 > 0。
- 中心距、同轴、均布、轴向 offset 正确。
- OCP 正体积干涉必须失败，并报告 component pair、common volume、possible cause。
## 9. 最小验收文件
每个新构型至少提供：
- 示例 requirement：`input/requirements/reducers/<family_name>/<example>.json`
- 构型模板：`src/configurations/<family_name>/topology.template.json`
- family 逻辑：`src/configurations/<family_name>/family.py`
- placement solver：`src/placement/<family_name>.py`
- 注册项：configuration registry 和 placement registry
- 单元测试：注册、拓扑展开、参数求解、运动学、placement
- CAD 集成测试：真实 STEP/model/session/manifest、placement 一致、validation report
## 10. 推荐新增构型顺序
建议优先：
1. 复合行星 / stepped planet：一个行星轴上多个齿轮，验证图驱动和 placement 扩展能力。
2. 差动行星：支持两个输入或一个输入一个控制输入。
3. 任意 N 级 cascade：从固定两级扩展为 stage list。
4. RV / 摆线针轮：单独作为新传动族处理。
新增构型时先做 `kinematic_demo`，再做 `industrial_core`，最后再接入关节模组。
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 中写齿数和模数 | 构型和参数耦合，无法复用 |
backend/docs/行星减速器公式化系统流程.md
+360
View File
@@ -0,0 +1,360 @@
# 行星减速器公式化系统流程说明
当前 demo 的目标：把行星减速器描述成一套可被 agent 和程序共同读取的“公式化规则”，并基于这些规则完成参数求解、运动学求解、CAD 生成和验证。当前版本先覆盖单级 `simple_2k_h`：太阳轮输入、内齿圈固定、行星架输出、多个行星轮均布、直齿。
## 1. 总体流程
```text
用户需求 requirements.json
-> 构型模板 topology template
-> 参数求解 formula_instance.json
-> 运动学求解 kinematic_solution.json
-> CAD 生成 reducer.step / reducer.model.json / reducer.session.json
-> 装配读回 assembly_snapshot.json
-> 验证报告 validation_report.json
```
核心要求：
| 要求 | 说明 |
| --- | --- |
| 可共享 | Pydantic 数据模型作为统一接口，多个 agent/模块读取同一份公式实例 |
| 可计算 | 参数由求解器枚举和筛选，不写死齿数 |
| 可生成 | CAD 由 SimpleCADAPI 真实生成 STEP/model/session |
| 可反查 | 每个组件写入 `run_id`、`formula_ref`、齿数、模数、中心、轴线、啮合关系 |
| 可验证 | 验证器读回本次输出文件，重新计算并检查装配和几何 |
## 2. 构型设计
构型用图结构表达：节点是机械构件或参考对象，边是机械关系。这样同一张构型图可以服务参数求解、运动学求解、CAD 生成和验证。
### 2.1 simple_2k_h 构型图
```mermaid
graph TD
sun["sun 外齿太阳轮"]
planet["planet 外齿行星轮 x N"]
ring["ring 内齿圈"]
carrier["carrier 行星架"]
housing["housing 固定参考"]
axis["main_axis 主轴线"]
sun -- "external_mesh 外啮合" --> planet
ring -- "internal_mesh 内啮合" --> planet
planet -- "revolute_joint 行星销转动副" --> carrier
ring -- "fixed 固定" --> housing
sun -- "coaxial 同轴" --> axis
ring -- "coaxial 同轴" --> axis
carrier -- "coaxial 同轴" --> axis
```
### 2.2 节点和边规范
| 节点 | 类型 | 作用 |
| --- | --- | --- |
| `sun` | 外齿轮 | 输入件 |
| `planet` | 外齿轮，重复件 | 与太阳轮、内齿圈啮合 |
| `ring` | 内齿轮 | 固定件 |
| `carrier` | 行星架 | 输出件 |
| `housing` | 固定参考 | 接地基准 |
| `main_axis` | 轴线 | 同轴基准 |
| 边 | 含义 |
| --- | --- |
| `external_mesh(sun, planet)` | 太阳轮和行星轮外啮合 |
| `internal_mesh(ring, planet)` | 内齿圈和行星轮内啮合 |
| `revolute_joint(planet, carrier)` | 行星轮安装在行星销上，可自转 |
| `fixed(ring, housing)` | 内齿圈固定 |
| `coaxial(sun/ring/carrier, main_axis)` | 太阳轮、内齿圈、行星架同轴 |
构型合法性检查：
```text
必须存在 sun、planet、ring、carrier
sun 和 planet 必须是 external gear
ring 必须是 internal gear
必须存在 sun-planet external_mesh
必须存在 ring-planet internal_mesh
必须存在 planet-carrier revolute_joint
input / fixed / output 必须引用合法运动构件
```
## 3. 参数求解
### 3.1 输入和变量
本例需求：
```text
target_ratio = 7.5
ratio_tolerance = 0.01
input = sun
fixed = ring
output = carrier
planet_count_candidates = [3, 4, 5]
module_candidates_mm = [0.5, 0.75, 1.0, 1.25, 1.5]
max_outer_diameter_mm = 100
min_planet_neighbor_clearance_mm = 0.3
min_sun_teeth = 12
max_sun_teeth = 80
```
求解变量：`z_sun`、`z_planet`、`z_ring`、`planet_count`、`module_mm`。默认参数：压力角 20°、齿宽 8 mm、齿侧间隙 0.03 mm、齿顶系数 1.0、顶隙系数 0.25、齿圈轮缘厚度 2.5 mm。
### 3.2 约束公式
| 约束 | 公式 | 作用 |
| --- | --- | --- |
| 齿数闭合 | `z_ring = z_sun + 2 * z_planet` | 保证太阳轮、行星轮、内齿圈能同时啮合 |
| 中心距一致 | `m*(z_sun+z_planet)/2 = m*(z_ring-z_planet)/2` | 保证外啮合中心距等于内啮合中心距 |
| 行星轮均布 | `(z_sun + z_ring) % planet_count == 0` | 保证多个行星轮等分布置时齿位能对齐 |
| 轨道半径 | `orbit_radius = center_distance` | 决定行星轮中心位置 |
| 行星轮间隙 | `2*orbit_radius*sin(pi/planet_count) - m*(z_planet+2*addendum_coeff) >= min_clearance` | 避免相邻行星轮互相碰撞 |
| 齿圈外径 | `m*z_ring + 2*m*(addendum_coeff+clearance_coeff) + 2*ring_rim_thickness <= max_outer_diameter` | 满足用户外径限制 |
| 传动比 | `abs(kinematic_ratio - target_ratio) <= ratio_tolerance` | 满足减速比要求 |
### 3.3 求解方法
求解器采用枚举过滤，不写死答案：
```text
for z_sun in range(min_sun_teeth, max_sun_teeth):
for z_planet in allowed_planet_teeth:
z_ring = z_sun + 2 * z_planet
for planet_count in planet_count_candidates:
for module_mm in module_candidates_mm:
检查齿数闭合、均布、中心距、外径、间隙
调用运动学求解器计算 kinematic_ratio
保留满足 target_ratio 的候选
按 ratio_error、外径、间隙、齿数评分，选择最优候选
```
本例真实枚举结果：
```text
总候选数 = 158355
通过候选数 = 8
最终选择:
z_sun = 12
z_planet = 33
z_ring = 78
planet_count = 3
module_mm = 0.5
ratio = 7.5
center_distance = 11.25 mm
ring_outer_diameter = 45.25 mm
planet_neighbor_clearance = 1.9856 mm
```
## 4. 运动学求解
运动学求解器的作用是根据构型关系计算传动比、输出方向、固定件速度和方程残差。它不是直接写死 `i = 1 + z_ring / z_sun`，而是从啮合关系生成线性方程。
变量：
```text
omega_sun
omega_ring
omega_carrier
omega_planet
```
外啮合方程：
```text
z_sun * (omega_sun - omega_carrier)
+ z_planet * (omega_planet - omega_carrier)
= 0
```
内啮合方程：
```text
z_ring * (omega_ring - omega_carrier)
- z_planet * (omega_planet - omega_carrier)
= 0
```
边界条件：
```text
omega_input = 1
omega_fixed = 0
```
本例即 `omega_sun = 1`、`omega_ring = 0`。程序把方程整理为 `A * omega = b`，用高斯消元求解，并检查矩阵是否奇异、是否欠约束、残差是否接近 0。
本例求解结果：
```text
omega_sun = 1.0
omega_ring = 0.0
omega_carrier = 0.1333333333
omega_planet = -0.1818181818
i = omega_sun / omega_carrier = 7.5
direction = same
residual_max_abs = 0
```
## 5. CAD 生成和读回
CAD 生成器读取 `formula_instance.json`，用 SimpleCADAPI 真实生成 `sun`、`ring`、`planet_1..planet_n`、`carrier`、`housing`，并导出：
```text
reducer.step
reducer.model.json
reducer.session.json
assembly_manifest.json
assembly_snapshot.json
validation_report.json
```
读回时不只看 manifest，还读取 `reducer.model.json` 中的真实组件、约束和 placement，生成统一的 `AssemblySnapshot`。每个组件必须能反查到公式来源，例如 `component_id`、`formula_ref`、齿数、模数、中心、轴线、啮合关系和 `run_id`。
## 6. 验证方法
### 6.1 静态公式验证
静态公式验证只检查参数关系，不依赖 CAD。
| 检查项 | 本例结果 |
| --- | --- |
| 齿数为正整数 | `12, 33, 78`，通过 |
| 齿数闭合 | `78 = 12 + 2 * 33`，通过 |
| 均布条件 | `(12 + 78) / 3 = 30`，通过 |
| 中心距一致 | `sun-planet = ring-planet = 11.25 mm`，通过 |
| 行星轮间隙 | `1.9856 mm >= 0.3 mm`，通过 |
| 齿圈外径 | `45.25 mm <= 100 mm`，通过 |
### 6.2 运动学验证
运动学验证重新建立方程并求解，不直接相信实例中的传动比。
检查项：
```text
重新求解 ratio
ratio 是否等于 formula_instance
ratio 是否满足 requirements
omega_fixed 是否等于 0
输出方向是否一致
residual_max_abs 是否在容差内
```
本例结果：`ratio = 7.5`、`omega_ring = 0`、`direction = same`、`residual_max_abs = 0`，通过。
### 6.3 装配和几何位置验证
装配语义检查：
```text
sun / ring / carrier / planet_i 是否存在
ring 是否 grounded
housing 是否 fixed 到 ring
sun 是否有输入转动副
carrier 是否有输出转动副
planet_i 是否有行星销转动副
sun-planet 是否有 external_mesh 约束
ring-planet 是否有 internal_mesh 语义
```
几何位置检查：
```text
sun / ring / carrier / housing 是否同轴
planet_i 是否在 orbit_radius 上
planet_i 是否按 360 / planet_count 等分
distance(sun, planet_i) = r_sun + r_planet
distance(ring, planet_i) = r_ring - r_planet
STEP / model / session 是否存在且非空
CAD 实体体积是否大于 0
```
本例：`r_sun = 3.0 mm`、`r_planet = 8.25 mm`、`r_ring = 19.5 mm`，所以外啮合和内啮合中心距都等于 `11.25 mm`。
### 6.4 几何干涉检测
中心距正确不代表齿轮实体一定不穿模，所以加入 OpenCascade/OCP 的真实 B-Rep 检测。
检测流程：
```text
1. 把装配后的每个组件单独导出 STEP
2. OCP 读取每个组件 STEP
3. 检查 shape 是否有效、体积是否大于 0
4. 用包围盒筛掉明显不相交的零件对
5. 对可能相交的零件对执行 Boolean Common
6. 计算公共体积 common_volume
7. common_volume > 1e-6 mm^3 判定为穿模
```
判定公式：
```text
common_shape = BooleanCommon(shape_a, shape_b)
common_volume = Volume(common_shape)
common_volume <= 1e-6 mm^3 通过
common_volume > 1e-6 mm^3 失败
```
如果失败，可以导出公共干涉体 STEP，例如 `common_planet_1_vs_ring.step`，用于直接查看两个零件真实重叠的位置。
本例初始版本检测到：
```text
ring vs planet_1: common_volume ≈ 19.331 mm^3
ring vs planet_2: common_volume ≈ 19.331 mm^3
ring vs planet_3: common_volume ≈ 19.331 mm^3
```
定位结果：齿数、中心距、传动比都正确，问题是内齿圈、太阳轮、行星轮三者齿槽相位没有同时对准。当前规则是行星轮按中心角和齿数关系补偿自转相位，内齿圈相位按行星轮齿数奇偶选择：
```text
internal_ring_phase_correction_deg = 180 / z_ring, if z_planet is odd
internal_ring_phase_correction_deg = 0, if z_planet is even
planet_phase_deg = 180 - 180 / z_planet + planet_center_angle_deg * (1 + z_sun / z_planet)
```
修正后：`OCP interferences = []`、`overall_passed = true`、`32 passed`、`0 failed`。
### 6.5 齿轮啮合检测
齿轮啮合不是只看中心距，而是分四层检查：
| 层级 | 检查内容 |
| --- | --- |
| 参数层 | `module`、`pressure_angle`、`tooth_form` 一致，齿数闭合正确 |
| 中心距层 | 外啮合 `distance = r_sun + r_planet`，内啮合 `distance = r_ring - r_planet` |
| 装配语义层 | CAD 中存在 `external_mesh` 和 `internal_mesh` 关系 |
| 实体层 | OCP 检查真实齿形 `common_volume <= 1e-6 mm^3` |
如果参数层和中心距层通过，但实体层失败，通常说明问题在齿形相位、齿顶齿根参数、齿侧间隙或内齿轮生成算法。本例就是通过实体层检测发现并修正了内齿圈相位问题。
## 7. 当前结果
本例最终参数：
```text
z_sun = 12
z_planet = 33
z_ring = 78
planet_count = 3
module_mm = 0.5
ratio = 7.5
ring_outer_diameter = 45.25 mm
planet_neighbor_clearance = 1.9856 mm
```
最终验证结果：
```text
overall_passed = true
32 passed
0 failed
```
当前已覆盖：构型描述、参数求解、运动学求解、CAD 真实生成、装配读回、静态公式验证、运动学验证、几何位置验证、OCP 实体干涉检测、齿轮啮合分层检测。
当前未覆盖：齿根弯曲强度、齿面接触强度、轴承寿命、润滑和热分析、制造公差、全周期运动采样、精确齿侧间隙测量。