chore: 整理文档目录结构

- 移动SMS验证相关文档到docs目录
- 移动github-actions-secrets.md到docs目录
- 删除根目录下的旧文档
This commit is contained in:
iammm0
2026-01-27 14:31:07 +08:00
parent 2fe6ebf44c
commit e2ee641d41
3 changed files with 0 additions and 0 deletions

View File

@@ -0,0 +1,158 @@
# 腾讯云短信验证码集成实施状态
## ✅ 已完成的任务
### 后端实施FastAPI
1. **环境配置与依赖**
- 已在 `api/requirements.txt` 中添加 `tencentcloud-sdk-python>=3.0.1000`
- 已在 `api/.env.production` 中添加腾讯云短信配置项
2. **数据库模型扩展**
- 已在 `api/database/models.py` 中添加 `SmsVerificationCode` 模型
- 已扩展 `RefreshToken` 表,添加 `device_info` 字段
3. **短信服务实现**
- 已创建 `api/services/sms_service.py`
- 实现了验证码生成、发送、验证和频率限制功能
- 集成了腾讯云SMS SDK
4. **认证路由扩展**
- 已在 `api/routers/auth.py` 中添加以下端点:
- `POST /api/auth/sms/send` - 发送验证码
- `POST /api/auth/login/sms` - 验证码登录
- `POST /api/auth/register/sms` - 验证码注册
- `POST /api/auth/password/reset` - 重置密码
- `POST /api/auth/password/change` - 修改密码
- `POST /api/auth/phone/change` - 修改手机号
- `POST /api/auth/logout/all` - 登出所有设备
5. **数据库迁移脚本**
- 已创建 `api/migrations/add_sms_verification.sql`
### Android端实施
6. **数据模型**
- 已在 `AuthModels.kt` 中添加所有短信验证相关的请求和响应模型
7. **网络服务**
- 已在 `AuthService.kt` 中添加所有短信验证相关的API调用方法
8. **ViewModel扩展**
- 已在 `AuthViewModel.kt` 中添加:
- 验证码倒计时状态管理
- 发送验证码、验证码登录/注册、重置密码、修改密码、修改手机号、登出所有设备等方法
9. **UI组件**
- 已创建 `SmsCodeInput.kt` - 验证码输入框组件
- 已创建 `SendSmsButton.kt` - 发送验证码按钮组件
- 已创建 `PasswordStrengthIndicator.kt` - 密码强度指示器组件
10. **注册页面**
- 已修改 `RegisterScreen.kt`,添加验证码验证流程
- 集成了验证码输入、发送按钮和密码强度指示器
## 🔄 进行中/待完成的任务
### Android端UI实施
11. **登录页面** 🔄
- 需要修改 `LoginScreen.kt`
- 添加密码登录和验证码登录的切换功能
- 添加"忘记密码"链接
12. **密码重置页面**
- 需要创建 `ResetPasswordScreen.kt`
- 实现通过验证码重置密码的完整流程
13. **账户管理页面**
- 需要创建 `AccountManagementScreen.kt`
- 实现修改密码、修改手机号、登出管理功能
14. **个人页面修改**
- 需要修改 `ProfileScreen.kt`
- 添加"账户管理"入口
- 移除原有的登出按钮(归并到账户管理中)
15. **导航配置**
- 需要更新 `AppNavigation.kt`
- 添加密码重置页面和账户管理页面的路由
### 测试与部署
16. **测试**
- 创建后端测试脚本 `api/test_sms_verification.py`
- 进行端到端测试
17. **部署**
- 配置生产环境的腾讯云短信服务凭证
- 执行数据库迁移脚本
- 更新 `docker-compose.yml` 添加环境变量
## 📝 下一步操作指南
### 1. 完成剩余的Android UI页面
#### 修改登录页面
```kotlin
// 在 LoginScreen.kt 中添加:
// 1. 登录方式切换(密码/验证码)
// 2. 验证码登录UI
// 3. "忘记密码"链接
```
#### 创建密码重置页面
```kotlin
// 创建 ResetPasswordScreen.kt
// 实现:手机号 → 验证码 → 新密码 → 确认密码 → 提交
```
#### 创建账户管理页面
```kotlin
// 创建 AccountManagementScreen.kt
// 包含:修改密码、修改手机号、登出当前设备、登出所有设备
```
### 2. 配置腾讯云短信服务
1. 登录腾讯云控制台
2. 开通短信服务
3. 创建应用并获取 SDK AppID
4. 配置签名和模板:
- 注册验证码模板
- 登录验证码模板
- 重置密码验证码模板
- 修改手机号验证码模板
5. 获取 SecretId 和 SecretKey
6. 更新 `api/.env.production` 文件中的配置
### 3. 执行数据库迁移
```bash
cd api
psql -U postgres -d life_echo -f migrations/add_sms_verification.sql
```
### 4. 测试验证
1. 后端测试:
- 测试发送验证码API
- 测试验证码登录/注册
- 测试密码重置
- 测试频率限制
2. Android端测试
- 测试注册流程已完成UI
- 测试登录流程待完成UI
- 测试密码重置流程待完成UI
- 测试账户管理功能待完成UI
## 🎯 核心功能已就绪
后端所有API已经实现并可以使用Android端的核心组件和ViewModel也已准备就绪。剩余工作主要是完成UI页面的开发和集成测试。
## 📞 技术支持
如有问题,请参考:
- 后端API文档`api/docs/README.md`
- 前端实施计划:查看项目根目录下的计划文件

