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,109 @@
+# Agent 构型开发规范
+
+当用户要求新增或维护减速器构型时，必须遵守本文档。不要直接在 solver、CAD、validator 中临时硬编码新构型。
+
+## 必须新增或检查的内容
+
+每个构型族必须具备：
+
+```text
+src/configurations/<family_name>/
+  family.py
+  topology.template.json
+  placement_rules.py
+input/requirements/reducers/<family_name>/
+src/placement/<family_name>.py
+```
+
+并且必须注册：
+
+- `src/configurations/registry.py`
+- `src/placement/registry.py`
+
+## 开发顺序
+
+按以下顺序做，不要跳步：
+
+```text
+requirement
+-> topology.template.json
+-> configuration registry
+-> topology runtime check
+-> parameter solving rule
+-> graph-driven kinematics
+-> placement solver
+-> CAD generator support
+-> validators
+-> tests
+-> examples
+```
+
+## Topology 要求
+
+节点必须写清楚：
+
+```text
+id / kind / role / gear_type / repeat / formula_ref / stage_id / local_role
+```
+
+关系必须写清楚：
+
+```text
+id / source / target / relation_type / carrier_ref / mesh_id / formula_ref / stage_id
+```
+
+只允许使用已经注册的 relation type：
+
+```text
+external_mesh
+internal_mesh
+revolute_joint
+fixed
+rigid
+coaxial
+```
+
+如果需要新 relation type，先扩展 relation validator 和运动学方程生成，不能只改模板。
+
+## Placement 要求
+
+所有 CAD 组件的位姿必须来自 `PlacementPlan`。每个组件必须有：
+
+```text
+component_id
+frame_id
+translation_mm
+rotation_axis_angle_deg
+axis_xyz
+center_xyz_mm
+source_formula_refs
+```
+
+CAD generator 不能重新计算 planet、pin、bearing、spacer、bolt 坐标。manifest 与 placement plan 不一致必须验证失败。
+
+## 参数和运动学要求
+
+- 参数求解必须枚举候选并过滤，不能写死答案。
+- family 专属公式放在 `family.py` 或 family rules。
+- 最终 ratio 必须由图驱动运动学求解得到。
+- fixed/rigid/input/output 边界必须从 requirement 或 topology 得到。
+
+## CAD 和验证要求
+
+- 生成失败必须真实失败，不允许输出假 STEP。
+- `simplecadapi` 不可用时不得跳过后声称成功。
+- OCP/PythonOCC 是实体干涉最终裁判。
+- `validation_report.overall_passed` 只能由所有 check 结果汇总得到。
+- 失败时必须返回失败 check code、actual、expected；几何干涉必须返回 component pair 和 possible cause。
+
+## 最小测试
+
+每个新构型至少补：
+
+- registry 能加载构型。
+- topology 能展开。
+- parameter solver 能找到目标 ratio。
+- kinematics ratio、direction、fixed speed 正确。
+- placement plan 覆盖所有 manifest component。
+- CAD 能真实生成 STEP/model/session。
+- validation report 通过或明确报告真实失败原因。