Split project into frontend and backend

backend/README.md

@@ -0,0 +1,124 @@
+# Planetary Reducer System Demo
+
+## 简介
+
+这是一个面向行星减速器和关节模组的公式化设计、生成与验证 demo。系统从 `input/` 中的需求 JSON 出发，先建立构型图，再枚举并求解齿轮参数，随后用图驱动运动学方程验证传动比和转向，最后调用 SimpleCADAPI 真实生成 STEP/model/session，并用读回的装配数据、统一 `PlacementSolver` 位姿计划和 OCP/PythonOCC 几何检测生成验证报告。
+
+当前主要支持单级 `simple_2k_h`、两级串联 `simple_2k_h_cascade`、`ferguson_wolfrom` 独立减速器，以及基于电机 STEP 和外壳资产的关节模组装配。关节模组当前只支持同轴输入/输出接口的 `simple_2k_h` 和 `simple_2k_h_cascade`；`ferguson_wolfrom` 的输入位于偏心行星销轴区域，暂不适配当前同轴电机和外壳接口。项目刻意区分输入、输出和过程文档：所有源需求和外部资产放在 `input/`，所有生成结果只进入 `output/`，说明文档和阶段报告放在 `progress/`。如果 CAD 或 OCP 环境不可用，生成和验证会真实失败并输出错误，不生成假 STEP 或假验证报告。
+
+This project formalizes, solves, generates, and validates planetary reducers and
+joint modules with real parameter solving, real kinematics, real CAD generation,
+and real geometry checks.
+
+## Project Layout
+
+```text
+input/      user requirements and source assets
+output/     generated run outputs only
+progress/   documents, reports, and working notes
+src/        implementation
+tests/      regression tests
+```
+
+Reducer configurations live under:
+
+```text
+src/planetary_reducer/configurations/
+```
+
+Reducer-internal component poses are solved by:
+
+```text
+src/planetary_reducer/placement/
+```
+
+- `src/models.py`：定义系统中所有核心数据模型。
+- `src/cli.py`：命令行入口，负责 `run`、`joint-run`、`auto-joint-run` 等流程。
+- `src/configurations/`：集中管理减速器构型，比如单级和两级串联。
+- `src/placement/`：统一计算各零件的三维位置和姿态。
+- `src/parameter_solver.py`：根据需求枚举并求解齿数、模数、行星数量等参数。
+- `src/kinematics.py`：根据构型图建立运动方程，验证传动比和转向。
+- `src/cad/`：调用 SimpleCADAPI 生成真实 STEP、model.json 和装配 manifest。
+- `src/validators.py`：总验证入口，统一执行公式、运动学、装配、位姿和几何检查。
+- `src/relation_validators/`：验证构型图中的啮合、转动副、固定、刚性和同轴关系。
+- `src/physical_validators/`：验证工业装配中的轴承、销轴、螺栓、配合和间隙关系。
+- `src/joint_module/`：生成并验证由电机、外壳和行星减速器组成的完整关节模组。
+
+## CLI
+
+Run a reducer:
+
+```bash
+PYTHONPATH=src \
+/Users/lk/miniconda3/bin/python -m planetary_reducer.cli run \
+  --input input/requirements/reducers/simple_2k_h/simple_2kh_industrial_ratio_7p5_spur.json \
+  --output output/runs/industrial_ratio_7p5_spur
+```
+
+Run a joint module:
+
+```bash
+PYTHONPATH=src \
+/Users/lk/miniconda3/bin/python -m planetary_reducer.cli joint-run \
+  --input input/requirements/joint_modules/3500_motor_housing.json \
+  --output output/runs/joint_3500_motor_housing
+```
+
+Auto-design a joint module from motor STEP and housing Python:
+
+```bash
+PYTHONPATH=src \
+/Users/lk/miniconda3/bin/python -m planetary_reducer.cli auto-joint-run \
+  --motor-step input/assets/motors/3500_motor_part2.step \
+  --housing-python input/assets/housings/gear_housing.py \
+  --output output/runs/auto_joint_3500
+```
+
+The CLI intentionally accepts `--input` only under `input/` and `--output` only
+under `output/`.
+
+List all formula-driven CAD part generators copied from SimpleCADAPI:
+
+```bash
+PYTHONPATH=src \
+/Users/lk/miniconda3/bin/python -m planetary_reducer.cli list-parts
+```
+
+Generate one standalone parametric part:
+
+```bash
+PYTHONPATH=src \
+/Users/lk/miniconda3/bin/python -m planetary_reducer.cli generate-part \
+  --part roller_chain_sprocket \
+  --parameters '{"n_teeth": 12, "chain_pitch": 6.35, "roller_diameter": 3.3, "sprocket_thickness": 3.0, "bore_radius": 1.2}' \
+  --output output/runs/parts/roller_chain_sprocket
+```
+
+## Run Output
+
+Reducer runs use:
+
+```text
+output/runs/<run>/
+  input_snapshot/
+  formula/
+  kinematics/
+  placement/
+  cad/
+  validation/
+  exports/
+```
+
+Important files include:
+
+```text
+formula/formula_instance.json
+kinematics/kinematic_solution.json
+placement/placement_plan.json
+cad/reducer.step
+cad/assembly_manifest.json
+validation/validation_report.json
+```
+
+`placement/placement_plan.json` is the reducer-internal pose source of truth.
+`assembly_manifest.json` must match it.