# BandTOTP 身份验证器

<div align="center">

![App Screenshot](https://img.shields.io/badge/Platform-Android-green)
![Kotlin](https://img.shields.io/badge/Language-Kotlin-orange)
![Compose](https://img.shields.io/badge/UI-Jetpack%20Compose-blue)
![API Level](https://img.shields.io/badge/API-28+-brightgreen)

**一款现代化的TOTP身份验证器应用，支持小米手环同步**

*安全 • 美观 • 高效 • 现代化*

</div>

---

## 🌟 项目概述

BandTOTP 是一款基于 Google Authenticator 设计风格的现代化双因子身份验证器应用，采用 Material Design 3 设计语言，不仅支持传统的TOTP验证码生成，更具备与小米手环的无缝同步功能，让您的验证码随时随地触手可及。

### ✨ 核心特性

- **🎨 现代化UI**: 基于 Jetpack Compose + Material Design 3
- **📱 多种添加方式**: 二维码扫描、文件导入、手动添加
- **⌚ 手环同步**: 完整的小米手环双向同步功能
- **🔒 安全可靠**: 本地存储，支持多种TOTP算法
- **🎯 用户友好**: 直观的界面设计和流畅的动画效果

---

## 📸 应用截图

> 注：可在此处添加应用的实际截图展示主要功能界面

---

## 🚀 功能特色

### 🔐 验证码管理
- **实时生成**: 支持标准TOTP和Steam格式验证码
- **智能识别**: 自动识别服务类型并显示对应图标
- **倒计时显示**: 圆形进度条，剩余时间直观可见
- **拖拽排序**: 长按拖拽自定义账户顺序

### 📲 多样化添加方式
- **📷 相机扫码**: 集成 CameraX + ML Kit 专业扫码体验
- **📁 文件导入**: 支持标准格式和Steam JSON导入
- **✏️ 手动添加**: 完整参数配置，支持自定义算法

### ⌚ 智能手环同步
- **双向同步**: 手机与手环账户互相同步
- **状态可视化**: 实时显示同步状态（仅手机/仅手环/已同步）
- **批量操作**: 一键同步所有账户到指定设备
- **冲突处理**: 智能合并去重，避免数据冲突

### 🎨 用户体验
- **Material You**: 动态主题色彩系统
- **流畅动画**: 精心设计的页面转场和交互动画
- **手势操作**: 支持左滑删除、双指缩放等直观操作
- **无障碍支持**: 完整的无障碍功能支持

---

## 🛠 技术架构

### 核心技术栈
- **开发语言**: Kotlin 2.0.21
- **UI框架**: Jetpack Compose + Material Design 3
- **架构模式**: MVVM + Repository
- **异步处理**: Kotlin Coroutines
- **相机扫码**: CameraX + ML Kit Barcode Scanning
- **数据存储**: SharedPreferences + JSON序列化
- **小米手环**: XMS Wearable SDK

### 项目结构
```
app/src/main/java/cn/deepfal/band/TOTPauthenticator/
├── MainActivity.kt                 # 主Activity - 现代化设计
├── data/
│   └── TOTPInfo.kt                # TOTP数据模型
├── components/
│   ├── ModernTOTPCard.kt          # 现代化验证码卡片
│   ├── AddComponents.kt           # 添加相关组件
│   ├── ReorderableBandAccountsList.kt # 可重排序手环账户列表
│   └── SyncScreen.kt              # 同步管理界面
├── scanner/
│   └── QRCodeScanner.kt           # 专业二维码扫描器
├── sync/
│   └── SyncManager.kt             # 同步逻辑管理
├── ui/theme/                      # Material Design主题配置
└── utils/
    ├── LocalAccountManager.kt     # 本地存储管理
    └── TOTPGenerator.kt           # TOTP算法实现
```

### 关键依赖
```kotlin
// Jetpack Compose 生态
implementation(platform("androidx.compose:compose-bom:2024.12.01"))
implementation("androidx.compose.material3:material3")
implementation("androidx.compose.material:material-icons-extended")

// 相机与扫码
implementation("androidx.camera:camera-camera2:1.3.1")
implementation("com.google.mlkit:barcode-scanning:17.2.0")

// 小米可穿戴SDK
implementation(files("libs/xms-wearable-lib_1.4_release.aar"))

// 拖拽排序
implementation("org.burnoutcrew.composereorderable:reorderable:0.9.6")
```

---

## 📦 构建与运行

### 环境要求
- **Android Studio**: Hedgehog | 2023.1.1 或更高版本
- **Gradle**: 8.12.0
- **Kotlin**: 2.0.21
- **目标SDK**: 36 (Android 14)
- **最低SDK**: 28 (Android 9.0)

### 快速开始

1. **克隆项目**
   ```bash
   git clone https://github.com/your-username/BandTOTP-APP.git
   cd BandTOTP-APP
   ```

2. **配置签名** (可选)
   
   创建 `keystore.properties` 文件：
   ```properties
   debug.store.file=keystore/keystore.jks
   debug.store.password=your_password
   debug.key.alias=your_alias
   debug.key.password=your_password
   
   release.store.file=keystore/keystore.jks
   release.store.password=your_password
   release.key.alias=your_alias
   release.key.password=your_password
   ```

3. **构建运行**
   ```bash
   ./gradlew assembleDebug
   ./gradlew installDebug
   ```

### 小米手环配置

要使用手环同步功能，需要：

1. **安装手环应用**: 在小米手环上安装对应的TOTP应用
2. **权限配置**: 应用会自动申请必要的蓝牙和设备管理权限
3. **设备配对**: 确保手环已通过小米穿戴应用正确配对

---

## 🔧 配置说明

### 权限说明
```xml
<!-- 蓝牙通信 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<!-- 相机扫码 -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- 文件读取 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
```

### 支持的导入格式

- **标准TOTP URL**: `otpauth://totp/Service:user@example.com?secret=...`
- **Steam JSON**: Steam Guard导出的JSON格式
- **文本文件**: 包含上述格式的纯文本文件

---

## 📱 使用说明

### 基本操作

1. **添加账户**
   - 点击右下角"+"按钮
   - 选择扫码、导入文件或手动添加
   - 按照提示完成添加流程

2. **管理账户**
   - 左滑账户卡片查看编辑/删除选项
   - 长按进入排序模式，拖拽调整顺序
   - 点击验证码自动复制到剪贴板

3. **手环同步**
   - 点击同步按钮进入同步界面
   - 查看手机和手环的账户状态
   - 使用批量同步功能管理设备间数据

### 高级功能

- **Steam账户**: 自动识别Steam格式，生成5位验证码
- **自定义参数**: 手动添加时可配置算法、位数、周期等
- **重复检测**: 导入时自动去重，避免重复账户

---

## 🤝 贡献指南

我们欢迎所有形式的贡献！无论是bug报告、功能建议、代码提交还是文档改进。