396 lines
13 KiB
Markdown
396 lines
13 KiB
Markdown
# 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 完成
|
||
|
||
**任务验收标准**：
|
||
- 半透明模态框界面创建完成
|
||
- 图片网格预览组件实现
|
||
- 文件夹选择器弹窗完成
|
||
- 标签输入和选择组件实现 |