test(hub): integration 测试套件(13 tests,真 prisma+真 cph)

三层 integration,对齐 unit 层:
- trigger.test.ts: @bot→run→lock→release→card 全链路;权限拒绝(READ
  不能 triggerAgent ADR-0004);竞态 busy(ADR-0002);未绑定 chat 忽略
  (ADR-0001);无 @bot 忽略 —— 5 tests
- lock.test.ts: acquire/release 回环;排他性(同 project 二次 acquire 抛);
  WellFormed(终止 run 持锁即抛);release 幂等;isTerminal 对齐 spec —— 5 tests
- cph.test.ts: 真 cph binary 跑 TH-141 examples 的 check(exit 0)+
  build student PDF(exit 0)+ 空目录 check(非 0)—— 3 tests
helpers: resetDb(truncate CASCADE)、mockFeishuRuntime(记录 sentTexts/
  sentCards)、MockProvider(fixed stop 响应)、seedProject(project→user→grant)
prisma migrate dev init 生成初始 migration 并应用到 cph_hub_test 库。
vitest config 改 fileParallelism=false(integration 共享一 DB,串行避免
truncate/insert 竞态)。
vitest run 35/35(22 unit + 13 integration)通过;tsc rc=0。

hub/test/integration/cph.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ToolRegistry } from "../../src/agent/tools.js";
+import { cphCheckTool, cphBuildTool } from "../../src/agent/cph.js";
+
+const EXAMPLES_DIR = join(process.cwd(), "..", "examples", "TH-141");
+
+describe("cph subprocess tools (integration, real cph binary)", () => {
+  let ws: string;
+  let tools: ToolRegistry;
+
+  beforeEach(async () => {
+    // Use the real TH-141 example as the workspace.
+    ws = EXAMPLES_DIR;
+    tools = new ToolRegistry();
+    tools.register(cphCheckTool());
+    tools.register(cphBuildTool());
+  });
+
+  it("cph_check runs on the TH-141 example and returns diagnostics", async () => {
+    const ctx = { runId: "r", projectId: "p", boundChatId: "c", workspaceDir: ws };
+    const out = await tools.execute("cph_check", {}, ctx);
+    const result = JSON.parse(out) as { exitCode: number; stdout: string; stderr: string };
+
+    // cph check exits 0 on a legal lesson (no error diagnostics, ADR-0010).
+    // If the example has warnings, exit is still 0.
+    expect(result.exitCode).toBe(0);
+  }, 30000);
+
+  it("cph_build renders the student target PDF", async () => {
+    const ctx = { runId: "r", projectId: "p", boundChatId: "c", workspaceDir: ws };
+    const out = await tools.execute("cph_build", { target: "student", output: "build/test-student.pdf" }, ctx);
+    const result = JSON.parse(out) as { exitCode: number; stdout: string; stderr: string; output: string };
+
+    expect(result.exitCode).toBe(0);
+  }, 30000);
+
+  it("cph_check on a temp dir with no engineering file returns non-zero", async () => {
+    const empty = await mkdtemp(join(tmpdir(), "hub-cph-empty-"));
+    try {
+      const ctx = { runId: "r", projectId: "p", boundChatId: "c", workspaceDir: empty };
+      const out = await tools.execute("cph_check", {}, ctx);
+      const result = JSON.parse(out) as { exitCode: number };
+      expect(result.exitCode).not.toBe(0);
+    } finally {
+      await rm(empty, { recursive: true, force: true });
+    }
+  }, 15000);
+});

hub/test/integration/helpers.ts

