Demo：ReconAudit｜批次：GS-726｜技术链：Node.js 文件系统 → 采集清单预检 → HarmonyOS 报告展示
说明：本文中的任务、图片和日志均为可复现的预设演示数据，并非真实设备拍摄、端侧重建成功或官方审核结果。

一、三维重建之前，先确认输入是否完整

一组用于3DGS的候选帧，通常会先经历采集、整理、筛查，之后才进入真正的重建链路。这个过程中，有个容易被忽略的交付边界：目录里能看到图片，并不等于下游拿到的是一组完整且有顺序的输入。重命名中断、同步软件跳过某个文件、复制时出现零字节文件，都可能让“已经准备好”的状态变得不可信。

本文专门把问题缩小到重建前的清单门禁。不讨论3DGS的训练参数，也不假定某一款终端可以直接完成重建。Demo叫ReconAudit，批次号固定为GS-726，清单要求frame_001.jpg到frame_024.jpg共24个文件。预设目录中实际有23个非空文件，缺少frame_017.jpg。业务期望不是让用户看到一个漂亮的进度条，而是明确显示“检查完成、重建未启动、输入被阻断”。

华为开发者平台确实提供3DGS端侧重建和相关空间计算资料，但采集质量、支持设备、SDK能力边界必须以具体方案和目标版本的官方说明为准。这里的Node.js程序只是开发者自建的素材准备工具，不是华为Spatial Reconstruction Kit接口；把两者区分开，文章才不会把本地文件检查包装成已完成三维重建。

1. 把三种状态分开

第一种是“目录扫描完成”：程序已经对预期序列逐个检查。第二种是“输入满足门禁”：文件名连续、没有清单重复项、实际文件存在且字节数大于零。第三种才是“业务可进入重建”。本例只负责前两种；达到READY只能表示通过当前文件级门禁，并不能证明照片清晰、视角覆盖充分或者图像内容有效。

这也是为什么在手机报告预览页里，进度应写“24/24项检查完成”，有效数据写“23/24个文件通过”，状态写BLOCKED。把检查进度100%误当成重建进度100%，会让后续排查几乎没有方向。

二、先约束输入，再判断文件

1. 统一命名，不用数组下标猜业务ID

清单最小字段只有batchId、expectedCount、frames。frames列出24个预期名称，文件名采用固定宽度序号。需要提醒的是，文件名连续只是项目定义的业务约束，并非3DGS SDK强制规定的命名格式。项目若使用时间戳或相机位姿索引，也应该换成自己的显式主键规则。

下面一段代码解决“如何区分清单重复、物理缺失、空文件”的问题。它不尝试打开图片解码，因此不会把非空但内容损坏的文件误报为已通过完整图像验证。

// tools/inspect.mjs —— 自定义业务门禁，不是系统重建API
import { existsSync, statSync } from 'node:fs';
import { join } from 'node:path';

export function inspectBatch(dir, manifest) {
  const declared = new Set();
  const duplicates = [];
  for (const name of manifest.frames) {
    if (declared.has(name)) duplicates.push(name);
    declared.add(name);
  }
  const missing = [], empty = [];
  let present = 0;
  for (let i = 1; i <= manifest.expectedCount; i++) {
    const name = `frame_${String(i).padStart(3, '0')}.jpg`;
    const path = join(dir, name);
    if (!declared.has(name) || !existsSync(path)) {
      missing.push(name);
    } else if (!statSync(path).isFile() || statSync(path).size === 0) {
      empty.push(name);
    } else {
      present++;
    }
  }
  const issues = [...missing, ...empty, ...duplicates];
  return { batchId: manifest.batchId, expected: manifest.expectedCount,
    present, missing, empty, duplicates,
    state: issues.length ? 'BLOCKED' : 'READY' };
}

这里的present表示“存在且非空的预期文件数”，它并不是照片帧质量的评分。Set只用来做名称比对和重复检查，不能靠index在UI里映射真实帧ID。即使用户后来补上传缺失的第17帧，也应该重新运行扫描，而不是在旧报告上手工加一。

异常边界同样要说明：statSync可能因为权限或文件系统变化抛错，生产代码应在单文件级捕获并归入unreadable，不能简单当成缺失。此处示例刻意保持短小，适合无并发修改的演示目录；对持续写入的采集目录，门禁前还应等待采集结束并锁定输入版本。

2. 失败要能留下报告，成功才允许下游继续

下游最怕含糊的返回值。把state写入固定的报告文件，构建任务就可以根据退出码决定是否继续。下面代码解决“错误清单如何阻断流水线，但仍留下可供人工查看的原因”的问题。它只操作本地项目目录，没有移动、覆盖或删除用户媒体文件。

// tools/preflight.mjs
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
import { inspectBatch } from './inspect.mjs';

const root = process.argv[2] ?? './fixtures/GS-726';
const manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'));
const report = inspectBatch(join(root, 'frames'), manifest);
mkdirSync(join(root, 'reports'), { recursive: true });
writeFileSync(join(root, 'reports', 'GS-726.json'),
  JSON.stringify(report, null, 2), 'utf8');
