HarmonyOS 审核契约重构 04:众筹回报页交付期文案错位的代码审计【共创稿事节】
代码审计与渐进重构 · 产品技术审查员视角 · 场景:手作灯具众筹。本文的系统接入与设备验收步骤需要按实际项目环境执行。

在什么条件下旧行为会错
这项需求看起来像小范围交互修改,实际牵涉一次跨模块解释权转移。单独修按钮文案容易通过视觉验收,却可能改变后续交易、任务和历史记录的含义。重构之前,先定义什么算真正完成。
在手作灯具众筹的实现里,最让人不安的地方是:商品卡写着预计季度,确认页只显示月份。用户以为已经锁定准确发货日,随后投诉实际交付晚于页面所见。这不是普通的文字错位,回报交付期说明会改变用户如何理解正在执行的行为。
目前掌握的现象是:商品卡写着预计季度,确认页只显示月份。用户以为已经锁定准确发货日,随后投诉实际交付晚于页面所见。换成技术语言,至少要核对rewardTier与estimatedWindow是不是同一份业务事实。只检查最终页面是否出现正确字符串,既无法发现缓存与源数据分歧,也无法知道错误从哪一次状态转换开始。
手作灯具众筹的这条路径依次经过“项目预览 → 回报选择 → 日期解释 → 承诺确认 → 订单留痕”。我们不应该凭直觉把它压成一个成功或失败的布尔值;从第一步到最后一步,每一阶段都可能留下尚未确认的事实。重构要先给关键交接点命名,再讨论状态应该放在哪里。
审计时先从失败条件倒着读取代码,而不是从函数第一行顺着读完。后端给出的是交付窗口,前端格式化函数把窗口上界当成单一日期,又丢弃了估计性质的文案标签。若只在最后增加一次界面刷新,旧模块仍然拥有错误的解释权。下次增加入口或并行任务,表面的修复就会重新失效。
时间窗口等价性审查:逐行追踪入口与副作用
把问题写成一次具体反例:跨年项目的预计窗口是十二月到次年二月;按字符串排序会把年份断裂隐藏掉。这里必须分清“旧请求仍然能返回”和“旧请求仍然有资格修改当前状态”。前者是底层执行事实,后者是产品承诺;两者不应由一个普通回调自动等同。
翻开旧实现后的初步判断是:后端给出的是交付窗口,前端格式化函数把窗口上界当成单一日期,又丢弃了估计性质的文案标签。因此第一步不应重写整个页面,先列出产生这个结果的最短调用链,把每个条件分支的输入和副作用分开。
本次审计的高价值字段是rewardTier, estimatedWindow, revision, disclaimer。它们在代码里可能被封装成不同数据对象,但在业务上应被视作同一个决策快照的组成部分。任何单字段修补都要回答:删除它、留空它、从历史缓存恢复它时,是否仍能推出有效结论。
领域层使用明确的时间窗口对象,并让展示组件同时输出最早、最晚和估计属性;不能从区间推导出确定日期。这里的重构目标不是创造一个拥有所有权力的工具类,而是让回报选择与承诺确认之间的交接可被验证。不能验证的结果不能提前渲染为完成,更不能拿前端已展示的状态替代服务器或资源管理层的确认。
先列出跨月和跨年的窗口输入,刻意不追求漂亮日期字符串。按日历月比较窗口边界,不把“预计”收缩成确定承诺;展示逻辑退居领域对象之后,才能讨论文案格式。
契约先于组件抽象
数据进入系统后,先走无副作用的规则判断,再决定是否调用承诺确认。纯函数不应该依赖当前组件的局部变量、弹窗关闭次数或某个尚未完成的网络副作用。相同输入应当得到相同裁决,这样才能从日志和固定样本中重放问题。
下面的代码只实现这篇文章需要的领域裁决,不封装未经确认的系统SDK调用。它更适合放在ArkTS业务层,平台能力接入放在外侧适配器:一边可以验证只要estimate标记成立,所有页面都必须保留预计性质,任何空区间都不应被格式化为确定交付日。,另一边能单独审阅文件、网络、页面生命周期带来的错误路径。
| 数据字段 | 归属职责 | 需要阻断的条件 |
|---|---|---|
rewardTier | 项目预览 | 无效值不得自动进入回报选择 |
estimatedWindow | 回报选择 | 无效值不得自动进入日期解释 |
revision | 日期解释 | 无效值不得自动进入承诺确认 |
disclaimer | 承诺确认 | 无效值不得自动进入订单留痕 |
本轮重构把约束写得很清楚:领域层使用明确的时间窗口对象,并让展示组件同时输出最早、最晚和估计属性;不能从区间推导出确定日期。这样即使将来换成另一种展示组件,规则也不会因为某个按钮换了位置而悄悄失效。
真正的审计工作往往始于“如果字段不存在怎么办”。比如estimatedWindow并非必然存在;如果它来自上次任务、上个窗口或另一名用户,就不能继续沿用。重构后的调用方应处理拒绝、重新获取和用户确认三种分支,而不是在逻辑中偷偷给一个看似合理的默认值。
再看时序条件:跨年项目的预计窗口是十二月到次年二月;按字符串排序会把年份断裂隐藏掉。这个条件下旧实现很可能继续调用视图更新,而新实现必须比较请求绑定的版本与当前版本。即使底层任务不能及时取消,也应该丢弃已失效的结果,避免历史操作夺回页面控制权。

