chore: naming improvements and use appropriate variables

Author: soulteary

README.md

@@ -247,6 +247,16 @@ auto state_arc = hand.getStateArc();
 - 使用示例和注意事项
 - 版本兼容性说明
 
+### 命名规范
+
+项目已进行命名规范改进，详细信息请参考：[命名规范改进文档](docs/NAMING_IMPROVEMENTS.md)
+
+主要改进包括：
+- 统一命名空间结构（所有型号实现类迁移到 `linkerhand::hand` 命名空间）
+- 类名改进（不同型号使用不同类名，如 `L10Hand`, `L20Hand` 等）
+- 参数命名修正（`handJoint` → `handModel`）
+- 完全向后兼容（旧命名仍可使用）
+
 ## 🧪 测试
 
 ### 运行测试

docs/API-Reference.md

@@ -55,14 +55,14 @@ LinkerHand C++ API 提供了完整的接口用于控制灵心巧手系列灵巧
 ### LinkerHandApi
 
 ```cpp
-LinkerHandApi(const LINKER_HAND &handJoint, const HAND_TYPE &handType, const COMM_TYPE commType = COMM_CAN_0);
+LinkerHandApi(const LINKER_HAND &handModel, const HAND_TYPE &handType, const COMM_TYPE commType = COMM_CAN_0);
 ```
 
 **功能描述**
 创建并初始化 LinkerHand API 实例。
 
 **参数说明**
-- `handJoint` (LINKER_HAND): 机械手型号
+- `handModel` (LINKER_HAND): 机械手型号
   - 可选值: `LINKER_HAND::O6`, `LINKER_HAND::L6`, `LINKER_HAND::L7`, `LINKER_HAND::L10`, `LINKER_HAND::L20`, `LINKER_HAND::L21`, `LINKER_HAND::L25`
 - `handType` (HAND_TYPE): 机械手类型
   - `HAND_TYPE::LEFT` - 左手
@@ -623,7 +623,7 @@ void setCurrent(const std::vector<uint8_t> &current);
 **使用示例**
 ```cpp
 // 仅 L20 支持
-if (hand.handJoint_ == LINKER_HAND::L20) {
+if (hand.handModel_ == LINKER_HAND::L20) {
     std::vector<uint8_t> current = {100, 100, 100, 100, 100};
     hand.setCurrent(current);
 }
@@ -655,7 +655,7 @@ void setEnable(const std::vector<uint8_t> &enable = std::vector<uint8_t>(5, 0));
 **使用示例**
 ```cpp
 // 仅 L25 支持
