authenticator/memory-bank/systemPatterns.md

系统模式 (System Patterns)

1. 总体架构

本应用遵循一个经典的纯客户端、组件化的 SPA 架构。

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. 核心组件关系

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