@@ -0,0 +1,135 @@
+/**
+ * Test helpers for integration tests.
+ *
+ * Each test gets a clean DB (tables truncated before the test), a mock
+ * FeishuRuntime (sendText/sendCard are no-ops that record calls), and a mock
+ * AgentProvider (chat() returns a fixed "stop" response — no real network).
+ */
+import { PrismaClient } from "@prisma/client";
+import type { FastifyBaseLogger } from "fastify";
+import type { FeishuRuntime } from "../src/feishu/client.js";
+import type { AgentProvider, ChatRequest, ChatResponse, Message } from "../src/agent/provider.js";
+
+export const TEST_DATABASE_URL = "postgresql://paradigm:paradigm@127.0.0.1:5432/cph_hub_test";
+
+export const prisma = new PrismaClient({
+  datasources: { db: { url: TEST_DATABASE_URL } },
+});
+
+/** Truncate all tables before each test for isolation. */
+export async function resetDb(): Promise<void> {
+  const tables = [
+    "AuditEntry",
+    "PermissionSettings",
+    "PermissionGrant",
+    "ProjectAgentLock",
+    "AgentRun",
+    "AgentSession",
+    "ProjectGroupBinding",
+    "PlatformRoleAssignment",
+    "User",
+    "Project",
+  ];
+  // Truncate with CASCADE to wipe dependent rows in one shot.
+  await prisma.$executeRawUnsafe(`TRUNCATE TABLE ${tables.map((t) => `"${t}"`).join(", ")} RESTART IDENTITY CASCADE`);
+}
+
+/** A logger that discards everything (tests don't need fastify's pino). */
+export const silentLogger: FastifyBaseLogger = {
+  info() {}, warn() {}, error() {}, debug() {}, fatal() {},
+  child() { return this; },
+  level: "silent",
+} as unknown as FastifyBaseLogger;
+
+/** Records sendText/sendCard calls so tests can assert on them. */
+export interface MockFeishuRuntime extends FeishuRuntime {
+  readonly sentTexts: string[];
+  readonly sentCards: unknown[];
+}
+
+export function mockFeishuRuntime(): MockFeishuRuntime {
+  const sentTexts: string[] = [];
+  const sentCards: unknown[] = [];
+  // Mock the client — sendText/sendCard are in client.ts, not on the runtime
+  // object directly. We patch by providing a runtime whose client is a stub;
+  // the actual send functions cast through shape, so a minimal stub works.
+  const rt: MockFeishuRuntime = {
+    client: {
+      im: {
+        v1: {
+          message: {
+            create: async (p: unknown) => {
+              const payload = p as { data?: { msg_type?: string; content?: string } };
+              if (payload.data?.msg_type === "interactive") {
+                sentCards.push(payload.data.content ? JSON.parse(payload.data.content) : null);
+              } else {
+                try {
+                  const c = JSON.parse(payload.data?.content ?? "{}") as { text?: string };
+                  sentTexts.push(c.text ?? payload.data?.content ?? "");
+                } catch {
+                  sentTexts.push(payload.data?.content ?? "");
+                }
+              }
+              return { data: { message_id: "mock-msg-id" } };
+            },
+          },
+        },
+      },
+    } as unknown as FeishuRuntime["client"],
+    logger: silentLogger,
+    sentTexts,
+    sentCards,
+  };
+  return rt;
+}
+
+/** A provider that always returns a fixed "stop" response — no network. */
+export class MockProvider implements AgentProvider {
+  readonly id = "mock";
+  readonly calls: ChatRequest[] = [];
+
+  async chat(req: ChatRequest): Promise<ChatResponse> {
+    this.calls.push(req);
+    const message: Message = {
+      role: "assistant",
+      parts: [{ type: "text", text: "mock response" }],
+    };
+    return { finishReason: "stop", message, usage: { inputTokens: 10, outputTokens: 5 } };
+  }
+}
+
+/** Create a project + binding + user + grant for a test. */
+export async function seedProject(
+  projectId: string,
+  chatId: string,
+  options: { principal?: string; role?: "READ" | "EDIT" | "MANAGE" } = {},
+): Promise<void> {
+  const principal = options.principal ?? "ou_test_user";
+  const role = options.role ?? "EDIT";
+  await prisma.project.create({
+    data: {
+      id: projectId,
+      name: `Test ${projectId}`,
+      workspaceDir: `/tmp/test-${projectId}`,
+    },
+  });
+  await prisma.user.create({
+    data: {
+      id: "u_" + projectId,
+      feishuOpenId: principal,
+      displayName: "Test User",
+      platformRoles: { create: { role: "TEACHER" } },
+      permissionGrants: {
+        create: {
+          resourceType: "PROJECT",
+          resourceId: projectId,
+          principal,
+          role,
+        },
+      },
+    },
+  });
+  await prisma.projectGroupBinding.create({
+    data: { projectId, chatId, createdByUserId: "u_" + projectId },
+  });
+}

