# Brew Guide 项目架构文档

> 面向开发者的快速上手指南，帮助你快速理解项目结构

## 技术栈速览

| 技术                  | 用途              |
| --------------------- | ----------------- |
| Next.js 15 + React 19 | 前端框架          |
| Tailwind CSS 4        | 样式              |
| Zustand               | 状态管理          |
| Dexie (IndexedDB)     | 本地数据库        |
| Capacitor             | 移动端/桌面端打包 |
| Framer Motion         | 动画              |

---

## 目录结构概览

```
src/
├── app/              # Next.js App Router 页面
├── components/       # UI 组件
├── lib/              # 核心逻辑和工具
├── providers/        # React Context Providers
├── styles/           # 全局样式和字体
└── types/            # 类型定义
```

---

## 核心模块说明

### 📁 `src/components/` - UI 组件

| 目录           | 说明                                                                            |
| -------------- | ------------------------------------------------------------------------------- |
| `brewing/`     | **冲煮相关** - 计时器 (`BrewingTimer`)、注水可视化 (`PourVisualizer`)、阶段控制 |
| `coffee-bean/` | **咖啡豆管理** - 列表、详情、表单、二维码、评分、年度报告等                     |
| `notes/`       | **冲煮笔记** - 记录详情、表单、列表、分享                                       |
| `equipment/`   | **器具管理** - 自定义器具配置                                                   |
| `method/`      | **冲煮方案** - 方案选择和自定义                                                 |
| `settings/`    | **设置页面** - 各类设置项组件                                                   |
| `common/`      | **通用组件** - 图片预览、弹窗、表单控件等                                       |
| `ui/`          | **基础 UI** - 按钮组、研磨度输入等基础控件                                      |
| `layout/`      | **布局组件** - 页面布局相关                                                     |
| `onboarding/`  | **引导流程** - 新用户引导                                                       |

### 📁 `src/lib/` - 核心逻辑

| 目录          | 说明                                                             |
| ------------- | ---------------------------------------------------------------- |
| `core/`       | **核心模块** - 数据库 (`db.ts`)、配置 (`config.ts`)、存储工具    |
| `stores/`     | **Zustand Store** - 状态管理，包括咖啡豆、冲煮笔记、器具、研磨器 |
| `types/`      | **类型定义** - 冲煮方法类型等                                    |
| `hooks/`      | **自定义 Hooks**                                                 |
| `utils/`      | **工具函数**                                                     |
| `app/`        | **App 相关** - Capacitor 能力、浏览器兼容、安全区域处理          |
| `sync/`       | **同步基础** - 同步管理器基类                                    |
| `webdav/`     | **WebDAV 同步** - WebDAV 客户端和同步逻辑                        |
| `s3/`         | **S3 同步** - S3 兼容存储同步                                    |
| `brewing/`    | **冲煮逻辑** - 冲煮相关业务逻辑                                  |
| `equipment/`  | **器具逻辑** - 器具相关业务逻辑                                  |
| `grinder/`    | **研磨器** - 研磨度相关逻辑                                      |
| `audio/`      | **音频** - 声音播放                                              |
| `navigation/` | **导航** - 路由和导航逻辑                                        |
| `managers/`   | **管理器** - 各类业务管理器                                      |
| `api/`        | **API** - 接口请求                                               |
| `ui/`         | **UI 工具** - UI 相关工具函数                                    |

### 📁 `src/providers/` - Context Providers

| 文件                       | 说明                                  |
| -------------------------- | ------------------------------------- |
| `StorageProvider.tsx`      | 存储初始化，处理 IndexedDB 和数据迁移 |
| `CapacitorProvider.tsx`    | Capacitor 能力初始化（原生功能）      |
| `ModalHistoryProvider.tsx` | 弹窗历史管理（支持返回键关闭弹窗）    |

---

## 数据层架构

### 数据库 (Dexie/IndexedDB)

位置：`src/lib/core/db.ts`

```
BrewGuideDB
├── brewingNotes    # 冲煮笔记
├── coffeeBeans     # 咖啡豆
├── customEquipments # 自定义器具
├── customMethods   # 自定义方案
└── settings        # 应用设置
```

### 状态管理 (Zustand)

位置：`src/lib/stores/`

| Store                 | 用途             |
| --------------------- | ---------------- |
| `coffeeBeanStore.ts`  | 咖啡豆列表和操作 |
| `brewingNoteStore.ts` | 冲煮笔记管理     |
| `equipmentStore.ts`   | 器具配置         |
| `grinderStore.ts`     | 研磨器设置       |

---

## 关键文件入口

| 文件                     | 说明                            |
| ------------------------ | ------------------------------- |
| `src/app/page.tsx`       | 应用主页面入口                  |
| `src/app/layout.tsx`     | 根布局，包含 Providers          |
| `src/lib/core/config.ts` | 全局配置和类型定义              |
| `src/lib/core/db.ts`     | 数据库定义和工具方法            |
| `capacitor.config.ts`    | Capacitor 配置（移动端/桌面端） |

---

## 开发流程

### 启动开发

```bash
pnpm install   # 安装依赖
pnpm dev       # 启动开发服务器 (localhost:3000)
```

### 构建

```bash
pnpm build           # Web 构建
pnpm cap:build       # 移动端构建并同步
pnpm build:desktop   # 桌面端构建（需要 Pake）
```

### 移动端调试

```bash
pnpm cap:ios      # 打开 Xcode
pnpm cap:android  # 打开 Android Studio
```

---

## 常见开发场景

### 添加新的设置项

1. 在 `src/components/settings/` 创建设置组件
2. 在 `Settings.tsx` 中引入
3. 如需持久化，使用 `src/lib/core/storage.ts`

### 添加新的咖啡豆字段

1. 修改 `src/types/app.d.ts` 中的 `CoffeeBean` 类型
2. 修改 `src/components/coffee-bean/Form/` 中的表单
3. 修改 `src/components/coffee-bean/Detail/` 中的详情展示

### 添加新的冲煮器具

1. 在 `src/lib/core/config.ts` 中添加器具配置
2. 添加对应图标资源

### 修改计时器逻辑

主要文件：

- `src/components/brewing/BrewingTimer.tsx` - 计时器主组件
- `src/components/brewing/Timer/` - 计时器子组件
- `src/components/brewing/stages/` - 阶段相关组件

---

## 同步功能架构

支持两种云同步方式：

| 方式   | 目录              | 说明                            |
| ------ | ----------------- | ------------------------------- |
| WebDAV | `src/lib/webdav/` | 支持 WebDAV 协议的网盘          |
| S3     | `src/lib/s3/`     | S3 兼容存储（AWS S3、MinIO 等） |

基类：`src/lib/sync/BaseSyncManager.ts`

---

## 资源文件

| 目录             | 说明                           |
| ---------------- | ------------------------------ |
| `public/images/` | 图片资源（图标、Logo、截图等） |
| `public/sounds/` | 音频资源（提示音）             |
| `public/data/`   | 数据文件（咖啡豆 CSV 数据库）  |
| `assets/`        | 其他资源                       |

---

## 多端支持

| 平台    | 技术      | 目录                         |
| ------- | --------- | ---------------------------- |
| Web/PWA | Next.js   | `src/`                       |
| iOS     | Capacitor | `ios/`                       |
| Android | Capacitor | `android/`                   |
| 桌面    | Pake      | 通过 `build-desktop.sh` 构建 |