diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cd8b3fb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# STM32固件端文档
+
+## 1. 端侧职责
+- 从 K210 串口接收识别结果。
+- 在本地执行签到逻辑（时间段判断、重复判定、缓存与重传）。
+- 通过 ESP8266 将签到数据以 AES-128-CBC 加密后上传服务端。
+- 维护 RTC（DS1302）与网络时间同步。
+
+对应入口文件：`User/main.c`
+
+## 2. 关键模块
+- 主流程：`User/main.c`
+- 考勤逻辑：`Hardware/Attendance.c`
+- WiFi/HTTP：`Hardware/esp8266.c`
+- 加密：`Hardware/Crypto.c`
+- RTC：`Hardware/DS1302.c`
+- 光照补光：`Hardware/LightSensor.c`
+- K210串口解析：`Hardware/K210_USART.c`
+
+## 3. 当前默认配置（代码内）
+文件：`User/main.c`
+- `WIFI_SSID`: `yzfh`
+- `WIFI_PASSWORD`: `yzfhroot`
+- `HTTP_SERVER_IP`: `27.106.113.205`
+- `HTTP_SERVER_PORT`: `8082`
+- `CLASS_ID`: `1`
+
+建议将上述配置改为部署环境参数后再编译烧录。
+
+## 4. 通信与接口
+STM32 通过 `ESP8266_HttpGet` / `ESP8266_SendEncryptedData` 访问服务端：
+- `POST /api/checkin`：上传加密签到数据（必带 `X-Encrypted: AES128-CBC`）。
+- `GET /api/time`：获取服务器时间戳。
+- `GET /api/timeslots`：下载时间段配置。
+- `GET /api/check_duplicate`：按时段查重。
+- `GET /api/today_records`：下载今日已签到学号列表。
+
+## 5. 主流程说明
+1. 系统初始化（OLED、串口、考勤模块、加密模块、RTC、传感器）。
+2. 初始化并连接 ESP8266 到 WiFi 与 HTTP 服务器。
+3. 可用时同步网络时间到 DS1302。
+4. 定时拉取时间段配置。
+5. 处理 K210 上报的人脸识别结果：
+- 置信度通过阈值后进入签到逻辑。
+- 本地去重 + 服务器时段去重。
+- 记录加入本地队列并尝试上传。
+6. 网络异常时离线缓存，恢复后批量补传。
+
+## 6. 调试建议
+- 优先看串口调试输出（`DEBUG_PRINT` 系列）。
+- 检查 `g_wifi_connected`、`g_server_connected` 变化。
+- 若频繁重连，先确认 AP 稳定性、服务器可达性与 8082 端口。
+
+## 7. 构建与烧录
+工程为 Keil 工程：
+- `Project.uvprojx`
+- `Project.uvoptx`
+
+按当前板卡配置在 Keil 中编译并烧录。
+
+## 8. 依赖与注意事项
+- 与服务端 AES Key/IV 必须一致（否则 `/api/checkin` 解密失败）。
+- DS1302 可用时优先作为本地时钟；不可用则回退网络时间。
+- `Attendance.c` 的默认时间段仅为兜底，实际以服务器下发为准。