# 接口调用履历

本文档用于快速梳理当前项目里“前端请求 -> WASM 导出函数 -> C++ 分发层 -> 业务实现文件”的执行链路，便于对照源码阅读。

## 1. 建议先看的总入口

建议按下面顺序看文件：

1. `src/main.cpp`
   说明这个工程最终是一个 WASM 可执行模块，`main` 主要用于本地构建提示。
2. `src/smart_json_wrapper.cpp`
   这里是所有 WASM 导出函数的真正入口。
3. `include/KinematicsWebAPI.h`
   业务接口类声明，能看见分发结构。
4. `src/api/KinematicsWebAPI.Core.cpp`
   业务 JSON 请求的总分发入口。
5. `src/api/KinematicsWebAPI.*Commands.cpp`
   按功能拆开的命令处理层。
6. 对应底层业务文件
   机器人看 `src/Robot.cpp`、`src/RobotManager.cpp`
   SPC 看 `src/spc_core.cpp`
   四连杆看 `src/FourBarMechanism/`
   四足看 `src/QuadrupedRobotSimulation/`

## 2. 顶层 WASM 导出接口

### 2.1 业务接口导出

前端主调的是这两个导出函数：

- `init_func`
- `func`

调用链如下：

```text
JS/HTML
-> public/wasm/smart_api_wrapper.js
-> WASM 导出函数 init_func / func
-> src/smart_json_wrapper.cpp
-> KinematicsWebAPI
-> src/api/KinematicsWebAPI.Core.cpp
-> 各功能 Commands 文件
-> 底层业务实现
```

### 2.2 智能数学/测试接口导出

这一套和业务接口是并行的另一条线：

- `smart_process_json`
- `smart_get_function_list`
- `smart_get_function_info`
- `smart_test_match`
- `smart_get_version`

调用链如下：

```text
JS/HTML
-> public/wasm/smart_api_wrapper.js
-> smart_* 导出函数
-> src/smart_json_wrapper.cpp
-> SmartJsonProcessor / FunctionRegistry
-> math_utils / 注册的测试函数
```

这一套主要是“数学函数演示 + 智能参数匹配”，不走 `KinematicsWebAPI`。

## 3. 业务总分发链路

### 3.1 初始化

`src/smart_json_wrapper.cpp` 中：

- `init_func()`
  - 首次调用时创建全局单例 `global_server = new KinematicsWebAPI()`
  - `KinematicsWebAPI` 构造函数里会继续调用 `KinematicsWebAPI::init_func()`

`src/api/KinematicsWebAPI.Core.cpp` 中：

- `KinematicsWebAPI::init_func()`
  - 从 `include/URDFStrings.h` 读取默认 URDF
  - 调用 `RobotManager::initRobot(...)`
  - 默认会初始化两个机器人实例

### 3.2 请求处理

`src/smart_json_wrapper.cpp`

- `func(const char* json_request)`
  - 把前端 JSON 字符串转成 `std::string`
  - 调 `global_server->func(request_str)`

`src/api/KinematicsWebAPI.Core.cpp`

- `KinematicsWebAPI::func(std::string sanitized_body)`
  - 解析 JSON
  - 取出 `msg / req_code / req_from / req_cmd / req_param`
  - 调 `dispatchCommand(req_cmd, req_param)`
  - 最后统一封装为 `utils::create_api_response(...)`

- `KinematicsWebAPI::dispatchCommand(...)`
  - 机器人类命令 -> `handleRobotCommand(...)`
  - SPC -> `handleSpcCommand(...)`
  - 四连杆 -> `handleFourBarCommand(...)`
  - 四足 -> `handleQuadrupedCommand(...)`

## 4. 机器人相关接口履历

机器人相关命令都在：

- `src/api/KinematicsWebAPI.RobotCommands.cpp`

底层核心文件：

- `src/RobotManager.cpp`
- `src/Robot.cpp`

### 4.1 `Cmd_InitRobot`

调用履历：

```text
func
-> KinematicsWebAPI::dispatchCommand
-> KinematicsWebAPI::handleRobotCommand
-> Cmd_InitRobot 分支
-> utils::base64_to_urdf
-> utils::validate_urdf_base64
-> RobotManager::initRobot
-> Robot::initRobot
```

