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

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

@@ -0,0 +1,192 @@
+// 任务短号 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");
+    addNetworkMember(otherNet, ownerId, "member", otherId);
+    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);
+  });
+});