496 lines
23 KiB
Plaintext
496 lines
23 KiB
Plaintext
|
/**
|
|||
|
|
* 家书 FamilyBook · 后台定期同步（鸿蒙端，v83）
|
|||
|
|
*
|
|||
|
|
* 🔴 用户 2026-10-23 的原话：
|
|||
|
|
* 「另外，要有定期同步的功能，就是家书app在后台，也能自动同步数据，
|
|||
|
|
* 这样打开app，基本上数据就是最新的。同步的策略，去synccalendar找，里面有办法。」
|
|||
|
|
*
|
|||
|
|
* ⇒ 策略照搬 `SyncCalendar/entry/src/main/ets/common/BackgroundSyncService.ets`
|
|||
|
|
* 与 `BackgroundSyncRunner.ets`，**不自己另发明一套**。它的分层调度是踩出来的：
|
|||
|
|
*
|
|||
|
|
* ① **前台**：无需在此处理（顶栏手动同步 + 页面各自同步已有）。
|
|||
|
|
* ② **退后台瞬间**：`requestSuspendDelay` 申请**短时任务**，让"刚退后台那一次"
|
|||
|
|
* 能跑完。⚠️ 必须在"前台或退后台 5 秒内"申请，否则被拒。
|
|||
|
|
* ③ **长期后台**：`workScheduler` **延迟任务**，周期 2 小时、`isPersisted` 重启自动恢复。
|
|||
|
|
* ④ **服务卡片定时刷新**：`updateDuration: 1`（单位 **30 分钟**）触发
|
|||
|
|
* `FbFormAbility.onUpdateForm`，**不受"应用活跃分组"压制** ⇒ 这是唯一
|
|||
|
|
* 能做到"约 30 分钟一次"的通道。借这个时机跑一次同步（带节流）。
|
|||
|
|
*
|
|||
|
|
* ⚠️ **30 分钟那条不能靠 workScheduler 实现**（本文件最大的坑，别改）：
|
|||
|
|
* 系统按"应用活跃分组"压制延迟任务周期 ——
|
|||
|
|
* 活跃≥2h / 经常使用≥4h / 常用≥24h / 极少使用≥48h / 受限·从未使用禁止调度。
|
|||
|
|
* 请求 30 分钟**不报错**，但会被压到 2 小时甚至更久 ⇒ **形同虚设**。
|
|||
|
|
* 这也是为什么 `DEFERRED_CYCLE_MS` 写死 2 小时而不是"用户想要的 30 分钟"。
|
|||
|
|
*
|
|||
|
|
* ⚠️ `WorkSchedulerExtensionAbility` 单次回调**上限 2 分钟**，超时进程被杀。
|
|||
|
|
*
|
|||
|
|
* ⚠️ 短时任务配额：**单日 10 分钟、单次最长 3 分钟**（低电量 1 分钟），
|
|||
|
|
* 用完必须 `cancelSuspendDelay` 归还，否则后面的"退后台同步"没配额可用。
|
|||
|
|
*
|
|||
|
|
* 🔴🔴 **后台进程是"另一个进程"**（WorkScheduler / Form 扩展都跑在独立进程里）：
|
|||
|
|
* 本文件里的 `prepare()` 必须在执行同步前把这些单例**重新初始化**一遍 ——
|
|||
|
|
* 主进程里 `EntryAbility.onCreate` 做过的那些 init，在新进程里**一个都没做**。
|
|||
|
|
* 漏了任何一步的表现都是"后台同步永远失败、但日志里看不出原因"：
|
|||
|
|
* · 漏 `FB_TOKEN_STORE.init` ⇒ 令牌空 ⇒ `syncAll` 直接判"未登录"
|
|||
|
|
* · 漏 `FB_SERVER_STORE.init` ⇒ 服务器地址空 ⇒ `fbApi` 报 `no_server`
|
|||
|
|
* · 漏 `FbDb.open` ⇒ 数据拉下来也存不进去（只能空跑一趟网络）
|
|||
|
|
* · 漏 `FB_MODULE_TOKEN.set` ⇒ 通用缓存仓库拿不到令牌（它走注入式读取）
|
|||
|
|
*
|
|||
|
|
* ⚠️ 所有方法**永不抛错**（后台路径没有 UI 承担异常）。
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
import { common } from '@kit.AbilityKit';
|
|||
|
|
import { backgroundTaskManager, workScheduler } from '@kit.BackgroundTasksKit';
|
|||
|
|
import { preferences } from '@kit.ArkData';
|
|||
|
|
import { hilog } from '@kit.PerformanceAnalysisKit';
|
|||
|
|
import { BusinessError } from '@kit.BasicServicesKit';
|
|||
|
|
import { FB_TOKEN_STORE } from '../data/FbTokenStore';
|
|||
|
|
import { FB_SERVER_STORE } from '../data/FbServerStore';
|
|||
|
|
import { FB_DEVICE_STORE } from '../data/FbDeviceStore';
|
|||
|
|
import { FB_SESSION } from '../data/FbSession';
|
|||
|
|
import { FB_KEY_STORE } from '../data/FbKeyStore';
|
|||
|
|
import { FbDb } from '../data/FbDb';
|
|||
|
|
import { FB_MODULE_TOKEN } from '../data/FbModuleRepo';
|
|||
|
|
import { FbSyncAllResult, syncAll } from '../data/FbSyncAll';
|
|||
|
|
|
|||
|
|
const DOMAIN: number = 0x0000;
|
|||
|
|
const TAG: string = 'FbBgSync';
|
|||
|
|
|
|||
|
|
/** 延迟任务的 workId（与 `module.json5` 里声明的 extension 名配套） */
|
|||
|
|
const WORK_ID: number = 2001;
|
|||
|
|
/** 延迟任务要拉起的扩展名（必须与 `module.json5` 的 `name` 逐字相同） */
|
|||
|
|
const WORK_ABILITY: string = 'FbSyncWorkAbility';
|
|||
|
|
/**
|
|||
|
|
* 延迟任务周期：**2 小时**。
|
|||
|
|
* 🔴 不是"用户想要的间隔"，而是系统"活跃分组"的**下限** —— 写小了会被压制，
|
|||
|
|
* 不报错、也不生效（详见文件头）。想更频繁只能靠服务卡片刷新（30 分钟那条）。
|
|||
|
|
*/
|
|||
|
|
const DEFERRED_CYCLE_MS: number = 2 * 60 * 60 * 1000;
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 卡片驱动同步的最小间隔。
|
|||
|
|
*
|
|||
|
|
* ⚠️ 与 `form_config.json` 的 `updateDuration: 1`（30 分钟）**必须对得上**：
|
|||
|
|
* 比 30 分钟还大的话，每两次卡片刷新就白白跳过一轮；
|
|||
|
|
* 太小则系统刷新一有漂移就会连着跑两遍。取 25 分钟，留 5 分钟容差。
|
|||
|
|
* （SyncCalendar 的取值与理由同此。）
|
|||
|
|
*/
|
|||
|
|
const CARD_MIN_GAP_MS: number = 25 * 60 * 1000;
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 卡片进程里**没申请到短时任务**时的软超时。
|
|||
|
|
*
|
|||
|
|
* 🔴 官方规定 `FormExtensionAbility` 生命周期回调返回后进程**仅存续约 10 秒**，
|
|||
|
|
* 超过就被回收（异步任务被硬杀半途）。这里主动在 9 秒收手，
|
|||
|
|
* 让"这一次"**干净地放弃**而不是被硬杀 —— 同步是幂等的，下轮会重试。
|
|||
|
|
*/
|
|||
|
|
const CARD_SOFT_TIMEOUT_MS: number = 9 * 1000;
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 卡片驱动同步可用的**总时长上限**。
|
|||
|
|
*
|
|||
|
|
* 🔴 短时任务单日总配额只有 10 分钟。若卡片每 30 分钟就把配额吃满，
|
|||
|
|
* "退后台那一次同步"（`onBackground` 申请）就会没配额可用 ——
|
|||
|
|
* 那是用户最需要它跑的时刻。⇒ 卡片这条路每次最多 60 秒。
|
|||
|
|
*/
|
|||
|
|
const CARD_MAX_TOTAL_MS: number = 60 * 1000;
|
|||
|
|
|
|||
|
|
/** 申请到短时任务后留出的余量：提前收手才能干净地 `cancelSuspendDelay` */
|
|||
|
|
const TRANSIENT_RESERVE_MS: number = 15 * 1000;
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 回前台 / 退后台补同步的**最小间隔**。
|
|||
|
|
*
|
|||
|
|
* 🔴 为什么必须有这道节流：`onForeground` / `onBackground` 会被**反复**触发
|
|||
|
|
* （切应用、下拉通知栏、锁屏解锁、多任务来回滑），
|
|||
|
|
* 每次都真跑一轮就是要用户为"切一下应用"付一次网络往返。
|
|||
|
|
* 而同步是增量的、又幂等 —— 5 分钟内基本不可能有新数据。
|
|||
|
|
* ⚠️ 取 5 分钟而不是 30：用户"去别的应用抄个东西再回来"是常见动作，
|
|||
|
|
* 超过 5 分钟的数据变化他大概率是想看到的（卡片驱动的 30 分钟那条只保证桌面）。
|
|||
|
|
*/
|
|||
|
|
const RESUME_MIN_GAP_MS: number = 5 * 60 * 1000;
|
|||
|
|
|
|||
|
|
const STORE_NAME: string = 'fb_bg_sync';
|
|||
|
|
const K_ENABLED: string = 'enabled';
|
|||
|
|
const K_LAST_CARD: string = 'last_card_sync_at';
|
|||
|
|
const K_LAST_ANY: string = 'last_sync_at';
|
|||
|
|
|
|||
|
|
/** 一次后台同步的结果（只用于日志，不做 UI） */
|
|||
|
|
export class FbBgSyncResult {
|
|||
|
|
/** 是否真的跑了同步（false = 未登录/未配置服务器/被节流，属正常跳过） */
|
|||
|
|
ran: boolean = false;
|
|||
|
|
/** 同步是否全部成功 */
|
|||
|
|
ok: boolean = false;
|
|||
|
|
done: number = 0;
|
|||
|
|
total: number = 0;
|
|||
|
|
/** 人话说明 */
|
|||
|
|
note: string = '';
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class FbBackgroundSyncImpl {
|
|||
|
|
/** 当前短时任务的 requestId（0 = 无）；退后台申请、回前台取消 */
|
|||
|
|
private transientId: number = 0;
|
|||
|
|
|
|||
|
|
/* ═══════════════════════════════════════════════════════════
|
|||
|
|
① 用户开关
|
|||
|
|
═══════════════════════════════════════════════════════════ */
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 是否开启"后台自动同步"。**默认开启**。
|
|||
|
|
*
|
|||
|
|
* 🔴 为什么默认开：用户要的是"打开 app 数据就是最新的"，
|
|||
|
|
* 默认关等于这个功能不存在。关掉是给"在意流量/电量"的人留的口子。
|
|||
|
|
* ⚠️ 读不到 preferences 时返回 true（宁可多同步一次，也不要静默失效）。
|
|||
|
|
*/
|
|||
|
|
async isEnabled(ctx: common.Context): Promise<boolean> {
|
|||
|
|
try {
|
|||
|
|
const p: preferences.Preferences = await preferences.getPreferences(ctx, STORE_NAME);
|
|||
|
|
const v: preferences.ValueType = await p.get(K_ENABLED, true);
|
|||
|
|
return typeof v === 'boolean' ? v : true;
|
|||
|
|
} catch (err) {
|
|||
|
|
hilog.warn(DOMAIN, TAG, '读后台同步开关失败（按开启处理）：%{public}s', JSON.stringify(err));
|
|||
|
|
return true;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 设置页切换开关：开 ⇒ 注册延迟任务；关 ⇒ 取消延迟任务。
|
|||
|
|
*
|
|||
|
|
* ⚠️ 关掉时**顺手取消短时任务**：用户刚说了不要后台同步，
|
|||
|
|
* 不该还留一个配额在用着。
|
|||
|
|
*/
|
|||
|
|
async setEnabled(ctx: common.Context, on: boolean): Promise<void> {
|
|||
|
|
try {
|
|||
|
|
const p: preferences.Preferences = await preferences.getPreferences(ctx, STORE_NAME);
|
|||
|
|
await p.put(K_ENABLED, on);
|
|||
|
|
await p.flush(); // 不 flush 等于没写（进程随时可能被回收）
|
|||
|
|
} catch (err) {
|
|||
|
|
hilog.warn(DOMAIN, TAG, '写后台同步开关失败：%{public}s', JSON.stringify(err));
|
|||
|
|
}
|
|||
|
|
if (on) {
|
|||
|
|
this.ensureWork(ctx);
|
|||
|
|
} else {
|
|||
|
|
this.cancelWork(ctx);
|
|||
|
|
this.cancelTransient();
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** 上次同步时间（毫秒；0 = 从没同步过）。设置页展示"上次同步"用。 */
|
|||
|
|
async lastSyncAt(ctx: common.Context): Promise<number> {
|
|||
|
|
return this.readNum(ctx, K_LAST_ANY);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* ═══════════════════════════════════════════════════════════
|
|||
|
|
② 延迟任务（长期后台）
|
|||
|
|
═══════════════════════════════════════════════════════════ */
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 注册（或刷新）延迟任务。**幂等**：重复调用只是让系统重排同一个 workId。
|
|||
|
|
*
|
|||
|
|
* ⚠️ `isPersisted: true` 是"重启后自动恢复"的开关，缺了它设备重启后
|
|||
|
|
* 这个任务就永久消失（用户不会知道，只会觉得"后台不同步了"）。
|
|||
|
|
* ⚠️ `networkType: NETWORK_TYPE_ANY`：没网时不必浪费一次唤醒。
|
|||
|
|
*/
|
|||
|
|
ensureWork(ctx: common.Context): void {
|
|||
|
|
/* ⚠️ 这里取包名用的是 `ctx.applicationInfo.name` —— **不是 `bundleName`**。
|
|||
|
|
`ApplicationInfo` 里没有 `bundleName` 这个字段（写了会编译报
|
|||
|
|
`Property 'bundleName' does not exist on type 'ApplicationInfo'`），
|
|||
|
|
而 `name` 的文档原文就是「Name of the application bundle. It corresponds to
|
|||
|
|
the **bundleName** field in the app.json5」⇒ 它就是包名。
|
|||
|
|
另一条路 `bundleManager.getBundleInfoForSelfSync().name` 也行，
|
|||
|
|
但那是**跨进程通信**（IPC，几毫秒到几十毫秒），在 onCreate 里不值得。
|
|||
|
|
⚠️ `WorkInfo.bundleName` 字段本身**必须**是包名 —— 写错了 `startWork`
|
|||
|
|
不报错、但永远不会回调（系统找不到这个扩展）。 */
|
|||
|
|
const info: workScheduler.WorkInfo = {
|
|||
|
|
workId: WORK_ID,
|
|||
|
|
bundleName: ctx.applicationInfo.name,
|
|||
|
|
abilityName: WORK_ABILITY,
|
|||
|
|
networkType: workScheduler.NetworkType.NETWORK_TYPE_ANY,
|
|||
|
|
isRepeat: true,
|
|||
|
|
isPersisted: true,
|
|||
|
|
repeatCycleTime: DEFERRED_CYCLE_MS,
|
|||
|
|
};
|
|||
|
|
try {
|
|||
|
|
workScheduler.startWork(info);
|
|||
|
|
hilog.info(DOMAIN, TAG, '延迟任务已注册：%{public}d 小时兜底同步', DEFERRED_CYCLE_MS / 3600000);
|
|||
|
|
} catch (err) {
|
|||
|
|
const e: BusinessError = err as BusinessError;
|
|||
|
|
hilog.warn(DOMAIN, TAG, '延迟任务注册失败：%{public}s %{public}s',
|
|||
|
|
(e.code !== undefined ? e.code.toString() : '-'), e.message);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** 取消延迟任务（用户关掉后台自动同步时） */
|
|||
|
|
cancelWork(ctx: common.Context): void {
|
|||
|
|
const info: workScheduler.WorkInfo = {
|
|||
|
|
workId: WORK_ID,
|
|||
|
|
bundleName: ctx.applicationInfo.name,
|
|||
|
|
abilityName: WORK_ABILITY,
|
|||
|
|
networkType: workScheduler.NetworkType.NETWORK_TYPE_ANY,
|
|||
|
|
isRepeat: true,
|
|||
|
|
isPersisted: true,
|
|||
|
|
repeatCycleTime: DEFERRED_CYCLE_MS,
|
|||
|
|
};
|
|||
|
|
try {
|
|||
|
|
workScheduler.stopWork(info, true);
|
|||
|
|
hilog.info(DOMAIN, TAG, '延迟任务已取消');
|
|||
|
|
} catch (err) {
|
|||
|
|
const e: BusinessError = err as BusinessError;
|
|||
|
|
hilog.warn(DOMAIN, TAG, '延迟任务取消失败：%{public}s', e.message);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* ═══════════════════════════════════════════════════════════
|
|||
|
|
③ 短时任务（退后台那一次）
|
|||
|
|
═══════════════════════════════════════════════════════════ */
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 申请短时任务，返回**实际可用时长（毫秒）**；失败返回 0。
|
|||
|
|
*
|
|||
|
|
* ⚠️ 只能在"应用处于前台"或"`onBackground` 回调里（5 秒内）"调用，
|
|||
|
|
* 其它时机会被系统拒绝（9900002 等）。被拒**不是 bug**，调用方退回软超时即可。
|
|||
|
|
* ⚠️ 已有短时任务在跑时**不重复申请** —— 重复申请会白白消耗当日配额。
|
|||
|
|
*/
|
|||
|
|
requestTransient(reason: string): number {
|
|||
|
|
if (this.transientId !== 0) {
|
|||
|
|
return 0;
|
|||
|
|
}
|
|||
|
|
try {
|
|||
|
|
const info: backgroundTaskManager.DelaySuspendInfo =
|
|||
|
|
backgroundTaskManager.requestSuspendDelay(reason, (): void => {
|
|||
|
|
// 超时回调：配额用尽，系统即将挂起。清状态，等下次前/退后台再申请
|
|||
|
|
hilog.info(DOMAIN, TAG, '短时任务超时（配额用尽），后台同步将被挂起');
|
|||
|
|
this.transientId = 0;
|
|||
|
|
});
|
|||
|
|
this.transientId = info.requestId;
|
|||
|
|
const actual: number = info.actualDelayTime !== undefined ? info.actualDelayTime : 0;
|
|||
|
|
hilog.info(DOMAIN, TAG, '短时任务已申请：剩余 %{public}d 秒', Math.round(actual / 1000));
|
|||
|
|
return actual;
|
|||
|
|
} catch (err) {
|
|||
|
|
const e: BusinessError = err as BusinessError;
|
|||
|
|
hilog.warn(DOMAIN, TAG, '短时任务申请失败（不影响使用）：%{public}s', e.message);
|
|||
|
|
return 0;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 取消短时任务，**归还当日配额**。
|
|||
|
|
*
|
|||
|
|
* 🔴 这一步不是可选的：配额一天只有 10 分钟，跑完不还，
|
|||
|
|
* 下一次"退后台同步"就会申请不到 —— 而用户只会看到"后台又不同步了"。
|
|||
|
|
*/
|
|||
|
|
cancelTransient(): void {
|
|||
|
|
if (this.transientId === 0) {
|
|||
|
|
return;
|
|||
|
|
}
|
|||
|
|
try {
|
|||
|
|
backgroundTaskManager.cancelSuspendDelay(this.transientId);
|
|||
|
|
hilog.info(DOMAIN, TAG, '短时任务已取消（归还配额）');
|
|||
|
|
} catch (err) {
|
|||
|
|
const e: BusinessError = err as BusinessError;
|
|||
|
|
hilog.warn(DOMAIN, TAG, '短时任务取消失败：%{public}s', e.message);
|
|||
|
|
}
|
|||
|
|
this.transientId = 0;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 回前台 / 退后台的**节流版**同步。
|
|||
|
|
*
|
|||
|
|
* 与 `runOnce` 的区别只有一处：距上次同步不到 `RESUME_MIN_GAP_MS` 就跳过。
|
|||
|
|
* 理由见常量说明（前后台回调会被反复触发，不节流等于"切一下应用打一次网络"）。
|
|||
|
|
*
|
|||
|
|
* ⚠️ 手动同步（顶栏那颗按钮）**不走这里** —— 用户明确点了就必须真的跑，
|
|||
|
|
* 不能被节流挡掉，否则他会以为"点了没反应"。
|
|||
|
|
*/
|
|||
|
|
async runOnceResumed(ctx: common.Context, tag: string): Promise<void> {
|
|||
|
|
try {
|
|||
|
|
const last: number = await this.readNum(ctx, K_LAST_ANY);
|
|||
|
|
const now: number = Date.now();
|
|||
|
|
if (last > 0 && now - last < RESUME_MIN_GAP_MS) {
|
|||
|
|
hilog.info(DOMAIN, TAG, '同步[%{public}s] 跳过：距上次仅 %{public}d 分钟',
|
|||
|
|
tag, Math.round((now - last) / 60000));
|
|||
|
|
return;
|
|||
|
|
}
|
|||
|
|
await this.runOnce(ctx, tag);
|
|||
|
|
} catch (err) {
|
|||
|
|
const e: BusinessError = err as BusinessError;
|
|||
|
|
hilog.warn(DOMAIN, TAG, '同步[%{public}s] 异常：%{public}s', tag, e.message);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* ═══════════════════════════════════════════════════════════
|
|||
|
|
④ 执行体（所有触发源共用）
|
|||
|
|
═══════════════════════════════════════════════════════════ */
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 在新进程里把"主进程启动时该做的事"补齐，再判断能不能同步。
|
|||
|
|
*
|
|||
|
|
* 🔴 后台扩展跑在**独立进程**里，`EntryAbility.onCreate` 那套初始化
|
|||
|
|
* 在这里**一步都没跑过** —— 见文件头"后台进程是另一个进程"那段。
|
|||
|
|
*
|
|||
|
|
* @returns true = 可以同步；false = 未登录 / 未配置服务器（正常跳过）
|
|||
|
|
*/
|
|||
|
|
private async prepare(ctx: common.Context): Promise<boolean> {
|
|||
|
|
try {
|
|||
|
|
await FB_TOKEN_STORE.init(ctx);
|
|||
|
|
await FB_SERVER_STORE.init(ctx);
|
|||
|
|
await FB_DEVICE_STORE.init(ctx);
|
|||
|
|
await FB_SESSION.init(ctx);
|
|||
|
|
// 数据密钥（附件解密用）。失败了不影响"拉数据"，只影响附件预览
|
|||
|
|
await FB_KEY_STORE.init(ctx);
|
|||
|
|
/* ⚠️ 通用缓存仓库靠注入拿令牌（它与令牌存储之间有循环 import 风险，
|
|||
|
|
见 `FbModuleRepo.FbModuleToken` 的说明）⇒ 新进程必须重新注入一次，
|
|||
|
|
否则 `module_cache` 那些模块永远拿不到令牌、全部 401。 */
|
|||
|
|
FB_MODULE_TOKEN.set((): string => FB_TOKEN_STORE.get());
|
|||
|
|
// 打开本地库：不开的话数据拉下来也存不住，白跑一趟网络
|
|||
|
|
await FbDb.inst().open(ctx);
|
|||
|
|
} catch (err) {
|
|||
|
|
hilog.warn(DOMAIN, TAG, '后台同步的准备步骤失败：%{public}s', JSON.stringify(err));
|
|||
|
|
// 继续往下走：也许只是某个非关键步骤失败（比如密钥库不支持）
|
|||
|
|
}
|
|||
|
|
if (FB_TOKEN_STORE.get() === '') {
|
|||
|
|
hilog.info(DOMAIN, TAG, '后台同步跳过：没有令牌（未登录）');
|
|||
|
|
return false;
|
|||
|
|
}
|
|||
|
|
if (FB_SERVER_STORE.get() === '') {
|
|||
|
|
hilog.info(DOMAIN, TAG, '后台同步跳过：没配置服务器地址');
|
|||
|
|
return false;
|
|||
|
|
}
|
|||
|
|
return true;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 跑一次完整同步。**永不抛错**。
|
|||
|
|
*
|
|||
|
|
* @param tag 触发来源（`deferred` / `transient` / `cardTick` / `foreground` / `netRecover`）
|
|||
|
|
*/
|
|||
|
|
async runOnce(ctx: common.Context, tag: string): Promise<FbBgSyncResult> {
|
|||
|
|
const r: FbBgSyncResult = new FbBgSyncResult();
|
|||
|
|
const t0: number = Date.now();
|
|||
|
|
try {
|
|||
|
|
if (!(await this.isEnabled(ctx))) {
|
|||
|
|
r.note = '后台自动同步已关闭';
|
|||
|
|
hilog.info(DOMAIN, TAG, '后台同步[%{public}s] 跳过：用户已关闭', tag);
|
|||
|
|
return r;
|
|||
|
|
}
|
|||
|
|
if (!(await this.prepare(ctx))) {
|
|||
|
|
r.note = '未登录或未配置服务器，跳过';
|
|||
|
|
return r;
|
|||
|
|
}
|
|||
|
|
r.ran = true;
|
|||
|
|
hilog.info(DOMAIN, TAG, '后台同步[%{public}s] 开始', tag);
|
|||
|
|
const res: FbSyncAllResult = await syncAll();
|
|||
|
|
r.ok = res.ok;
|
|||
|
|
r.done = res.done;
|
|||
|
|
r.total = res.total;
|
|||
|
|
r.note = res.note;
|
|||
|
|
await this.writeNum(ctx, K_LAST_ANY, Date.now());
|
|||
|
|
hilog.info(DOMAIN, TAG, '后台同步[%{public}s] 完成：%{public}d/%{public}d，耗时 %{public}d 秒',
|
|||
|
|
tag, res.done, res.total, Math.round((Date.now() - t0) / 1000));
|
|||
|
|
} catch (err) {
|
|||
|
|
/* 🔴 后台路径**必须吞掉所有异常**：抛出去没人接（没有 UI 栈），
|
|||
|
|
系统只会看到"扩展崩了"，而用户那边表现为"卡片变白 / 后台不同步"。 */
|
|||
|
|
const e: BusinessError = err as BusinessError;
|
|||
|
|
r.note = '同步异常：' + (e.message !== undefined ? e.message : JSON.stringify(err));
|
|||
|
|
hilog.warn(DOMAIN, TAG, '后台同步[%{public}s] 异常：%{public}s', tag, r.note);
|
|||
|
|
}
|
|||
|
|
return r;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* ⭐ **服务卡片定时刷新驱动**的同步（0.0.8 起唯一的"约 30 分钟"通道）。
|
|||
|
|
*
|
|||
|
|
* 为什么是卡片：`workScheduler` 周期被活跃分组压制到 ≥2 小时（见文件头），
|
|||
|
|
* 而卡片配了 `updateDuration: 1`（30 分钟）后系统会**每 30 分钟**回调一次
|
|||
|
|
* `onUpdateForm`，且不受活跃分组压制（每天上限 50 次）。
|
|||
|
|
*
|
|||
|
|
* ⚠️ 节流：系统刷新可能漂移或重入 ⇒ 用时间戳挡一道，保证两次真实同步
|
|||
|
|
* 之间至少间隔 `CARD_MIN_GAP_MS`。**先写时间戳再同步**，
|
|||
|
|
* 避免执行期间卡片再次刷新导致并发重入（两个进程同时拉同一批数据）。
|
|||
|
|
* ⚠️ 时间预算：优先申请短时任务把 10 秒窗口延长；申请不到就 9 秒收手。
|
|||
|
|
* 两种情况下都**主动放弃**而不是被硬杀 —— 同步幂等，下轮重试即可。
|
|||
|
|
*/
|
|||
|
|
async runThrottledByCard(ctx: common.Context): Promise<void> {
|
|||
|
|
try {
|
|||
|
|
const last: number = await this.readNum(ctx, K_LAST_CARD);
|
|||
|
|
const now: number = Date.now();
|
|||
|
|
if (last > 0 && now - last < CARD_MIN_GAP_MS) {
|
|||
|
|
hilog.info(DOMAIN, TAG, '卡片驱动同步：距上次仅 %{public}d 分钟，跳过',
|
|||
|
|
Math.round((now - last) / 60000));
|
|||
|
|
return;
|
|||
|
|
}
|
|||
|
|
await this.writeNum(ctx, K_LAST_CARD, now);
|
|||
|
|
|
|||
|
|
// 尝试把 10 秒窗口延长到最多 3 分钟（失败则退回 9 秒软超时）
|
|||
|
|
let budget: number = CARD_SOFT_TIMEOUT_MS;
|
|||
|
|
const granted: number = this.requestTransient('正在同步家书数据');
|
|||
|
|
if (granted > 0) {
|
|||
|
|
const usable: number = granted - TRANSIENT_RESERVE_MS;
|
|||
|
|
budget = usable > CARD_SOFT_TIMEOUT_MS ? usable : CARD_SOFT_TIMEOUT_MS;
|
|||
|
|
if (budget > CARD_MAX_TOTAL_MS) {
|
|||
|
|
budget = CARD_MAX_TOTAL_MS;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
hilog.info(DOMAIN, TAG, '卡片驱动同步：开始（预算 %{public}d 秒）', Math.round(budget / 1000));
|
|||
|
|
try {
|
|||
|
|
await this.raceWithBudget(this.runOnce(ctx, 'cardTick'), budget);
|
|||
|
|
} finally {
|
|||
|
|
// 无论成败都释放：① 归还配额 ② 避免超时不取消被系统强杀进程
|
|||
|
|
this.cancelTransient();
|
|||
|
|
}
|
|||
|
|
} catch (err) {
|
|||
|
|
const e: BusinessError = err as BusinessError;
|
|||
|
|
hilog.warn(DOMAIN, TAG, '卡片驱动同步异常：%{public}s', e.message);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 给一个异步任务套"时间预算"：超时就让调用方继续，**不杀**那个任务。
|
|||
|
|
*
|
|||
|
|
* ⚠️ 用 `Promise.race` 而不是 `AbortController`：这里的任务是**一串幂等的
|
|||
|
|
* 网络+落库**，中途掐断会留下"拉了一半"的中间态；让它自己在后台跑完，
|
|||
|
|
* 或者被系统回收（同样幂等），都更安全。
|
|||
|
|
*/
|
|||
|
|
private raceWithBudget(job: Promise<FbBgSyncResult>, budgetMs: number): Promise<void> {
|
|||
|
|
return new Promise<void>((resolve: () => void): void => {
|
|||
|
|
let settled: boolean = false;
|
|||
|
|
const fin = (): void => {
|
|||
|
|
if (!settled) {
|
|||
|
|
settled = true;
|
|||
|
|
resolve();
|
|||
|
|
}
|
|||
|
|
};
|
|||
|
|
job.then((): void => { fin(); }).catch((): void => { fin(); });
|
|||
|
|
setTimeout((): void => {
|
|||
|
|
if (!settled) {
|
|||
|
|
hilog.info(DOMAIN, TAG, '卡片驱动同步：时间预算用尽，主动收手（幂等，下轮重试）');
|
|||
|
|
}
|
|||
|
|
fin();
|
|||
|
|
}, budgetMs);
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* ---- preferences 小工具 ---- */
|
|||
|
|
|
|||
|
|
private async readNum(ctx: common.Context, key: string): Promise<number> {
|
|||
|
|
try {
|
|||
|
|
const p: preferences.Preferences = await preferences.getPreferences(ctx, STORE_NAME);
|
|||
|
|
const v: preferences.ValueType = await p.get(key, 0);
|
|||
|
|
return typeof v === 'number' ? v : 0;
|
|||
|
|
} catch (err) {
|
|||
|
|
return 0;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
private async writeNum(ctx: common.Context, key: string, val: number): Promise<void> {
|
|||
|
|
try {
|
|||
|
|
const p: preferences.Preferences = await preferences.getPreferences(ctx, STORE_NAME);
|
|||
|
|
await p.put(key, val);
|
|||
|
|
await p.flush();
|
|||
|
|
} catch (err) {
|
|||
|
|
hilog.warn(DOMAIN, TAG, '写 %{public}s 失败：%{public}s', key, JSON.stringify(err));
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export const FB_BG_SYNC: FbBackgroundSyncImpl = new FbBackgroundSyncImpl();
|