hub/test/integration/lock.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterAll } from "vitest";
+import { prisma, resetDb } from "./helpers.js";
+import { acquireLock, releaseLock, currentLockRunId, isTerminal } from "../../src/lock.js";
+
+describe("ProjectAgentLock WellFormed (integration, ADR-0002)", () => {
+  beforeEach(async () => {
+    await resetDb();
+  });
+
+  it("acquireLock + currentLockRunId round-trip", async () => {
+    const project = await prisma.project.create({
+      data: { id: "p-lock-1", name: "Test", workspaceDir: "/tmp/x" },
+    });
+    const run = await prisma.agentRun.create({
+      data: { projectId: project.id, entrypoint: "FEISHU", status: "ACTIVE", prompt: "x", model: "m", provider: "mock", metadata: {} },
+    });
+
+    await acquireLock(prisma, project.id, run.id, null);
+    const holder = await currentLockRunId(prisma, project.id);
+    expect(holder).toBe(run.id);
+
+    await releaseLock(prisma, run.id);
+    const after = await currentLockRunId(prisma, project.id);
+    expect(after).toBeNull();
+  });
+
+  it("acquireLock fails when project already locked (exclusivity)", async () => {
+    const project = await prisma.project.create({
+      data: { id: "p-lock-2", name: "Test", workspaceDir: "/tmp/x" },
+    });
+    const run1 = await prisma.agentRun.create({
+      data: { projectId: project.id, entrypoint: "FEISHU", status: "ACTIVE", prompt: "x", model: "m", provider: "mock", metadata: {} },
+    });
+    const run2 = await prisma.agentRun.create({
+      data: { projectId: project.id, entrypoint: "FEISHU", status: "ACTIVE", prompt: "y", model: "m", provider: "mock", metadata: {} },
+    });
+
+    await acquireLock(prisma, project.id, run1.id, null);
+    await expect(acquireLock(prisma, project.id, run2.id, null)).rejects.toThrow();
+  });
+
+  it("currentLockRunId throws when a terminal run holds the lock (WellFormed)", async () => {
+    const project = await prisma.project.create({
+      data: { id: "p-lock-3", name: "Test", workspaceDir: "/tmp/x" },
+    });
+    // Create a run that is already COMPLETED (terminal), then manually insert a lock.
+    const run = await prisma.agentRun.create({
+      data: { projectId: project.id, entrypoint: "FEISHU", status: "COMPLETED", prompt: "x", model: "m", provider: "mock", metadata: {}, finishedAt: new Date() },
+    });
+    await prisma.projectAgentLock.create({
+      data: { projectId: project.id, runId: run.id },
+    });
+
+    // WellFormed invariant: reading a lock held by a terminal run must throw.
+    await expect(currentLockRunId(prisma, project.id)).rejects.toThrow(/lock invariant violated/);
+  });
+
+  it("releaseLock is idempotent", async () => {
+    const project = await prisma.project.create({
+      data: { id: "p-lock-4", name: "Test", workspaceDir: "/tmp/x" },
+    });
+    const run = await prisma.agentRun.create({
+      data: { projectId: project.id, entrypoint: "FEISHU", status: "ACTIVE", prompt: "x", model: "m", provider: "mock", metadata: {} },
+    });
+
+    await acquireLock(prisma, project.id, run.id, null);
+    await releaseLock(prisma, run.id);
+    // Second release is a no-op.
+    await releaseLock(prisma, run.id);
+    expect(await currentLockRunId(prisma, project.id)).toBeNull();
+  });
+
+  it("isTerminal matches spec RunState.Terminal", () => {
+    expect(isTerminal("ACTIVE")).toBe(false);
+    expect(isTerminal("WAITING_FOR_USER")).toBe(false);
+    expect(isTerminal("COMPLETED")).toBe(true);
+    expect(isTerminal("FAILED")).toBe(true);
+    expect(isTerminal("TIMED_OUT")).toBe(true);
+    expect(isTerminal("CANCELED")).toBe(true);
+  });
+});
+
+afterAll(async () => {
+  await prisma.$disconnect();
+});

