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

package/src/requirements-search.test.ts

@@ -0,0 +1,32 @@
+// requirements-search.ts 的纯函数:任务 ID 匹配(与 App 的 task-short-id.ts matchesTaskId 同一规则)。
+import { describe, expect, test } from "bun:test";
+import { matchesTaskId, parseListQuery, taskIdQuery } from "./requirements-search.js";
+
+const row = (id: string, seq: number | null) => ({ requirement_id: id, seq });
+
+describe("matchesTaskId", () => {
+  test("#N / N match seq exactly (#7 does not hit #70)", () => {
+    expect(matchesTaskId(row("req_a", 7), "#7")).toBe(true);
+    expect(matchesTaskId(row("req_a", 7), "7")).toBe(true);
+    expect(matchesTaskId(row("req_a", 70), "#7")).toBe(false);
+    expect(matchesTaskId(row("req_a", null), "#7")).toBe(false);
+  });
+  test("full id and 8+ char prefix, with or without req_; shorter prefixes do not count", () => {
+    const id = "req_0a1b2c3d-4e5f-6789-abcd-ef0123456789";
+    expect(matchesTaskId(row(id, 1), id)).toBe(true);
+    expect(matchesTaskId(row(id, 1), "0a1b2c3d")).toBe(true);
+    expect(matchesTaskId(row(id, 1), "req_0a1b2c3d-4")).toBe(true);
+    expect(matchesTaskId(row(id, 1), "0a1b2c3")).toBe(false);
+    expect(matchesTaskId(row(id, 1), "")).toBe(false);
+  });
+  test("taskIdQuery: trim, NFKC (full-width ＃７ → #7), lowercase", () => {
+    expect(taskIdQuery(" ＃７ ")).toBe("#7");
+    expect(taskIdQuery("REQ_0A1B")).toBe("req_0a1b");
+  });
+  test("parseListQuery: idQuery only when there are terms", () => {
+    const q = (s: string) => parseListQuery(new URLSearchParams(s)) as any;
+    expect(q("q=%EF%BC%83%EF%BC%97").idQuery).toBe("#7");
+    expect(q("q=%20%20").idQuery).toBe("");
+    expect(q("").idQuery).toBe("");
+  });
+});

package/src/requirements-search.ts

