# 系统模式 (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