@zhin.js/plugin-ledger 0.0.0-stage → 1.0.1

package/src/period.ts

@@ -0,0 +1,101 @@
+/**
+ * Calendar periods evaluated in the configured IANA timezone. Entries are compared by their
+ * local calendar date (YYYY-MM-DD), so daylight-saving shifts never move an entry into another day.
+ */
+
+export type LedgerPeriod = 'today' | 'week' | 'month' | 'all';
+
+const DAY_MS = 86_400_000;
+
+const PERIOD_LABELS: Readonly<Record<LedgerPeriod, string>> = {
+  today: '今日',
+  week: '本周',
+  month: '本月',
+  all: '全部',
+};
+
+export function periodLabel(period: LedgerPeriod): string {
+  return PERIOD_LABELS[period];
+}
+
+/** Maps a user-typed period word to a period; undefined when the word is not recognised. */
+export function parsePeriodWord(word: string | undefined, fallback: LedgerPeriod): LedgerPeriod | undefined {
+  if (word === undefined || word.trim() === '') return fallback;
+  const normalized = word.trim();
+  if (normalized === '今日' || normalized === '今天') return 'today';
+  if (normalized === '本周' || normalized === '这周') return 'week';
+  if (normalized === '本月' || normalized === '这个月') return 'month';
+  if (normalized === '全部' || normalized === '所有') return 'all';
+  return undefined;
+}
+
+function partsIn(instantMs: number, timeZone: string): Record<string, string> {
+  const formatter = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hourCycle: 'h23',
+  });
+  const parts: Record<string, string> = {};
+  for (const part of formatter.formatToParts(instantMs)) parts[part.type] = part.value;
+  return parts;
+}
+
+/** Local calendar date `YYYY-MM-DD` of an instant in a timezone. */
+export function localDateKey(instantMs: number, timeZone: string): string {
+  const parts = partsIn(instantMs, timeZone);
+  return `${parts.year}-${parts.month}-${parts.day}`;
+}
+
+/** Local wall-clock time `HH:MM` of an instant in a timezone. */
+export function localTimeKey(instantMs: number, timeZone: string): string {
+  const parts = partsIn(instantMs, timeZone);
+  return `${parts.hour}:${parts.minute}`;
+}
+
+function dateKeyToUtcMs(dateKey: string): number {
+  const [year, month, day] = dateKey.split('-').map(Number);
+  return Date.UTC(year!, month! - 1, day!);
+}
+
+function utcMsToDateKey(utcMs: number): string {
+  return new Date(utcMs).toISOString().slice(0, 10);
+}
+
+/** Monday of the ISO week containing a local date. */
+export function weekStartKey(dateKey: string): string {
+  const utcMs = dateKeyToUtcMs(dateKey);
+  const dayOfWeek = new Date(utcMs).getUTCDay();
+  const daysSinceMonday = (dayOfWeek + 6) % 7;
+  return utcMsToDateKey(utcMs - daysSinceMonday * DAY_MS);
+}
+
+/** Sunday that ends the ISO week starting on `weekStart`. */
+export function weekEndKey(weekStart: string): string {
+  return utcMsToDateKey(dateKeyToUtcMs(weekStart) + 6 * DAY_MS);
+}
+
+/** Whether an entry made at `entryMs` falls in `period` as seen at `nowMs`. */
+export function isInPeriod(entryMs: number, nowMs: number, period: LedgerPeriod, timeZone: string): boolean {
+  if (period === 'all') return true;
+  const entryDate = localDateKey(entryMs, timeZone);
+  const today = localDateKey(nowMs, timeZone);
+  if (period === 'today') return entryDate === today;
+  if (period === 'month') return entryDate.slice(0, 7) === today.slice(0, 7);
+  return weekStartKey(entryDate) === weekStartKey(today);
+}
+
+/** Human-readable range for a period header, e.g. `2026-10-19 ~ 2026-10-25`. */
+export function describePeriodRange(nowMs: number, period: LedgerPeriod, timeZone: string): string {
+  const today = localDateKey(nowMs, timeZone);
+  if (period === 'today') return today;
+  if (period === 'month') return today.slice(0, 7);
+  if (period === 'week') {
+    const start = weekStartKey(today);
+    return `${start} ~ ${weekEndKey(start)}`;
+  }
+  return '全部记录';
+}

