# CLAUDE.md

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

## 项目概览

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

## 架构与结构

### 核心架构
- **Material 3 设计系统** 配合深色主题
- **三个主界面**: 照片流、分类管理、添加照片表单
- **底部导航栏** 包含2个标签页（照片、分类）
- **悬浮按钮** 用于通用照片添加
- **命名路由** `/add-photo` 用于导航

### 文件结构
```
lib/
├── main.dart                 # 根应用，包含主题和导航
├── pages/
│   ├── photo_page.dart      # 照片网格和详情查看器
│   ├── categories_page.dart # 分类CRUD操作
│   └── add_photo_page.dart  # 照片上传和元数据管理
└── ...
```

## 开发命令

### 基础命令
```bash
# 安装依赖
flutter pub get

# 运行开发
flutter run

# 构建命令
flutter build apk        # Android APK
flutter build ios        # iOS应用
flutter build web        # Web构建

# 代码质量
flutter analyze          # 静态分析
flutter test            # 运行所有测试
flutter format .        # 代码格式化
```

### 热重载与开发
```bash
flutter run --hot       # 带热重载的开发模式
flutter pub outdated    # 检查过时包
flutter pub upgrade     # 更新依赖
```

## 关键技术模式

### 状态管理
- **StatefulWidget** 用于本地状态管理
- **setState** 用于UI更新
- **AnimationController** 用于按压动画（照片卡片）
- **SingleTickerProviderStateMixin** 用于流畅动画

### UI模式
- **CustomScrollView + Slivers** 用于灵活滚动
- **ShaderMask** 用于文字渐变效果
- **BoxDecoration** 带阴影和渐变效果
- **GestureDetector** 用于高级触摸处理
- **AnimationController** 配合Tween动画

### 导航模式
- **BottomNavigationBar** 自定义样式
- **命名路由** (`/add-photo`) 便于维护
- **PageView** 用于照片详情浏览
- **基于对话框的交互** 用于CRUD操作

### 数据结构
- **分类**: `{'name': String, 'count': int, 'isDefault': bool}`
- **标签**: `List<String>` 支持#前缀
- **照片**: 目前为模拟数据，带TODO占位符

## 开发注意事项

### 已实现的关键功能
- 深色主题配合品牌色（#FF8A1F渐变）
- 响应式照片卡片，4:5宽高比
- 分类管理，带创建/删除验证
- 标签系统，支持#前缀
- 照片详情查看器，带PageView
- 自定义底部导航配合FAB集成

### TODO项目（可在代码中搜索）
- 用真实照片存储替换模拟数据
- 集成图片选择器用于设备照片
- 实现照片保存功能
- 添加收藏/分享/删除功能
- 实现基于分类的照片筛选
- 集成真实文件夹/分类数据

### 当前限制
- 无实际照片存储/检索
- 无相机集成
- 无持久化存储
- 无图像缓存/优化
- 仅基础错误处理

### 设计系统
- **背景色**: #0F1113
- **表面色**: #1A1D1F
- **主色**: #FF8A1F
- **次色**: #FFBE3D
- **文字**: #EDEDED
- **次要文字**: #9CA3AF

## 开发环境
- **Flutter**: 3.2.5+
- **Dart**: 3.2.5+
- **平台**: iOS、Android、Web
- **语言**: 中文界面，带详细中文代码注释
- **架构**: 标准Flutter工具链