reducers/backend/docs/configuration-development-standard.md

构型开发规范

本文档说明如何在本项目中新增或维护行星减速器构型。目标是让复合行星、多级串联、差动行星等新构型沿同一套结构扩展，避免把公式、位姿、CAD 和验证逻辑散落到各个模块中。

1. 总流程

新增构型必须按以下链路接入：

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. 构型目录规范

每个构型族必须有独立目录：

src/configurations/<family_name>/
  family.py
  topology.template.json
  placement_rules.py
input/requirements/reducers/<family_name>/
tests/

必须在 src/configurations/registry.py 中注册：

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 只描述构型，不写死最终齿数或具体输出文件。

节点字段必须遵守：

id
kind: gear / carrier / housing / axis
role
gear_type: external / internal / null
repeat: single / planet_count
formula_ref
stage_id
local_role

关系字段必须遵守：

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：

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. 验证规范

验证分三层：

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，最后再接入关节模组。