# CLAUDE.md

此文件为 Claude Code (claude.ai/code) 提供本仓库代码开发的指导说明。

## 项目概览

**SnapWish** - 一款使用中文界面的 Flutter 照片管理应用。该应用允许用户将照片组织到分类中、添加标签并管理他们的照片收藏。

## 架构结构

该应用采用标准的 Flutter Material Design 架构：
- **主入口**: `lib/main.dart` - 包含根组件和导航设置
- **导航**: 底部导航栏包含 2 个标签页（照片、分类）
- **悬浮按钮**: 通用添加照片按钮
- **页面**: 位于 `lib/pages/` 目录

## 核心组件

### 主结构 (`lib/main.dart`)
- **SnapWishApp**: 根 MaterialApp 组件，包含主题配置
- **MainPage**: 管理底部导航的有状态组件
- **路由**: `/add-photo` 路由用于添加新照片

### 页面 (`lib/pages/`)  
- **PhotoPage** (`photo_page.dart`): 照片网格显示和照片详情查看器
- **CategoriesPage** (`categories_page.dart`): 文件夹/分类管理，包含创建/删除功能
- **AddPhotoPage** (`add_photo_page.dart`): 照片上传表单，包含分类选择和标签功能

## 开发命令

### 构建与运行
```bash
# 安装依赖
flutter pub get

# 运行开发服务器
flutter run

# 构建 APK
flutter build apk

# 构建 iOS 应用
flutter build ios

# 构建 Web 应用
flutter build web
```

### 测试与代码质量
```bash
# 运行所有测试
flutter test

# 运行特定测试文件
flutter test test/widget_test.dart

# 代码分析
flutter analyze

# 代码格式化
flutter format .
```

### 开发工作流
```bash
# 开发期间热重载
flutter run --hot

# 检查过时包
flutter pub outdated

# 升级包
flutter pub upgrade
```

## 代码模式

### 状态管理
- 使用 **StatefulWidget** 进行本地状态管理
- 使用 **setState** 进行 UI 更新
- 目前使用模拟数据（标有 TODO 注释）

### 导航
- **命名路由** 用于主要导航 (`/add-photo`)
- **Navigator.push** 用于照片详情查看
- **BottomNavigationBar** 用于主标签页切换

### UI 组件
- **Material 3** 设计系统 (`useMaterial3: true`)
- **中文界面**（标签为中文）
- **响应式网格布局** 用于照片显示
- **对话框式** 交互用于分类管理

### 数据结构模式
- **模拟数据** 目前以 Lists/Maps 实现
- **分类结构**: `{name: String, count: int, isDefault: bool}`
- **标签管理**: 字符串列表支持 # 前缀

## 关键 TODO 项目

代码库包含多个 TODO 注释，指示计划功能：
- 用真实照片数据替换模拟数据
- 实现从设备选择照片功能
- 添加照片保存功能
- 实现收藏/分享/删除功能
- 按分类筛选照片
- 集成真实文件夹/分类数据

## 当前限制

- 无实际照片存储/检索（仅模拟数据）
- 无相机集成
- 无持久化存储
- 无图像缓存或优化
- 仅基础错误处理

## 开发环境

- **Flutter**: 3.2.5+
- **Dart**: 3.2.5+
- **目标平台**: iOS、Android（支持 Web）
- **构建工具**: 标准 Flutter 工具链