docs: 为所有代码源文件添加详细中文注释，并在设计文档中纠正GPIO物理引脚映射表

App/ui.h

@@ -3,16 +3,83 @@
 
 #include "config.h"
 
+/* ====== OLED 屏幕 UI (用户界面) 渲染层接口 ====== */
+
+/**
+ * @brief 渲染显示待机时钟主页面
+ * @param state 当前的系统运行状态 (STATE_NORMAL/STATE_ARMED/STATE_DISARMED)
+ * @param hour 当前待显示的小时
+ * @param min 当前待显示的分钟
+ * @details 负责在 120x240 大小的 AMOLED 屏幕上居中绘制巨大的时钟字样，并在顶部
+ *          绘制对应的状态图标 (如一把打开的锁代表已撤防、闭合的锁代表已布防等)。
+ */
 void UI_ShowClockPage(SystemState state, u8 hour, u8 min);
+
+/**
+ * @brief 渲染显示传感器对码的二级设备选择菜单页面
+ * @param selected_index 当前正在选中的传感器类型索引 (0:门磁, 1:PIR, 2:烟感, 3:燃气, 4:水浸)
+ */
 void UI_ShowPairMenuPage(u8 selected_index);
+
+/**
+ * @brief 动态刷新显示正在搜寻无线传感器信号的等待对码动态图画
+ * @param frame_index 当前雷达扫描波纹动画的帧索引 (0~2 帧循环)
+ */
 void UI_ShowPairWaitPage(u8 frame_index);
+
+/**
+ * @brief 渲染显示捕获到无线信号后的传感器类型确认与自定义防区微调界面
+ * @param type 已捕获的传感器类型 (0~4)
+ * @param zone_index 当前设定的防区数值 (1~99)，允许通过按键增加或减小
+ */
 void UI_ShowPairConfirmPage(u8 type, u8 zone_index);
+
+/**
+ * @brief 渲染显示对码学习成功反馈页
+ * @details 屏幕中央显示巨大对勾图标，并绘制文字 "APPAIRAGE OK" (配对成功)。
+ */
 void UI_ShowPairSuccessPage(void);
+
+/**
+ * @brief 渲染显示对码失败 (或30秒超时) 反馈页
+ * @param is_timeout 1表示超时失败，0表示其他错误
+ * @details 屏幕显示红色大叉图标，并提示 "ECHEC" (配对失败)。
+ */
 void UI_ShowPairFailPage(u8 is_timeout);
+
+/**
+ * @brief 渲染显示传感器入侵警报报警页面
+ * @param type 触发入侵的传感器类型 (0:门磁, 1:PIR, 2:烟感, 3:燃气, 4:水浸)
+ * @param zone_index 报警传感器所绑定的防区号 (1~99, 0)
+ * @details 屏幕爆闪红色粗边框，并交替绘制代表紧急入侵的巨大传感器特定警示大图标。
+ */
 void UI_ShowAlarmPage(u8 type, u8 zone_index);
+
+/**
+ * @brief 渲染显示 SOS 主动求救发送状态页面
+ * @details 爆闪红白双层边框，在屏幕上绘制求救警示图，并闪烁显示法语 "SOS EMIS" (求救已发送)。
+ */
 void UI_ShowSosPage(void);
+
+/**
+ * @brief 渲染显示与网络摄像机 (IPC) 进行一键绑定配对的进度画面
+ * @param addr 手环克隆发送的 24 位出厂 ID 地址 (十六进制字符串格式展示)
+ */
 void UI_ShowBindingPage(u32 addr);
+
+/**
+ * @brief 渲染显示设置主菜单界面
+ * @param selected_index 当前菜单高亮行索引 (0:HORLOGE时间, 1:APPAIRAGE对码, 2:LIAISON绑定)
+ */
 void UI_ShowMainMenu(u8 selected_index);
+
+/**
+ * @brief 渲染显示修改时间页面 (时钟设置编辑状态)
+ * @param hour 待修改的小时
+ * @param min 待修改的分钟
+ * @param selection 当前选中的修改项 (1:修改小时, 2:修改分钟)
+ * @param blink_on 控制被选中数值以 500ms 周期进行隐现闪烁的周期标志位 (1-显示, 0-消隐)
+ */
 void UI_ShowSetTimePage(u8 hour, u8 min, u8 selection, u8 blink_on);
 
-#endif
+#endif // __UI_H__