做文搜图时，检索结果出现并不意味着对应的照片资源一定还在。一次相册迁移、用户删除原图，或者导入中途退出，都可能让“引用表里的照片编号”和“实际资源清单”分离。页面仍能查到一条漂亮的标题，点击却找不到缩略图。把这种问题直接解释成搜索模型不准，很容易把排查方向带偏。

本文把焦点放到检索之后的离线引用治理：先用应用自有的清单判断哪些引用确实指向现存照片，再把可以公开展示的数据分组提交。遇到孤儿引用时，当前批次不得悄悄写入，更不能把整轮导入标为完成。这里讨论的是以后接入 HarmonyOS ArkData RelationalStore 的业务前置层，不是已经执行过的数据库或真实文搜图模型实验。

一、需要先拆开的三种“成功”

假设本地相册里原本有十二条检索引用。检索引擎返回十二个 assetId，并不保证十二个 assetId 的源文件仍然存在；引用表扫描完成十二条，也不保证它们都适合向用户显示；写入事务成功提交某几条，也不代表整个图库已经完成一致性修复。三个概念的完成条件不同，必须在日志和界面上区分。

本次规则夹具的项目叫 RefSnapshotGate，任务编号固定为 REF-1011-28，输入批次是 album_ref_12。应用自有清单提供十二条候选引用，其中 R01 至 R09 可以解析到相册照片，R10、R11、R12 分别指向已经不存在的 P999、P1000、P1001。预期结果是九条有效引用、三条孤儿引用，界面可见数为九，最终整批状态为 INDEX_REPAIR_HOLD。

最初容易犯的错误，是把总数从十二改成九以后继续显示“导入成功”。这会让运维误以为源数据只有九条，并且丢掉识别缺口的证据。更稳妥的做法是分别保留候选总数、有效数、孤儿数和可见数。用户侧可以只展示九张照片，诊断页仍应留下三条待修复引用。产品上看不到损坏项目，不等于系统没有损坏项目。

另一个误区是把“回滚”理解成整个页面的数据退回初始状态。本方案中 A、B 两组有效引用已经通过应用自定义事务端口完成模型提交，第三组 C 中的三条孤儿引用被模拟回滚。因此可见行数保持九，既不会因 C 失败清空 A、B，也不会把 C 的异常混进成功结果。这是分组导入的局部原子性，与数据库全局快照是否一致仍是两件事。

二、同一张照片为什么会留下悬空编号

业务里的照片 ID 通常比文件路径稳定：一张照片更名或换目录，业务 ID 可能保持不变；但如果用户从系统相册永久删除资源，旧引用并不会自动获得一个有效的新路径。搜索索引也可能保留临时资产编号，直到下一次后台维护才被发现。离线场景下不能依赖网络服务立刻修正全部索引，需要本地预检给出一个明确的灰度地带。

这里故意不把“文件存在”简化成打开路径返回 true。正式产品还必须考虑授权有效期、文件类型、是否已移入回收站、用户是否允许该图库继续被检索、资产映射有没有跨账户混用等条件。当前固定夹具只有 photoId 的存在性校验，不进行文件系统读取和权限检查；所以文中的 VALID 只能解释为“通过清单引用校验”，不能解读成“已验证可展示真实照片”。

设计表结构时最好把素材主表和检索引用表分开：素材主表保存应用识别的资源身份、最后检查时间与来源；引用表保存索引记录 ID、photoId、批次和逻辑删除标志。删除素材时，引用可以先进入隔离队列，再由事务将可见标志和诊断状态一起更新。这样即便异常退出，修复队列也能回答上次处理到哪里，而不是重扫后无法解释差异。

示例故意采用九条可用与三条孤儿的分布。R10 对应 P999，R11 对应 P1000，R12 对应 P1001。这三个数字只是应用自定义测试数据，绝非真实 Media Library Kit 返回的资源标识。若未来接入真实系统资源，必须把源资源的生命周期和授权获取流程另列一层，避免将示例字段误当平台保证。

三、先做一次纯数据分类，再考虑数据库连接

这一步解决两个问题：第一，不能把未知 photoId 直接带进可见表；第二，同一轮分类结果必须能够重复计算。分类器不修改数据库，也不释放照片对象，只返回两个数组。代码采用 TypeScript 可以直接在 Node.js 固定输入环境复核；移植到 ArkTS 时仍需根据项目的类型约束处理只读集合和实体类型。

interface PhotoEntry { id: string; title: string }
interface RefEntry { id: string; photoId: string; batch: string }
interface RefAudit { valid: RefEntry[]; orphan: RefEntry[] }

