@sleep2agi/commhub-server 0.9.0-preview.72 → 0.9.0-preview.74

package/src/push.ts

@@ -158,6 +158,10 @@ function closeClient(client: SSEClient, reason: string): void {
     // we're done with it.
   }
   console.log(`[${ts()}] SSE ✕ ${printableKey(client.key)} closed (reason=${reason})`);
+  if (isUserStreamClient(client)) {
+    touchUserSeen(client.subscriberUserId!);
+    if (!isUserOnline(client.subscriberUserId!)) notifyPresence(client.subscriberUserId!, false);
+  }
 }
 
 /** Best-effort enqueue with backpressure guard. Returns:
@@ -308,8 +312,11 @@ function createStreamForKey(
         ...(opts.eventFilter ? { eventFilter: opts.eventFilter } : {}),
       };
 
+      const presenceUser = isUserStreamClient(client) ? client.subscriberUserId! : null;
+      const wasOnline = presenceUser ? isUserOnline(presenceUser) : true;
       if (!clients.has(key)) clients.set(key, []);
       clients.get(key)!.push(client);
+      if (presenceUser) touchUserSeen(presenceUser);
       console.log(`[${ts()}] SSE ← ${printableKey(key)} connected (${clients.get(key)!.length} clients)`);
 
       // Send initial connected frame through the backpressure guard so
@@ -328,6 +335,7 @@ function createStreamForKey(
           return;
         }
         const result = tryEnqueueBytes(client, encoder.encode(`: keepalive\n\n`));
+        if (result === "ok" && isUserStreamClient(client)) touchUserSeen(client.subscriberUserId!);
         if (result === "dead") {
           // closeClient already cleared the timer; just make sure we
           // also prune from the map.
@@ -337,6 +345,8 @@ function createStreamForKey(
       (client.keepaliveTimer as any)?.unref?.();
 
       ensureLivenessSweep();
+      // 在线状态的广播放在 connected 帧之后:订阅方先拿到自己的 connected,再看到别人的变化。
+      if (presenceUser && !wasOnline) notifyPresence(presenceUser, true);
     },
     cancel() {
       // Consumer side hangup — straightforward path, mark closed and
@@ -523,6 +533,75 @@ export function pushUserEvent(
   if (needPrune) pruneClosed(key);
 }
 
+// ── 人类成员在线状态(人员列表的在线点)──────────────────────────────────
+// 判据就是上面这张用户流(/events/users/me)注册表:此刻有活着的用户流 = 在线。按**用户**算,
+// 不按网络 —— 桌面端同一时刻只连当前网络的用户流,按网络算会把正在别的网络里的人画成离线。
+// last_seen 只在内存:连上、每次 keepalive 成功、断开时刷新。Hub 重启后清空(未知 = null,
+// 调用方不要把 null 画成「很久以前」)。
+
+const userLastSeen = new Map<string, number>();
+let presenceListener: ((userId: string, online: boolean, lastSeenAt: string | null) => void) | null = null;
+
+function isUserStreamClient(client: SSEClient): boolean {
+  return !!client.subscriberUserId && client.key.startsWith(USER_KEY_PREFIX);
+}
+
+function touchUserSeen(userId: string): void {
+  userLastSeen.set(userId, Date.now());
+}
+
+function isUserOnline(userId: string): boolean {
+  for (const [key, arr] of clients) {
+    if (!key.startsWith(USER_KEY_PREFIX)) continue;
+    if (arr.some((c) => !c.closed && c.subscriberUserId === userId)) return true;
+  }
+  return false;
+}
+
+function lastSeenIso(userId: string): string | null {
+  const ms = userLastSeen.get(userId);
+  return ms === undefined ? null : new Date(ms).toISOString();
+}
+
+function notifyPresence(userId: string, online: boolean): void {
+  if (!presenceListener) return;
+  try {
+    presenceListener(userId, online, lastSeenIso(userId));
+  } catch (e: any) {
+    console.log(`[${ts()}] presence listener failed: ${e?.message || e}`);
+  }
+}
+
+/** 用户的第一条用户流连上 / 最后一条断开时回调(server.ts 用它向同网络成员推 member_presence)。 */
+export function onUserPresenceChange(cb: ((userId: string, online: boolean, lastSeenAt: string | null) => void) | null): void {
+  presenceListener = cb;
+}
+
+/** 一批用户此刻的在线状态。鉴权由调用方负责。 */
+export function getUserPresence(userIds: readonly string[]): Map<string, { online: boolean; last_seen_at: string | null }> {
+  const online = new Set<string>();
+  for (const [key, arr] of clients) {
+    if (!key.startsWith(USER_KEY_PREFIX)) continue;
+    for (const c of arr) if (!c.closed && c.subscriberUserId) online.add(c.subscriberUserId);
+  }
+  const out = new Map<string, { online: boolean; last_seen_at: string | null }>();
+  for (const uid of userIds) out.set(uid, { online: online.has(uid), last_seen_at: lastSeenIso(uid) });
+  return out;
+}
+
+/** 推给某网络里所有连着用户流的人(可排除一个)。鉴权由调用方负责。 */
+export function pushUserEventToNetwork(networkId: string, event: Record<string, unknown>, exceptUserId?: string): number {
+  const prefix = `${USER_KEY_PREFIX}${networkId}:`;
+  const recipients: string[] = [];
+  for (const key of clients.keys()) {
+    if (!key.startsWith(prefix)) continue;
+    const uid = key.slice(prefix.length);
+    if (uid && uid !== exceptUserId) recipients.push(uid);
+  }
+  for (const uid of recipients) pushUserEvent(networkId, uid, event);
+  return recipients.length;
+}
+
 /**
  * 多用户 Agent 权限:某用户在某网络的授权 / 成员资格变了,断开他在这个网络里**订阅时带了身份**
  * 的流(网络观察流、用户流),客户端重连时按新权限重新鉴权。返回断开的条数。
@@ -549,6 +628,7 @@ export function __resetSSEClientsForTest(): void {
     for (const c of arr) closeClient(c, "reset-for-test");
   }
   clients.clear();
+  userLastSeen.clear();
   if (livenessSweepTimer) {
     clearInterval(livenessSweepTimer);
     livenessSweepTimer = null;

package/src/requirement-tag-ops-http.test.ts

@@ -0,0 +1,266 @@
+// 标签管理(POST /api/requirements/tags/ops + GET /api/requirements/tags 的 counts / colors / can_manage)
+// —— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+//
+// 场景:Hub 管理员 admin 的网络 NET,另有一个不相干的网络 NET2(同名标签,不能被波及)。成员:
+//   alice —— scoped 成员(RFC-038 §9),只授权项目 P1;
+//   carol —— task_access='all' 的老成员;
+//   vic   —— viewer。
+// 正向:改名 / 合并 / 删除改写网络里每张带这个标签的卡(含归档的)、颜色跟着挪、写审计、updated_at 前移;
+//       carol 与 owner 能管;GET 带用量与颜色。
+// 反向:scoped / viewer / 节点令牌被挡且一张卡都不改;scoped 的 counts / colors 只含看得见的卡;
+//       不存在的标签 404、坏参数 400;事务中途失败一张都不改;别的网络不受影响。
+
+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-tag-ops-"));
+let BASE = "";
+let hub: any = null;
+let db: any = null;
+const PW = "TagOpsPassw0rd!x";
+let NET = "";
+let NET2 = "";
+let admin = { token: "", id: "" };
+let other = { token: "", id: "" };
+let alice = { token: "", id: "" };
+let carol = { token: "", id: "" };
+let vic = { token: "", id: "" };
+let nodeToken = "";
+let P1 = "";
+const C: Record<string, string> = {};
+
+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 op = (token: string, payload: unknown, net = NET) => send(token, "POST", `/api/requirements/tags/ops?network_id=${net}`, payload);
+const tagsOf = (token: string, net = NET) => send(token, "GET", `/api/requirements/tags?network_id=${net}`);
+const cardTags = (name: string): string[] => JSON.parse(db.get("SELECT tags_json FROM requirements WHERE requirement_id = ?1", C[name]).tags_json);
+const snapshot = () => Object.fromEntries(Object.keys(C).map(name => [name, cardTags(name)]));
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  ({ db } = await import("./db.js"));
+  const { createNetworkTokenForNode, register } = await import("./auth.js");
+  const stamp = Date.now();
+  const a = register(`to_admin_${stamp}`, 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 b = register(`to_other_${stamp}`, PW, undefined, "Other");
+  expect(b.ok).toBe(true);
+  other = { token: b.token!, id: b.user!.user_id };
+  NET2 = b.network_id!;
+  const ntok = createNetworkTokenForNode(admin.id, NET, "tag-node");
+  expect(ntok.ok).toBe(true);
+  nodeToken = ntok.token!;
+
+  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, role: string) => {
+    const r = await send(admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role });
+    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 };
+  };
+  alice = await mk(`to_alice_${stamp}`, "member");
+  carol = await mk(`to_carol_${stamp}`, "member");
+  vic = await mk(`to_vic_${stamp}`, "viewer");
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, alice.id]);
+  db.run("UPDATE network_members SET task_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, carol.id]);
+
+  const p = await send(admin.token, "POST", "/api/requirements/projects", { network_id: NET, name: "to-P1" });
+  expect(p.status).toBe(201);
+  P1 = p.body.project.id;
+  const g = await send(admin.token, "PUT", `/api/networks/${NET}/members/${alice.id}/task-grants`, { project_grants: [{ project_id: P1, can_edit: true }] });
+  expect(g.status).toBe(200);
+
+  const card = async (name: string, tags: string[], extra: Record<string, unknown> = {}, token = admin.token, net = NET) => {
+    const r = await send(token, "POST", "/api/requirements", { network_id: net, name, tags, ...extra });
+    expect(r.status).toBe(201);
+    C[name] = r.body.requirement.id;
+  };
+  await card("visible", ["UI", "交互", "bug"], { project_id: P1 });
+  await card("hidden", ["UI", "secret"]);
+  await card("archived", ["UI", "旧"], { archived: true });
+  await card("both", ["交互", "TMWork", "UI"]);
+  await card("plain", []);
+  await card("net2", ["UI", "交互"], {}, other.token, NET2);
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/requirements/tags", () => {
+  test("owner:tags 仍是排序后的字符串数组(旧 App 形状不变),多出 counts / colors / can_manage", async () => {
+    const r = await tagsOf(admin.token);
+    expect(r.status).toBe(200);
+    expect(r.body.tags).toEqual(["TMWork", "UI", "bug", "secret", "交互", "旧"]);
+    expect(r.body.counts).toEqual({ UI: 4, 交互: 2, bug: 1, secret: 1, 旧: 1, TMWork: 1 });
+    expect(r.body.colors).toEqual({});
+    expect(r.body.can_manage).toBe(true);
+  });
+
+  test("scoped 成员:counts 只数看得见的卡,不能管;viewer 与节点令牌也不能管;老成员能管", async () => {
+    const a = await tagsOf(alice.token);
+    expect(a.body.tags).toEqual(["UI", "bug", "交互"]);
+    expect(a.body.counts).toEqual({ UI: 1, bug: 1, 交互: 1 });
+    expect(a.body.can_manage).toBe(false);
+    expect((await tagsOf(vic.token)).body.can_manage).toBe(false);
+    expect((await send(nodeToken, "GET", "/api/requirements/tags")).body.can_manage).toBe(false);
+    expect((await tagsOf(carol.token)).body.can_manage).toBe(true);
+  });
+
+  test("列表响应的 capabilities 带 tag_ops", async () => {
+    const r = await send(admin.token, "GET", `/api/requirements?network_id=${NET}`);
+    expect(r.body.capabilities).toContain("tag_ops");
+  });
+});
+
+describe("被拒的调用一张卡都不改", () => {
+  test("scoped 成员 403(连他看得见的那张也不改,不做半套改名)", async () => {
+    const before = snapshot();
+    for (const payload of [{ op: "rename", from: "UI", to: "界面" }, { op: "delete", tag: "bug" }, { op: "merge", from: ["UI", "交互"], to: "x" }, { op: "color", tag: "UI", color: "#123456" }]) {
+      const r = await op(alice.token, payload);
+      expect(r.status).toBe(403);
+      expect(r.body.error).toBe("permission_denied");
+    }
+    expect(snapshot()).toEqual(before);
+    expect(db.get("SELECT COUNT(*) AS n FROM network_tags WHERE network_id = ?1", NET).n).toBe(0);
+  });
+
+  test("viewer 403;节点令牌 403 user_token_required;别的网络的 owner 碰不到这个网络", async () => {
+    const before = snapshot();
+    expect((await op(vic.token, { op: "delete", tag: "UI" })).status).toBe(403);
+    const n = await send(nodeToken, "POST", "/api/requirements/tags/ops", { op: "delete", tag: "UI" });
+    expect(n.status).toBe(403);
+    expect(n.body.error).toBe("user_token_required");
+    expect((await op(other.token, { op: "delete", tag: "UI" })).status).toBe(403);
+    expect(snapshot()).toEqual(before);
+  });
+
+  test("坏参数 400、不存在的标签 404、GET 到 ops 404", async () => {
+    expect((await op(admin.token, { op: "explode" })).body.error).toBe("invalid_tag_op");
+    expect((await op(admin.token, { op: "rename", from: "UI", to: "" })).body.error).toBe("invalid_tag");
+    expect((await op(admin.token, { op: "rename", from: "UI", to: "x".repeat(21) })).body.error).toBe("invalid_tag");
+    expect((await op(admin.token, { op: "rename", from: "UI", to: " UI " })).body.error).toBe("same_tag");
+    expect((await op(admin.token, { op: "merge", from: [], to: "UI" })).body.error).toBe("invalid_tag");
+    expect((await op(admin.token, { op: "merge", from: ["UI"], to: "UI" })).body.error).toBe("same_tag");
+    expect((await op(admin.token, { op: "color", tag: "UI", color: "red" })).body.error).toBe("invalid_tag_color");
+    const missing = await op(admin.token, { op: "delete", tag: "没有这个" });
+    expect(missing.status).toBe(404);
+    expect(missing.body.error).toBe("tag_not_found");
+    expect((await send(admin.token, "GET", `/api/requirements/tags/ops?network_id=${NET}`)).status).toBe(404);
+  });
+
+  test("事务:改到一半失败 → 一张都不改,颜色也不挪", async () => {
+    expect((await op(admin.token, { op: "color", tag: "UI", color: "#2563EB" })).status).toBe(200);
+    // 让其中一张卡的 UPDATE 抛错(SQLite 用 RAISE,PostgreSQL 用 plpgsql 触发器;PG 阶梯会跑这个文件)。
+    const pg = db.dialect === "postgres";
+    if (pg) {
+      db.exec(`CREATE OR REPLACE FUNCTION tag_ops_fail() RETURNS trigger AS $$ BEGIN IF NEW.requirement_id = '${C["both"]}' THEN RAISE EXCEPTION 'boom'; END IF; RETURN NEW; END $$ LANGUAGE plpgsql`);
+      db.exec("CREATE TRIGGER tag_ops_fail BEFORE UPDATE OF tags_json ON requirements FOR EACH ROW EXECUTE FUNCTION tag_ops_fail()");
+    } else {
+      db.exec(`CREATE TRIGGER tag_ops_fail BEFORE UPDATE OF tags_json ON requirements WHEN NEW.requirement_id = '${C["both"]}' BEGIN SELECT RAISE(ABORT, 'boom'); END;`);
+    }
+    const before = snapshot();
+    try {
+      const r = await op(admin.token, { op: "rename", from: "UI", to: "界面" });
+      expect(r.status).toBeGreaterThanOrEqual(500);
+    } finally {
+      db.exec(pg ? "DROP TRIGGER tag_ops_fail ON requirements" : "DROP TRIGGER tag_ops_fail");
+      if (pg) db.exec("DROP FUNCTION tag_ops_fail()");
+    }
+    expect(snapshot()).toEqual(before);
+    expect(db.get("SELECT color FROM network_tags WHERE network_id = ?1 AND name = 'UI'", NET).color).toBe("#2563eb");
+  });
+});
+
+describe("改名 / 合并 / 删除 / 颜色", () => {
+  test("颜色:设置(存小写)、GET 带出来;scoped 成员看不到他看不见的标签的颜色", async () => {
+    expect((await op(admin.token, { op: "color", tag: "secret", color: "#DC2626" })).status).toBe(200);
+    const r = await tagsOf(admin.token);
+    expect(r.body.colors).toEqual({ UI: "#2563eb", secret: "#dc2626" });
+    expect((await tagsOf(alice.token)).body.colors).toEqual({ UI: "#2563eb" });
+    expect((await op(admin.token, { op: "color", tag: "secret", color: null })).status).toBe(200);
+    expect((await tagsOf(admin.token)).body.colors).toEqual({ UI: "#2563eb" });
+  });
+
+  test("改名:每张卡(含看不见的、归档的)都改,位置不变;颜色跟着走;updated_at 前移;审计;别的网络不动", async () => {
+    const t0 = new Date().toISOString();
+    const r = await op(admin.token, { op: "rename", from: "UI", to: "界面" });
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ ok: true, op: "rename", affected: 4 });
+    expect(cardTags("visible")).toEqual(["界面", "交互", "bug"]);
+    expect(cardTags("hidden")).toEqual(["界面", "secret"]);
+    expect(cardTags("archived")).toEqual(["界面", "旧"]);
+    expect(cardTags("both")).toEqual(["交互", "TMWork", "界面"]);
+    expect(cardTags("net2")).toEqual(["UI", "交互"]);
+    expect((await tagsOf(admin.token)).body.colors).toEqual({ 界面: "#2563eb" });
+    const row = db.get("SELECT updated_at, updated_by_json FROM requirements WHERE requirement_id = ?1", C["hidden"]);
+    expect(row.updated_at >= t0).toBe(true);
+    expect(JSON.parse(row.updated_by_json)).toEqual({ kind: "user", id: admin.id });
+    const audit = db.get("SELECT detail, target_id, network_id FROM audit_log WHERE action = 'requirement_tag_rename' ORDER BY id DESC LIMIT 1");
+    expect(audit.target_id).toBe("界面");
+    expect(audit.network_id).toBe(NET);
+    expect(JSON.parse(audit.detail)).toEqual({ op: "rename", from: "UI", to: "界面", affected: 4 });
+    // 这次改动 updated_since 同步得到(包括 GET 列表)。
+    const since = await send(admin.token, "GET", `/api/requirements?network_id=${NET}&include_archived=1&updated_since=${encodeURIComponent(t0)}`);
+    expect(since.body.requirements.map((x: any) => x.name).sort()).toEqual(["archived", "both", "hidden", "visible"]);
+  });
+
+  test("改名成已存在的标签 = 合并,同一张卡上不出现两次", async () => {
+    const r = await op(carol.token, { op: "rename", from: "交互", to: "界面" });
+    expect(r.body.affected).toBe(2);
+    expect(cardTags("visible")).toEqual(["界面", "bug"]);
+    expect(cardTags("both")).toEqual(["界面", "TMWork"]);
+  });
+
+  test("合并:多个来源进一个新标签;目标没颜色就继承来源的;来源颜色行删掉", async () => {
+    expect((await op(admin.token, { op: "color", tag: "旧", color: "#16a34a" })).status).toBe(200);
+    const r = await op(admin.token, { op: "merge", from: ["bug", "旧", "secret", "不存在"], to: "杂项" });
+    expect(r.body).toEqual({ ok: true, op: "merge", affected: 3 });
+    expect(cardTags("visible")).toEqual(["界面", "杂项"]);
+    expect(cardTags("hidden")).toEqual(["界面", "杂项"]);
+    expect(cardTags("archived")).toEqual(["界面", "杂项"]);
+    expect((await tagsOf(admin.token)).body.colors).toEqual({ 界面: "#2563eb", 杂项: "#16a34a" });
+    expect(db.get("SELECT COUNT(*) AS n FROM network_tags WHERE network_id = ?1 AND name = '旧'", NET).n).toBe(0);
+  });
+
+  test("合并进已有颜色的目标:目标颜色不变", async () => {
+    const r = await op(admin.token, { op: "merge", from: ["杂项"], to: "界面" });
+    expect(r.body.affected).toBe(3);
+    expect((await tagsOf(admin.token)).body.colors).toEqual({ 界面: "#2563eb" });
+  });
+
+  test("删除:从每张卡上拿掉(卡保留),颜色行删掉,审计带 affected", async () => {
+    const r = await op(admin.token, { op: "delete", tag: "界面" });
+    expect(r.body).toEqual({ ok: true, op: "delete", affected: 4 });
+    expect(cardTags("visible")).toEqual([]);
+    expect(cardTags("both")).toEqual(["TMWork"]);
+    expect(db.get("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", NET).n).toBe(5);
+    expect(db.get("SELECT COUNT(*) AS n FROM network_tags WHERE network_id = ?1", NET).n).toBe(0);
+    const audit = db.get("SELECT detail FROM audit_log WHERE action = 'requirement_tag_delete' ORDER BY id DESC LIMIT 1");
+    expect(JSON.parse(audit.detail)).toEqual({ op: "delete", tag: "界面", affected: 4 });
+    expect((await tagsOf(admin.token)).body.tags).toEqual(["TMWork"]);
+    expect(cardTags("net2")).toEqual(["UI", "交互"]);
+  });
+});

package/src/requirement-tags.ts

@@ -14,3 +14,76 @@ export function normalizeTags(value: unknown): string[] | null {
 export function storedTags(value: string | null): string[] {
   try { return normalizeTags(JSON.parse(value || "[]")) ?? []; } catch { return []; }
 }
+
+// ── 标签管理(改名 / 合并 / 删除 / 颜色) ──
+// 标签只是卡片 tags 数组里的字符串,没有自己的表;批量操作 = 把网络里每张带这个标签的卡的数组改写一遍。
+// 颜色是可选的,单独存在 network_tags(network_id, name, color);没行 = 客户端用默认灰。
+export const MAX_MERGE_SOURCES = 50;
+export type TagOp =
+  | { op: "rename"; from: string; to: string }
+  | { op: "merge"; from: string[]; to: string }
+  | { op: "delete"; tag: string }
+  | { op: "color"; tag: string; color: string | null };
+
+/** 单个标签名,规则同 normalizeTags。不合法 = null。 */
+export function tagName(value: unknown): string | null {
+  const tags = normalizeTags([value]);
+  return tags && tags.length === 1 ? tags[0] : null;
+}
+
+const TAG_COLOR = /^#[0-9a-fA-F]{6}$/;
+/** 请求体 → 操作;不合法返回错误码。 */
+export function parseTagOp(body: Record<string, unknown>): TagOp | { error: string } {
+  switch (body.op) {
+    case "rename": {
+      const from = tagName(body.from), to = tagName(body.to);
+      if (!from || !to) return { error: "invalid_tag" };
+      if (from === to) return { error: "same_tag" };
+      return { op: "rename", from, to };
+    }
+    case "merge": {
+      if (!Array.isArray(body.from) || body.from.length === 0 || body.from.length > MAX_MERGE_SOURCES) return { error: "invalid_tag" };
+      const from: string[] = [];
+      for (const value of body.from) {
+        const tag = tagName(value);
+        if (!tag) return { error: "invalid_tag" };
+        if (!from.includes(tag)) from.push(tag);
+      }
+      const to = tagName(body.to);
+      if (!to) return { error: "invalid_tag" };
+      // 目标自己出现在来源里不算来源(合并进自己 = 什么都不做)。
+      const sources = from.filter(tag => tag !== to);
+      if (!sources.length) return { error: "same_tag" };
+      return { op: "merge", from: sources, to };
+    }
+    case "delete": {
+      const tag = tagName(body.tag);
+      return tag ? { op: "delete", tag } : { error: "invalid_tag" };
+    }
+    case "color": {
+      const tag = tagName(body.tag);
+      if (!tag) return { error: "invalid_tag" };
+      if (body.color !== null && (typeof body.color !== "string" || !TAG_COLOR.test(body.color))) return { error: "invalid_tag_color" };
+      return { op: "color", tag, color: body.color === null ? null : (body.color as string).toLowerCase() };
+    }
+    default:
+      return { error: "invalid_tag_op" };
+  }
+}
+
+/** 这张卡的标签被这个操作改写后的样子;没变返回 null。顺序保留(新名字占第一个来源的位置),去重。 */
+export function applyTagOp(tags: string[], op: TagOp): string[] | null {
+  let sources: string[];
+  let to: string | null;
+  if (op.op === "rename") { sources = [op.from]; to = op.to; }
+  else if (op.op === "merge") { sources = op.from; to = op.to; }
+  else if (op.op === "delete") { sources = [op.tag]; to = null; }
+  else return null;
+  if (!tags.some(tag => sources.includes(tag))) return null;
+  const next: string[] = [];
+  for (const tag of tags) {
+    const mapped = sources.includes(tag) ? to : tag;
+    if (mapped !== null && !next.includes(mapped)) next.push(mapped);
+  }
+  return next;
+}

