文档：输出使用文档
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)**。
|
||||
|
||||
### 功能总览与用法
|
||||
|
||||
按模块整理的“功能 + 最小调用示例”请见 **[《Framework 功能与用法总览》](framework_feature_usage.md)**。
|
||||
|
||||
---
|
||||
|
||||
## 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