# 商品详情页 API 替换指南

## 概述

本文档说明如何将商品详情页的模拟数据替换为真实的后端API接口。商品详情页包含商品图片、商品信息、商品特点等模块，所有数据都来自酒谷商品主数据表。

## 核心API接口

### 1. 获取商品详情

**当前模拟接口：**
```javascript
// api/product.js
export const getProductDetail = async (productId) => {
    // 模拟实现
}
```

**需要替换为真实接口：**
```javascript
// 真实API调用示例
export const getProductDetail = async (productId) => {
    try {
        const response = await uni.request({
            url: `${API_BASE_URL}/api/products/${productId}`,
            method: 'GET',
            header: {
                'Authorization': `Bearer ${getToken()}`,
                'Content-Type': 'application/json'
            }
        })
        
        if (response.statusCode === 200) {
            return {
                success: true,
                message: '商品详情获取成功',
                data: response.data.data
            }
        } else {
            throw new Error(response.data.message || '商品详情获取失败')
        }
    } catch (error) {
        console.error('获取商品详情失败:', error)
        return {
            success: false,
            message: error.message || '商品详情获取失败',
            data: null
        }
    }
}
```

**接口地址：** `GET /api/products/{productId}`

**返回数据结构：**
```json
{
    "success": true,
    "message": "商品详情获取成功",
    "data": {
        "id": "product_jg_001",
        "name": "酒谷陈酿",
        "price": 888.00,
        "points": 400,
        "mainImage": "https://...",
        "packageImage": "https://...",
        "qualityImage": "https://...",
        "qualityDescription": "采用高温制曲、二次投料...",
        
        // 商品特点字段 - 从酒谷商品主数据表获取
        "material": "水、高粱、小麦",
        "alcohol": "53%vol.",
        "origin": "贵州省仁怀市茅台镇",
        "type": "酱香型白酒",
        "capacity": "500ml",
        "storage": "干燥、通风、阴凉的环境条件下存储",
        "company": "贵州茅台酒股份有限公司"
    }
}
```

### 2. 获取商品图片

**当前模拟接口：**
```javascript
// api/product.js
export const getProductImages = async (productId, imageType = 2) => {
    // 模拟实现
}
```

**需要替换为真实接口：**
```javascript
// 真实API调用示例
export const getProductImages = async (productId, imageType = 2) => {
    try {
        const response = await uni.request({
            url: `${API_BASE_URL}/api/products/${productId}/images`,
            method: 'GET',
            data: {
                imageType: imageType, // 图片分类==2 (商品详情图片)
                limit: 6 // 限制最多6张图片
            },
            header: {
                'Authorization': `Bearer ${getToken()}`,
                'Content-Type': 'application/json'
            }
        })
        
        if (response.statusCode === 200) {
            return {
                success: true,
                message: '商品图片获取成功',
                data: {
                    images: response.data.data.images,
                    total: response.data.data.total
                }
            }
        } else {
            throw new Error(response.data.message || '商品图片获取失败')
        }
    } catch (error) {
        console.error('获取商品图片失败:', error)
        return {
            success: false,
            message: error.message || '商品图片获取失败',
            data: {
                images: [],
                total: 0
            }
        }
    }
}
```

**接口地址：** `GET /api/products/{productId}/images?imageType=2&limit=6`

**返回数据结构：**
```json
{
    "success": true,
    "message": "商品图片获取成功",
    "data": {
        "images": [
            {
                "id": "img_001",
                "url": "https://...",
                "type": 2,
                "sort": 1,
                "description": "商品主图"
            }
        ],
        "total": 6
    }
}
```

## 数据来源说明

### 商品主数据表字段映射

| 前端字段 | 数据库字段 | 说明 | 示例值 |
|---------|-----------|------|--------|
| `name` | `product_name` | 商品名称 | 茅台飞天 53° 500ml |
| `price` | `product_price` | 商品价格 | 888.00 |
| `material` | `raw_material` | 原料 | 水、高粱、小麦 |
| `alcohol` | `alcohol_content` | 酒精度数 | 53%vol. |
| `origin` | `production_place` | 厂址 | 贵州省仁怀市茅台镇 |
| `type` | `wine_type` | 酒品类型 | 酱香型白酒 |
| `capacity` | `net_content` | 容量 | 500ml |
| `storage` | `storage_advice` | 储存条件 | 干燥、通风、阴凉的环境条件下存储 |
| `company` | `company_name` | 公司 | 贵州茅台酒股份有限公司 |

