initial commit

2025-06-07 23:17:40 +08:00
commit 6561991a9e
36 changed files with 5849 additions and 0 deletions
--- a/memory-bank/activeContext.md
+++ b/memory-bank/activeContext.md
@ -0,0 +1,24 @@
+# 当前上下文 (Active Context)
+
+## 1. 当前工作焦点
+
+**阶段四：`otpauth://` URI 功能已完成**。
+
+已成功为应用添加了完整的 `otpauth://` URI 支持，包括通过多种方式导入和导出。
+
+## 2. 近期决策与实现
+
+- **URI 解析服务**: 创建了 `src/services/uriParser.ts`，使用 `otpauth` 库来解析 URI 字符串，并将其转换为 `TotpAccount` 对象。
+- **表单集成**:
+    - 在 `TotpForm.tsx` 中，新增了一个专门用于粘贴 `otpauth://` URI 的输入区域。
+    - 实现了 URI 输入与手动表单输入的互斥逻辑：当一个被使用时，另一个将被禁用，以防止数据冲突。
+    - URI 解析成功后，会自动填充手动输入表单。
+- **导入/导出功能扩展**:
+    - 在 `SettingsPage.tsx` 中，添加了“导出为 URI 文本”功能，可以将所有账户转换为多行 `otpauth://` URI 格式并下载为 `.txt` 文件。
+    - 扩展了文件导入逻辑，使其能够识别和解析包含多行 `otpauth://` URI 的 `.txt` 文件。
+
+## 3. 下一步计划
+
+- **代码审查和重构**: 回顾已实现的功能，寻找可以优化或重构的地方。
+- **UI/UX 优化**: 检查应用的整体用户体验，特别是在导入/导出流程中，考虑增加更友好的用户提示和反馈。
+- **全面测试**: 对所有 `otpauth://` 相关功能进行手动测试，确保其稳定性和正确性。
--- a/memory-bank/productContext.md
+++ b/memory-bank/productContext.md
@ -0,0 +1,28 @@
+# 产品背景 (Product Context)
+
+## 1. 解决的问题
+
+在数字化生活中，双因素认证 (2FA) 已成为保护账户安全的重要手段。其中，基于时间的一次性密码 (TOTP) 是最常见的实现方式之一。用户通常需要依赖手机应用（如 Google Authenticator, Authy）或桌面程序来管理他们的 TOTP 密钥并获取动态密码。
+
+然而，现有方案存在一些痛点：
+
+- **跨设备同步不便**: 某些认证应用（特别是早期版本）不提供云同步功能，更换设备或同时在多台设备上使用时，数据迁移非常繁琐。
+- **数据备份和恢复**: 备份和恢复流程往往不够直观，用户可能会因为忘记备份或备份文件丢失而永久失去对账户的访问权限。
+- **平台依赖性**: 用户被锁定在特定的应用或生态系统中。
+
+本项目旨在提供一个轻量、透明且完全由用户掌控的 TOTP 管理工具，以解决上述问题。
+
+## 2. 产品定位与目标用户
+
+- **定位**: 一个纯粹的、基于浏览器的、开源的 TOTP 认证器。它将简单、安全和用户控制权放在首位。
+- **目标用户**:
+  - **注重隐私和数据所有权的技术爱好者**: 他们希望自己的敏感密钥数据完全掌握在自己手中，不上传到任何云端。
+  - **开发者和 IT 专业人员**: 他们需要一个便捷、可靠的工具来管理多个服务的 TOTP，并欣赏其导入/导出功能的灵活性。
+  - **普通用户**: 寻求一个简单、免费且无需安装额外软件的备用 TOTP 解决方案。
+
+## 3. 核心用户体验 (UX) 目标
+
+- **即时可用**: 用户打开网页即可立即使用，无需注册或复杂配置。
+- **操作直观**: 添加、查看、复制和删除 TOTP 的流程应尽可能简化，符合用户直觉。
+- **信息清晰**: 动态密码、剩余时间、账户名称等关键信息一目了然。
+- **安全透明**: 明确告知用户所有数据均存储在本地，并提供可靠的备份/恢复机制，让用户对自己的数据有完全的控制感和安全感。
--- a/memory-bank/progress.md
+++ b/memory-bank/progress.md
@ -0,0 +1,78 @@
+# 进展追踪 (Progress)
+
+## 1. 已完成的功能 (What Works)
+
+- **项目规划**:
+  - [x] 核心需求定义 (`projectbrief.md`)
+  - [x] 产品背景和目标确立 (`productContext.md`)
+  - [x] 技术栈选型 (`techContext.md`)
+  - [x] 系统架构设计 (`systemPatterns.md`)
+  - [x] 初始化计划制定 (`activeContext.md`)
+
+## 2. 当前状态
+
+- **阶段**: 功能完善。
+- **描述**: 所有核心功能，包括 TOTP 管理和两种格式（JSON, TXT）的数据导入/导出，均已完成。
+
+## 3. 未完成的功能 (What's Left to Build)
+
+### 阶段一: 基础架构
+
+- [x] 初始化 Vite + React + TypeScript 项目。
+- [x] 安装所有 npm 依赖项。
+- [x] 配置 Tailwind CSS。
+- [x] 建立基本的文件夹结构 (`src/pages`, `src/components`, `src/services`, `src/hooks`, `src/types`)。
+- [x] 设置 IndexedDB 服务 (`db.ts`)。
+- [x] 设置基础路由 (`react-router-dom`)。
+
+### 阶段二:核心 TOTP 功能
+
+- [x] **数据录入**:
+  - [x] 创建 "添加新账户" 页面和表单。
+  - [x] 实现表单验证。
+  - [x] 将新账户数据存入 IndexedDB。
+- [x] **数据展示**:
+  - [x] 从 IndexedDB 读取所有账户。
+  - [x] 在首页以卡片形式展示每个账户。
+- [x] **实时功能**:
+  - [x] 计算并显示实时 TOTP 密码。
+  - [x] 实现密码自动刷新的倒计时进度条。
+  - [x] 实现一键复制密码功能。
+- [x] **数据删除**:
+  - [x] 添加删除账户的按钮。
+  - [x] 实现从 IndexedDB 中删除指定账户的功能。
+
+### 阶段三: 导入/导出功能
+
+- [x] **导出**:
+  - [x] 实现将所有数据导出为 JSON 文件的功能。
+  - [x] 实现将所有数据导出为 `rsc/2fa` 兼容的文本格式的功能。
+- [x] **导入**:
+  - [x] 实现通过上传/粘贴 JSON 文件来导入数据的功能。
+  - [x] 实现通过上传/粘贴 `rsc/2fa` 格式文本来导入数据的功能。
+  - [x] 处理导入时的冲突（例如，覆盖或合并）。
+
+## 4. 已知问题 (Known Issues)
+
+- 尚无。
+
+## 5. 决策日志 (Decision Log)
+
+- **2025-06-06**:
+  - 决定使用 Vite + React + TypeScript + Tailwind CSS 技术栈。
+  - 决定支持 JSON 和 `rsc/2fa` 两种导入/导出格式。
+  - 决定使用 `idb` 和 `otpauth` 作为核心库。
+
+### 阶段四: URI 支持
+
+- [x] **URI 解析**:
+  - [x] 实现一个可以解析 `otpauth://` URI 的函数。
+  - [x] 提取所有相关参数 (secret, issuer, algorithm, digits, period)。
+- [x] **表单集成**:
+  - [x] 在添加账户表单中，允许用户粘贴 URI。
+  - [x] 自动填充表单字段。
+- [x] **导入/导出扩展**:
+  - [x] 实现导出为多行 `otpauth://` URI 的文本文件。
+  - [x] 实现从多行 `otpauth://` URI 的文本文件导入。
+- [x] **测试**:
+  - [x] (手动) 已完成核心功能验证。
--- a/memory-bank/projectbrief.md
+++ b/memory-bank/projectbrief.md
@ -0,0 +1,50 @@
+# 项目简报：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)。
--- a/memory-bank/systemPatterns.md
+++ b/memory-bank/systemPatterns.md
@ -0,0 +1,76 @@
+# 系统模式 (System Patterns)
+
+## 1. 总体架构
+
+本应用遵循一个经典的纯客户端、组件化的 SPA 架构。
+
+```mermaid
+graph TD
+    subgraph Browser
+        UI(React Components)
+        State(State Management)
+        Logic(Business Logic)
+        DB(IndexedDB)
+    end
+
+    User[User] --> UI
+    UI --> State
+    UI --> Logic
+    Logic --> State
+    Logic --> DB
+```
+
+- **用户 (User)**: 与界面交互。
+- **UI (React Components)**: 负责渲染视图。这是用户直接交互的层。组件是自包含的，并从状态管理层获取数据。
+- **状态管理 (State Management)**: 使用 React Context API 和 Hooks (`useState`, `useReducer`) 构成。它持有应用的瞬时状态，如 TOTP 列表、UI 加载状态等。
+- **业务逻辑 (Business Logic)**:
+  - **TOTP 生成**: 使用 `otpauth` 库计算当前密码。
+  - **数据服务**: 封装了对 IndexedDB 的所有 CRUD (创建, 读取, 更新, 删除) 操作。
+  - **导入/导出**: 处理不同格式数据的解析和序列化。
+  - **URI 解析**: 新增一个专门的解析器，负责处理 `otpauth://` 格式的 URI。它将 URI 字符串作为输入，输出一个结构化的账户对象，用于填充表单或直接保存。
+- **IndexedDB**: 作为持久化存储层，保存用户的 TOTP 账户信息。
+
+## 2. 关键设计模式
+
+- **组件化模式**:
+  - **容器组件 (Container Components)**: 负责数据获取和业务逻辑，例如 `TotpListPage`。
+  - **展示组件 (Presentational Components)**: 负责渲染 UI，接收 props 并显示，例如 `TotpCard`, `CopyButton`。
+  - **自定义钩子 (Custom Hooks)**: 将可重用的逻辑（如与 IndexedDB 的交互、TOTP 计时器）封装在自定义 Hook 中（例如 `useDatabase`, `useTotpTimer`），以实现逻辑的复用和分离。
+
+- **数据流模式**:
+  - **单向数据流**: 遵循 React 的标准模式。状态从上层组件（或 Context）流向子组件。用户操作通过回调函数向上触发状态更新。
+  - **Context as State Provider**: 创建一个 `DbContext` 和一个 `TotpProvider`，在应用顶层注入，使得任何深层嵌套的组件都能访问数据库实例和 TOTP 数据，避免了 props drilling。
+
+- **服务层模式 (Service Layer)**:
+  - 创建一个 `databaseService.ts` 模块，将所有与 `idb` 库的交互逻辑封装起来。这使得应用的其余部分与具体的数据库实现解耦。如果未来需要更换存储方案，只需修改这个服务层。
+
+- **异步处理模式**:
+  - **Promise-based**: 所有与 IndexedDB 的交互、文件读取（导入）都是异步的。将广泛使用 `async/await` 语法来处理这些异步操作，使代码更易读。
+  - **加载与错误状态**: 在 UI 中明确处理异步操作的加载 (loading)、成功 (success) 和错误 (error) 状态，为用户提供及时的反馈。
+
+## 3. 核心组件关系
+
+```mermaid
+graph TD
+    App[App.tsx] --> Router[React Router]
+    Router --> HomePage[HomePage.tsx]
+    Router --> AddPage[AddPage.tsx]
+    Router --> SettingsPage[SettingsPage.tsx]
+
+    HomePage --> TotpList[TotpList.tsx]
+    TotpList --> TotpCard[TotpCard.tsx]
+    TotpCard --> TotpDisplay[TotpDisplay.tsx]
+    TotpCard --> CountdownBar[CountdownBar.tsx]
+    TotpCard --> CopyButton[CopyButton.tsx]
+
+    AddPage --> TotpForm[TotpForm.tsx]
+    SettingsPage --> ImportExport[ImportExport.tsx]
+
+    subgraph Global Context
+        DatabaseProvider[DatabaseProvider]
+        TotpProvider[TotpProvider]
+    end
+
+    App --> DatabaseProvider
+    DatabaseProvider --> TotpProvider
+    TotpProvider --> Router
--- a/memory-bank/techContext.md
+++ b/memory-bank/techContext.md
@ -0,0 +1,44 @@
+# 技术背景 (Tech Context)
+
+## 1. 技术选型
+
+- **构建与开发环境**:
+  - **Vite**: 选择 Vite 作为构建工具，因为它提供了极速的冷启动、即时的热模块替换 (HMR) 和优化的构建输出。
+  - **Node.js/npm**: 用于项目依赖管理和运行开发脚本。
+
+- **前端框架**:
+  - **React**: 使用 React (v18+) 构建用户界面。其组件化架构非常适合管理 TOTP 列表和独立的 UI 元素。
+  - **React Hooks**: 将广泛使用 Hooks (如 `useState`, `useEffect`, `useCallback`) 来管理组件状态和生命周期。
+
+- **样式**:
+  - **Tailwind CSS**: 一个功能优先的 CSS 框架，可以快速构建现代化的界面而无需离开 HTML (或 JSX)。
+  - **PostCSS**: 与 Tailwind CSS 配合使用，用于处理和转换 CSS。
+
+- **状态管理**:
+  - **React Context API**: 对于这个规模的项目，React 自带的 Context API 足以在组件间共享状态（例如 TOTP 列表），无需引入 Redux 或 MobX 等外部库。
+
+- **数据持久化**:
+  - **IndexedDB**: 选择 IndexedDB 是因为它为客户端提供了强大的结构化数据存储能力，远胜于 localStorage，非常适合存储包含多个字段的 TOTP 账户信息。
+  - **`idb` 库**: 为了简化 IndexedDB 的操作，将使用 `idb` 这个轻量级库，它提供了基于 Promise 的简洁 API。
+
+- **TOTP 逻辑**:
+  - **`otpauth` 库**: 这是一个流行的、经过验证的库，用于生成和解析 TOTP/HOTP URL，并能计算出一次性密码。我们将用它来处理核心的 TOTP 算法。其 `OTP.parse(uri)` 方法可以直接将 `otpauth://` URI 解析为一个包含所有参数的对象，极大地简化了 URI 的导入功能开发。
+
+- **语言**:
+  - **TypeScript**: 推荐使用 TypeScript 来增强代码的健壮性和可维护性，提供类型安全。
+
+## 2. 开发工作流
+
+1.  **初始化**: 使用 `npm create vite@latest` 命令创建项目模板。
+2.  **安装依赖**: 安装 React, Tailwind CSS, `idb`, `otpauth` 等核心依赖。
+3.  **配置**:
+    -   配置 `tailwind.config.js` 和 `postcss.config.js` 以启用 Tailwind CSS。
+    -   配置 `tsconfig.json` 以获得最佳的 TypeScript 开发体验。
+4.  **开发**: 运行 `npm run dev` 启动 Vite 开发服务器。
+5.  **构建**: 运行 `npm run build` 将项目打包为静态文件，用于部署。
+
+## 3. 关键技术决策
+
+- **不使用后端**: 这是项目的核心原则。所有逻辑和数据都在客户端处理，确保用户数据的隐私和所有权。
+- **优先选择原生 Web API**: 在可能的情况下，优先使用浏览器原生 API (如 IndexedDB, Crypto API)，仅在能显著简化开发时才引入第三方库。
+- **模块化**: 代码将按功能进行模块化组织（例如，`services/idb.ts`, `hooks/useTotp.ts`, `components/TotpCard.tsx`），以保持代码库的清晰和可扩展性。