220 lines
6.7 KiB
Markdown
220 lines
6.7 KiB
Markdown
# 构型开发规范
|
||
|
||
本文档说明如何在本项目中新增或维护行星减速器构型。目标是让复合行星、多级串联、差动行星等新构型沿同一套结构扩展，避免把公式、位姿、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`，最后再接入关节模组。
|