底层细节：

- `RobotManager::initRobot`
  - 创建 `std::shared_ptr<Robot>`
  - 调 `robot->initRobot(urdf_robot)`
  - 生成或使用 `robot_uuid`
  - 计算 URDF 哈希
  - 调 `_validateKinematics(robot)` 做基本正解验证
  - 存入 `_kinematics_table`

- `Robot::initRobot`
  - `kdl_parser::treeFromString(...)`
  - `tree.getChain("base", "tool0", kinematicChain)`
  - `parseJointChildLinkUuidsFromUrdf(...)`
  - 初始化 FK / IK 求解器

### 4.2 `Cmd_GetRobot`

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> Cmd_GetRobot
-> RobotManager::getRobot
-> Robot::isInitialized / Robot::getNumberOfJoints
```

### 4.3 `Cmd_RemoveRobot`

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> Cmd_RemoveRobot
-> RobotManager::removeRobot
```

### 4.4 `Cmd_ListRobots`

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> Cmd_ListRobots
-> RobotManager::listRobots
-> detail=true 时内部还会调 RobotManager::_validateKinematics
-> Robot::calculateFK_TCP
```

### 4.5 `Cmd_Kinematics_forward_pose_str`

用途：

- 输入一组 6 轴关节角
- 输出 TCP 位姿

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> Cmd_Kinematics_forward_pose_str
-> RobotManager::getRobot
-> Robot::parseJointString
-> Robot::calculateFK_TCP
```

`Robot::calculateFK_TCP` 内部主要做：

- 关节数组转 `KDL::JntArray`
- `fkSolver->JntToCart(...)`
- 取出位置和四元数

### 4.6 `Cmd_Kinematics_forward_all_joints`

用途：

- 输入一帧或多帧关节角列表
- 输出每个关节节点的位姿，组织成前端使用的 `OPERATION.frames[].objStates`

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> Cmd_Kinematics_forward_all_joints
-> RobotManager::getRobot
-> Robot::handleKinematicsForwardAllJoints
-> Robot::parseJointListString
-> Robot::kinematicsForwardAllJointsList
-> Robot::forwardKinematics
-> Robot::getJointUuidByIndex
```

补充说明：

- `Robot::handleKinematicsForwardAllJoints(...)`
  - 遍历每一帧关节角
  - 每帧都调一次 `kinematicsForwardAllJointsList(...)`
- `Robot::kinematicsForwardAllJointsList(...)`
  - 调 `forwardKinematics(...)`
  - 把 6 个关节的位姿打包成 `objStates`

### 4.7 `Cmd_Kinematics_inverse_pose_str_NoDifference`

用途：

- 输入一个或多个姿态点
- 不做插补，直接逐点逆解

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> Cmd_Kinematics_inverse_pose_str_NoDifference
-> RobotManager::getRobot
-> Robot::inversePoseStrNoDifference
-> Robot::parsePoseString
-> Robot::parseJointString
-> Robot::inverse(vector)
-> Robot::calculateIK_LMA
```

### 4.8 `Cmd_Kinematics_inverse_pose_str`

用途：

- 输入多个姿态点
- 相邻姿态间先自动插补轨迹，再逐点逆解

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> Cmd_Kinematics_inverse_pose_str
-> RobotManager::getRobot
-> Robot::inversePoseStr
-> Robot::parsePoseString
-> Robot::parseJointString
-> Robot::calculateAutoSteps
-> Robot::trajectoryPlanning
-> Robot::inverse(vector)
-> Robot::calculateIK_LMA
```

关键点：

- `calculateAutoSteps(...)` 根据位置差和姿态差自动算插补点数
- `trajectoryPlanning(...)` 调 KDL 轨迹插补
- 每个插补点再进入 `inverse(...)`

### 4.9 `Cmd_Kinematics_inverse_pose_str_2PSteps`

用途：

- 只取两个姿态点
- 按指定 `steps` 做轨迹插补

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> Cmd_Kinematics_inverse_pose_str_2PSteps
-> RobotManager::getRobot
-> Robot::inversePoseStr2PSteps
-> Robot::parsePoseString
-> Robot::parseJointString
-> Robot::trajectoryPlanning(..., steps)
-> Robot::inverse(vector)
-> Robot::calculateIK_LMA
```

