【HarmonyOS 7新能力｜029】3DGS工程封装：把接入逻辑放进可维护的分层结构
3DGS（3D Gaussian Splatting）让多视角图像重建和新视角渲染有了更灵活的表达方式，但工程难点远不止“调用一次重建”。拍摄覆盖不足、模糊帧进入计算、相机位姿失败、资源峰值过高、应用退到后台后仍继续优化，都会让结果不可用。
本文把端侧三维重建拆成采集交互、会话、数据治理、重建编排、资源和呈现六层。文中的类型、阶段与策略是应用侧教学封装，不代表 HarmonyOS 7 官方 3DGS API、算法实现或性能指标；能力范围、硬件条件和接口应以当前 SDK 与华为官方资料为准。图片中的质量数值均为设计示意，不是实测结论。
一、先定义可交付的重建目标
“把物体变成 3D”无法直接验收。第一版应限定对象大小、拍摄距离、环境光、输出用途与最低完整性。例如仅支持静态小型物体，输出用于本机预览，不承诺精密测量，也不处理透明和强反光表面。
验收目标包括：用户获得覆盖引导；明显模糊帧被拒绝；位姿异常时停止并提示补拍；任务可取消；资源超过预算时降级或失败；结果通过完整性检查后才进入预览；原始图像默认不上传。
二、把采集计划变成显式数据
采集不是随手拍一圈。应用应描述目标、推荐视角、已覆盖区域和缺口，形成可恢复的会话。
interface CapturePlan { sessionId: string targetName: string expectedViews: number elevationBands: ReadonlyArray<'low' | 'middle' | 'high'> minOverlap: number } interface CaptureProgress { acceptedFrames: number rejectedFrames: number missingBands: ReadonlyArray<string> }expectedViews和重叠阈值只是产品策略，需根据目标设备与算法实测确定，不能当成通用标准。
三、每张图像都绑定可信元数据
图像需要与拍摄时间、方向、尺寸、焦距信息和会话版本关联。只保存文件路径，后续很难判断它属于哪一次采集或是否已经过旋转。
interface CaptureFrame { id: string sessionId: string revision: number width: number height: number rotation: 0 | 90 | 180 | 270 capturedAt: number localUri: string }元数据进入清单，重建任务读取不可变快照。用户补拍后生成新 revision，旧任务的迟到结果不能覆盖新任务。
四、帧质量门禁早于重建
模糊、曝光异常、重复视角和缺少纹理的帧应在重建前识别。质量门禁不需要替代算法，只负责淘汰明确无效输入并给出可操作反馈。
interface FrameQuality { frameId: string sharpness: number exposure: 'low' | 'normal' | 'high' duplicateOf?: string accepted: boolean reasons: ReadonlyArray<string> } function canUse(q: FrameQuality): boolean { return q.accepted && q.exposure === 'normal' && q.duplicateOf === undefined }阈值由目标设备样本标定，并保留人工复核入口，避免算法误判后用户无法继续。
五、重建流程采用阶段状态机
重建包含输入冻结、位姿估计、初始化、优化、验证和导出。把它压成一个loading会导致取消和恢复无从落地。
type ReconstructionStage = | 'preparing' | 'estimating-pose' | 'initializing' | 'optimizing' | 'validating' | 'completed' | 'failed' | 'cancelled' interface ReconstructionJob { id: string revision: number stage: ReconstructionStage progress: number checkpointUri?: string }只有验证通过才能进入 completed。取消是终态，后台回调只能清理资源，不能偷偷恢复执行。
六、分层结构隔离算法变化
采集层提供引导和覆盖反馈；会话层管理状态、取消和进度；数据治理层处理筛帧、元数据与隐私；编排层组织位姿、初始化和优化；资源层控制内存、温控与持久化；呈现层只消费稳定输出。
页面不直接持有重建引擎对象，算法适配器也不修改 UI。未来更换模型或增加云端备选时，业务会话和验收规则仍可复用。
七、算法接入收口为窄接口
interface ReconstructionInput { jobId: string manifestUri: string outputDirectory: string } interface ReconstructionArtifact { sceneUri: string metadataUri: string previewUri: string } interface ReconstructionPort { run(input: ReconstructionInput, signal: AbortSignal): Promise<ReconstructionArtifact> release(): Promise<void> }适配器把平台错误映射为有限错误码，确保失败时关闭句柄、释放加速资源和临时缓冲区。
八、资源预算是运行时门禁
端侧优化可能持续占用内存、算力和电量。启动前检查可用存储与设备状态，运行中监控内存峰值、温度等级和应用可见性。
interface ResourceBudget { maxMemoryBytes: number maxTemporaryBytes: number maxElapsedMs: number allowBackground: boolean } function deadlineExceeded(startedAt: number, budget: ResourceBudget): boolean { return Date.now() - startedAt >= budget.maxElapsedMs }触发预算后应保存安全检查点、降级或明确失败，不能依靠系统强杀来结束。
九、检查点只保存可恢复状态
并非每个内部缓冲区都适合持久化。检查点应包含算法版本、输入清单摘要、阶段、必要参数和已验证的中间产物引用。
interface JobCheckpoint { jobId: string algorithmVersion: string manifestDigest: string stage: ReconstructionStage artifactUris: ReadonlyArray<string> savedAt: number }恢复前核对版本和输入摘要。不匹配时从安全阶段重新开始，避免把旧中间结果套到新图片上。
十、结果质量需要多维验收
是否能打开预览不是质量通过。至少检查输入覆盖、位姿有效比例、空洞区域、异常漂浮点、目标外区域和多个保留视角的重投影表现。
interface QualityReport { validPoseRatio: number uncoveredRegions: ReadonlyArray<string> artifactWarnings: ReadonlyArray<string> holdoutChecksPassed: boolean status: 'passed' | 'needs-more-capture' | 'failed' }阈值必须来自产品场景和设备实验。报告应允许返回“需要补采”，而不是强行给出成功模型。
十一、隐私和数据保留必须显式
环绕拍摄可能带入人脸、室内环境和文档。默认在本地处理，采集前提示用户清理敏感背景；原始图像、临时文件、检查点和最终模型分别定义保留期限与删除入口。
interface RetentionPolicy { keepSourceFrames: boolean deleteTemporaryOnSuccess: boolean deleteTemporaryOnCancel: boolean exportRequiresConfirmation: boolean }日志只记录任务号、阶段、耗时、错误码和资源指标，不记录图片内容与精确环境信息。
十二、用故障注入完成验收
测试覆盖：覆盖不足、连续重复视角、模糊帧、旋转元数据错误、位姿失败、用户中途补拍、任务取消、应用退后台、存储耗尽、内存预算触发、温控降级、检查点版本不匹配、导出失败和删除流程。
还要连续运行多轮任务，确认句柄、内存和临时目录回到基线；对同一输入重复执行时，阶段与报告可复现。只有正常与失败链路都能安全收束，才说明工程封装完整。
3DGS 的体验上限由算法决定，交付下限却由工程边界决定。把采集质量、状态机、算法适配、资源预算、检查点、质量报告和隐私清理纳入同一链路，端侧三维重建才能从一次炫酷演示变成可维护的产品能力。
十三、接入前检查清单
3DGS工程封装：把接入正式接入前，工程侧要过一遍检查清单：SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停，带着不匹配的版本往上冲，排错成本会翻倍。
interface PrecheckItem { name: string; pass: boolean; note?: string } const checklist: PrecheckItem[] = [ { name: 'SDK/API版本匹配', pass: false }, { name: '权限声明完整', pass: false }, { name: '开关集中管理', pass: false }, { name: '包体积增量<预算', pass: false }, ] const allPass = checklist.every(x => x.pass)检查清单跑通的标志是：新建工程按清单接入一次成功，且不依赖任何口头经验。做不到，说明文档还缺关键步骤。
十四、常见坑与版本适配记录
3DGS工程封装：把接入最常踩的坑集中在三处：示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表，注明坑点、影响版本、修复方式与验证方式。
interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] } const pitfalls: Pitfall[] = [] function knownPit(api: string): Pitfall[] { return pitfalls.filter(p => p.sinceApi === api) }适配表的价值在升级时兑现：每次目标版本变更，先对照表过一遍已知坑，能省下一整轮盲目排查。
十五、回归口径与停止线
3DGS工程封装：把接入的任何改动合入前都要回答同一个问题：怎么证明没有把好的部分改坏。回归口径必须落在纸面：上一版通过的用例清单全量重跑、上一版记录的基线值全量对比、新增能力补一条专属用例。三件事缺一件，回归就是走过场。
interface RegressionGate { lastPassedCases: number; rerun: number; baselineCompare: 'PASS' | 'FAIL'; newCaseAdded: boolean } function gateOk(g: RegressionGate): boolean { return g.rerun === g.lastPassedCases && g.baselineCompare === 'PASS' && g.newCaseAdded }停止线同样要提前写明：同一问题打回三次、回归连挂两轮、或验证环境与目标环境指纹不一致，满足其一就停下来复盘流程，而不是继续硬修。把停止线当成流程的一部分，才能避免在小问题上耗掉整块的排期。
