文档：输出使用文档
This commit is contained in:
ivan
parent
7192c7275e
commit
d1f51b9245
@ -15,6 +15,10 @@
|
|||||||
|
|
||||||
从零创建一个新的换皮应用（`skin_config.json`、`ClientBootstrap`、`main` 初始化顺序、Android/iOS 要点等），请阅读 **[《创建新换皮应用 — 步骤清单》](create_new_skin_app.md)**。
|
从零创建一个新的换皮应用（`skin_config.json`、`ClientBootstrap`、`main` 初始化顺序、Android/iOS 要点等），请阅读 **[《创建新换皮应用 — 步骤清单》](create_new_skin_app.md)**。
|
||||||
|
|
||||||
|
### 功能总览与用法
|
||||||
|
|
||||||
|
按模块整理的“功能 + 最小调用示例”请见 **[《Framework 功能与用法总览》](framework_feature_usage.md)**。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. 快速开始
|
## 2. 快速开始
|
||||||
|
|||||||
309
docs/framework_feature_usage.md
Normal file
309
docs/framework_feature_usage.md
Normal file
@ -0,0 +1,309 @@
|
|||||||
|
# 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`
|
||||||
Loading…
x
Reference in New Issue
Block a user