create-windy 0.4.1 → 0.5.1

package/template/apps/server/src/ai-runtime-report/routes.ts

@@ -0,0 +1,172 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import { parsePagination } from "../pagination.js";
+import { findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { routeContext } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+import { withPermission } from "../system/resource-route-support.js";
+import {
+  AiRuntimeReportError,
+  type AiRuntimeReportService,
+} from "./service.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function registerAiRuntimeReportRoutes(
+  app: RouteApp,
+  service: AiRuntimeReportService,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+): void {
+  const feature = findFeature(features, "system.ai-runtime");
+
+  app.get("/system/ai-runtime/summary", (rawContext) => {
+    const { guardContext, query } = routeContext(rawContext);
+    return permitted(runtime, guardContext, feature, () =>
+      safe(() => service.summary(reportQuery(query), guardContext)),
+    );
+  });
+
+  app.get("/system/ai-runtime/runs", (rawContext) => {
+    const { guardContext, query } = routeContext(rawContext);
+    return permitted(runtime, guardContext, feature, () =>
+      safe(async () => {
+        const pagination = parsePagination(query);
+        if (pagination instanceof Response) return pagination;
+        return service.runs(
+          { ...reportQuery(query), ...pagination },
+          guardContext,
+        );
+      }),
+    );
+  });
+
+  app.get("/system/ai-runtime/runs/:runId", (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return permitted(runtime, guardContext, feature, () =>
+      safe(() => service.run(runId(params.runId), guardContext)),
+    );
+  });
+
+  app.get("/system/ai-runtime/actors", (rawContext) => {
+    const { guardContext, query } = routeContext(rawContext);
+    return permitted(runtime, guardContext, feature, () =>
+      safe(async () => {
+        const pagination = parsePagination(query);
+        if (pagination instanceof Response) return pagination;
+        return service.actorPage(
+          {
+            ...pagination,
+            ...(keyword(query.q) ? { q: keyword(query.q) } : {}),
+          },
+          guardContext,
+        );
+      }),
+    );
+  });
+}
+
+function permitted(
+  runtime: ServerRuntime,
+  context: Parameters<typeof withPermission>[1],
+  feature: FeatureFlagDefinition | undefined,
+  handler: () => unknown,
+) {
+  return withPermission(
+    runtime,
+    context,
+    "GET",
+    "ai-runtime",
+    "read",
+    feature,
+    handler,
+  );
+}
+
+function reportQuery(query: Record<string, string | undefined>) {
+  if (query.actorId !== undefined) {
+    throw new AiRuntimeReportError(
+      "INVALID_AI_RUNTIME_QUERY",
+      "操作者筛选必须使用 opaque handle",
+      400,
+    );
+  }
+  const range = query.range ?? "day";
+  if (!["day", "month", "retained"].includes(range)) {
+    throw new AiRuntimeReportError(
+      "INVALID_AI_RUNTIME_RANGE",
+      "报表时间范围无效",
+      400,
+    );
+  }
+  const actorHandle = optionalActorHandle(query.actorHandle);
+  return {
+    range: range as "day" | "month" | "retained",
+    ...(actorHandle ? { actorHandle } : {}),
+  };
+}
+
+function optionalActorHandle(value: string | undefined): string | undefined {
+  if (value === undefined || value === "") return undefined;
+  if (!/^actor_[A-Za-z0-9_-]{30,220}$/.test(value)) {
+    throw new AiRuntimeReportError(
+      "INVALID_AI_RUNTIME_QUERY",
+      "操作者筛选无效",
+      400,
+    );
+  }
+  return value;
+}
+
+function runId(value: string | undefined): string {
+  const result = optionalIdentifier(value, "Run ID");
+  if (!result) {
+    throw new AiRuntimeReportError(
+      "INVALID_AI_RUNTIME_RUN_ID",
+      "Run ID 无效",
+      400,
+    );
+  }
+  return result;
+}
+
+function optionalIdentifier(
+  value: string | undefined,
+  label: string,
+): string | undefined {
+  if (value === undefined || value === "") return undefined;
+  if (!/^[A-Za-z0-9_-]{1,80}$/.test(value)) {
+    throw new AiRuntimeReportError(
+      "INVALID_AI_RUNTIME_QUERY",
+      `${label} 无效`,
+      400,
+    );
+  }
+  return value;
+}
+
+function keyword(value: string | undefined): string | undefined {
+  const result = value?.trim();
+  if (result && result.length > 100) {
+    throw new AiRuntimeReportError(
+      "INVALID_AI_RUNTIME_QUERY",
+      "搜索关键词最多 100 个字符",
+      400,
+    );
+  }
+  return result || undefined;
+}
+
+async function safe(handler: () => unknown): Promise<unknown> {
+  try {
+    return await handler();
+  } catch (error) {
+    if (error instanceof AiRuntimeReportError) {
+      return Response.json(
+        { error: error.code, message: error.message },
+        { status: error.status },
+      );
+    }
+    throw error;
+  }
+}

