client_framework/docs/framework_feature_usage.md

Framework 功能与用法总览

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

1. 初始化与配置

1.1 两种初始化方式

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

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

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：删除账号

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

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

B. 三方下单：ThirdPartyCheckoutCoordinator

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

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

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

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：本地映射管理

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：预签名上传地址

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”全流程。

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

4.3 进度轮询：ImageProgressPoll

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

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)：提交反馈内容

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 自动映射埋点

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