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

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 });
+  });
+});

package/src/requirement-events.ts

@@ -0,0 +1,144 @@
+// 任务动态(#429,Vincent 2026-09-30「任务有新的状态…这完成了,这是有这种动态」)。
+//
+// requirements 表只存「现在是什么」和「最后是谁改的」(updated_by_json),改之前是什么没有任何地方留着 ——
+// 「优先级 P2 → P0」「状态 需求池 → 进行中」画不出来。这里给每一次写入记字段级的流水:谁(用户 / 节点)、
+// 什么时候、哪个字段、旧值 → 新值。写入点在 requirements.ts 的各条写路径里,和那次 UPDATE 在同一个事务里。
+//
+// 表只加不改:旧 Hub(回滚之后)不认识这张表,也不会碰它;再升回来接着记(回滚期间的改动没有流水)。
+// 读:GET /api/requirements/events(requirements.ts,可见范围与列表相同),capability `events`。
+import type { DbAdapter } from "./db-adapter.js";
+
+/** 流水保留多久。更早的在写入时顺手清掉(每 PRUNE_EVERY 次写一次)。 */
+export const EVENTS_RETENTION_MS = 180 * 86_400_000;
+const PRUNE_EVERY = 500;
+
+/** IF NOT EXISTS:重复执行无副作用;SQLite / PostgreSQL 同一段(适配层把 AUTOINCREMENT 译成 BIGSERIAL)。 */
+export function ensureRequirementEvents(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_events (
+      id             INTEGER PRIMARY KEY AUTOINCREMENT,
+      network_id     TEXT NOT NULL,
+      requirement_id TEXT NOT NULL,
+      seq            INTEGER,
+      title          TEXT,
+      actor_json     TEXT,
+      kind           TEXT NOT NULL,
+      field          TEXT,
+      old_json       TEXT,
+      new_json       TEXT,
+      created_at     TEXT NOT NULL
+    );
+  `);
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_network ON requirement_events(network_id, id)");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_card ON requirement_events(requirement_id, id)");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_created ON requirement_events(created_at)");
+}
+
+/** 流水要比较的列(requirements.ts 的 Row 的子集)。 */
+export type EventCard = {
+  requirement_id: string;
+  network_id: string;
+  seq: number | null;
+  title: string;
+  column_name: string;
+  priority: string;
+  due_on: string | null;
+  start_on: string | null;
+  assignee: string | null;
+  owner_json: string | null;
+  agent_owner_json: string | null;
+  participants_json: string | null;
+  tags_json: string | null;
+  checklist_json: string | null;
+  description: string | null;
+  project_id: string | null;
+  parent_id: string | null;
+  archived: number | null;
+};
+
+export type EventKind = "created" | "changed" | "deleted" | "comment";
+/**
+ * field(kind = changed):column / title / priority / due / start / assignee / owner / agent_owner / participants /
+ * tags / checklist_item(勾选或取消一项:{id,text,done})/ checklist(增删改条目:{total,done})/
+ * description(只记字数,不存正文)/ project / parent / archived。
+ * kind = comment(#474):field 为 null,new = { text }(评论正文,≤ 4000 字),只追加,不对应任何字段的改动。
+ */
+export type EventDraft = { kind: EventKind; field: string | null; old: unknown; new: unknown };
+
+const parse = (json: string | null | undefined): unknown => {
+  if (!json) return null;
+  try { return JSON.parse(json); } catch { return null; }
+};
+const list = (json: string | null | undefined): unknown[] => { const v = parse(json); return Array.isArray(v) ? v : []; };
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+type Item = { id: string; text: string; done: boolean };
+const items = (json: string | null | undefined): Item[] =>
+  list(json).filter((x): x is Item => !!x && typeof (x as Item).id === "string" && typeof (x as Item).text === "string").map(x => ({ id: x.id, text: x.text, done: !!x.done }));
+const counts = (xs: Item[]) => ({ total: xs.length, done: xs.filter(x => x.done).length });
+
+/** 一次写入前后的差异。before = null:新建(只记一条 created)。 */
+export function diffRequirement(before: EventCard | null, after: EventCard): EventDraft[] {
+  if (!before) return [{ kind: "created", field: null, old: null, new: { title: after.title, column: after.column_name } }];
+  const out: EventDraft[] = [];
+  const scalar = (field: string, a: unknown, b: unknown) => { if (!same(a, b)) out.push({ kind: "changed", field, old: a, new: b }); };
+  scalar("column", before.column_name, after.column_name);
+  scalar("title", before.title, after.title);
+  scalar("priority", before.priority, after.priority);
+  scalar("due", before.due_on || null, after.due_on || null);
+  scalar("start", before.start_on || null, after.start_on || null);
+  scalar("assignee", before.assignee || null, after.assignee || null);
+  scalar("owner", parse(before.owner_json), parse(after.owner_json));
+  scalar("agent_owner", parse(before.agent_owner_json), parse(after.agent_owner_json));
+  scalar("participants", list(before.participants_json), list(after.participants_json));
+  scalar("tags", list(before.tags_json), list(after.tags_json));
+  // 子任务:同一条(同 id、同文字)只是勾选变了 = 一条 checklist_item;条目增删 / 改字 / 换顺序 = 一条 checklist。
+  const a = items(before.checklist_json), b = items(after.checklist_json);
+  const shape = (xs: Item[]) => xs.map(x => `${x.id}\u0000${x.text}`).join("\u0001");
+  if (shape(a) === shape(b)) {
+    for (let i = 0; i < b.length; i++) if (a[i].done !== b[i].done) out.push({ kind: "changed", field: "checklist_item", old: a[i], new: b[i] });
+  } else {
+    out.push({ kind: "changed", field: "checklist", old: counts(a), new: counts(b) });
+  }
+  if ((before.description || "") !== (after.description || "")) {
+    out.push({ kind: "changed", field: "description", old: { chars: (before.description || "").length }, new: { chars: (after.description || "").length } });
+  }
+  scalar("project", before.project_id || null, after.project_id || null);
+  scalar("parent", before.parent_id || null, after.parent_id || null);
+  scalar("archived", !!before.archived, !!after.archived);
+  return out;
+}
+
+let writes = 0;
+
+/** 记下一张卡的一组流水(调用方负责放进同一个事务)。actorJson = updated_by_json 的那个值。 */
+export function recordRequirementEvents(database: DbAdapter, card: Pick<EventCard, "requirement_id" | "network_id" | "seq" | "title">, actorJson: string | null, drafts: readonly EventDraft[], at: string): void {
+  for (const d of drafts) {
+    database.run(
+      `INSERT INTO requirement_events (network_id, requirement_id, seq, title, actor_json, kind, field, old_json, new_json, created_at)
+       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)`,
+      [card.network_id, card.requirement_id, card.seq ?? null, card.title, actorJson && actorJson !== "null" ? actorJson : null, d.kind, d.field,
+        d.old === null || d.old === undefined ? null : JSON.stringify(d.old), d.new === null || d.new === undefined ? null : JSON.stringify(d.new), at],
+    );
+    writes++;
+  }
+  if (drafts.length && writes >= PRUNE_EVERY) {
+    writes = 0;
+    database.run("DELETE FROM requirement_events WHERE created_at < ?1", [new Date(Date.parse(at) - EVENTS_RETENTION_MS).toISOString()]);
+  }
+}
+
+export type EventRow = { id: number | string; network_id: string; requirement_id: string; seq: number | string | null; title: string | null; actor_json: string | null; kind: string; field: string | null; old_json: string | null; new_json: string | null; created_at: string };
+
+/** 对外的一条(id 转成字符串:PostgreSQL 的 BIGSERIAL 可能回成字符串或 bigint,客户端一律按字符串比较 / 翻页)。 */
+export const eventPublic = (row: EventRow) => ({
+  id: String(row.id),
+  requirement_id: row.requirement_id,
+  seq: row.seq == null ? null : Number(row.seq),
+  title: row.title,
+  actor: parse(row.actor_json),
+  kind: row.kind,
+  field: row.field,
+  old: parse(row.old_json),
+  new: parse(row.new_json),
+  at: row.created_at,
+});

package/src/requirement-notify.ts

@@ -0,0 +1,165 @@
+// 参与人改了任务 → 通知相关的人(Vincent 2026-10-01「参与人可以改，但是改了之后需要有个通知」)。
+//
+// 谁触发:操作者是人,且是这张卡的参与人、不是负责人(权限上参与人只能改状态和检查项,见 task-access.ts
+// PARTICIPANT_EDIT_FIELDS;老成员 task_access='all' 的参与人改了也一样通知)。只说状态和检查项的变化,别的字段不进正文。
+// 通知谁:负责人、创建者、其他参与人 —— 只要人类、去重、不含操作者本人。
+// 怎么送:复用人与人私信(human-dm.ts,user_inbox kind=human_dm + /events/users/me 的 desktop_message),
+//   发信人 = 操作者。App 已有的展示:顶部提示 + 人员列表未读 + 与他的私信会话。不新增渠道。
+// 合并:同一 (收件人, 操作者, 卡) 在 COALESCE_WINDOW_MS 内的连续改动并进同一条还没读的私信(改写正文,不再弹)。
+
+import { db, uuidv4 } from "./db.js";
+import { isParticipant } from "./task-access.js";
+import { rewriteUnreadNoticeDm, sendNoticeDm } from "./human-dm.js";
+
+export const COALESCE_WINDOW_MS = 60_000;
+const COLUMN_LABEL: Record<string, string> = { pool: "需求池", doing: "进行中", done: "完成" };
+const MAX_LINES = 20;
+const MAX_ITEM_CHARS = 40;
+
+export type NoticeCard = {
+  requirement_id: string;
+  network_id: string;
+  seq: number | null;
+  title: string;
+  column_name: string;
+  checklist_json: string | null;
+  owner_json: string | null;
+  participants_json: string | null;
+  created_by: string | null;
+  created_by_json: string | null;
+};
+
+type Item = { id: string; text: string; done: boolean };
+const items = (raw: string | null): Item[] => {
+  try {
+    const list = raw ? JSON.parse(raw) : [];
+    return Array.isArray(list) ? list.filter((x) => x && typeof x.id === "string").map((x) => ({ id: x.id, text: String(x.text ?? ""), done: x.done === true })) : [];
+  } catch { return []; }
+};
+const clip = (s: string) => { const c = Array.from(s); return c.length > MAX_ITEM_CHARS ? c.slice(0, MAX_ITEM_CHARS).join("") + "…" : s; };
+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;
+};
+
+/**
+ * 这次改动里要说的那几件事,按「对象」做键:同一个对象后一次覆盖前一次(先勾再取消 = 只剩「取消勾选」)。
+ * 键:column / ck:<id>。值:一句短话(不带主语和卡名)。
+ */
+export function describeChanges(before: Pick<NoticeCard, "column_name" | "checklist_json">, after: Pick<NoticeCard, "column_name" | "checklist_json">): Array<[string, string]> {
+  const out: Array<[string, string]> = [];
+  if (before.column_name !== after.column_name) out.push(["column", `改为 ${COLUMN_LABEL[after.column_name] ?? after.column_name}`]);
+  const a = items(before.checklist_json), b = items(after.checklist_json);
+  const was = new Map(a.map((x) => [x.id, x]));
+  const now = new Map(b.map((x) => [x.id, x]));
+  for (const x of b) {
+    const old = was.get(x.id);
+    if (!old) { out.push([`ck:${x.id}`, `添加了检查项「${clip(x.text)}」`]); continue; }
+    if (old.text !== x.text) out.push([`ck:${x.id}`, `把检查项「${clip(old.text)}」改为「${clip(x.text)}」`]);
+    else if (old.done !== x.done) out.push([`ck:${x.id}`, `${x.done ? "勾选了" : "取消勾选了"}检查项「${clip(x.text)}」`]);
+  }
+  for (const x of a) if (!now.has(x.id)) out.push([`ck:${x.id}`, `删除了检查项「${clip(x.text)}」`]);
+  return out;
+}
+
+/** 收件人:负责人、创建者、其他参与人(只要人,去重,去掉操作者)。 */
+export function noticeRecipients(card: NoticeCard, actorUserId: string): string[] {
+  const ids = new Set<string>();
+  const owner = userIdOf(parse(card.owner_json));
+  if (owner) ids.add(owner);
+  const creator = userIdOf(parse(card.created_by_json)) ?? (!card.created_by_json && card.created_by ? card.created_by : null);
+  if (creator) ids.add(creator);
+  const participants = parse(card.participants_json);
+  if (Array.isArray(participants)) for (const p of participants) { const id = userIdOf(p); if (id) ids.add(id); }
+  ids.delete(actorUserId);
+
+  return [...ids];
+}
+
+export function noticeText(actorName: string, title: string, lines: readonly string[]): string {
+  if (lines.length === 1) {
+    const line = lines[0];
+    return line.startsWith("改为 ") ? `${actorName} 把「${title}」${line}` : `${actorName} 在「${title}」${line}`;
+  }
+  const shown = lines.slice(-MAX_LINES);
+  const more = lines.length > shown.length ? `\n…另有 ${lines.length - shown.length} 项` : "";
+  return `${actorName} 更新了「${title}」:\n${shown.map((l) => `· ${l}`).join("\n")}${more}`;
+}
+
+type Pending = { messageId: string; startedAt: number; changes: Map<string, string> };
+const pending = new Map<string, Pending>();
+
+export function __resetRequirementNoticesForTest(): void { pending.clear(); }
+
+/**
+ * 参与人(非负责人)改完一张卡之后调用(事务提交之后)。before / after = 改前改后的行。
+ * 不是参与人、或者状态和检查项都没变 → 什么都不发。返回这次通知到的收件人(测试用)。
+ */
+export function notifyParticipantChange(input: { before: NoticeCard; after: NoticeCard; actorUserId: string; now?: number }): string[] {
+  const { before, after, actorUserId } = input;
+  if (!isParticipant(before, actorUserId)) return [];
+  if (userIdOf(parse(before.owner_json)) === actorUserId) return [];
+
+  const changes = describeChanges(before, after);
+  if (!changes.length) return [];
+  const now = input.now ?? Date.now();
+  // 用户名从库里取:MCP 入口的 auth.username 是空串。
+  const user = db.get<{ username: string; display_name: string | null }>("SELECT username, display_name FROM users WHERE user_id = ?1", actorUserId);
+  if (!user) return [];
+  const actorName = user.display_name?.trim() || user.username;
+  const sender = { userId: actorUserId, username: user.username };
+  const sent: string[] = [];
+  for (const target of noticeRecipients(after, actorUserId)) {
+    const key = `${target}\u0000${actorUserId}\u0000${after.requirement_id}`;
+    const prev = pending.get(key);
+    const live = prev && now - prev.startedAt < COALESCE_WINDOW_MS ? prev : null;
+    const merged = new Map(live?.changes ?? []);
+    for (const [k, line] of changes) { merged.delete(k); merged.set(k, line); }
+    const meta = JSON.stringify({ task_notice: { requirement_id: after.requirement_id, seq: after.seq ?? null, network_id: after.network_id } });
+    const base = { networkId: after.network_id, targetUserId: target, sender, title: "任务更新", metaJson: meta };
+    if (live && rewriteUnreadNoticeDm({ ...base, messageId: live.messageId, text: noticeText(actorName, after.title, [...merged.values()]) })) {
+      live.changes = merged;
+      sent.push(target);
+      continue;
+    }
+    const messageId = `dm_task_${uuidv4()}`;
+    const fresh = new Map(changes);
+    if (!sendNoticeDm({ ...base, messageId, text: noticeText(actorName, after.title, [...fresh.values()]) })) continue;
+    pending.set(key, { messageId, startedAt: now, changes: fresh });
+    sent.push(target);
+  }
+  if (pending.size > 5_000) for (const [k, p] of pending) if (now - p.startedAt >= COALESCE_WINDOW_MS) pending.delete(k);
+  return sent;
+}
+
+/**
+ * RFC-040 Q4:部门负责人(只凭负责人身份)删了本部门的一张卡 → 私信卡的负责人。
+ * 卡没有人类负责人时,私信负责 Agent 的主人(这张卡正是因为那个 Agent 才算「本部门的卡」)。
+ * 删的人就是收件人 / 收件人已不在网络 → 不发。返回收件人(测试用),没发 → null。
+ */
+export function notifyLeaderDeleted(input: { card: NoticeCard & { agent_owner_json?: string | null }; actorUserId: string }): string | null {
+  const { card, actorUserId } = input;
+  let target = userIdOf(parse(card.owner_json));
+  if (!target) {
+    const agent = parse(card.agent_owner_json ?? null) as { kind?: unknown; id?: unknown } | null;
+    if (agent?.kind === "node" && typeof agent.id === "string") {
+      target = db.get<{ owner_user_id: string | null }>("SELECT owner_user_id FROM nodes WHERE node_id = ?1 AND network_id = ?2", agent.id, card.network_id)?.owner_user_id ?? null;
+    }
+  }
+  if (!target || target === actorUserId) return null;
+  const user = db.get<{ username: string; display_name: string | null }>("SELECT username, display_name FROM users WHERE user_id = ?1", actorUserId);
+  if (!user) return null;
+  const actorName = user.display_name?.trim() || user.username;
+  const number = card.seq ? ` #${card.seq}` : "";
+  const sent = sendNoticeDm({
+    networkId: card.network_id,
+    targetUserId: target,
+    sender: { userId: actorUserId, username: user.username },
+    title: "任务删除",
+    metaJson: JSON.stringify({ task_notice: { requirement_id: card.requirement_id, seq: card.seq ?? null, network_id: card.network_id, deleted: true } }),
+    messageId: `dm_task_${uuidv4()}`,
+    text: `${actorName}(部门负责人)删除了你负责的任务${number}「${card.title}」`,
+  });
+  return sent ? target : null;
+}