package/template/apps/server/src/ai-runtime-report/scope.ts

@@ -0,0 +1,63 @@
+import { isServerScopeContext } from "../data-access/context.js";
+import { buildDataScopeQuerySpecification } from "../data-access/query-specification.js";
+import type { RequestActor } from "../guards.js";
+import type {
+  AiRuntimeReportScope,
+  InternalAiRuntimeRunListItem,
+} from "./contracts.js";
+
+export interface AiRuntimeDepartmentScope {
+  descendants(departmentId: string): Promise<readonly string[]>;
+}
+
+export async function resolveAiRuntimeReportScope(
+  actor: RequestActor,
+  departments: AiRuntimeDepartmentScope,
+): Promise<AiRuntimeReportScope> {
+  if (!isServerScopeContext(actor.scopeContext)) {
+    return { mode: "none", actorIds: [], departmentIds: [] };
+  }
+  const specification = await buildDataScopeQuerySpecification(
+    actor.scopeContext,
+    departments,
+  );
+  if (
+    specification.branches.some(
+      ({ kind }) => kind === "all" || kind === "tenant",
+    )
+  ) {
+    return { mode: "all", actorIds: [], departmentIds: [] };
+  }
+  const actorIds = specification.branches.flatMap((branch) =>
+    branch.kind === "owner" ? [branch.ownerId] : [],
+  );
+  const departmentIds = specification.branches.flatMap((branch) =>
+    branch.kind === "dimension" && branch.dimension === "departmentId"
+      ? [...branch.values]
+      : [],
+  );
+  const hasScope = actorIds.length > 0 || departmentIds.length > 0;
+  return {
+    mode: hasScope ? "bounded" : "none",
+    actorIds: unique(actorIds),
+    departmentIds: unique(departmentIds),
+  };
+}
+
+export function reportScopeAllows(
+  scope: AiRuntimeReportScope,
+  run: Pick<InternalAiRuntimeRunListItem, "actorId"> & {
+    departmentId?: string | null;
+  },
+): boolean {
+  if (scope.mode === "all") return true;
+  if (scope.mode === "none") return false;
+  return Boolean(
+    (run.actorId && scope.actorIds.includes(run.actorId)) ||
+    (run.departmentId && scope.departmentIds.includes(run.departmentId)),
+  );
+}
+
+function unique(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
+}

package/template/apps/server/src/ai-runtime-report/service.test.ts

