@sleep2agi/commhub-server 0.9.0-preview.8 → 0.9.0-preview.80

package/src/requirements-migrate.ts

@@ -0,0 +1,225 @@
+// 需求卡的启动迁移。requirements.ts 载入时调用一次(列由 db.ts 的加列循环加上)。
+import type { DbAdapter } from "./db-adapter";
+
+/**
+ * 负责人 = 人类(owner, kind user);负责 Agent = 节点(agent_owner, kind node)。
+ * 之前 owner 可以是节点:这些卡把节点挪到 agent_owner、owner 置空。只动 agent_owner 还空着的行,
+ * 所以重复执行不会再改任何东西;不删行,不碰别的列。在 JS 里判 kind(不依赖 SQLite 的 json_extract)。
+ */
+export function migrateRequirementAgentOwners(database: DbAdapter): { moved: number } {
+  const rows = database.all<{ requirement_id: string; owner_json: string | null }>(
+    "SELECT requirement_id, owner_json FROM requirements WHERE owner_json IS NOT NULL AND agent_owner_json IS NULL",
+  );
+  let moved = 0;
+  for (const row of rows) {
+    let owner: { kind?: unknown; id?: unknown } | null = null;
+    try { owner = JSON.parse(row.owner_json || "null"); } catch { continue; }
+    if (!owner || owner.kind !== "node" || typeof owner.id !== "string" || !owner.id) continue;
+    database.run(
+      "UPDATE requirements SET agent_owner_json = ?1, owner_json = NULL WHERE requirement_id = ?2 AND agent_owner_json IS NULL",
+      [JSON.stringify({ kind: "node", id: owner.id }), row.requirement_id],
+    );
+    moved += 1;
+  }
+  return { moved };
+}
+
+/**
+ * 项目表(需求卡的「项目」)。只建表、建索引,不塞任何项目 —— 军团项目 / TMAI 由 owner 在界面里建。
+ * CREATE ... IF NOT EXISTS:重复执行无副作用。放在这里而不是 db.ts,db.ts 的行号被文档钉着。
+ */
+export function ensureRequirementProjects(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_projects (
+      project_id  TEXT PRIMARY KEY,
+      network_id  TEXT NOT NULL,
+      name        TEXT NOT NULL,
+      color       TEXT NOT NULL,
+      sort        INTEGER NOT NULL DEFAULT 0,
+      archived    INTEGER NOT NULL DEFAULT 0,
+      created_at  TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_requirement_projects_network ON requirement_projects(network_id, sort);
+  `);
+}
+
+/**
+ * 标签颜色(可选)。标签本身仍只是卡片 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)
+    );
+  `);
+}
+
+/**
+ * 删掉的卡留一条墓碑,给 GET /api/requirements?changes=1 报「这些 id 没了」(按 updated_since 增量同步的客户端
+ * 否则永远不知道一张卡被删了)。连同判断可见性要用的列一起存:受限成员只收到他本来看得见的卡的删除。
+ * 保留 30 天(requirements.ts TOMBSTONE_RETENTION_MS,写入时顺手清)。IF NOT EXISTS:重复执行无副作用。
+ */
+export function ensureRequirementTombstones(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_tombstones (
+      requirement_id    TEXT PRIMARY KEY,
+      network_id        TEXT NOT NULL,
+      deleted_at        TEXT NOT NULL,
+      project_id        TEXT,
+      owner_json        TEXT,
+      participants_json TEXT,
+      created_by        TEXT,
+      created_by_json   TEXT
+    );
+  `);
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_tombstones_network ON requirement_tombstones(network_id, deleted_at)");
+}
+
+/** 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");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirements_network_updated ON requirements(network_id, updated_at)");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirements_parent ON requirements(parent_id) WHERE parent_id IS NOT NULL");
+}
+
+/**
+ * 优先级加 lowest(P3 极低)。旧库建表时带 CHECK(priority IN ('high', 'normal', 'low')),SQLite 不能就地改
+ * CHECK,只能重建一次:拿 sqlite_master 里的原建表语句(含历次加的列)只换掉那个 CHECK,整表拷过去,
+ * 再按原样重建这张表的索引。已经放开的库什么都不做。存量值不改。
+ */
+const OLD_PRIORITY_CHECK = /CHECK\s*\(\s*priority\s+IN\s*\(\s*'high'\s*,\s*'normal'\s*,\s*'low'\s*\)\s*\)/i;
+export const PRIORITY_CHECK = "CHECK(priority IN ('high', 'normal', 'low', 'lowest'))";
+export function migrateRequirementPriorityCheck(database: DbAdapter): { rebuilt: boolean } {
+  if (database.dialect === "postgres") {
+    try {
+      database.exec("ALTER TABLE requirements DROP CONSTRAINT IF EXISTS requirements_priority_check");
+      database.exec(`ALTER TABLE requirements ADD CONSTRAINT requirements_priority_check ${PRIORITY_CHECK}`);
+    } catch {}
+    return { rebuilt: false };
+  }
+  const table = database.get<{ sql: string }>("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'requirements'");
+  if (!table?.sql || !OLD_PRIORITY_CHECK.test(table.sql)) return { rebuilt: false };
+  const indexes = database.all<{ sql: string }>("SELECT sql FROM sqlite_master WHERE type = 'index' AND tbl_name = 'requirements' AND sql IS NOT NULL");
+  const createSql = table.sql
+    .replace(/^CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?requirements["`]?/i, "CREATE TABLE requirements_migrated")
+    .replace(OLD_PRIORITY_CHECK, PRIORITY_CHECK);
+  database.transaction(() => {
+    database.exec("DROP TABLE IF EXISTS requirements_migrated");
+    database.exec(createSql);
+    database.exec("INSERT INTO requirements_migrated SELECT * FROM requirements");
+    database.exec("DROP TABLE requirements");
+    database.exec("ALTER TABLE requirements_migrated RENAME TO requirements");
+    for (const index of indexes) database.exec(index.sql);
+  });
+  return { rebuilt: true };
+}
+
+/**
+ * 任务短号 seq:每个网络自己的 #1、#2…,界面显示和按 #N 查都用它。主键 requirement_id 不变。
+ * - 加可空列 seq;没有号的旧行按 created_at(再按 requirement_id)补号,接在该网络已有的最大号后面。
+ * - requirement_seq_counters 记每个网络发到过的最大号:删掉 / 归档的卡,号也不回收。
+ * - (network_id, seq) 唯一。重复执行只补还没号的行(回滚到旧 Hub 期间新建的卡)。
+ */
+export function ensureRequirementSeq(database: DbAdapter): { backfilled: number } {
+  try { database.exec("ALTER TABLE requirements ADD COLUMN seq INTEGER"); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
+  database.exec("CREATE TABLE IF NOT EXISTS requirement_seq_counters (network_id TEXT PRIMARY KEY, last_seq INTEGER NOT NULL DEFAULT 0)");
+  const pending = database.all<{ requirement_id: string; network_id: string; created_at: string | null }>(
+    "SELECT requirement_id, network_id, created_at FROM requirements WHERE seq IS NULL",
+  );
+  if (pending.length) {
+    // datetime('now') 的旧默认值「YYYY-MM-DD HH:MM:SS」是 UTC,和 ISO 混在一起时按字符串排会错位,换成毫秒再排。
+    const at = (v: string | null) => {
+      const s = v ?? "";
+      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) ? ms : 0;
+    };
+    pending.sort((a, b) => a.network_id.localeCompare(b.network_id) || at(a.created_at) - at(b.created_at) || (a.requirement_id < b.requirement_id ? -1 : a.requirement_id > b.requirement_id ? 1 : 0));
+    database.transaction(() => {
+      const next = new Map<string, number>();
+      for (const row of pending) {
+        if (!next.has(row.network_id)) {
+          const max = database.get<{ m: number | null }>("SELECT MAX(seq) AS m FROM requirements WHERE network_id = ?1", row.network_id)?.m ?? 0;
+          const counter = database.get<{ last_seq: number }>("SELECT last_seq FROM requirement_seq_counters WHERE network_id = ?1", row.network_id)?.last_seq ?? 0;
+          next.set(row.network_id, Math.max(Number(max), Number(counter)));
+        }
+        const seq = next.get(row.network_id)! + 1;
+        next.set(row.network_id, seq);
+        database.run("UPDATE requirements SET seq = ?1 WHERE requirement_id = ?2 AND seq IS NULL", [seq, row.requirement_id]);
+      }
+    });
+  }
+  // 计数器不低于库里的最大号(补号之后、或计数器表是新建的)。
+  for (const row of database.all<{ network_id: string; m: number }>("SELECT network_id, MAX(seq) AS m FROM requirements WHERE seq IS NOT NULL GROUP BY network_id")) {
+    database.run(
+      `INSERT INTO requirement_seq_counters (network_id, last_seq) VALUES (?1, ?2)
+       ON CONFLICT(network_id) DO UPDATE SET last_seq = CASE WHEN excluded.last_seq > requirement_seq_counters.last_seq THEN excluded.last_seq ELSE requirement_seq_counters.last_seq END`,
+      [row.network_id, Number(row.m)],
+    );
+  }
+  database.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_network_seq ON requirements(network_id, seq) WHERE seq IS NOT NULL");
+  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) 唯一索引兜底。
+ */
+export function nextRequirementSeq(database: DbAdapter, networkId: string): number {
+  const row = database.get<{ last_seq: number }>(
+    `INSERT INTO requirement_seq_counters (network_id, last_seq)
+     VALUES (?1, COALESCE((SELECT MAX(seq) FROM requirements WHERE network_id = ?1), 0) + 1)
+     ON CONFLICT(network_id) DO UPDATE SET last_seq = requirement_seq_counters.last_seq + 1
+     RETURNING last_seq`,
+    networkId,
+  );
+  return Number(row!.last_seq);
+}

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