console.info(`GS-726 CHECKED 24/24 present=${report.present}`);
if (report.state !== 'READY') {
  console.error(`GS-726 MISSING ${report.missing.join(',')}`);
  console.error(`GS-726 BLOCKED; reconstruction NOT_RUN`);
  process.exitCode = 2;
}

process.exitCode=2是本项目自定义的流水线约定，并不是HarmonyOS系统错误码。程序先持久化报告，再给出阻断状态，所以失败场景仍然保留证据。若未来接入Hvigor或CI，必须在上一级流程显式判断该退出码；单独执行脚本不会自动拦截应用市场的发布动作。

这里也没有把写入说成“原子提交”。writeFileSync同步返回不意味着突然断电时一定保有完整旧版本。正式项目若要强保证，应引入临时文件、校验和及明确恢复流程，并对不同设备或文件系统的替换语义单独验证。

三、报告如何在HarmonyOS页面中可读

1. 展示的是预检快照，不是手机端执行Node

报告预览页面名为AuditPage.ets。它可以由打包的演示JSON或受控服务下发数据驱动，但手机本身不应被描绘成自动运行上述Node.js脚本，更不要把模拟器中的按钮写成调用了官方3DGS重建接口。下面的ArkTS示意代码只描述显示层的数据契约，解决“检查进度和可进入重建的状态不要混成一行”的问题。

// entry/src/main/ets/pages/AuditPage.ets
interface AuditViewModel {
  batchId: string;
  checked: string;
  present: string;
  missing: string;
  state: string;
}
@Entry
@Component
struct AuditPage {
  @State report: AuditViewModel = {
    batchId: 'GS-726', checked: '24/24', present: '23/24',
    missing: 'frame_017.jpg', state: 'BLOCKED'
  };
  build() {
    Column({ space: 18 }) {
      Text('3DGS采集清单门禁').fontSize(25).fontWeight(FontWeight.Bold)
      Text(`批次 ${this.report.batchId}`)
      Text(`扫描进度 ${this.report.checked}`)
      Text(`有效文件 ${this.report.present}`)
      Text(`缺失文件 ${this.report.missing}`)
      Text(`状态 ${this.report.state}`).fontColor(Color.Red)
      Text('重建未启动 · 补齐文件后重新检查')
    }.width('100%').padding(22)
  }
}

@State在此负责页面响应式刷新，没有打开图片句柄，自然也不存在需要release()的ImageSource。实际从异步接口加载报告时，应在页面退出后忽略迟到回调，在aboutToDisappear清理自建监听；若报告来源是下载文件，要验证它与当前batchId匹配，防止上一轮结果覆盖新的采集会话。

DevEco风格图片里的左侧工程目录、中心代码、右侧模拟器以及底部HiLog均为本文预设的演示界面。右侧只显示GS-726的报告结果，BLOCKED与脚本出口保持一致；底部日志内容同样是示例文案，不是已执行过真机采集的证据。

四、用失败场景反推验收口径

预设目录中有24条清单声明，文件系统上却只有23个非空文件。演示工具读取后，结果应为expected=24、present=23、missing=[frame_017.jpg]、state=BLOCKED。此时检查项本身已经走完，重建调用仍应明确标记NOT_RUN。这组数据可以在本地用Node.js伪造安全的文件夹结构来测试脚本分支，但不能据此宣称相机视角足够或者模型质量通过。

值得覆盖的另一类场景是存在frame_017.jpg，却是零字节文件：missing应为空，empty应包含它，整个批次仍为BLOCKED。再补一类是清单里写了两次同一名称：即使目录文件都存在，也不能用“24个文件”掩盖重复声明。这三个条件尽管表现形式不同，都必须在报告中保留原始原因。

手机纯屏配图固定展示GS-726、23/24、frame_017.jpg和BLOCKED。页面中的进度24/24只表示门禁扫描已结束，它与“有效文件数量”不能互换。演示时间用于画面一致性，不计入处理性能，也不意味着成功启动过重建任务。

五、工程边界：门禁不应抢SDK的工作

这个方案有意不检查相机外参、图像曝光、运动模糊、重复视角和相邻帧重叠率。它们属于后续采集质量审查或具体重建算法的输入要求。文件大小大于零也不能证明JPEG可正常解码；若产品确实需要，可另加受限解码校验，并明确CPU、内存和异常图片的安全上限。

清单层建议至少保存采集批次、原始顺序、校验时间、工具版本、问题文件和阻断原因。报告需要可重复生成，不能把“执行了一次”写成“问题一定消失”。对用户可见的恢复入口应当是“补齐或重新选择素材，再运行预检”，而不是跳过提醒继续提交重建。

我更看重这层门禁的意义：把“不知道为何失败”尽可能提前变成“知道是哪个输入没有准备好”。技术方案小，但能减少把数据问题错误归因给模型或系统API的机会。是否能真正提升重建成功率，需要在有权限、符合官方能力边界的目标工程里另做测量，本文不对此给出虚构数字。

官方核对入口： 华为HarmonyOS空间计算与3DGS特性介绍：https://developer.huawei.com/consumer/cn/features/spatialization ；3DGS重建流水线说明：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/spatial-recon-c-spatial-recon-pipeline 。Node.js node:fs接口应以Node.js对应运行时的官方文档核对：https://nodejs.org/api/fs.html 。