### 图片地址表字段映射

| 前端字段 | 数据库字段 | 说明 | 筛选条件 |
|---------|-----------|------|----------|
| `url` | `image_url` | 图片URL地址 | - |
| `type` | `image_category` | 图片分类 | = 2 (商品详情图片) |
| `sort` | `sort_order` | 排序权重 | ASC |
| `productId` | `product_code` | 商品编码 | = 当前商品ID |

## 替换步骤

### 步骤1：配置API基础地址

在 `api/config.js` 中配置真实的后端API地址：

```javascript
// api/config.js
export const API_CONFIG = {
    BASE_URL: 'http://localhost:8080', // 替换为真实后端地址
    TIMEOUT: 10000,
    HEADERS: {
        'Content-Type': 'application/json'
    }
}
```

### 步骤2：替换模拟接口

将 `api/product.js` 中的模拟实现替换为真实API调用：

```javascript
// 替换前
export const getProductDetail = async (productId) => {
    await delay(600) // 删除模拟延迟
    // 删除模拟数据逻辑
    // 添加真实API调用
}

// 替换后
export const getProductDetail = async (productId) => {
    try {
        const response = await uni.request({
            url: `${API_CONFIG.BASE_URL}/api/products/${productId}`,
            method: 'GET',
            timeout: API_CONFIG.TIMEOUT,
            header: {
                ...API_CONFIG.HEADERS,
                'Authorization': `Bearer ${getToken()}`
            }
        })
        
        // 处理响应数据
        return handleApiResponse(response)
    } catch (error) {
        return handleApiError(error)
    }
}
```

### 步骤3：更新错误处理

使用统一的错误处理机制：

```javascript
// utils/api.js
export const handleApiResponse = (response) => {
    if (response.statusCode >= 200 && response.statusCode < 300) {
        return {
            success: true,
            message: response.data.message || '请求成功',
            data: response.data.data
        }
    } else {
        throw new Error(response.data.message || `请求失败: ${response.statusCode}`)
    }
}

export const handleApiError = (error) => {
    console.error('API请求失败:', error)
    return {
        success: false,
        message: error.message || '网络请求失败',
        data: null
    }
}
```

### 步骤4：测试接口

1. 确保后端服务正常运行
2. 测试商品详情接口：`GET /api/products/{productId}`
3. 测试商品图片接口：`GET /api/products/{productId}/images?imageType=2&limit=6`
4. 验证返回数据结构是否符合前端要求

## 注意事项

### 1. 图片数量限制
- 商品详情页最多显示6张图片
- 通过 `limit=6` 参数控制
- 前端使用 `.slice(0, 6)` 作为备用限制

### 2. 图片分类筛选
- 商品详情图片的 `imageType` 必须为 2
- 后端需要根据此条件筛选图片

### 3. 数据完整性
- 确保所有必需字段都有值
- 对于可选字段，提供合理的默认值
- 处理空值或null的情况

### 4. 性能优化
- 图片使用CDN加速
- 实现图片懒加载
- 考虑图片压缩和格式优化

### 5. 错误处理
- 网络错误：显示重试按钮
- 数据错误：显示默认内容
- 权限错误：跳转到登录页

## 测试清单

- [ ] 商品详情接口正常返回
- [ ] 商品图片接口正常返回
- [ ] 图片数量限制为6张
- [ ] 所有商品特点字段正确显示
- [ ] 错误情况处理正常
- [ ] 加载状态显示正常
- [ ] 页面跳转功能正常

## 总结

完成以上替换后，商品详情页将从模拟数据切换到真实的后端API，实现数据的动态获取和展示。确保在替换过程中保持前端界面的稳定性和用户体验的一致性。