@@ -0,0 +1,114 @@
+// GET /api/requirements/people 的 display_name 字段 —— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+// test2123 在真实 PostgreSQL 上原样再跑一遍(COMMHUB_TEST_PG_URL)。
+//
+// name 保持原样:成员 = display_name,没设回落到用户名;节点 = display_name → alias → node_name(旧 app 只读它)。
+// display_name 另给一份,没设就是 "" —— 分享图等对外场景据此不把 admin 之类的账号名印出去。
+// 成员的 display_name 等于用户名也返回 "":register() 没给显示名时存的就是 username。
+
+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-req-people-"));
+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 = "ReqPeoplePassw0rd!x";
+
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let owner = { token: "", id: "", username: "" };
+let named = { id: "" };
+let plain = { id: "", username: "" };
+let same = { id: "", username: "" };
+
+async function people(token: string) {
+  const res = await fetch(`${BASE}/api/requirements/people?network_id=${NET}`, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: res.status, body: await res.json() as any };
+}
+
+beforeAll(async () => {
+  const { db } = await import("./db.js");
+  const { addNetworkMember, register } = await import("./auth.js");
+  const stamp = Date.now();
+  const o = register(`rp_owner_${stamp}`, PW, undefined, "");
+  expect(o.ok).toBe(true);
+  owner = { token: o.token!, id: o.user!.user_id, username: o.user!.username };
+  NET = o.network_id!;
+  const m = register(`rp_member_${stamp}`, PW, undefined, "");
+  expect(m.ok).toBe(true);
+  named = { id: m.user!.user_id };
+  addNetworkMember(NET, named.id, "member", owner.id, { taskAccess: "all" });
+  // owner:没有显示名(= 只有用户名);member:有显示名。
+  db.run("UPDATE users SET display_name = NULL WHERE user_id = ?1", [owner.id]);
+  db.run("UPDATE users SET display_name = ?1 WHERE user_id = ?2", ["Placeholder Person", named.id]);
+  // plain:注册时没给显示名 —— register() 存的是 display_name = username,不改。
+  const pl = register(`rp_plain_${stamp}`, PW);
+  expect(pl.ok).toBe(true);
+  plain = { id: pl.user!.user_id, username: pl.user!.username };
+  addNetworkMember(NET, plain.id, "member", owner.id, { taskAccess: "all" });
+  // same:显示名被显式设成和用户名一模一样。
+  const sm = register(`rp_same_${stamp}`, PW, undefined, "Placeholder Other");
+  expect(sm.ok).toBe(true);
+  same = { id: sm.user!.user_id, username: sm.user!.username };
+  addNetworkMember(NET, same.id, "member", owner.id, { taskAccess: "all" });
+  db.run("UPDATE users SET display_name = username WHERE user_id = ?1", [same.id]);
+  db.run("INSERT INTO nodes(node_id,node_name,alias,display_name,network_id) VALUES (?1,?2,?3,?4,?5)", ["rp-node-alias", "rp-node-name", "placeholder-alias", "", NET]);
+  db.run("INSERT INTO nodes(node_id,node_name,alias,display_name,network_id) VALUES (?1,?2,?3,?4,?5)", ["rp-node-named", "rp-node-name-2", "placeholder-alias-2", "Placeholder Agent", NET]);
+  db.run("INSERT INTO nodes(node_id,node_name,network_id) VALUES (?1,?2,?3)", ["rp-node-bare", "rp-node-bare-name", NET]);
+  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}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/requirements/people display_name", () => {
+  test("display_name is its own field, empty when unset; name keeps the username / alias fallback", async () => {
+    const r = await people(owner.token);
+    expect(r.status).toBe(200);
+    const find = (kind: string, id: string) => r.body.people.find((p: any) => p.kind === kind && p.id === id);
+    expect(find("user", owner.id)).toMatchObject({ name: owner.username, display_name: "", networkId: NET });
+    expect(find("user", named.id)).toMatchObject({ name: "Placeholder Person", display_name: "Placeholder Person" });
+    expect(find("node", "rp-node-alias")).toMatchObject({ name: "placeholder-alias", display_name: "" });
+    expect(find("node", "rp-node-named")).toMatchObject({ name: "Placeholder Agent", display_name: "Placeholder Agent" });
+    expect(find("node", "rp-node-bare")).toMatchObject({ name: "rp-node-bare-name", display_name: "" });
+    expect(r.body.people.every((p: any) => typeof p.display_name === "string")).toBe(true);
+  });
+
+  test("a member whose display_name is just the username gets display_name \"\" (name still the username)", async () => {
+    const { db } = await import("./db.js");
+    // 前提是真的:register() 没给显示名时存的就是用户名。
+    expect(db.get<{ display_name: string }>("SELECT display_name FROM users WHERE user_id = ?1", plain.id)!.display_name).toBe(plain.username);
+    const r = await people(owner.token);
+    const find = (id: string) => r.body.people.find((p: any) => p.kind === "user" && p.id === id);
+    expect(find(plain.id)).toMatchObject({ name: plain.username, display_name: "" });
+    expect(find(same.id)).toMatchObject({ name: same.username, display_name: "" });
+    // 显示名只是「包含」用户名、不等于它:照常返回。
+    db.run("UPDATE users SET display_name = ?1 WHERE user_id = ?2", [`${same.username} (placeholder)`, same.id]);
+    const r2 = await people(owner.token);
+    expect(r2.body.people.find((p: any) => p.kind === "user" && p.id === same.id)).toMatchObject({ display_name: `${same.username} (placeholder)` });
+    db.run("UPDATE users SET display_name = username WHERE user_id = ?1", [same.id]);
+  });
+
+  test("sort order is still by name, then id", async () => {
+    const r = await people(owner.token);
+    const users = r.body.people.filter((p: any) => p.kind === "user");
+    const sorted = [...users].sort((a: any, b: any) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.id < b.id ? -1 : 1));
+    expect(users.map((p: any) => p.id)).toEqual(sorted.map((p: any) => p.id));
+  });
+
+  test("the existing fields keep their shape for old apps", async () => {
+    const r = await people(owner.token);
+    for (const p of r.body.people) {
+      expect(Object.keys(p).sort()).toEqual(["display_name", "id", "kind", "name", "networkId"]);
+      expect(typeof p.name).toBe("string");
+      expect(p.name.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/requirements-priority-lowest.test.ts

@@ -0,0 +1,114 @@
+// P0–P3 优先级:lowest(P3 极低)。生产库的 requirements 表建于旧 db.ts,带 CHECK(priority IN ('high', 'normal', 'low')),
+// 光放开校验集合写进去也会被 SQLite 拒掉。这里先用旧建表语句建库、塞行,再走真实启动路径(db.ts + server.ts),
+// 看:表重建一次、存量行 / 索引原样、lowest 在 POST / PATCH / upsert 都能写、坏值仍被拒、再启动不再重建。
+import { afterAll, beforeAll, describe, 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-priority-"));
+const file = join(dir, "hub.db");
+process.env.COMMHUB_DB = file;
+
+const legacy = new Database(file);
+legacy.exec(`
+  CREATE TABLE IF NOT EXISTS 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' CHECK(priority IN ('high', 'normal', 'low')),
+    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'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_requirements_network ON requirements(network_id, created_at DESC);
+`);
+legacy.exec("ALTER TABLE requirements ADD COLUMN tags_json TEXT NOT NULL DEFAULT '[]'");
+legacy.exec("ALTER TABLE requirements ADD COLUMN description TEXT");
+const seeded = [["r_high", "high"], ["r_normal", "normal"], ["r_low", "low"]] as const;
+for (const [id, p] of seeded) {
+  legacy.run("INSERT INTO requirements (requirement_id, network_id, title, priority, client_id, description, tags_json) VALUES (?1, 'net_legacy', ?2, ?3, ?4, ?5, '[\"旧\"]')", [id, `卡 ${id}`, p, `c_${id}`, `desc ${id}`]);
+}
+// 旧库确实拒 lowest:这就是光改 PRIORITIES 不够的原因
+expect(() => legacy.run("INSERT INTO requirements (requirement_id, network_id, title, priority) VALUES ('x', 'n', 't', 'lowest')")).toThrow(/CHECK/);
+legacy.close();
+
+let base = "";
+let token = "";
+let server: { port: number; stop?: (force?: boolean) => void };
+let db: any;
+
+async function api(path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+  return { status: res.status, body: await res.json() as any };
+}
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const owner = register(`prio_owner_${Date.now()}`, "PriorityOwner123!", undefined, "seed");
+  token = owner.token!;
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("P3 lowest priority", () => {
+  test("startup rebuilds the legacy CHECK once and keeps every row and index", async () => {
+    const sql = db.get("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'requirements'").sql as string;
+    expect(sql).toContain("'lowest'");
+    expect(sql).toContain("CHECK(column_name IN ('pool', 'doing', 'done'))");
+    const rows = db.all("SELECT requirement_id, network_id, title, priority, client_id, description, tags_json FROM requirements WHERE network_id = 'net_legacy' ORDER BY requirement_id") as any[];
+    expect(rows.map(r => [r.requirement_id, r.priority])).toEqual([["r_high", "high"], ["r_low", "low"], ["r_normal", "normal"]]);
+    for (const r of rows) {
+      expect(r.title).toBe(`卡 ${r.requirement_id}`);
+      expect(r.client_id).toBe(`c_${r.requirement_id}`);
+      expect(r.description).toBe(`desc ${r.requirement_id}`);
+      expect(r.tags_json).toBe('["旧"]');
+    }
+    const indexes = (db.all("PRAGMA index_list(requirements)") as { name: string; unique: number }[]).map(i => i.name);
+    for (const name of ["idx_requirements_network", "idx_requirements_client", "idx_requirements_external_ref", "idx_requirements_network_updated", "idx_requirements_parent"]) expect(indexes).toContain(name);
+    expect(db.get("SELECT name FROM sqlite_master WHERE name = 'requirements_migrated'")).toBeNull();
+    // 坏值仍被数据库拒
+    expect(() => db.run("INSERT INTO requirements (requirement_id, network_id, title, priority) VALUES ('bad', 'n', 't', 'urgent')")).toThrow(/CHECK/);
+    // 下次启动:已经放开,不再重建
+    const { migrateRequirementPriorityCheck } = await import("./requirements-migrate.js");
+    expect(migrateRequirementPriorityCheck(db).rebuilt).toBe(false);
+  });
+
+  test("lowest is accepted on create, PATCH and upsert; unknown values stay 400", async () => {
+    const created = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "极低的活", priority: "lowest" }) });
+    expect(created.status).toBe(201);
+    expect(created.body.requirement.priority).toBe("lowest");
+    const id = created.body.requirement.id;
+    const patched = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ priority: "low" }) });
+    expect(patched.body.requirement.priority).toBe("low");
+    const back = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ priority: "lowest" }) });
+    expect(back.status).toBe(200);
+    expect(back.body.requirement.priority).toBe("lowest");
+    const up = await api("/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "同步来的", external_ref: "github:t/p#1", priority: "lowest" }) });
+    expect(up.status).toBe(201);
+    expect(up.body.requirement.priority).toBe("lowest");
+    const upAgain = await api("/api/requirements/upsert", { method: "POST", body: JSON.stringify({ external_ref: "github:t/p#1", priority: "high" }) });
+    expect(upAgain.body.requirement.priority).toBe("high");
+    for (const [path, method] of [["/api/requirements", "POST"], [`/api/requirements/${id}`, "PATCH"]] as const) {
+      const bad = await api(path, { method, body: JSON.stringify({ name: "x", priority: "urgent" }) });
+      expect(bad.status).toBe(400);
+      expect(bad.body.error).toBe("invalid_priority");
+    }
+    const listed = await api("/api/requirements");
+    expect(listed.body.capabilities).toContain("priority_lowest");
+    expect(listed.body.requirements.find((r: any) => r.id === id).priority).toBe("lowest");
+  });
+});

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

