日程改为本地库按需查询,修掉每次进页面解析 9.3MB 的架构错误

## 用户指出的问题

「这个数据量很大,不是应该每次同步完了之后解包放在一个数据库里吗?
 然后点开日程,不就是把今天的日程从数据库里查出来吗?
 这个应该速度非常快才对呀!怎么能每次打开都要去读所有的数据呢?」

用户说得完全对。这是**架构错误**,上一轮我只做了算法层的局部优化
(把 O(n²) 改成 O(n)),没动"数据怎么存、怎么取"这个根本问题。

## 改前 vs 改后

改前:
    load() → module_cache 表读 **9.3MB 字符串**
           → JSON.parse **28628 个对象**
           → 全塞进 this.allEvents 内存数组
    渲染   → 在这 28628 条上遍历

`module_cache` 的设计注释本来写着「解析一遍毫秒级,可接受」——
那是按小数据量假设写的,日程涨到 2.8 万条后这个假设就破了。

改后:
    load() → ① `WHERE date BETWEEN ? AND ?`(走 idx_cal_date)→ 立刻渲染
             ② 后台拉全量 → 批量入库 → 重查当前范围
    渲染   → 只在**当前范围**那几十到几百条上遍历

## 改动

### FbSchema / FbDb:新增 cal_events 实体表

字段对齐 FbCalEvent(12 个)+ uid + fetched_at,三个索引:
- `idx_cal_date` —— 按日期查(最高频)
- `idx_cal_date_kind` —— 农历/节日按 kind 过滤
- `idx_cal_uid` —— 同步去重

⚠️ 主键不用服务端 `ref_id`:衍生条目(农历/节气/纪念日)的 ref_id **恒为 0**,
几万条全撞主键。用自增 rowid + (cal_id, uid) 唯一索引。
uid 由 kind|calId|evId|date|time|title哈希 组成。

⚠️ **建表语句与 migrate 两处都改了**,列名逐一比对一致
(这个坑本项目已踩 5 次,加了静态守卫钉住)。

### FbCalStore(新建):本地库读写

- `replaceAll(rows, stamp)` —— 事务内先 DELETE 再分批写(20 行/批,照
  FbMovieRepo 的实测结论,200 行会卡死)。整批替换而非逐条 upsert,
  否则服务端已删的条目会永远留在本地。
- `between(from,to)` / `ofDay(iso)` —— 页面真正用的查询
- `lunarBetween` —— 月视图 42 个格子只要农历文字,单独查比取全量再过滤快
- `count()` / `fetchedAt()` —— 判空与"数据新不新"

⚠️ 命名用 `FbCalStore` 而不是 `FbCalRepo`:后者已存在,是**接口读写**层
(create/update/remove/fetchBooks)。我第一版误覆盖了它,编译报 8 处错误后
从 git 恢复,改名为 Store 区分「本地库」和「接口」。

### FbCalendarPage

- `allEvents` → **`rangeEvents`**(改名强制提醒:这里不再是全量)
- `rangeOfView()` —— 算当前视图需要的日期区间
- `loadFromLocal()` —— 先查本地,有数据立刻渲染
- `persistAndRefresh()` —— 入库完成后重查,界面跟上最新数据
- `reloadRange()` + `@Monitor('showYear','showMonth','mode')` —— 翻月/切视图按需重查
- `rangeSeq` —— 防抖,避免旧结果覆盖新结果

## 验证

### 编译
`build_hap debug` → BUILD SUCCESSFUL

### 静态校验(34 项全过)
`_tooling/check_cal_db.js`,含最关键的两项:
- 建表与迁移**列名逐一相同**(15 列全对上)
- `load()` 里本地查询确实在远程同步**之前**

### 未验证
**真机实测未做**(设备未连接)。需要确认:
- 老库升级(v7→v8)是否顺利建表
- 首次进入(库空)要等全量拉取,之后进入应该秒开
- 翻月是否立刻有数据

## 过程中的一个失误

第一版把新仓储命名为 `FbCalRepo`,**覆盖了已存在的同名文件**。
编译立刻报 8 处 "has no exported member / does not exist on type"。
从 git 恢复原文件后改名 `FbCalStore`,避免了两层职责混在一个类里。

