# ApiMixin 使用指南

## 概述
`ApiMixin` 是一个 Vue mixin，用于统一管理和简化应用中的 API 调用。它提供了两个主要方法：
- `callApi()` - 基础的 API 调用方法
- `callApiWithErrorMsg()` - 带自动错误处理的 API 调用方法

## 安装步骤

### 1. 引入 ApiMixin
在您的 HTML 页面中添加脚本引用（在 Vue 和其他依赖之后）：
```html
<script src="Scripts/ApiMixin.js"></script>
```

### 2. 在 Vue 组件中使用
在您的 Vue 组件中，在 mixins 数组中添加 `ApiMixin`：
```javascript
receiptEditApp = new Vue({
    el: '#receiptEditApp',
    mixins: [DateMixin, ToastMixin, ApiMixin],  // 添加 ApiMixin
    data: { ... },
    // 其他选项
});
```

## API 方法

### callApi(endpoint, functionName, data)
**用途**: 调用 API 并返回原始结果

**参数**:
- `endpoint` (string): API 端点名称（.asmx 文件名）
  - 示例: `'領據處理'`, `'付款設定'`
- `functionName` (string): 方法名称
  - 示例: `'Save'`, `'GetOne'`, `'SearchRecipient'`
- `data` (object, 可选): 要传送的数据对象，默认为 `{}`

**返回值**: Promise，resolve 时返回 API 响应对象，reject 时返回错误对象

**示例**:
```javascript
// 基础使用
try {
    const result = await this.callApi('領據處理', 'GetOne', { no: '001' });
    console.log(result.Data);
} catch (error) {
    console.error('API 调用失败:', error);
}

// 不等待结果
this.callApi('領據處理', 'Save', data)
    .then(result => {
        this.ShowSuccess(result.Message);
    })
    .catch(error => {
        this.ShowError(error.message);
    });
```

### callApiWithErrorMsg(endpoint, functionName, data, errorPrefix)
**用途**: 调用 API 并自动显示错误消息

**参数**:
- `endpoint` (string): API 端点名称
- `functionName` (string): 方法名称
- `data` (object, 可选): 要传送的数据对象
- `errorPrefix` (string, 可选): 错误消息前缀，默认为 `'操作'`

**返回值**: Promise，reject 时自动调用 `this.ShowError()`

**示例**:
```javascript
// 使用自动错误处理
try {
    const result = await this.callApiWithErrorMsg('領據處理', 'Save', data, '儲存');
    this.ShowSuccess(result.Message);
} catch (error) {
    // 错误已自动显示
    console.error('操作失败:', error);
}
```

## 完整示例

### 原始代码（冗长）
```javascript
loadData(no) {
    this.loading = true;

    axios({
        method: 'post',
        url: `${API_BASE}/GetOne`,
        headers: {
            'Content-Type': 'application/json; charset=utf-8'
        },
        data: JSON.stringify({ no })
    })
        .then(response => {
            const result = response.data.d || response.data;
            if (result.Success) {
                this.mainData = result.Data.main;
                this.laborData = result.Data.labor;
                this.travelData = result.Data.travel;
                this.backupData();
            } else {
                this.ShowError('載入失敗: ' + result.Message);
            }
        })
        .catch(error => {
            console.error('LoadData error:', error);
            this.ShowError('載入發生錯誤: ' + (error.message || '請檢查網路連線'));
        })
        .finally(() => {
            this.loading = false;
        });
}
```

### 使用 ApiMixin 的简化代码
```javascript
async loadData(no) {
    this.loading = true;

    try {
        const result = await this.callApiWithErrorMsg('領據處理', 'GetOne', { no }, '載入');
        
        this.mainData = result.Data.main;
        this.laborData = result.Data.labor;
        this.travelData = result.Data.travel;
        this.backupData();
    } catch (error) {
        console.error('LoadData error:', error);
    } finally {
        this.loading = false;
    }
}
```

## 重构建议

使用 ApiMixin 后，您可以将 `領據處理.js` 中的多个方法简化：

1. **save()** - 减少 ~15 行代码
2. **loadDropdownList()** - 减少 ~10 行代码
3. **searchRecipient()** - 减少 ~10 行代码
4. **searchPlan()** - 减少 ~10 行代码
5. **searchOriginStation()** - 减少 ~10 行代码
6. **searchDestStation()** - 减少 ~10 行代码
7. **calculateTax()** - 减少 ~5 行代码
8. **calculateFare()** - 减少 ~5 行代码

**总计**: 可减少 ~65+ 行代码，提高代码可读性和可维护性

## 错误处理

ApiMixin 会自动处理以下情况：
- ✅ API 响应格式 (`data.d` 或 `data`)
- ✅ Success 字段检查
- ✅ 错误消息提取
- ✅ 网络错误捕获
- ✅ 自动显示错误（使用 `callApiWithErrorMsg`）

## 注意事项

1. **ToastMixin 依赖**: `callApiWithErrorMsg` 需要 `this.ShowError()` 方法，确保您的 Vue 组件已混入 `ToastMixin`

2. **API_BASE 变量**: 确保 `API_BASE` 全局变量已定义

3. **异步/等待**: 建议在 async/await 的 try-catch 块中使用，更易读

4. **错误消息格式**: 错误消息会自动格式化为 `"{errorPrefix}失敗: {具体错误信息}"`

## 性能优化

由于所有 API 调用都走同一个方法，未来可以在 `callApi` 中添加：
- ✅ API 请求/响应日志
- ✅ 请求超时管理
- ✅ 重试机制
- ✅ 请求缓存
- ✅ 性能监测

无需修改调用代码！