export function classifyRefs(photos: PhotoEntry[], refs: RefEntry[]): RefAudit {
  const photoIds: Set<string> = new Set(photos.map((p: PhotoEntry) => p.id));
  const valid: RefEntry[] = [];
  const orphan: RefEntry[] = [];
  for (const ref of refs) {
    if (photoIds.has(ref.photoId)) valid.push(ref);
    else orphan.push(ref);
  }
  return { valid, orphan };
}

这里没有自动“修复” R10 的路径。原因是按编号猜测同名照片可能造成身份串联，最坏情况下把别人的照片关联到当前索引。分类器只负责发现缺口，后续恢复要由明确的资源身份回查策略决定。对于不存在的对象，也不应该在循环里反复弹窗，记录 ID、photoId 和失败原因即可；能否重建索引、能否清除历史引用，需要下一层策略判断。

从生命周期角度看，分类函数没有持有文件句柄或数据库游标，因此失败路径简单。真正接入关系型数据库以后，扫描 ResultSet 要在完成读取或捕获异常时及时关闭，避免页面重复进入后游标留存。资料中常见的 relationalStore.getRdbStore 是取得 RdbStore 的入口，但该轮无法在 DevEco Studio 核实当前 SDK 的全部事务签名，因此下面的事务端口明确标注为应用自定义接口，不冒充系统方法。

四、把三个批次视为三份不同的承诺

若把十二条候选一次性写入，混入孤儿引用后要么整批失败，要么应用错误地忽略坏记录并承认总体成功。两种策略都不适合需要持续离线更新的照片库。这里的事务划分先按分类结果切开：A 保存 R01 至 R05 五条有效项；B 保存 R06 至 R09 四条有效项；C 用 R10 至 R12 三条异常项验证“错误批次不公开”。

A、B 的成功只代表本轮模型中的可见快照累积到九条，C 失败后保持九条不动。提交次数是二，回滚次数是一，最终不将整体批次标记为完成，因为仍有三条悬空引用等待数据修复。这种状态设计有意比“成功率 75%”更啰嗦：比率适合图表，不足以驱动后续恢复操作。只有知道哪组被回滚、可见快照属于哪个检查版本，才能避免下一轮重复插入和错误覆盖。

下面是本地业务端口的最小模拟。commitBatch、rollbackBatch 全部是应用自己定义的函数，不是 RelationalStore 的系统接口。一个真实的 RDB 适配器需要将多表写入放入数据库事务，并在提交失败时检查错误和清理资源；这份示例故意不伪造未验证的 API 调用。

class FixtureBatchPort {
  constructor() { this.visible = new Map(); this.commits = 0; this.rollbacks = 0; }
  async commitBatch(name, rows) {
    for (const row of rows) this.visible.set(row.id, row);
    this.commits += 1;
    return { name, count: rows.length, result: 'COMMITTED' };
  }
  async rollbackBatch(name, rows) {
    this.rollbacks += 1;
    return { name, count: rows.length, result: 'ROLLED_BACK' };
  }
}

async function replay(port, valid, orphan) {
  await port.commitBatch('A', valid.slice(0, 5));
  await port.commitBatch('B', valid.slice(5, 9));
  if (orphan.length > 0) await port.rollbackBatch('C', orphan);
  return {
    visibleRows: port.visible.size,
    commitCount: port.commits,
    rollbackCount: port.rollbacks,
    state: orphan.length ? 'INDEX_REPAIR_HOLD' : 'INDEX_READY'
  };
}

这个模型还有一个故意留出的空白：如果 B 的真实数据库提交在写入一半时失败，Map 实现不会自动撤销已经写入的项，因此它只演示批次边界，不具备真实事务的 ACID 特性。若没有数据库层原子保障，不得把这段代码放到生产环境并宣称能处理中断。这正是分开写模型与平台适配的价值：先确认想要的规则，再用经过官方签名验证和设备验证的事务接口实现，而不是把同步 Map 操作当成持久化方案。

五、后续接入 RelationalStore 时要补哪些契约

在 HarmonyOS 应用里，关系型数据持久化应放在业务服务层，不要让每个组件为了刷新卡片列表都重新打开一个数据库实例。页面只关心稳定的快照版本和查询结果，服务层负责上下文、数据库配置、表结构版本、事务与 ResultSet 生命周期。拿到一个 RdbStore 不意味着本轮的数据模型已经拥有事务隔离；需要先确定使用的 API 版本和执行方式，再定义批次提交承诺。

