# client_proxy_framework

通用代理 API 框架。**接口请求已按原始字段名写好**，不同应用只需**修改映射表**即可接入不同后端。

**新建换皮应用**：请阅读 [docs/create_new_skin_app.md](docs/create_new_skin_app.md)（`skin_config.json` + `ClientBootstrap` 全流程）。

## 设计思路

- **业务层**：统一使用**原始字段名**（canonical），如 `deviceId`、`userId`、`credits`、`userToken`
- **映射层**：`FieldMapping` 负责 原始 ↔ V2 互转
- **换皮应用**：只需提供自己的 `fieldMapping`，无需改业务代码

## 使用方式

### 1. 添加依赖

```yaml
dependencies:
  client_proxy_framework:
    path: ../client_proxy_framework   # 与 app_client_1 同级
```

### 2. 实现配置

```dart
class MyAppConfig extends AppConfig {
  @override
  String get appId => 'YourAppId';
  @override
  String get packageName => 'com.yourapp.package';
  @override
  String get aesKey => 'your-16-char-key';
  @override
  String get preBaseUrl => 'https://pre-api.example.com';
  @override
  String get prodBaseUrl => 'https://api.example.com';
  @override
  String get proxyPath => '/quester/defender/summoner';

  // 若后端 V2 字段名不同，覆盖此方法
  @override
  FieldMapping get fieldMapping => myCustomFieldMapping;
}
```

### 3. 初始化并调用

```dart
void main() {
  ApiClient.init(MyAppConfig());
  runApp(MyApp());
}

// 使用原始字段名调用
final res = await UserApi.fastLogin(
  deviceId: deviceId,
  sign: sign,
  referer: referer,
);
if (res.isSuccess) {
  final data = res.data as Map<String, dynamic>;
  ApiClient.instance.setUserToken(data['userToken']);  // 原始字段名
  UserState.setCredits(data['credits']);
}
```

## 内置 API 服务（均使用原始字段名）

| 服务 | 方法示例 |
|------|----------|
| UserApi | fastLogin, referrer, getCommonInfo, getAccount |
| PaymentApi | getGooglePayActivities, getPaymentMethods, createPayment, googlepay |
| ImageApi | getCategoryList, getImg2VideoTasks, getProgress, getUploadPresignedUrl, createTask, getMyTasks |

## 映射表

单一映射表：**原始字段 → 后端字段**。请求时按此转换，响应时自动取反。

```dart
const myMapping = FieldMapping({
  'deviceId': 'origin',
  'userId': 'asset',
  'userToken': 'reevaluate',
  'credits': 'reveal',
  // ... 后端文档给的映射表直接填入即可
});
```

## 可配置项

| 配置项 | 说明 |
|--------|------|
| fieldMapping | 字段映射表，换皮应用主要修改此项 |
| proxyKeys | 代理请求体字段名 |
| v2SanctumPath | V2 嵌套路径 |
| responseCodeField / responseMsgField / responseDataField | 响应结构字段名 |