图像转换库

本文档介绍 HealthAide 应用中与"图像转换"能力相关的实现：基于 iFLYTEK（讯飞）AI 服务的文生图（Text-to-Image）转换链路，以及图像验证码的展示与校验组件。

Purpose and Scope

本页覆盖 code/app/HealthAide_V1.1.0_SDK_V1.14.0 模块中与图像生成、图像转换、图像验证相关的全部组件：

  • 文生图转换链路：TextToImageApi → TextToImageParam / TextToImageResponse → IflytekTextToImageWrapper
  • 图像验证组件：ImageCaptchaDialog 及其布局 dialog_image_verify.xml

以下主题属于兄弟页面，不在本页展开：

  • 媒体文件传输（文件上传/下载协议）——见 6-transfer-media 目录下其他子页面
  • 通用 HTTP 网络层实现——仅在本页作为上游依赖提及
  • 语音 AI 能力（iFLYTEK 语音相关封装）——属于 AI 模块其他页面

说明：本文档基于仓库内已发现的源文件路径与命名约定撰写。受源代码探索预算限制，未能读取全部文件正文，因此"推断"信息均已明确标注，未虚构任何代码示例。如需精确 API 签名，请直接查看下方源码链接。

Overview

在 HealthAide 应用中，"图像转换"不是一个独立的像素处理库，而是由两条能力线组成：

  1. 文本到图像的 AI 转换：应用将用户输入的提示词（prompt）通过 HTTP API 发送给讯飞 AI 服务，服务端生成图像并返回；应用侧用 TextToImageResponse 接收结果，由 IflytekTextToImageWrapper 封装调用细节，供上层 UI 使用。
  2. 图像验证码的展示与校验：在需要人机验证的场景（如登录、敏感操作）中，ImageCaptchaDialog 负责展示服务端下发的验证码图片，收集用户输入并回传校验。

这种设计遵循了"转换与消费分离"的意图：tool/http 层只负责把文本参数转换为图像结果的网络契约（参数对象 → 请求 → 响应对象），tool/aiui 层负责封装 AI 供应商的调用细节，而 ui/dialog 层只关心图像结果的展示与用户交互。分层清晰，便于替换 AI 供应商或复用图像结果。

Architecture

flowchart TD
    subgraph sg_UI["UI 层 (ui/dialog)"]
        CaptchaDialog["ImageCaptchaDialog"]
        CaptchaLayout["dialog_image_verify.xml"]
    end

    subgraph sg_AI["AI 封装层 (tool/aiui/iflytek)"]
        IflytekWrapper["IflytekTextToImageWrapper"]
    end

    subgraph sg_HTTP["HTTP 契约层 (tool/http)"]
        Api["TextToImageApi"]
        Param["TextToImageParam"]
        Response["TextToImageResponse"]
    end

    subgraph sg_External["外部服务"]
        IflytekService["iFLYTEK AI 服务 (文生图)"]
        CaptchaServer["验证码下发/校验服务"]
    end

    IflytekWrapper -->|"调用"| Api
    Api -->|"携带"| Param
    Api -->|"解析为"| Response
    Api -->|"HTTP 请求"| IflytekService
    IflytekService -->|"图像结果"| Response
    Response -->|"图像数据"| IflytekWrapper
    IflytekWrapper -->|"图像展示"| CaptchaDialog
    CaptchaDialog -->|"引用布局"| CaptchaLayout
    CaptchaDialog -->|"请求验证码/提交答案"| CaptchaServer

架构说明：

  • HTTP 契约层（tool/http） 是文生图转换的"入口与出口"：TextToImageParam 定义请求参数（文本提示词等），TextToImageApi 定义网络端点，TextToImageResponse 定义响应模型。该层不关心 AI 供应商的实现细节，只维护数据契约。
  • AI 封装层（tool/aiui/iflytek） 的 IflytekTextToImageWrapper 是对讯飞文生图服务的门面（Facade）封装，向上层屏蔽了参数组装、网络调用、响应解析等细节。
  • UI 层（ui/dialog） 的 ImageCaptchaDialog 与 dialog_image_verify.xml 负责把（由服务端生成或由文生图链路产生的）图像呈现给用户，并完成验证码输入交互。
  • 外部服务 是转换能力的真正执行者：讯飞 AI 服务把文本"转换"为图像；验证码服务负责下发与校验图像验证码。