-if (hand.handJoint_ == LINKER_HAND::L25) {
+if (hand.handModel_ == LINKER_HAND::L25) {
     std::vector<uint8_t> enable = {1, 1, 1, 1, 1}; // 使能所有手指
     hand.setEnable(enable);
 }
@@ -687,7 +687,7 @@ void setDisable(const std::vector<uint8_t> &disable = std::vector<uint8_t>(5, 1)
 **使用示例**
 ```cpp
 // 仅 L25 支持
-if (hand.handJoint_ == LINKER_HAND::L25) {
+if (hand.handModel_ == LINKER_HAND::L25) {
     std::vector<uint8_t> disable = {1, 1, 1, 1, 1}; // 禁用所有手指
     hand.setDisable(disable);
 }
@@ -718,7 +718,7 @@ void clearFaultCode(const std::vector<uint8_t> &torque = std::vector<uint8_t>(5,
 **使用示例**
 ```cpp
 // 仅 L20 支持
-if (hand.handJoint_ == LINKER_HAND::L20) {
+if (hand.handModel_ == LINKER_HAND::L20) {
     hand.clearFaultCode();
 }
 ```

docs/NAMING_IMPROVEMENTS.md

@@ -0,0 +1,166 @@
+# LinkerHand C++ SDK 命名规范改进指南
+
+## 概述
+
+本文档描述了 LinkerHand C++ SDK 的命名规范改进，这些改进旨在提高代码一致性、可维护性和可读性。
+
+## 改进内容
+
+### 1. 统一命名空间结构
+
+所有手型号实现类已迁移到统一的 `linkerhand::hand` 命名空间：
+
+**改进前：**
+```cpp
+namespace LinkerHandL10 {
+    class LinkerHand : public linkerhand::hand::IHand { ... };
+}
+```
+
+**改进后：**
+```cpp
+namespace linkerhand {
+namespace hand {
+    class L10Hand : public IHand { ... };
+} // namespace hand
+} // namespace linkerhand
+```
+
+### 2. 类名改进
+
+不同型号的手现在使用不同的类名，便于区分：
+
+| 型号 | 旧类名 | 新类名 | 命名空间 |
+|------|--------|--------|---------|
+| L6/O6 | `LinkerHandL6::LinkerHand` | `linkerhand::hand::L6Hand` | `linkerhand::hand` |
+| L7 | `LinkerHandL7::LinkerHand` | `linkerhand::hand::L7Hand` | `linkerhand::hand` |
+| L10 | `LinkerHandL10::LinkerHand` | `linkerhand::hand::L10Hand` | `linkerhand::hand` |
+| L20 | `LinkerHandL20::LinkerHand` | `linkerhand::hand::L20Hand` | `linkerhand::hand` |
+| L25/L21 | `LinkerHandL25::LinkerHand` | `linkerhand::hand::L25Hand` | `linkerhand::hand` |
+| Modbus L10 | `ModbusLinkerHandL10::LinkerHand` | `linkerhand::hand::ModbusL10Hand` | `linkerhand::hand` |
+
+### 3. 帧属性枚举重命名
+
+各型号的帧属性枚举已重命名，使用更清晰的命名：
+
+| 型号 | 旧枚举名 | 新枚举名 |
+|------|---------|---------|
+| L6/O6 | `LinkerHandL6::FRAME_PROPERTY` | `linkerhand::hand::L6FrameProperty` |
+| L7 | `LinkerHandL7::FRAME_PROPERTY` | `linkerhand::hand::L7FrameProperty` |
+| L10 | `LinkerHandL10::FRAME_PROPERTY` | `linkerhand::hand::L10FrameProperty` |
+| L20 | `LinkerHandL20::FRAME_PROPERTY` | `linkerhand::hand::L20FrameProperty` |
+| L25/L21 | `LinkerHandL25::FRAME_PROPERTY` | `linkerhand::hand::L25FrameProperty` |
+
+### 4. 参数命名修正
+
+修正了错误的参数命名：
+
+**改进前（错误）**：
+```cpp
+LinkerHandApi(const LINKER_HAND &handJoint, ...);
+LINKER_HAND handJoint_;  // 这是手型号，不是关节
+```
+
+**改进后（正确）**：
+```cpp
+LinkerHandApi(const LINKER_HAND &handModel, ...);
+LINKER_HAND handModel_;  // 手型号（L6, L7, L10, L20, L21, L25 等）
+```
+
+**说明**：
+- `handJoint` 命名不准确，因为这是手型号（Model），不是关节（Joint）
+- 已统一修正为 `handModel`，更准确地表示手型号
+
+## 向后兼容性
+
+为了保持向后兼容，所有旧的命名空间和类名都通过 `using` 别名保留：
+
+```cpp
+// 向后兼容：在旧命名空间中提供别名
+namespace LinkerHandL10 {
+    using FRAME_PROPERTY = linkerhand::hand::L10FrameProperty;
+    using LinkerHand = linkerhand::hand::L10Hand;
+} // namespace LinkerHandL10
+```
+
+这意味着现有代码可以继续使用旧的命名，无需立即修改。
+
+## 使用示例
+
+### 使用新命名（推荐）
+
+```cpp
+#include "LinkerHandL10.h"
+#include "HandFactory.h"
+
+// 使用新的命名空间和类名
+using namespace linkerhand;
+
+auto hand = factory::HandFactory::createHand(
+    LINKER_HAND::L10,
+    HAND_TYPE::RIGHT,
+    COMM_CAN_0
+);
+// hand 的类型是 std::unique_ptr<hand::IHand>
+// 实际类型是 hand::L10Hand
+```
+
+### 使用旧命名（向后兼容）
+
+```cpp
+#include "LinkerHandL10.h"
+#include "HandFactory.h"
+
+// 仍然可以使用旧的命名空间
+LinkerHandL10::LinkerHand hand(0x27, "can0", 1000000);
+```
+
+## 迁移建议
+
+### 阶段一：保持兼容（当前）
+
+- ✅ 所有新命名已实现
+- ✅ 向后兼容别名已添加
+- ✅ 现有代码无需修改即可继续工作
+
+### 阶段二：逐步迁移（推荐）
+
+1. **新代码使用新命名**：所有新编写的代码应使用新的命名空间和类名
+2. **更新文档和示例**：逐步更新文档和示例代码使用新命名
+3. **代码审查**：在代码审查中鼓励使用新命名
+
+### 阶段三：完全迁移（未来）
+
+在未来版本中，可以考虑：
+- 移除向后兼容别名（需要主版本号升级）
+- 更新所有内部代码使用新命名
+- 更新所有文档和示例
+
+## 优势
+
+1. **一致性**：所有型号使用统一的命名空间结构
+2. **可读性**：类名直接反映型号（`L10Hand` vs `LinkerHand`）
+3. **可维护性**：统一的命名空间便于管理和查找
+4. **扩展性**：新型号可以轻松添加到同一命名空间
+
+## 注意事项
+
+1. **工厂类**：`HandFactory` 已更新为使用新类名，但返回类型仍然是 `IHand` 接口
+2. **头文件**：头文件名暂时保持不变，未来可以考虑重命名
+3. **枚举**：帧属性枚举已重命名，但枚举值保持不变
+
+## 相关文件
+
+- `include/LinkerHandL6.h` - L6/O6 型号实现
+- `include/LinkerHandL7.h` - L7 型号实现
+- `include/LinkerHandL10.h` - L10 型号实现
+- `include/LinkerHandL20.h` - L20 型号实现
+- `include/LinkerHandL25.h` - L25/L21 型号实现
+- `include/ModbusLinkerHandL10.h` - Modbus L10 型号实现
+- `include/HandFactory.h` - 工厂类
+
+## 版本信息
+
+- **改进版本**：1.1.7+
+- **兼容性**：完全向后兼容
+

docs/TROUBLESHOOTING.md

@@ -398,7 +398,7 @@ CMake 3.5 or higher is required
    ```cpp
    std::vector<uint8_t> pose;
 
-   switch (hand.handJoint_) {
+   switch (hand.handModel_) {
        case LINKER_HAND::L6:
        case LINKER_HAND::O6:
            pose.resize(6);
@@ -423,7 +423,7 @@ CMake 3.5 or higher is required
    ```cpp
    void safeFingerMove(LinkerHandApi& hand, const std::vector<uint8_t>& pose) {
        int expected_size = 0;
-       switch (hand.handJoint_) {
+       switch (hand.handModel_) {
            case LINKER_HAND::L10: expected_size = 10; break;
            case LINKER_HAND::L20: expected_size = 20; break;
            // ...
@@ -451,7 +451,7 @@ CMake 3.5 or higher is required
 1. **检查型号支持**:
    ```cpp
    // 仅 L20 支持 setCurrent
-   if (hand.handJoint_ == LINKER_HAND::L20) {
+   if (hand.handModel_ == LINKER_HAND::L20) {
        hand.setCurrent(current);
    } else {
        std::cerr << "警告: setCurrent 仅支持 L20" << std::endl;

examples/toolset_example.cpp

@@ -281,7 +281,7 @@ void interactiveMode(LinkerHandApi &hand)
             }
             break;
         case 11:
-            if (hand.handJoint_ == LINKER_HAND::L6) {
+            if (hand.handModel_ == LINKER_HAND::L6) {
                 std::cout << "L6 - Execute action" << std::endl;
 
                 for (size_t i = 0; i < 10; i++) {
@@ -293,7 +293,7 @@ void interactiveMode(LinkerHandApi &hand)
                 }
 
 
-            } else if (hand.handJoint_ == LINKER_HAND::L7) {
+            } else if (hand.handModel_ == LINKER_HAND::L7) {
                 hand.setSpeed(std::vector<uint8_t>(7, HAND_SPEED)); // L7 need 7 speed
                 hand.setTorque(std::vector<uint8_t>(7, HAND_TORQUE)); // L7 need 7 torque
                 //---------------------------------------------------------
@@ -309,7 +309,7 @@ void interactiveMode(LinkerHandApi &hand)
                 std::this_thread::sleep_for(std::chrono::seconds(1));
                 //---------------------------------------------------------
             }
-            else if (hand.handJoint_ == LINKER_HAND::L10)
+            else if (hand.handModel_ == LINKER_HAND::L10)
             {
                 hand.setSpeed(std::vector<uint8_t>(5, HAND_SPEED)); // L10 need 5 speed
                 hand.setTorque(std::vector<uint8_t>(5, HAND_TORQUE)); // L10 need 5 torque
@@ -344,7 +344,7 @@ void interactiveMode(LinkerHandApi &hand)
                 std::this_thread::sleep_for(std::chrono::seconds(1));
                 //---------------------------------------------------------
             }
-            else if (hand.handJoint_ == LINKER_HAND::L20)
+            else if (hand.handModel_ == LINKER_HAND::L20)
             {
                 hand.setSpeed(std::vector<uint8_t>(5, HAND_SPEED)); // L20 need 5 speed
                 //---------------------------------------------------------
@@ -358,7 +358,7 @@ void interactiveMode(LinkerHandApi &hand)
                 hand.fingerMove(L20_POSE_OPEN);
                 std::this_thread::sleep_for(std::chrono::seconds(1));
             }
-            else if (hand.handJoint_ == LINKER_HAND::L25 || hand.handJoint_ == LINKER_HAND::L21)
+            else if (hand.handModel_ == LINKER_HAND::L25 || hand.handModel_ == LINKER_HAND::L21)
             {
                 hand.setSpeed(std::vector<uint8_t>(25, HAND_SPEED));
                 hand.setTorque(std::vector<uint8_t>(25, HAND_TORQUE));

include/HandFactory.h

@@ -61,25 +61,25 @@ class HandFactory {
         if (canChannel == "can0" || canChannel == "can1" || canChannel == "ethercat") {
             switch (type) {
                 case O6:
-                    return std::unique_ptr<hand::IHand>(std::make_unique<LinkerHandL6::LinkerHand>(handId, canChannel, baudrate));
+                    return std::unique_ptr<hand::IHand>(std::make_unique<hand::L6Hand>(handId, canChannel, baudrate));
                     break;
                 case L6:
-                    return std::unique_ptr<hand::IHand>(std::make_unique<LinkerHandL6::LinkerHand>(handId, canChannel, baudrate));
+                    return std::unique_ptr<hand::IHand>(std::make_unique<hand::L6Hand>(handId, canChannel, baudrate));
                     break;
                 case L7:
-                    return std::unique_ptr<hand::IHand>(std::make_unique<LinkerHandL7::LinkerHand>(handId, canChannel, baudrate));
+                    return std::unique_ptr<hand::IHand>(std::make_unique<hand::L7Hand>(handId, canChannel, baudrate));
                     break;
                 case L10:
-                    return std::unique_ptr<hand::IHand>(std::make_unique<LinkerHandL10::LinkerHand>(handId, canChannel, baudrate));
+                    return std::unique_ptr<hand::IHand>(std::make_unique<hand::L10Hand>(handId, canChannel, baudrate));
                     break;
                 case L20:
-                    return std::unique_ptr<hand::IHand>(std::make_unique<LinkerHandL20::LinkerHand>(handId, canChannel, baudrate));
+                    return std::unique_ptr<hand::IHand>(std::make_unique<hand::L20Hand>(handId, canChannel, baudrate));
                     break;
                 case L21:
-                    return std::unique_ptr<hand::IHand>(std::make_unique<LinkerHandL25::LinkerHand>(handId, canChannel, baudrate, 1));
+                    return std::unique_ptr<hand::IHand>(std::make_unique<hand::L25Hand>(handId, canChannel, baudrate, 1));
                     break;
                 case L25:
-                    return std::unique_ptr<hand::IHand>(std::make_unique<LinkerHandL25::LinkerHand>(handId, canChannel, baudrate, 0));
+                    return std::unique_ptr<hand::IHand>(std::make_unique<hand::L25Hand>(handId, canChannel, baudrate, 0));
                     break;
                 default:
                     throw std::invalid_argument("Unknown hand type");
@@ -88,7 +88,7 @@ class HandFactory {
         	#if USE_RMAN
             switch (type) {
                 case L10:
-                    return std::unique_ptr<hand::IHand>(std::make_unique<ModbusLinkerHandL10::LinkerHand>(handId));
+                    return std::unique_ptr<hand::IHand>(std::make_unique<hand::ModbusL10Hand>(handId));
                 default:
                     throw std::invalid_argument("Unknown hand type");
                     break;

include/LinkerHandApi.h

@@ -21,11 +21,11 @@ class LinkerHandApi
 public:
 	/**
 	 * @brief 构造函数
-	 * @param handJoint 手型号（LINKER_HAND 枚举）
+	 * @param handModel 手型号（LINKER_HAND 枚举）
 	 * @param handType 手类型（左手/右手）
 	 * @param commType 通信类型（默认 CAN_0）
 	 */
-	LinkerHandApi(const LINKER_HAND &handJoint, const HAND_TYPE &handType, 
+	LinkerHandApi(const LINKER_HAND &handModel, const HAND_TYPE &handType,
 	              const COMM_TYPE commType = COMM_CAN_0);
 	~LinkerHandApi();
 
@@ -80,7 +80,7 @@ class LinkerHandApi
 	std::unique_ptr<linkerhand::hand::IHand> hand;
 	uint32_t handId;
 public:
-	LINKER_HAND handJoint_;
+	LINKER_HAND handModel_;  // 手型号（L6, L7, L10, L20, L21, L25 等）
 	HAND_TYPE handType_;
 };