### 4.10 `Cmd_SelectCraftTree` / `Cmd_AddOperationTree`

这两个目前是轻量占位接口。

调用履历：

```text
func
-> dispatchCommand
-> handleRobotCommand
-> 直接在 KinematicsWebAPI.RobotCommands.cpp 内拼装返回 JSON
```

当前没有继续下钻到独立业务类。

## 5. SPC 接口履历

命令文件：

- `src/api/KinematicsWebAPI.SpcCommands.cpp`

底层文件：

- `include/spc_core.h`
- `src/spc_core.cpp`

### 5.1 `Cmd_Spc`

调用履历：

```text
func
-> dispatchCommand
-> handleSpcCommand
-> SpcCalculator::Spc
-> SpcTestData::FromJson
-> SpcCalculator::CalculateXR
-> SpcCalculator::CalculateXS
-> SpcCalculator::CalculateCpk
-> SpcCalculator::RoundSpcData
-> SpcResultJson::ToJson
```

底层职责分布：

- `SpcTestData::FromJson`
  - 从请求中读取 `n / k / usl / lsl / x`
- `CalculateXR`
  - 算 X-R 控制图
- `CalculateXS`
  - 算 X-S 控制图
- `CalculateCpk`
  - 算过程能力指数和直方图数据
- `RoundSpcData`
  - 做统一小数位保留

## 6. 四连杆接口履历

命令文件：

- `src/api/KinematicsWebAPI.FourBarCommands.cpp`

底层文件：

- `include/FourBarMechanism/CrankSliderMechanism.h`
- `src/FourBarMechanism/CrankSliderMechanism.cpp`

### 6.1 `Cmd_FourBar_CrankSlider`

调用履历：

```text
func
-> dispatchCommand
-> handleFourBarCommand
-> createCrankSliderMechanism
-> CrankSliderMechanism::setL_AB / setL_BS / setS_OFS
-> CrankSliderMechanism::validateParameters
-> CrankSliderMechanism::calculate
-> CrankSliderMechanism::getTrajectoryPoints
-> CrankSliderMechanism::getSliderTrajectory
```

说明：

- 命令层负责把参数取出来、调机制对象、再把结果组装成 JSON
- 真正的机构计算在 `src/FourBarMechanism/CrankSliderMechanism.cpp`

### 6.2 `Cmd_FourBar_CrankSlider_Simulate`

用途：

- 输入曲柄滑块初始参数、起始角度、结束角度、总时长和步长时间
- 一次性生成整段仿真帧数据，适合前端播放、导出轨迹和离线验证

调用履历：

```text
func
-> dispatchCommand
-> handleFourBarCommand
-> createCrankSliderMechanism
-> CrankSliderMechanism::setL_AB / setL_BS / setS_OFS
-> CrankSliderMechanism::validateParameters
-> for each frame:
   -> CrankSliderMechanism::calculate(currentAngleDeg)
-> CrankSliderMechanism::getTrajectoryPoints
-> CrankSliderMechanism::getSliderTrajectory
```

主要入参：

- `L_AB`：曲柄长度
- `L_BS`：连杆长度
- `S_OFS`：滑块偏移
- `startAngleDeg`：起始曲柄角度
- `endAngleDeg`：结束曲柄角度
- `duration`：仿真总时长，单位秒
- `stepTime`：仿真步长时间，单位秒

主要出参：

- `frames[]`：逐帧仿真数据，每帧包含 `frame`、`time`、`angleDeg`、`points`、`poses`、`angles`
- `trajectory`：B 点整段轨迹
- `slider_trajectory`：S 点整段滑块轨迹

### 6.3 `Cmd_FourBar_Simulate`

用途：

- 统一仿真 PDPS 连杆定义界面中的 `PRRR / RPRR / RRRP / RRRR` 四类结构
- 输入机构类型、起始输入、结束输入、总时长和步长时间
- 一次性返回逐帧点位、姿态、角度和轨迹，适合前端 Three.js 播放和 ECharts 曲线验证

调用履历：

