补充接口调用履历文档
This commit is contained in:
zhangshun
599
docs/notes/接口调用履历.md
Normal file
599
docs/notes/接口调用履历.md
Normal file
@@ -0,0 +1,599 @@
|
||||
# 接口调用履历
|
||||
|
||||
本文档用于快速梳理当前项目里“前端请求 -> 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`
|
||||
|
||||
## 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`
|
||||
|
||||
Reference in New Issue
Block a user