为所有函数和类添加中文注释文档字符串

tests/test_dead_bug_rules.py

@@ -3,26 +3,32 @@ from __future__ import annotations
 from app.exercises.dead_bug.rules import detect_diagonal_extension, has_required_visibility, is_ready_position
 from app.exercises.dead_bug.types import DeadBugMetrics, Point
 
-
 class TestDeadBugRules:
+    """死虫式规则函数单元测试"""
+
     def _make_landmark(self, x=0.5, y=0.5, z=0.0, visibility=1.0):
+        """创建测试用Point对象"""
         return Point(x, y, z, visibility)
 
     def _make_visible_landmarks(self):
+        """创建33个全可见的测试用关键点"""
         return [self._make_landmark() for _ in range(33)]
 
     def test_has_required_visibility_all_visible(self):
+        """测试：所有关键点可见时应返回True"""
         lm = self._make_visible_landmarks()
         indices = (11, 12, 13, 14, 15, 16, 23, 24, 25, 26, 27, 28)
         assert has_required_visibility(lm, indices, 0.45)
 
     def test_has_required_visibility_low(self):
+        """测试：关键点可见度过低时应返回False"""
         lm = self._make_visible_landmarks()
         lm[11] = self._make_landmark(visibility=0.1)
         indices = (11, 12, 13, 14, 15, 16, 23, 24, 25, 26, 27, 28)
         assert not has_required_visibility(lm, indices, 0.45)
 
     def test_detect_diagonal_extension_none(self):
+        """测试：四肢均未伸展时应返回None"""
         metrics = DeadBugMetrics(
             left_arm_extended=False, right_arm_extended=False,
             left_leg_extended=False, right_leg_extended=False,
@@ -33,6 +39,7 @@ class TestDeadBugRules:
         assert detect_diagonal_extension(metrics) is None
 
     def test_detect_diagonal_extension_left_arm_right_leg(self):
+        """测试：左臂+右腿对角伸展检测"""
         metrics = DeadBugMetrics(
             left_arm_extended=True, right_arm_extended=False,
             left_leg_extended=False, right_leg_extended=True,
@@ -43,6 +50,7 @@ class TestDeadBugRules:
         assert detect_diagonal_extension(metrics) == "left_arm_right_leg"
 
     def test_is_ready_position(self):
+        """测试：膝盖弯曲且四肢收缩应识别为准备姿态"""
         metrics = DeadBugMetrics(
             left_arm_extended=False, right_arm_extended=False,
             left_leg_extended=False, right_leg_extended=False,
@@ -53,6 +61,7 @@ class TestDeadBugRules:
         assert is_ready_position(metrics)
 
     def test_is_not_ready_legs_extended(self):
+        """测试：腿部伸展时不识别为准备姿态"""
         metrics = DeadBugMetrics(
             left_arm_extended=False, right_arm_extended=False,
             left_leg_extended=True, right_leg_extended=False,

tests/test_dead_bug_state_machine.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 from app.exercises.dead_bug.state_machine import DeadBugStateMachine
 from app.exercises.dead_bug.types import DeadBugMetrics, DeadBugPhase
 
-
 class TestDeadBugStateMachine:
+    """死虫式状态机单元测试"""
+
     def _ready_metrics(self) -> DeadBugMetrics:
+        """构建准备姿态的度量数据"""
         return DeadBugMetrics(
             left_arm_extended=False, right_arm_extended=False,
             left_leg_extended=False, right_leg_extended=False,
@@ -15,6 +17,7 @@ class TestDeadBugStateMachine:
         )
 
     def _extended_left(self) -> DeadBugMetrics:
+        """构建左臂+右腿对角伸展的度量数据"""
         return DeadBugMetrics(
             left_arm_extended=True, right_arm_extended=False,
             left_leg_extended=False, right_leg_extended=True,
@@ -24,17 +27,20 @@ class TestDeadBugStateMachine:
         )
 
     def test_initial_state(self):
+        """测试：状态机初始化后应为READY且计数为0"""
         sm = DeadBugStateMachine()
         assert sm.phase == DeadBugPhase.READY
         assert sm.rep_count == 0
 
     def test_no_transition_in_ready(self):
+        """测试：准备姿态下不触发状态转换"""
         sm = DeadBugStateMachine()
         result = sm.update(self._ready_metrics())
         assert sm.phase == DeadBugPhase.READY
         assert result.rep_count == 0
 
     def test_confirm_extension(self):
+        """测试：连续确认帧数后从READY转换到EXTENDING"""
         sm = DeadBugStateMachine(extension_confirm_frames=2, reset_confirm_frames=2)
         sm.update(self._extended_left())
         assert sm.phase == DeadBugPhase.READY

tests/test_ice_parser.py

@@ -2,9 +2,11 @@ from __future__ import annotations
 
 from app.signaling.ice_parser import parse_ice
 
-
 class TestIceParser:
+    """ICE候选者解析单元测试"""
+
     def test_parse_valid_ice(self):
+        """测试：解析有效的ICE host候选者"""
         data = {
             "candidate": "1234567890 1 UDP 2130706431 192.168.1.1 12345 typ host",
             "sdpMid": "0",
@@ -20,9 +22,11 @@ class TestIceParser:
         assert cand.type == "host"
 
     def test_parse_invalid_ice(self):
+        """测试：解析无效ICE字符串应返回None"""
         assert parse_ice({"candidate": "invalid"}) is None
 
     def test_parse_srflx(self):
+        """测试：解析含有raddr/rport的srflx候选者"""
         data = {
             "candidate": "abcdef 1 UDP 1686052607 203.0.113.1 50000 typ srflx raddr 192.168.1.1 rport 12345",
             "sdpMid": "0",