@allbluecn/web-app 0.17.1 → 0.18.0

package/src/server/serverFns/testcase/generation-schema.ts

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// AI 生成测试用例的结构化产物 schema（规格 §7 逐字钉死）。
+// 纯净自含文件：仅依赖 zod，steps/枚举全部内联定义——serverFn（任务 20）与
+// runChatAsAgent 的 outputSchema 直接消费本文件，禁止再引入其他模块。
+import { z } from "zod";
+
+// ── 分组维度四值（规格 §7 钉死的中文字面量）──
+export const TESTGEN_ASPECT_VALUES = ["正常流", "边界", "异常", "安全"] as const;
+export type TestGenAspect = (typeof TESTGEN_ASPECT_VALUES)[number];
+
+// ── type/priority 值域（与手建 TestCase 的 constants.ts 同域；自含内联防跨文件耦合，
+// 一致性由 testgen-output.test.ts 哨兵断言钉住）──
+export const TESTGEN_CASE_TYPE_VALUES = [
+  "functional",
+  "boundary",
+  "exception",
+  "performance",
+  "security",
+  "compatibility",
+] as const;
+export type TestGenCaseType = (typeof TESTGEN_CASE_TYPE_VALUES)[number];
+
+export const TESTGEN_CASE_PRIORITY_VALUES = ["p0", "p1", "p2", "p3"] as const;
+export type TestGenCasePriority = (typeof TESTGEN_CASE_PRIORITY_VALUES)[number];
+
+const TestGenStepSchema = z.object({
+  order: z.number().int().min(1),
+  action: z.string().min(1),
+  expected: z.string().optional(),
+});
+
+const TestGenCaseSchema = z
+  .object({
+    title: z.string().min(1),
+    precondition: z.string().optional(),
+    steps: z.array(TestGenStepSchema).min(1),
+    type: z.enum(TESTGEN_CASE_TYPE_VALUES),
+    priority: z.enum(TESTGEN_CASE_PRIORITY_VALUES),
+    rationale: z.string().min(1),
+  })
+  .superRefine((val, ctx) => {
+    const seen = new Set<number>();
+    for (const step of val.steps) {
+      if (seen.has(step.order)) {
+        ctx.addIssue({
+          code: "custom",
+          message: `步骤序号 order 重复：${step.order}`,
+          path: ["steps"],
+        });
+      }
+      seen.add(step.order);
+    }
+  });
+
+const TestGenGroupSchema = z.object({
+  aspect: z.enum(TESTGEN_ASPECT_VALUES),
+  conditions: z.array(z.string()),
+  cases: z.array(TestGenCaseSchema),
+});
+
+export const TestGenerationOutputSchema = z.object({
+  groups: z.array(TestGenGroupSchema).min(1),
+  coverageNotes: z.array(z.string()),
+});
+
+export type TestGenerationOutput = z.infer<typeof TestGenerationOutputSchema>;

package/src/server/serverFns/testcase/generation.ts

