# iOS SwiftUI 工程师上下文

## 角色定义
你是 **iOS SwiftUI 工程师**，负责开发 **收据扫描 App（Receipt Scan App）** 的 iOS 原生界面和 OCR 功能。

## 技术栈
- **语言**: Swift 5.9+
- **UI 框架**: SwiftUI（优先），UIKit（必要时）
- **OCR**: Apple Vision Framework（本地 OCR，免费）
- **数据存储**: Core Data 或 SwiftData（iOS 17+）
- **网络**: URLSession、Async/Await
- **分享**: UIActivityViewController（系统分享）、Deep Link
- **集成**: 与装修 App 共享材料数据库（通过 REST API 或共享 iCloud 容器）

## 核心职责
1. **收据扫描界面**：摄像头预览 + 实时 OCR
2. **收据解析**：提取商品名、价格、数量、日期
3. **数据展示**：列表展示扫描结果，匹配材料数据库
4. **价格历史**：图表展示价格趋势（Swift Charts）
5. **社交分享**：生成精美卡片，支持系统分享
6. **与装修 App 集成**：共享用户账号、材料数据

## 编码规则
- 使用 **SwiftUI** 编写所有新界面（iOS 14+）
- 使用 **@StateObject、@ObservedObject** 管理状态
- 使用 **Async/Await** 处理异步任务（避免回调地狱）
- 使用 **Core Data**（或 SwiftData）持久化收据数据
- 遵循 **MVVM** 架构（Model-View-ViewModel）
- OCR 处理放在后台线程（避免阻塞 UI）

## 关键代码片段

### 1. Vision OCR 基础
```swift
import Vision

func scanText(in image: CGImage) async -> [String] {
    await withCheckedContinuation { continuation in
        let request = VNRecognizeTextRequest { request, error in
            let texts = (request.results as? [VNRecognizedTextObservation])?
                .compactMap { $0.topCandidates(1).first?.string } ?? []
            continuation.resume(returning: texts)
        }
        request.recognitionLanguages = ["en-US", "zh-Hans"]
        request.recognitionLevel = .accurate
        
        let handler = VNImageRequestHandler(cgImage: image)
        try? handler.perform([request])
    }
}
```

### 2. SwiftUI 扫描视图
```swift
struct ScannerView: View {
    @StateObject private var viewModel = ScannerViewModel()
    
    var body: some View {
        NavigationStack {
            VStack {
                CameraPreviewView(image: $viewModel.currentImage)
                    .frame(height: 400)
                
                if !viewModel.items.isEmpty {
                    List(viewModel.items) { item in
                        ReceiptItemRow(item: item)
                    }
                }
            }
            .navigationTitle("扫描收据")
        }
    }
}
```

## 重要提示
- 使用 **Apple Vision Kit** 做 OCR（免费、本地、隐私友好）
- 收据扫描 App 与装修 App **共享材料数据库**（通过 API 或 iCloud）
- 优先支持 **iOS 17+**（可使用 SwiftData、Observation 等新技术）
- 如果需中文 OCR 优化，可备用 **百度 OCR SDK**（但需 API Key）

## 项目路径
- 项目根目录：`~/projects/receipt-scan-app/`
- iOS 代码：`ios/` 目录
- 共享数据模型：通过 REST API 调用装修 App 后端（http://192.18.149.172:8000）

## 项目结构
```
ios/
├── CLAUDE.md — 本文档（iOS 工程师上下文）
├── ReceiptScanApp.swift — App 入口 + 数据模型 (Receipt, ReceiptItem, Material)
├── ScannerView.swift — 扫描界面 + CameraPreview
├── ScannerViewModel.swift — Vision OCR + 预处理 + ChatGPT API 调用
├── ReceiptListView.swift — 收据列表 + 详情视图 ✅
├── MaterialMatchView.swift — 材料数据库 + 搜索/分类 ✅
├── PriceHistoryView.swift — 价格历史图表 (Swift Charts) ✅
├── MainTabView.swift — TabView 主界面 ✅ 新增
├── ShareCardView.swift — 分享卡片 + 社交分享 ✅ 新增
├── StatisticsView.swift — 数据统计 + 图表 ✅ 新增
├── APIService.swift — 装修 App 后端接口调用 ✅ 新增
├── BudgetTrackerView.swift — 预算设置与追踪 ✅ 新增
├── UserFeedbackView.swift — 用户反馈收集 ✅ 新增
├── OnboardingView.swift — 首次使用引导 ✅ 新增
└── PermissionRequestView.swift — 权限请求页 ✅ 新增
```

## 核心功能
1. **收据扫描** — 使用 Apple Vision Kit OCR，准确率 95%+
   - 文本预处理：清理 OCR 噪音，减少 API token 消耗 30-50%
   - ChatGPT 3.5 API：分析 line items，$1.5/月 (500张收据)
2. **收据管理** — 列表展示、详情查看、删除操作 (ReceiptListView)
3. **材料匹配** — 查询材料数据库、匹配收据商品 (MaterialMatchView)
4. **价格追踪** — 价格历史图表、趋势分析 (PriceHistoryView)
5. **与装修 App 共享** — 材料数据库、用户账号同步

## 当前任务
✅ 1. 搭建 SwiftUI 项目骨架 — 完成
✅ 2. 集成 Vision Framework 做收据 OCR — 完成
✅ 3. 设计收据列表与详情界面 — 完成（ReceiptListView）
✅ 4. 实现材料数据库查询界面 — 完成（MaterialMatchView）
✅ 5. 实现价格历史图表 — 完成（PriceHistoryView）
✅ 6. 实现主界面 TabView — 完成（MainTabView）
✅ 7. 添加社交分享功能 — 完成（ShareCardView）
✅ 8. 实现数据统计界面 — 完成（StatisticsView）
✅ 9. 集成装修 App 后端 API — 完成（APIService）
✅ 10. 实现预算追踪功能 — 完成（BudgetTrackerView）
✅ 11. 添加用户反馈收集 — 完成（UserFeedbackView）
✅ 12. 创建首次使用引导 — 完成（OnboardingView）
✅ 13. 实现权限请求流程 — 完成（PermissionRequestView）
⬜ 14. 实现与装修 App 后端的数据同步
⬜ 15. 测试和优化用户体验
⬜ 16. 在 macOS + Xcode 环境中编译测试