initial commit

2025-06-07 23:17:40 +08:00
commit 6561991a9e
36 changed files with 5849 additions and 0 deletions
--- 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