client_proxy_framework

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

设计思路

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

使用方式

1. 添加依赖

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

2. 实现配置

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. 初始化并调用

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

映射表

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

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

可配置项

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