```text
func
-> dispatchCommand
-> handleFourBarCommand
-> simulateUnifiedFourBar
-> 按 mechanismType 创建或调用对应机构类
-> validateParameters
-> for each frame:
   -> calculate(currentInput)
-> 组装 frames / trajectory / parameters
```

类型映射：

- `RRRP`：调用 `CrankSliderMechanism`，角度驱动曲柄滑块正解
- `PRRR`：调用 `SliderCrankMechanism`，滑块位移驱动曲柄滑块逆解
- `RPRR`：调用 `CrankRockingBlockMechanism_Forward`，当前按曲柄摇块正解承接
- `RRRR`：调用 `FourBarMechanism`，角度驱动四转副四杆正解

主要公共入参：

- `mechanismType`：`PRRR`、`RPRR`、`RRRP`、`RRRR`
- `startValue` / `endValue`：统一输入范围，角度驱动类型表示角度，`PRRR` 表示滑块 X
- `duration`：仿真总时长，单位秒
- `stepTime`：仿真步长时间，单位秒

各类型参数：

- `RRRP`：`L_AB`、`L_BS`、`S_OFS`
- `PRRR`：`L_AB`、`L_BS`、`S_OFS`，也可使用 `startSliderX` / `endSliderX`
- `RPRR`：`OA`、`AB`、`OC`
- `RRRR`：`L1`、`L2`、`L3`、`L4`

主要出参：

- `mechanismType`：实际仿真的机构类型
- `inputName`：当前输入字段名，`angleDeg` 或 `sliderX`
- `frames[]`：逐帧仿真数据，每帧包含 `frame`、`time`、`inputValue`、`points`、`poses`、`angles`
- `trajectory`：主运动点轨迹
- `slider_trajectory`：滑块轨迹，适用于 `RRRP / PRRR`
- `alternative_trajectory`：备选逆解轨迹，适用于 `PRRR`
- `trajectory_c`：C 点轨迹，适用于 `RRRR`
- `crank_circle`：曲柄端点轨迹，适用于 `RPRR / RRRR`
- `rocker_trajectory`：摇块轨迹，适用于 `RPRR`

注意：

- `RPRR` 当前先复用现有曲柄摇块正解类，PDPS 中输入/输出链节的方向、坐标系和安装约定后续如有更精确资料，可继续对齐参数语义。

## 7. 四足机器人接口履历

命令文件：

- `src/api/KinematicsWebAPI.QuadrupedCommands.cpp`

中间帮助层：

- `include/QuadrupedRobotSimulation/KinematicsHelper.h`
- `src/QuadrupedRobotSimulation/KinematicsHelper.cpp`

底层实现文件：

- `src/QuadrupedRobotSimulation/KinematicsSimulation.cpp`
- `src/QuadrupedRobotSimulation/KinematicsReverse.cpp`
- `src/QuadrupedRobotSimulation/CompleteJsonExporter.cpp`
- `src/QuadrupedRobotSimulation/RobotConfig.cpp`
- `src/QuadrupedRobotSimulation/SharedGeometry.cpp`

### 7.1 `Cmd_QuadrupedRobot_CalculateAllPointsFromMotorAngles`

用途：

- 输入电机角
- 反推出各关键点坐标

调用履历：

```text
func
-> dispatchCommand
-> handleQuadrupedCommand
-> KinematicsHelper::QuadrupedRobot_CalculateAllPointsFromMotorAngles
-> KinematicsHelper::RobotGaitDataManagerFromJson
-> ReverseKinematicsCalculator
-> ReverseKinematicsCalculator::CalculateAllPointsFromMotorAnglesJsonStr
-> json::parse
```

说明：

- 数据管理入口在 `RobotGaitDataManagerFromJson(...)`
- 反解主逻辑在 `src/QuadrupedRobotSimulation/KinematicsReverse.cpp`

### 7.2 `Cmd_QuadrupedRobot_PerformForwardKinematics`

用途：

- 输入步态/系统参数
- 正向生成四足机器人整段步态轨迹

调用履历：