View File

@@ -0,0 +1,616 @@
# 短信验证码功能实施总结
## 概述
本文档总结了短信验证码功能的完整实施情况包括后端API、Android客户端、测试和部署等所有方面。
## 实施日期
2024-01-27
## 实施内容
### 一、后端实施 (FastAPI)
#### 1. 数据库模型
**新增表:`sms_verification_codes`**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | VARCHAR | 主键ID |
| phone | VARCHAR | 手机号 |
| code | VARCHAR | 6位验证码 |
| purpose | VARCHAR | 用途register/login/reset_password/change_phone |
| is_used | BOOLEAN | 是否已使用 |
| is_expired | BOOLEAN | 是否已过期 |
| expires_at | TIMESTAMP | 过期时间5分钟 |
| created_at | TIMESTAMP | 创建时间 |
| verified_at | TIMESTAMP | 验证时间 |
| ip_address | VARCHAR | 请求IP地址 |
**扩展表:`refresh_tokens`**
- 新增字段:`device_info` (VARCHAR) - 设备信息,用于全设备登出
**索引:**
- `idx_sms_phone` - 手机号索引
- `idx_sms_created_at` - 创建时间索引
- `idx_sms_purpose` - 用途索引
- `idx_sms_phone_purpose` - 复合索引
#### 2. 短信服务 (`api/services/sms_service.py`)
**核心功能:**
- ✅ 发送验证码集成腾讯云SMS SDK
- ✅ 验证验证码
- ✅ 频率限制60秒内同一手机号只能发送一次
- ✅ 验证码过期检查5分钟
- ✅ 验证码使用后标记
#### 3. 认证路由扩展 (`api/routers/auth.py`)
**新增API端点**
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/auth/sms/send` | POST | 发送验证码 |
| `/api/auth/login/sms` | POST | 验证码登录 |
| `/api/auth/register/sms` | POST | 验证码注册 |
| `/api/auth/password/reset` | POST | 重置密码 |
| `/api/auth/password/change` | POST | 修改密码(已登录) |
| `/api/auth/phone/change` | POST | 修改手机号 |
| `/api/auth/logout/all` | POST | 登出所有设备 |
#### 4. 依赖配置
**新增依赖:**
```
tencentcloud-sdk-python>=3.0.1000
```
**环境变量:**
```bash
TENCENT_SMS_SECRET_ID=your_secret_id
TENCENT_SMS_SECRET_KEY=your_secret_key
TENCENT_SMS_SDK_APP_ID=your_app_id
TENCENT_SMS_SIGN_NAME=your_sign_name
# 统一使用一个短信模板ID所有场景共用
TENCENT_SMS_TEMPLATE_ID=your_template_id
```
### 二、Android端实施
#### 1. 网络层扩展 (`AuthService.kt`)
**新增方法:**
-`sendVerificationCode()` - 发送验证码
-`loginWithSms()` - 验证码登录
-`registerWithSms()` - 验证码注册
-`resetPassword()` - 重置密码
-`changePassword()` - 修改密码
-`changePhone()` - 修改手机号
-`logoutAll()` - 登出所有设备
#### 2. ViewModel扩展 (`AuthViewModel.kt`)
**新增状态:**
-`smsCountdown` - 验证码倒计时60秒
**新增方法:**
-`sendVerificationCode()` - 发送验证码
-`loginWithSms()` - 验证码登录
-`registerWithSms()` - 验证码注册
-`resetPassword()` - 重置密码
-`changePassword()` - 修改密码
-`changePhone()` - 修改手机号
-`logoutAll()` - 登出所有设备
-`startCountdown()` - 启动倒计时
#### 3. UI组件
**可复用组件:**
-`SmsCodeInput.kt` - 验证码输入框6位数字自动聚焦
-`SendSmsButton.kt` - 发送验证码按钮(带倒计时)
-`CompactSendSmsButton.kt` - 紧凑版发送按钮
-`PasswordStrengthIndicator.kt` - 密码强度指示器
-`PasswordRequirements.kt` - 密码要求提示
#### 4. 新增页面
**密码重置页面 (`ResetPasswordScreen.kt`)**
- ✅ 手机号输入
- ✅ 发送验证码(带倒计时)
- ✅ 验证码输入
- ✅ 新密码输入
- ✅ 确认密码输入
- ✅ 密码强度指示
- ✅ 表单验证
- ✅ 成功后跳转登录
**账户管理页面 (`AccountManagementScreen.kt`)**
- ✅ 账户信息展示
- ✅ 修改密码对话框
- ✅ 修改手机号对话框
- ✅ 登出当前设备
- ✅ 登出所有设备(带二次确认)
#### 5. 页面修改
**注册页面 (`RegisterScreen.kt`)**
- ✅ 已在之前的实施中完成
- ✅ 手机号输入框后添加"发送验证码"按钮
- ✅ 验证码输入框
- ✅ 倒计时显示
**登录页面 (`LoginScreen.kt`)**
- ✅ 添加"忘记密码"链接
- ✅ 跳转到密码重置页面
**个人页面 (`ProfileScreen.kt`)**
- ✅ 移除原有的"登出"按钮
- ✅ 在"设置"区域添加"账户管理"入口
- ✅ 仅在已登录时显示
#### 6. 导航配置 (`AppNavigation.kt`)
**新增路由:**
-`Screen.ResetPassword` - 密码重置页面
-`Screen.AccountManagement` - 账户管理页面
**路由配置:**
- ✅ 密码重置成功后跳转到登录页面
- ✅ 登出成功后清空导航栈并跳转到登录页面
- ✅ 登录页面添加忘记密码回调
#### 7. 图标扩展 (`AppIcons.kt`)
**新增图标:**
-`ManageAccounts` - 账户管理
-`Lock` - 锁(密码)
-`Phone` - 手机
-`ExitToApp` - 登出
-`DevicesOther` - 多设备
### 三、测试
#### 1. 后端测试脚本 (`api/test_sms_verification.py`)
**测试模式:**
- ✅ 交互式测试(需要真实短信验证码)
- ✅ 自动化测试(需要测试验证码支持)
- ✅ API连接测试
**测试用例:**
- ✅ 发送验证码
- ✅ 频率限制
- ✅ 验证码注册
- ✅ 验证码登录
- ✅ 密码重置
- ✅ 修改密码
- ✅ 修改手机号
- ✅ 登出所有设备
#### 2. 测试文档
**文档:**
-`api/docs/短信验证码测试指南.md` - 完整的测试指南
- ✅ 包含手动测试步骤
- ✅ 包含常见问题解答
- ✅ 包含测试检查清单
### 四、部署
#### 1. 数据库迁移
**迁移脚本:** `api/migrations/add_sms_verification.sql`
- ✅ 创建 `sms_verification_codes`
- ✅ 创建索引
- ✅ 扩展 `refresh_tokens`
- ✅ 添加表和字段注释
#### 2. 部署文档
**文档:** `api/docs/部署指南.md`
- ✅ 腾讯云短信服务配置步骤
- ✅ 环境变量配置说明
- ✅ 数据库迁移步骤
- ✅ Docker部署配置
- ✅ Systemd部署配置
- ✅ GitHub Actions配置
- ✅ 监控与告警配置
- ✅ 安全加固建议
- ✅ 备份与恢复步骤
- ✅ 故障排查指南
- ✅ 性能优化建议
#### 3. 部署脚本
**脚本:** `api/deploy.sh`
- ✅ 自动检查前置条件
- ✅ 验证环境变量
- ✅ 安装依赖
- ✅ 执行数据库迁移
- ✅ 验证部署
- ✅ 测试服务连接
#### 4. GitHub Actions配置文档
**文档:** `github-actions-secrets.md`
- ✅ 列出所有需要配置的Secrets
- ✅ 配置步骤说明
## 功能特性
### 安全性
- ✅ 验证码采用6位随机数字
- ✅ 5分钟过期时间
- ✅ 60秒发送频率限制
- ✅ 验证码使用后立即标记
- ✅ 密码修改需验证旧密码
- ✅ 手机号修改需验证码验证
- ✅ 敏感操作记录IP地址
- ✅ 密码强度验证
### 用户体验
- ✅ 倒计时显示60秒
- ✅ 自动聚焦验证码输入框
- ✅ 实时表单验证
- ✅ 友好的错误提示
- ✅ 加载状态指示
- ✅ 成功后自动跳转
- ✅ 密码强度可视化
- ✅ 二次确认(危险操作)
### 性能优化
- ✅ 验证码查询使用索引
- ✅ 数据库连接池
- ✅ 异步操作
- ✅ 错误重试机制
## 文件清单
### 后端文件
```
api/
├── services/
│ └── sms_service.py # 短信服务(新增)
├── migrations/
│ └── add_sms_verification.sql # 数据库迁移脚本(新增)
├── docs/
│ ├── 短信验证码测试指南.md # 测试指南(新增)
│ └── 部署指南.md # 部署指南(新增)
├── test_sms_verification.py # 测试脚本(新增)
├── deploy.sh # 部署脚本(新增)
├── requirements.txt # 更新依赖
├── .env.production # 更新环境变量
└── routers/auth.py # 扩展认证路由
```
### Android文件
```
app-android/app/src/main/java/com/huaga/life_echo/
├── ui/
│ ├── screens/
│ │ ├── ResetPasswordScreen.kt # 密码重置页面(新增)
│ │ ├── AccountManagementScreen.kt # 账户管理页面(新增)
│ │ ├── RegisterScreen.kt # 修改(已在之前完成)
│ │ ├── LoginScreen.kt # 修改
│ │ └── ProfileScreen.kt # 修改
│ ├── components/auth/
│ │ ├── SmsCodeInput.kt # 验证码输入框(已存在)
│ │ ├── SendSmsButton.kt # 发送验证码按钮(已存在)
│ │ └── PasswordStrengthIndicator.kt # 密码强度指示器(已存在)
│ └── icons/
│ └── AppIcons.kt # 扩展图标
├── viewmodel/
│ └── AuthViewModel.kt # 扩展(已在之前完成)
├── network/
│ ├── AuthService.kt # 扩展(已在之前完成)
│ └── models/
│ └── AuthModels.kt # 扩展(已在之前完成)
└── navigation/
└── AppNavigation.kt # 扩展
```
### 文档文件
```
├── SMS_VERIFICATION_IMPLEMENTATION_STATUS.md # 实施状态(已存在)
├── SMS_VERIFICATION_IMPLEMENTATION_SUMMARY.md # 实施总结(本文档)
└── github-actions-secrets.md # GitHub Actions配置已存在
```
## API文档
### 发送验证码
```http
POST /api/auth/sms/send
Content-Type: application/json
{
"phone": "13800138000",
"purpose": "register" // register/login/reset_password/change_phone
}
Response 200:
{
"message": "",
"expires_in": 300
}
Response 429:
{
"detail": "60"
}
```
### 验证码登录
```http
POST /api/auth/login/sms
Content-Type: application/json
{
"phone": "13800138000",
"code": "123456"
}
Response 200:
{
"access_token": "eyJ...",
"refresh_token": "eyJ...",
"token_type": "bearer"
}
```
### 验证码注册
```http
POST /api/auth/register/sms
Content-Type: application/json
{
"phone": "13800138000",
"code": "123456",
"password": "password123",
"nickname": "",
"email": "optional@email.com"
}
Response 201:
{
"access_token": "eyJ...",
"refresh_token": "eyJ...",
"token_type": "bearer"
}
```
### 重置密码
```http
POST /api/auth/password/reset
Content-Type: application/json
{
"phone": "13800138000",
"code": "123456",
"new_password": "newpassword123"
}
Response 200:
{
"message": ""
}
```
### 修改密码(已登录)
```http
POST /api/auth/password/change
Authorization: Bearer <access_token>
Content-Type: application/json
{
"old_password": "oldpassword123",
"new_password": "newpassword123"
}
Response 200:
{
"message": ""
}
```
### 修改手机号
```http
POST /api/auth/phone/change
Authorization: Bearer <access_token>
Content-Type: application/json
{
"new_phone": "13900139000",
"code": "123456"
}
Response 200:
{
"id": "user_id",
"phone": "13900139000",
"nickname": "",
...
}
```
### 登出所有设备
```http
POST /api/auth/logout/all
Authorization: Bearer <access_token>
Response 200:
{
"message": ""
}
```
## 使用说明
### 开发环境测试
1. 启动后端服务:
```bash
cd api
python main.py
```
2. 运行测试脚本:
```bash
cd api
python test_sms_verification.py
```
3. 运行Android应用并测试各个功能
### 生产环境部署
1. 配置腾讯云短信服务(参考部署指南)
2. 配置环境变量:
```bash
cd api
cp .env.production.example .env.production
# 编辑 .env.production填入实际配置
```
3. 运行部署脚本:
```bash
cd api
./deploy.sh
```
4. 或使用Docker部署
```bash
cd api
docker-compose up -d
```
## 注意事项
### 安全
1. **保护API密钥**
- 不要将腾讯云API密钥提交到Git仓库
- 使用环境变量或密钥管理服务
- 定期轮换密钥
2. **验证码安全**
- 验证码仅5分钟有效
- 使用后立即失效
- 60秒频率限制防止暴力破解
3. **密码安全**
- 强制最小长度6位
- 建议包含大小写字母、数字和特殊字符
- 密码加密存储
### 性能
1. **数据库优化**
- 使用索引加速查询
- 定期清理过期验证码
- 监控数据库性能
2. **短信发送**
- 异步发送避免阻塞
- 监控发送成功率
- 设置合理的超时时间
3. **缓存**
- 使用Redis缓存频率限制状态
- 缓存用户会话信息
### 监控
1. **关键指标**
- 短信发送成功率
- 验证码验证成功率
- API响应时间
- 错误率
2. **日志**
- 记录所有短信发送操作
- 记录验证失败原因
- 记录异常情况
3. **告警**
- 发送失败率过高
- API响应时间过长
- 数据库连接失败
## 后续优化建议
### 功能增强
1. **验证码类型**
- 支持语音验证码
- 支持邮箱验证码
- 支持图形验证码(防机器人)
2. **安全增强**
- 设备指纹识别
- 异常登录检测
- 多因素认证MFA
3. **用户体验**
- 验证码自动填充Android SMS Retriever API
- 记住设备(免验证码登录)
- 生物识别登录
### 性能优化
1. **缓存优化**
- 缓存用户信息
- 缓存验证码状态
- 使用CDN加速
2. **数据库优化**
- 分表分库
- 读写分离
- 使用时序数据库存储验证码记录
3. **服务优化**
- 使用消息队列处理短信发送
- 负载均衡
- 服务降级和熔断
## 相关文档
- [实施状态文档](SMS_VERIFICATION_IMPLEMENTATION_STATUS.md)
- [测试指南](api/docs/短信验证码测试指南.md)
- [部署指南](api/docs/部署指南.md)
- [GitHub Actions配置](github-actions-secrets.md)
## 联系方式
如有问题或建议,请联系开发团队。
## 更新日志
- 2024-01-27: 完成短信验证码功能实施
- 后端API实现
- Android客户端实现
- 测试脚本和文档
- 部署脚本和文档
---
**实施完成日期:** 2024-01-27
**实施人员:** AI Assistant
**状态:** ✅ 已完成

View File

@@ -0,0 +1,28 @@
# GitHub Actions Secrets 配置
## 必需配置
- **SSH_PRIVATE_KEY**:
```
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
QyNTUxOQAAACB3BQ//aK/77ZssuViiCXioGClmtNEPCPHYfAMIYWDXtgAAAKDC1YPXwtWD
1wAAAAtzc2gtZWQyNTUxOQAAACB3BQ//aK/77ZssuViiCXioGClmtNEPCPHYfAMIYWDXtg
AAAECC+VS5S2bvxIpnVxH+VsvOndnzgu600cNGibd/lpulkHcFD/9or/vtmyy5WKIJeKgY
KWa00Q8I8dh8AwhhYNe2AAAAGGdpdGh1Yi1hY3Rpb25zLWxpZmUtZWNobwECAwQF
-----END OPENSSH PRIVATE KEY-----
```
- **SSH_USER**: `root`
- **SSH_HOST**: `1.15.29.57`
- **ALIYUN_CR_USERNAME**: `zaikunxu`
- **ALIYUN_CR_PASSWORD**: `57uCV,g4LF2cqm8`
## 可选配置
- **SSH_PORT**: `22` (默认值)
- **DEPLOY_PATH**: `/home/ubuntu/production/lifecho`