flowchart LR
    subgraph sg_Flow["文生图转换主流程"]
        A["用户输入提示词"] --> B["IflytekTextToImageWrapper"]
        B --> C["TextToImageApi 发送请求"]
        C --> D["iFLYTEK 服务生成图像"]
        D --> E["TextToImageResponse 接收结果"]
        E --> F["上层 UI 展示图像"]
    end

注：以上流程图为基于组件职责与命名约定的推断，未读取到方法级实现细节。

组件详解

TextToImageApi — 文生图网络端点

文件：TextToImageApi.java

职责：定义文本转图像的 HTTP 端点。从类名与所在包（tool/http/api）推断，该类为 Retrofit 风格接口或 HTTP 工具类，负责将 TextToImageParam 序列化为请求并发送至讯飞服务。

设计意图：把"网络调用"抽象为独立 API 契约，使上层（IflytekTextToImageWrapper）不直接接触 URL、鉴权头等传输细节，便于后续替换传输实现（如 OKHttp 换 Retrofit）而不影响业务层。

TextToImageParam — 请求参数模型

文件：TextToImageParam.java

职责：封装文生图请求所需的全部入参（推断至少包含提示词文本，可能含图像尺寸、数量、风格等可选字段）。位于 model/param 包，与 model/response 对称，遵循"请求/响应模型分离"的常见网络层约定。

TextToImageResponse — 响应模型

文件：TextToImageResponse.java

职责：承载文生图结果（推断包含图像 URL 或 Base64 数据、错误码、请求标识等字段）。作为转换链路的"输出 DTO"，其设计决定了上层如何消费生成的图像。

IflytekTextToImageWrapper — 讯飞文生图封装

文件：IflytekTextToImageWrapper.java

职责：位于 tool/aiui/iflytek 包，是讯飞 AI 能力的门面封装。从命名推断，它把"文本 → 图像"的完整转换流程（构造参数、调用 TextToImageApi、解析 TextToImageResponse、失败重试/回调）收敛到一个 Wrapper 类中，向 UI 层暴露简洁接口。

设计意图：Wrapper 模式在此的意义是供应商隔离——若未来切换或并行接入其他文生图服务商，只需新增对应 Wrapper，上层调用方无需改动。

ImageCaptchaDialog — 图像验证码对话框

文件：ImageCaptchaDialog.java 与 dialog_image_verify.xml

职责：在需要人机验证的界面弹窗中展示验证码图像、接收用户输入并提交校验。布局文件定义弹窗 UI（图像展示区 + 输入框 + 确认/刷新按钮）。

设计意图：将验证码交互封装为独立 Dialog，可复用于登录、注册、敏感操作等多个入口，避免每个页面重复实现图像加载与校验逻辑。

核心数据流

sequenceDiagram
    participant UI as UI 调用方
    participant W as IflytekTextToImageWrapper
    participant API as TextToImageApi
    participant S as iFLYTEK 服务
    participant R as TextToImageResponse

    UI->>W: 请求生成图像（传入提示词）
    activate W
    W->>W: 构造 TextToImageParam
    W->>API: 发起网络请求
    activate API
    API->>S: HTTP 请求（携带参数）
    S-->>API: 返回图像结果
    API->>R: 解析为响应对象
    deactivate API
    R-->>W: 返回响应模型
    W-->>UI: 回调结果（图像/错误）
    deactivate W

流程说明（推断）：

  1. UI 层调用 IflytekTextToImageWrapper 并传入提示词；
  2. Wrapper 构造 TextToImageParam（可能补充默认尺寸、风格等参数）；
  3. 通过 TextToImageApi 发送 HTTP 请求至讯飞服务；
  4. 服务端完成"文本 → 图像"的实际转换并返回数据；
  5. TextToImageResponse 承载结果回传 Wrapper，再由 Wrapper 回调 UI 层展示。

该链路体现了转换与展示分离：网络契约层不感知图像内容，UI 层不感知网络细节。

图像验证码交互流程

sequenceDiagram
    participant U as 用户
    participant D as ImageCaptchaDialog
    participant S as 验证码服务

    D->>S: 请求验证码图像
    S-->>D: 返回图像（dialog_image_verify.xml 展示）
    U->>D: 输入验证码文本
    D->>S: 提交校验
    S-->>D: 校验结果
    D-->>U: 成功回调 / 失败提示（可刷新重试）

注：以上交互细节为基于组件职责的推断，未在源码正文中逐行验证。

