# 构型开发规范

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