最小可验证重构
失败出口还需要资源层面的处理。一次被拒绝的变更,可能已经创建暂存文件、产生订阅令牌或准备了请求体。如果不能保证调用方执行清理,应该把资源交还动作写成显式协议。对缺失边界的回报停止提交并提示联系项目方,保留用户已选择的档位。这比捕获所有异常后统一显示“请重试”更有工程价值。
可单独审阅的ArkTS/TypeScript业务规则
type DeliveryWindow = { start: string; end: string | null; estimated: true };
function deliveryLabel(w: DeliveryWindow): string {
if (!/^\d{4}-\d{2}$/.test(w.start)) throw Error('bad month');
if (w.end && (!/^\d{4}-\d{2}$/.test(w.end) || w.end < w.start)) {
throw Error('bad interval');
}
return w.end ? `预计 ${w.start} 至 ${w.end} 交付` : `预计从 ${w.start} 开始交付`;
}
这一段针对rewardTier的约束是纯逻辑实现,不包含SDK绑定。项目里可在entry/src/main/ets/domain/建立对应模块,通过ArkTS接口适配调用,保留可独立运行的测试输入。
构造同月、跨月、跨年、未指定上界和撤回承诺五组案例,比较列表、详情与确认页的完整语义。这些用例的重点不是让测试数量好看,而是能否分辨不同错误来源。输入准备最好由独立于被测函数的规格表驱动,避免把函数当下的输出复制为预期答案。
为每个用例保留四份信息:输入快照、预期的不变量、实际得到的领域决策、调用方应呈现的动作。发生偏差时先看rewardTier和disclaimer是否一致,再定位是否为并发、缓存或业务解释差异。不要把视觉截图当作唯一证明。
在真实项目里还需要一组“旧输入与新代码混用”的兼容测试。版本升级之后历史数据不会突然消失,手作灯具众筹中的旧记录可能很长时间后才被再次打开。新代码对旧字段的容错必须有上界;遇到无法判断的状态,宁可留下待确认,也不能编造一个已完成的结论。
特殊路径是否真被覆盖
重构的收益和成本需要同时记录:把自由文案改成结构化窗口会增加内容录入约束,但能减少不同页面各自截断日期的风险。它会影响测试夹具、跨端协议、产品文案乃至客服排查方式,不能只凭代码行数的减少决定取舍。需要删除旧分支时,先证明新旧版本在允许的样本范围内得到同一个结果。
发布前还要审查权限与数据最小化边界。用于排障的rewardTier可以是可复核的匿名键,私人信息不应因为开发者想要排错就被原样写入日志。若确需保留审计证据,应标注保存期限、接触角色和删除规则,并与产品实际隐私说明一致。
专门保留一个不容易被正常测试覆盖的条件:跨年项目的预计窗口是十二月到次年二月;按字符串排序会把年份断裂隐藏掉。它是审查增量代码的重要样本,因为它往往能揭露时序、缓存与版本所有权的真实边界。
本篇真正应当被审核的是一条不变量:只要estimate标记成立,所有页面都必须保留预计性质,任何空区间都不应被格式化为确定交付日。这种句子可以被写成自动化断言,也能被产品、测试和审查人员读懂。相比“优化用户体验”“加强稳定性”,它给出了明确的失败判定,因此适合作为后续改造的长期契约。
当某个页面声称动作已完成时,必须能够回答是谁完成了什么、对应哪份输入、记录在哪里。订单留痕是这条流程的终点,却不意味着从此不需要版本。只要历史有机会回看,回看时就必须识别当时的规则与现在的规则并不必然相同。

