# haven

**Repository Path**: HiHi_Peter/haven

## Basic Information

- **Project Name**: haven
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Haven - 购物决策助手

## 📱 项目概述

Haven 是一款智能购物决策助手应用，帮助用户做出更明智的购物决策。用户可以通过上传心仪单品的图片，AI 分析该单品与衣橱中现有衣物的搭配可能性，避免购买"只能单穿"的闲置款。应用支持愿望清单功能，可以标记想买的单品，后续结合衣橱推荐搭配方案，判断是否值得入手。

## 🎨 设计规范

### 主题颜色

- **主色调渐变**：`#FD0BAA` → `#FFA2DF`
- **使用场景**：
  - 导航栏背景
  - 按钮背景
  - 强调元素
  - 品牌标识

### 命名规范

#### 文件夹命名规范

采用 **PascalCase** 命名方式，按功能模块组织：

```
Haven/
├── AppDelegate.swift
├── SceneDelegate.swift
├── Info.plist
├── Resources/              # 资源文件
│   ├── Assets.xcassets/
│   ├── Localizable.strings
│   └── Fonts/
├── Core/                   # 核心功能
│   ├── Models/            # 数据模型
│   ├── Services/          # 业务服务
│   ├── Network/           # 网络层
│   └── Storage/           # 数据持久化
├── Features/              # 功能模块
│   ├── Home/              # 首页模块
│   │   ├── ViewControllers/
│   │   ├── Views/
│   │   ├── ViewModels/
│   │   └── Models/
│   ├── Wardrobe/          # 衣橱模块
│   │   ├── ViewControllers/
│   │   ├── Views/
│   │   ├── ViewModels/
│   │   └── Models/
│   ├── Wishlist/          # 愿望清单模块
│   │   ├── ViewControllers/
│   │   ├── Views/
│   │   ├── ViewModels/
│   │   └── Models/
│   └── Analysis/          # AI分析模块
│       ├── ViewControllers/
│       ├── Views/
│       ├── ViewModels/
│       └── Models/
├── Shared/                # 共享组件
│   ├── Components/        # 可复用UI组件
│   ├── Extensions/        # 扩展
│   ├── Utils/             # 工具类
│   └── Constants/         # 常量定义
└── Resources/
```

#### 文件命名规范

- **ViewController**: `[功能名]ViewController.swift`
  - 示例：`HomeViewController.swift`, `WishlistViewController.swift`
  
- **View**: `[功能名]View.swift` 或 `[组件名]View.swift`
  - 示例：`WardrobeItemCardView.swift`, `WishlistCardView.swift`
  
- **ViewModel**: `[功能名]ViewModel.swift`
  - 示例：`HomeViewModel.swift`, `WishlistViewModel.swift`
  
- **Model**: `[实体名].swift`
  - 示例：`WardrobeItem.swift`, `WishlistItem.swift`, `Outfit.swift`
  
- **Service**: `[功能名]Service.swift`
  - 示例：`AIAnalysisService.swift`, `WardrobeService.swift`
  
- **Extension**: `[类型名]+[功能].swift`
  - 示例：`UIColor+Theme.swift`, `UIView+Extensions.swift`

#### 类/结构体命名规范

- **类名**: PascalCase
  - 示例：`WardrobeItemCardView`, `WishlistViewController`
  
- **变量/函数名**: camelCase
  - 示例：`wardrobeItems`, `loadWishlistItems()`
  
- **常量**: SCREAMING_SNAKE_CASE
  - 示例：`MAX_RETRY_ATTEMPTS`, `API_BASE_URL`

## 🏗️ 布局方案

### 1. 首页 - 卡片式瀑布流布局

**设计理念**：类似 Pinterest 的瀑布流布局，展示衣橱单品和搭配方案

**特点**：
- 多列网格布局（2-3列，根据屏幕尺寸自适应）
- 卡片高度根据内容自适应
- 支持下拉刷新和上拉加载更多
- 卡片包含：图片、标题、标签、操作按钮

**适用页面**：
- 首页
- 衣橱浏览页

**实现要点**：
- 使用 `UICollectionView` + 自定义 `UICollectionViewFlowLayout`
- 卡片组件：`WardrobeItemCardView`（可复用）
- 支持图片懒加载和缓存

### 2. 愿望清单 - 看板式布局

**设计理念**：类似 Trello 的看板布局，分列展示不同状态

**特点**：
- 水平滚动，分列展示状态：
  - **想买** (Want to Buy)
  - **分析中** (Analyzing)
  - **已购买** (Purchased)
  - **已放弃** (Abandoned)
- 每列可垂直滚动
- 支持卡片拖拽移动（改变状态）
- 卡片支持左右滑动操作（收藏、删除）

**适用页面**：
- 愿望清单管理页

**实现要点**：
- 使用 `UICollectionView` + 水平滚动
- 每列独立的 `UICollectionView` 或使用嵌套布局
- 卡片组件：`WishlistCardView`（可复用）
- 拖拽功能：`UICollectionViewDragDelegate` / `UICollectionViewDropDelegate`

## 🔧 组件复用规范

### 可复用组件清单

#### 1. 卡片组件

**`WardrobeItemCardView`** - 衣橱单品卡片
- 用途：首页瀑布流、衣橱列表
- 属性：图片、标题、标签、操作按钮
- 位置：`Shared/Components/WardrobeItemCardView.swift`

