# Framework 功能与用法总览

本文档按“对外可用功能”整理 `client_proxy_framework` 的主要能力和用法，覆盖初始化、认证、支付、图像任务、反馈、埋点与常用工具。

## 1. 初始化与配置

### 1.1 两种初始化方式

- **方式 A（推荐换皮）**：`ClientBootstrap` + `skin_config.json`
- **方式 B（手写配置）**：自定义 `AppConfig` + `ApiClient.init`

```dart
import 'package:client_proxy_framework/client_proxy_framework.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 方式 A：从资产加载皮肤配置（推荐）
  await ClientBootstrap.initFromAsset('assets/skin_config.json');
  await ClientBootstrap.initAnalytics(); // 可选：Adjust/Facebook

  // 方式 B：手写配置
  // ApiClient.init(MyAppConfig());

  runApp(const MyApp());
}
```

### 1.2 字段映射（FieldMapping）

调用层统一使用逻辑字段（例如 `userId`、`deviceId`、`credits`），框架自动做请求/响应映射。  
如需适配新后端，只需调整 `fieldMapping`。

---

## 2. 认证与用户功能

### 2.1 启动登录编排：`FrameworkAuthService`

`FrameworkAuthService` 封装了：

1. `fastLogin`
2. 归因上报（Adjust/Facebook/Play）
3. `getCommonInfo`

```dart
class MyAuthCallbacks implements AuthServiceCallbacks {
  @override
  Future<String> getDeviceId() async => 'device_id';

  @override
  String computeSign(String deviceId) => 'SIGN';

  @override
  void onLoginSuccess(FastLoginResponse data) {
    // 可在这里同步宿主状态
  }
}

void setupAuth() {
  FrameworkAuthService.init(MyAuthCallbacks());
  FrameworkAuthService.start();
}
```

### 2.2 常用用户 API：`UserApi`

- `fastLogin`：设备登录
- `referrer`：归因上报
- `getCommonInfo`：拉取公共配置与开关
- `getAccount`：账户信息
- `getCreditsPage`：积分流水分页
- `getUserPayments`：用户支付记录
- `getUnreadMessageCount`：未读消息
- `deleteAccount`：删除账号

```dart
final cfg = ApiClient.instance.config;
final app = defaultTargetPlatform == TargetPlatform.iOS
    ? cfg.backendAppTypeIOS
    : cfg.backendAppTypeAndroid;

final accountRes = await UserApi.getAccount(app: app, userId: 'uid');
if (accountRes.isSuccess) {
  final credits = accountRes.data?.credits;
}
```

---

## 3. 支付能力

支付建议按“商品 -> 支付方式 -> 下单 -> 支付结果处理”来接入。

### 3.1 商品与支付接口：`PaymentApi`

- `getGooglePayActivities` / `getApplePayActivities`：商品档位
- `getPaymentMethods`：第三方支付方式列表
- `createPayment`：创建订单
- `getOrderDetail`：订单查询
- `googlepay`：Google Play 回调验证

### 3.2 支付编排（推荐入口）

#### A. 商品加载：`PaymentFlowCatalog`

```dart
final productsRes = await PaymentFlowCatalog.loadStoreActivities();
final productList = productsRes.data?.productList ?? [];
```

#### B. 三方下单：`ThirdPartyCheckoutCoordinator`

```dart
final outcome = await ThirdPartyCheckoutCoordinator.createOrder(
  userId: 'uid',
  activityId: 'activity_id',
  paymentMethod: 'GOOGLEPAY',
);
if (!outcome.success) return;

await ThirdPartyCheckoutCoordinator.openPayUrlIfPresent(
  outcome.payUrl,
  (uri) async {
    // 宿主实现：WebView 或外链
  },
);
```

#### C. 第三方支付状态轮询：`ThirdPartyPaymentWatch`

```dart
final watch = ThirdPartyPaymentWatch(
  userId: 'uid',
  sink: mySettlementSink,
);
watch.start(orderId: 'order_id');
// 页面销毁时 watch.dispose();
```

#### D. Google Play 原生内购编排：`NativeIapCoordinator`

```dart
await NativeIapCoordinator.purchaseGooglePlay(
  sink: mySettlementSink,
  userId: 'uid',
  activityId: 'activity_id',
  storeProductId: 'google_product_id',
);
```

### 3.3 Google Play 执行与补单：`PaymentService`