建议为集成端口补足四类错误：库不可用、事务创建失败、写入中断、提交结果未知。前三类可以转为确定失败，最后一类尤其需要幂等批次键防止重入。假设应用在 COMMIT 调用后、收到成功回执前被系统终止，下一次启动不能直接再次插入同一批次。可以先查询批次凭证表：若凭证已存在，使用已提交的可见快照；若不存在，则按事务约定重放。凭证表与业务行必须处于同一数据库事务，否则“凭证成功、数据失败”仍然会制造新问题。

每条引用还要保存可解释的来源。至少有 batchId、refId、photoId、检查版本、处理状态、最后变更序列。这些是建议的业务字段，不是 RelationalStore 或系统媒体库规定的字段。对删除类操作，尤其不能仅凭“缓存里没找到照片”就直接清空历史引用，因为缓存可能未加载完成。只有资源枚举完成、授权状态确认、快照版本一致时，孤儿判断才有资格触发正式的隐藏或删除策略。

把事务当成乐观并发保护也要小心。另一个页面可能在修复期间重新导入相同照片，旧快照仍认为 R10 缺失。这时应检查快照代次，不把旧诊断覆盖新记录。若用户主动清空整个图库，需要不同的、明确授权的操作入口；不能借“孤儿回收”脚本执行全库删除。对外状态 INDEX_REPAIR_HOLD 应持续保留，直到新一轮校验确认缺口得到处理。

在真正落库之前还要确定数据版本迁移的顺序。假设旧版引用表没有 batchId，而新版要增加批次凭证，如果先升级页面查询再升级表结构，某些设备会因为字段缺失直接停止展示。升级脚本应在同一受控阶段完成表结构检测、必要字段增补和旧数据回填，并为历史没有可靠来源的引用设置“待补充来源”，不能拿当前批次编号伪造过去的事实。升级失败应保留旧库与可恢复的备份路径，不能一边弹提示一边继续写入新结构。

对于批量导入，后台任务与前台展示最好共享同一个快照修订号，却不要共享可变数组。后台生成 revision 13 的候选时，前台仍显示 revision 12 的稳定结果；只有提交回执及一致性检查都通过，才允许查询切到新修订号。若第三批 C 回滚，前台可以继续读已经确认的九条，但批次层状态必须保留 HOLD。这样处理的实际价值是避免列表在逐条写入时忽多忽少，尤其适合大量缩略图在低速存储上加载的场景。

索引修复日志还要控制敏感信息。生产环境不应把用户照片的完整私有路径、定位信息和可识别文件名直接写入 HiLog；排障只需经过脱敏的引用标识、批次水位、失败码与时间序列。若未来通过开发者工具导出诊断包，必须限定可读取人员和保留周期，并在用户移除相册授权之后停止采集。完整性治理本身不该成为新的隐私泄露来源。

六、主界面为什么只展示九张缩略图

主界面 RefGalleryPage 显示九张可见样例，诊断页 RefAuditPage 列出 R10、R11、R12。这样分层可以让内容使用与故障定位互不干扰。用户看到的是经过当前业务校验的资源列表，维护者查看的是候选、有效、孤儿、批次提交和回滚的完整关系。页面上标注 FIXTURE_ONLY 和 RDB_REAL NOT_RUN，目的是阻止观者误把演示页面当成真实数据库已经修复的证据。

固定数据展示：候选十二条，有效九条，孤儿三条；A 提交五条，B 提交四条，C 回滚三条；提交次数二、回滚次数一，最后可见九条。当前显示的 R01 至 R09 采用风景样例图，只用于辅助理解信息结构，并不是从某台设备相册取得的截图。图里的数量来自同一份合同，不因页面换成九宫格就改变统计口径。

开发环境图是根据项目目录与模型代码生成的 DevEco Studio 风格示意图，右侧模拟器和底部 HiLog 同样是设计展示，不是编译器实际打开的工作区。能够从示意图读出类和按钮的关系，却不能由它证明 TypeScript 已经通过 ArkTS 静态检查。尤其图片里没有展示完整的数据库适配器，不能用 UI 上的 COMMIT 文案反推关系型数据库真的持久化了九条数据。

一个值得保留的微小差别是“可见九条”与“已提交九条”在本模型里恰好相等，但一般不应绑定成恒等式。正式产品可能因为隐私级别、用户筛选条件或者缩略图临时授权缺失，只把部分已提交项展示出来。建议把可见条件放在独立的查询视图中，避免业务规则被页面渲染结果反向定义。

七、模型验收不要只跑一次绿灯

本轮的最低检查不是“程序有没有报错”，而是固定集合重复执行后是否得到相同分类，以及遇到异常是否保持既有可见快照。测试先造出 P001 至 P012 的十二条素材清单记录，以及十二条检索引用；其中九条可解析，另外三条指向 P999、P1000、P1001，再执行分类、分组与状态计算。模型验证可以在 Node.js 执行，不需要假装已经安装 HarmonyOS 模拟器。

