2025-09-17 09:49:37 +08:00

12 KiB

Raw Blame History

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 - 已确认的产品需求文档

技术方案

核心技术选型

框架：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          # 应用入口

开发命令

# 安装依赖
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: 数据层架构 ✅

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

验收状态：

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

任务1.3: 核心工具类

图片压缩工具类（长边500px + WebP）
文件存储管理工具
UUID生成和路径管理
错误处理和日志系统

任务1.4: 基础UI组件

创建可复用的按钮组件
实现加载状态组件（骨架屏）
空状态页面组件
错误提示组件

📤 Phase 2: 分享功能（2-3天）

任务2.1: 分享接收机制

配置receive_sharing_intent插件
实现Android分享接收配置
实现iOS分享接收配置
处理多张图片接收逻辑

任务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修复和完善

数据模型定义

核心实体类

// 图片实体
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必须有详细中文注释

注释模板示例：

/// 用户服务类 - 负责用户相关的业务逻辑处理
/// 提供用户注册、登录、信息修改等功能
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 进行中
下一阶段：数据层架构搭建...

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

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

开发进度跟踪

📊 总体进度

Phase 1.1: 项目基础配置（5/5）✅
Phase 1.2: 数据层架构搭建（4/4）✅
Phase 1.3: 核心工具类（0/4）
Phase 1.4: 基础UI组件（0/4）
Phase 2: 分享功能（0/4）

🎯 当前任务详情

任务编号：1.3 任务名称：核心工具类 任务状态：待开始 预计完成：2025年9月17日 依赖项：Phase 1.2 完成

任务验收标准：

图片压缩工具类实现（长边500px + WebP格式）
文件存储管理工具（支持日期分类存储）
UUID生成和路径管理工具
错误处理和日志系统完善
代码质量检查通过（解决print警告）

12 KiB Raw Blame History Unescape Escape