```text
func
-> dispatchCommand
-> handleQuadrupedCommand
-> KinematicsHelper::QuadrupedRobot_PerformForwardKinematics
-> KinematicsHelper::RobotGaitDataManagerFromJson
-> QuadrupedRobotConfiguration
-> QuadrupedRobotSimulation
-> QuadrupedRobotSimulation::CalculateAllTrajectoriesJsonString
-> CompleteJsonExporter::ExportCompleteDataJsonString
-> json::parse
```

说明：

- 配置拼装在 `RobotConfig.cpp`
- 轨迹生成主体在 `KinematicsSimulation.cpp`
- 最终 JSON 打包在 `CompleteJsonExporter.cpp`

## 8. 智能数学接口履历

这部分不是机器人业务，但也常会看到。

核心文件：

- `src/smart_json_wrapper.cpp`
- `include/smart_json_wrapper.h`
- `src/math_utils.cpp`

### 8.1 `smart_process_json`

调用履历：

```text
smart_process_json
-> SmartJsonProcessor::processRequest
-> 解析 req_cmd
-> FunctionRegistry::getFunction
-> SmartJsonProcessor::parseJsonParams
-> FunctionRegistry::smartMatchParams
-> FunctionInfo::validateParams
-> function handler lambda
-> math_utils 中的 add/subtract/multiply/divide/fibonacci 等
```

### 8.2 `smart_get_function_list`

调用履历：

```text
smart_get_function_list
-> SmartJsonProcessor::getAvailableFunctions
-> FunctionRegistry::getAllFunctions
```

### 8.3 `smart_get_function_info`

调用履历：

```text
smart_get_function_info
-> SmartJsonProcessor::getFunctionInfo
-> FunctionRegistry::getFunction
```

### 8.4 `smart_test_match`

调用履历：

```text
smart_test_match
-> 解析 req_cmd
-> FunctionRegistry::getFunction
-> SmartJsonProcessor::parseJsonParams
-> FunctionRegistry::smartMatchParams
-> 返回匹配结果，不真正执行业务函数
```

## 9. 文件职责一览

### 9.1 入口层

- `src/main.cpp`
  - 构建入口，基本不承接业务
- `src/smart_json_wrapper.cpp`
  - 所有 WASM 导出函数
  - 业务接口入口和智能数学接口入口都在这里

### 9.2 业务分发层

- `src/api/KinematicsWebAPI.Core.cpp`
  - 总分发
- `src/api/KinematicsWebAPI.RobotCommands.cpp`
  - 机器人接口分支
- `src/api/KinematicsWebAPI.SpcCommands.cpp`
  - SPC 接口分支
- `src/api/KinematicsWebAPI.FourBarCommands.cpp`
  - 四连杆接口分支
- `src/api/KinematicsWebAPI.QuadrupedCommands.cpp`
  - 四足接口分支

### 9.3 业务实现层

- `src/RobotManager.cpp`
  - 机器人实例生命周期管理
- `src/Robot.cpp`
  - 机器人 KDL 正解、逆解、轨迹插补、前端返回格式组装
- `src/spc_core.cpp`
  - SPC 计算主体
- `src/FourBarMechanism/*.cpp`
  - 连杆/曲柄滑块算法
- `src/QuadrupedRobotSimulation/*.cpp`
  - 四足机器人轨迹与反解

## 10. 如果你要继续顺着看，推荐顺序

如果你想先搞清“机器人接口”：

1. `src/smart_json_wrapper.cpp` 里的 `func`
2. `src/api/KinematicsWebAPI.Core.cpp`
3. `src/api/KinematicsWebAPI.RobotCommands.cpp`
4. `src/RobotManager.cpp`
5. `src/Robot.cpp`

如果你想先搞清“四足机器人接口”：

1. `src/api/KinematicsWebAPI.QuadrupedCommands.cpp`
2. `src/QuadrupedRobotSimulation/KinematicsHelper.cpp`
3. `src/QuadrupedRobotSimulation/KinematicsSimulation.cpp`
4. `src/QuadrupedRobotSimulation/KinematicsReverse.cpp`
5. `src/QuadrupedRobotSimulation/CompleteJsonExporter.cpp`

如果你想先搞清“SPC 接口”：

1. `src/api/KinematicsWebAPI.SpcCommands.cpp`
2. `src/spc_core.cpp`
3. `include/spc_core.h`