@@ -0,0 +1,145 @@
+// GET /api/requirements 的服务端搜索(q=)与分页(limit / cursor)。纯函数,requirements.ts 接线。
+//
+// 为什么要:列表一直是 `ORDER BY created_at DESC LIMIT 500`,App 的任务搜索只在读到的行里搜 ——
+// 生产一个网络已经 ~400 张卡,过了 500 最老的那些就搜不到、也翻不到。
+//
+// 语义与 App 的任务搜索(agent-network-app src/task-search.ts)一致,两边搜同一个词得到同一批卡:
+//   · 字段:标题、描述(去掉 markdown 图片 / 链接的地址,链接文字保留)、负责人 / 负责 Agent / 参与人的显示名、
+//     旧 assignee 文本、项目名、标签
+//   · NFKC(全角 → 半角)+ 小写;中文按子串;空白隔开的词是「且」,每个词可以落在不同字段,但不跨字段拼
+//   · 调用者看不见的节点(受限成员)在卡片上本来就被隐去,它的名字也不参与匹配 —— 否则 q= 就成了
+//     「这张卡是不是某个没授权给我的 Agent 负责」的探测器
+//
+// 分页:按 (created_at DESC, requirement_id DESC) 排,cursor = 上一页最后一行的这两个值(不透明的 base64url)。
+// 不带 limit / cursor / q 的旧请求:同样的 500 行、同样的顺序,响应只多两个字段 has_more / next_cursor。
+
+export const DEFAULT_LIST_LIMIT = 500;
+export const MAX_LIST_LIMIT = 1000;
+export const MAX_QUERY_LENGTH = 200;
+
+const fold = (s: string): string => s.normalize("NFKC").toLocaleLowerCase();
+
+/** 搜索词:归一后按空白切开,去重、去空。 */
+export function searchTerms(q: string): string[] {
+  return [...new Set(fold(q).split(/\s+/).filter(Boolean))];
+}
+
+/** 描述是 markdown:图片 / 链接的地址不参与搜索,链接文字保留;html 标签去掉。 */
+export function descriptionText(md: string | null | undefined): string {
+  if (!md) return "";
+  return md
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, " ");
+}
+
+type Ref = { kind?: unknown; id?: unknown } | null | undefined;
+export type SearchableRow = {
+  name: string;
+  description: string;
+  assignee: string;
+  tags: readonly string[];
+  project_id: string | null;
+  owner: Ref;
+  agent_owner: Ref;
+  participants: readonly Ref[] | unknown;
+};
+export type NameMaps = {
+  /** `user:<id>` / `node:<id>` → 显示名(看不见的节点不在里面)。 */
+  people: ReadonlyMap<string, string>;
+  /** project_id → 项目名。 */
+  projects: ReadonlyMap<string, string>;
+};
+
+const refName = (ref: Ref, maps: NameMaps): string => {
+  if (!ref || typeof ref !== "object" || typeof ref.id !== "string" || (ref.kind !== "user" && ref.kind !== "node")) return "";
+  return maps.people.get(`${ref.kind}:${ref.id}`) ?? "";
+};
+
+/** 一张卡能被搜到的文字,字段之间用换行隔开(一个词不会跨两个字段拼出来)。 */
+export function searchText(row: SearchableRow, maps: NameMaps): string {
+  const participants = Array.isArray(row.participants) ? row.participants as Ref[] : [];
+  return fold([
+    row.name,
+    descriptionText(row.description),
+    refName(row.owner, maps),
+    refName(row.agent_owner, maps),
+    ...participants.map(r => refName(r, maps)),
+    row.assignee,
+    row.project_id ? maps.projects.get(row.project_id) ?? "" : "",
+    ...row.tags,
+  ].filter(Boolean).join("\n"));
+}
+
+export function matchesTerms(row: SearchableRow, terms: readonly string[], maps: NameMaps): boolean {
+  if (!terms.length) return true;
+  const hay = searchText(row, maps);
+  return terms.every(t => hay.includes(t));
+}
+
+export type Cursor = { createdAt: string; id: string };
+
+export function encodeCursor(c: Cursor): string {
+  return Buffer.from(JSON.stringify([c.createdAt, c.id]), "utf8").toString("base64url");
+}
+
+export function decodeCursor(raw: string): Cursor | null {
+  if (!raw || raw.length > 600 || !/^[A-Za-z0-9_-]+$/.test(raw)) return null;
+  try {
+    const v = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+    if (!Array.isArray(v) || v.length !== 2 || typeof v[0] !== "string" || typeof v[1] !== "string" || !v[0] || !v[1]) return null;
+    return { createdAt: v[0], id: v[1] };
+  } catch {
+    return null;
+  }
+}
+
+export type ListQuery = { limit: number; cursor: Cursor | null; terms: string[]; /** 整句当任务 ID 去对(taskIdQuery);空 = 没有搜索。 */ idQuery: string; /** #471 —— 只要带这个标签的卡(精确、区分大小写);null = 不按标签筛。 */ tag: string | null };
+
+/**
+ * 任务 ID(同 App 的 task-short-id.ts matchesTaskId):「#42」「42」精确对短号 seq;完整 id,或 8 位以上的
+ * id 前缀(带不带 req_ 都行)对主键。整句当一个 ID —— 和文字匹配是「或」,不拆成「ID 且文字」。
+ * 全角「＃４２」先 NFKC 归一(ID 本身都是 ASCII)。
+ */
+export const taskIdQuery = (q: string): string => q.trim().normalize("NFKC").toLowerCase();
+export const seqOfQuery = (idQuery: string): number | null => {
+  const m = /^#?(\d{1,15})$/.exec(idQuery);
+  return m ? Number(m[1]) : null;
+};
+export function matchesTaskId(row: { requirement_id: string; seq?: number | null }, idQuery: string): boolean {
+  if (!idQuery) return false;
+  const n = seqOfQuery(idQuery);
+  if (n !== null) return typeof row.seq === "number" && row.seq === n;
+  const id = row.requirement_id.toLowerCase();
+  if (idQuery === id) return true;
+  const bare = idQuery.replace(/^req_/, "");
+  return bare.length >= 8 && id.replace(/^req_/, "").startsWith(bare);
+}
+
+/** 解析 limit / cursor / q。不合法 → 错误码(400)。都没带 = 旧行为(500 行、第一页、不搜)。 */
+export function parseListQuery(params: URLSearchParams): ListQuery | { error: string } {
+  let limit = DEFAULT_LIST_LIMIT;
+  const rawLimit = params.get("limit");
+  if (rawLimit !== null) {
+    if (!/^\d{1,5}$/.test(rawLimit)) return { error: "invalid_limit" };
+    limit = Number(rawLimit);
+    if (limit < 1 || limit > MAX_LIST_LIMIT) return { error: "invalid_limit" };
+  }
+  let cursor: Cursor | null = null;
+  const rawCursor = params.get("cursor");
+  if (rawCursor !== null && rawCursor !== "") {
+    cursor = decodeCursor(rawCursor);
+    if (!cursor) return { error: "invalid_cursor" };
+  }
+  const q = params.get("q") ?? "";
+  if (q.length > MAX_QUERY_LENGTH) return { error: "invalid_q" };
+  const terms = searchTerms(q);
+  // #471 —— tag=:和卡片标签同一套规范(去首尾空白、1–20 个字符、不含控制字符);不带 = 旧行为。
+  const rawTag = params.get("tag");
+  let tag: string | null = null;
+  if (rawTag !== null) {
+    tag = rawTag.trim();
+    if (!tag || [...tag].length > 20 || /[\u0000-\u001f\u007f]/u.test(tag)) return { error: "invalid_tag" };
+  }
+  return { limit, cursor, terms, idQuery: terms.length ? taskIdQuery(q) : "", tag };
+}

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