package/src/report-format.ts

@@ -0,0 +1,125 @@
+import { formatCents, MASKED_AMOUNT } from './money.js';
+import { describePeriodRange, localDateKey, periodLabel, type LedgerPeriod } from './period.js';
+import type { LedgerEntry } from './store.js';
+
+/** Total, entry count and share for one category. */
+export interface CategoryTotal {
+  readonly category: string;
+  readonly totalCents: number;
+  readonly count: number;
+  readonly largestCents: number;
+}
+
+export interface PeriodSummary {
+  readonly period: LedgerPeriod;
+  readonly range: string;
+  readonly totalCents: number;
+  readonly count: number;
+  readonly categories: readonly CategoryTotal[];
+}
+
+/** A reply in two versions: the full one for the owner, the masked one for public conversations. */
+export interface LedgerReply {
+  readonly full: string;
+  readonly masked: string;
+}
+
+/** Groups entries by category, largest total first (ties by name for a stable order). */
+export function totalsByCategory(entries: readonly LedgerEntry[]): CategoryTotal[] {
+  const byCategory = new Map<string, { totalCents: number; count: number; largestCents: number }>();
+  for (const entry of entries) {
+    const current = byCategory.get(entry.category) ?? { totalCents: 0, count: 0, largestCents: 0 };
+    current.totalCents += entry.amountCents;
+    current.count += 1;
+    current.largestCents = Math.max(current.largestCents, entry.amountCents);
+    byCategory.set(entry.category, current);
+  }
+  const totals = [...byCategory.entries()].map(([category, value]) => ({ category, ...value }));
+  totals.sort((left, right) => right.totalCents - left.totalCents || left.category.localeCompare(right.category));
+  return totals;
+}
+
+export function summarize(entries: readonly LedgerEntry[], period: LedgerPeriod, nowMs: number, timeZone: string): PeriodSummary {
+  let totalCents = 0;
+  for (const entry of entries) totalCents += entry.amountCents;
+  return {
+    period,
+    range: describePeriodRange(nowMs, period, timeZone),
+    totalCents,
+    count: entries.length,
+    categories: totalsByCategory(entries),
+  };
+}
+
+/** Share of the total with one decimal, computed from integers. */
+function sharePercent(partCents: number, totalCents: number): string {
+  if (totalCents === 0) return '0';
+  const tenths = Math.round((partCents * 1000) / totalCents);
+  return `${Math.floor(tenths / 10)}.${tenths % 10}`;
+}
+
+export function formatPeriodSummary(summary: PeriodSummary): LedgerReply {
+  const label = periodLabel(summary.period);
+  if (summary.count === 0) {
+    const empty = `📒 ${label}还没有记账（${summary.range}）`;
+    return { full: empty, masked: empty };
+  }
+  const header = `📒 ${label}消费（${summary.range}）`;
+  const fullLines = [header, `合计 ${formatCents(summary.totalCents)} · ${summary.count} 笔`];
+  const maskedLines = [header, `合计 ${MASKED_AMOUNT} · ${summary.count} 笔`];
+  for (const category of summary.categories) {
+    const share = sharePercent(category.totalCents, summary.totalCents);
+    fullLines.push(`· ${category.category} ${formatCents(category.totalCents)}（${category.count} 笔，${share}%）`);
+    maskedLines.push(`· ${category.category} ${MASKED_AMOUNT}（${category.count} 笔）`);
+  }
+  return { full: fullLines.join('\n'), masked: maskedLines.join('\n') };
+}
+
+export function formatCategoryStatistics(summary: PeriodSummary): LedgerReply {
+  const label = periodLabel(summary.period);
+  if (summary.count === 0) {
+    const empty = `📊 ${label}没有可统计的记账（${summary.range}）`;
+    return { full: empty, masked: empty };
+  }
+  const header = `📊 分类统计 · ${label}（${summary.range}）`;
+  const fullLines = [header];
+  const maskedLines = [header];
+  for (const category of summary.categories) {
+    const averageCents = Math.round(category.totalCents / category.count);
+    const share = sharePercent(category.totalCents, summary.totalCents);
+    fullLines.push(`· ${category.category}：合计 ${formatCents(category.totalCents)}，${category.count} 笔，平均 ${formatCents(averageCents)}，最大 ${formatCents(category.largestCents)}，占比 ${share}%`);
+    maskedLines.push(`· ${category.category}：${category.count} 笔，金额已隐藏`);
+  }
+  fullLines.push(`共 ${summary.categories.length} 个类别 · 合计 ${formatCents(summary.totalCents)}`);
+  maskedLines.push(`共 ${summary.categories.length} 个类别`);
+  return { full: fullLines.join('\n'), masked: maskedLines.join('\n') };
+}
+
+export const MAX_LISTED_ENTRIES = 20;
+
+/** Newest first, with `#id` so users can find what to delete. */
+export function formatEntryList(entries: readonly LedgerEntry[], period: LedgerPeriod, nowMs: number, timeZone: string): LedgerReply {
+  const label = periodLabel(period);
+  const range = describePeriodRange(nowMs, period, timeZone);
+  if (entries.length === 0) {
+    const empty = `🧾 ${label}没有账目（${range}）`;
+    return { full: empty, masked: empty };
+  }
+  const newestFirst = [...entries].sort((left, right) => right.createdAt - left.createdAt || right.seq - left.seq);
+  const shown = newestFirst.slice(0, MAX_LISTED_ENTRIES);
+  const header = `🧾 ${label}账单（${range}）`;
+  const fullLines = [header];
+  const maskedLines = [header];
+  for (const entry of shown) {
+    const date = localDateKey(entry.createdAt, timeZone).slice(5);
+    const note = entry.note ? ` ${entry.note}` : '';
+    fullLines.push(`#${entry.seq} ${date} ${entry.category} ${formatCents(entry.amountCents)}${note}`);
+    maskedLines.push(`#${entry.seq} ${date} ${entry.category} ${MASKED_AMOUNT}`);
+  }
+  if (newestFirst.length > shown.length) {
+    const more = `……另有 ${newestFirst.length - shown.length} 笔未显示`;
+    fullLines.push(more);
+    maskedLines.push(more);
+  }
+  return { full: fullLines.join('\n'), masked: maskedLines.join('\n') };
+}

