suixinkan_uikit/docs/相册管理与AI修图功能说明.md

相册管理与 AI 修图功能说明

文档日期：2026-07-29
适用范围：新增相册 → 相册任务 → 相册管理 → 照片上传与传输 → 照片预览与 AI 修图
数据说明：相册和照片列表、有线相机连接及照片传输继续使用项目已有真实数据能力；传输模式选择保存在本地。原图精修结果、氛围感结果、封面模板、剩余 9 张额度及状态角标目前为本地可演示数据，尚未接入服务端持久化，App 进程重启后会清空。

1. 照片预览、左右滑动与底部操作

功能说明

用户在“相册管理”照片网格中点击任意缩略图，进入单张照片预览页。页面只保留一个返回按钮，导航区域展示当前照片文件名和文件大小；照片区域支持左右滑动查看同一相册内的上一张或下一张照片。

预览页统一使用黑色沉浸式自定义头部，不再混用系统导航栏：左侧为圆形返回按钮，中间展示文件名和文件大小，右侧展示“当前张数/总张数”。切换照片时三处信息同步更新。照片预览与原图精修、氛围感、封面模板预览都直接使用同一个全屏模态容器，不进入项目导航栈，因此不会叠加系统白色导航栏或出现两个返回按钮；关闭后回到进入前的相册管理页或修图弹窗。

底部固定展示以下三个操作，不展示打印按钮：

操作	点击结果	操作期间或异常处理
AI修图	打开当前照片的 AI 修图弹窗	当前照片处于“修图中”时按钮置灰，避免重复提交
删除	二次确认后删除当前照片	删除成功后自动定位到相邻照片；删除最后一张后返回相册管理
刷新	重新加载当前照片及最新修图结果	刷新失败时不清空当前已显示内容，可再次点击

左右滑动时同步刷新文件名、文件大小、原图/修图后状态和底部按钮状态。第一张继续向右滑、最后一张继续向左滑时保持当前照片，不循环跳转。

页面底部图标使用项目内 TravelAlbumPreviewIcons SVG 资源，确保 AI 修图、删除、刷新三个入口视觉一致。

状态流转图

本功能验收

• 从任意缩略图进入时只显示一个返回入口。
• 文件名和文件大小与当前照片一致。
• 导航头部保持黑色沉浸样式，右侧张数随照片切换同步变化。
• 左右滑动后照片和文件信息同步变化。
• 首尾照片不会越界或循环。
• 底部仅显示 AI修图、删除、刷新，不显示打印。
• 删除当前照片后能正确定位或退出预览。

2. 上传照片与传输模式选择

功能说明

相册管理处于普通状态时，用户点击底部“上传照片”，先从底部弹出“选择传输模式”，展示“边拍边传”和“拍后传输”两个选项。点击任一选项后弹窗关闭，并进入当前相册的有线传输页面；点击“取消”或向下关闭弹窗时停留在相册管理，不改变现有照片和选择状态。

传输模式	弹窗说明	下一页初始状态	后续行为
边拍边传	相机拍摄后，照片自动传输并上传到当前相册	传输模式显示“边拍边传”	新传入 App 的照片自动上传
拍后传输	拍摄完成后，再选择相机照片批量传输	传输模式显示“拍后传输”	新照片先保留，用户后续选择并上传

本次弹窗选择优先于本机上一次保存的传输模式，并同步成为新的最近使用模式，确保下一页展示和实际传输行为一致。相册 ID、相册名称、联系电话及照片数据继续沿用相册管理页面的真实数据，不创建新的相册或假照片。

进入有线传输页面后，非批量选择状态下点击任意照片缩略图，预览页会使用当前 Tab 筛选后的照片顺序，并从被点击照片开始展示。用户可左右滑动查看上一张或下一张，顶部页码随照片同步变化；没有可用预览地址的照片不进入预览序列，也不占用页码。第一张继续向右滑、最后一张继续向左滑时均停留在边界，不循环跳转。处于批量上传选择状态时，点击照片仍执行选择或取消选择，不打开预览。

状态流转图

本功能验收

