smart_wasm/docs/notes/接口调用履历.md

接口调用履历

本文档用于快速梳理当前项目里“前端请求 -> 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

调用链如下：

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

调用链如下：

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

调用履历：

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

调用履历：

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

4.3 Cmd_RemoveRobot

调用履历：

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

4.4 Cmd_ListRobots

调用履历：

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

4.5 Cmd_Kinematics_forward_pose_str

用途：

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

调用履历：

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

调用履历：

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

用途：

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

调用履历：

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

用途：

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

调用履历：

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 做轨迹插补

调用履历：

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

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

调用履历：

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

调用履历：

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

调用履历：

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

用途：

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

调用履历：

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 曲线验证

调用履历：

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

用途：

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

调用履历：

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

说明：

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

7.2 Cmd_QuadrupedRobot_PerformForwardKinematics

用途：

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

调用履历：

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

调用履历：

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

调用履历：

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

8.3 smart_get_function_info

调用履历：

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

8.4 smart_test_match

调用履历：

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