From d1f51b9245857e05f6dfd145940a32a584428a2e Mon Sep 17 00:00:00 2001 From: ivan Date: Tue, 14 Apr 2026 15:47:37 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E8=BE=93=E5=87=BA?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 4 + docs/framework_feature_usage.md | 309 ++++++++++++++++++++++++++++++++ 2 files changed, 313 insertions(+) create mode 100644 docs/framework_feature_usage.md diff --git a/docs/README.md b/docs/README.md index caa7361..9a4219b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,6 +15,10 @@ 从零创建一个新的换皮应用（`skin_config.json`、`ClientBootstrap`、`main` 初始化顺序、Android/iOS 要点等），请阅读 **[《创建新换皮应用 — 步骤清单》](create_new_skin_app.md)**。 +### 功能总览与用法 + +按模块整理的“功能 + 最小调用示例”请见 **[《Framework 功能与用法总览》](framework_feature_usage.md)**。 + --- ## 2. 快速开始 diff --git a/docs/framework_feature_usage.md b/docs/framework_feature_usage.md new file mode 100644 index 0000000..87fe372 --- /dev/null +++ b/docs/framework_feature_usage.md @@ -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 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 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`