Split project into frontend and backend

2026-08-13 16:24:36 +08:00
commit f051146486
274 changed files with 953932 additions and 0 deletions
@@ -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 实体干涉检测、齿轮啮合分层检测。
+
+当前未覆盖：齿根弯曲强度、齿面接触强度、轴承寿命、润滑和热分析、制造公差、全周期运动采样、精确齿侧间隙测量。