snap_wish/CLAUDE.md

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  # 照片上传和元数据管理
└── ...

开发命令

基础命令

# 安装依赖
flutter pub get

# 运行开发
flutter run

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

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

热重载与开发

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工具链

特殊说明

• 代码中使用中文注释，且简介、有效的说明逻辑，并支持flutter复杂、重点的运用和开发技巧，方便后续复盘和学习