@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.131

package/src/requirement-participant-notify-http.test.ts

@@ -0,0 +1,309 @@
+// 参与人可以改任务的状态和检查项,改了通知相关的人(Vincent 2026-10-01)—— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+// test2123 在真实 PostgreSQL 上原样再跑一遍(COMMHUB_TEST_PG_URL)。
+//
+// 网络 NET(owner = boss)。成员:
+//   owen —— 卡的负责人;cara —— 建卡的人(task_access='all');
+//   pat  —— 参与人,scoped(只看相关任务);pia —— 另一个参与人(all);
+//   sam  —— scoped,与卡无关(看不见)。
+// 正向:pat 改状态 / 勾检查项 / 改检查项列表 → 200;owen、cara、pia 各收到一条私信(发信人 pat),pat 自己没有;
+//       60 s 内连续改动并成一条(未读时改写正文);读过之后再改 → 新的一条;MCP 与 REST 一致。
+// 反向:pat 改标题 / 描述 / 负责人 / 参与人 / 项目 / 优先级 / 日期 / 标签 → 403 task_read_only + field,卡不变、不通知;
+//       负责人自己改不通知;sam 照旧看不见(与不存在的卡逐字节相同)。
+
+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-part-notify-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+process.env.HOST = "127.0.0.1";
+const PW = "PartNotifyPassw0rd!x";
+
+type U = { token: string; id: string; username: string };
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let PROJ = "";
+let db: any;
+let notify: typeof import("./requirement-notify.js");
+let boss: U, owen: U, cara: U, pat: U, pia: U, sam: U;
+
+type R = { status: number; body: any; text: string };
+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, text };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const payload = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(payload.result.content[0].text);
+}
+const userRef = (id: string) => ({ kind: "user", id });
+
+/** 某张卡发出的通知私信:按收件人分组(只看这张卡的,meta.task_notice.requirement_id)。 */
+function notices(reqId: string): Record<string, Array<{ message_id: string; content: string; sender_user_id: string; acked: number; from_session: string }>> {
+  const rows = db.all(
+    "SELECT message_id, user_id, sender_user_id, from_session, content, acked, meta_json FROM user_inbox WHERE network_id = ?1 AND kind = 'human_dm' ORDER BY created_at, message_id",
+    NET,
+  ) as any[];
+  const out: Record<string, any[]> = {};
+  for (const r of rows) {
+    let meta: any = null;
+    try { meta = JSON.parse(r.meta_json); } catch {}
+    if (meta?.task_notice?.requirement_id !== reqId) continue;
+    (out[r.user_id] ||= []).push({ message_id: r.message_id, content: r.content, sender_user_id: r.sender_user_id, acked: Number(r.acked), from_session: r.from_session });
+  }
+  return out;
+}
+
+async function card(name: string, extra: Record<string, unknown> = {}) {
+  const r = await send(cara.token, "POST", "/api/requirements", {
+    network_id: NET, name, owner: userRef(owen.id), participants: [userRef(pat.id), userRef(pia.id)],
+    checklist: [{ id: "i1", text: "写测试", done: false }, { id: "i2", text: "发版", done: false }], ...extra,
+  });
+  expect(r.status).toBe(201);
+  return r.body.requirement.id as string;
+}
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { addNetworkMember, register } = await import("./auth.js");
+  const stamp = Date.now();
+  const mk = (name: string, display?: string): U => {
+    const r = register(`pn_${name}_${stamp}`, PW, undefined, display);
+    expect(r.ok).toBe(true);
+    return { token: r.token!, id: r.user!.user_id, username: r.user!.username };
+  };
+  const b = register(`pn_boss_${stamp}`, PW);
+  expect(b.ok).toBe(true);
+  boss = { token: b.token!, id: b.user!.user_id, username: b.user!.username };
+  NET = b.network_id!;
+  owen = mk("owen"); cara = mk("cara"); pat = mk("pat", "参与人甲"); pia = mk("pia"); sam = mk("sam");
+  addNetworkMember(NET, owen.id, "member", boss.id, { taskAccess: "all" });
+  addNetworkMember(NET, cara.id, "member", boss.id, { taskAccess: "all" });
+  addNetworkMember(NET, pat.id, "member", boss.id, { taskAccess: "scoped" });
+  addNetworkMember(NET, pia.id, "member", boss.id, { taskAccess: "all" });
+  addNetworkMember(NET, sam.id, "member", boss.id, { taskAccess: "scoped" });
+  notify = await import("./requirement-notify.js");
+  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}`;
+  // register() 给每人建了自己的网络:后面的请求一律带 network_id。
+  const p = await send(boss.token, "POST", "/api/requirements/projects", { network_id: NET, name: "pn-proj" });
+  expect(p.status).toBe(201);
+  PROJ = p.body.project.id;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("参与人能改的", () => {
+  test("改状态:200,负责人 / 创建者 / 其他参与人各一条,操作者自己没有", async () => {
+    const id = await card("pn-状态");
+    const r = await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" });
+    expect(r.status).toBe(200);
+    expect(r.body.requirement.column).toBe("doing");
+    const n = notices(id);
+    expect(Object.keys(n).sort()).toEqual([owen.id, cara.id, pia.id].sort());
+    for (const uid of [owen.id, cara.id, pia.id]) {
+      expect(n[uid].length).toBe(1);
+      expect(n[uid][0].sender_user_id).toBe(pat.id);
+      expect(n[uid][0].from_session).toBe(pat.username);
+      expect(n[uid][0].content).toBe("参与人甲 把「pn-状态」改为 进行中");
+    }
+    expect(n[pat.id]).toBeUndefined();
+  });
+
+  test("勾检查项(单条接口):200 并通知", async () => {
+    const id = await card("pn-勾选");
+    const r = await send(pat.token, "PATCH", `/api/requirements/${id}/checklist/i1?network_id=${NET}`, { done: true });
+    expect(r.status).toBe(200);
+    expect(r.body.requirement.checklist.find((x: any) => x.id === "i1").done).toBe(true);
+    expect(notices(id)[owen.id].map(x => x.content)).toEqual(["参与人甲 在「pn-勾选」勾选了检查项「写测试」"]);
+  });
+
+  test("整表改检查项(增 / 删 / 改字)+ 状态:一次 PATCH 一条通知,逐项列出", async () => {
+    const id = await card("pn-整表");
+    const r = await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, {
+      column: "done", checklist: [{ id: "i1", text: "写更多测试", done: false }, { id: "i3", text: "回归", done: false }],
+    });
+    expect(r.status).toBe(200);
+    const n = notices(id)[cara.id];
+    expect(n.length).toBe(1);
+    expect(n[0].content).toBe("参与人甲 更新了「pn-整表」:\n· 改为 完成\n· 把检查项「写测试」改为「写更多测试」\n· 添加了检查项「回归」\n· 删除了检查项「发版」");
+  });
+
+  test("60 s 内连续勾选并成一条(未读时改写正文);同一项先勾再取消只留最后一次", async () => {
+    const id = await card("pn-合并");
+    for (const [item, done] of [["i1", true], ["i2", true], ["i1", false]] as const) {
+      expect((await send(pat.token, "PATCH", `/api/requirements/${id}/checklist/${item}?network_id=${NET}`, { done })).status).toBe(200);
+    }
+    const n = notices(id);
+    for (const uid of [owen.id, cara.id, pia.id]) {
+      expect(n[uid].length).toBe(1);
+      expect(n[uid][0].content).toBe("参与人甲 更新了「pn-合并」:\n· 勾选了检查项「发版」\n· 取消勾选了检查项「写测试」");
+    }
+  });
+
+  test("收件人读过之后再改 → 另发一条;别人那条仍在合并", async () => {
+    const id = await card("pn-已读");
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}/checklist/i1?network_id=${NET}`, { done: true })).status).toBe(200);
+    db.run("UPDATE user_inbox SET acked = 1 WHERE user_id = ?1 AND message_id = ?2", [owen.id, notices(id)[owen.id][0].message_id]);
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}/checklist/i2?network_id=${NET}`, { done: true })).status).toBe(200);
+    const n = notices(id);
+    expect(n[owen.id].length).toBe(2);
+    expect(n[owen.id][1].content).toBe("参与人甲 在「pn-已读」勾选了检查项「发版」");
+    expect(n[cara.id].length).toBe(1);
+  });
+
+  test("过了合并窗口 → 另发一条", async () => {
+    const id = await card("pn-窗口");
+    const row = (col: string, ck: boolean) => ({
+      requirement_id: id, network_id: NET, seq: null, title: "pn-窗口", column_name: col,
+      checklist_json: JSON.stringify([{ id: "i1", text: "写测试", done: ck }]),
+      owner_json: JSON.stringify(userRef(owen.id)), participants_json: JSON.stringify([userRef(pat.id)]),
+      created_by: null, created_by_json: JSON.stringify(userRef(cara.id)),
+    });
+    const t0 = Date.now();
+    expect(notify.notifyParticipantChange({ before: row("pool", false), after: row("pool", true), actorUserId: pat.id, now: t0 }).sort()).toEqual([owen.id, cara.id].sort());
+    notify.notifyParticipantChange({ before: row("pool", true), after: row("doing", true), actorUserId: pat.id, now: t0 + notify.COALESCE_WINDOW_MS - 1 });
+    expect(notices(id)[owen.id].length).toBe(1);
+    notify.notifyParticipantChange({ before: row("doing", true), after: row("done", true), actorUserId: pat.id, now: t0 + notify.COALESCE_WINDOW_MS + 1 });
+    expect(notices(id)[owen.id].length).toBe(2);
+  });
+
+  test("推送:收件人的用户流收到 desktop_message(kind=human_dm,发信人 = 参与人)", async () => {
+    const id = await card("pn-推送");
+    const ctrl = new AbortController();
+    const res = await fetch(`${BASE}/events/users/me?network_id=${NET}`, { headers: { Authorization: `Bearer ${owen.token}` }, signal: ctrl.signal });
+    expect(res.status).toBe(200);
+    const events: any[] = [];
+    const reader = res.body!.getReader();
+    const dec = new TextDecoder();
+    let buf = "";
+    void (async () => {
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value);
+          let i: number;
+          while ((i = buf.indexOf("\n\n")) >= 0) {
+            const frame = buf.slice(0, i); buf = buf.slice(i + 2);
+            for (const line of frame.split("\n")) if (line.startsWith("data: ")) { try { events.push(JSON.parse(line.slice(6))); } catch {} }
+          }
+        }
+      } catch {}
+    })();
+    const until = async (cond: () => boolean) => { for (let k = 0; k < 150 && !cond(); k++) await new Promise(r => setTimeout(r, 20)); };
+    await until(() => events.some(e => e.type === "connected"));
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
+    await until(() => events.some(e => e.type === "desktop_message"));
+    ctrl.abort();
+    const ev = events.find(e => e.type === "desktop_message");
+    expect(ev).toMatchObject({ kind: "human_dm", from: pat.username, from_user_id: pat.id, title: "任务更新", message: "参与人甲 把「pn-推送」改为 进行中" });
+    expect(ev.meta.task_notice.requirement_id).toBe(id);
+  });
+
+  test("MCP 与 REST 一致:requirements_update 改状态能过并通知,改标题被拒", async () => {
+    const id = await card("pn-mcp");
+    const ok = await mcp(pat.token, "requirements_update", { id, network_id: NET, column: "doing" });
+    expect(ok.ok).toBe(true);
+    expect(notices(id)[owen.id][0].content).toBe("参与人甲 把「pn-mcp」改为 进行中");
+    expect(notices(id)[owen.id][0].from_session).toBe(pat.username);
+    const no = await mcp(pat.token, "requirements_update", { id, network_id: NET, name: "改名" });
+    expect(no).toMatchObject({ ok: false, error: "task_read_only", field: "name", status: 403 });
+    const tog = await mcp(pat.token, "requirements_checklist_toggle", { id, network_id: NET, item_id: "i2", done: true });
+    expect(tog.ok).toBe(true);
+  });
+
+  test("viewer_can:参与人带 edit_fields;负责人不带", async () => {
+    const id = await card("pn-权限");
+    const mine = await send(pat.token, "GET", `/api/requirements/${id}?network_id=${NET}`);
+    expect(mine.body.requirement.viewer_can).toEqual({ edit: false, delete: false, edit_fields: ["column", "checklist"] });
+  });
+});
+
+describe("参与人不能改的", () => {
+  test("标题 / 描述 / 负责人 / 负责 Agent / 参与人 / 项目 / 优先级 / 日期 / 标签:403 task_read_only + field;卡不变、不通知", async () => {
+    const id = await card("pn-拒绝");
+    const before = (await send(cara.token, "GET", `/api/requirements/${id}?network_id=${NET}`)).body.requirement;
+    const cases: Array<[string, unknown]> = [
+      ["name", "改名"], ["description", "x"], ["owner", userRef(pat.id)], ["agent_owner", null], ["participants", [userRef(pat.id)]],
+      ["project_id", PROJ], ["priority", "high"], ["due", "2026-12-31"], ["start", "2026-12-01"], ["tags", ["t"]], ["archived", true], ["parent_id", null],
+    ];
+    for (const [field, value] of cases) {
+      const r = await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { [field]: value });
+      expect(r.status).toBe(403);
+      expect(r.body.ok).toBe(false);
+      expect(r.body.error).toBe("task_read_only");
+      expect(r.body.field).toBe(field);
+      expect(typeof r.body.message).toBe("string");
+    }
+    // 混着能改的字段一起发:整条拒绝,状态也不动。
+    const mixed = await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing", name: "改名" });
+    expect(mixed.status).toBe(403);
+    expect(mixed.body.field).toBe("name");
+    const after = (await send(cara.token, "GET", `/api/requirements/${id}?network_id=${NET}`)).body.requirement;
+    expect(after).toEqual(before);
+    expect(notices(id)).toEqual({});
+  });
+
+  test("负责人 / 创建者自己改:不通知;删除仍不行", async () => {
+    const id = await card("pn-负责人");
+    expect((await send(owen.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
+    expect((await send(cara.token, "PATCH", `/api/requirements/${id}/checklist/i1?network_id=${NET}`, { done: true })).status).toBe(200);
+    expect(notices(id)).toEqual({});
+    expect((await send(pat.token, "DELETE", `/api/requirements/${id}?network_id=${NET}`)).status).toBe(403);
+  });
+
+  test("负责人同时是参与人:改了也不通知", async () => {
+    const id = await card("pn-兼任", { owner: userRef(pat.id), participants: [userRef(pat.id), userRef(pia.id)] });
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
+    expect(notices(id)).toEqual({});
+  });
+
+  test("只看相关任务的无关成员:看不见、改不了(与不存在的卡逐字节相同),也收不到通知", async () => {
+    const id = await card("pn-无关");
+    const list = await send(sam.token, "GET", `/api/requirements?network_id=${NET}`);
+    expect((list.body.requirements as any[]).some(x => x.id === id)).toBe(false);
+    const hidden = await send(sam.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" });
+    const ghost = await send(sam.token, "PATCH", `/api/requirements/req_does_not_exist?network_id=${NET}`, { column: "doing" });
+    expect(hidden.status).toBe(404);
+    expect(hidden.text).toBe(ghost.text);
+    const hiddenCk = await send(sam.token, "PATCH", `/api/requirements/${id}/checklist/i1?network_id=${NET}`, { done: true });
+    expect(hiddenCk.status).toBe(404);
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
+    expect(notices(id)[sam.id]).toBeUndefined();
+  });
+});
+
+describe("收件人(纯函数)", () => {
+  test("只要人、去重、去掉操作者;旧卡没有 created_by_json 时用 created_by", () => {
+    const base = {
+      requirement_id: "r", network_id: NET, seq: 1, title: "t", column_name: "pool", checklist_json: null,
+      owner_json: JSON.stringify(userRef("u-owner")),
+      participants_json: JSON.stringify([userRef("u-actor"), userRef("u-owner"), { kind: "node", id: "n-1" }, userRef("u-other")]),
+      created_by: null, created_by_json: JSON.stringify({ kind: "node", id: "n-2" }),
+    };
+    expect(notify.noticeRecipients(base, "u-actor").sort()).toEqual(["u-other", "u-owner"]);
+    expect(notify.noticeRecipients({ ...base, created_by_json: null, created_by: "u-legacy" }, "u-actor").sort()).toEqual(["u-legacy", "u-other", "u-owner"]);
+  });
+});

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", "交互"]);
+  });
+});