# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概览

**项目名称**：想拍 (InspoSnap)  
**项目描述**：Shoot What Inspires You - 拍摄灵感收集与管理应用  
**当前阶段**：MVP v1.1 开发中  
**技术栈**：Flutter + Riverpod + Hive  
**参考文档**：[snapwish_PRD_v1.1.md](snapwish_PRD_v1.1.md) - 已确认的产品需求文档

## 技术方案

### 核心技术选型
- **框架**：Flutter 3.2.5+ (Dart)
- **状态管理**：Riverpod (现代、类型安全)
- **数据库**：Hive (轻量级、高性能)
- **图片处理**：flutter_image_compress + image
- **瀑布流**：flutter_staggered_grid_view
- **国际化**：flutter_localizations
- **分享接收**：receive_sharing_intent
- **图片查看**：photo_view
- **UI组件**：Material Design + 自定义主题

### 架构设计
```
lib/
├── core/               # 核心功能
│   ├── constants/      # 常量定义
│   ├── errors/         # 错误处理
│   ├── utils/          # 工具类（图片压缩、文件操作）
│   └── theme/          # 主题配置
├── data/               # 数据层
│   ├── datasources/    # 数据源
│   │   ├── local/      # Hive数据库
│   │   └── share/      # 分享接收
│   ├── models/         # 数据模型
│   └── repositories/   # 数据仓库
├── domain/             # 业务逻辑层
│   ├── entities/       # 实体类
│   ├── repositories/   # 仓库接口
│   └── usecases/       # 用例
├── presentation/       # 表示层
│   ├── providers/      # Riverpod状态管理
│   ├── pages/          # 页面
│   ├── widgets/        # 组件
│   └── l10n/           # 国际化
└── main.dart          # 应用入口
```

## 开发命令

```bash
# 安装依赖
flutter pub get

# 运行应用
flutter run                    # 默认设备
flutter run -d android         # Android设备
flutter run -d ios            # iOS设备

# 代码分析
flutter analyze

# 运行测试
flutter test

# 构建发布
flutter build apk             # Android APK
flutter build ios            # iOS应用
flutter build web            # Web版本

# 清理缓存
flutter clean
```

## 技术规范

### 图片处理规范
- **缩略图**：长边500px，WebP格式，85%质量，保持原始比例
- **大GIF处理**：提取前几帧作为缩略图，避免内存溢出
- **存储路径**：按保存日期分类 `/yyyy/MM/dd/`
- **缓存策略**：30天/500MB自动清理

### 性能指标
- **冷启动时间**：< 2秒
- **图片加载空窗期**：< 200ms
- **搜索响应时间**：< 500ms
- **内存占用**：< 200MB（正常使用）
- **用户操作响应**：< 200ms

### UI/UX规范
- **响应式断点**：手机≤600dp(2列)，平板>600dp(3-4列)
- **图片间距**：8dp标准间距
- **动画时长**：页面转场300ms
- **加载体验**：骨架屏 + 进度提示

## 开发任务分解

### 📋 任务清单（模块化开发）

#### 🔧 Phase 1: 架构搭建（3-4天）
**任务1.1: 项目基础配置**
- [ ] 创建Flutter项目并配置基础依赖
- [ ] 配置国际化支持（简中/繁中/English）
- [ ] 设置主题系统（浅色/深色/跟随系统）
- [ ] 配置Material Design和自定义色彩方案

**任务1.2: 数据层架构** ✅
- [x] 配置Hive数据库和实体模型
- [x] 实现数据访问对象（DAO）模式
- [x] 创建基础Repository接口和实现
- [x] 设置数据迁移和版本管理

**验收状态**：
- ✅ Hive数据库配置完成，适配器生成成功
- ✅ 实体模型定义完整（图片、文件夹、标签）
- ✅ DAO模式实现正确（ImageDAO、FolderDAO、TagDAO）
- ✅ Repository接口设计合理，支持CRUD操作
- ✅ 数据迁移机制配置完成，支持版本管理
- ⚠️ 代码质量：26个`avoid_print`提示，无致命错误

**任务1.3: 核心工具类** ✅
- [x] 图片压缩工具类（长边500px + WebP）
- [x] 文件存储管理工具
- [x] UUID生成和路径管理
- [x] 错误处理和日志系统

**验收状态**：
- ✅ 图片压缩工具类：支持JPG/PNG/GIF/WebP/HEIC格式，长边500px，WebP格式，GIF帧提取防内存溢出
- ✅ 文件存储管理：日期分类存储（/yyyy/MM/dd/），完整的文件和目录操作
- ✅ UUID和路径管理：多种UUID生成，路径安全检查，链式路径构建器
- ✅ 日志系统：5级日志（debug/info/warning/error/fatal），替换所有print语句

