reducers/backend/docs/行星减速器公式化系统流程.md

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

当前 demo 的目标：把行星减速器描述成一套可被 agent 和程序共同读取的“公式化规则”，并基于这些规则完成参数求解、运动学求解、CAD 生成和验证。当前版本先覆盖单级 simple_2k_h：太阳轮输入、内齿圈固定、行星架输出、多个行星轮均布、直齿。

1. 总体流程

用户需求 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 构型图

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)	太阳轮、内齿圈、行星架同轴

构型合法性检查：

必须存在 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 输入和变量

本例需求：

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 求解方法

求解器采用枚举过滤，不写死答案：

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、外径、间隙、齿数评分，选择最优候选

本例真实枚举结果：

总候选数 = 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，而是从啮合关系生成线性方程。

变量：

omega_sun
omega_ring
omega_carrier
omega_planet

外啮合方程：

z_sun * (omega_sun - omega_carrier)
+ z_planet * (omega_planet - omega_carrier)
= 0

内啮合方程：

z_ring * (omega_ring - omega_carrier)
- z_planet * (omega_planet - omega_carrier)
= 0

边界条件：

omega_input = 1
omega_fixed = 0

本例即 omega_sun = 1、omega_ring = 0。程序把方程整理为 A * omega = b，用高斯消元求解，并检查矩阵是否奇异、是否欠约束、残差是否接近 0。

本例求解结果：

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，并导出：

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 运动学验证

运动学验证重新建立方程并求解，不直接相信实例中的传动比。

检查项：

重新求解 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 装配和几何位置验证

装配语义检查：

sun / ring / carrier / planet_i 是否存在
ring 是否 grounded
housing 是否 fixed 到 ring
sun 是否有输入转动副
carrier 是否有输出转动副
planet_i 是否有行星销转动副
sun-planet 是否有 external_mesh 约束
ring-planet 是否有 internal_mesh 语义

几何位置检查：

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 检测。

检测流程：

1. 把装配后的每个组件单独导出 STEP
2. OCP 读取每个组件 STEP
3. 检查 shape 是否有效、体积是否大于 0
4. 用包围盒筛掉明显不相交的零件对
5. 对可能相交的零件对执行 Boolean Common
6. 计算公共体积 common_volume
7. common_volume > 1e-6 mm^3 判定为穿模

判定公式：

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，用于直接查看两个零件真实重叠的位置。

本例初始版本检测到：

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

定位结果：齿数、中心距、传动比都正确，问题是内齿圈、太阳轮、行星轮三者齿槽相位没有同时对准。当前规则是行星轮按中心角和齿数关系补偿自转相位，内齿圈相位按行星轮齿数奇偶选择：

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. 当前结果

本例最终参数：

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

最终验证结果：

overall_passed = true
32 passed
0 failed

当前已覆盖：构型描述、参数求解、运动学求解、CAD 真实生成、装配读回、静态公式验证、运动学验证、几何位置验证、OCP 实体干涉检测、齿轮啮合分层检测。

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