# 🔗 双 App 集成指南

本文档说明 **收据扫描 App** 与 **家居装修 App** 的深度集成方案。

---

## 🎯 集成目标

### 1. 共享材料数据库
- 两个 App 访问**同一套材料数据库**（33+ 种材料）
- 支持 **中美双市场**（CN/US）
- 材料信息：名称、品牌、型号、价格、购买链接

### 2. 收据扫描 → 材料匹配
- 扫描收据后，**自动匹配**装修材料数据库
- 识别商品是否为装修材料（地板、油漆、灯具等）
- 显示参考价格，帮助用户判断是否买贵

### 3. 预算对比
- 装修 App 生成预算 **$15,780**
- 收据 App 记录实际花费 **$12,350**
- 实时显示 **节省 $3,430**（或超支）

### 4. 用户账号同步（未来）
- 统一用户账号系统（JWT）
- 装修方案、收据记录云端同步
- 跨设备访问

---

## 🏗️ 架构设计

```
┌─────────────────────────────────────────────────────┐
│                  用户（David Yin）                    │
└────────────┬────────────────────┬──────────────────┘
             │                    │
             ▼                    ▼
┌─────────────────┐    ┌──────────────────┐
│  收据扫描 App   │    │  家居装修 App    │
│  (iOS SwiftUI) │    │ (Flutter/Web)   │
└────────┬────────┘    └────────┬─────────┘
         │                      │
         │  REST API           │
         └──────────┬───────────┘
                    ▼
         ┌──────────────────────┐
         │   后端 API 服务        │
         │  (FastAPI, Port 8000) │
         └──────────┬───────────┘
                    │
         ┌──────────▼───────────┐
         │   材料数据库 (JSON)     │
         │  materials_cn.json    │
         │  materials_us.json    │
         └──────────────────────┘
```

---

## 📡 API 接口定义

### 1. 查询材料数据库

**端点**：`GET /api/v1/materials`

**收据 App 调用示例**
```swift
func queryMaterials(name: String? = nil, category: String? = nil, market: String = "CN") async throws -> [Material] {
    var urlComponents = URLComponents(string: "\(baseURL)/api/v1/materials")!
    var queryItems: [URLQueryItem] = []
    
    if let name = name {
        queryItems.append(URLQueryItem(name: "search", value: name))
    }
    if let category = category {
        queryItems.append(URLQueryItem(name: "category", value: category))
    }
    queryItems.append(URLQueryItem(name: "market", value: market))
    urlComponents.queryItems = queryItems
    
    let (data, _) = try await URLSession.shared.data(from: urlComponents.url!)
    return try JSONDecoder().decode([Material].self, from: data)
}

// 使用示例
let materials = try await queryMaterials(name: "地板", market: "CN")
print("✅ 找到 \(materials.count) 种地板材料")
```

---

### 2. 匹配收据商品到材料

**端点**：`POST /api/v1/materials/query`

**请求体**
```json
{
  "item_name": "圣象地板",
  "price": 4.99
}
```

**收据 App 调用示例**
```swift
func matchReceiptItem(name: String, price: Double) async throws -> Material? {
    let url = URL(string: "\(baseURL)/api/v1/materials/query")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    
    let body: [String: Any] = [
        "item_name": name,
        "price": price
    ]
    request.httpBody = try JSONSerialization.data(withJSONObject: body)
    
    let (data, _) = try await URLSession.shared.data(for: request)
    let materials = try JSONDecoder().decode([Material].self, from: data)
    return materials.first
}

// 使用示例
if let matched = try await matchReceiptItem(name: "圣象地板", price: 4.99) {
    print("✅ 匹配到材料：\(matched.name ?? "")")
    print("   品牌：\(matched.brand ?? "")")
    print("   参考价：\(\matched.estimatedPrice)")
}
```

---

### 3. 上传收据到后端（可选）

**端点**：`POST /api/v1/receipts`

**请求体**
```json
{
  "merchant": "Home Depot",
  "total": 123.45,
  "items": [
    {"name": "Pergo Laminate Flooring", "price": 2.59, "quantity": 10},
    {"name": "Behr Premium Plus Paint", "price": 38.98, "quantity": 2}
  ]
}
```