**`WishlistCardView`** - 愿望清单卡片
- 用途：愿望清单看板
- 属性：图片、商品信息、价格、状态标签、操作按钮
- 位置：`Shared/Components/WishlistCardView.swift`

**`OutfitCardView`** - 搭配方案卡片
- 用途：搭配推荐展示
- 属性：主单品 + 搭配单品组合图、匹配度、操作按钮
- 位置：`Shared/Components/OutfitCardView.swift`

#### 2. 通用UI组件

**`GradientButton`** - 渐变按钮
- 用途：所有需要主题色按钮的地方
- 属性：标题、渐变颜色（主题色）、点击回调
- 位置：`Shared/Components/GradientButton.swift`

**`LoadingView`** - 加载视图
- 用途：数据加载状态展示
- 位置：`Shared/Components/LoadingView.swift`

**`EmptyStateView`** - 空状态视图
- 用途：列表为空时的提示
- 属性：图标、标题、描述、操作按钮
- 位置：`Shared/Components/EmptyStateView.swift`

**`ImagePickerView`** - 图片选择器
- 用途：上传单品图片
- 位置：`Shared/Components/ImagePickerView.swift`

#### 3. 布局组件

**`WaterfallLayout`** - 瀑布流布局
- 用途：首页、衣橱浏览页
- 位置：`Shared/Components/WaterfallLayout.swift`

**`BoardLayout`** - 看板布局
- 用途：愿望清单看板
- 位置：`Shared/Components/BoardLayout.swift`

### 组件使用原则

1. **单一职责**：每个组件只负责一个功能
2. **可配置性**：通过属性或闭包配置组件行为
3. **可复用性**：避免在组件内部硬编码业务逻辑
4. **一致性**：相同功能的组件在不同页面保持一致的样式和行为

## 📐 架构设计

### MVVM 架构模式

```
View (ViewController/View)
    ↓ 绑定
ViewModel
    ↓ 调用
Service/Repository
    ↓ 操作
Model/Storage
```

### 目录结构示例

```
Features/Home/
├── ViewControllers/
│   └── HomeViewController.swift
├── Views/
│   ├── HomeHeaderView.swift
│   └── HomeWaterfallView.swift
├── ViewModels/
│   └── HomeViewModel.swift
└── Models/
    └── HomeItem.swift

Shared/Components/
├── WardrobeItemCardView.swift
├── WishlistCardView.swift
├── OutfitCardView.swift
├── GradientButton.swift
├── LoadingView.swift
├── EmptyStateView.swift
└── ImagePickerView.swift

Shared/Extensions/
├── UIColor+Theme.swift      # 主题颜色扩展
├── UIView+Extensions.swift  # UIView扩展
└── UIImage+Extensions.swift # UIImage扩展
```

## 🎯 开发指南

### 1. 创建新功能模块

1. 在 `Features/` 下创建新文件夹（PascalCase）
2. 按 MVC/MVVM 结构创建子文件夹
3. 遵循命名规范创建文件
4. 复用 `Shared/Components/` 中的组件

### 2. 添加可复用组件

1. 在 `Shared/Components/` 下创建组件文件
2. 确保组件独立、可配置
3. 添加必要的文档注释
4. 在组件文件中添加使用示例（注释形式）

### 3. 使用主题颜色

```swift
// 在 UIColor+Theme.swift 中定义
extension UIColor {
    static var themePrimary: UIColor {
        return UIColor(hex: "#FD0BAA")
    }
    
    static var themeSecondary: UIColor {
        return UIColor(hex: "#FFA2DF")
    }
    
    static var themeGradient: [UIColor] {
        return [themePrimary, themeSecondary]
    }
}

// 使用示例
let gradientLayer = CAGradientLayer()
gradientLayer.colors = UIColor.themeGradient.map { $0.cgColor }
```

### 4. 代码规范

- **类型声明**：所有变量、函数必须声明类型
- **禁止使用**：`dynamic`、`Any` 类型
- **函数紧凑**：函数内部不使用空行
- **命名规范**：严格遵循上述命名规范
- **注释语言**：代码注释使用英文
- **UI文本**：应用内UI文本使用英文（除特殊说明外）

### 5. 注意事项

⚠️ **重要原则**：
- ✅ 复用现有组件，不要重复创建
- ✅ 保持应用风格一致
- ✅ 遵循命名规范
- ❌ 不要修改无关代码
- ❌ 不要重复创建功能
- ❌ 不要重复创建文件

## 📦 依赖管理

当前使用 CocoaPods 管理依赖。如需添加新依赖：

1. 在 `Podfile` 中添加依赖
2. 运行 `pod install`
3. 使用 `.xcworkspace` 文件打开项目

## 🚀 开发流程

1. **需求分析**：明确功能需求
2. **设计确认**：确认UI/UX设计
3. **架构规划**：确定模块结构和组件复用
4. **编码实现**：遵循命名规范和代码规范
5. **代码审查**：检查是否符合规范
6. **测试验证**：功能测试和UI测试

## 📝 待实现功能清单

- [ ] 首页瀑布流布局实现
- [ ] 愿望清单看板布局实现
- [ ] 图片上传功能
- [ ] AI分析服务集成
- [ ] 衣橱管理功能
- [ ] 搭配推荐功能
- [ ] 数据持久化
- [ ] 用户引导流程

## 📄 许可证

Copyright © 2025 Haven. All rights reserved.