测试矩阵与回归证据
工程验证需要分层:纯函数可以用固定数据在本地测试,系统接口需要与真实设备或目标SDK集成,跨端框架还要做协议一致性核对。本篇不以预先编造的帧率、耗时或通过率证明方案有效;所有需要实机采样的结论都留给项目CI和设备记录。
审阅者准备的反例表
| 情况 | 输入特征 | 期望处理 |
|---|---|
| 正常输入 | rewardTier与disclaimer一致 | 按业务规则继续 |
| 缺少字段 | estimatedWindow为空或非法 | 拒绝并指明缺失项 |
| 旧数据回流 | rewardTier已过期 | 保留当前状态,提示复核 |
| 并发交错 | 日期解释先于前序动作返回 | 以契约版本判断是否可提交 |
关键回归集不应只从正向流程生成。构造同月、跨月、跨年、未指定上界和撤回承诺五组案例,比较列表、详情与确认页的完整语义。同时必须检查用户端的解释是否对应实际拒绝原因,避免页面虽然正确拒绝,却用错误提示误导后续操作。
最容易诱惑维护者的简化,是把revision和disclaimer在界面层合并成一个状态字段。这样看似避免了多次赋值,实则掩盖了“谁提出、谁接受、谁可撤销”的不同责任。字段只要参与权限、金额、身份或资源释放,就应该保留清晰的所有权。
评审还有一个实用问题:如果只修改日期解释,系统剩下的路径会不会仍按照旧规则执行?如果答案是不确定,那么提交范围不应仅包含页面组件。应把入口适配器、领域规则、失败提示和必要的持久化字段放到同一轮受控修改中,避免半新半旧的协议长期共存。
为了让差异可被复核,代码提交应记录旧行为的最小反例、新契约的字段定义,以及对业务含义有影响的命名变更。尤其是estimatedWindow,一旦从可选值变成必填值,必须同步排查历史记录、跨端消息和测试夹具,不能让编译通过成为唯一的验收条件。
发布前的保留意见
如果团队关心为什么现在值得承担这次改造成本,可以回到两种方案的取舍:把自由文案改成结构化窗口会增加内容录入约束,但能减少不同页面各自截断日期的风险。这类成本和收益可以在设计评审中讨论,却不能从一次页面截图推断。
面对生产故障,先止损再迁移:对缺失边界的回报停止提交并提示联系项目方,保留用户已选择的档位。恢复策略要能够连续执行两次而不引入新问题。无论用户是主动重试、窗口被系统重新创建,还是后台任务刚刚恢复,都不应该产生更多不可解释的中间状态。
最后安排一名没有参与修改的审查者,只凭用例与领域约束推导预期结果。如果他不能解释为什么rewardTier变化后必须使某个缓存失效,说明文档仍过度依赖作者脑海中的隐含规则。让审查者找出一个不同于开发者所列样本的反例,通常比重复走一遍幸福路径更有效。
关于平台版本,本篇刻意把稳定业务算法与系统接口分开;涉及DevEco Studio、ArkTS和跨端运行时的使用方法,均需按目标设备API级别及项目依赖锁定版本复核。不同发布渠道的审核要求也可能变化,最终以提交时开发者后台发布的最新文档为准。
官方资料与适用范围
交易承诺、商品说明和纠纷预防是此篇需要跟踪的规范范围;具体平台API与审核条款以实际提交日和目标SDK文档为准。下列是可复核的官方入口,不代表本文代码已经在设备上跑通。
更多推荐

所有评论(0)