import assert from 'node:assert/strict';
const photos = Array.from({ length: 12 }, (_, i) => ({ id: `P${String(i + 1).padStart(3, '0')}` }));
const refs = Array.from({ length: 12 }, (_, i) => ({
  id: `R${String(i + 1).padStart(2, '0')}`,
  photoId: i < 9 ? photos[i].id : `P${999 + i - 9}`
}));
const known = new Set(photos.map(p => p.id));
const valid = refs.filter(r => known.has(r.photoId));
const orphan = refs.filter(r => !known.has(r.photoId));
assert.equal(valid.length, 9);
assert.deepEqual(orphan.map(r => r.id), ['R10', 'R11', 'R12']);
const port = new FixtureBatchPort();
const result = await replay(port, valid, orphan);
assert.deepEqual(result, {
  visibleRows: 9, commitCount: 2, rollbackCount: 1,
  state: 'INDEX_REPAIR_HOLD'
});

这组断言覆盖了分类数量、异常身份和批次结果，却没有覆盖数据库磁盘损坏、磁盘空间不足、事务锁等待或并发写冲突。准备接入真库时，还要为每种错误建立可注入的测试案例，特别验证 COMMIT 结果未知与应用重启之后的补偿。所有事务故障不能仅用 try/catch 后刷新 UI 就结束：错误状态必须可恢复、可追踪，也不能让用户误以为索引变更已经落盘。

本地演示日志约定在 2026-10-11 02:41 这一窗口内输出：02:41:11 加载，02:41:12 分类，02:41:13 提交 A，02:41:14 提交 B，02:41:15 回滚 C，02:41:16 进入 HOLD。它们是预先设定的诊断序列，而不是系统 HiLog 实测时间。正式运行时应采用设备真实时钟并附上单调事件序列，不能只依赖墙上时间判断前后因果。

八、资源释放、页面退出与恢复边界

若未来引用表需要从真实相册扫描生成，流程将同时持有资源游标、可能的图片源和数据库对象。每个对象应有明确释放点：枚举结束关闭结果集，缩略图解码使用后按 Image Kit 生命周期释放，数据库连接则由服务层统一管理。不要因为页面从前台退出就贸然关闭仍被其他页面共享的存储实例，也不能在后台继续偷偷扩大用户授权范围。

在页面生命周期里，最危险的是回调次序被误当成逻辑次序。用户切换到另一个相册，旧的修复扫描可能稍晚返回。如果没有批次代次隔离，旧页面结果就会覆盖新的可见列表。推荐业务层维持 currentBatchId 与 snapshotRevision，返回前检查两者仍匹配。页面销毁后只更新可靠的持久化进度，不再向已销毁组件发送列表变更。异常时要区分可以重试的批次故障和必须由用户明确处理的资源删除。

还需要考虑修复动作的可撤销性。将孤儿直接物理删除虽然简单，却会失去排障证据。更合理的策略是先逻辑隔离，记录原因和校验版本，经过保留期或用户确认后再执行不可逆清理。对于学校、企业展陈或素材管理系统，长期留存引用异常日志还有助于检查资源迁移工具的质量。这种治理收益来自可观察的状态记录，不来自把九张图片摆得更整齐。

九、当前结论只属于业务层

这轮模型得到九条有效、三条孤儿、两次模拟提交、一次模拟回滚，输出 INDEX_REPAIR_HOLD。它证明业务判定的输入输出合同可以写清楚、复核清楚；它不能证明 RelationalStore 的事务接口在某个 SDK 版本中已经按此代码运行，也不能证明真实文搜图索引与系统照片授权已完成一致性修复。

下一步应先核对所使用的 HarmonyOS SDK 与 ArkData 官方关系型数据库文档，确认 RdbStore 的事务类型、ResultSet 关闭方式和错误处理，再把目前的 FixtureBatchPort 替换成真实适配器。之后补应用终止恢复、重复批次幂等、资源授权变化和真机并发写入的验证矩阵。只有这些证据齐全，才能把状态从 INDEX_REPAIR_HOLD 推进到真正的 INDEX_READY。对于内容创作而言，保留这条边界比写一句“已成功修复”更有价值。

官方资料：华为 ArkData 关系型数据库开发文档中心，及 2026-09-23 更新的 LiteResultSet 参考页（https://developer.huawei.com/consumer/cn/doc/doccenter-references/api/arkts-apis-data-relationalstore-literesultset）。本轮未核对完整的 RdbStore 事务签名，因此不把示例端口写成系统方法。