package/src/requirements-completed-at-migration.test.ts

@@ -0,0 +1,70 @@
+// 完成时间的启动迁移(requirements-migrate.ts ensureRequirementCompletedAt):用加完成时间之前的表结构建库、塞行,
+// 再 import db.ts + requirements.ts(真实启动路径)。覆盖:两种旧时间形状、没有 updated_at 的行、
+// 回滚到旧 Hub 期间「移出完成」留下的残值被清掉、「移进完成」的卡被补上,以及重复执行不再改任何东西。
+import { afterAll, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-req-completed-at-"));
+const file = join(dir, "hub.db");
+process.env.COMMHUB_DB = file;
+
+const legacy = new Database(file);
+legacy.exec(`CREATE TABLE requirements (
+  requirement_id TEXT PRIMARY KEY, network_id TEXT NOT NULL, title TEXT NOT NULL,
+  column_name TEXT NOT NULL DEFAULT 'pool' CHECK(column_name IN ('pool', 'doing', 'done')), priority TEXT NOT NULL DEFAULT 'normal', due_on TEXT, assignee TEXT,
+  client_id TEXT, issues_json TEXT, created_by TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')), updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  owner_json TEXT, participants_json TEXT NOT NULL DEFAULT '[]', updated_by_json TEXT)`);
+const seed: [string, string, string, string][] = [
+  // id, column, created_at, updated_at
+  ["r_done_sqlite_ts", "done", "2026-08-01 08:00:00", "2026-09-01 10:00:00"],
+  ["r_done_iso", "done", "2026-08-02T00:00:00.000Z", "2026-09-02T03:04:05.678Z"],
+  ["r_done_bad_updated", "done", "2026-08-03T00:00:00.000Z", "not a time"],
+  ["r_doing", "doing", "2026-08-04T00:00:00.000Z", "2026-09-04T00:00:00.000Z"],
+  ["r_pool", "pool", "2026-08-05T00:00:00.000Z", "2026-09-05T00:00:00.000Z"],
+];
+for (const [id, column, createdAt, updatedAt] of seed) {
+  legacy.run("INSERT INTO requirements (requirement_id, network_id, title, column_name, created_at, updated_at, updated_by_json) VALUES (?1, 'net', ?1, ?2, ?3, ?4, ?5)",
+    [id, column, createdAt, updatedAt, JSON.stringify({ kind: "user", id: "u_last_editor" })]);
+}
+legacy.close();
+
+afterAll(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+const read = (db: any) => Object.fromEntries((db.all("SELECT requirement_id, column_name, updated_at, completed_at, completed_by_json, completed_at_approx FROM requirements") as any[]).map(r => [r.requirement_id, r]));
+
+test("backfill: done rows get an approximate ISO completed_at from updated_at; others stay empty; idempotent", async () => {
+  const { db } = await import("./db.js");
+  await import("./requirements.js");
+  const { ensureRequirementCompletedAt } = await import("./requirements-migrate.js");
+  const by = read(db);
+  expect(by.r_done_sqlite_ts.completed_at).toBe("2026-09-01T10:00:00.000Z");
+  expect(by.r_done_iso.completed_at).toBe("2026-09-02T03:04:05.678Z");
+  // updated_at 读不懂 → 退到 created_at,而不是留空(留空的完成卡在仪表盘上就「没完成过」)
+  expect(by.r_done_bad_updated.completed_at).toBe("2026-08-03T00:00:00.000Z");
+  for (const id of ["r_done_sqlite_ts", "r_done_iso", "r_done_bad_updated"]) {
+    expect(by[id].completed_at_approx).toBe(1);
+    // 最后改的人不是「完成的人」:近似值不猜完成者
+    expect(by[id].completed_by_json).toBeNull();
+    // 补值不碰 updated_at
+    expect(by[id].updated_at).toBe(seed.find(s => s[0] === id)![3]);
+  }
+  for (const id of ["r_doing", "r_pool"]) expect([by[id].completed_at, by[id].completed_by_json, by[id].completed_at_approx]).toEqual([null, null, 0]);
+
+  // 下次启动:什么都不动
+  expect(ensureRequirementCompletedAt(db)).toEqual({ backfilled: 0, cleared: 0 });
+  expect(read(db)).toEqual(by);
+
+  // 回滚到旧 Hub 期间:旧 Hub 不认识这三列 —— 把一张完成的卡移出(列留着旧值)、把一张卡移进完成(列是空的)。
+  db.run("UPDATE requirements SET column_name = 'doing' WHERE requirement_id = 'r_done_iso'");
+  db.run("UPDATE requirements SET column_name = 'done', updated_at = '2026-09-06T00:00:00.000Z' WHERE requirement_id = 'r_pool'");
+  expect(ensureRequirementCompletedAt(db)).toEqual({ backfilled: 1, cleared: 1 });
+  const after = read(db);
+  expect([after.r_done_iso.completed_at, after.r_done_iso.completed_by_json, after.r_done_iso.completed_at_approx]).toEqual([null, null, 0]);
+  expect([after.r_pool.completed_at, after.r_pool.completed_at_approx]).toEqual(["2026-09-06T00:00:00.000Z", 1]);
+  expect(after.r_done_sqlite_ts).toEqual(by.r_done_sqlite_ts);
+  expect(ensureRequirementCompletedAt(db)).toEqual({ backfilled: 0, cleared: 0 });
+});

package/src/requirements-http.test.ts

@@ -35,7 +35,8 @@ beforeAll(async () => {
   expect(viewer.ok).toBe(true);
   viewerToken = viewer.token!;
   const viewerId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", viewer.user!.username)!.user_id;
-  addNetworkMember(networkId, viewerId, "viewer", ownerId);
+  // 这里的 viewer 代表 RFC-038 §9 之前的语义(能读全网、不能写);scoped viewer 在 task-access-http.test.ts 里测。
+  addNetworkMember(networkId, viewerId, "viewer", ownerId, { taskAccess: "all" });
   const ntok = createNetworkTokenForNode(ownerId, networkId, "req-node");
   expect(ntok.ok).toBe(true);
   nodeToken = ntok.token!;
@@ -372,7 +373,7 @@ describe("requirements stay on the hub", () => {
     expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "" }) })).body.requirement.due).toBe("");
     const listed = await api(ownerToken, "/api/requirements");
     expect(listed.body.capabilities).toContain("due_datetime");