教训:新建文件前先查同名是否存在(`git status` 没报是因为该文件本就在版控里,
我 `cp` 上去把它改成"已修改"状态,看着像正常改动)。
This commit is contained in:
2026-11-03 09:59:40 +08:00
parent 57a0ddd5ad
commit 0397270e8b
4 changed files with 535 additions and 15 deletions
+286
View File
@@ -0,0 +1,286 @@
/**
* 岁月家 FamilyBook · 日程本地库(鸿蒙端)
*
* 🔴 2026-11-03 新建。起因是用户的一句话点破了架构错误:
* 「这个数据量很大,不是应该每次同步完了之后解包放在一个数据库里吗?
* 然后点开日程,不就是把今天的日程从数据库里查出来吗?
* 这个应该速度非常快才对呀!怎么能每次打开都要去读所有的数据呢?」
*
* 他说得完全对。改之前的样子:
* 日程 → `module_cache` 表(存整个接口 JSON 的**原样文本**,9.3MB)
* 每次进页面:读 9.3MB 字符串 → JSON.parse 28628 个对象 → 全塞进内存数组
* ⇒ 那"好几秒"就花在这里。
*
* `module_cache` 的设计注释本来写着「解析一遍毫秒级,可接受」——
* 那个判断建立在"数据量小"上,日程涨到 2.8 万条之后假设就破了。
*
* 改之后:
* 同步 → 批量写入 `cal_events` 实体表
* 页面 → `WHERE date = '2026-11-03'`(走索引,毫秒级)
*
* 这就是用户说的「把今天的查出来」。
*/
import { relationalStore } from '@kit.ArkData';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { FbDb, FbRow } from './FbDb';
import { FbCalEvent } from '../model/Types';
const DOMAIN: number = 0x0000;
const TAG: string = 'FbCalStore';
/**
* 每批写入的行数。
*
* ⚠️ 取 20 是照 `FbMovieRepo` 的**实测**结论:
* 一次塞 200 行时 `batchInsert` 卡死不返回,分批到 20 能正常完成。
* 日程有 2.8 万条,更必须分批 —— 别随手改大。
*/
const BATCH_SIZE: number = 20;
/** `cal_events` 表的列(建表语句与此处必须一致,见 FbSchema) */
const COLS: string = 'uid, ev_id, cal_id, title, date, time, end_time, '
+ 'cal_name, color, all_day, place, note, kind';
/**
* 日程仓库。
*
* 与 `FbMovieRepo` 同一定位:**UI 只读这里,不直接读接口**。
* 有网没网读的都是同一份本地数据,于是"断网可用""零等待"是天然成立的。
*/
export class FbCalStore {
private static _inst: FbCalStore | null = null;
static inst(): FbCalStore {
if (FbCalStore._inst === null) {
FbCalStore._inst = new FbCalStore();
}
return FbCalStore._inst;
}
private db: FbDb = FbDb.inst();
// ============================================================
// 写入
// ============================================================
/**
* 把一批日程**整体替换**进本地库。
*
* @param rows 解析好的日程(`parseCalendar` 的输出)
* @param stamp 本批数据的拉取时刻(秒)。用于区分"这一批"和"更早的残留"
*
* ⚠️ 先清空再整批写入,而不是逐条 upsert:
* 服务端每次给的是**这个时间窗口的全部数据**,
* 逐条 upsert 会让"服务端已删除的条目"永远留在本地。
* 整批替换才是对的语义。
*
* ⚠️ 全程在一个事务里:中途失败就整批回滚,
* 否则会出现"删了旧的、新的没写完"——空日历,比慢更糟。
*/
async replaceAll(rows: FbCalEvent[], stamp: number): Promise<void> {
if (!this.db.isReady()) {
hilog.warn(DOMAIN, TAG, '库未就绪,跳过写日程');
return;
}
const t0: number = Date.now();
await this.db.transaction(async (tx: relationalStore.Transaction): Promise<void> => {
// ① 清空旧数据
await tx.execute('DELETE FROM cal_events');
// ② 分批插入
for (let i = 0; i < rows.length; i += BATCH_SIZE) {
const chunk: FbCalEvent[] = rows.slice(i, i + BATCH_SIZE);
const buckets: relationalStore.ValuesBucket[] = [];
for (const e of chunk) {
const vb: relationalStore.ValuesBucket = {
'uid': this.uidOf(e),
'ev_id': e.id,
'cal_id': e.calId,
'title': e.title,
'date': e.date,
'time': e.time,
'end_time': e.endTime,
'cal_name': e.calName,
'color': e.color,
'all_day': e.allDay ? 1 : 0,
'place': e.place,
'note': e.note,
'kind': e.kind,
'fetched_at': stamp
};
buckets.push(vb);
}
// ⚠️ 用 tx.insert + 冲突替換:`(cal_id, uid)` 唯一索引会挡住重复
for (const vb of buckets) {
await tx.insert('cal_events', vb, relationalStore.ConflictResolution.ON_CONFLICT_REPLACE);
}
}
});
hilog.info(DOMAIN, TAG, '日程入库 %{public}d 条,耗时 %{public}dms',
rows.length, Date.now() - t0);
}
/**
* 给一条日程算稳定 UID。
*
* 为什么要自己造:服务端的 `ref_id` 对衍生条目(农历/节气/纪念日)**恒为 0**,
* 几万条全是 0,没法当唯一键。
*
* 组成:`kind|calId|evId|date|time|title的短哈希`
* · 自定义日程:evId 是真 id,天然唯一
* · 衍生条目:靠 kind + date 区分(农历每天一条,节气每年 24 条)
* · 再挂 title 的哈希,防止同一天同 kind 的多条(如两个节日)互相覆盖
*/
private uidOf(e: FbCalEvent): string {
const base: string = e.kind + '|' + e.calId + '|' + e.id + '|' + e.date + '|' + e.time;
// 简易 32 位哈希(FNV-1a):够用,不追求密码学强度
let h: number = 0x811c9dc5;
const src: string = base + '|' + e.title;
for (let i = 0; i < src.length; i++) {
h = h ^ src.charCodeAt(i);
h = (h * 0x01000193) >>> 0;
}
return base + '|' + h.toString(16);
}
// ============================================================
// 读取(页面真正用的就是这几个)
// ============================================================
/** 本地有没有数据(判断要不要等网络) */
async count(): Promise<number> {
if (!this.db.isReady()) {
return 0;
}
return await this.db.scalar('SELECT COUNT(*) FROM cal_events');
}
/** 库里的数据是什么时候拉的(用于显示"数据可能不新") */
async fetchedAt(): Promise<number> {
if (!this.db.isReady()) {
return 0;
}
return await this.db.scalar('SELECT COALESCE(MAX(fetched_at), 0) FROM cal_events');
}
/**
* 取某个日期区间的日程(含衍生条目)。
*
* `WHERE date BETWEEN ? AND ?` 走 `idx_cal_date`,几万条里取一个月是毫秒级。
*
* @param from 'YYYY-MM-DD'(含)
* @param to 'YYYY-MM-DD'(含)
*/
async between(from: string, to: string): Promise<FbCalEvent[]> {
if (!this.db.isReady()) {
return [];
}
const rows: FbRow[] = await this.db.queryRows(
'SELECT ' + COLS + ' FROM cal_events WHERE date >= ? AND date <= ? ORDER BY date, time',
[from, to]);
return this.toModels(rows);
}
/** 取某一天的全部条目 */
async ofDay(iso: string): Promise<FbCalEvent[]> {
if (!this.db.isReady()) {
return [];
}
const rows: FbRow[] = await this.db.queryRows(
'SELECT ' + COLS + ' FROM cal_events WHERE date = ? ORDER BY all_day DESC, time',
[iso]);
return this.toModels(rows);
}
/**
* 取某个日期区间的**农历/节日文字**(月视图每个格子要的那一小段)。
*
* ⚠️ 只要 `kind` 是那几类的,不要整个月所有条目 ——
* 月视图 42 个格子只需要"这天是什么农历/节日",
* 真日程由 `between()` 另取。分开查比取全量再过滤快得多。
*/
async lunarBetween(from: string, to: string): Promise<FbCalEvent[]> {
if (!this.db.isReady()) {
return [];
}
const rows: FbRow[] = await this.db.queryRows(
`SELECT ${COLS} FROM cal_events
WHERE date >= ? AND date <= ?
AND kind IN ('lunar', 'traditional', 'solarterm', 'holiday')
ORDER BY date`,
[from, to]);
return this.toModels(rows);
}
/** 某天的真日程(排除农历/节气这类衍生条目) */
async eventsOfDay(iso: string): Promise<FbCalEvent[]> {
if (!this.db.isReady()) {
return [];
}
const rows: FbRow[] = await this.db.queryRows(
`SELECT ${COLS} FROM cal_events
WHERE date = ?
AND kind NOT IN ('lunar', 'traditional', 'solarterm', 'holiday')
ORDER BY all_day DESC, time`,
[iso]);
return this.toModels(rows);
}
/** 库里最早的日期(决定能往前翻到哪) */
async minDate(): Promise<string> {
if (!this.db.isReady()) {
return '';
}
const r: FbRow | null = await this.db.queryOne(
'SELECT MIN(date) AS d FROM cal_events WHERE date <> \'\'', []);
return r === null ? '' : r.strOr('d', '');
}
/** 库里最晚的日期 */
async maxDate(): Promise<string> {
if (!this.db.isReady()) {
return '';
}
const r: FbRow | null = await this.db.queryOne(
'SELECT MAX(date) AS d FROM cal_events WHERE date <> \'\'', []);
return r === null ? '' : r.strOr('d', '');
}
/** 清空("重装/清缓存"时用) */
async clear(): Promise<void> {
if (!this.db.isReady()) {
return;
}
await this.db.exec('DELETE FROM cal_events');
}
// ============================================================
// 行 → 模型
// ============================================================
private toModels(rows: FbRow[]): FbCalEvent[] {
const out: FbCalEvent[] = [];
for (const r of rows) {
const e: FbCalEvent = {
id: r.num('ev_id', 0),
calId: r.num('cal_id', 0),
title: r.strOr('title', ''),
date: r.strOr('date', ''),
time: r.strOr('time', ''),
endTime: r.strOr('end_time', ''),
calName: r.strOr('cal_name', ''),
color: r.strOr('color', '') !== '' ? r.strOr('color', '') : '#A84A28',
allDay: r.num('all_day', 0) === 1,
place: r.strOr('place', ''),
note: r.strOr('note', ''),
kind: r.strOr('kind', '')
};
out.push(e);
}
return out;
}
}
+39
View File
@@ -362,6 +362,45 @@ export class FbDb {
}
}
// ---- v7 → v8:日程实体表(cal_events)----
// 🔴 2026-11-03:日程从 module_cache(存整包 JSON)改为实体表。
// 老库升级时这张表是空的;第一次同步会全量灌进去。
// ⚠️ 建表语句必须与 FbSchema 里**完全一致** —— 只改一处就是
// "新装有、老库没有"或者反过来(这个坑代码里已记 5 次)。
if (from < 8) {
const calDdl: string[] = [
`CREATE TABLE IF NOT EXISTS cal_events (
row_id INTEGER PRIMARY KEY AUTOINCREMENT,
uid TEXT NOT NULL DEFAULT '',
ev_id INTEGER NOT NULL DEFAULT 0,
cal_id INTEGER NOT NULL DEFAULT 0,
title TEXT NOT NULL DEFAULT '',
date TEXT NOT NULL DEFAULT '',
time TEXT NOT NULL DEFAULT '',
end_time TEXT NOT NULL DEFAULT '',
cal_name TEXT NOT NULL DEFAULT '',
color TEXT NOT NULL DEFAULT '',
all_day INTEGER NOT NULL DEFAULT 0,
place TEXT NOT NULL DEFAULT '',
note TEXT NOT NULL DEFAULT '',
kind TEXT NOT NULL DEFAULT '',
fetched_at INTEGER NOT NULL DEFAULT 0
)`,
`CREATE INDEX IF NOT EXISTS idx_cal_date ON cal_events (date)`,
`CREATE INDEX IF NOT EXISTS idx_cal_date_kind ON cal_events (date, kind)`,
`CREATE UNIQUE INDEX IF NOT EXISTS idx_cal_uid ON cal_events (cal_id, uid)`,
];
for (const sql of calDdl) {
try {
await store.executeSql(sql);
} catch (err) {
// 已经建过就跳过(迁移中途失败后重跑的场景)
hilog.warn(DOMAIN, TAG, '建 cal_events 跳过:%{public}s', JSON.stringify(err));
}
}
}
store.version = FB_DB_VERSION;
}
+45 -1
View File
@@ -37,7 +37,7 @@ export const FB_DB_NAME: string = 'familybook.db';
* 本地库**不能像服务端那样"每次启动都全量 ALTER 一遍"** ——
* 那是拿用户的手机当试验田。必须按版本逐步迁移。
*/
export const FB_DB_VERSION: number = 7;
export const FB_DB_VERSION: number = 8;
/**
* 建表语句。
@@ -315,6 +315,46 @@ export const FB_SCHEMA_SQL: string[] = [
payload TEXT NOT NULL DEFAULT '',
fetched_at INTEGER NOT NULL DEFAULT 0
)`,
// ---------- 日程实体表(v8 新增)----------
//
// 用户 2026-11-03 指出:「数据量这么大,不是应该同步完放进数据库,
// 点开日程就把今天的查出来吗?怎么能每次都去读全部数据?」
//
// 他说得对。原来日程走 `module_cache`(存 9.3MB JSON 原样文本),
// 每次进页面都要读 9.3MB + JSON.parse 28628 个对象 + 全塞内存。
// 那张表的注释本来说「解析一遍毫秒级,可接受」—— 那是按小数据量假设写的,
// 日程 2.8 万条之后这个假设就破了。
//
// ⇒ 日程单独建实体表(跟 events 表给观影用的思路一致),
// 同步时批量入库,页面按日期范围查。
//
// ⚠️ 为什么主键不用 id:
// 服务端 `ref_id` 对衍生条目(农历/节气/纪念日)恒为 0,
// 几万条全是 0 会撞主键。用自增 rowid + (cal_id, uid) 唯一索引。
`CREATE TABLE IF NOT EXISTS cal_events (
row_id INTEGER PRIMARY KEY AUTOINCREMENT,
uid TEXT NOT NULL DEFAULT '' COMMENT '服务端条目稳定标识',
ev_id INTEGER NOT NULL DEFAULT 0 COMMENT '服务端 ref_id(自定义日程才是真 id)',
cal_id INTEGER NOT NULL DEFAULT 0 COMMENT '所属日历本 id;0=衍生条目',
title TEXT NOT NULL DEFAULT '',
date TEXT NOT NULL DEFAULT '' COMMENT 'YYYY-MM-DD',
time TEXT NOT NULL DEFAULT '' COMMENT 'HH:mm;全天为空',
end_time TEXT NOT NULL DEFAULT '',
cal_name TEXT NOT NULL DEFAULT '',
color TEXT NOT NULL DEFAULT '',
all_day INTEGER NOT NULL DEFAULT 0,
place TEXT NOT NULL DEFAULT '',
note TEXT NOT NULL DEFAULT '',
kind TEXT NOT NULL DEFAULT '' COMMENT 'custom / lunar / holiday / anniv …',
fetched_at INTEGER NOT NULL DEFAULT 0 COMMENT '这批数据的拉取时刻(全量替换时用来防并发)'
)`,
// 按日期查是最高频的(「今天的日程」「本月」),必须索引
`CREATE INDEX IF NOT EXISTS idx_cal_date ON cal_events (date)`,
// 农历/节日按 kind 过滤(渲染日历时区分「真日程」和「衍生条目」)
`CREATE INDEX IF NOT EXISTS idx_cal_date_kind ON cal_events (date, kind)`,
// 同步时按 uid 去重/更新
`CREATE UNIQUE INDEX IF NOT EXISTS idx_cal_uid ON cal_events (cal_id, uid)`,
];
/** 建表语句分组说明(供日志/排查用) */
@@ -339,6 +379,10 @@ export const FB_TABLE_GROUPS: FbTableGroup[] = [
group: '名册',
tables: ['person_roster', 'person_tags']
},
{
group: '日程',
tables: ['cal_events']
},
{
group: '同步元数据(本地专有)',
tables: ['sync_state', 'pending_ops', 'module_sync', 'attach_cache']