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,113 @@
+# Topology JSON Authoring Guide
+
+这份说明给只负责创建构型 JSON 的机械工程师使用。构型 JSON 只描述机械构件和关系，不填写齿数、模数、目标速比、三维坐标或输出文件。
+
+## 文件位置
+
+```text
+src/configurations/<family_name>/topology.template.json
+```
+
+`family_name` 必须和 JSON 顶层 `family` 一致。
+
+## 顶层字段
+
+```json
+{
+  "template_id": "<family>_v0_1",
+  "family": "<family>",
+  "description": "one sentence",
+  "nodes": [],
+  "relations": []
+}
+```
+
+## node 字段
+
+每个 node 表示一个构件或参考对象：
+
+```json
+{
+  "id": "sun",
+  "kind": "gear",
+  "role": "sun",
+  "gear_type": "external",
+  "repeat": "single",
+  "formula_ref": "nodes.sun",
+  "stage_id": null,
+  "local_role": "sun"
+}
+```
+
+填写规则：
+
+- `kind`: `gear`、`carrier`、`housing`、`axis`
+- `gear_type`: 外齿轮填 `external`，内齿圈填 `internal`，非齿轮填 `null`
+- `repeat`: 单个构件填 `single`，按行星数量重复的行星轮填 `planet_count`
+- `stage_id/local_role`: 多级构型用于表达级内角色；单级可以省略或填 `null`
+
+不要在模板里手写 `planet_1..planet_n`。只写一个 `planet`，并设置 `repeat = planet_count`。
+
+## relation 字段
+
+每个 relation 表示构件之间的机械关系：
+
+```json
+{
+  "id": "sun_planet_external_mesh",
+  "source": "sun",
+  "target": "planet",
+  "relation_type": "external_mesh",
+  "carrier_ref": "carrier",
+  "mesh_id": "sun_planet",
+  "formula_ref": "relations.sun_planet_external_mesh",
+  "stage_id": null
+}
+```
+
+允许的 `relation_type`：
+
+```text
+external_mesh
+internal_mesh
+revolute_joint
+coaxial
+fixed
+rigid
+```
+
+常用关系：
+
+- `sun --external_mesh--> planet`，`carrier_ref = carrier`
+- `ring --internal_mesh--> planet`，`carrier_ref = carrier`
+- `planet --revolute_joint--> carrier`
+- `sun/ring/carrier --coaxial--> main_axis`
+- `ring --fixed--> housing`
+- `s1_output --rigid--> s2_input`
+
+## 不要填写的内容
+
+不要在 topology JSON 中填写：
+
+- 目标速比
+- 齿数
+- 模数
+- 行星数量候选
+- 坐标和轴线
+- STEP 路径
+- 材料和颜色
+- 验证结果
+
+这些内容分别属于 requirement、参数求解、PlacementPlan、CAD 输出和 validation report。
+
+## 提交前检查
+
+- `template_id` 唯一。
+- `family` 和目录名一致。
+- 所有 relation 的 `source/target/carrier_ref` 都能在 nodes 中找到。
+- 齿轮 `gear_type` 正确。
+- 行星轮使用 `repeat = planet_count`。
+- 行星啮合填写了 `carrier_ref`。
+- 所有主运动构件都有 `coaxial` 到 `main_axis`。
+- 固定关系用 `fixed`，刚性连接用 `rigid`。
+- 没有使用未注册 relation type。