• 点击“上传照片”后先显示底部传输模式弹窗，不直接进入下一页。
• 弹窗同时显示“边拍边传”和“拍后传输”及对应说明。
• 选择“边拍边传”后，下一页模式显示为“边拍边传”。
• 选择“拍后传输”后，下一页模式显示为“拍后传输”。
• 本次选择不会被上一次保存的模式覆盖。
• 取消或关闭弹窗后仍停留在相册管理。
• 非批量选择状态点击缩略图后，从被点击照片进入全屏预览。
• 预览可左右滑动查看当前 Tab 中的上一张和下一张，页码同步变化且首尾不循环。
• 批量选择状态点击照片只改变选择状态，不打开预览。

3. 相册管理多选与底部操作栏切换

功能说明

相册管理页普通状态下，底部显示“上传照片”。用户点击右上角选择按钮后进入多选状态，每张缩略图右上角显示选择圆圈，底部“上传照片”隐藏，替换为“AI修图”和“删除”。

多选状态	页面表现	可用操作	下一状态
未进入多选	不显示选择圆圈，底部显示上传照片	点击照片进入预览；点击右上角选择	进入多选
已进入但未选照片	显示未选圆圈，AI修图和删除置灰	选择照片；再次点击右上角选择退出	已选择或退出
已选择照片	选中照片显示勾选，AI修图和删除可用	发起批量修图或批量删除	弹窗、处理中或删除结果
选中项含修图中的照片	保留当前选择，AI修图置灰	等待任务完成；删除仍按现有删除规则处理	任务结束后恢复
退出多选	清空本次选择，恢复上传照片	上传或进入照片预览	普通状态

批量删除必须二次确认；用户取消时不删除任何照片并保留当前选择。批量 AI 修图复用与单张预览相同的预设、任务状态和结果覆盖逻辑。

状态流转图

本功能验收

• 进入多选后上传按钮消失，AI修图和删除出现。
• 未选择照片时两个批量按钮不可点击。
• 选择至少一张后两个批量按钮恢复可用。
• 包含修图中照片时不能再次发起 AI 修图。
• 退出多选后选择状态清空并恢复上传按钮。

4. AI 修图弹窗、原图精修、氛围感与按张收费模式

功能说明

用户从单张预览或相册多选操作栏点击“AI修图”后，以同一个底部弹窗展示 AI 修图配置。标题与弹窗顶部保留足够间距，标题下方展示“已选择 N 张照片”。弹窗内容可纵向滚动，取消和确定按钮固定在底部，照片较多并出现封面模块时也不会遮挡选择项。

“原图精修”是基础修图模块，使用横向滚动单选列表，每个预设同时展示名称和对应效果图：

预设	当前效果用途
还原为原图	清除该照片已有修图结果和封面类型
写真-简约肖像	低饱和、提亮的人像效果
写真-清冷古风	清冷复古效果
旅拍-锦绣	提升饱和度和对比度
旅拍-远山	低饱和、柔和远景效果
旅拍-薄雾	提亮并降低对比度
油画-夏日	偏暖夏日效果
油画-浓郁	高饱和、高对比效果

原图精修默认选中“还原为原图”，用户点击其他预设后仅保留一个选中项。没有可用原图时，效果图位置显示稳定占位图，不影响弹窗选择。每张样式效果图右下角都有“预览”按钮，点击后全屏查看当前照片应用该样式的效果，不改变当前选中项。

“氛围感修图”位于原图精修下方，并明确标记为“选填”。该模块与原图精修保持一致，使用横向滚动效果图单选，当前本地演示包含日落暖阳、复古胶片、清透蓝调、森系薄雾、浓郁故事五种样式。默认不选中；点击一种样式后仅保留该项，再次点击当前样式即可取消。每个样式同样提供“预览”按钮。选中后不是把氛围效果叠加并合并到精修图中，而是为每张照片额外生成一张可独立查看的“氛围感”结果。

原图精修、氛围感、封面模板和“查看高清图”统一进入同一个沉浸式大图预览页。大图页不再套用系统导航栏，只显示一个返回按钮、当前样式名称和“双指缩放查看细节”提示；关闭后回到原弹窗或照片页，并保留关闭前的选择状态。