@@ -0,0 +1,271 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import type {
+  AiRuntimeActorDirectory,
+  AiRuntimeReportRemotePort,
+  AiRuntimeReportScope,
+  InternalAiRuntimeRunDetail,
+} from "./contracts.js";
+import { registerAiRuntimeReportRoutes } from "./routes.js";
+import { AiRuntimeReportError, AiRuntimeReportService } from "./service.js";
+
+const feature = {
+  key: featureKey("system.ai-runtime"),
+  label: "AI Runtime 报表",
+  module: "system.agent",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+};
+
+describe("AI Runtime report service", () => {
+  test("部门范围详情越权统一返回 404", async () => {
+    const runtime = createServerRuntime({}, { featureCatalog: [feature] });
+    const remote = new FakeRemote();
+    remote.detail = runDetail("department-other");
+    const service = createService(runtime, remote);
+
+    await expect(service.run("run_1", context(true))).rejects.toEqual(
+      new AiRuntimeReportError(
+        "AI_RUNTIME_RUN_NOT_FOUND",
+        "Agent Run 不存在",
+        404,
+      ),
+    );
+  });
+
+  test("详情授权后剥离内部 actorId 与 departmentId 并记录审计", async () => {
+    const runtime = createServerRuntime({}, { featureCatalog: [feature] });
+    const remote = new FakeRemote();
+    remote.detail = runDetail("department-a");
+    const service = createService(runtime, remote);
+
+    const result = await service.run("run_1", context(true));
+
+    expect(result.actor).toEqual({
+      handle: "actor_opaque_value",
+      displayName: "用户 A",
+      username: "user-a",
+    });
+    expect(result).not.toHaveProperty("actorId");
+    expect(result).not.toHaveProperty("departmentId");
+    expect(runtime.auditSink.list().at(-1)?.action).toBe(
+      "agent.runtime.run.read",
+    );
+  });
+
+  test("缺少权限时 API fail closed 且不调用远端", async () => {
+    const runtime = createServerRuntime({}, { featureCatalog: [feature] });
+    const remote = new FakeRemote();
+    const service = createService(runtime, remote);
+    const app = new FakeRouteApp();
+    registerAiRuntimeReportRoutes(app, service, runtime, [feature]);
+
+    const result = (await app.invoke("GET", "/system/ai-runtime/summary", {
+      guardContext: context(false),
+      params: {},
+      query: { range: "day" },
+    })) as Response;
+
+    expect(result.status).toBe(403);
+    expect(remote.summaryCalls).toBe(0);
+  });
+
+  test("浏览器只能用可验证 handle 筛选，远端仍接收内部 actorId", async () => {
+    const runtime = createServerRuntime({}, { featureCatalog: [feature] });
+    const remote = new FakeRemote();
+    const service = createService(runtime, remote);
+
+    await service.summary(
+      { range: "day", actorHandle: "actor_opaque_value" },
+      context(true),
+    );
+
+    expect(remote.summaryQuery).toEqual({
+      range: "day",
+      actorId: "user-a",
+    });
+  });
+
+  test("旧 actorId query 被 API 拒绝", async () => {
+    const runtime = createServerRuntime({}, { featureCatalog: [feature] });
+    const remote = new FakeRemote();
+    const service = createService(runtime, remote);
+    const app = new FakeRouteApp();
+    registerAiRuntimeReportRoutes(app, service, runtime, [feature]);
+
+    const result = (await app.invoke("GET", "/system/ai-runtime/summary", {
+      guardContext: context(true),
+      params: {},
+      query: { range: "day", actorId: "user-a" },
+    })) as Response;
+
+    expect(result.status).toBe(400);
+    expect(remote.summaryCalls).toBe(0);
+  });
+
+  test("无法验证或越出范围的 handle fail closed", async () => {
+    const runtime = createServerRuntime({}, { featureCatalog: [feature] });
+    const remote = new FakeRemote();
+    const service = createService(runtime, remote);
+
+    await expect(
+      service.summary(
+        { range: "day", actorHandle: "actor_out_of_scope" },
+        context(true),
+      ),
+    ).rejects.toEqual(
+      new AiRuntimeReportError(
+        "INVALID_AI_RUNTIME_ACTOR",
+        "操作者筛选无效或已超出当前数据范围",
+        400,
+      ),
+    );
+    expect(remote.summaryCalls).toBe(0);
+  });
+});
+
+class FakeRemote implements AiRuntimeReportRemotePort {
+  detail?: InternalAiRuntimeRunDetail;
+  summaryCalls = 0;
+  summaryQuery?: { range: "day" | "month" | "retained"; actorId?: string };
+
+  async summary(
+    query: { range: "day" | "month" | "retained"; actorId?: string },
+    _scope: AiRuntimeReportScope,
+  ) {
+    this.summaryCalls += 1;
+    this.summaryQuery = query;
+    return {
+      generatedAt: "2026-07-31T00:00:00.000Z",
+      reportingAvailableFrom: null,
+      retentionDays: 90,
+      runs: {
+        total: 0,
+        completed: 0,
+        failed: 0,
+        cancelled: 0,
+        inProgress: 0,
+        successRate: null,
+      },
+      cache: {
+        hit: 0,
+        miss: 0,
+        unknown: 0,
+        hitRate: null,
+        tokenRate: null,
+        coverageRate: 0,
+      },
+      tokens: {
+        input: 0,
+        output: 0,
+        cachedInput: 0,
+        reasoning: 0,
+        total: 0,
+        coverageRate: 0,
+      },
+      byModel: [],
+      activity: [],
+    };
+  }
+
+  async runs(
+    _query: {
+      range: "day" | "month" | "retained";
+      actorId?: string;
+      page: number;
+      pageSize: number;
+    },
+    _scope: AiRuntimeReportScope,
+  ) {
+    return { items: [], total: 0, page: 1, pageSize: 20 };
+  }
+
+  async run() {
+    return this.detail;
+  }
+}
+
+const actors: AiRuntimeActorDirectory = {
+  async list(query) {
+    return { items: [], total: 0, ...query };
+  },
+  async resolve(actorIds) {
+    return new Map(
+      actorIds.map((id) => [
+        id,
+        {
+          handle: "actor_opaque_value",
+          displayName: "用户 A",
+          username: "user-a",
+        },
+      ]),
+    );
+  },
+  async resolveHandle(handle) {
+    return handle === "actor_opaque_value" ? "user-a" : undefined;
+  },
+};
+
+function createService(
+  runtime: ReturnType<typeof createServerRuntime>,
+  remote: AiRuntimeReportRemotePort,
+) {
+  return new AiRuntimeReportService(
+    remote,
+    actors,
+    { descendants: async (id) => [id] },
+    runtime,
+  );
+}
+
+function context(permitted: boolean) {
+  return createRequestGuardContext(new Request("http://localhost"), {
+    resolveActor: () => ({
+      id: "reviewer",
+      type: "user",
+      name: "审计员",
+      roleCodes: ["reviewer"],
+      permissionKeys: permitted ? ["system.ai-runtime.read"] : [],
+      scopeContext: buildScopeContext("reviewer", "department-a", [
+        {
+          id: "role-reviewer",
+          code: "reviewer",
+          dataScope: "department",
+          departmentIds: [],
+        },
+      ]),
+    }),
+  });
+}
+
+function runDetail(departmentId: string): InternalAiRuntimeRunDetail {
+  return {
+    runId: "run_1",
+    operationKey: "business.answer",
+    actorId: "user-a",
+    departmentId,
+    status: "completed",
+    startedAt: "2026-07-31T00:00:00.000Z",
+    finishedAt: "2026-07-31T00:00:01.000Z",
+    durationMs: 1_000,
+    attemptCount: 0,
+    models: [],
+    cacheStatus: "unknown",
+    usage: {
+      inputTokens: null,
+      outputTokens: null,
+      cachedInputTokens: null,
+      reasoningTokens: null,
+      totalTokens: null,
+    },
+    releaseId: "release_1",
+    traceId: "trace_1",
+    safeErrorCode: null,
+    attempts: [],
+  };
+}

