diff --git a/docs/notes/接口调用履历.md b/docs/notes/接口调用履历.md
new file mode 100644
index 0000000..130c536
--- /dev/null
+++ b/docs/notes/接口调用履历.md
@@ -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`
+