弹窗内的 Tips 会随当前组合实时变化：

当前选择	确认后的结果
仅原图精修	每张照片生成 1 个“精修后”结果
原图精修 + 氛围感修图	每张照片生成“精修后 + 氛围感”2 个独立结果
有封面、未选氛围感	每张照片生成精修结果，第一张选中照片额外生成封面
有封面、已选氛围感	每张照片生成精修和氛围感 2 个结果，第一张选中照片再额外生成封面

“修图模式”区域只读展示“AI精修 · 按张收费”和“剩余 9 张”，不再显示勾选圆圈，也不能点击选择。当前剩余数量为本地演示数据，不会真实扣减额度；未来接入服务端时由接口返回剩余额度，并以任务创建成功或服务端明确返回的扣减结果为准。

点击“确定”提交当前原图精修、氛围感和封面组合并关闭弹窗；点击“取消”或关闭弹窗时不创建任务、不改变旧修图结果，也不改变额度。

状态流转图

本功能验收

• 标题与弹窗顶部间距自然，不贴近顶部。
• 已选照片数量准确。
• 原图精修预设同时展示文字和效果图，并可横向滚动、保持单选。
• 原图精修、氛围感和封面模板效果图均可通过小按钮全屏预览，预览不改变选择。
• 所有大图预览使用同一黑色头部、单一返回入口，并支持双指缩放。
• 氛围感修图横向展示多个效果图，默认不选中、保持单选，可再次点击当前样式取消。
• 同时选择原图精修和氛围感时，每张照片生成两个独立结果。
• Tips 能根据氛围感和封面选择动态说明实际输出结果。
• 修图模式只展示按张收费与剩余张数，不提供选择操作。
• 取消弹窗不会创建任务或覆盖旧结果。

5. AI 修图任务状态、失败重试与结果覆盖

功能说明

用户确认修图后，所选照片立即进入“修图中”。任务未结束前，相关 AI 修图入口置灰；即使用户离开照片预览页，本地演示任务仍会继续完成，并通过共享结果状态刷新相册缩略图。

任务状态	进入条件	页面表现	可用操作	后续状态
可发起	未修图、已有成功结果或上次任务已结束	AI修图按钮可用	选择预设并确认	修图中
修图中	已提交预设，等待结果	按钮置灰；缩略图显示“修图中”	查看其他照片、离开页面	成功或失败
成功	获取原图并完成本地效果处理	分别保存精修、氛围感和封面结果；默认展示“精修后”；按钮恢复	在已有结果间切换、再次修图、还原原图	新任务或已上传
失败	原图无法获取或处理失败	缩略图显示“修图失败”；按钮恢复	再次修图	修图中

成功后，照片预览页至少出现“原图 / 精修后”切换；本次选择了氛围感时增加“氛围感”，存在封面结果时增加“封面”。各结果互相独立，不把两个效果合成同一张图；有修图结果时还可以点击“查看高清图”。再次修图时，旧结果在新任务处理期间继续保留，新任务成功后整组替换为本次最新组合：本次未选择氛围感时会清除旧氛围感结果；新任务失败时保留旧成功图片，但状态优先显示“修图失败”，提醒用户本次任务未成功。

选择“还原为原图”会同时清除修图结果、失败状态和封面类型，缩略图恢复为“已上传”。删除照片时同步清理该照片的本地修图记录，避免已删除照片的结果残留。

状态流转图

本功能验收

• 修图中不能重复点击 AI修图。
• 离开预览页后任务仍能结束并刷新缩略图。
• 成功后可切换查看原图、精修后以及本次实际生成的氛围感或封面。
• 同选原图精修和氛围感时两个结果均可独立查看。
• 再次修图成功后以本次结果组合覆盖旧结果。
• 失败后按钮恢复并允许重试。
• 还原原图后所有本地修图类型和结果被清除。

6. 选中 4 张及以上时的封面模板选择

功能说明

从相册管理多选照片并点击“AI修图”时，系统根据选中照片数量决定是否展示“封面风格模板”：