---

## 🔄 完整工作流程

### 场景：用户装修客厅，扫描购买收据

```
1. 【装修 App】生成客厅现代简约方案
   ↓
   输出：3套方案，每套包含 8-10 种材料，总预算 $15,780
   ↓
   材料清单保存到后端数据库

2. 【收据 App】用户去 Home Depot 购买材料
   ↓
   扫描收据（Vision OCR + 预处理）
   ↓
   ChatGPT 3.5 分析 line items
   ↓
   得到：Pergo 地板 $2.59×10, Behr 油漆 $38.98×2, ...

3. 【收据 App】匹配材料数据库
   ↓
   调用 POST /api/v1/materials/query
   ↓
   匹配结果：
   - Pergo 地板 → 材料数据库 ID: floor-001
   - Behr 油漆 → 材料数据库 ID: wall-003
   ↓
   显示参考价格对比：
   - 你买的价格：$2.59/sq ft
   - 参考价格：$2.45/sq ft
   - 结论：买贵了 5.7% ⚠️

4. 【收据 App】更新预算追踪
   ↓
   实际花费：地板 $259 + 油漆 $77.96 = $336.96
   ↓
   对比装修 App 预算：地板 $245 + 油漆 $60 = $305
   ↓
   超支 $31.96（建议下次选择更便宜的品牌）

5. 【用户】查看统计报表
   ↓
   装修 App：方案预算 $15,780
   收据 App：实际花费 $12,350
   ↓
   节省 $3,430（21.7%）✅
```

---

## 💻 代码实现

### 收据 App 中的 APIService.swift

```swift
class APIService {
    static let shared = APIService()
    private let baseURL = "http://192.18.149.172:8000"
    
    // 1. 查询材料
    func queryMaterials(name: String? = nil, category: String? = nil, market: String = "CN") async throws -> [Material] {
        // 实现见上文
    }
    
    // 2. 匹配收据商品
    func matchReceiptItem(name: String, price: Double) async throws -> Material? {
        // 实现见上文
    }
    
    // 3. 上传收据（可选）
    func uploadReceipt(_ receipt: Receipt) async throws -> Bool {
        // 实现见上文
    }
}
```

---

## 📊 数据库共享方案

### 方案 A：REST API（当前实现）✅
- 收据 App 通过 HTTP 调用装修 App 后端
- **优点**：解耦、跨平台、易维护
- **缺点**：需要网络连接

**适用场景**：日常使用，有网络环境

---

### 方案 B：iCloud 容器共享（未来）⚠️ 仅 iOS
- 两个 App 共享同一个 iCloud Container
- **优点**：无需后端、离线可用
- **缺点**：仅限 Apple 生态

**适用场景**：纯 iOS 生态，注重隐私

---

### 方案 C：PostgreSQL + 用户账号（未来）
- 统一后端数据库，JWT 认证
- **优点**：跨平台、云端同步、数据安全
- **缺点**：需要用户注册、服务器成本

**适用场景**：多设备用户、团队协作

---

## 🎯 集成优势

| 优势 | 说明 |
|------|------|
| **数据一致性** | 材料信息统一来源，避免重复维护 |
| **智能匹配** | 扫描收据自动识别装修材料 |
| **预算控制** | 实时对比预算与实际花费 |
| **省钱建议** | 根据历史价格推荐最优购买时机 |
| **生态闭环** | 从设计到购买到记录，一站式管理 |

---

## 🚀 下一步集成任务

- [ ] 装修 App 后端添加 `POST /api/v1/materials/query` 接口
- [ ] 收据 App 实现 `APIService.matchReceiptItem()`
- [ ] 添加 JWT 认证（保护 API）
- [ ] 实现用户账号系统（注册、登录）
- [ ] iCloud 数据同步（仅 iOS）
- [ ] 统一数据库（PostgreSQL）

---

## 📞 联系方式

**David Yin** - [GitHub](https://github.com/davidyin)

---
🏠 **家居装修 App**: https://github.com/davidyin/home-renovation-app  
📱 **收据扫描 App**: https://github.com/davidyin/receipt-scan-app