Usage Examples

受源代码探索预算限制，本页未能读取到可引用的方法级源码正文。根据"禁止虚构代码示例"原则，此处不提供杜撰的代码块。请通过下方源码链接直接查阅：

Configuration Options

配置项类型默认值说明验证状态
TextToImageParam 各字段推断为 String/int 等未读取提示词、图像尺寸、数量等请求参数推断（未读取正文）
TextToImageResponse 各字段推断为 String/List未读取图像 URL/Base64、错误码等推断（未读取正文）
讯飞服务地址与鉴权信息推断位于 HTTP 层未读取端点 URL、API Key 等推断（未读取正文）

以上配置项仅为基于文件职责的推断。精确字段名、类型与默认值请查阅上方源码链接中的模型类定义。

Failure Modes, Edge Cases & Concurrency

基于组件职责的推断，以下场景是需要重点关注的失败路径（未在源码中逐行验证）：

  • 网络失败/超时：文生图与验证码请求均依赖网络。IflytekTextToImageWrapper 与 ImageCaptchaDialog 应处理请求失败时的重试或错误提示（验证码弹窗通常提供"刷新"入口重新拉取图像）。
  • 服务端返回异常：TextToImageResponse 大概率包含错误码字段，上层需在图像字段为空或错误码非 0 时给出用户可理解的提示。
  • 图像加载失败：若 TextToImageResponse 返回的是图像 URL，UI 层需要处理 URL 失效、加载失败、解码异常（Bitmap 解码 OOM 等）的情况。
  • 并发/重复点击：验证码弹窗中用户可能快速多次点击"确认"，需要防抖或禁用按钮；文生图请求如由异步回调驱动，需注意回调线程与 UI 线程的切换（Android 主线程约束）。
  • 验证码过期：验证码通常有有效期，用户输入过慢会导致校验失败，弹窗应支持刷新重新获取。

Extension Points

  • 更换/新增 AI 供应商：IflytekTextToImageWrapper 以 Wrapper 模式隔离供应商实现。新增其他文生图服务商时，可仿照该类新增 Wrapper，并复用 TextToImageApi/TextToImageParam/TextToImageResponse 契约层（若契约兼容）或新增对应模型。
  • 验证码复用：ImageCaptchaDialog 设计为独立弹窗组件，可被登录、注册、敏感操作等多个页面复用；dialog_image_verify.xml 可独立调整验证码展示样式而不影响逻辑。

Performance & Operational Notes

  • 文生图属于慢操作（AI 推理耗时通常为秒级），应异步执行并展示加载态，避免阻塞 UI 线程。
  • 图像数据若以 Base64 传输，注意内存占用；若以 URL 传输，建议接入图片加载库的缓存与缩放机制。
  • 验证码图片体积小、请求频繁，可考虑短期缓存或预加载以提升用户体验。

两条能力线对比

维度文生图转换（AI 图像生成）图像验证码（人机校验）
核心入口IflytekTextToImageWrapperImageCaptchaDialog
网络契约TextToImageApi + TextToImageParam / TextToImageResponse验证码服务（UI 层直接交互）
转换方向文本 → 图像（AI 生成）图像 → 用户输入（校验）
典型场景用户生成健康主题插图、自定义图片登录、注册、敏感操作的人机验证
失败特征慢请求、AI 服务限流、图像解码失败验证码过期、输入错误、重复提交

设计意图总结：HealthAide 的"图像转换"能力遵循契约分层 + 供应商隔离 + 组件复用三大原则：

  1. 契约分层：model/param 与 model/response 对称分离，请求与响应模型独立演进；
  2. 供应商隔离：IflytekTextToImageWrapper 门面封装使讯飞实现可替换；
  3. 组件复用：ImageCaptchaDialog 作为独立弹窗组件服务于多个业务入口。

已知局限与后续补充建议

本文档基于仓库文件发现结果撰写，受探索预算限制存在以下信息缺口，建议后续补充验证：

  • 各类的方法签名与字段定义（需读取 TextToImageParam、TextToImageResponse、IflytekTextToImageWrapper 正文）；
  • 网络层实现细节（端点 URL、鉴权方式、超时与重试策略）；
  • 调用方（哪些 UI 页面调用了文生图与验证码能力）；
  • 错误码语义与图像数据格式（URL vs Base64）。

在补充验证前，请以 仓库源码 中对应文件的实际实现为准。