# 行星减速器公式化系统流程说明

当前 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 实体干涉检测、齿轮啮合分层检测。

当前未覆盖：齿根弯曲强度、齿面接触强度、轴承寿命、润滑和热分析、制造公差、全周期运动采样、精确齿侧间隙测量。