选中数量	弹窗表现
1～3 张	展示“原图精修 + 氛围感修图（选填）”两个模块，不展示封面模板
≥ 4 张	展示“原图精修 + 氛围感修图（选填）+ 封面模板”三个模块，并提高弹窗高度

封面模板为横向滚动单选，默认选中“旅行纪念册”。每个模板效果图右下角提供“预览”按钮，点击后全屏查看完整排版，不改变当前模板选择。当前提供：

• 旅行纪念册
• 简约留白
• 景区故事
• 电影胶片

每个模板展示名称和以第一张选中照片生成的排版效果图。用户确认后，所有选中照片先生成原图精修结果；选择了氛围感时，所有照片再各自生成一个氛围感结果；第一张选中照片另外生成独立封面并作为封面承载图。封面不会替代精修或氛围感结果，用户进入预览后可分别切换查看。

当前所有封面模板 quotaCost = 0，弹窗显示“赠送 · 不占精修张数”，不会减少剩余修图额度。后续收费时保留同一选择流程，由服务端为模板返回大于 0 的 quotaCost，客户端在确认前显示实际消耗，并以服务端成功结果为准扣减；收费能力目前尚未实现。

再次对不少于 4 张照片选择新封面模板并修图时，新封面效果覆盖旧封面效果。封面承载图处理失败时不标记为封面成功，缩略图显示“修图失败”并允许重试。选择“还原为原图”时清除封面效果和封面类型。

状态流转图

本功能验收

• 选中 3 张时不显示封面模板。
• 选中 4 张或更多时显示封面模板。
• 有封面模块时，弹窗同时完整显示原图精修、氛围感和封面三个风格模块。
• 封面模板可横向滚动且始终单选。
• 每个封面模板均可独立预览，关闭预览后保留原选择。
• 默认选中旅行纪念册。
• 当前显示赠送并且不消耗精修额度。
• 成功后第一张选中照片成为封面承载图。
• 再次生成封面时以新结果覆盖旧结果。

7. 相册缩略图结果类型与显示优先级

功能说明

相册管理缩略图左上角复用同一状态位，根据照片当前结果显示不同类型，让用户无需进入预览即可区分未修、处理中、已修、封面和失败照片。

缩略图状态	角标文案与颜色	缩略图内容	进入条件	可用操作
普通原图	绿色“已上传”	服务端原图或缩略图	没有本地修图结果	预览、选择、AI修图、删除
处理中	蓝色“修图中”	有旧成功结果时继续显示旧结果，否则显示原图	AI 任务未结束	预览、删除；不能再次修图
普通修图结果	紫色“AI已修”	最新精修图片	原图精修成功，可同时存在氛围感结果	预览原图/精修后/氛围感、再次修图、还原
封面结果	橙色“AI封面”	所选封面模板排版图	封面承载图生成成功	预览、再次修图、重新生成封面、还原
修图失败	红色“修图失败”	有旧成功结果时保留旧图，否则显示原图	最近一次任务失败	再次修图、删除

状态显示优先级为：

修图中 > 修图失败 > AI封面 > AI已修 > 已上传

该优先级保证处理中或失败状态不会被历史成功结果遮盖。普通修图成功后显示“AI已修”；封面模板成功后，第一张选中照片显示封面排版图和“AI封面”，其他照片继续显示“AI已修”。再次修图成功后缩略图切换为最新结果；还原原图后回到“已上传”；删除照片后对应本地状态一起删除。

当前状态和结果由内存数据源在相册管理与照片预览之间共享，尚不支持 App 重启后的恢复。服务端接入时至少需要返回素材 ID、任务状态、结果类型、结果图地址、原图精修预设 ID、是否生成氛围感、封面模板 ID、失败原因和额度消耗，客户端才能恢复完全一致的缩略图状态。

状态流转图

本功能验收

• 未修图照片显示“已上传”。
• 修图中照片显示“修图中”且不能重复提交。
• 普通成功结果显示“AI已修”和最新效果图。
• 封面成功结果显示“AI封面”和封面排版图。
• 最近一次任务失败时优先显示“修图失败”。
• 还原、覆盖和删除后缩略图状态同步更新。