前言有按钮不等于流程已经验证M4 异常闭环包含登记、调机、复核、模板确认和关闭多个阶段。页面可以渲染出按钮Repository 也可以写出状态但如果没有明确的操作步骤、预期结果和运行证据文章很难回答一个实际问题这条流程到底在哪一步被验证过本篇不新增业务字段而是对当前已经实现的异常模块做验证收束。重点使用项目中已有的M4 异常列表布局树。M4 异常详情布局树。登记页布局树。登记后详情截图。关闭被阻止截图。M2.1 测试报告中的 M4 补充用例。ExceptionList.ets、ExceptionDetail.ets和DemoBusinessRepository.ets源码。文章会把“运行观察”“布局树证据”“源码逻辑”和“尚未专项截图的结论”分开。这样做的目的是让人工审稿和开发排错都能准确追溯。一、先定义 M4 需要证明的结果当前异常状态模型包含exporttypeExceptionStatusopen|debugging|verifying|template_pending|closed;M4 测试至少要证明下面几类结果验证对象需要证明的结果异常列表能显示已有异常并提供登记入口异常详情能打开指定异常并显示状态、批次和关联调机入口异常登记标题输入存在提交后创建异常和草稿调机记录关闭门禁关联调机记录未提交时不能直接关闭状态模型页面文案与 Repository 中的状态枚举一致证据链每个结论能对应截图、布局树、测试报告或源码这些目标不等于“所有 M4 状态都分别截图”。当前材料对登记页和未提交关闭场景有运行证据对部分状态推进主要使用源码审查。证据强度必须如实标注。二、测试环境必须写清编译和运行 API项目测试报告使用的环境是编译DevEco Studio Beta 26.0.0.461 编译 APIHarmonyOS API 26 Beta1 运行设备HarmonyOS API 24 模拟器 127.0.0.1:12024 包名com.atan.enotebook这里有两个 API 版本API 26 Beta1 是工程构建环境。API 24 是页面运行观察环境。文章标题中的 API 24 对应运行验证口径不能写成“使用 API 24 SDK 完成编译”。如果不写清楚读者可能会把构建失败和运行兼容性混成同一个问题。三、先确认异常页签入口Index.ets中的异常页签装配}elseif(this.selectedTabexceptions){ExceptionList({onOpen:(exceptionId:string)this.openDetail(exception,exceptionId),onCreate:()this.openDetail(exception,new)}).layoutWeight(1)}列表进入详情的关键不是把整个对象传给子组件而是传递稳定的异常 IDonOpen:(exceptionId:string)this.openDetail(exception,exceptionId)这样详情页出现时可以重新通过 Repository 查询最新对象减少列表快照和详情对象之间的状态分叉。四、M4-T01打开异常列表和 EX-241项目测试报告中的 M4-T01 是打开“异常”页签和 EX-241预期结果页面显示“异常管理”。页面显示“登记异常”入口。页面显示异常列表卡片。EX-241 卡片显示标题、状态和批次。点击卡片可以进入异常详情。ExceptionList.ets的当前实现Scroll(){Column({space:14}){Row(){Text(异常管理)Blank()Button(登记异常).onClick(()this.onCreate())}Text(登记、调机、复核、模板确认和关闭均围绕同一异常编号完成。)ForEach(demoBusinessRepository.loadExceptions(),(item:ExceptionRecord){Button(${item.id}·${item.title}\n${item.statusLabel()}·${item.batchId}).onClick(()this.onOpen(item.id))},(item:ExceptionRecord)item.id)}}这里的 key 使用item.id而不是状态文案或数组序号。异常状态变化后ArkUI 仍然能识别同一条记录。五、列表布局树证明了哪些内容M4 列表布局树是document_claude/20260723_功能开发_M2至M6业务闭环/测试文件/m4-list.json从布局树中可以提取出节点运行文本页面标题异常管理创建按钮登记异常说明文字登记、调机、复核、模板确认和关闭均围绕同一异常编号完成。第一张异常卡片EX-241 · 短射复核 / 待处理 · 20260719-A07第二张异常卡片EX-238 · 飞边处理 / 待模板确认 · 20260720-A03布局树证明的是控件和文字确实出现在运行页面中。它不能单独证明点击卡片后详情页的数据保存逻辑需要和详情源码、Repository 代码及后续截图结合。六、为什么截图和布局树要同时保留截图适合回答用户实际看到的页面是什么样布局树适合回答页面有哪些可定位的控件、文本和 bounds两者互补证据优点局限JPEG 截图直观展示视觉结果不容易精确检索控件文本和坐标JSON 布局树可检索文本、类型和 bounds看不出完整视觉层次和颜色效果源码能解释行为和状态规则不能证明运行时页面一定出现测试报告记录操作和结论需要依赖具体证据文件文章在写运行结论时应该尽量把四者关联起来。七、M4-T02未提交调机记录时关闭被阻止测试报告中的 M4-T02未提交关联调机记录时直接关闭 EX-241预期结果关闭被阻止提示“请先提交关联调机记录”对应证据m4-close-blocked.json m4-close-blocked.jpeg这条用例是 M4 重要的边界测试因为它证明页面虽然有“关闭异常”按钮但业务层不会允许状态越级。八、关闭门禁的实际代码DemoBusinessRepository.canCloseException()先查异常对象再查关联调机记录canCloseException(exceptionId:string):string{constexception:ExceptionRecord|undefinedthis.exceptionById(exceptionId);if(exceptionundefined)return未找到异常记录。;constdebug:DebugRecord|undefinedthis.debugById(exception.debugRecordId);if(debugundefined||(debug.status!submitteddebug.status!approved)){return请先提交关联调机记录。;}if(!exception.verificationPassed){return请先完成稳定性复核。;}if(exception.disposition.trim().length0){return请先记录异常品处置结果。;}if(exception.templateDecisionpending){return请先应用模板或明确不更新模板。;}return;}检查顺序有现场意义先提示最前面的缺口用户补齐调机提交后下一次点击才会进入复核、处置和模板门禁。九、关闭动作为什么要调用同一个门禁详情页关闭方法很薄privateclose():void{constreason:stringdemoBusinessRepository.closeException(this.exceptionId);this.feedbackreason.length0?异常已关闭。:reason;}真正的状态修改在 RepositorycloseException(exceptionId:string):string{constreason:stringthis.canCloseException(exceptionId);if(reason.length0)returnreason;constexception:ExceptionRecord|undefinedthis.exceptionById(exceptionId);if(exception!undefined)exception.statusclosed;this.notifyStateChanged();return;}页面负责反馈Repository 负责条件和状态。未来增加列表快捷关闭或后台动作时也可以复用同一个门禁。十、关闭阻止截图能证明什么这张图可以证明异常详情页面确实运行出来。页面存在关闭动作入口。当前操作得到明确阻止反馈。反馈内容与canCloseException()的第一道条件一致。它不能证明处置结果保存成功、复核通过、模板已经应用或异常在其他数据状态下可以关闭。一张截图只证明截图中的状态。十一、M4-T03打开登记异常页面测试报告中的 M4-T03打开“登记异常”并输入异常标题预期结果显示登记表单与异常标题输入。提交时创建同一异常编号下的草稿调机记录。详情页可以继续打开关联调机记录。对应证据m4-registration-form.json ExceptionDetail.ets DemoBusinessRepository.registerException() 提交 7b592b6十二、登记页布局树的定位信息登记页布局树记录了关键控件类型运行文本或 hint作用Button返回异常列表返回列表Text登记异常页面标题Text登记后自动创建同一异常编号下的草稿调机记录……说明业务关系Text异常标题字段标签TextInput例如外观银纹复核输入异常标题Button登记并进入处置提交登记动作布局树中的输入框和按钮都有 bounds可以用于确认 API 24 设备上控件没有被底部导航遮挡也没有因为页面内容变化而消失。十三、登记和关闭是两个独立用例登记成功只说明ExceptionRecord 已创建 DebugRecord 已创建状态为 draft 页面进入新异常详情它不说明调机记录已经 submitted、复核已经通过、模板决定已经明确或异常已经 closed。测试报告把 M4-T03 和 M4-T02 分开是正确的测试设计。一个测试用例只验证一个动作链路便于定位失败原因。十四、登记后详情截图登记后详情截图对应布局树document_claude/20260723_功能开发_M2至M6业务闭环/测试文件/m4-registered-detail.json这张截图可以证明登记后页面已经从new表单进入真实异常详情。关联对象是否双向正确还需要结合registerException()的源码审查。十五、登记方法的测试审查点registerException()的关键逻辑registerException(title:string):ExceptionRecord|undefined{constnormalizedTitle:stringtitle.trim();if(normalizedTitle.length0)returnundefined;constsequence:numberthis.exceptions.filter((item:ExceptionRecord)item.id.startsWith(EX-NEW-)).length1;constexceptionId:stringEX-NEW-${sequence.toString().padStart(3,0)};constdebugId:stringDBG-NEW-${sequence.toString().padStart(3,0)};// 创建异常和关联草稿调机记录}测试审查点包括空标题返回undefined。标题会清理首尾空白。两个 ID 使用同一序号。新异常状态是open。新调机记录状态是draft。两个对象都加入 Repository 集合。页面回调使用新异常 ID。十六、测试证据的强弱分级A 级运行截图和布局树共同存在例如异常列表、登记页、关闭阻止页面。可以写成“API 24 运行中观察到”。B 级运行布局树或截图单独存在可以证明页面节点或视觉结果但要少写一步行为结论。C 级源码和测试报告支持可以写成“源码逻辑和测试记录支持”不能写成“截图已经证明”。D 级设计推断或未来建议只能写成“建议”“后续可补充”不能放进当前完成清单。当前 M4 的登记页和关闭阻止属于 A 级或接近 A 级证据复核保存专项截图属于尚未独立提供的证据。十七、为什么不能只看源码判定页面完成源码中存在Button(登记并进入处置)只能说明组件声明了这个按钮。要判定页面运行完成还要观察页面是否能进入、按钮是否可见、输入框是否位于可视区域、底部导航是否覆盖页面以及点击后是否进入真实详情。这就是运行布局树和截图的价值。代码是必要证据但不是全部证据。十八、为什么不能只看截图判定业务完成截图中的“异常已关闭”文字如果出现也还要确认真实对象状态是否变成closed。关闭是否经过canCloseException()。关联调机记录是否满足条件。处置、复核和模板决定是否已保存。截图是观察结果Repository 是业务规则。两者需要互相验证。十九、M4 测试中的状态转移表当前代码可以整理为当前状态或条件动作结果登记模式输入有效标题并提交创建open异常和draft调机记录open提交关联调机记录进入verifyingverifying保存复核未通过保持verifyingverifying保存复核通过进入template_pendingtemplate_pending模板决定仍为 pending关闭被阻止全部关闭条件满足点击关闭进入closed这个表比“点击按钮后状态变化”的描述更适合测试因为每一行都有前置状态、动作和预期结果。二十、边界测试空标题登记页面的空标题测试输入空字符串、空格、换行或制表符 预期提示“请填写异常标题后再登记”同时检查异常列表没有新增记录。调机列表没有新增草稿。页面仍然停留在登记模式。onRegistered没有被调用。只观察提示文字还不够因为可能存在“提示显示了但对象已经创建”的半失败状态。二十一、边界测试不存在的异常 ID详情页通过privateexists():boolean{returndemoBusinessRepository.exceptionById(this.exceptionId)!undefined;}处理不存在对象。预期页面只显示未找到异常记录 返回异常列表不应显示保存、复核和关闭操作。安全占位对象只保证渲染不崩溃不能代表可以执行真实业务动作。二十二、边界测试关联调机记录不存在关闭门禁先调用this.debugById(exception.debugRecordId)如果找不到关联调机记录应该返回请先提交关联调机记录。这个结果比直接抛出空指针异常更适合现场页面也提醒开发者检查异常和调机对象之间的双向关联。二十三、边界测试复核未通过准备一个关联调机记录已提交、但复核未通过的异常字段测试值debug.statussubmittedexception.verificationPassedfalse点击关闭时预期请先完成稳定性复核。这条用例证明“调机提交”已经完成但复核仍然是独立门禁。二十四、边界测试处置结果为空准备一个调机已提交、复核已通过、模板决定已明确但处置结果为空的异常字段测试值debug.statussubmittedverificationPassedtruetemplateDecisionapplied或not_requireddisposition空字符串关闭时预期请先记录异常品处置结果。当前保存方法允许保存空摘要但关闭门禁不会放过空摘要。测试要把这两个行为写清楚。二十五、边界测试模板决定 pending准备一个调机已提交、复核已通过、处置结果非空、模板决定仍为 pending 的异常字段测试值debug.statussubmittedverificationPassedtruedisposition非空templateDecisionpending关闭时预期请先应用模板或明确不更新模板。这样可以确认关闭条件没有把复核通过误认为模板决定完成。二十六、测试用例不应该互相污染本地 Repository 使用内存数组。一个测试如果登记了新异常后面的测试可能看到新增对象。测试执行前应该demoBusinessRepository.resetDemoData();当前工程提供了重置演示数据的方法。虽然测试报告主要记录运行观察和源码审查但状态性测试需要可重复的初始数据。二十七、状态通知不是测试通过标记Repository 更新对象后调用this.notifyStateChanged();这只是通知页面状态变化。测试仍然需要观察实际字段、页面文案或布局树不能因为通知被调用就判定业务动作通过。如果通知遗漏可能出现对象已更新、页面仍显示旧状态的情况如果对象没有更新通知调用也不能让错误数据变正确。二十九、测试报告中的结论边界当前测试报告明确写出M4 的关闭校验由 DemoBusinessRepository.canCloseException() 执行页面无法绕过该条件。这条结论可以直接支撑本篇关于关闭门禁的说明。但它不自动支撑复核保存、模板应用和异常关闭成功的全部运行结论。每个动作仍要回到对应的代码和证据。三十、如何为缺失的专项截图补证据如果要补齐复核保存后的截图可以设计一条最小操作路径打开异常详情。输入处置结果。打开稳定性复核开关。选择模板决定。点击保存。截取保存反馈和状态文案。导出同一时刻布局树。补证后台账的screenshot_source应增加该专项截图文章的验证清单也可以把对应结论从“已验证源码”提升为“已通过运行观察”。当前版本不虚构这个尚未提供的文件。三十一、测试文章为什么需要写失败路径成功路径只能说明“条件满足时能继续”。失败路径才说明门禁真的生效未提交调机时不能关闭。复核未通过时不能进入模板确认。处置为空时不能关闭。模板决定 pending 时不能关闭。空标题不能创建异常。工业现场应用比普通展示页面更依赖失败路径。用户需要知道下一步缺什么而不是只看到按钮没有反应。三十二、常见问题一截图与布局树不是同一状态如果截图显示 EX-241但布局树显示 EX-238不能把两份材料混在一条结论中。先核对截图文件时间、布局树文件时间、操作步骤、当前异常 ID以及是否执行过resetDemoData()。证据必须能确定属于同一个运行状态才适合放在同一测试用例下。三十三、常见问题二测试只检查按钮存在按钮存在只能证明渲染不代表点击行为正确。每个按钮至少要有入口 动作 前置条件 成功结果 失败结果 数据变化例如“关闭异常”不能只记录“按钮存在”还要记录未提交调机时被阻止的反馈。三十四、常见问题三把源码建议当成运行结果文章中如果写了生产改进方案要使用“建议”“后续”“当前未实现”等明确词语。当前saveExceptionDisposition()返回void不能把建议的错误返回值写成已经合入的实现。三十五、常见问题四把 API 26 构建写成 API 24 编译正确表述工程使用 API 26 Beta1 构建在 API 24 模拟器中运行观察。错误表述使用 API 24 SDK 编译并运行。构建 API 和运行 API 不同文章标题和测试环境必须保持一致。三十六、当前 M4 测试的未覆盖项当前材料还没有为每一个后续状态提供独立运行截图未覆盖或需要补强的内容包括复核保存后的专项截图。模板应用后的独立 M4 截图。全部关闭条件满足后的成功关闭截图。多次复核历史。异常关闭后的只读页面。远程接口失败和重试。这些未覆盖项不影响已经存在的列表、登记和关闭阻止结论但会限制文章能声称的完整程度。三十七、测试文章的发布前检查发布前逐项核对检查项结果操作步骤能在 API 24 页面复现已有 M4 运行路径运行环境写明编译 API 和运行 API已写明列表、登记和关闭阻止有对应证据已有代码片段与当前文件一致已核对图片路径真实存在已核对复核保存专项截图尚未提供正文已标注把未验证能力写成完成能力未发现临时占位标记未发现三十八、总结本篇完成了 M4 异常闭环的测试证据整理用 M4-T01 验证异常列表、登记入口和卡片状态。用 M4-T02 验证关联调机记录未提交时关闭被阻止。用 M4-T03 验证登记表单、异常创建和草稿调机记录关联。使用布局树定位运行控件使用截图保留视觉结果。使用源码解释状态转移和关闭门禁。区分运行证据、源码证据和待补专项证据。明确 API 26 构建与 API 24 运行观察的环境边界。附录工程配置与版本说明为了便于读者复现本文中的代码片段和运行现象这里把当前文章系列对应的工程基线单独列出。本文所说的“当前工程”指e_notebook项目的 HarmonyOS ArkTS 客户端应用名称为“注塑工程师助手”主要用于脱敏演示机台档案、产品档案、调机记录、参数模板、异常闭环、生产批次和看板报表等业务路径。1. 应用与模块配置应用包名com.atan.enotebook。应用版本versionName为1.0.0versionCode为1000000。工程模型ArkTS / ArkUI Stage 模型。主模块entry模块类型为entry。入口 AbilityEntryAbility入口文件为entry/src/main/ets/entryability/EntryAbility.ets。主页面配置模块通过pages: $profile:main_pages读取页面列表。设备类型当前模块声明支持phone、tablet和2in1。安装方式deliveryWithInstall为trueinstallationFree为false属于随应用安装的普通 entry 模块。2. SDK 与 API 版本DevEco Studio 版本DevEco Studio Beta26.0.0.461。编译 SDKHarmonyOS SDK API 26 Beta1SDK 包版本为26.0.0.23。SDK 平台信息apiVersion为26platformVersion为26.0.0releaseType/stage为Beta1。targetSdkVersion26.0.0。compatibleSdkVersion6.1.1(24)。API 口径说明文章系列以 API 24 作为兼容目标进行表述当前工程实际由 API 26 Beta SDK 编译并在 API 24 模拟器上做过安装、启动和交互观察。因此文中的“API 24 运行观察”表示兼容目标环境下的模拟器验证结果不等同于使用 API 24 SDK 重新完成编译验证。3. 构建与运行工具开发工具 IDEDevEco Studio Beta安装目录指向D:/Program Files/Huawei/DevEco Studio Beta。SDK 路径D:/Program Files/Huawei/DevEco Studio Beta/sdk。构建系统Hvigor工程入口hvigorfile.ts使用ohos/hvigor-ohos-plugin的appTasks。Hvigor 执行配置开启 daemon、incremental、parallel 和 typeCheck日志级别为info。构建脚本本地build.ps1优先使用 DevEco Studio 自带的 JBR、Node.js、SDK 与 Hvigor避免系统环境变量中的 Java 或 Node.js 版本干扰构建结果。调试产物未配置签名时本地构建生成entry/build/default/outputs/default/entry-default-unsigned.hap。这类 unsigned HAP 只用于本地调试和模拟器验证正式发布前需要在 DevEco Studio 中补充签名配置。4. 本系列文章的验证边界本系列代码以脱敏演示数据为主Repository、Store、页面状态和组件边界都围绕本地演示闭环展开。已观察过的运行现象以文中对应截图、布局树和人工核对记录为准没有重新核对的页面不在单篇文章中扩大为完整结论。如果读者使用更新的 DevEco Studio、HarmonyOS SDK 或真机系统版本复现API 差异、控件行为和签名流程可能会发生变化。遇到差异时建议优先核对build-profile.json5、module.json5、SDK Manager 中安装的 API 版本以及当前设备或模拟器的系统 API 等级。附录 2项目目录结构与设计意图下面这份目录说明对应当前 DevEco Studio 中打开的harmonyos-app工程。截图里能看到的目录并不只是文件摆放习惯它反映了一个 ArkTS Stage 工程的分层方式应用级配置、业务模块、页面源码、资源文件、构建配置和过程归档分别放在不同位置方便后续排查问题时先判断“问题属于配置、页面、数据、状态、资源还是构建产物”。harmonyos-app/ ├── AppScope/ # 应用级配置与全局资源入口 │ ├── app.json5 # bundleName、版本号、图标、应用标签等应用级元信息 │ └── resources/ # 应用级图标、字符串和基础资源 ├── entry/ # 主业务模块当前 App 的主要页面和业务代码都在这里 │ ├── src/main/ets/ # ArkTS 源码根目录 │ │ ├── components/ # 可复用 ArkUI 组件如底部导航、数据状态面板 │ │ ├── entryability/ # Stage 模型入口 Ability负责应用启动入口 │ │ ├── features/ # 按业务域拆分的功能页面 │ │ │ ├── debug/ # 调机记录相关页面 │ │ │ ├── exceptions/ # 异常处置与闭环相关页面 │ │ │ ├── home/ # 首页看板与概览入口 │ │ │ ├── machines/ # 机台档案列表、详情和机台相关交互 │ │ │ ├── production/ # 生产批次、报工和结案门禁相关页面 │ │ │ ├── products/ # 产品档案、产品详情和关联信息 │ │ │ ├── reports/ # 周报、月报、班次报表和下钻入口 │ │ │ └── templates/ # 参数模板列表与详情 │ │ ├── models/ # 业务对象的数据结构如 Machine、Product、DebugRecord │ │ ├── pages/ # 页面容器与导航装配如 Index.ets │ │ ├── repositories/ # 脱敏演示数据、查询方法、快照持久化和数据重置边界 │ │ ├── stores/ # 页面路由、导航选择和共享状态规则 │ │ └── utils/ # 主题令牌、校验函数等通用工具 │ ├── src/main/resources/base/ # 模块级资源目录 │ │ ├── element/ # 字符串、颜色等基础资源声明 │ │ ├── media/ # 图标、启动图等媒体资源 │ │ └── profile/ # 页面 profile 配置如 main_pages.json │ ├── src/main/module.json5 # entry 模块配置声明 EntryAbility、设备类型和页面入口 │ ├── build-profile.json5 # 模块级构建目标、混淆和 target 配置 │ └── oh-package.json5 # entry 模块包信息与依赖声明 ├── hvigor/ # Hvigor 构建系统配置 │ └── hvigor-config.json5 # 构建执行参数如增量、并行和类型检查 ├── build-profile.json5 # 工程级 SDK、targetSdkVersion、compatibleSdkVersion 配置 ├── hvigorfile.ts # 工程级构建任务入口接入 appTasks ├── local.properties # 本机 SDK 路径配置 ├── oh-package.json5 # 工程级包信息与依赖声明 ├── build.ps1 # 本地构建脚本固定使用 DevEco Studio 自带工具链 ├── document_claude/ # 开发过程归档、测试记录和验证材料 ├── .hvigor/ # Hvigor 生成的缓存和构建记录不作为手写源码维护 ├── .idea/ # DevEco Studio / IntelliJ 工程配置不承载业务逻辑 └── entry/build/ # 构建输出目录HAP 和中间产物由构建流程生成1. 为什么应用级配置放在AppScopeAppScope负责应用整体身份而不是某个页面的业务逻辑。app.json5中的bundleName、versionName、versionCode、应用图标和应用标签会影响安装包身份、桌面展示和版本识别。把这类配置放在应用级目录可以避免业务页面为了改一个标题或图标而混入应用发布配置。在当前工程中AppScope更像“应用身份证”。它回答的是“这个 App 是谁、版本是多少、展示什么图标”而不是“机台列表怎么筛选、详情页怎么返回”。2. 为什么业务代码集中在entry/src/main/etsentry是当前工程的主业务模块src/main/ets是 ArkTS 源码根目录。截图里打开的MachineDetail.ets就位于features/machines下面说明机台详情页被归入“机台业务域”而不是随意放在全局页面目录中。这种组织方式的好处是定位明确机台问题优先看features/machines产品问题优先看features/products生产批次问题优先看features/production。当文章里讨论某个业务链路时读者也能从目录直接反推代码位置。3.components、features和pages的边界components放的是可复用组件例如底部导航、加载/空态/失败态面板。它们不应该直接知道“当前打开的是哪台机台”而是通过参数和回调服务于不同页面。features放的是业务域页面。每个子目录都围绕一个业务主题组织例如machines负责机台档案templates负责参数模板exceptions负责异常闭环。业务页面可以组合组件也可以读取模型和仓储但应尽量把本业务域的显示和交互留在本目录内。pages更偏页面容器和入口装配。当前Index.ets承担主页面状态切换、底部导航和详情路径分发等职责。它不应该塞满所有业务细节而是负责把用户当前所在位置、打开对象和页面分支组织起来。4.models、repositories和stores分别解决什么问题models定义数据形状例如机台、产品、调机记录、生产批次等对象有哪些字段。它让页面和仓储使用同一套类型语言避免每个页面临时拼对象。repositories定义数据来源和查询边界。当前工程使用脱敏演示数据和本地持久化快照因此仓储层负责“从哪里取数据、按什么 ID 查询、怎样重置演示数据”。页面不直接关心数据是内置数组、Preferences 快照还是后续真实接口。stores定义页面级或应用级状态规则例如当前导航项、路由分支、打开详情的类型和 ID。把状态规则从具体组件中抽出来可以减少“列表、详情、导航互相覆盖状态”的问题。5. 为什么资源放在resources/baseresources/base/element管字符串、颜色等声明resources/base/media管图标和图片resources/base/profile管页面 profile。它们和 ArkTS 页面代码分开是为了让“界面逻辑”和“静态资源”各自清晰。如果页面显示异常先判断是布局代码问题还是资源引用问题。比如图标不显示应优先检查media和资源引用页面无法进入应检查profile/main_pages.json和module.json5的页面声明颜色或字符串不符合预期则回到element下核对。6. 构建目录和生成目录不要手工维护.hvigor、entry/build和部分中间产物目录由构建系统生成主要用于缓存、编译记录、HAP 输出和临时文件。它们可以帮助排查构建结果但不应该作为手写业务代码维护。当前调试 HAP 位于entry/build/default/outputs/default/entry-default-unsigned.hap。这个路径说明构建已经产出安装包但它仍是 unsigned 调试产物正式发布前应回到 DevEco Studio 的签名配置和发布流程而不是直接修改build目录里的文件。
HarmonyOS ArkTS API 24+ 实战：补齐异常闭环测试与运行截图
发布时间：2026/8/1 4:45:29
前言有按钮不等于流程已经验证M4 异常闭环包含登记、调机、复核、模板确认和关闭多个阶段。页面可以渲染出按钮Repository 也可以写出状态但如果没有明确的操作步骤、预期结果和运行证据文章很难回答一个实际问题这条流程到底在哪一步被验证过本篇不新增业务字段而是对当前已经实现的异常模块做验证收束。重点使用项目中已有的M4 异常列表布局树。M4 异常详情布局树。登记页布局树。登记后详情截图。关闭被阻止截图。M2.1 测试报告中的 M4 补充用例。ExceptionList.ets、ExceptionDetail.ets和DemoBusinessRepository.ets源码。文章会把“运行观察”“布局树证据”“源码逻辑”和“尚未专项截图的结论”分开。这样做的目的是让人工审稿和开发排错都能准确追溯。一、先定义 M4 需要证明的结果当前异常状态模型包含exporttypeExceptionStatusopen|debugging|verifying|template_pending|closed;M4 测试至少要证明下面几类结果验证对象需要证明的结果异常列表能显示已有异常并提供登记入口异常详情能打开指定异常并显示状态、批次和关联调机入口异常登记标题输入存在提交后创建异常和草稿调机记录关闭门禁关联调机记录未提交时不能直接关闭状态模型页面文案与 Repository 中的状态枚举一致证据链每个结论能对应截图、布局树、测试报告或源码这些目标不等于“所有 M4 状态都分别截图”。当前材料对登记页和未提交关闭场景有运行证据对部分状态推进主要使用源码审查。证据强度必须如实标注。二、测试环境必须写清编译和运行 API项目测试报告使用的环境是编译DevEco Studio Beta 26.0.0.461 编译 APIHarmonyOS API 26 Beta1 运行设备HarmonyOS API 24 模拟器 127.0.0.1:12024 包名com.atan.enotebook这里有两个 API 版本API 26 Beta1 是工程构建环境。API 24 是页面运行观察环境。文章标题中的 API 24 对应运行验证口径不能写成“使用 API 24 SDK 完成编译”。如果不写清楚读者可能会把构建失败和运行兼容性混成同一个问题。三、先确认异常页签入口Index.ets中的异常页签装配}elseif(this.selectedTabexceptions){ExceptionList({onOpen:(exceptionId:string)this.openDetail(exception,exceptionId),onCreate:()this.openDetail(exception,new)}).layoutWeight(1)}列表进入详情的关键不是把整个对象传给子组件而是传递稳定的异常 IDonOpen:(exceptionId:string)this.openDetail(exception,exceptionId)这样详情页出现时可以重新通过 Repository 查询最新对象减少列表快照和详情对象之间的状态分叉。四、M4-T01打开异常列表和 EX-241项目测试报告中的 M4-T01 是打开“异常”页签和 EX-241预期结果页面显示“异常管理”。页面显示“登记异常”入口。页面显示异常列表卡片。EX-241 卡片显示标题、状态和批次。点击卡片可以进入异常详情。ExceptionList.ets的当前实现Scroll(){Column({space:14}){Row(){Text(异常管理)Blank()Button(登记异常).onClick(()this.onCreate())}Text(登记、调机、复核、模板确认和关闭均围绕同一异常编号完成。)ForEach(demoBusinessRepository.loadExceptions(),(item:ExceptionRecord){Button(${item.id}·${item.title}\n${item.statusLabel()}·${item.batchId}).onClick(()this.onOpen(item.id))},(item:ExceptionRecord)item.id)}}这里的 key 使用item.id而不是状态文案或数组序号。异常状态变化后ArkUI 仍然能识别同一条记录。五、列表布局树证明了哪些内容M4 列表布局树是document_claude/20260723_功能开发_M2至M6业务闭环/测试文件/m4-list.json从布局树中可以提取出节点运行文本页面标题异常管理创建按钮登记异常说明文字登记、调机、复核、模板确认和关闭均围绕同一异常编号完成。第一张异常卡片EX-241 · 短射复核 / 待处理 · 20260719-A07第二张异常卡片EX-238 · 飞边处理 / 待模板确认 · 20260720-A03布局树证明的是控件和文字确实出现在运行页面中。它不能单独证明点击卡片后详情页的数据保存逻辑需要和详情源码、Repository 代码及后续截图结合。六、为什么截图和布局树要同时保留截图适合回答用户实际看到的页面是什么样布局树适合回答页面有哪些可定位的控件、文本和 bounds两者互补证据优点局限JPEG 截图直观展示视觉结果不容易精确检索控件文本和坐标JSON 布局树可检索文本、类型和 bounds看不出完整视觉层次和颜色效果源码能解释行为和状态规则不能证明运行时页面一定出现测试报告记录操作和结论需要依赖具体证据文件文章在写运行结论时应该尽量把四者关联起来。七、M4-T02未提交调机记录时关闭被阻止测试报告中的 M4-T02未提交关联调机记录时直接关闭 EX-241预期结果关闭被阻止提示“请先提交关联调机记录”对应证据m4-close-blocked.json m4-close-blocked.jpeg这条用例是 M4 重要的边界测试因为它证明页面虽然有“关闭异常”按钮但业务层不会允许状态越级。八、关闭门禁的实际代码DemoBusinessRepository.canCloseException()先查异常对象再查关联调机记录canCloseException(exceptionId:string):string{constexception:ExceptionRecord|undefinedthis.exceptionById(exceptionId);if(exceptionundefined)return未找到异常记录。;constdebug:DebugRecord|undefinedthis.debugById(exception.debugRecordId);if(debugundefined||(debug.status!submitteddebug.status!approved)){return请先提交关联调机记录。;}if(!exception.verificationPassed){return请先完成稳定性复核。;}if(exception.disposition.trim().length0){return请先记录异常品处置结果。;}if(exception.templateDecisionpending){return请先应用模板或明确不更新模板。;}return;}检查顺序有现场意义先提示最前面的缺口用户补齐调机提交后下一次点击才会进入复核、处置和模板门禁。九、关闭动作为什么要调用同一个门禁详情页关闭方法很薄privateclose():void{constreason:stringdemoBusinessRepository.closeException(this.exceptionId);this.feedbackreason.length0?异常已关闭。:reason;}真正的状态修改在 RepositorycloseException(exceptionId:string):string{constreason:stringthis.canCloseException(exceptionId);if(reason.length0)returnreason;constexception:ExceptionRecord|undefinedthis.exceptionById(exceptionId);if(exception!undefined)exception.statusclosed;this.notifyStateChanged();return;}页面负责反馈Repository 负责条件和状态。未来增加列表快捷关闭或后台动作时也可以复用同一个门禁。十、关闭阻止截图能证明什么这张图可以证明异常详情页面确实运行出来。页面存在关闭动作入口。当前操作得到明确阻止反馈。反馈内容与canCloseException()的第一道条件一致。它不能证明处置结果保存成功、复核通过、模板已经应用或异常在其他数据状态下可以关闭。一张截图只证明截图中的状态。十一、M4-T03打开登记异常页面测试报告中的 M4-T03打开“登记异常”并输入异常标题预期结果显示登记表单与异常标题输入。提交时创建同一异常编号下的草稿调机记录。详情页可以继续打开关联调机记录。对应证据m4-registration-form.json ExceptionDetail.ets DemoBusinessRepository.registerException() 提交 7b592b6十二、登记页布局树的定位信息登记页布局树记录了关键控件类型运行文本或 hint作用Button返回异常列表返回列表Text登记异常页面标题Text登记后自动创建同一异常编号下的草稿调机记录……说明业务关系Text异常标题字段标签TextInput例如外观银纹复核输入异常标题Button登记并进入处置提交登记动作布局树中的输入框和按钮都有 bounds可以用于确认 API 24 设备上控件没有被底部导航遮挡也没有因为页面内容变化而消失。十三、登记和关闭是两个独立用例登记成功只说明ExceptionRecord 已创建 DebugRecord 已创建状态为 draft 页面进入新异常详情它不说明调机记录已经 submitted、复核已经通过、模板决定已经明确或异常已经 closed。测试报告把 M4-T03 和 M4-T02 分开是正确的测试设计。一个测试用例只验证一个动作链路便于定位失败原因。十四、登记后详情截图登记后详情截图对应布局树document_claude/20260723_功能开发_M2至M6业务闭环/测试文件/m4-registered-detail.json这张截图可以证明登记后页面已经从new表单进入真实异常详情。关联对象是否双向正确还需要结合registerException()的源码审查。十五、登记方法的测试审查点registerException()的关键逻辑registerException(title:string):ExceptionRecord|undefined{constnormalizedTitle:stringtitle.trim();if(normalizedTitle.length0)returnundefined;constsequence:numberthis.exceptions.filter((item:ExceptionRecord)item.id.startsWith(EX-NEW-)).length1;constexceptionId:stringEX-NEW-${sequence.toString().padStart(3,0)};constdebugId:stringDBG-NEW-${sequence.toString().padStart(3,0)};// 创建异常和关联草稿调机记录}测试审查点包括空标题返回undefined。标题会清理首尾空白。两个 ID 使用同一序号。新异常状态是open。新调机记录状态是draft。两个对象都加入 Repository 集合。页面回调使用新异常 ID。十六、测试证据的强弱分级A 级运行截图和布局树共同存在例如异常列表、登记页、关闭阻止页面。可以写成“API 24 运行中观察到”。B 级运行布局树或截图单独存在可以证明页面节点或视觉结果但要少写一步行为结论。C 级源码和测试报告支持可以写成“源码逻辑和测试记录支持”不能写成“截图已经证明”。D 级设计推断或未来建议只能写成“建议”“后续可补充”不能放进当前完成清单。当前 M4 的登记页和关闭阻止属于 A 级或接近 A 级证据复核保存专项截图属于尚未独立提供的证据。十七、为什么不能只看源码判定页面完成源码中存在Button(登记并进入处置)只能说明组件声明了这个按钮。要判定页面运行完成还要观察页面是否能进入、按钮是否可见、输入框是否位于可视区域、底部导航是否覆盖页面以及点击后是否进入真实详情。这就是运行布局树和截图的价值。代码是必要证据但不是全部证据。十八、为什么不能只看截图判定业务完成截图中的“异常已关闭”文字如果出现也还要确认真实对象状态是否变成closed。关闭是否经过canCloseException()。关联调机记录是否满足条件。处置、复核和模板决定是否已保存。截图是观察结果Repository 是业务规则。两者需要互相验证。十九、M4 测试中的状态转移表当前代码可以整理为当前状态或条件动作结果登记模式输入有效标题并提交创建open异常和draft调机记录open提交关联调机记录进入verifyingverifying保存复核未通过保持verifyingverifying保存复核通过进入template_pendingtemplate_pending模板决定仍为 pending关闭被阻止全部关闭条件满足点击关闭进入closed这个表比“点击按钮后状态变化”的描述更适合测试因为每一行都有前置状态、动作和预期结果。二十、边界测试空标题登记页面的空标题测试输入空字符串、空格、换行或制表符 预期提示“请填写异常标题后再登记”同时检查异常列表没有新增记录。调机列表没有新增草稿。页面仍然停留在登记模式。onRegistered没有被调用。只观察提示文字还不够因为可能存在“提示显示了但对象已经创建”的半失败状态。二十一、边界测试不存在的异常 ID详情页通过privateexists():boolean{returndemoBusinessRepository.exceptionById(this.exceptionId)!undefined;}处理不存在对象。预期页面只显示未找到异常记录 返回异常列表不应显示保存、复核和关闭操作。安全占位对象只保证渲染不崩溃不能代表可以执行真实业务动作。二十二、边界测试关联调机记录不存在关闭门禁先调用this.debugById(exception.debugRecordId)如果找不到关联调机记录应该返回请先提交关联调机记录。这个结果比直接抛出空指针异常更适合现场页面也提醒开发者检查异常和调机对象之间的双向关联。二十三、边界测试复核未通过准备一个关联调机记录已提交、但复核未通过的异常字段测试值debug.statussubmittedexception.verificationPassedfalse点击关闭时预期请先完成稳定性复核。这条用例证明“调机提交”已经完成但复核仍然是独立门禁。二十四、边界测试处置结果为空准备一个调机已提交、复核已通过、模板决定已明确但处置结果为空的异常字段测试值debug.statussubmittedverificationPassedtruetemplateDecisionapplied或not_requireddisposition空字符串关闭时预期请先记录异常品处置结果。当前保存方法允许保存空摘要但关闭门禁不会放过空摘要。测试要把这两个行为写清楚。二十五、边界测试模板决定 pending准备一个调机已提交、复核已通过、处置结果非空、模板决定仍为 pending 的异常字段测试值debug.statussubmittedverificationPassedtruedisposition非空templateDecisionpending关闭时预期请先应用模板或明确不更新模板。这样可以确认关闭条件没有把复核通过误认为模板决定完成。二十六、测试用例不应该互相污染本地 Repository 使用内存数组。一个测试如果登记了新异常后面的测试可能看到新增对象。测试执行前应该demoBusinessRepository.resetDemoData();当前工程提供了重置演示数据的方法。虽然测试报告主要记录运行观察和源码审查但状态性测试需要可重复的初始数据。二十七、状态通知不是测试通过标记Repository 更新对象后调用this.notifyStateChanged();这只是通知页面状态变化。测试仍然需要观察实际字段、页面文案或布局树不能因为通知被调用就判定业务动作通过。如果通知遗漏可能出现对象已更新、页面仍显示旧状态的情况如果对象没有更新通知调用也不能让错误数据变正确。二十九、测试报告中的结论边界当前测试报告明确写出M4 的关闭校验由 DemoBusinessRepository.canCloseException() 执行页面无法绕过该条件。这条结论可以直接支撑本篇关于关闭门禁的说明。但它不自动支撑复核保存、模板应用和异常关闭成功的全部运行结论。每个动作仍要回到对应的代码和证据。三十、如何为缺失的专项截图补证据如果要补齐复核保存后的截图可以设计一条最小操作路径打开异常详情。输入处置结果。打开稳定性复核开关。选择模板决定。点击保存。截取保存反馈和状态文案。导出同一时刻布局树。补证后台账的screenshot_source应增加该专项截图文章的验证清单也可以把对应结论从“已验证源码”提升为“已通过运行观察”。当前版本不虚构这个尚未提供的文件。三十一、测试文章为什么需要写失败路径成功路径只能说明“条件满足时能继续”。失败路径才说明门禁真的生效未提交调机时不能关闭。复核未通过时不能进入模板确认。处置为空时不能关闭。模板决定 pending 时不能关闭。空标题不能创建异常。工业现场应用比普通展示页面更依赖失败路径。用户需要知道下一步缺什么而不是只看到按钮没有反应。三十二、常见问题一截图与布局树不是同一状态如果截图显示 EX-241但布局树显示 EX-238不能把两份材料混在一条结论中。先核对截图文件时间、布局树文件时间、操作步骤、当前异常 ID以及是否执行过resetDemoData()。证据必须能确定属于同一个运行状态才适合放在同一测试用例下。三十三、常见问题二测试只检查按钮存在按钮存在只能证明渲染不代表点击行为正确。每个按钮至少要有入口 动作 前置条件 成功结果 失败结果 数据变化例如“关闭异常”不能只记录“按钮存在”还要记录未提交调机时被阻止的反馈。三十四、常见问题三把源码建议当成运行结果文章中如果写了生产改进方案要使用“建议”“后续”“当前未实现”等明确词语。当前saveExceptionDisposition()返回void不能把建议的错误返回值写成已经合入的实现。三十五、常见问题四把 API 26 构建写成 API 24 编译正确表述工程使用 API 26 Beta1 构建在 API 24 模拟器中运行观察。错误表述使用 API 24 SDK 编译并运行。构建 API 和运行 API 不同文章标题和测试环境必须保持一致。三十六、当前 M4 测试的未覆盖项当前材料还没有为每一个后续状态提供独立运行截图未覆盖或需要补强的内容包括复核保存后的专项截图。模板应用后的独立 M4 截图。全部关闭条件满足后的成功关闭截图。多次复核历史。异常关闭后的只读页面。远程接口失败和重试。这些未覆盖项不影响已经存在的列表、登记和关闭阻止结论但会限制文章能声称的完整程度。三十七、测试文章的发布前检查发布前逐项核对检查项结果操作步骤能在 API 24 页面复现已有 M4 运行路径运行环境写明编译 API 和运行 API已写明列表、登记和关闭阻止有对应证据已有代码片段与当前文件一致已核对图片路径真实存在已核对复核保存专项截图尚未提供正文已标注把未验证能力写成完成能力未发现临时占位标记未发现三十八、总结本篇完成了 M4 异常闭环的测试证据整理用 M4-T01 验证异常列表、登记入口和卡片状态。用 M4-T02 验证关联调机记录未提交时关闭被阻止。用 M4-T03 验证登记表单、异常创建和草稿调机记录关联。使用布局树定位运行控件使用截图保留视觉结果。使用源码解释状态转移和关闭门禁。区分运行证据、源码证据和待补专项证据。明确 API 26 构建与 API 24 运行观察的环境边界。附录工程配置与版本说明为了便于读者复现本文中的代码片段和运行现象这里把当前文章系列对应的工程基线单独列出。本文所说的“当前工程”指e_notebook项目的 HarmonyOS ArkTS 客户端应用名称为“注塑工程师助手”主要用于脱敏演示机台档案、产品档案、调机记录、参数模板、异常闭环、生产批次和看板报表等业务路径。1. 应用与模块配置应用包名com.atan.enotebook。应用版本versionName为1.0.0versionCode为1000000。工程模型ArkTS / ArkUI Stage 模型。主模块entry模块类型为entry。入口 AbilityEntryAbility入口文件为entry/src/main/ets/entryability/EntryAbility.ets。主页面配置模块通过pages: $profile:main_pages读取页面列表。设备类型当前模块声明支持phone、tablet和2in1。安装方式deliveryWithInstall为trueinstallationFree为false属于随应用安装的普通 entry 模块。2. SDK 与 API 版本DevEco Studio 版本DevEco Studio Beta26.0.0.461。编译 SDKHarmonyOS SDK API 26 Beta1SDK 包版本为26.0.0.23。SDK 平台信息apiVersion为26platformVersion为26.0.0releaseType/stage为Beta1。targetSdkVersion26.0.0。compatibleSdkVersion6.1.1(24)。API 口径说明文章系列以 API 24 作为兼容目标进行表述当前工程实际由 API 26 Beta SDK 编译并在 API 24 模拟器上做过安装、启动和交互观察。因此文中的“API 24 运行观察”表示兼容目标环境下的模拟器验证结果不等同于使用 API 24 SDK 重新完成编译验证。3. 构建与运行工具开发工具 IDEDevEco Studio Beta安装目录指向D:/Program Files/Huawei/DevEco Studio Beta。SDK 路径D:/Program Files/Huawei/DevEco Studio Beta/sdk。构建系统Hvigor工程入口hvigorfile.ts使用ohos/hvigor-ohos-plugin的appTasks。Hvigor 执行配置开启 daemon、incremental、parallel 和 typeCheck日志级别为info。构建脚本本地build.ps1优先使用 DevEco Studio 自带的 JBR、Node.js、SDK 与 Hvigor避免系统环境变量中的 Java 或 Node.js 版本干扰构建结果。调试产物未配置签名时本地构建生成entry/build/default/outputs/default/entry-default-unsigned.hap。这类 unsigned HAP 只用于本地调试和模拟器验证正式发布前需要在 DevEco Studio 中补充签名配置。4. 本系列文章的验证边界本系列代码以脱敏演示数据为主Repository、Store、页面状态和组件边界都围绕本地演示闭环展开。已观察过的运行现象以文中对应截图、布局树和人工核对记录为准没有重新核对的页面不在单篇文章中扩大为完整结论。如果读者使用更新的 DevEco Studio、HarmonyOS SDK 或真机系统版本复现API 差异、控件行为和签名流程可能会发生变化。遇到差异时建议优先核对build-profile.json5、module.json5、SDK Manager 中安装的 API 版本以及当前设备或模拟器的系统 API 等级。附录 2项目目录结构与设计意图下面这份目录说明对应当前 DevEco Studio 中打开的harmonyos-app工程。截图里能看到的目录并不只是文件摆放习惯它反映了一个 ArkTS Stage 工程的分层方式应用级配置、业务模块、页面源码、资源文件、构建配置和过程归档分别放在不同位置方便后续排查问题时先判断“问题属于配置、页面、数据、状态、资源还是构建产物”。harmonyos-app/ ├── AppScope/ # 应用级配置与全局资源入口 │ ├── app.json5 # bundleName、版本号、图标、应用标签等应用级元信息 │ └── resources/ # 应用级图标、字符串和基础资源 ├── entry/ # 主业务模块当前 App 的主要页面和业务代码都在这里 │ ├── src/main/ets/ # ArkTS 源码根目录 │ │ ├── components/ # 可复用 ArkUI 组件如底部导航、数据状态面板 │ │ ├── entryability/ # Stage 模型入口 Ability负责应用启动入口 │ │ ├── features/ # 按业务域拆分的功能页面 │ │ │ ├── debug/ # 调机记录相关页面 │ │ │ ├── exceptions/ # 异常处置与闭环相关页面 │ │ │ ├── home/ # 首页看板与概览入口 │ │ │ ├── machines/ # 机台档案列表、详情和机台相关交互 │ │ │ ├── production/ # 生产批次、报工和结案门禁相关页面 │ │ │ ├── products/ # 产品档案、产品详情和关联信息 │ │ │ ├── reports/ # 周报、月报、班次报表和下钻入口 │ │ │ └── templates/ # 参数模板列表与详情 │ │ ├── models/ # 业务对象的数据结构如 Machine、Product、DebugRecord │ │ ├── pages/ # 页面容器与导航装配如 Index.ets │ │ ├── repositories/ # 脱敏演示数据、查询方法、快照持久化和数据重置边界 │ │ ├── stores/ # 页面路由、导航选择和共享状态规则 │ │ └── utils/ # 主题令牌、校验函数等通用工具 │ ├── src/main/resources/base/ # 模块级资源目录 │ │ ├── element/ # 字符串、颜色等基础资源声明 │ │ ├── media/ # 图标、启动图等媒体资源 │ │ └── profile/ # 页面 profile 配置如 main_pages.json │ ├── src/main/module.json5 # entry 模块配置声明 EntryAbility、设备类型和页面入口 │ ├── build-profile.json5 # 模块级构建目标、混淆和 target 配置 │ └── oh-package.json5 # entry 模块包信息与依赖声明 ├── hvigor/ # Hvigor 构建系统配置 │ └── hvigor-config.json5 # 构建执行参数如增量、并行和类型检查 ├── build-profile.json5 # 工程级 SDK、targetSdkVersion、compatibleSdkVersion 配置 ├── hvigorfile.ts # 工程级构建任务入口接入 appTasks ├── local.properties # 本机 SDK 路径配置 ├── oh-package.json5 # 工程级包信息与依赖声明 ├── build.ps1 # 本地构建脚本固定使用 DevEco Studio 自带工具链 ├── document_claude/ # 开发过程归档、测试记录和验证材料 ├── .hvigor/ # Hvigor 生成的缓存和构建记录不作为手写源码维护 ├── .idea/ # DevEco Studio / IntelliJ 工程配置不承载业务逻辑 └── entry/build/ # 构建输出目录HAP 和中间产物由构建流程生成1. 为什么应用级配置放在AppScopeAppScope负责应用整体身份而不是某个页面的业务逻辑。app.json5中的bundleName、versionName、versionCode、应用图标和应用标签会影响安装包身份、桌面展示和版本识别。把这类配置放在应用级目录可以避免业务页面为了改一个标题或图标而混入应用发布配置。在当前工程中AppScope更像“应用身份证”。它回答的是“这个 App 是谁、版本是多少、展示什么图标”而不是“机台列表怎么筛选、详情页怎么返回”。2. 为什么业务代码集中在entry/src/main/etsentry是当前工程的主业务模块src/main/ets是 ArkTS 源码根目录。截图里打开的MachineDetail.ets就位于features/machines下面说明机台详情页被归入“机台业务域”而不是随意放在全局页面目录中。这种组织方式的好处是定位明确机台问题优先看features/machines产品问题优先看features/products生产批次问题优先看features/production。当文章里讨论某个业务链路时读者也能从目录直接反推代码位置。3.components、features和pages的边界components放的是可复用组件例如底部导航、加载/空态/失败态面板。它们不应该直接知道“当前打开的是哪台机台”而是通过参数和回调服务于不同页面。features放的是业务域页面。每个子目录都围绕一个业务主题组织例如machines负责机台档案templates负责参数模板exceptions负责异常闭环。业务页面可以组合组件也可以读取模型和仓储但应尽量把本业务域的显示和交互留在本目录内。pages更偏页面容器和入口装配。当前Index.ets承担主页面状态切换、底部导航和详情路径分发等职责。它不应该塞满所有业务细节而是负责把用户当前所在位置、打开对象和页面分支组织起来。4.models、repositories和stores分别解决什么问题models定义数据形状例如机台、产品、调机记录、生产批次等对象有哪些字段。它让页面和仓储使用同一套类型语言避免每个页面临时拼对象。repositories定义数据来源和查询边界。当前工程使用脱敏演示数据和本地持久化快照因此仓储层负责“从哪里取数据、按什么 ID 查询、怎样重置演示数据”。页面不直接关心数据是内置数组、Preferences 快照还是后续真实接口。stores定义页面级或应用级状态规则例如当前导航项、路由分支、打开详情的类型和 ID。把状态规则从具体组件中抽出来可以减少“列表、详情、导航互相覆盖状态”的问题。5. 为什么资源放在resources/baseresources/base/element管字符串、颜色等声明resources/base/media管图标和图片resources/base/profile管页面 profile。它们和 ArkTS 页面代码分开是为了让“界面逻辑”和“静态资源”各自清晰。如果页面显示异常先判断是布局代码问题还是资源引用问题。比如图标不显示应优先检查media和资源引用页面无法进入应检查profile/main_pages.json和module.json5的页面声明颜色或字符串不符合预期则回到element下核对。6. 构建目录和生成目录不要手工维护.hvigor、entry/build和部分中间产物目录由构建系统生成主要用于缓存、编译记录、HAP 输出和临时文件。它们可以帮助排查构建结果但不应该作为手写业务代码维护。当前调试 HAP 位于entry/build/default/outputs/default/entry-default-unsigned.hap。这个路径说明构建已经产出安装包但它仍是 unsigned 调试产物正式发布前应回到 DevEco Studio 的签名配置和发布流程而不是直接修改build目录里的文件。