@@ -0,0 +1,182 @@
+// GET /api/requirements 的 q= 服务端搜索与 limit / cursor 分页(requirements-search.ts)。一次性 hub:临时 DB、端口 0。
+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-req-search-"));
+process.env.COMMHUB_DB = join(dir, "hub.db");
+
+let server: { port: number; stop?: (force?: boolean) => void };
+let base = "";
+let token = "";
+let otherToken = "";
+let net = "";
+let db: any;
+
+async function api(tok: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${tok}`, "Content-Type": "application/json", ...(init?.headers || {}) } });
+  return { status: res.status, body: await res.json() as any };
+}
+const list = (query: string, tok = token) => api(tok, `/api/requirements?network_id=${net}${query ? `&${query}` : ""}`);
+const ids = async (query: string, tok = token) => {
+  const r = await list(query, tok);
+  expect(r.status).toBe(200);
+  return (r.body.requirements as any[]).map(x => x.name);
+};
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const owner = register(`search_owner_${Date.now()}`, "SearchOwner123!", undefined, "seed");
+  token = owner.token!;
+  net = owner.network_id!;
+  const other = register(`search_other_${Date.now()}`, "SearchOther123!", undefined, "seed");
+  otherToken = other.token!;
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+  db.run("INSERT INTO nodes(node_id,node_name,alias,display_name,network_id) VALUES (?1,?2,?2,?3,?4)", ["n_search_a", "portal-cow", "示例-门户牛", net]);
+  const project = await api(token, "/api/requirements/projects", { method: "POST", body: JSON.stringify({ name: "示例门户项目", network_id: net }) });
+  const pid = project.body.project.id;
+  const mk = (name: string, extra: Record<string, unknown> = {}) => api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name, network_id: net, ...extra }) });
+  await mk("企业组织树权限设置");
+  await mk("Portal Token 管理 | 估算成本卡布局", { agent_owner: { kind: "node", id: "n_search_a" }, tags: ["前端"] });
+  await mk("Space 网络策略 | 历史 receipt 误报", { description: "看 ![截图](/api/files/abc123) 和 [链接文字](https://example.com/x),重启导致 binding 丢失" });
+  await mk("子项目的卡", { project_id: pid });
+  const arch = await mk("已归档的组织树旧方案");
+  await api(token, `/api/requirements/${arch.body.requirement.id}`, { method: "PATCH", body: JSON.stringify({ archived: true }) });
+  await api(otherToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "别的网络的组织树" }) });
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("q= server-side search (same semantics as the app's task search)", () => {
+  test("title substring, CJK, case-insensitive, full-width input", async () => {
+    expect(await ids("q=" + encodeURIComponent("组织树"))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("q=portal")).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+    expect(await ids("q=" + encodeURIComponent("ＰＯＲＴＡＬ"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+  });
+  test("agent owner display name, tags, project name, description text (not URLs)", async () => {
+    expect(await ids("q=" + encodeURIComponent("门户牛"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+    expect(await ids("q=" + encodeURIComponent("前端"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+    expect(await ids("q=" + encodeURIComponent("示例门户项目"))).toEqual(["子项目的卡"]);
+    expect(await ids("q=binding")).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    expect(await ids("q=" + encodeURIComponent("链接文字"))).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    expect(await ids("q=abc123")).toEqual([]);
+    expect(await ids("q=example.com")).toEqual([]);
+  });
+  test("space-separated terms are ANDed across fields", async () => {
+    expect(await ids("q=" + encodeURIComponent("成本 门户牛"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+    expect(await ids("q=" + encodeURIComponent("成本 receipt"))).toEqual([]);
+  });
+  test("archived only with archived=true / include_archived=1; other networks never", async () => {
+    expect(await ids("q=" + encodeURIComponent("组织树"))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("archived=true&q=" + encodeURIComponent("组织树"))).toEqual(["已归档的组织树旧方案"]);
+    expect((await ids("include_archived=1&q=" + encodeURIComponent("组织树"))).sort()).toEqual(["企业组织树权限设置", "已归档的组织树旧方案"].sort());
+  });
+  test("combines with the other filters", async () => {
+    expect(await ids("status=done&q=portal")).toEqual([]);
+    expect(await ids("agent_owner=node:n_search_a&q=" + encodeURIComponent("成本"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+  });
+  test("empty / whitespace q = no search; too long q = 400", async () => {
+    expect((await ids("q=")).length).toBe(4);
+    expect((await ids("q=%20%20")).length).toBe(4);
+    const r = await list("q=" + "x".repeat(201));
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("invalid_q");
+  });
+});
+
+describe("q= also matches task ids: #N / N on seq (#2139), full id and 8+ char prefix", () => {
+  const idOf = async (name: string) => (await list("limit=1000&include_archived=1")).body.requirements.find((r: any) => r.name === name).id as string;
+  test("full id and id prefix (with or without req_), not shorter prefixes", async () => {
+    const id = await idOf("企业组织树权限设置");
+    const bare = id.replace(/^req_/, "");
+    expect(await ids("q=" + encodeURIComponent(id))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("q=" + encodeURIComponent(id.toUpperCase()))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("q=" + encodeURIComponent(bare.slice(0, 10)))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("q=" + encodeURIComponent(`req_${bare.slice(0, 9)}`))).toEqual(["企业组织树权限设置"]);
+    // 7 位以下的前缀不算 ID(否则输入几个字母就搜出一堆)
+    expect(await ids("q=" + encodeURIComponent(`req_${bare.slice(0, 5)}`))).toEqual([]);
+  });
+  test("#N / full-width ＃Ｎ / padded #N match the task's seq (#2139); #N plus text is plain text; filters still apply", async () => {
+    const target = await idOf("Space 网络策略 | 历史 receipt 误报");
+    const n = db.get("SELECT seq FROM requirements WHERE requirement_id = ?1", target).seq as number;
+    expect(typeof n).toBe("number");
+    expect(await ids(`q=%23${n}`)).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    const fullWidth = `＃${String(n).replace(/\d/g, d => String.fromCharCode(0xff10 + Number(d)))}`;
+    expect(await ids("q=" + encodeURIComponent(fullWidth))).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    expect(await ids("q=" + encodeURIComponent(` #${n} `))).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    // 「#N receipt」整句不是 ID,只按文字「且」:没有卡同时含「#N」和「receipt」
+    expect(await ids("q=" + encodeURIComponent(`#${n} receipt`))).toEqual([]);
+    // ID 命中也受筛选管
+    expect(await ids(`status=done&q=%23${n}`)).toEqual([]);
+  });
+});
+
+describe("paging: limit / cursor / has_more / next_cursor", () => {
+  test("no params: legacy shape plus has_more=false, next_cursor=null, capabilities advertise search + paging", async () => {
+    const r = await list("");
+    expect(r.body.requirements.length).toBe(4);
+    expect(r.body.has_more).toBe(false);
+    expect(r.body.next_cursor).toBeNull();
+    expect(r.body.capabilities).toContain("search");
+    expect(r.body.capabilities).toContain("paging");
+  });
+  test("walking pages returns every row exactly once, newest first, including same-timestamp ties", async () => {
+    // 25 张,其中 10 张同一个 created_at(翻页边界落在并列上也不能漏 / 重)
+    const same = new Date(Date.now() + 60_000).toISOString();
+    for (let i = 0; i < 25; i++) {
+      const c = await api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name: `页-${String(i).padStart(2, "0")}`, network_id: net }) });
+      if (i >= 10 && i < 20) db.run("UPDATE requirements SET created_at = ?1 WHERE requirement_id = ?2", [same, c.body.requirement.id]);
+    }
+    const full = await ids("limit=1000");
+    expect(full.length).toBe(29);
+    const seen: string[] = [];
+    let cursor = "";
+    let pages = 0;
+    for (;;) {
+      const r = await list(`limit=7${cursor ? `&cursor=${cursor}` : ""}`);
+      expect(r.status).toBe(200);
+      seen.push(...r.body.requirements.map((x: any) => x.name));
+      pages++;
+      if (!r.body.has_more) { expect(r.body.next_cursor).toBeNull(); break; }
+      expect(typeof r.body.next_cursor).toBe("string");
+      cursor = r.body.next_cursor;
+      expect(pages).toBeLessThan(10);
+    }
+    expect(pages).toBe(5);
+    expect(seen).toEqual(full);
+    expect(new Set(seen).size).toBe(29);
+  });
+  test("q= pages too", async () => {
+    const first = await list("limit=4&q=" + encodeURIComponent("页-"));
+    expect(first.body.requirements.length).toBe(4);
+    expect(first.body.has_more).toBe(true);
+    const rest = await list(`limit=100&q=${encodeURIComponent("页-")}&cursor=${first.body.next_cursor}`);
+    expect(rest.body.requirements.length).toBe(21);
+    expect(rest.body.has_more).toBe(false);
+  });
+  test("default limit stays 500 (legacy clients see the same cap)", async () => {
+    const { DEFAULT_LIST_LIMIT } = await import("./requirements-search.js");
+    expect(DEFAULT_LIST_LIMIT).toBe(500);
+  });
+  test("bad limit / cursor → 400", async () => {
+    for (const q of ["limit=0", "limit=1001", "limit=abc", "limit=-1", "cursor=%%%", "cursor=bm9wZQ"]) {
+      const r = await list(q);
+      expect(r.status).toBe(400);
+      expect(["invalid_limit", "invalid_cursor"]).toContain(r.body.error);
+    }
+  });
+  test("ETag still works with the new fields", async () => {
+    const first = await fetch(`${base}/api/requirements?network_id=${net}&limit=5`, { headers: { Authorization: `Bearer ${token}` } });
+    const etag = first.headers.get("etag")!;
+    await first.text();
+    const again = await fetch(`${base}/api/requirements?network_id=${net}&limit=5`, { headers: { Authorization: `Bearer ${token}`, "If-None-Match": etag } });
+    expect(again.status).toBe(304);
+  });
+});