# 项目简报：SPA TOTP Authenticator

## 1. 项目核心目标

构建一个基于 Vite + React 的纯前端单页应用（SPA），作为一个 TOTP (基于时间的一次性密码) 认证器。所有用户数据将安全地存储在用户本地浏览器中，不依赖任何后端服务器。

## 2. 主要功能需求

- **TOTP 信息管理**:
  - **录入**: 提供一个表单，用于添加新的 TOTP 配置，信息包括：
    - **名称 (Name)**: 用于用户识别的标签，例如 "GitHub"。
    - **发行方 (Issuer)**: 可选项，进一步说明账户来源，例如 "user@example.com"。
    - **密钥 (Secret Key)**: 用于生成 TOTP 的密钥。
    - **位数 (Digits)**: 密码长度，支持 6, 7, 或 8 位。
    - **算法 (Algorithm)**: 哈希算法，默认为 SHA1。
    - **周期 (Period)**: 密码刷新周期，通常为 30 秒。
  - **存储**: 将录入的 TOTP 信息持久化存储在浏览器的 IndexedDB 中。
  - **列表**: 在首页展示所有已保存的 TOTP 账户列表。
  - **删除**: 提供删除已保存账户的功能。

- **TOTP 展示与交互**:
  - **实时显示**: 在首页清晰地展示每个账户当前的一次性密码。
  - **自动刷新**: 密码应根据其生命周期（例如 30 秒）自动刷新，并提供一个视觉指示器（如进度条）来显示剩余时间。
  - **一键复制**: 为每个密码提供一个复制按钮，方便用户快速将密码复制到剪贴板。

- **数据管理 (导入/导出)**:
  - **支持格式**:
    1.  **JSON 格式**: 导出所有账户信息为结构化的 JSON 文件，便于完整备份和恢复。
    2.  **纯文本格式**: 支持 `github.com/rsc/2fa` 的兼容格式。
        -   格式为多行文本，每行代表一个账户。
        -   每行格式: `NameWithoutSpaces Digits(6/7/8) totp-key`。
  - **备份 (导出)**: 提供将数据导出为上述两种格式的功能。
  - **恢复 (导入)**: 允许用户通过上传文件或粘贴文本的方式，使用上述两种格式恢复数据。
  - **URI 导入**: 支持通过直接粘贴 `otpauth://` 格式的 URI 来快速添加单个账户。

## 3. 技术栈

- **构建工具**: Vite
- **前端框架**: React
- **样式**: Tailwind CSS (`@tailwindcss/postcss`)
- **数据持久化**: IndexedDB
- **TOTP 算法**: 使用一个可靠的第三方 JavaScript 库来处理 TOTP 生成逻辑。
- **核心语言**: TypeScript (推荐) 或 JavaScript (ES6+)

## 4. 项目边界

- **纯客户端**: 无任何服务器端逻辑或数据存储。所有操作均在浏览器内完成。
- **TOTP Only**: 暂时仅支持 TOTP，不支持 HOTP (基于计数器的一次性密码)。
- **安全性**: 密钥直接存储于客户端 IndexedDB。需要明确告知用户数据仅存于本地，清理浏览器数据会导致信息丢失。备份文件需要提醒用户妥善保管。
- **浏览器兼容性**: 优先支持现代主流浏览器 (Chrome, Firefox, Safari, Edge)。