-    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging"]);
+    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {

package/src/requirements-migrate.ts

@@ -43,6 +43,22 @@ export function ensureRequirementProjects(database: DbAdapter): void {
   `);
 }
 
+/**
+ * 标签颜色(可选)。标签本身仍只是卡片 tags 数组里的字符串;这里只存「这个网络里这个名字用什么颜色」。
+ * 没有行 = 默认色。改名 / 合并 / 删除时跟着挪或删(见 requirements.ts 的标签管理)。IF NOT EXISTS:重复执行无副作用。
+ */
+export function ensureNetworkTags(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS network_tags (
+      network_id  TEXT NOT NULL,
+      name        TEXT NOT NULL,
+      color       TEXT NOT NULL,
+      updated_at  TEXT NOT NULL,
+      PRIMARY KEY (network_id, name)
+    );
+  `);
+}
+
 /** external_ref 在同一网络里唯一(只管有值的行)。IF NOT EXISTS:重复执行无副作用。 */
 export function ensureRequirementIndexes(database: DbAdapter): void {
   database.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_external_ref ON requirements(network_id, external_ref) WHERE external_ref IS NOT NULL");
@@ -128,6 +144,50 @@ export function ensureRequirementSeq(database: DbAdapter): { backfilled: number
   return { backfilled: pending.length };
 }
 
+/**
+ * 完成时间(仪表盘「今天 / 本周完成了多少」用)。三列只加不改:
+ * - completed_at:进入「完成」列的时刻(ISO,UTC)。移出「完成」列清空;在「完成」列里改别的字段不动它。
+ * - completed_by_json:谁把它移进「完成」的({kind,id},同 updated_by)。
+ * - completed_at_approx:1 = 这个时刻是补出来的近似值(见下),界面可以标「近似」。
+ * 补值:已经在「完成」列、还没有 completed_at 的卡,按 updated_at(没有就 created_at)补,approx = 1,completed_by 留空
+ * —— updated_at 是「最后一次改」,不是「完成那一刻」,只能当近似。旧库里 datetime('now') 的「YYYY-MM-DD HH:MM:SS」(UTC)
+ * 统一换成 ISO,按时间范围比较时不和 ISO 值错位。
+ * 每次启动都跑,重复执行只处理需要处理的行:回滚到旧 Hub 期间移进「完成」的卡补近似值,移出「完成」的卡清掉残留。
+ */
+export function ensureRequirementCompletedAt(database: DbAdapter): { backfilled: number; cleared: number } {
+  for (const column of ["completed_at TEXT", "completed_by_json TEXT", "completed_at_approx INTEGER NOT NULL DEFAULT 0"]) {
+    try { database.exec(`ALTER TABLE requirements ADD COLUMN ${column}`); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
+  }
+  const pending = database.all<{ requirement_id: string; updated_at: string | null; created_at: string | null }>(
+    "SELECT requirement_id, updated_at, created_at FROM requirements WHERE column_name = 'done' AND completed_at IS NULL",
+  );
+  const stale = database.all<{ requirement_id: string }>(
+    "SELECT requirement_id FROM requirements WHERE column_name <> 'done' AND (completed_at IS NOT NULL OR completed_by_json IS NOT NULL OR completed_at_approx <> 0)",
+  );
+  if (pending.length || stale.length) {
+    database.transaction(() => {
+      for (const row of pending) {
+        database.run(
+          "UPDATE requirements SET completed_at = ?1, completed_by_json = NULL, completed_at_approx = 1 WHERE requirement_id = ?2 AND completed_at IS NULL",
+          [isoInstant(row.updated_at) ?? isoInstant(row.created_at) ?? new Date().toISOString(), row.requirement_id],
+        );
+      }
+      for (const row of stale) {
+        database.run("UPDATE requirements SET completed_at = NULL, completed_by_json = NULL, completed_at_approx = 0 WHERE requirement_id = ?1", [row.requirement_id]);
+      }
+    });
+  }
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirements_network_completed ON requirements(network_id, completed_at) WHERE completed_at IS NOT NULL");
+  return { backfilled: pending.length, cleared: stale.length };
+}
+
+/** 库里的时间 → ISO(UTC)。认 ISO 和旧默认值「YYYY-MM-DD HH:MM:SS」(SQLite datetime('now'),UTC);读不懂 → null。 */
+export function isoInstant(value: string | null | undefined): string | null {
+  const s = value ?? "";
+  const ms = Date.parse(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(s) ? `${s.replace(" ", "T")}Z` : s);
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
 /**
  * 给新卡领下一个号。调用方把它和 INSERT 放在同一个事务里:插入失败(client_id / external_ref 撞了)号也一起回滚。
  * 一条语句完成「读 + 加一 + 写回」,两个并发的新建拿不到同一个号;(network_id, seq) 唯一索引兜底。

package/src/requirements-seq-http.test.ts

@@ -122,7 +122,8 @@ describe("requirement short numbers (#N)", () => {
   test("a user whose scope spans two networks gets 409 ambiguous_seq for #N, and network_id resolves it", async () => {
     const { db } = await import("./db.js");
     const { addNetworkMember } = await import("./auth.js");
-    addNetworkMember(otherNet, ownerId, "member", otherId);
+    // 看全网的成员(RFC-038 §9 之前的语义):这里测的是跨网络 #N 歧义,不是任务范围。
+    addNetworkMember(otherNet, ownerId, "member", otherId, { taskAccess: "all" });
     const both = await api(ownerToken, "/api/requirements/%231");
     expect(both.status).toBe(409);
     expect(both.body.error).toBe("ambiguous_seq");