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

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