authenticator/memory-bank/projectbrief.md

项目简报：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)。