定时提醒突然报 201：HarmonyOS 7 reminderAgentManager 权限分流与补偿实战

烹饪计时器显示“提醒已创建”，几分钟后却没有通知。排查发现 publish 调用抛出 201，但页面先乐观写入成功状态，后台又不断重试，最终同一个任务出现多条本地记录。

本文交付：一个 ReminderPublisher、幂等 taskKey、201 权限分支、计时器与周计划两类案例，以及补偿队列表。。

图中的每条箭头都应对应一条可查询日志：输入、平台调用、状态映射、UI 或降级结果。只有 UI 变化而没有中间证据，后续仍然难以区分接口失败和页面逻辑错误。

官方依据与版本边界

官方变更页：https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/js-apidiff-backgroundtaskskit-7003

1. reminderAgentManager 发布提醒在 API 26 增加错误码 201。
2. 权限失败与时间参数失败必须分开处理。
3. 已创建提醒 ID 要和本地任务绑定。
4. 补偿队列不能无限自动重试。

本文依据 HarmonyOS 7.0.0 Release（API 26）官方变更说明梳理接口，并对状态模型、分支选择和异常映射做了宿主侧 TypeScript 测试。当前本机 SDK 为 API 24，且没有连接 HDC 设备，因此不把示例描述为 API 26 编译通过、真机性能数据或上架审核结论。接入前请在 API 26 工程中按文末清单完成编译、设备与回归验证。

两种行为不同的案例

案例一：20 分钟烹饪计时

用户正在等待结果，权限失败应立即回到页内倒计时并清楚提示，不自动循环发布。

案例二：每周采购计划

任务可持久化为 waiting-permission；用户恢复权限后按 taskKey 重新提交一次并读回提醒 ID。

可复用的 ArkTS 集成片段

type ReminderState = 'prepared' | 'published' | 'waiting-permission' | 'failed'
+type ReminderRecord = { taskKey: string; state: ReminderState; reminderId?: number }
+
+export async function publishReminder(record: ReminderRecord): Promise<ReminderRecord> {
+  if (record.state === 'published') return record
+  try {
+    const reminderId = await reminderAgentManager.publishReminder(buildRequest(record.taskKey))
+    return { ...record, state: 'published', reminderId }
+  } catch (error) {
+    const code = (error as BusinessError).code
+    if (code === 201) return { ...record, state: 'waiting-permission' }
+    return { ...record, state: 'failed' }
+  }
+}
+
+export function shouldRetry(record: ReminderRecord, permissionGranted: boolean) {
+  return record.state === 'waiting-permission' && permissionGranted
+}

代码刻意把平台调用和业务状态分开：平台返回什么就记录什么，页面只消费稳定状态。接入时还应补齐项目的日志域、错误码类型和生命周期释放。

复现与验证

1. 为每个提醒生成稳定 taskKey。
2. 在允许和拒绝权限两种环境分别发布。
3. 保存 publish 回执、提醒 ID 与本地状态。
4. 恢复权限后只查询 waiting-permission 项并提交一次。
5. 重新进入应用，确认 published 项不会再次创建。

取舍与落地清单

把权限问题当一般网络错误重试，会把一个确定失败放大成频控和重复数据。需要补偿的是用户恢复权限后的业务意图，而不是无条件重复同一请求。

• 已用 API 26 工程编译，并记录 SDK 与设备版本
• 已覆盖“20 分钟烹饪计时”和“每周采购计划”两类行为
• 已记录成功、失败、降级三条路径的输入与结果
• 已核对监听、对象或任务的释放与幂等行为
• 已把本文宿主测试替换为项目自己的真机证据

小结

一个 ReminderPublisher、幂等 taskKey、201 权限分支、计时器与周计划两类案例，以及补偿队列表。。建议先在最小页面复现，再接入完整“中式美食”流程；先证明状态链正确，再谈动画、缓存或埋点优化。