- `launchPurchaseAndReturnData`：拉起购买并回收 `purchaseData/signature/orderId`
- `completeAndConsumePurchase`：核销+消费
- `runOrderRecovery`：补单（未核销订单恢复）
- `saveIdForGoogleOrderId/getIdForGoogleOrderId`：本地映射管理

```dart
final needRefresh = await PaymentService.runOrderRecovery(
  userId: 'uid',
  onPaymentCallback: (id, signature, purchaseData, userId) async {
    final res = await PaymentApi.googlepay(
      signature: signature,
      purchaseData: purchaseData,
      orderId: id,
      userId: userId,
    );
    return PaymentResult(
      isSuccess: res.isSuccess,
      msg: res.msg,
    );
  },
);
```

### 3.4 支付结果出口：`PaymentSettlementSink`

所有支付编排最终都走 `PaymentSettlementSink.onPaymentSettled`。  
可使用 `PaymentSettlementSinkWithAnalytics` 自动补埋点。

---

## 4. 图像/视频任务能力

### 4.1 基础接口：`ImageApi`

常用接口：

- `getCategoryList`：分类列表
- `getImg2VideoTasks`：模板/任务列表
- `getPromptRecommends`：推荐提示词
- `createTxt2Img`：文生图任务
- `createTask`：图像任务创建
- `getProgress`：进度查询
- `getMyTasks`：我的任务列表
- `getUploadPresignedUrl`：预签名上传地址

```dart
final createRes = await ImageApi.createTask(
  userId: 'uid',
  prompt: 'A futuristic city',
  size: '720p',
  needopt: false,
);
final taskId = createRes.data?.taskId;
```

### 4.2 上传 + 创建任务一体流：`ImagePresignedUploadCreateTaskFlow`

封装了“压缩 -> 预签名 -> PUT 上传 -> createTask”全流程。

```dart
final result = await ImagePresignedUploadCreateTaskFlow.run(
  sourceFile: File('/path/to/local.jpg'),
  userId: 'uid',
  compressFirst: true,
);
final taskId = result.createResponse.taskId;
```

### 4.3 进度轮询：`ImageProgressPoll`

串行轮询，支持临时网络失败重试与可取消句柄。

```dart
final handle = ImageProgressPoll.start(
  app: 'HAndroid',
  taskId: 'task_id',
  userId: 'uid',
  onTick: (tick) {
    final progress = tick.response.data;
    if (progress == null) return;
    // 刷新 UI
  },
  onFatalError: (msg) {
    // 提示用户
  },
);

// 取消轮询
handle.cancel();
```

### 4.4 本地封面与历史解析

- `TaskUploadCoverStore`：按任务 ID 维护本地上传封面缓存
- `ImageTaskHistory`：解析“我的任务”并合并本地封面路径

---

## 5. 反馈功能

`FeedbackApi` 提供：

- `getUploadPresignedUrl(fileName)`：获取反馈图片上传地址
- `submit(fileUrls, content, contentType)`：提交反馈内容

```dart
final submitRes = await FeedbackApi.submit(
  fileUrls: ['https://cdn.example.com/a.jpg'],
  content: 'The output is blurry.',
  contentType: 'text/plain',
);
```

---

## 6. 埋点与归因

### 6.1 SDK 级埋点：`AnalyticsService` / `AdjustService` / `FacebookService`

用于初始化与底层事件上报。

### 6.2 业务埋点封装：`AnalyticsEvents`

已内置：

- 档位点击埋点
- 首注/支付成功/支付失败埋点
- `PaymentSettlement` 自动映射埋点

```dart
AnalyticsEvents.trackPaymentSettlement(
  settlement,
  product: selectedProduct,
);
```

---

## 7. 典型接入顺序（建议）

1. 初始化 `ClientBootstrap` / `ApiClient`
2. 可选初始化 `Analytics`
3. 初始化并启动 `FrameworkAuthService`
4. 充值页进入先跑 `PaymentService.runOrderRecovery`
5. 购买时使用 `PaymentFlowCatalog + ThirdPartyCheckoutCoordinator + NativeIapCoordinator`
6. 图片页使用 `ImagePresignedUploadCreateTaskFlow + ImageProgressPoll`
7. 反馈页使用 `FeedbackApi`

---

## 8. 相关文档

- 新换皮流程：`docs/create_new_skin_app.md`
- 支付时序细节：`docs/payment_flow.md`
- SDK 集成细节：`docs/sdk_integration_guide.md`
- 总体指南：`docs/README.md`