package/template/apps/server/src/ai-runtime-report/service.ts

@@ -0,0 +1,206 @@
+import type {
+  AiRuntimeActorPage,
+  AiRuntimeReportSummary,
+  AiRuntimeRunDetail,
+  AiRuntimeRunListItem,
+  AiRuntimeRunPage,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import { resourceEvent } from "../system/route-helpers.js";
+import type { createServerRuntime } from "../runtime.js";
+import type {
+  AiRuntimeActorDirectory,
+  AiRuntimeReportQuery,
+  AiRuntimeReportRemotePort,
+  InternalAiRuntimeRunDetail,
+  InternalAiRuntimeRunListItem,
+  PublicAiRuntimeReportQuery,
+} from "./contracts.js";
+import {
+  reportScopeAllows,
+  resolveAiRuntimeReportScope,
+  type AiRuntimeDepartmentScope,
+} from "./scope.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export class AiRuntimeReportService {
+  constructor(
+    private readonly remote: AiRuntimeReportRemotePort,
+    private readonly actors: AiRuntimeActorDirectory,
+    private readonly departments: AiRuntimeDepartmentScope,
+    private readonly runtime: ServerRuntime,
+  ) {}
+
+  async summary(
+    query: PublicAiRuntimeReportQuery,
+    context: RequestGuardContext,
+  ): Promise<AiRuntimeReportSummary> {
+    const [scope, remoteQuery] = await Promise.all([
+      resolveAiRuntimeReportScope(context.actor, this.departments),
+      this.remoteQuery(query, context),
+    ]);
+    const result = await this.remote.summary(remoteQuery, scope);
+    await this.auditReport(context, query, "summary", {
+      resultCount: result.runs.total,
+    });
+    return result;
+  }
+
+  async runs(
+    query: PublicAiRuntimeReportQuery & { page: number; pageSize: number },
+    context: RequestGuardContext,
+  ): Promise<AiRuntimeRunPage> {
+    const [scope, remoteQuery] = await Promise.all([
+      resolveAiRuntimeReportScope(context.actor, this.departments),
+      this.remoteQuery(query, context),
+    ]);
+    const result = await this.remote.runs(
+      { ...remoteQuery, page: query.page, pageSize: query.pageSize },
+      scope,
+    );
+    const items = await this.projectRuns(result.items, context);
+    await this.auditReport(context, query, "runs", {
+      page: result.page,
+      pageSize: result.pageSize,
+      resultCount: items.length,
+      total: result.total,
+    });
+    return { ...result, items };
+  }
+
+  async run(
+    runId: string,
+    context: RequestGuardContext,
+  ): Promise<AiRuntimeRunDetail> {
+    const [scope, raw] = await Promise.all([
+      resolveAiRuntimeReportScope(context.actor, this.departments),
+      this.remote.run(runId),
+    ]);
+    if (!raw || !reportScopeAllows(scope, raw)) {
+      throw new AiRuntimeReportError(
+        "AI_RUNTIME_RUN_NOT_FOUND",
+        "Agent Run 不存在",
+        404,
+      );
+    }
+    const item = await this.projectRunDetail(raw, context);
+    await this.runtime.auditSink.recordCriticalEvent(
+      resourceEvent(
+        context,
+        "agent.runtime.run.read",
+        "agent-runtime-run",
+        runId,
+        {
+          operationKey: raw.operationKey,
+          attemptCount: raw.attemptCount,
+        },
+      ),
+    );
+    return item;
+  }
+
+  async actorPage(
+    query: { q?: string; page: number; pageSize: number },
+    context: RequestGuardContext,
+  ): Promise<AiRuntimeActorPage> {
+    const result = await this.actors.list(query, context.actor);
+    await this.auditReport(context, { range: "retained" }, "actors", {
+      page: result.page,
+      pageSize: result.pageSize,
+      resultCount: result.items.length,
+      total: result.total,
+    });
+    return result;
+  }
+
+  async projectRuns(
+    values: InternalAiRuntimeRunListItem[],
+    context: RequestGuardContext,
+  ): Promise<AiRuntimeRunListItem[]> {
+    const actorMap = await this.actors.resolve(
+      values.flatMap(({ actorId }) => (actorId ? [actorId] : [])),
+      context.actor,
+    );
+    return values.map((value) => projectRun(value, actorMap));
+  }
+
+  async projectRunDetail(
+    value: InternalAiRuntimeRunDetail,
+    context: RequestGuardContext,
+  ): Promise<AiRuntimeRunDetail> {
+    const actorMap = await this.actors.resolve(
+      value.actorId ? [value.actorId] : [],
+      context.actor,
+    );
+    const { actorId, departmentId: _departmentId, ...publicValue } = value;
+    return {
+      ...publicValue,
+      actor: actorId ? (actorMap.get(actorId) ?? null) : null,
+    };
+  }
+
+  async auditReport(
+    context: RequestGuardContext,
+    query: PublicAiRuntimeReportQuery,
+    view: string,
+    metadata: Record<string, unknown>,
+  ): Promise<void> {
+    await this.runtime.auditSink.recordCriticalEvent(
+      resourceEvent(
+        context,
+        "agent.runtime.report.read",
+        "agent-runtime-report",
+        view,
+        {
+          range: query.range,
+          actorFilterApplied: Boolean(query.actorHandle),
+          ...metadata,
+        },
+      ),
+    );
+  }
+
+  private async remoteQuery(
+    query: PublicAiRuntimeReportQuery,
+    context: RequestGuardContext,
+  ): Promise<AiRuntimeReportQuery> {
+    if (!query.actorHandle) return { range: query.range };
+    const actorId = await this.actors.resolveHandle(
+      query.actorHandle,
+      context.actor,
+    );
+    if (!actorId) {
+      throw new AiRuntimeReportError(
+        "INVALID_AI_RUNTIME_ACTOR",
+        "操作者筛选无效或已超出当前数据范围",
+        400,
+      );
+    }
+    return { range: query.range, actorId };
+  }
+}
+
+export class AiRuntimeReportError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+function projectRun(
+  value: InternalAiRuntimeRunListItem,
+  actors: Map<
+    string,
+    { handle: string; displayName: string; username?: string }
+  >,
+): AiRuntimeRunListItem {
+  const { actorId, departmentId: _departmentId, ...publicValue } = value;
+  return {
+    ...publicValue,
+    actor: actorId ? (actors.get(actorId) ?? null) : null,
+  };
+}