@@ -0,0 +1,193 @@
+// 任务短号 seq:新建领号(并发不撞)、按网络各自编号、按 #N 查 / 改、删除和归档不回收号、MCP 工具也收 #N。
+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-seq-"));
+process.env.COMMHUB_DB = join(dir, "hub.db");
+
+let server: { port: number; stop?: (force?: boolean) => void };
+let base = "";
+let ownerToken = "", otherToken = "", nodeToken = "";
+let ownerNet = "", otherNet = "", ownerId = "", otherId = "";
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...(init?.headers || {}) } });
+  return { status: res.status, body: await res.json() as any };
+}
+const create = (token: string, body: Record<string, unknown>, query = "") => api(token, `/api/requirements${query}`, { method: "POST", body: JSON.stringify(body) });
+
+beforeAll(async () => {
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  // 第一个注册的用户是 Hub 管理员、作用域是全部网络;让它先占掉,下面两个是普通用户(各自一个网络)。
+  register(`seq_admin_${Date.now()}`, "SeqAdmin123!x", undefined, "seed");
+  const o = register(`seq_owner_${Date.now()}`, "SeqOwner123!x", undefined, "seed");
+  const x = register(`seq_other_${Date.now()}`, "SeqOther123!x", undefined, "seed");
+  ownerToken = o.token!; ownerNet = o.network_id!; ownerId = o.user!.user_id;
+  otherToken = x.token!; otherNet = x.network_id!; otherId = x.user!.user_id;
+  nodeToken = createNetworkTokenForNode(ownerId, ownerNet, "seq-node").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("requirement short numbers (#N)", () => {
+  test("capability is advertised and create returns seq", async () => {
+    const list = await api(ownerToken, "/api/requirements");
+    expect(list.body.capabilities).toContain("requirement_seq");
+    const first = await create(ownerToken, { name: "第一张" });
+    expect(first.status).toBe(201);
+    expect(first.body.requirement.seq).toBe(1);
+    expect(first.body.requirement.id).toMatch(/^req_/);
+    const got = await api(ownerToken, `/api/requirements/${first.body.requirement.id}`);
+    expect(got.body.requirement.seq).toBe(1);
+    expect((await api(ownerToken, "/api/requirements")).body.requirements[0].seq).toBe(1);
+  });
+
+  test("concurrent creates get distinct, gap-free seqs", async () => {
+    const before = (await create(ownerToken, { name: "before" })).body.requirement.seq as number;
+    const results = await Promise.all(Array.from({ length: 40 }, (_, i) => create(i % 2 ? nodeToken : ownerToken, { name: `并发 ${i}` })));
+    expect(results.every(r => r.status === 201)).toBe(true);
+    const seqs = results.map(r => r.body.requirement.seq as number).sort((a, b) => a - b);
+    expect(new Set(seqs).size).toBe(40);
+    expect(seqs).toEqual(Array.from({ length: 40 }, (_, i) => before + 1 + i));
+  });
+
+  test("seq is per network", async () => {
+    const a = await create(otherToken, { name: "别的网络第一张" });
+    expect(a.body.requirement.seq).toBe(1);
+    const b = await create(otherToken, { name: "别的网络第二张" });
+    expect(b.body.requirement.seq).toBe(2);
+    // 同一个 #1 在两个网络各指各的卡
+    expect((await api(ownerToken, "/api/requirements/%231")).body.requirement.name).toBe("第一张");
+    expect((await api(otherToken, "/api/requirements/%231")).body.requirement.name).toBe("别的网络第一张");
+    // 别的网络的号查不到对方的卡
+    expect((await api(otherToken, "/api/requirements/%2310")).status).toBe(404);
+  });
+
+  test("lookup and patch by #N; list filter ?seq=; malformed forms rejected", async () => {
+    const c = (await create(ownerToken, { name: "按号查", checklist: [{ id: "a", text: "一" }] })).body.requirement;
+    const ref = `%23${c.seq}`;
+    const got = await api(ownerToken, `/api/requirements/${ref}`);
+    expect(got.status).toBe(200);
+    expect(got.body.requirement.id).toBe(c.id);
+    const patched = await api(nodeToken, `/api/requirements/${ref}`, { method: "PATCH", body: JSON.stringify({ column: "doing" }) });
+    expect(patched.status).toBe(200);
+    expect(patched.body.requirement.column).toBe("doing");
+    expect(patched.body.requirement.seq).toBe(c.seq); // 改卡不改号
+    const ticked = await api(ownerToken, `/api/requirements/${ref}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: true }) });
+    expect(ticked.body.requirement.checklist[0].done).toBe(true);
+    const listed = await api(ownerToken, `/api/requirements?seq=${c.seq}`);
+    expect(listed.body.requirements.map((r: any) => r.id)).toEqual([c.id]);
+    expect((await api(ownerToken, "/api/requirements?seq=abc")).status).toBe(400);
+    expect((await api(ownerToken, "/api/requirements?seq=0")).status).toBe(400);
+    // 旧 id 照常;裸数字、「#」「#0」「#-1」都不是短号,按 id 查 → 404
+    expect((await api(ownerToken, `/api/requirements/${c.id}`)).body.requirement.seq).toBe(c.seq);
+    for (const bad of [String(c.seq), "%23", "%230", "%23-1", `%23${c.seq}x`]) expect((await api(ownerToken, `/api/requirements/${bad}`)).status).toBe(404);
+  });
+
+  test("deleting or archiving never frees a number", async () => {
+    const top = (await create(ownerToken, { name: "最大号" })).body.requirement;
+    expect((await api(ownerToken, `/api/requirements/%23${top.seq}`, { method: "DELETE" })).status).toBe(200);
+    expect((await api(ownerToken, `/api/requirements/%23${top.seq}`)).status).toBe(404);
+    const next = (await create(ownerToken, { name: "删之后" })).body.requirement;
+    expect(next.seq).toBe(top.seq + 1);
+    await api(ownerToken, `/api/requirements/${next.id}`, { method: "PATCH", body: JSON.stringify({ archived: true }) });
+    expect((await create(ownerToken, { name: "归档之后" })).body.requirement.seq).toBe(next.seq + 1);
+    // 归档的卡按号照样能查到
+    expect((await api(ownerToken, `/api/requirements/%23${next.seq}`)).body.requirement.archived).toBe(true);
+  });
+
+  test("a create that loses on client_id / external_ref does not burn a number", async () => {
+    const a = (await create(ownerToken, { name: "幂等", client_id: "seq-client-1" })).body.requirement;
+    const again = await create(ownerToken, { name: "幂等", client_id: "seq-client-1" });
+    expect(again.body.requirement.seq).toBe(a.seq);
+    await create(ownerToken, { name: "外部", external_ref: "github:acme/seq#1" });
+    expect((await create(ownerToken, { name: "外部", external_ref: "github:acme/seq#1" })).status).toBe(409);
+    const after = (await create(ownerToken, { name: "之后" })).body.requirement;
+    expect(after.seq).toBe(a.seq + 2);
+    // upsert 新建也领号,改的时候号不变
+    const up = await api(ownerToken, "/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "同步", external_ref: "github:acme/seq#2" }) });
+    expect(up.body.requirement.seq).toBe(after.seq + 1);
+    const up2 = await api(ownerToken, "/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "同步改名", external_ref: "github:acme/seq#2" }) });
+    expect(up2.body.requirement.seq).toBe(after.seq + 1);
+  });
+
+  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");
+    // 看全网的成员(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");
+    expect(both.body.networks.sort()).toEqual([ownerNet, otherNet].sort());
+    expect(both.body.message).toContain("pass network_id");
+    // MCP 上用户令牌(跨两个网络)同样:清楚的错误 + 带 network_id 就能查到
+    {
+      const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+      const { InMemoryTransport } = await import("@modelcontextprotocol/sdk/inMemory.js");
+      const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+      const { registerTools } = await import("./tools.js");
+      const mcp = new McpServer({ name: "seq-mcp-user", version: "1" });
+      registerTools(mcp, undefined, null, ownerId, "seq-owner", false, "tok_user");
+      const client = new Client({ name: "seq-mcp-user-client", version: "1" });
+      const [ct, st] = InMemoryTransport.createLinkedPair();
+      await mcp.connect(st); await client.connect(ct);
+      const call = async (name: string, args: Record<string, unknown>) => JSON.parse(((await client.callTool({ name, arguments: args })) as any).content[0].text);
+      try {
+        const amb = await call("requirements_get", { id: "#1" });
+        expect(amb.ok).toBe(false);
+        expect(amb.error).toBe("ambiguous_seq");
+        expect(amb.status).toBe(409);
+        expect(amb.message).toContain("pass network_id");
+        expect((await call("requirements_update", { id: "#1", priority: "low" })).error).toBe("ambiguous_seq");
+        expect((await call("requirements_get", { id: "#1", network_id: otherNet })).requirement.name).toBe("别的网络第一张");
+        expect((await call("requirements_get", { id: "#1", network_id: ownerNet })).requirement.name).toBe("第一张");
+      } finally { await client.close(); await mcp.close(); }
+    }
+    // 旧 id 不受影响
+    const firstId = (await api(ownerToken, `/api/requirements/%231?network_id=${ownerNet}`)).body.requirement.id;
+    expect((await api(ownerToken, `/api/requirements/${firstId}`)).status).toBe(200);
+    const scoped = await api(ownerToken, `/api/requirements/%231?network_id=${otherNet}`);
+    expect(scoped.status).toBe(200);
+    expect(scoped.body.requirement.name).toBe("别的网络第一张");
+    db.run("DELETE FROM network_members WHERE network_id = ?1 AND user_id = ?2", [otherNet, ownerId]);
+  });
+
+  test("MCP tools accept #N and expose seq", async () => {
+    const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+    const { InMemoryTransport } = await import("@modelcontextprotocol/sdk/inMemory.js");
+    const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+    const { registerTools } = await import("./tools.js");
+    const { db } = await import("./db.js");
+    const tokenId = db.get<{ token_id: string }>("SELECT token_id FROM api_tokens WHERE network_id = ?1 AND name LIKE 'node:%' LIMIT 1", ownerNet)?.token_id ?? null;
+    const mcp = new McpServer({ name: "seq-mcp", version: "1" });
+    registerTools(mcp, undefined, ownerNet, ownerId, "seq-node", true, tokenId);
+    const client = new Client({ name: "seq-mcp-client", version: "1" });
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    await mcp.connect(st); await client.connect(ct);
+    const call = async (name: string, args: Record<string, unknown>) => {
+      const r: any = await client.callTool({ name, arguments: args });
+      return r.isError ? { mcpError: true } : JSON.parse(r.content[0].text);
+    };
+    try {
+      const made = await call("requirements_create", { name: "MCP 建的", checklist: [{ id: "k", text: "一" }] });
+      expect(Number.isInteger(made.requirement.seq)).toBe(true);
+      const n = `#${made.requirement.seq}`;
+      expect((await call("requirements_get", { id: n })).requirement.id).toBe(made.requirement.id);
+      expect((await call("requirements_update", { id: n, priority: "high" })).requirement.priority).toBe("high");
+      expect((await call("requirements_checklist_toggle", { id: n, item_id: "k", done: true })).requirement.checklist[0].done).toBe(true);
+      const listed = await call("requirements_list", { seq: made.requirement.seq });
+      expect(listed.requirements.map((r: any) => r.id)).toEqual([made.requirement.id]);
+      expect((await call("requirements_list", { seq: 0 })).mcpError).toBe(true);
+      expect((await call("requirements_get", { id: "#1" })).requirement.name).toBe("第一张"); // 节点令牌只看自己网络的 #1
+    } finally { await client.close(); await mcp.close(); }
+  });
+});

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

@@ -0,0 +1,63 @@
+// 任务短号 seq 的启动迁移:用没有 seq 列的旧表建库、塞行,再走真实启动路径(import db.ts + requirements.ts)。
+// 补号按网络各自从 1 开始,按 created_at(新旧两种时间格式混在一起)排,同一时刻按 requirement_id。
+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-seq-migrate-"));
+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', 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 '[]')`);
+// 插入顺序故意打乱;期望的号写在第三列。
+const rows: [string, string, string, number][] = [
+  ["req_c", "net_a", "2026-09-02T00:00:00.000Z", 5],
+  ["req_a", "net_a", "2026-09-01 08:00:00", 1],        // 旧默认格式(UTC,空格分隔)
+  ["req_z", "net_b", "2026-08-01T00:00:00.000Z", 1],
+  ["req_b2", "net_a", "2026-09-01T09:00:00.000Z", 3],  // 与 req_b1 同一时刻 → 按 id
+  ["req_b1", "net_a", "2026-09-01T09:00:00.000Z", 2],
+  ["req_y", "net_b", "2026-08-02 00:00:00", 2],
+  ["req_d", "net_a", "2026-09-01 23:59:59", 4],        // 旧格式,晚于 09:00 的 ISO、早于 09-02
+];
+for (const [id, net, at] of rows) legacy.run("INSERT INTO requirements (requirement_id, network_id, title, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, ?4)", [id, net, `卡 ${id}`, at]);
+legacy.close();
+
+afterAll(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+test("startup backfills seq per network in created_at order, then id; counters and unique index follow", async () => {
+  const { db } = await import("./db.js");
+  await import("./requirements.js"); // 真实启动路径
+  const got = Object.fromEntries((db.all("SELECT requirement_id, network_id, seq FROM requirements") as any[]).map(r => [r.requirement_id, r.seq]));
+  // net_a 按时间:req_a 09-01 08:00 → req_b1 / req_b2 09-01 09:00(按 id)→ req_d 09-01 23:59:59 → req_c 09-02
+  expect(got).toEqual({ req_a: 1, req_b1: 2, req_b2: 3, req_d: 4, req_c: 5, req_z: 1, req_y: 2 });
+  // 按字符串排会把「2026-09-01 23:59:59」排到所有 ISO 的 09-01 前面 —— 证明排序真的按时刻,不按字面
+  expect("2026-09-01 23:59:59" < "2026-09-01T09:00:00.000Z").toBe(true);
+  const counters = Object.fromEntries((db.all("SELECT network_id, last_seq FROM requirement_seq_counters") as any[]).map(r => [r.network_id, r.last_seq]));
+  expect(counters).toEqual({ net_a: 5, net_b: 2 });
+  const idx = (db.all("PRAGMA index_list(requirements)") as { name: string; unique: number }[]).find(i => i.name === "idx_requirements_network_seq");
+  expect(idx?.unique).toBe(1);
+  expect(() => db.run("UPDATE requirements SET seq = 1 WHERE requirement_id = 'req_c'")).toThrow();
+
+  // 重复执行:已有号的行一个不动;回滚到旧 Hub 期间建的卡(seq 为空)接在后面补号
+  const { ensureRequirementSeq, nextRequirementSeq } = await import("./requirements-migrate.js");
+  expect(ensureRequirementSeq(db).backfilled).toBe(0);
+  db.run("INSERT INTO requirements (requirement_id, network_id, title, created_at, updated_at) VALUES ('req_old_hub', 'net_a', 'x', '2020-01-01T00:00:00Z', '2020-01-01T00:00:00Z')");
+  expect(ensureRequirementSeq(db).backfilled).toBe(1);
+  expect((db.get("SELECT seq FROM requirements WHERE requirement_id = 'req_old_hub'") as any).seq).toBe(6);
+  expect(got.req_a).toBe((db.get("SELECT seq FROM requirements WHERE requirement_id = 'req_a'") as any).seq);
+  // 删掉最大号的卡,下一个号也不回收
+  db.run("DELETE FROM requirements WHERE requirement_id = 'req_old_hub'");
+  ensureRequirementSeq(db);
+  expect(nextRequirementSeq(db, "net_a")).toBe(7);
+  // 从没建过卡的网络从 1 开始
+  expect(nextRequirementSeq(db, "net_new")).toBe(1);
+  expect(nextRequirementSeq(db, "net_new")).toBe(2);
+});

package/src/requirements-start-date.test.ts

@@ -0,0 +1,125 @@
+// 需求的可选开始字段(start,存 start_on):App 甘特图用。
+// 先用「没有 start_on 列」的旧库形状建库、塞行,再走真实启动路径(db.ts + server.ts),看:
+// 列被加上、存量行读出来 start = "" 且别的列原样;POST / PATCH / upsert 都能写;只 PATCH due 不动 start 和描述;
+// 旧客户端(不带 start)的 PATCH 不清掉已有的 start;坏值 400 invalid_start;capabilities 带 start_date。
+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-start-"));
+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', 'lowest')),
+    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'))
+  );
+`);
+legacy.exec("ALTER TABLE requirements ADD COLUMN description TEXT");
+legacy.run("INSERT INTO requirements (requirement_id, network_id, title, due_on, description) VALUES ('r_old', 'net_legacy', '旧卡', '2026-10-01', '旧描述')");
+expect(legacy.query("SELECT name FROM pragma_table_info('requirements') WHERE name = 'start_on'").all()).toEqual([]);
+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(`start_owner_${Date.now()}`, "StartOwner123!", 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("optional requirement start date", () => {
+  test("startup adds start_on to an old table; existing rows keep every value and read start = ''", () => {
+    const cols = (db.all("PRAGMA table_info(requirements)") as { name: string }[]).map(c => c.name);
+    expect(cols).toContain("start_on");
+    const row = db.get("SELECT title, due_on, description, start_on FROM requirements WHERE requirement_id = 'r_old'") as any;
+    expect(row).toEqual({ title: "旧卡", due_on: "2026-10-01", description: "旧描述", start_on: null });
+  });
+
+  test("create / PATCH / upsert write start; due-only PATCH and start-less PATCH keep it", async () => {
+    const created = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "有开始的", start: "2026-09-20", due: "2026-10-01", description: "别动我" }) });
+    expect(created.status).toBe(201);
+    expect(created.body.requirement.start).toBe("2026-09-20");
+    const id = created.body.requirement.id;
+
+    // 甘特图拖动只发 due:start 和描述原样
+    const dueOnly = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ due: "2026-10-05" }) });
+    expect(dueOnly.status).toBe(200);
+    expect(dueOnly.body.requirement.due).toBe("2026-10-05");
+    expect(dueOnly.body.requirement.start).toBe("2026-09-20");
+    expect(dueOnly.body.requirement.description).toBe("别动我");
+
+    // 旧客户端不认识 start:它的 PATCH 不带这个字段,不能清掉
+    const old = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ name: "改名了" }) });
+    expect(old.body.requirement.start).toBe("2026-09-20");
+
+    const instant = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ start: "2026-09-21T09:30:00+08:00" }) });
+    expect(instant.body.requirement.start).toBe("2026-09-21T01:30:00Z");
+    const cleared = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ start: "" }) });
+    expect(cleared.status).toBe(200);
+    expect(cleared.body.requirement.start).toBe("");
+    // 只带 start 的 PATCH 不是 empty_patch
+    const onlyStart = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ start: "2026-09-22" }) });
+    expect(onlyStart.status).toBe(200);
+
+    const up = await api("/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "同步来的", external_ref: "github:t/p#9", start: "2026-09-01" }) });
+    expect(up.status).toBe(201);
+    expect(up.body.requirement.start).toBe("2026-09-01");
+    const upAgain = await api("/api/requirements/upsert", { method: "POST", body: JSON.stringify({ external_ref: "github:t/p#9", start: "2026-09-02" }) });
+    expect(upAgain.body.requirement.start).toBe("2026-09-02");
+
+    const noStart = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "没开始字段" }) });
+    expect(noStart.body.requirement.start).toBe("");
+  });
+
+  test("bad start values are 400 invalid_start and change nothing", async () => {
+    const created = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "坏值", start: "2026-09-20" }) });
+    const id = created.body.requirement.id;
+    for (const bad of ["2026-02-30", "tomorrow", "2026-09-20T10:00:00", 20260920]) {
+      const post = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "x", start: bad }) });
+      const patch = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ start: bad }) });
+      expect(patch.status).toBe(400);
+      expect(patch.body.error).toBe("invalid_start");
+      if (typeof bad === "string") {
+        expect(post.status).toBe(400);
+        expect(post.body.error).toBe("invalid_start");
+      }
+    }
+    const listed = await api("/api/requirements");
+    expect(listed.body.requirements.find((r: any) => r.id === id).start).toBe("2026-09-20");
+    expect(listed.body.capabilities).toContain("start_date");
+    // 旧卡在列表里 start = ""(不是缺字段:新 App 按 capabilities 判断支持与否)
+    expect(listed.body.requirements.every((r: any) => typeof r.start === "string")).toBe(true);
+  });
+});