**任务1.4: 基础UI组件** ✅
- [x] 创建可复用的按钮组件
- [x] 实现加载状态组件（骨架屏）
- [x] 空状态页面组件
- [x] 错误提示组件

**验收状态**：
- ✅ 可复用按钮组件：支持主要、次要、文本、轮廓、危险按钮类型，多种尺寸，加载状态，图标支持
- ✅ 加载状态组件：骨架屏动画、圆形加载器、进度条、全屏加载、列表/网格骨架屏
- ✅ 空状态页面组件：多种预设场景（无数据、无搜索结果、网络错误等），自定义图标和操作
- ✅ 错误提示组件：多种错误类型（网络、服务器、权限、数据等），详细错误信息显示

#### 📤 Phase 2: 分享功能（2-3天）
**任务2.1: 分享接收机制** ✅
- [x] 配置receive_sharing_intent插件
- [x] 实现Android分享接收配置
- [x] 实现iOS分享接收配置（已添加TODO注释，跳过iOS设备）
- [x] 处理多张图片接收逻辑（支持批量处理和队列管理）

**任务2.2: 保存界面UI**
- [ ] 创建半透明模态框界面
- [ ] 实现图片网格预览组件
- [ ] 构建文件夹选择器弹窗
- [ ] 实现标签输入和选择组件

**任务2.3: 保存业务逻辑**
- [ ] 实现批量保存模式（默认）
- [ ] 实现单张编辑模式切换
- [ ] 处理保存进度提示
- [ ] 异步保存和缩略图生成

**任务2.4: 文件夹管理**
- [ ] 创建文件夹弹窗界面
- [ ] 实现Material Icons选择器
- [ ] 文件夹排序（最近使用）
- [ ] 文件夹CRUD操作

#### 🖼️ Phase 3: 图库展示（2-3天）
**任务3.1: 主图库界面**
- [ ] 实现瀑布流布局（flutter_staggered_grid_view）
- [ ] 响应式列数切换（手机2列/平板3-4列）
- [ ] 图片懒加载和缓存优化
- [ ] 下拉刷新和上拉加载更多

**任务3.2: 搜索功能**
- [ ] 实现常驻搜索框
- [ ] 模糊搜索算法（文件夹+标签+备注）
- [ ] 搜索历史记录（最近10条）
- [ ] 空搜索结果页面

**任务3.3: 状态管理**
- [ ] 图库状态管理（Riverpod）
- [ ] 图片加载状态管理
- [ ] 搜索状态管理
- [ ] 分页数据管理

#### 📁 Phase 4: 管理功能（3-4天）
**任务4.1: 图片详情页**
- [ ] 图片查看器（photo_view）
- [ ] 左右滑动切换（非循环）
- [ ] 双击放大/缩小功能
- [ ] 横竖屏适配

**任务4.2: 详情信息展示**
- [ ] 显示文件夹、标签、备注信息
- [ ] 编辑功能入口
- [ ] 删除功能（二次确认）
- [ ] 导出到系统相册

**任务4.3: 标签管理系统**
- [ ] 标签列表页面
- [ ] 标签编辑功能
- [ ] Material Icons选择
- [ ] 标签使用统计

**任务4.4: 文件夹页面**
- [ ] 文件夹网格展示
- [ ] 文件夹封面设置
- [ ] 文件夹重命名功能
- [ ] 文件夹删除处理

#### ⚙️ Phase 5: 搜索设置（2-3天）
**任务5.1: 设置页面**
- [ ] 设置页面分组布局
- [ ] 语言切换功能
- [ ] 主题模式切换
- [ ] 网格布局切换

**任务5.2: 存储管理**
- [ ] 存储使用情况显示
- [ ] 一键清理缓存功能
- [ ] 缩略图管理
- [ ] 存储路径管理

**任务5.3: 性能优化**
- [ ] 虚拟滚动实现
- [ ] 内存管理优化
- [ ] 大图片处理优化
- [ ] 启动速度优化

**任务5.4: 最终调试**
- [ ] 完整功能测试
- [ ] 性能测试和调优
- [ ] 多设备兼容性测试
- [ ] Bug修复和完善

## 数据模型定义