hub/test/integration/trigger.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach, afterAll, vi } from "vitest";
+import { prisma, resetDb, mockFeishuRuntime, MockProvider, seedProject, silentLogger } from "./helpers.js";
+import { InMemoryModelRegistry } from "../../src/agent/models.js";
+import { ToolRegistry, feishuContextTool } from "../../src/agent/tools.js";
+import { makeTriggerHandler, extractPrompt } from "../../src/feishu/trigger.js";
+import type { MessageReceiveEvent } from "../../src/feishu/client.js";
+
+const bot = { key: "@_user_1", id: { open_id: "ou_bot" }, name: "Bot" };
+
+function makeEvent(chatId: string, text: string, senderOpenId = "ou_test_user"): MessageReceiveEvent {
+  return {
+    message: {
+      message_id: "m_" + Math.random().toString(36).slice(2),
+      chat_id: chatId,
+      chat_type: "group",
+      message_type: "text",
+      content: JSON.stringify({ text }),
+      mentions: [bot],
+    },
+    sender: { sender_id: { open_id: senderOpenId }, sender_type: "user" },
+  };
+}
+
+describe("trigger full lifecycle (integration)", () => {
+  let provider: MockProvider;
+  let tools: ToolRegistry;
+  let models: InMemoryModelRegistry;
+  let rt: ReturnType<typeof mockFeishuRuntime>;
+
+  beforeEach(async () => {
+    await resetDb();
+    provider = new MockProvider();
+    tools = new ToolRegistry();
+    models = new InMemoryModelRegistry(
+      [{ id: "mock-model", label: "Mock", toolCapable: true }],
+      [{ id: "draft", label: "草稿", defaultModel: "mock-model" }],
+    );
+    rt = mockFeishuRuntime();
+  });
+
+  it("creates a run, acquires + releases the lock, sends status card", async () => {
+    await seedProject("proj-1", "chat-1");
+    const trigger = makeTriggerHandler({ prisma, provider, tools, models, logger: silentLogger });
+
+    await trigger(makeEvent("chat-1", "@_user_1 写教案"), rt);
+
+    // Wait for the async run to complete (fire-and-forget in trigger).
+    await vi.waitFor(async () => {
+      const runs = await prisma.agentRun.findMany();
+      expect(runs).toHaveLength(1);
+      expect(runs[0]?.status).toBe("COMPLETED");
+    });
+
+    // Lock released (no lock row remains).
+    const locks = await prisma.projectAgentLock.findMany();
+    expect(locks).toHaveLength(0);
+
+    // A status card was sent.
+    expect(rt.sentCards.length).toBeGreaterThanOrEqual(1);
+    expect(rt.sentTexts).toContain("已开始处理(model: mock-model)。");
+  });
+
+  it("rejects a sender without edit grant (ADR-0004)", async () => {
+    await seedProject("proj-2", "chat-2", { role: "READ" });
+    const trigger = makeTriggerHandler({ prisma, provider, tools, models, logger: silentLogger });
+
+    await trigger(makeEvent("chat-2", "@_user_1 写教案"), rt);
+
+    expect(rt.sentTexts).toContain("无权限触发。");
+    const runs = await prisma.agentRun.findMany();
+    expect(runs).toHaveLength(0);
+  });
+
+  it("replies busy when project is already locked (ADR-0002)", async () => {
+    await seedProject("proj-3", "chat-3");
+    // Manually create a lock by inserting a run + lock.
+    const existingRun = await prisma.agentRun.create({
+      data: { projectId: "proj-3", entrypoint: "FEISHU", status: "ACTIVE", prompt: "x", model: "m", provider: "mock", metadata: {} },
+    });
+    await prisma.projectAgentLock.create({
+      data: { projectId: "proj-3", runId: existingRun.id },
+    });
+
+    const trigger = makeTriggerHandler({ prisma, provider, tools, models, logger: silentLogger });
+    await trigger(makeEvent("chat-3", "@_user_1 写教案"), rt);
+
+    expect(rt.sentTexts).toContain("项目正在处理中,请稍候。");
+    // No new run created.
+    const runs = await prisma.agentRun.findMany();
+    expect(runs).toHaveLength(1);
+  });
+
+  it("ignores messages from unbound chats (ADR-0001)", async () => {
+    await seedProject("proj-4", "chat-4");
+    const trigger = makeTriggerHandler({ prisma, provider, tools, models, logger: silentLogger });
+
+    await trigger(makeEvent("chat-UNKNOWN", "@_user_1 写教案"), rt);
+
+    expect(rt.sentTexts).toHaveLength(0);
+    expect(rt.sentCards).toHaveLength(0);
+    const runs = await prisma.agentRun.findMany();
+    expect(runs).toHaveLength(0);
+  });
+
+  it("ignores messages without @bot mention", async () => {
+    await seedProject("proj-5", "chat-5");
+    const trigger = makeTriggerHandler({ prisma, provider, tools, models, logger: silentLogger });
+
+    const event: MessageReceiveEvent = {
+      message: {
+        message_id: "m_nobot",
+        chat_id: "chat-5",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello no bot" }),
+        mentions: undefined,
+      },
+      sender: { sender_id: { open_id: "ou_test_user" }, sender_type: "user" },
+    };
+    await trigger(event, rt);
+
+    expect(rt.sentTexts).toHaveLength(0);
+    const runs = await prisma.agentRun.findMany();
+    expect(runs).toHaveLength(0);
+  });
+});
+
+afterAll(async () => {
+  await prisma.$disconnect();
+});