docs: add detailed Chinese comments for code files and correct GPIO mapping table in main.md

App/database.h

@@ -3,16 +3,68 @@
 
 #include "config.h"
 
-// 底层 IAP 接口
+/* ====== 底层 IAP (在应用编程 Flash) 读写驱动接口 ====== */
+
+/**
+ * @brief 禁用 IAP 模块，关闭 Flash 擦写控制器
+ * @details 每次完成 Flash 的读、写或擦除操作后，必须立即调用此函数，
+ *          清除寄存器状态以防止因外部强干扰触发 Flash 误擦写。
+ */
 void IAP_Disable(void);
+
+/**
+ * @brief 从指定 IAP Flash 地址读取一个字节
+ * @param addr 16位目标 Flash 内部偏移物理地址 (对应扇区内偏移)
+ * @return u8 读取到的 8 位数据字节
+ */
 u8 IAP_ReadByte(u16 addr);
+
+/**
+ * @brief 向指定 IAP Flash 地址写入一个字节数据
+ * @param addr 16位目标 Flash 内部偏移物理地址
+ * @param dat 要写入的 8 位数据字节
+ * @note STC32G 的 EEPROM/IAP 写入只能把 1 写为 0，若要把 0 改为 1，必须先执行扇区擦除操作。
+ */
 void IAP_WriteByte(u16 addr, u8 dat);
+
+/**
+ * @brief 擦除指定的 Flash 物理扇区 (512字节)
+ * @param addr 目标扇区内的任意物理字节地址 (传入首地址即可)
+ * @note STC32G EEPROM 的擦除以扇区 (512 字节) 为基本单位。擦除后，该扇区内所有字节的数据均恢复为 0xFF。
+ */
 void IAP_EraseSector(u16 addr);
 
-// 数据库持久化接口
+
+/* ====== 传感器数据库业务持久化接口 ====== */
+
+/**
+ * @brief 从 Flash 扇区 254 (0xFE0000) 载入全部传感器槽位配置至 RAM 变量
+ * @details 系统初始化时调用，将 EEPROM 中的传感器绑定数据拷贝到 RAM 中的 `sensor_list` 数组。
+ */
 void Load_Database(void);
+
+/**
+ * @brief 将 RAM 中的全部传感器配置保存/写入到 Flash 扇区中
+ * @details 在完成对码、添加新传感器或微调防区号后调用，该函数会先擦除第 254 扇区，然后逐字节写入当前最新的 `sensor_list` 数组。
+ */
 void Save_Database(void);
+
+/**
+ * @brief 添加一个新的传感器或更新已有的传感器防区、类型和名称
+ * @param addr 捕获到的 24 位无线传感器 EV1527 射频地址
+ * @param type 传感器类型 (0:门磁, 1:红外PIR, 2:烟感, 3:燃气, 4:水浸)
+ * @param zone 自定义分配的防区号 (1~99, 0代表24小时紧急防区)
+ * @details 如果检测到该地址已在列表，则覆盖更新防区号并保存；否则在首个空闲槽位插入该传感器，
+ *          自动生成其法语名称字符串，并调用 `Save_Database()` 写入 Flash 中。
+ */
 void Add_Sensor_With_Zone(u32 addr, u8 type, u8 zone);
+
+/**
+ * @brief 检测特定射频地址是否已被绑定在传感器数据库中
+ * @param addr 接收到的 24 位无线传感器射频地址
+ * @param out_slot_index 输出参数指针：如果匹配成功，将写入该传感器在 `sensor_list` 数组中的索引槽位号 (0~15)
+ * @return bit 返回匹配结果。1 表示数据库中已存在该传感器；0 表示该传感器未登记 (未知设备)
+ */
 bit Check_Sensor_ID(u32 addr, u8 *out_slot_index);
 
-#endif
+#endif // __DATABASE_H__