@sleep2agi/commhub-server 0.9.0-preview.1 → 0.9.0-preview.100

package/src/requirement-due-reminders.ts

@@ -0,0 +1,310 @@
+// #491 / #492 —— 任务到期提醒(Hub 侧)。
+//
+// 每 COMMHUB_DUE_REMINDER_TICK_MS(默认 10 分钟)扫一次「没完成、没归档、有预计完成时间」的卡,按下面三种发提醒:
+//   due_soon  即将到期:日期型 due = 明天;时刻型 due 在 24 小时内(且不是今天)。每个 due 值一次。
+//   due_today 今天到期:日期型 due = 今天;时刻型 due 落在今天且还没到。每个 due 值一次。
+//   overdue   已逾期 N 天:每个自然日最多一次;逾期超过 COMMHUB_DUE_OVERDUE_MAX_DAYS(默认 7)天后不再提醒
+//             (上线当天不会把几个月前的旧卡一次性刷一遍,也不会天天提醒一张早被遗忘的卡)。
+// 「今天 / 明天 / 自然日」按 COMMHUB_DUE_REMINDER_TZ(默认 Asia/Shanghai)算。网络没有时区设置;due 的存法不变:
+//   日期型原样「YYYY-MM-DD」(requirements.ts normalizeDue:全天,客户端按查看者本地理解),时刻型是 UTC 秒。
+//
+// 收件人:
+//   人 —— 负责人(owner)+ 参与人里的人,去重。走 #462/#464 的 Hub 通知路(agent-notice.ts:user_inbox +
+//         /events/users/me desktop_message)。发信别名 = 负责 Agent 的别名(收件人看得见它时 → 出现在与它的会话里),
+//         否则 DUE_REMINDER_SENDER「任务提醒」。
+//   负责 Agent(agent_owner 节点)—— 一条不需要回复的消息:与 send_message 同一写法(inbox type='message' +
+//         new_message 推送),不是任务。节点不在 active 状态(停了 / 删除中)就不发。
+// 停止:卡完成 / 归档 / 清空 due → 扫描查询本身就选不到它;due 往后挪 → 那一档不再成立,而新 due 值重新上膛。
+// 去重:requirement_due_reminders 主键 (requirement_id, kind, due_on, day),先 INSERT … ON CONFLICT DO NOTHING
+//   抢到这一行(changes = 1)才发 —— 重启、多次扫描、并发都不会重发。宁可漏一次(发送中途崩溃),不发两次。
+// 只加表:旧 Hub 回滚后不认识这张表也不碰它。
+//
+// 上线护栏(生产上有别的团队的网络和节点):
+//   COMMHUB_DUE_REMINDER_NETWORKS=<id,id,…>  只给这些网络发;不设 = 所有网络(自建 Hub 默认就有这个功能)。
+//   COMMHUB_DUE_REMINDER_NODES=1              给负责 Agent 节点发消息;默认关(人照常提醒)。
+//   开通时不补发:每个网络第一次被扫描到时记一行基线(kind='baseline',sent_at = 那一刻)。只有在基线**之后**才变成逾期的卡
+//     会收到「已逾期」提醒;基线之前就已经逾期的卡永远不发逾期提醒(打开功能 / 把网络加进白名单都不会刷一批旧卡)。
+//     选这个而不是「把旧卡逐张记成已发」:不用每卡每天写行,也不怕某张旧卡第一次没被扫到、第二天又冒出来。
+//     即将到期 / 今天到期不受基线影响(它们本来就只在临近时发一次)。
+
+import type { DbAdapter } from "./db-adapter.js";
+import { db, uuidv4 } from "./db.js";
+import { sendAgentNotice } from "./agent-notice.js";
+import { canSeeAgent } from "./agent-access.js";
+import { assertNodeActive } from "./lifecycle-guard.js";
+import { pushEvent } from "./push.js";
+import { pendingInboxCount } from "./inbox-count.js";
+import { parseHubTimestamp } from "./hub-timestamp.js";
+
+export const DUE_REMINDER_KIND = "task_due";
+export const DUE_REMINDER_SENDER = "任务提醒";
+export type DueKind = "due_soon" | "due_today" | "overdue";
+
+const DAY_MS = 86_400_000;
+const RETENTION_DAYS = 60;
+
+/** IF NOT EXISTS:重复执行无副作用;SQLite / PostgreSQL 同一段。 */
+export function ensureDueReminders(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_due_reminders (
+      requirement_id TEXT NOT NULL,
+      kind           TEXT NOT NULL,
+      due_on         TEXT NOT NULL,
+      day            TEXT NOT NULL,
+      network_id     TEXT NOT NULL,
+      sent_at        TEXT NOT NULL,
+      PRIMARY KEY (requirement_id, kind, due_on, day)
+    );
+  `);
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_due_reminders_sent ON requirement_due_reminders(sent_at)");
+  // 扫描查询按 due_on 取一段范围:只给有 due 的行建索引。
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirements_due_on ON requirements(due_on) WHERE due_on IS NOT NULL");
+}
+
+function envNumber(name: string, fallback: number, min: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= min ? n : fallback;
+}
+
+export function dueReminderTimezone(): string {
+  const tz = process.env.COMMHUB_DUE_REMINDER_TZ?.trim() || "Asia/Shanghai";
+  try { new Intl.DateTimeFormat("en-US", { timeZone: tz }); return tz; } catch { return "Asia/Shanghai"; }
+}
+/** COMMHUB_DUE_REMINDER_NETWORKS:逗号分隔的网络 id;没设(或只有空白)→ null = 所有网络。 */
+export function reminderNetworks(): string[] | null {
+  const raw = process.env.COMMHUB_DUE_REMINDER_NETWORKS;
+  if (raw === undefined) return null;
+  const ids = raw.split(",").map((x) => x.trim()).filter(Boolean);
+  return ids.length ? ids : null;
+}
+export function nodeRemindersEnabled(): boolean { return process.env.COMMHUB_DUE_REMINDER_NODES === "1"; }
+export const BASELINE_KIND = "baseline";
+
+export function overdueMaxDays(): number { return Math.floor(envNumber("COMMHUB_DUE_OVERDUE_MAX_DAYS", 7, 0)); }
+
+// ── 时区小工具 ─────────────────────────────────────────────
+/** 某一时刻在 tz 的日期「YYYY-MM-DD」。 */
+export function localDate(ms: number, tz: string): string {
+  return new Intl.DateTimeFormat("en-CA", { timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit" }).format(new Date(ms));
+}
+/** 日期 + n 天(纯日历运算,与时区无关)。 */
+export function addDays(date: string, n: number): string {
+  const [y, m, d] = date.split("-").map(Number);
+  return new Date(Date.UTC(y, m - 1, d) + n * DAY_MS).toISOString().slice(0, 10);
+}
+/** 两个日期相差几天(a - b)。 */
+export function dayDiff(a: string, b: string): number {
+  const ms = (s: string) => { const [y, m, d] = s.split("-").map(Number); return Date.UTC(y, m - 1, d); };
+  return Math.round((ms(a) - ms(b)) / DAY_MS);
+}
+function tzOffsetMs(ms: number, tz: string): number {
+  const p = Object.fromEntries(new Intl.DateTimeFormat("en-US", { timeZone: tz, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" })
+    .formatToParts(new Date(ms)).filter((x) => x.type !== "literal").map((x) => [x.type, Number(x.value)]));
+  return Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second) - Math.floor(ms / 1000) * 1000;
+}
+/** tz 里某天 00:00 对应的 UTC 时刻(ms)。 */
+export function localMidnightMs(date: string, tz: string): number {
+  const [y, m, d] = date.split("-").map(Number);
+  const guess = Date.UTC(y, m - 1, d);
+  let t = guess - tzOffsetMs(guess, tz);
+  t = guess - tzOffsetMs(t, tz);
+  return t;
+}
+
+const isDateOnly = (due: string) => due.length === 10;
+
+/** 从哪一刻起算逾期:日期型 = tz 里第二天零点;时刻型 = 那个时刻。 */
+export function overdueSinceMs(due: string, tz: string): number {
+  return isDateOnly(due) ? localMidnightMs(addDays(due, 1), tz) : Date.parse(due);
+}
+
+/** 这张卡此刻该发哪一档(没有 → null)。day = 去重用的那一天。 */
+export function dueReminderFor(due: string, nowMs: number, tz: string, maxOverdue = overdueMaxDays()): { kind: DueKind; day: string; overdueDays: number; dueDay: string } | null {
+  const today = localDate(nowMs, tz);
+  if (isDateOnly(due)) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(due)) return null;
+    if (due === today) return { kind: "due_today", day: due, overdueDays: 0, dueDay: due };
+    if (due === addDays(today, 1)) return { kind: "due_soon", day: due, overdueDays: 0, dueDay: due };
+    if (due < today) {
+      const n = dayDiff(today, due);
+      return n <= maxOverdue ? { kind: "overdue", day: today, overdueDays: n, dueDay: due } : null;
+    }
+    return null;
+  }
+  const t = Date.parse(due);
+  if (!Number.isFinite(t)) return null;
+  const dueDay = localDate(t, tz);
+  if (t <= nowMs) {
+    const n = dayDiff(today, dueDay);
+    return n <= maxOverdue ? { kind: "overdue", day: today, overdueDays: n, dueDay } : null;
+  }
+  if (dueDay === today) return { kind: "due_today", day: dueDay, overdueDays: 0, dueDay };
+  if (t - nowMs <= DAY_MS) return { kind: "due_soon", day: dueDay, overdueDays: 0, dueDay };
+  return null;
+}
+
+/**
+ * 列表筛选(requirements.ts listFilters)用的条件:overdue / due_within_days。只看没完成的卡。
+ * 日期型(长度 10)按 tz 的「今天」比日期;时刻型(UTC 字符串)按此刻比时刻。字符串比较:两种形状各自同长、同格式。
+ */
+export function overdueSql(params: unknown[], nowMs: number, tz: string): string {
+  const today = localDate(nowMs, tz);
+  const nowIso = new Date(nowMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+  return `(due_on IS NOT NULL AND column_name <> 'done' AND ((length(due_on) = 10 AND due_on < ?${params.push(today)}) OR (length(due_on) > 10 AND due_on <= ?${params.push(nowIso)})))`;
+}
+/** 没逾期、且在 tz 的「今天 + days」那天结束之前到期(0 = 今天内)。 */
+export function dueWithinSql(params: unknown[], days: number, nowMs: number, tz: string): string {
+  const today = localDate(nowMs, tz);
+  const lastDay = addDays(today, days);
+  const endIso = new Date(localMidnightMs(addDays(lastDay, 1), tz)).toISOString().replace(/\.\d{3}Z$/, "Z");
+  const nowIso = new Date(nowMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+  return `(due_on IS NOT NULL AND column_name <> 'done' AND ((length(due_on) = 10 AND due_on >= ?${params.push(today)} AND due_on <= ?${params.push(lastDay)}) OR (length(due_on) > 10 AND due_on > ?${params.push(nowIso)} AND due_on < ?${params.push(endIso)})))`;
+}
+
+// ── 扫描 ───────────────────────────────────────────────────
+type DueRow = {
+  requirement_id: string; network_id: string; seq: number | null; title: string; due_on: string;
+  owner_json: string | null; participants_json: string | null; agent_owner_json: string | null;
+};
+const parse = (raw: string | null) => { try { return raw ? JSON.parse(raw) : null; } catch { return null; } };
+const userIdOf = (ref: unknown): string | null => {
+  const r = ref as { kind?: unknown; id?: unknown } | null;
+  return r && r.kind === "user" && typeof r.id === "string" ? r.id : null;
+};
+
+export function humanRecipients(row: Pick<DueRow, "owner_json" | "participants_json">): string[] {
+  const ids = new Set<string>();
+  const owner = userIdOf(parse(row.owner_json));
+  if (owner) ids.add(owner);
+  const participants = parse(row.participants_json);
+  if (Array.isArray(participants)) for (const p of participants) { const id = userIdOf(p); if (id) ids.add(id); }
+  return [...ids];
+}
+
+function fmtDue(due: string, tz: string): string {
+  if (isDateOnly(due)) return due;
+  const t = Date.parse(due);
+  const s = new Intl.DateTimeFormat("sv-SE", { timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(new Date(t));
+  return s;
+}
+
+export function dueReminderText(row: Pick<DueRow, "seq" | "title" | "due_on">, r: { kind: DueKind; overdueDays: number }, tz: string): { title: string; text: string } {
+  const card = `${row.seq ? `#${row.seq} ` : ""}「${row.title}」`;
+  const when = fmtDue(row.due_on, tz);
+  if (r.kind === "due_soon") return { title: "任务即将到期", text: `任务${card}即将到期(预计完成 ${when})。` };
+  if (r.kind === "due_today") return { title: "任务今天到期", text: `任务${card}今天到期(预计完成 ${when})。` };
+  const late = r.overdueDays >= 1 ? `已逾期 ${r.overdueDays} 天` : "已过预计完成时间";
+  return { title: "任务已逾期", text: `任务${card}${late}(预计完成 ${when}),还没有完成。` };
+}
+
+export type DueReminderSent = { requirement_id: string; kind: DueKind; users: string[]; node: string | null };
+
+/**
+ * 跑一次。now 可注入(测试用假时钟)。返回这次真正发出的提醒。
+ * 一条按 due_on 范围走索引的查询取候选;每个候选先抢去重行,抢到才发。
+ */
+export function runDueReminders(opts: { now?: number } = {}): DueReminderSent[] {
+  const nowMs = opts.now ?? Date.now();
+  const tz = dueReminderTimezone();
+  const maxOverdue = overdueMaxDays();
+  const today = localDate(nowMs, tz);
+  // 范围:最老 = 今天 - maxOverdue - 1(UTC 日期 ≤ 本地日期,多留一天);最新 < 今天 + 2(24 小时内的时刻型 UTC 日期 ≤ 明天)。
+  const lo = addDays(today, -maxOverdue - 1);
+  const hi = addDays(today, 2);
+  const allow = reminderNetworks();
+  const sentAt = new Date(nowMs).toISOString();
+  // 基线:范围内每个网络第一次被扫到的那一刻(已有就不动)。一条 INSERT … SELECT。
+  {
+    const bp: unknown[] = [BASELINE_KIND, sentAt];
+    // WHERE 必须有:SQLite 里「INSERT … SELECT … FROM t ON CONFLICT」会把 ON 读成 JOIN 约束(语法错),要一个 WHERE 隔开。
+    const where = ` WHERE 1=1${allow ? ` AND network_id IN (${allow.map((id) => `?${bp.push(id)}`).join(", ")})` : ""}`;
+    db.run(
+      `INSERT INTO requirement_due_reminders (requirement_id, kind, due_on, day, network_id, sent_at)
+       SELECT '__baseline__:' || network_id, ?1, '', '', network_id, ?2 FROM networks${where}
+       ON CONFLICT DO NOTHING`,
+      bp,
+    );
+  }
+  const baselines = new Map(
+    db.all<{ network_id: string; sent_at: string }>("SELECT network_id, sent_at FROM requirement_due_reminders WHERE kind = ?1", BASELINE_KIND)
+      .map((b) => [b.network_id, parseHubTimestamp(b.sent_at)] as const)
+      .filter((e): e is readonly [string, number] => e[1] !== null),
+  );
+  const params: unknown[] = [lo, hi];
+  const netFilter = allow ? ` AND network_id IN (${allow.map((id) => `?${params.push(id)}`).join(", ")})` : "";
+  const rows = db.all<DueRow>(
+    `SELECT requirement_id, network_id, seq, title, due_on, owner_json, participants_json, agent_owner_json
+       FROM requirements
+      WHERE due_on IS NOT NULL AND due_on >= ?1 AND due_on < ?2 AND column_name <> 'done' AND COALESCE(archived, 0) = 0${netFilter}`,
+    ...params,
+  );
+  const out: DueReminderSent[] = [];
+  for (const row of rows) {
+    const r = dueReminderFor(row.due_on, nowMs, tz, maxOverdue);
+    if (!r) continue;
+    if (r.kind === "overdue") {
+      // 基线之前就已经逾期 → 不发(开通时不补发)。没有基线(网络行不存在)= 当作此刻开通。
+      const base = baselines.get(row.network_id) ?? nowMs;
+      if (overdueSinceMs(row.due_on, tz) < base) continue;
+    }
+    try {
+      const claimed = db.run(
+        `INSERT INTO requirement_due_reminders (requirement_id, kind, due_on, day, network_id, sent_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6) ON CONFLICT DO NOTHING`,
+        [row.requirement_id, r.kind, row.due_on, r.day, row.network_id, sentAt],
+      );
+      if (claimed.changes < 1) continue;
+      out.push(deliver(row, r, tz));
+    } catch (e: any) {
+      console.error(`[due-reminders] ${row.requirement_id} ${r.kind} failed: ${e?.message || e}`);
+    }
+  }
+  // 去重行保留 RETENTION_DAYS 天(比逾期上限长得多,删掉的行不会再被需要)。
+  try { db.run("DELETE FROM requirement_due_reminders WHERE sent_at < ?1 AND kind <> ?2", [new Date(nowMs - RETENTION_DAYS * DAY_MS).toISOString(), BASELINE_KIND]); } catch {}
+  return out;
+}
+
+function deliver(row: DueRow, r: { kind: DueKind; overdueDays: number; dueDay: string }, tz: string): DueReminderSent {
+  const { title, text } = dueReminderText(row, r, tz);
+  const agent = parse(row.agent_owner_json) as { kind?: unknown; id?: unknown } | null;
+  const nodeId = agent?.kind === "node" && typeof agent.id === "string" ? agent.id : null;
+  const node = nodeId
+    ? db.get<{ alias: string | null }>("SELECT alias FROM nodes WHERE node_id = ?1 AND network_id = ?2", nodeId, row.network_id)
+    : null;
+  const alias = node?.alias || null;
+  const meta = { task_notice: { requirement_id: row.requirement_id, seq: row.seq ?? null, network_id: row.network_id, due_reminder: r.kind, due: row.due_on, overdue_days: r.overdueDays } };
+  const users: string[] = [];
+  for (const userId of humanRecipients(row)) {
+    const fromAlias = alias && canSeeAgent(userId, row.network_id, { alias, nodeId }) ? alias : DUE_REMINDER_SENDER;
+    const id = sendAgentNotice({
+      networkId: row.network_id, userId, fromAlias, kind: DUE_REMINDER_KIND, title, text,
+      severity: r.kind === "overdue" ? "warning" : "info", meta, idPrefix: "dm_due_",
+    });
+    if (id) users.push(userId);
+  }
+  let notifiedNode: string | null = null;
+  if (alias && nodeRemindersEnabled() && assertNodeActive(alias, row.network_id).ok) {
+    const id = uuidv4();
+    const message = `[${title}] ${text}\n(这是提醒,不需要回复。requirement_id=${row.requirement_id})`;
+    db.run(
+      `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
+       VALUES (?1, ?2, ?3, 'message', 'normal', ?4, ?5, ?6)`,
+      [id, alias, nodeId, message, DUE_REMINDER_SENDER, row.network_id],
+    );
+    pushEvent(alias, { type: "new_message", inbox_count: pendingInboxCount(alias, row.network_id), from: DUE_REMINDER_SENDER, message_id: id }, row.network_id);
+    notifiedNode = alias;
+  }
+  return { requirement_id: row.requirement_id, kind: r.kind as DueKind, users, node: notifiedNode };
+}
+
+/** startHub 里调用。COMMHUB_DUE_REMINDERS=0 关掉;bootServer(测试)不调用它。第一次扫描延后一个间隔外的 30 秒,不和启动抢。 */
+export function startDueReminderTimer(): ReturnType<typeof setInterval> | null {
+  if (process.env.COMMHUB_DUE_REMINDERS === "0") return null;
+  const ms = envNumber("COMMHUB_DUE_REMINDER_TICK_MS", 10 * 60_000, 1_000);
+  const tick = () => { try { runDueReminders(); } catch (e: any) { console.error(`[due-reminders] tick failed: ${e?.message || e}`); } };
+  const first = setTimeout(tick, Math.min(ms, 30_000));
+  (first as any)?.unref?.();
+  return setInterval(tick, ms);
+}

package/src/requirement-events-http.test.ts

@@ -0,0 +1,257 @@
+// 任务动态(#429)—— HTTP 集成测试(真实 Bun.serve,临时库;PG 梯子上用 COMMHUB_TEST_PG_URL 原样再跑一遍)。
+//   写路径    —— 新建 / PATCH 的每个字段 / 勾子任务 / 标签改名 / 删项目 / 删卡,各记字段级流水:谁、旧值 → 新值
+//   同一事务  —— 流水写不进去,那次改动也不生效
+//   可见范围  —— 与列表相同:scoped 成员只看到看得见的卡(删掉的按墓碑);Agent 受限成员看不见的节点被隐去
+//   翻页      —— limit / next_cursor / since / requirement_id;参数不合法 400;capability `events`
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-requirement-events-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "EventsPassw0rd!x";
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let admin = { token: "", id: "" };
+let member = { token: "", id: "" };
+let scoped = { token: "", id: "" };
+let restricted = { token: "", id: "" };
+let nodeToken = "";
+let NODE = "";
+
+type R = { status: number; body: any };
+async function send(token: string, method: string, path: string, payload?: unknown): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json" },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+const create = async (t: string, card: Record<string, unknown>) => {
+  const r = await send(t, "POST", "/api/requirements", { network_id: NET, ...card });
+  expect(r.status).toBe(201);
+  return r.body.requirement as { id: string; seq: number };
+};
+const patch = (t: string, id: string, p: Record<string, unknown>) => send(t, "PATCH", `/api/requirements/${id}?network_id=${NET}`, p);
+const events = (t: string, qs = "") => send(t, "GET", `/api/requirements/events?network_id=${NET}${qs}`);
+const of = (list: any[], id: string) => list.filter(e => e.requirement_id === id);
+const user = (id: string) => ({ kind: "user", id });
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`ev_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(a.ok).toBe(true);
+  admin = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [admin.id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  const mk = async (username: string) => {
+    const r = await send(admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  member = await mk(`ev_member_${stamp}`);
+  scoped = await mk(`ev_scoped_${stamp}`);
+  restricted = await mk(`ev_restricted_${stamp}`);
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, scoped.id]);
+  // 看全部任务,但一个 Agent 都没授权:所有节点对他隐去
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'granted' WHERE network_id = ?1 AND user_id = ?2", [NET, restricted.id]);
+  NODE = `n_ev_${stamp}`;
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id) VALUES (?1, ?2, ?3, ?4)", [NODE, "ev-node", "ev-node", NET]);
+  const ntok = createNetworkTokenForNode(admin.id, NET, "ev-node");
+  expect(ntok.ok).toBe(true);
+  nodeToken = ntok.token!;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirement events", () => {
+  test("capability `events` is advertised", async () => {
+    const r = await send(admin.token, "GET", `/api/requirements?network_id=${NET}`);
+    expect(r.body.capabilities).toContain("events");
+  });
+
+  test("create records one `created` event with the actor, title and seq", async () => {
+    const card = await create(member.token, { name: "动态示例一" });
+    const r = await events(admin.token, `&requirement_id=${card.id}`);
+    expect(r.status).toBe(200);
+    expect(r.body.events.length).toBe(1);
+    const [e] = r.body.events;
+    expect(e).toMatchObject({ kind: "created", field: null, actor: user(member.id), title: "动态示例一", seq: card.seq, new: { title: "动态示例一", column: "pool" } });
+    expect(typeof e.id).toBe("string");
+    expect(Date.parse(e.at)).toBeGreaterThan(0);
+  });
+
+  test("a PATCH records one event per changed field, old → new; unchanged fields and no-op PATCHes record nothing", async () => {
+    const card = await create(admin.token, { name: "动态示例二", priority: "normal", tags: ["UI"] });
+    const r1 = await patch(member.token, card.id, {
+      column: "doing", priority: "high", due: "2026-10-03", name: "动态示例二(改)", tags: ["UI", "后端"],
+      agent_owner: { kind: "node", id: NODE }, participants: [user(admin.id)], assignee: "",
+    });
+    expect(r1.status).toBe(200);
+    const list = of((await events(admin.token)).body.events, card.id);
+    const byField = Object.fromEntries(list.filter((e: any) => e.kind === "changed").map((e: any) => [e.field, e]));
+    expect(Object.keys(byField).sort()).toEqual(["agent_owner", "column", "due", "participants", "priority", "tags", "title"]);
+    expect(byField.column).toMatchObject({ old: "pool", new: "doing", actor: user(member.id) });
+    expect(byField.priority).toMatchObject({ old: "normal", new: "high" });
+    expect(byField.due).toMatchObject({ old: null, new: "2026-10-03" });
+    expect(byField.title).toMatchObject({ old: "动态示例二", new: "动态示例二(改)" });
+    expect(byField.tags).toMatchObject({ old: ["UI"], new: ["UI", "后端"] });
+    expect(byField.agent_owner).toMatchObject({ old: null, new: { kind: "node", id: NODE } });
+    expect(byField.participants).toMatchObject({ old: [], new: [user(admin.id)] });
+    // every event of that PATCH carries the card's title after the change
+    expect(new Set(list.filter((e: any) => e.kind === "changed").map((e: any) => e.title))).toEqual(new Set(["动态示例二(改)"]));
+    const before = list.length;
+    expect((await patch(member.token, card.id, { priority: "high", column: "doing" })).status).toBe(200);
+    expect(of((await events(admin.token)).body.events, card.id).length).toBe(before);
+    // archive / unarchive, description (length only, never the text), move to done
+    await patch(member.token, card.id, { description: "一段描述" });
+    await patch(member.token, card.id, { column: "done" });
+    await patch(member.token, card.id, { archived: true });
+    const later = of((await events(admin.token)).body.events, card.id).slice(0, 3);
+    expect(later.map((e: any) => e.field)).toEqual(["archived", "column", "description"]);
+    expect(later[0]).toMatchObject({ old: false, new: true });
+    expect(later[1]).toMatchObject({ old: "doing", new: "done" });
+    expect(later[2]).toMatchObject({ old: { chars: 0 }, new: { chars: 4 } });
+    expect(JSON.stringify(later[2])).not.toContain("一段描述");
+  });
+
+  test("checklist: ticking an item is `checklist_item` (repeat is a no-op); adding items is `checklist`", async () => {
+    const card = await create(admin.token, { name: "动态示例三", checklist: [{ id: "a", text: "第一项" }, { id: "b", text: "第二项" }] });
+    const tick = (done: boolean) => send(member.token, "PATCH", `/api/requirements/${card.id}/checklist/a?network_id=${NET}`, { done });
+    expect((await tick(true)).status).toBe(200);
+    expect((await tick(true)).status).toBe(200);
+    let list = of((await events(admin.token)).body.events, card.id);
+    const ticks = list.filter((e: any) => e.field === "checklist_item");
+    expect(ticks.length).toBe(1);
+    expect(ticks[0]).toMatchObject({ old: { id: "a", text: "第一项", done: false }, new: { id: "a", text: "第一项", done: true }, actor: user(member.id) });
+    // a PATCH that only flips one item's done is also `checklist_item`
+    await patch(member.token, card.id, { checklist: [{ id: "a", text: "第一项", done: true }, { id: "b", text: "第二项", done: true }] });
+    await patch(member.token, card.id, { checklist: [{ id: "a", text: "第一项", done: true }, { id: "b", text: "第二项", done: true }, { id: "c", text: "第三项" }] });
+    list = of((await events(admin.token)).body.events, card.id);
+    expect(list[0]).toMatchObject({ field: "checklist", old: { total: 2, done: 2 }, new: { total: 3, done: 2 } });
+    expect(list[1]).toMatchObject({ field: "checklist_item", new: { id: "b", done: true } });
+  });
+
+  test("the actor of a node token is the node", async () => {
+    const card = await create(admin.token, { name: "动态示例四" });
+    expect((await patch(nodeToken, card.id, { column: "doing" })).status).toBe(200);
+    const [e] = of((await events(nodeToken)).body.events, card.id);
+    expect(e).toMatchObject({ field: "column", actor: { kind: "node", id: NODE } });
+  });
+
+  test("tag rename, project delete and card delete each record per-card events", async () => {
+    const p = await send(admin.token, "POST", `/api/requirements/projects?network_id=${NET}`, { name: `动态项目-${Date.now()}` });
+    expect(p.status).toBe(201);
+    const card = await create(admin.token, { name: "动态示例五", tags: ["旧标签"], project_id: p.body.project.id });
+    expect((await send(admin.token, "POST", `/api/requirements/tags/ops?network_id=${NET}`, { op: "rename", from: "旧标签", to: "新标签" })).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/projects/${p.body.project.id}?network_id=${NET}`)).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/${card.id}?network_id=${NET}`)).status).toBe(200);
+    const list = of((await events(admin.token)).body.events, card.id);
+    expect(list.slice(0, 3).map((e: any) => [e.kind, e.field])).toEqual([["deleted", null], ["changed", "project"], ["changed", "tags"]]);
+    expect(list[0]).toMatchObject({ title: "动态示例五", seq: expect.any(Number), actor: user(admin.id) });
+    expect(list[1]).toMatchObject({ old: p.body.project.id, new: null });
+    expect(list[2]).toMatchObject({ old: ["旧标签"], new: ["新标签"] });
+  });
+
+  test("the write and its events are one transaction: no events table → the PATCH fails and the card is unchanged", async () => {
+    const { db } = await import("./db.js");
+    const card = await create(admin.token, { name: "动态示例六", priority: "low" });
+    db.exec("ALTER TABLE requirement_events RENAME TO requirement_events_away");
+    try {
+      const r = await patch(admin.token, card.id, { priority: "high" });
+      expect(r.status).toBeGreaterThanOrEqual(500);
+    } finally {
+      db.exec("ALTER TABLE requirement_events_away RENAME TO requirement_events");
+    }
+    const now = await send(admin.token, "GET", `/api/requirements/${card.id}?network_id=${NET}`);
+    expect(now.body.requirement.priority).toBe("low");
+  });
+
+  test("a scoped member sees events only for cards they can see — deleted ones by their tombstone", async () => {
+    const mine = await create(scoped.token, { name: "动态示例七(scoped 自己建的)" });
+    const theirs = await create(admin.token, { name: "动态示例八(scoped 看不见)" });
+    const joined = await create(admin.token, { name: "动态示例九(scoped 是参与人)", participants: [user(scoped.id)] });
+    await patch(admin.token, mine.id, { priority: "high" });
+    await patch(admin.token, theirs.id, { priority: "high" });
+    await send(admin.token, "DELETE", `/api/requirements/${joined.id}?network_id=${NET}`);
+    const seen = (await events(scoped.token, "&limit=500")).body.events;
+    expect(of(seen, mine.id).length).toBe(2);
+    expect(of(seen, theirs.id).length).toBe(0);
+    expect(of(seen, joined.id).map((e: any) => e.kind)).toEqual(["deleted", "created"]);
+    // a filter on a card they cannot see answers like a card with no events
+    expect((await events(scoped.token, `&requirement_id=${theirs.id}`)).body.events).toEqual([]);
+  });
+
+  test("an agent-restricted member: hidden nodes are masked, and an event that only differs by a hidden node is dropped", async () => {
+    const card = await create(admin.token, { name: "动态示例十" });
+    await patch(nodeToken, card.id, { priority: "high" });
+    await patch(admin.token, card.id, { agent_owner: { kind: "node", id: NODE } });
+    await patch(admin.token, card.id, { participants: [user(admin.id), { kind: "node", id: NODE }] });
+    const seen = of((await events(restricted.token)).body.events, card.id);
+    const all = of((await events(admin.token)).body.events, card.id);
+    expect(all.map((e: any) => e.field)).toEqual(["participants", "agent_owner", "priority", null]);
+    expect(seen.map((e: any) => e.field)).toEqual(["participants", "priority", null]);
+    expect(seen[0]).toMatchObject({ old: [], new: [user(admin.id)] });
+    expect(seen[1]).toMatchObject({ field: "priority", actor: null });
+    expect(JSON.stringify(seen)).not.toContain(NODE);
+  });
+
+  test("paging: newest first, limit + next_cursor without overlap; since; bad params 400", async () => {
+    const card = await create(admin.token, { name: "动态示例十一" });
+    for (const priority of ["high", "low", "lowest", "normal"]) await patch(admin.token, card.id, { priority });
+    const q = `&requirement_id=${card.id}`;
+    const p1 = await events(admin.token, `${q}&limit=2`);
+    expect(p1.body.events.length).toBe(2);
+    expect(p1.body.has_more).toBe(true);
+    expect(p1.body.events[0].new).toBe("normal");
+    const p2 = await events(admin.token, `${q}&limit=2&cursor=${p1.body.next_cursor}`);
+    const p3 = await events(admin.token, `${q}&limit=2&cursor=${p2.body.next_cursor}`);
+    const ids = [...p1.body.events, ...p2.body.events, ...p3.body.events].map((e: any) => e.id);
+    expect(new Set(ids).size).toBe(5);
+    expect(p3.body.has_more).toBe(false);
+    expect(p3.body.next_cursor).toBe(null);
+    expect(ids.map(Number)).toEqual([...ids.map(Number)].sort((a, b) => b - a));
+    // since = server_time of an earlier read → only what came after
+    const t = p1.body.server_time;
+    await patch(admin.token, card.id, { priority: "high" });
+    const after = await events(admin.token, `${q}&since=${encodeURIComponent(t)}`);
+    // since is inclusive (>=): an event written in the same millisecond as server_time comes back again,
+    // and clients dedupe by id. Only the events not already seen must be exactly the new one.
+    expect(after.body.events.every((e: any) => Date.parse(e.at) >= Date.parse(t))).toBe(true);
+    const seen = new Set(ids);
+    expect(after.body.events.filter((e: any) => !seen.has(e.id)).map((e: any) => e.new)).toEqual(["high"]);
+    for (const bad of ["&limit=0", "&limit=501", "&limit=x", "&since=nope", "&cursor=abc", "&cursor=0"]) {
+      expect((await events(admin.token, bad)).status).toBe(400);
+    }
+  });
+
+  test("migration is idempotent and leaves the rows alone", async () => {
+    const { db } = await import("./db.js");
+    const { ensureRequirementEvents } = await import("./requirement-events.js");
+    const n = Number(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events")!.n);
+    ensureRequirementEvents(db);
+    ensureRequirementEvents(db);
+    expect(Number(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events")!.n)).toBe(n);
+    expect(n).toBeGreaterThan(0);
+  });
+});

package/src/requirement-events.test.ts

@@ -0,0 +1,45 @@
+// diffRequirement 的边角(HTTP 层的写路径在 requirement-events-http.test.ts)。
+import { describe, expect, test } from "bun:test";
+import { diffRequirement, eventPublic, type EventCard } from "./requirement-events.js";
+
+const base: EventCard = {
+  requirement_id: "req_1", network_id: "net_1", seq: 7, title: "示例", column_name: "pool", priority: "normal", due_on: null, start_on: null,
+  assignee: null, owner_json: null, agent_owner_json: null, participants_json: "[]", tags_json: "[]", checklist_json: "[]", description: null,
+  project_id: null, parent_id: null, archived: 0,
+};
+const ck = (items: { id: string; text: string; done?: boolean }[]) => JSON.stringify(items.map(i => ({ done: false, ...i })));
+
+describe("diffRequirement", () => {
+  test("no change → no events; null vs empty string are the same", () => {
+    expect(diffRequirement(base, { ...base })).toEqual([]);
+    expect(diffRequirement(base, { ...base, due_on: "", assignee: "", description: "" })).toEqual([]);
+  });
+  test("created carries title and column only", () => {
+    expect(diffRequirement(null, base)).toEqual([{ kind: "created", field: null, old: null, new: { title: "示例", column: "pool" } }]);
+  });
+  test("checklist: reorder, rename, add or remove is one `checklist` event with counts", () => {
+    const a = { ...base, checklist_json: ck([{ id: "a", text: "一" }, { id: "b", text: "二", done: true }]) };
+    for (const next of [ck([{ id: "b", text: "二", done: true }, { id: "a", text: "一" }]), ck([{ id: "a", text: "一改" }, { id: "b", text: "二", done: true }]), ck([{ id: "a", text: "一" }])]) {
+      const out = diffRequirement(a, { ...a, checklist_json: next });
+      expect(out.length).toBe(1);
+      expect(out[0].field).toBe("checklist");
+    }
+    expect(diffRequirement(a, { ...a, checklist_json: ck([{ id: "a", text: "一" }]) })[0]).toMatchObject({ old: { total: 2, done: 1 }, new: { total: 1, done: 0 } });
+  });
+  test("checklist: two items ticked in one write are two `checklist_item` events", () => {
+    const a = { ...base, checklist_json: ck([{ id: "a", text: "一" }, { id: "b", text: "二" }]) };
+    const out = diffRequirement(a, { ...a, checklist_json: ck([{ id: "a", text: "一", done: true }, { id: "b", text: "二", done: true }]) });
+    expect(out.map(e => [e.field, (e.new as { id: string }).id])).toEqual([["checklist_item", "a"], ["checklist_item", "b"]]);
+  });
+  test("malformed stored JSON reads as empty rather than throwing", () => {
+    expect(() => diffRequirement({ ...base, tags_json: "{nope", participants_json: "x" }, base)).not.toThrow();
+  });
+  test("description records lengths, never text", () => {
+    const [e] = diffRequirement(base, { ...base, description: "secret text" });
+    expect(e).toEqual({ kind: "changed", field: "description", old: { chars: 0 }, new: { chars: 11 } });
+  });
+  test("eventPublic: bigint / string ids from PostgreSQL come out as strings, seq as a number", () => {
+    const row = { id: 12n as unknown as string, network_id: "n", requirement_id: "r", seq: "3", title: "t", actor_json: null, kind: "changed", field: "priority", old_json: "\"low\"", new_json: "\"high\"", created_at: "2026-10-01T00:00:00.000Z" };
+    expect(eventPublic(row)).toMatchObject({ id: "12", seq: 3, old: "low", new: "high", actor: null });
+  });
+});