310 lines
7.5 KiB
Markdown
310 lines
7.5 KiB
Markdown
# 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`
|