### 核心实体类
```dart
// 图片实体
class InspirationImage {
  final String id;              // UUID
  final String filePath;        // 原图路径
  final String thumbnailPath;   // 缩略图路径
  final String? folderId;       // 文件夹ID
  final List<String> tags;      // 标签ID列表
  final String? note;           // 备注内容
  final DateTime createdAt;     // 创建时间（保存时间）
  final DateTime updatedAt;     // 更新时间
  final String? originalName;   // 原始文件名
  final int fileSize;           // 文件大小
  final String mimeType;        // MIME类型
  final int? width;             // 图片宽度
  final int? height;            // 图片高度
  final bool isFavorite;        // 是否收藏
}

// 文件夹实体
class ImageFolder {
  final String id;              // UUID
  final String name;            // 文件夹名称
  final String? coverImageId;   // 封面图片ID
  final String icon;            // Material Icons名称
  final DateTime createdAt;     // 创建时间
  final DateTime updatedAt;     // 更新时间
  final DateTime lastUsedAt;    // 最近使用时间
}

// 标签实体
class ImageTag {
  final String id;              // UUID
  final String name;            // 标签名称
  final String icon;            // Material Icons名称
  final String color;           // 十六进制颜色
  final int usageCount;         // 使用次数
  final DateTime lastUsedAt;    // 最近使用时间
}
```

## 开发注意事项

### 代码规范
- 遵循Dart官方代码风格指南
- 使用有意义的变量和函数命名
- 添加必要的代码注释
- 保持widget的纯净性，业务逻辑分离到provider

### 性能要求
- 冷启动时间 < 2秒
- 图片加载流畅，无卡顿
- 用户操作响应 < 200ms
- 内存占用 < 200MB

### 错误处理
- 分享失败："出了点小问题，请重新分享试试~"
- 保存失败：同上
- 存储空间不足：同上
- 所有错误都需要友好提示

### 兼容性要求
- Android 7.0+ (API 24+)
- iOS 12.0+
- 适配各种屏幕尺寸和分辨率

## 当前开发任务

### 🎯 当前阶段：Phase 1.2 - 数据层架构搭建
**预计时间：1天**
**优先级：高**

**具体任务**：
- [ ] 配置Hive数据库和实体模型
- [ ] 实现数据访问对象（DAO）模式
- [ ] 创建基础Repository接口和实现
- [ ] 设置数据迁移和版本管理

**已完成任务**：Phase 1.1 - 项目基础配置
**下一个任务**：Phase 1.3 - 核心工具类

**开发顺序**：严格按照任务编号顺序执行，每个任务完成后再进行下一个任务。

**代码提交**：每个任务完成后提交一次，确保版本控制清晰。

## 代码规范要求

### 注释规范（强制要求）
**所有代码文件必须包含中文注释**，具体要求：
- **实体类**：每个字段必须有中文注释，说明字段用途和业务含义
- **方法**：每个公共方法必须有中文注释，说明方法功能、参数含义、返回值
- **类**：每个类必须有中文注释，说明类的职责和设计目的
- **复杂逻辑**：算法或业务逻辑复杂的地方必须有详细中文注释
- **常量**：所有常量必须有中文注释，说明常量用途
- **数据库相关**：所有数据库模型、DAO、Repository必须有详细中文注释

**注释模板示例**：
```dart
/// 用户服务类 - 负责用户相关的业务逻辑处理
/// 提供用户注册、登录、信息修改等功能
class UserService {
  /// 用户唯一标识符 - UUID格式，全局唯一
  final String id;
  
  /// 用户昵称 - 显示名称，支持2-20个字符
  final String nickname;
  
  /// 构造函数 - 创建用户实例
  /// [id] 用户唯一标识符，不能为空
  /// [nickname] 用户昵称，不能为空
  UserService({required this.id, required this.nickname});
  
  /// 更新用户昵称 - 修改用户显示名称
  /// 返回更新后的用户实例，保持不可变性
  UserService updateNickname(String newNickname) {
    return UserService(id: id, nickname: newNickname);
  }
}
```

---

**最后更新**：2025年9月12日  
**开发状态**：Phase 1.2 进行中  
**下一阶段**：数据层架构搭建...  

**记住：功能优先，保持代码整洁，及时沟通！** 🚀

**重要提醒：所有代码必须包含中文注释，遵循注释规范！** 📋

## 开发进度跟踪

### 📊 总体进度
- [x] Phase 1.1: 项目基础配置（5/5）✅
- [x] Phase 1.2: 数据层架构搭建（4/4）✅
- [x] Phase 1.3: 核心工具类（4/4）✅
- [x] Phase 1.4: 基础UI组件（4/4）✅
- [x] Phase 2.1: 分享接收机制（4/4）✅
- [ ] Phase 2.2: 保存界面UI（0/4）

### 🎯 当前任务详情
**任务编号**：2.2
**任务名称**：保存界面UI
**任务状态**：待开始
**预计完成**：2025年9月19日
**依赖项**：Phase 2.1 完成

**任务验收标准**：
- 半透明模态框界面创建完成
- 图片网格预览组件实现
- 文件夹选择器弹窗完成
- 标签输入和选择组件实现