diff --git a/src/README.MD b/src/README.MD
new file mode 100644
index 0000000..d656229
--- /dev/null
+++ b/src/README.MD
@@ -0,0 +1,128 @@
+# Keycloak QR Login
+
+易识IT 开发的基于二维码的 Keycloak 登录插件。
+
+## 项目概述
+
+本项目是一个 Keycloak 身份提供商（Identity Provider）插件，实现了基于二维码的登录功能。用户可以通过扫描二维码，在移动设备上确认登录，实现更便捷、安全的身份验证。
+
+主要特性：
+- 支持二维码生成和展示
+- 支持扫码状态轮询
+- 支持基于JWT Token的身份验证
+- 支持内存和Redis两种会话存储方式
+- 完整的签名验证机制保证通信安全
+- 可配置的各项参数
+
+## 技术架构
+
+### 主要组件
+
+1. **QRLoginIdentityProvider**: 核心身份提供商实现
+2. **QRLoginEndpoint**: REST API端点，处理扫码、确认等操作
+3. **SessionStore**: 会话存储接口及实现（内存/Redis）
+4. **SignatureUtil**: 签名工具，保障通信安全
+5. **前端脚本**: 实现二维码展示和状态轮询
+
+### 数据流
+
+```
+
+1. 用户访问登录页面 -> 2. 点击"二维码登录" -> 3. 生成二维码并展示
+   ↓
+4. 用户使用App扫描二维码 <- 5. App调用/qr/scan接口
+   ↓
+6. 用户在App确认登录 -> 7. App调用/qr/confirm接口
+   ↓
+8. 前端轮询/qr/status获取状态 -> 9. 跳转到确认后的回调URL完成登录
+```
+## 配置说明
+
+### 插件配置项
+
+| 配置项 | 说明 | 默认值 |
+|-------|------|--------|
+| Session TTL (s) | 二维码会话有效期(秒) | 120 |
+| Poll Interval (ms) | 前端轮询间隔(毫秒) | 1500 |
+| Store Type | 存储类型(redis或memory) | memory |
+| Redis URI | Redis连接地址 | redis://127.0.0.1:6379 |
+| Redis Namespace | Redis键前缀 | qrlogin: |
+| HMAC Secret | 签名校验密钥 | change-me |
+| Algorithm | 签名算法 | HmacSHA256 |
+| Time Window Seconds | 请求有效时间范围(秒) | 5 |
+
+### 环境要求
+
+- Keycloak 20+
+- Java 17+
+- Redis (可选，用于分布式部署)
+
+## 安装部署
+
+1. 构建项目:
+   ``` bash
+    mvn clean package
+   ```
+2. 将生成的JAR包复制到Keycloak的providers目录:
+   ```bash
+    cp target/keycloak-qr-login-*.jar $KEYCLOAK_HOME/providers/
+   ```
+3. 重启Keycloak服务
+
+4. 在Keycloak管理界面中配置QR Login身份提供商
+
+## API 接口
+
+详细API文档请参考 [OpenAPI 文档](src/main/resources/openapi/qrlogin-openapi.yaml)
+
+主要接口:
+- POST `/qr/scan`: 处理二维码扫描
+- POST `/qr/confirm`: 处理登录确认
+- GET `/qr/status`: 查询二维码状态
+
+## 开发指南
+
+### 项目结构
+
+```
+
+src/main/java/top/ysit/qrlogin
+├── config                 # 配置类
+├── core                   # 核心组件
+│   ├── security           # 安全相关
+│   ├── store              # 会话存储
+│   └── util               # 工具类
+├── idp                    # 身份提供商实现
+│   ├── resource           # REST资源
+│   │   ├── endpoint       # 端点实现
+│   │   └── factory        # 工厂类
+│   └── QRLoginIdentityProvider*
+└── spi                    # SPI实现
+```
+### 扩展功能
+
+1. 添加新的存储实现: `core\SessionStore.java` 接口
+2. 自定义签名算法: 扩展 `SignatureConfig.SignatureAlgorithm`
+3. 修改前端样式: 编辑主题文件 `theme/qrlogin/login/resources/js/script.js`
+
+## 安全说明
+
+1. 所有API调用均需签名验证
+2. 时间戳验证防止重放攻击
+3. JWT Token验证确保用户身份合法性
+4. 会话具有固定有效期，防止长期有效攻击
+
+## 特殊说明
+
+1. Redis功能暂时没有开发完整，待完善。
+2. 基于IDP ISP 实现的，所以用户第一次登录时，需要绑定账号
+3. 前端登录效果需要依赖`theme/qrlogin/login/resources/js/script.js`文件
+
+## 许可证
+
+Apache License 2.0
+
+## 联系我们
+
+易识IT 
+