package/src/runtime.ts

@@ -0,0 +1,4 @@
+import { createToken } from 'zhin.js';
+import type { LedgerService } from './service.js';
+
+export const ledgerServiceToken = createToken<LedgerService>('zhin.ledger.service', 'Personal expense ledger');

package/src/service.ts

@@ -0,0 +1,217 @@
+import { getLogger, type DeliveryTarget, type OutboundHost, type PluginDatabaseHost } from 'zhin.js';
+import type { ResolvedLedgerConfig } from './config.js';
+import { parseEntryInput } from './entry-input.js';
+import type { LedgerCaller } from './identity.js';
+import { formatCents, MASKED_AMOUNT } from './money.js';
+import { isInPeriod, localDateKey, localTimeKey, periodLabel, type LedgerPeriod } from './period.js';
+import {
+  formatCategoryStatistics,
+  formatEntryList,
+  formatPeriodSummary,
+  summarize,
+  type LedgerReply,
+} from './report-format.js';
+import { LedgerStore, type LedgerEntry } from './store.js';
+
+const logger = getLogger('ledger');
+
+export type DailyReportAction = 'on' | 'off' | 'status';
+
+export interface LedgerServiceOptions {
+  /** Wall clock; tests pass a fake. */
+  readonly now?: () => number;
+}
+
+/**
+ * Personal expense ledger. Every operation is scoped to the caller's own `ownerKey`.
+ *
+ * Group privacy: replies that contain amounts go to the caller's private chat when the platform
+ * can deliver there (`OutboundHost.sendTarget` exists and the send succeeds). Otherwise the
+ * group gets the masked version. This is a capability check, not a per-platform list.
+ */
+export class LedgerService {
+  readonly #store: LedgerStore;
+  readonly #outbound: OutboundHost | undefined;
+  readonly #config: ResolvedLedgerConfig;
+  readonly #now: () => number;
+  /** Serialises writes per user so two quick `记` commands never share an `#id`. */
+  readonly #userQueues = new Map<string, Promise<unknown>>();
+  /** Private targets already saved this process, to skip redundant writes. */
+  readonly #knownPrivate = new Map<string, string>();
+
+  constructor(database: PluginDatabaseHost, outbound: OutboundHost | undefined, config: ResolvedLedgerConfig, options: LedgerServiceOptions = {}) {
+    this.#store = new LedgerStore(database);
+    this.#outbound = outbound;
+    this.#config = config;
+    this.#now = options.now ?? (() => Date.now());
+  }
+
+  #withUserLock<T>(ownerKey: string, operation: () => Promise<T>): Promise<T> {
+    const previous = this.#userQueues.get(ownerKey) ?? Promise.resolve();
+    const next = previous.then(operation, operation);
+    const settled = next.catch(() => undefined);
+    this.#userQueues.set(ownerKey, settled);
+    void settled.then(() => {
+      if (this.#userQueues.get(ownerKey) === settled) this.#userQueues.delete(ownerKey);
+    });
+    return next;
+  }
+
+  /**
+   * Some platforms (Discord, Lark, Slack, ...) address a private chat by a conversation id that is
+   * not the user id. When the user talks to the bot in private we save that real conversation and
+   * use it for later private deliveries; until then the user id is the best available guess.
+   */
+  async #rememberPrivate(caller: LedgerCaller): Promise<void> {
+    if (!caller.isPrivate) return;
+    const raw = JSON.stringify(caller.conversation);
+    if (this.#knownPrivate.get(caller.ownerKey) === raw) return;
+    try {
+      await this.#store.setPrivateTarget(caller.ownerKey, caller.conversation);
+      this.#knownPrivate.set(caller.ownerKey, raw);
+    } catch (error) {
+      logger.warn(`saving private target failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async #privateTargetOf(caller: LedgerCaller): Promise<DeliveryTarget> {
+    if (caller.isPrivate) return caller.conversation;
+    return (await this.#store.getPrivateTarget(caller.ownerKey)) ?? caller.privateTarget;
+  }
+
+  async addEntry(caller: LedgerCaller, text: string): Promise<string> {
+    await this.#rememberPrivate(caller);
+    const parsed = parseEntryInput(text);
+    if (!parsed.ok) return parsed.reason;
+    const { category, amountCents, note } = parsed.entry;
+    const seq = await this.#withUserLock(caller.ownerKey, async () => {
+      const reserved = await this.#store.reserveSequence(caller.ownerKey);
+      await this.#store.insertEntry({
+        ownerKey: caller.ownerKey,
+        seq: reserved,
+        category,
+        amountCents,
+        note,
+        createdAt: this.#now(),
+      });
+      return reserved;
+    });
+    const amount = caller.isPrivate ? formatCents(amountCents) : MASKED_AMOUNT;
+    const noteText = note ? ` · ${note}` : '';
+    return `✅ 已记账 #${seq} · ${category} ${amount}${noteText}`;
+  }
+
+  async deleteEntry(caller: LedgerCaller, seq: number): Promise<string> {
+    await this.#rememberPrivate(caller);
+    return this.#withUserLock(caller.ownerKey, async () => {
+      const entry = await this.#store.findEntry(caller.ownerKey, seq);
+      if (!entry) return `没有找到你的账目 #${seq}（只能删除自己的记账，可用「账单」查看编号）`;
+      await this.#store.deleteEntry(caller.ownerKey, seq);
+      const amount = caller.isPrivate ? formatCents(entry.amountCents) : MASKED_AMOUNT;
+      return `🗑️ 已删除 #${seq} · ${entry.category} ${amount}`;
+    });
+  }
+
+  async #entriesIn(ownerKey: string, period: LedgerPeriod): Promise<LedgerEntry[]> {
+    const nowMs = this.#now();
+    const entries = await this.#store.listEntries(ownerKey);
+    return entries.filter((entry) => isInPeriod(entry.createdAt, nowMs, period, this.#config.timezone));
+  }
+
+  async periodSummary(caller: LedgerCaller, period: LedgerPeriod): Promise<string> {
+    const entries = await this.#entriesIn(caller.ownerKey, period);
+    const reply = formatPeriodSummary(summarize(entries, period, this.#now(), this.#config.timezone));
+    return this.#deliver(caller, reply, `${periodLabel(period)}消费`);
+  }
+
+  async categoryStatistics(caller: LedgerCaller, period: LedgerPeriod): Promise<string> {
+    const entries = await this.#entriesIn(caller.ownerKey, period);
+    const reply = formatCategoryStatistics(summarize(entries, period, this.#now(), this.#config.timezone));
+    return this.#deliver(caller, reply, '分类统计');
+  }
+
+  async listEntries(caller: LedgerCaller, period: LedgerPeriod): Promise<string> {
+    const entries = await this.#entriesIn(caller.ownerKey, period);
+    const reply = formatEntryList(entries, period, this.#now(), this.#config.timezone);
+    return this.#deliver(caller, reply, `${periodLabel(period)}账单`);
+  }
+
+  /** Private chat: full reply. Group/channel: try a private message, else the masked reply. */
+  async #deliver(caller: LedgerCaller, reply: LedgerReply, title: string): Promise<string> {
+    if (caller.isPrivate) {
+      await this.#rememberPrivate(caller);
+      return reply.full;
+    }
+    if (reply.full === reply.masked) return reply.full;
+    const delivered = await this.#sendPrivately(caller, reply.full);
+    if (delivered) return `🔒 ${title}已私信发送给你`;
+    return `${reply.masked}\n（群聊中金额已隐藏，私聊我可查看完整金额）`;
+  }
+
+  async #sendPrivately(caller: LedgerCaller, content: string): Promise<boolean> {
+    const sendTarget = this.#outbound?.sendTarget;
+    if (!sendTarget) return false;
+    try {
+      await sendTarget.call(this.#outbound, await this.#privateTargetOf(caller), content);
+      return true;
+    } catch (error) {
+      logger.debug(`private delivery unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    }
+  }
+
+  async dailyReport(caller: LedgerCaller, action: DailyReportAction): Promise<string> {
+    await this.#rememberPrivate(caller);
+    const reportTime = this.#config.reportTime;
+    const user = await this.#store.getUser(caller.ownerKey);
+    if (action === 'status') {
+      if (user?.reportEnabled) return `记账日报已开启：每天 ${reportTime}（${this.#config.timezone}）私信发送当天消费`;
+      return '记账日报未开启。发送「记账日报 开启」订阅';
+    }
+    if (action === 'off') {
+      await this.#store.setReport(caller.ownerKey, false, undefined, user?.lastReportDate ?? '');
+      return '已关闭记账日报';
+    }
+    if (!this.#outbound?.sendTarget) return '当前环境不支持主动私信，无法开启记账日报';
+    const confirmation = `已开启记账日报：每天 ${reportTime}（${this.#config.timezone}）私信发送当天消费。发送「记账日报 关闭」取消`;
+    if (!caller.isPrivate) {
+      const reachable = await this.#sendPrivately(caller, confirmation);
+      if (!reachable) return '无法私信你，请先私聊我后再发送「记账日报 开启」';
+    }
+    const nowMs = this.#now();
+    const today = localDateKey(nowMs, this.#config.timezone);
+    const alreadyPastReportTime = localTimeKey(nowMs, this.#config.timezone) >= reportTime;
+    const lastReportDate = alreadyPastReportTime ? today : '';
+    await this.#store.setReport(caller.ownerKey, true, await this.#privateTargetOf(caller), lastReportDate);
+    return caller.isPrivate ? confirmation : '🔒 已开启记账日报，确认消息已私信发送给你';
+  }
+
+  /**
+   * Called every minute by the schedule. Once the local time reaches `reportTime`, each subscriber
+   * who has not had today's report gets it in their private chat. A failed delivery is logged and
+   * not retried that day, so an unreachable user is not messaged every minute.
+   */
+  async runDailyReports(): Promise<number> {
+    const nowMs = this.#now();
+    const timezone = this.#config.timezone;
+    if (localTimeKey(nowMs, timezone) < this.#config.reportTime) return 0;
+    const today = localDateKey(nowMs, timezone);
+    const subscribers = await this.#store.listReportSubscribers();
+    let sent = 0;
+    for (const subscriber of subscribers) {
+      if (subscriber.lastReportDate === today) continue;
+      await this.#store.markReported(subscriber.ownerKey, today);
+      if (!subscriber.reportTarget || !this.#outbound?.sendTarget) continue;
+      const entries = await this.#entriesIn(subscriber.ownerKey, 'today');
+      if (entries.length === 0 && !this.#config.reportWhenEmpty) continue;
+      const summary = formatPeriodSummary(summarize(entries, 'today', nowMs, timezone));
+      try {
+        await this.#outbound.sendTarget(subscriber.reportTarget, `🌙 记账日报\n${summary.full}`);
+        sent += 1;
+      } catch (error) {
+        logger.warn(`daily report delivery failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return sent;
+  }
+}

package/src/store.ts

@@ -0,0 +1,195 @@
+import type { DatabaseHostModel, DeliveryTarget, PluginDatabaseHost } from 'zhin.js';
+
+export const ENTRY_TABLE = 'ledger_entries';
+export const USER_TABLE = 'ledger_users';
+/** Separate table: existing databases only run CREATE TABLE IF NOT EXISTS, so new columns on `ledger_users` would never appear. */
+export const PRIVATE_TARGET_TABLE = 'ledger_private_targets';
+
+/** One expense. `seq` is the per-user number shown as `#id`; amounts are integer cents. */
+export interface LedgerEntry {
+  readonly ownerKey: string;
+  readonly seq: number;
+  readonly category: string;
+  readonly amountCents: number;
+  readonly note: string;
+  readonly createdAt: number;
+}
+
+/** Per-user settings: the next entry number and the opt-in daily report. */
+export interface LedgerUserRecord {
+  readonly ownerKey: string;
+  readonly nextSeq: number;
+  readonly reportEnabled: boolean;
+  readonly reportTarget: DeliveryTarget | undefined;
+  readonly lastReportDate: string;
+}
+
+/** Registers both tables; called from `setup()` before the database starts. */
+export function defineLedgerTables(database: Pick<PluginDatabaseHost, 'define'>): void {
+  database.define(ENTRY_TABLE, {
+    owner_key: { type: 'text', nullable: false },
+    seq: { type: 'integer', nullable: false },
+    category: { type: 'text', nullable: false },
+    amount_cents: { type: 'integer', nullable: false },
+    note: { type: 'text', default: '' },
+    created_at: { type: 'text', nullable: false },
+  });
+  database.define(USER_TABLE, {
+    owner_key: { type: 'text', nullable: false },
+    next_seq: { type: 'integer', default: 1 },
+    report_enabled: { type: 'integer', default: 0 },
+    report_target: { type: 'text', default: '' },
+    last_report_date: { type: 'text', default: '' },
+  });
+  database.define(PRIVATE_TARGET_TABLE, {
+    owner_key: { type: 'text', nullable: false },
+    target: { type: 'text', nullable: false },
+  });
+}
+
+function toEntry(row: Record<string, unknown>): LedgerEntry {
+  return {
+    ownerKey: String(row.owner_key),
+    seq: Number(row.seq),
+    category: String(row.category),
+    amountCents: Number(row.amount_cents),
+    note: String(row.note ?? ''),
+    createdAt: Date.parse(String(row.created_at)),
+  };
+}
+
+function parseTarget(raw: unknown): DeliveryTarget | undefined {
+  if (typeof raw !== 'string' || raw === '') return undefined;
+  try {
+    return JSON.parse(raw) as DeliveryTarget;
+  } catch {
+    return undefined;
+  }
+}
+
+function toUser(row: Record<string, unknown>): LedgerUserRecord {
+  return {
+    ownerKey: String(row.owner_key),
+    nextSeq: Number(row.next_seq ?? 1),
+    reportEnabled: Number(row.report_enabled ?? 0) === 1,
+    reportTarget: parseTarget(row.report_target),
+    lastReportDate: String(row.last_report_date ?? ''),
+  };
+}
+
+/**
+ * Every query filters on `owner_key`, the caller's own identity, so one user can never read,
+ * number or delete another user's entries. Models are looked up per call because the
+ * database only starts after `setup()`.
+ */
+export class LedgerStore {
+  readonly #database: PluginDatabaseHost;
+
+  constructor(database: PluginDatabaseHost) {
+    this.#database = database;
+  }
+
+  #model(table: string): DatabaseHostModel {
+    const model = this.#database.models.get(table);
+    if (!model) throw new Error(`记账数据表 ${table} 不可用`);
+    return model;
+  }
+
+  async getUser(ownerKey: string): Promise<LedgerUserRecord | undefined> {
+    const rows = await this.#model(USER_TABLE)
+      .select('owner_key', 'next_seq', 'report_enabled', 'report_target', 'last_report_date')
+      .where({ owner_key: ownerKey });
+    const first = rows[0];
+    return first ? toUser(first) : undefined;
+  }
+
+  async #ensureUser(ownerKey: string): Promise<LedgerUserRecord> {
+    const existing = await this.getUser(ownerKey);
+    if (existing) return existing;
+    await this.#model(USER_TABLE).insert({
+      owner_key: ownerKey,
+      next_seq: 1,
+      report_enabled: 0,
+      report_target: '',
+      last_report_date: '',
+    });
+    return { ownerKey, nextSeq: 1, reportEnabled: false, reportTarget: undefined, lastReportDate: '' };
+  }
+
+  /** Reserves the next per-user entry number. Callers serialise per user (see LedgerService). */
+  async reserveSequence(ownerKey: string): Promise<number> {
+    const user = await this.#ensureUser(ownerKey);
+    const reserved = user.nextSeq;
+    await this.#model(USER_TABLE).update({ next_seq: reserved + 1 }).where({ owner_key: ownerKey });
+    return reserved;
+  }
+
+  async insertEntry(entry: LedgerEntry): Promise<void> {
+    await this.#model(ENTRY_TABLE).insert({
+      owner_key: entry.ownerKey,
+      seq: entry.seq,
+      category: entry.category,
+      amount_cents: entry.amountCents,
+      note: entry.note,
+      created_at: new Date(entry.createdAt).toISOString(),
+    });
+  }
+
+  async listEntries(ownerKey: string): Promise<LedgerEntry[]> {
+    const rows = await this.#model(ENTRY_TABLE)
+      .select('owner_key', 'seq', 'category', 'amount_cents', 'note', 'created_at')
+      .where({ owner_key: ownerKey });
+    return rows.map(toEntry);
+  }
+
+  async findEntry(ownerKey: string, seq: number): Promise<LedgerEntry | undefined> {
+    const rows = await this.#model(ENTRY_TABLE)
+      .select('owner_key', 'seq', 'category', 'amount_cents', 'note', 'created_at')
+      .where({ owner_key: ownerKey, seq });
+    const first = rows[0];
+    return first ? toEntry(first) : undefined;
+  }
+
+  async deleteEntry(ownerKey: string, seq: number): Promise<void> {
+    await this.#model(ENTRY_TABLE).delete().where({ owner_key: ownerKey, seq });
+  }
+
+  async setReport(ownerKey: string, enabled: boolean, target: DeliveryTarget | undefined, lastReportDate: string): Promise<void> {
+    await this.#ensureUser(ownerKey);
+    await this.#model(USER_TABLE).update({
+      report_enabled: enabled ? 1 : 0,
+      report_target: target ? JSON.stringify(target) : '',
+      last_report_date: lastReportDate,
+    }).where({ owner_key: ownerKey });
+  }
+
+  /** The real private conversation saved when the user talked to the bot in private. */
+  async getPrivateTarget(ownerKey: string): Promise<DeliveryTarget | undefined> {
+    const rows = await this.#model(PRIVATE_TARGET_TABLE).select('owner_key', 'target').where({ owner_key: ownerKey });
+    return parseTarget(rows[0]?.target);
+  }
+
+  /** Saves the real private conversation; an enabled daily report follows it. */
+  async setPrivateTarget(ownerKey: string, target: DeliveryTarget): Promise<void> {
+    const raw = JSON.stringify(target);
+    const model = this.#model(PRIVATE_TARGET_TABLE);
+    const existing = await model.select('owner_key', 'target').where({ owner_key: ownerKey });
+    if (existing.length > 0) await model.update({ target: raw }).where({ owner_key: ownerKey });
+    else await model.insert({ owner_key: ownerKey, target: raw });
+    const user = await this.getUser(ownerKey);
+    if (user?.reportEnabled) {
+      await this.#model(USER_TABLE).update({ report_target: raw }).where({ owner_key: ownerKey });
+    }
+  }
+
+  async listReportSubscribers(): Promise<LedgerUserRecord[]> {
+    const rows = await this.#model(USER_TABLE)
+      .select('owner_key', 'next_seq', 'report_enabled', 'report_target', 'last_report_date')
+      .where({ report_enabled: 1 });
+    return rows.map(toUser);
+  }
+
+  async markReported(ownerKey: string, dateKey: string): Promise<void> {
+    await this.#model(USER_TABLE).update({ last_report_date: dateKey }).where({ owner_key: ownerKey });
+  }
+}