@@ -0,0 +1,540 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// AI 生成批次 serverFns（规格 §7 R3 链路）。本文件只准导出 createServerFn 产物
+// （serverFn 纯净铁律），描述纯文本化、kbContext 组装、DTO cast 等均为文件内私有成员。
+// 链路：startGenerationFn 组装 input（storySnapshot + description 纯文本 + 同 Story
+// 既有用例标题清单做去重提示 + kbContext 字符截断）→ runChatAsAgent(bizKey='testgen',
+// outputSchema=TestGenerationOutputSchema) → 产物落 TestGenerationRun.output + 批量建
+// draft 用例（aiGenerated/generationId 回链）。AI 调用与 parse 均包 try-catch 降级：
+// 失败置 run.status=failed + error（不抛给前端，返回 run 记录可重试），半结构化产物
+// 不建 draft 不污染库。adoptDraftsFn：draft→approved（edits 随采纳应用）、拒绝→
+// deprecated（留痕）、adoptedCount 回写；重复采纳（adoptedCount>0）拒绝且零写。
+import { getPrisma } from "@allbluecn/database/get-prisma";
+import { createServerFn } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+import { z } from "zod";
+import type { Prisma } from "@allbluecn/database";
+import { requireAuth } from "@/server/auth-helpers";
+import { requireFeature } from "@/server/entitlements";
+import { checkAiRateLimit } from "@/server/lib/rate-limit";
+import { hasAiKey } from "@/server/ai-gateway/adapter";
+import { runChatAsAgent } from "@/server/ai-gateway/runs/agent-runtime";
+import {
+  TestGenerationOutputSchema,
+  TESTGEN_CASE_PRIORITY_VALUES,
+  TESTGEN_CASE_TYPE_VALUES,
+  type TestGenerationOutput,
+} from "./generation-schema";
+import { TEST_CASE_IDENTIFIER_PREFIX } from "./constants";
+
+/** 项目有效成员校验（口径同 testcase-crud：suspended 视同无权限） */
+async function assertProjectMembership(projectId: string, userId: string) {
+  const prisma = await getPrisma();
+  const membership = await prisma.projectMember.findUnique({
+    where: { projectId_userId: { projectId, userId } },
+    select: { status: true },
+  });
+  if (!membership || membership.status === "suspended") {
+    throw new Error("无权限操作该项目的测试模块");
+  }
+}
+
+// ── description 纯文本化（与 lib/story/description-diff.ts 兼容口径一致的三形态：
+// JSON 主格式 {html, markdown} / 裸 HTML / 纯文本。文件内私有防 serverFn 模块混装）──
+
+function stripHtml(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">");
+}
+
+function descriptionToPlainText(desc: string | null | undefined): string {
+  if (!desc) return "";
+  try {
+    const parsed = JSON.parse(desc) as { html?: unknown; markdown?: unknown };
+    if (typeof parsed.markdown === "string" && parsed.markdown) return parsed.markdown;
+    if (typeof parsed.html === "string" && parsed.html) return stripHtml(parsed.html);
+  } catch {
+    // 非 JSON：裸 HTML 或纯文本
+  }
+  return /<\/?[a-z][^>]*>/i.test(desc) ? stripHtml(desc) : desc;
+}
+
+// ── kbContext 组装（规格 §7 截断预算 8K tokens ≈ 24K chars 的最小实现：
+// 按 docId 直取文档纯文本拼接 + 逐篇 8K / 总量 24K 字符截断；仅收录当前用户
+// 名下知识库的未删除文档。检索式召回（向量搜索）为后续增强点，接口形状不变 ──
+
+interface KbExcerpt {
+  docId: string;
+  title: string;
+  excerpt: string;
+}
+
+const KB_PER_DOC_CHAR_LIMIT = 8_000;
+const KB_TOTAL_CHAR_LIMIT = 24_000;
+
+/** TipTap content Json → 纯文本（node.text 递归拼接，兼容 markdown/html 载体） */
+function contentToPlainText(content: unknown): string {
+  if (!content || typeof content !== "object") return typeof content === "string" ? content : "";
+  const obj = content as Record<string, unknown>;
+  if (typeof obj.markdown === "string" && obj.markdown) return obj.markdown;
+  if (typeof obj.html === "string" && obj.html) return stripHtml(obj.html);
+  if (typeof obj.text === "string" && obj.text) return obj.text;
+  const walk = (node: unknown): string => {
+    if (!node || typeof node !== "object") return "";
+    const n = node as Record<string, unknown>;
+    if (typeof n.text === "string") return n.text;
+    if (Array.isArray(n.content)) return n.content.map(walk).join("");
+    return "";
+  };
+  if (obj.doc || obj.json) return walk(obj.doc ?? obj.json);
+  if (obj.type === "doc" && Array.isArray(obj.content)) return walk(obj);
+  return "";
+}
+
+async function buildKbContext(
+  kbDocIds: string[],
+  userId: string,
+): Promise<KbExcerpt[]> {
+  if (kbDocIds.length === 0) return [];
+  const prisma = await getPrisma();
+  const docs = await prisma.knowledgeDocument.findMany({
+    where: { id: { in: kbDocIds }, isDeleted: false },
+    select: { id: true, title: true, content: true, kb: { select: { userId: true } } },
+  });
+  const excerpts: KbExcerpt[] = [];
+  let total = 0;
+  for (const doc of docs) {
+    if (doc.kb.userId !== userId) continue;
+    const text = contentToPlainText(doc.content) || doc.title;
+    if (!text.trim()) continue;
+    const excerpt = text.slice(0, KB_PER_DOC_CHAR_LIMIT);
+    if (total + excerpt.length > KB_TOTAL_CHAR_LIMIT) {
+      excerpts.push({ docId: doc.id, title: doc.title, excerpt: excerpt.slice(0, Math.max(0, KB_TOTAL_CHAR_LIMIT - total)) });
+      break;
+    }
+    excerpts.push({ docId: doc.id, title: doc.title, excerpt });
+    total += excerpt.length;
+  }
+  return excerpts;
+}
+
+// ── DTO cast（日期转 ISO 跨 JSON 边界；Json 域用 Prisma.JsonValue 保持可序列化形状；
+// 文件内私有）──
+
+interface TestGenerationRunDTO {
+  id: string;
+  projectId: string;
+  storyId: string;
+  status: string;
+  error: string | null;
+  input: Prisma.JsonValue | null;
+  output: Prisma.JsonValue | null;
+  draftCount: number;
+  adoptedCount: number;
+  createdAt: string;
+  completedAt: string | null;
+}
+
+type RunRow = {
+  id: string;
+  projectId: string;
+  storyId: string;
+  status: string;
+  error: string | null;
+  input: Prisma.JsonValue | null;
+  output: Prisma.JsonValue | null;
+  draftCount: number;
+  adoptedCount: number;
+  createdAt: Date;
+  completedAt: Date | null;
+};
+
+function castRun(row: RunRow): TestGenerationRunDTO {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    storyId: row.storyId,
+    status: row.status,
+    error: row.error,
+    input: row.input,
+    output: row.output,
+    draftCount: row.draftCount,
+    adoptedCount: row.adoptedCount,
+    createdAt: row.createdAt.toISOString(),
+    completedAt: row.completedAt ? row.completedAt.toISOString() : null,
+  };
+}
+
+interface GenerationDraftDTO {
+  id: string;
+  sequenceId: number;
+  identifier: string;
+  title: string;
+  precondition: string | null;
+  steps: { steps: { order: number; action: string; expected?: string }[] };
+  type: string;
+  priority: string;
+  state: string;
+  aiGenerated: boolean;
+  generationId: string | null;
+}
+
+type DraftRow = {
+  id: string;
+  sequenceId: number;
+  identifier: string;
+  title: string;
+  precondition: string | null;
+  steps: unknown;
+  type: string;
+  priority: string;
+  state: string;
+  aiGenerated: boolean;
+  generationId: string | null;
+};
+
+function castDraft(row: DraftRow): GenerationDraftDTO {
+  return {
+    id: row.id,
+    sequenceId: row.sequenceId,
+    identifier: row.identifier,
+    title: row.title,
+    precondition: row.precondition,
+    steps: row.steps as GenerationDraftDTO["steps"],
+    type: row.type,
+    priority: row.priority,
+    state: row.state,
+    aiGenerated: row.aiGenerated,
+    generationId: row.generationId,
+  };
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// ── 启动生成批次 ──
+
+const startGenerationInputSchema = z.object({
+  storyId: z.string().min(1),
+  kbDocIds: z.array(z.string().min(1)).max(5).optional(),
+});
+
+export const startGenerationFn = createServerFn({ method: "POST" })
+  .validator(startGenerationInputSchema)
+  .handler(async ({ data }) => {
+    // 计费门控（规格 §12）：serverFn 第一行 requireFeature
+    await requireFeature(getRequest(), "testGeneration");
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+    await checkAiRateLimit(userId, "testGeneration");
+
+    if (!(await hasAiKey(userId))) {
+      throw new Error("AI 未配置，请先前往 AI 设置页配置 API Key");
+    }
+
+    const prisma = await getPrisma();
+    const story = await prisma.story.findUnique({
+      where: { id: data.storyId },
+      select: { id: true, projectId: true, name: true, description: true },
+    });
+    if (!story) throw new Error("需求不存在");
+    await assertProjectMembership(story.projectId, userId);
+
+    // 去重基准：同 Story 未归档用例标题清单（规格 §7「同 Story 既有用例标题」）
+    const existing = await prisma.testCase.findMany({
+      where: { storyId: story.id, archived: false },
+      select: { title: true },
+      take: 200,
+      orderBy: { sequenceId: "asc" },
+    });
+
+    const kbContext = await buildKbContext(data.kbDocIds ?? [], userId);
+    const descriptionText = descriptionToPlainText(story.description);
+
+    const inputPayload = {
+      storySnapshot: { name: story.name, descriptionText },
+      // Story 模型无结构化 AC 字段，验收标准含于 descriptionText（prompt 内做 ThoughtWorks
+      // AC→测试条件拆解）；字段按规格 §3.4 形状保留，接结构化 AC 后在此填充
+      acceptanceCriteria: [] as string[],
+      kbContext: kbContext.map(({ docId, excerpt }) => ({ docId, excerpt })),
+    };
+
+    // run 先建（running）——AI 失败置 failed 可重试
+    const run = await prisma.testGenerationRun.create({
+      data: {
+        projectId: story.projectId,
+        storyId: story.id,
+        status: "running",
+        input: inputPayload as unknown as Prisma.InputJsonValue,
+        createdById: userId,
+      },
+    });
+
+    try {
+      const raw = await runChatAsAgent(
+        "testgen",
+        [{ role: "user", content: `为需求「${story.name}」生成测试用例` }],
+        {
+          userId,
+          temperature: 0.2,
+          promptVars: {
+            storyContext: `【需求】${story.name}\n【描述】\n${descriptionText || "（无）"}`,
+            kbContext:
+              kbContext.length > 0
+                ? kbContext.map((k) => `《${k.title}》\n${k.excerpt}`).join("\n\n")
+                : "（无）",
+            existingTitles:
+              existing.length > 0
+                ? existing.map((c) => `- ${c.title}`).join("\n")
+                : "（暂无）",
+          },
+          outputSchema: TestGenerationOutputSchema,
+        },
+      );
+
+      // 半结构化产物不污染库：parse 失败走 catch → failed（审查重点 5）
+      const output: TestGenerationOutput = TestGenerationOutputSchema.parse(
+        JSON.parse(raw),
+      );
+
+      // flatMap 组序展平（评审 UI 按 output.groups 顺序对齐草稿卡片流）
+      const flatCases = output.groups.flatMap((group) =>
+        group.cases.map((c) => ({ ...c, aspect: group.aspect })),
+      );
+
+      const { createdDrafts, updatedRun } = await prisma.$transaction(async (tx) => {
+        const project = await tx.project.findUnique({
+          where: { id: story.projectId },
+          select: { displayId: true, name: true },
+        });
+        if (!project) throw new Error("项目不存在");
+        const prefix =
+          (project.displayId ?? project.name ?? "")
+            .replace(/[^a-zA-Z0-9]/g, "")
+            .toUpperCase() || "PRJ";
+
+        const createdDrafts: DraftRow[] = [];
+        for (const c of flatCases) {
+          // 落库前再守一道：draft 用例 steps 至少 1 步（outputSchema 已保证，双保险）
+          if (c.steps.length < 1) throw new Error(`用例「${c.title}」步骤为空，产物无效`);
+          const counter = await tx.sequenceCounter.upsert({
+            where: { scope: `testcase:${story.projectId}` },
+            create: { scope: `testcase:${story.projectId}`, seq: 1 },
+            update: { seq: { increment: 1 } },
+          });
+          const created = await tx.testCase.create({
+            data: {
+              sequenceId: counter.seq,
+              identifier: `${prefix}${TEST_CASE_IDENTIFIER_PREFIX}${counter.seq}`,
+              projectId: story.projectId,
+              storyId: story.id,
+              title: c.title,
+              precondition: c.precondition ?? null,
+              steps: { steps: c.steps } as unknown as Prisma.InputJsonValue,
+              type: c.type,
+              priority: c.priority,
+              state: "draft",
+              aiGenerated: true,
+              generationId: run.id,
+              createdById: userId,
+            },
+          });
+          createdDrafts.push(created as unknown as DraftRow);
+        }
+
+        await tx.testGenerationRun.update({
+          where: { id: run.id },
+          data: {
+            status: "completed",
+            output: output as unknown as Prisma.InputJsonValue,
+            draftCount: createdDrafts.length,
+            completedAt: new Date(),
+          },
+        });
+        const updatedRun = await tx.testGenerationRun.findUniqueOrThrow({
+          where: { id: run.id },
+        });
+        return { createdDrafts, updatedRun: updatedRun as unknown as RunRow };
+      });
+
+      return {
+        run: castRun(updatedRun),
+        drafts: createdDrafts.map(castDraft),
+      };
+    } catch (err) {
+      // AI 失败降级：置 failed + error，不抛给前端（返回 run 记录可重试）
+      const failed = await prisma.testGenerationRun.update({
+        where: { id: run.id },
+        data: { status: "failed", error: errMessage(err), completedAt: new Date() },
+      });
+      return { run: castRun(failed), drafts: [] as GenerationDraftDTO[] };
+    }
+  });
+
+// ── 采纳/拒绝草稿 ──
+
+const DraftEditsSchema = z.object({
+  title: z.string().min(1).max(200).optional(),
+  precondition: z.string().nullable().optional(),
+  steps: z
+    .object({
+      steps: z
+        .array(
+          z.object({
+            order: z.number().int().min(1),
+            action: z.string().min(1),
+            expected: z.string().optional(),
+          }),
+        )
+        .min(1),
+    })
+    .optional(),
+  type: z.enum(TESTGEN_CASE_TYPE_VALUES).optional(),
+  priority: z.enum(TESTGEN_CASE_PRIORITY_VALUES).optional(),
+});
+
+const adoptDraftsInputSchema = z.object({
+  generationId: z.string().min(1),
+  adopted: z
+    .array(
+      z.object({
+        caseId: z.string().min(1),
+        edits: DraftEditsSchema.optional(),
+      }),
+    )
+    .max(500),
+  rejected: z.array(z.string().min(1)).max(500),
+});
+
+export const adoptDraftsFn = createServerFn({ method: "POST" })
+  .validator(adoptDraftsInputSchema)
+  .handler(async ({ data }) => {
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+    const prisma = await getPrisma();
+
+    const run = await prisma.testGenerationRun.findUnique({
+      where: { id: data.generationId },
+    });
+    if (!run) throw new Error("生成批次不存在");
+    await assertProjectMembership(run.projectId, userId);
+    if (run.status !== "completed") {
+      throw new Error("批次未完成或已失败，无法评审");
+    }
+    // 重复 adopt 二次调用被拒（拒绝路径零写）
+    if (run.adoptedCount > 0) {
+      throw new Error("该批次已完成评审采纳，不能重复提交");
+    }
+
+    // 载荷合法性：adopted/rejected 交集拒绝；adopted 内部去重
+    const adoptedIds = data.adopted.map((a) => a.caseId);
+    const rejectedSet = new Set(data.rejected);
+    const overlap = adoptedIds.filter((id) => rejectedSet.has(id));
+    if (overlap.length > 0) {
+      throw new Error(`采纳与拒绝列表存在交集：${overlap.join("、")}`);
+    }
+    const adoptedSet = new Set(adoptedIds);
+    if (adoptedSet.size !== adoptedIds.length) {
+      throw new Error("采纳列表存在重复用例");
+    }
+
+    const allIds = [...adoptedIds, ...data.rejected];
+    const batchCases = await prisma.testCase.findMany({
+      where: {
+        id: { in: allIds },
+        generationId: run.id,
+        projectId: run.projectId,
+      },
+      select: { id: true, state: true },
+    });
+    if (batchCases.length !== allIds.length) {
+      throw new Error("存在不属于该批次的用例");
+    }
+    const nonDraft = batchCases.filter((c) => c.state !== "draft");
+    if (nonDraft.length > 0) {
+      throw new Error("部分用例状态已变更，请刷新后重试");
+    }
+
+    await prisma.$transaction(async (tx) => {
+      // 评审权条件更新（并发 TOCTOU 治理）：仅当 adoptedCount 仍为 0 时占位写入。
+      // 行锁使并发事务在此串行化——后到者 count=0 → 抛错整体回滚（含下方用例更新），
+      // 「批次仅评审一次」不变量由 DB 条件保证而非事务外 check-then-act。
+      const claim = await tx.testGenerationRun.updateMany({
+        where: { id: run.id, adoptedCount: 0 },
+        data: { adoptedCount: data.adopted.length },
+      });
+      if (claim.count !== 1) {
+        throw new Error("该批次已被其他成员完成评审，不能重复提交");
+      }
+      for (const a of data.adopted) {
+        await tx.testCase.update({
+          where: { id: a.caseId },
+          data: { state: "approved", ...(a.edits ?? {}) },
+        });
+      }
+      if (data.rejected.length > 0) {
+        // 拒绝→deprecated 留痕（规格 §13 R3：拒绝用例留痕）
+        await tx.testCase.updateMany({
+          where: { id: { in: data.rejected } },
+          data: { state: "deprecated" },
+        });
+      }
+    });
+
+    return {
+      runId: run.id,
+      adopted: data.adopted.length,
+      rejected: data.rejected.length,
+      actorId: userId,
+    };
+  });
+
+// ── 批次详情（评审界面数据源）──
+
+const getGenerationInputSchema = z.object({
+  generationId: z.string().min(1),
+});
+
+export const getGenerationFn = createServerFn({ method: "POST" })
+  .validator(getGenerationInputSchema)
+  .handler(async ({ data }) => {
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+    const prisma = await getPrisma();
+
+    const run = await prisma.testGenerationRun.findUnique({
+      where: { id: data.generationId },
+    });
+    if (!run) throw new Error("生成批次不存在");
+    await assertProjectMembership(run.projectId, userId);
+
+    const drafts = await prisma.testCase.findMany({
+      where: { generationId: run.id },
+      orderBy: { sequenceId: "asc" },
+    });
+
+    return { run: castRun(run), drafts: drafts.map(castDraft) };
+  });