create-windy 0.1.0

package/template/apps/server/src/notification/repository.ts

@@ -0,0 +1,160 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  MarkNotificationReadResult,
+  NotificationInboxItem,
+  PageResult,
+  PlatformNotification,
+  PublishNotificationInput,
+} from "@windy/shared";
+import type { RequestActor } from "../guards.js";
+
+export interface NotificationRepository {
+  listInbox(
+    actor: Pick<RequestActor, "id" | "roleCodes">,
+    page: number,
+    pageSize: number,
+  ): Promise<PageResult<NotificationInboxItem>>;
+  listManaged(
+    page: number,
+    pageSize: number,
+    query?: string,
+  ): Promise<PageResult<PlatformNotification>>;
+  publish(
+    input: PublishNotificationInput,
+    actor: RequestActor,
+  ): Promise<PlatformNotification>;
+  markRead(
+    notificationId: string,
+    actor: Pick<RequestActor, "id" | "roleCodes">,
+  ): Promise<MarkNotificationReadResult | undefined>;
+  archive(
+    notificationId: string,
+    actor: RequestActor,
+  ): Promise<PlatformNotification | undefined>;
+}
+
+export class InMemoryNotificationRepository implements NotificationRepository {
+  private readonly notifications = new Map<string, PlatformNotification>();
+  private readonly reads = new Map<string, string>();
+  private readonly sources = new Map<string, string>();
+
+  async listInbox(
+    actor: Pick<RequestActor, "id" | "roleCodes">,
+    page: number,
+    pageSize: number,
+  ) {
+    const items = [...this.notifications.values()]
+      .filter(({ status }) => status === "published")
+      .filter((item) => visibleTo(item, actor))
+      .sort((left, right) => right.publishedAt.localeCompare(left.publishedAt))
+      .map((item) => {
+        const readAt = this.reads.get(readKey(item.id, actor.id));
+        return { ...item, read: Boolean(readAt), readAt };
+      });
+    return pageResult(items, page, pageSize);
+  }
+
+  async listManaged(page: number, pageSize: number, query?: string) {
+    const keyword = query?.trim().toLowerCase();
+    const items = [...this.notifications.values()]
+      .filter((item) =>
+        keyword
+          ? [item.title, item.summary, item.category].some((value) =>
+              value.toLowerCase().includes(keyword),
+            )
+          : true,
+      )
+      .sort((left, right) => right.publishedAt.localeCompare(left.publishedAt));
+    return pageResult(items, page, pageSize);
+  }
+
+  async publish(input: PublishNotificationInput, actor: RequestActor) {
+    const existingId = input.sourceKey
+      ? this.sources.get(input.sourceKey)
+      : undefined;
+    const existing = existingId
+      ? this.notifications.get(existingId)
+      : undefined;
+    if (existing) return existing;
+    const now = new Date().toISOString();
+    const notification: PlatformNotification = {
+      id: randomUUIDv7(),
+      ...input,
+      status: "published",
+      publishedAt: now,
+      createdAt: now,
+      createdBy: actor.id,
+      updatedAt: now,
+      updatedBy: actor.id,
+    };
+    this.notifications.set(notification.id, notification);
+    if (input.sourceKey) this.sources.set(input.sourceKey, notification.id);
+    return notification;
+  }
+
+  async markRead(
+    notificationId: string,
+    actor: Pick<RequestActor, "id" | "roleCodes">,
+  ) {
+    const notification = this.notifications.get(notificationId);
+    if (
+      !notification ||
+      notification.status !== "published" ||
+      !visibleTo(notification, actor)
+    )
+      return undefined;
+    const key = readKey(notificationId, actor.id);
+    const existing = this.reads.get(key);
+    if (existing)
+      return { success: true, alreadyRead: true, readAt: existing } as const;
+    const readAt = new Date().toISOString();
+    this.reads.set(key, readAt);
+    return { success: true, alreadyRead: false, readAt } as const;
+  }
+
+  async archive(notificationId: string, actor: RequestActor) {
+    const current = this.notifications.get(notificationId);
+    if (!current || current.status === "archived") return undefined;
+    const now = new Date().toISOString();
+    const archived: PlatformNotification = {
+      ...current,
+      status: "archived",
+      updatedAt: now,
+      updatedBy: actor.id,
+      archivedAt: now,
+      archivedBy: actor.id,
+    };
+    this.notifications.set(notificationId, archived);
+    return archived;
+  }
+}
+
+function visibleTo(
+  item: PlatformNotification,
+  actor: Pick<RequestActor, "id" | "roleCodes">,
+) {
+  const roles = item.recipientRoleCodes || [];
+  return (
+    (!item.recipientUserId && !roles.length) ||
+    item.recipientUserId === actor.id ||
+    roles.some((role) => actor.roleCodes.includes(role))
+  );
+}
+
+function readKey(notificationId: string, userId: string) {
+  return `${notificationId}:${userId}`;
+}
+
+function pageResult<T>(
+  items: T[],
+  page: number,
+  pageSize: number,
+): PageResult<T> {
+  const start = (page - 1) * pageSize;
+  return {
+    items: items.slice(start, start + pageSize),
+    total: items.length,
+    page,
+    pageSize,
+  };
+}

package/template/apps/server/src/notification/routes.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { InMemoryNotificationRepository } from "./repository.js";
+import { registerNotificationRoutes } from "./routes.js";
+
+class FakeRouteApp {
+  readonly handlers = new Map<string, (context: unknown) => unknown>();
+
+  get(path: string, handler: (context: unknown) => unknown) {
+    this.handlers.set(`GET ${path}`, handler);
+  }
+
+  post(path: string, handler: (context: unknown) => unknown) {
+    this.handlers.set(`POST ${path}`, handler);
+  }
+
+  delete(path: string, handler: (context: unknown) => unknown) {
+    this.handlers.set(`DELETE ${path}`, handler);
+  }
+
+  invoke(method: string, path: string, context: unknown) {
+    const handler = this.handlers.get(`${method} ${path}`);
+    if (!handler) throw new Error(`未注册路由 ${method} ${path}`);
+    return handler(context);
+  }
+}
+
+describe("站内通知闭环", () => {
+  test("通知列表共享默认 10 条和 100 条服务端上限", async () => {
+    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+    const app = new FakeRouteApp();
+    registerNotificationRoutes(
+      app,
+      new InMemoryNotificationRepository(),
+      runtime,
+      createFoundationSnapshot().features,
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/notifications", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+
+    const listed = (await app.invoke("GET", "/system/notifications", {
+      guardContext,
+      params: {},
+      query: {},
+    })) as { pageSize: number };
+    expect(listed.pageSize).toBe(10);
+
+    const response = (await app.invoke("GET", "/system/notifications", {
+      guardContext,
+      params: {},
+      query: { pageSize: "101" },
+    })) as Response;
+    expect(response.status).toBe(400);
+  });
+
+  test("管理员发布后用户可读取正文并幂等标记已读，归档后不再进入收件箱", async () => {
+    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+    const repository = new InMemoryNotificationRepository();
+    const app = new FakeRouteApp();
+    registerNotificationRoutes(
+      app,
+      repository,
+      runtime,
+      createFoundationSnapshot().features,
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/notifications", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+
+    const published = (await app.invoke("POST", "/system/notifications", {
+      guardContext,
+      params: {},
+      query: {},
+      body: {
+        title: "维护通知",
+        summary: "今晚进行例行维护",
+        content: "维护窗口为 22:00 至 22:30，请提前保存工作。",
+        category: "系统",
+      },
+    })) as { id: string; status: string };
+    const inbox = (await app.invoke("GET", "/notifications", {
+      guardContext,
+      params: {},
+      query: {},
+    })) as { items: Array<{ id: string; content: string; read: boolean }> };
+    const firstRead = await app.invoke("POST", "/notifications/:id/read", {
+      guardContext,
+      params: { id: published.id },
+      query: {},
+    });
+    const secondRead = await app.invoke("POST", "/notifications/:id/read", {
+      guardContext,
+      params: { id: published.id },
+      query: {},
+    });
+
+    expect(published.status).toBe("published");
+    expect(inbox.items[0]).toMatchObject({
+      id: published.id,
+      content: "维护窗口为 22:00 至 22:30，请提前保存工作。",
+      read: false,
+    });
+    expect(firstRead).toMatchObject({ success: true, alreadyRead: false });
+    expect(secondRead).toMatchObject({ success: true, alreadyRead: true });
+
+    await app.invoke("DELETE", "/system/notifications/:id", {
+      guardContext,
+      params: { id: published.id },
+      query: {},
+    });
+    const emptyInbox = (await app.invoke("GET", "/notifications", {
+      guardContext,
+      params: {},
+      query: {},
+    })) as { items: unknown[] };
+    expect(emptyInbox.items).toHaveLength(0);
+    expect(runtime.auditSink.list().map(({ action }) => action)).toEqual([
+      "notification.publish",
+      "notification.read",
+      "notification.archive",
+    ]);
+  });
+
+  test("匿名用户不能读取通知", async () => {
+    const runtime = createServerRuntime();
+    const app = new FakeRouteApp();
+    registerNotificationRoutes(
+      app,
+      new InMemoryNotificationRepository(),
+      runtime,
+      createFoundationSnapshot().features,
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/notifications"),
+    );
+
+    const response = (await app.invoke("GET", "/notifications", {
+      guardContext,
+      params: {},
+      query: {},
+    })) as Response;
+
+    expect(response.status).toBe(403);
+  });
+});

package/template/apps/server/src/notification/routes.ts

@@ -0,0 +1,185 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  AuditActionType,
+  FeatureFlagDefinition,
+  HttpMethod,
+  PublishNotificationInput,
+} from "@windy/shared";
+import type { RequestGuardContext } from "../guards.js";
+import { evaluateRouteGuards, findSystemFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { NotificationRepository } from "./repository.js";
+import { parsePagination } from "../pagination.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+type RouteContext = {
+  body?: unknown;
+  guardContext: RequestGuardContext;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+};
+
+interface NotificationRouteApp {
+  get(path: string, handler: (context: unknown) => unknown): unknown;
+  post(path: string, handler: (context: unknown) => unknown): unknown;
+  delete(path: string, handler: (context: unknown) => unknown): unknown;
+}
+
+export function registerNotificationRoutes(
+  app: NotificationRouteApp,
+  repository: NotificationRepository,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[] = [],
+) {
+  const feature = findSystemFeature(features, "notification");
+
+  app.get("/notifications", (raw) =>
+    guarded(raw, "GET", "read", feature, runtime, async (context) => {
+      const pagination = parsePagination(context.query);
+      if (pagination instanceof Response) return pagination;
+      return repository.listInbox(
+        context.guardContext.actor,
+        pagination.page,
+        pagination.pageSize,
+      );
+    }),
+  );
+  app.post("/notifications/:id/read", (raw) =>
+    guarded(raw, "POST", "read", feature, runtime, async (context) => {
+      const id = context.params.id || "";
+      const result = await repository.markRead(id, context.guardContext.actor);
+      if (!result) return notFound(id);
+      if (!result.alreadyRead) {
+        runtime.auditSink.recordEvent(event(context, "notification.read", id));
+      }
+      return result;
+    }),
+  );
+  app.get("/system/notifications", (raw) =>
+    guarded(raw, "GET", "manage", feature, runtime, async (context) => {
+      const pagination = parsePagination(context.query);
+      if (pagination instanceof Response) return pagination;
+      return repository.listManaged(
+        pagination.page,
+        pagination.pageSize,
+        context.query.q,
+      );
+    }),
+  );
+  app.post("/system/notifications", (raw) =>
+    guarded(raw, "POST", "manage", feature, runtime, async (context) => {
+      const input = parsePublishInput(context.body);
+      if (input instanceof Response) return input;
+      const notification = await repository.publish(
+        input,
+        context.guardContext.actor,
+      );
+      await runtime.auditSink.recordCriticalEvent(
+        event(context, "notification.publish", notification.id),
+      );
+      return notification;
+    }),
+  );
+  app.delete("/system/notifications/:id", (raw) =>
+    guarded(raw, "DELETE", "manage", feature, runtime, async (context) => {
+      const id = context.params.id || "";
+      const notification = await repository.archive(
+        id,
+        context.guardContext.actor,
+      );
+      if (!notification) return notFound(id);
+      await runtime.auditSink.recordCriticalEvent(
+        event(context, "notification.archive", id),
+      );
+      return notification;
+    }),
+  );
+  return app;
+}
+
+async function guarded(
+  raw: unknown,
+  method: HttpMethod,
+  action: "read" | "manage",
+  feature: FeatureFlagDefinition | undefined,
+  runtime: ServerRuntime,
+  handler: (context: RouteContext) => unknown,
+) {
+  const context = raw as RouteContext;
+  const decision = await evaluateRouteGuards(runtime, context.guardContext, {
+    permission: {
+      method,
+      path: "/api/notifications",
+      permissionKey: `system.notification.${action}`,
+    },
+    feature,
+  });
+  return decision.allowed
+    ? handler(context)
+    : Response.json(
+        { error: "FORBIDDEN", reason: decision.reason },
+        { status: 403 },
+      );
+}
+
+function parsePublishInput(body: unknown): PublishNotificationInput | Response {
+  const value =
+    body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  const input = {
+    title: text(value.title),
+    summary: text(value.summary),
+    content: text(value.content),
+    category: text(value.category),
+  };
+  if (!input.title || !input.summary || !input.content || !input.category) {
+    return Response.json(
+      {
+        error: "INVALID_NOTIFICATION",
+        message: "标题、摘要、正文和分类均不能为空",
+      },
+      { status: 400 },
+    );
+  }
+  if (
+    input.title.length > 120 ||
+    input.summary.length > 240 ||
+    input.content.length > 10_000 ||
+    input.category.length > 40
+  ) {
+    return Response.json(
+      { error: "INVALID_NOTIFICATION", message: "通知内容超过长度限制" },
+      { status: 400 },
+    );
+  }
+  return input;
+}
+
+function event(context: RouteContext, action: AuditActionType, id: string) {
+  return {
+    id: randomUUIDv7(),
+    action,
+    outcome: "success" as const,
+    actor: {
+      id: context.guardContext.actor.id,
+      type:
+        context.guardContext.actor.type === "anonymous"
+          ? ("user" as const)
+          : context.guardContext.actor.type,
+      name: context.guardContext.actor.name,
+    },
+    target: { type: "notification", id },
+    requestId: context.guardContext.requestId,
+    occurredAt: new Date().toISOString(),
+  };
+}
+
+function notFound(id: string) {
+  return Response.json(
+    { error: "NOT_FOUND", resource: "notification", id },
+    { status: 404 },
+  );
+}
+
+function text(value: unknown) {
+  return typeof value === "string" ? value.trim() : "";
+}

package/template/apps/server/src/observability/bootstrap.ts

@@ -0,0 +1,56 @@
+import type { AuditWriteStatus } from "../audit/contracts.js";
+import type { FeatureManifestSyncResult } from "../feature/manifest-feature-repository.js";
+import type { RouteApp } from "../system/route-types.js";
+import {
+  HttpObservability,
+  type StructuredRequestLogger,
+} from "./http-observability.js";
+import { RuntimeMetrics } from "./metrics.js";
+import { createReadinessProbe } from "./readiness.js";
+import { registerObservabilityRoutes } from "./routes.js";
+
+export interface PlatformObservabilityOptions {
+  databaseCheck?: () => Promise<void>;
+  databaseRequired: boolean;
+  auditStatus(): AuditWriteStatus;
+  logger: StructuredRequestLogger;
+}
+
+export function createPlatformObservability(
+  options: PlatformObservabilityOptions,
+) {
+  const metrics = new RuntimeMetrics();
+  const readiness = createReadinessProbe(options);
+  const http = new HttpObservability(metrics, options.logger);
+  return {
+    http,
+    metrics,
+    register(app: Pick<RouteApp, "get">) {
+      registerObservabilityRoutes(app, readiness, metrics);
+    },
+  };
+}
+
+export function logPlatformStartup(
+  logger: StructuredRequestLogger,
+  input: {
+    featureSync: FeatureManifestSyncResult;
+    persistenceEnabled: boolean;
+    port: number;
+  },
+): void {
+  if (input.persistenceEnabled) {
+    logger.info(
+      { event: "persistence.enabled", authority: "postgresql" },
+      "PostgreSQL 持久化已启用",
+    );
+  }
+  logger.info(
+    { event: "feature.manifest.synchronized", ...input.featureSync },
+    "Feature Manifest 已同步",
+  );
+  logger.info(
+    { event: "service.started", component: "windy-server", port: input.port },
+    "服务已启动",
+  );
+}

package/template/apps/server/src/observability/http-observability.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import type { RequestGuardContext } from "../guards.js";
+import { HttpObservability, responseStatus } from "./http-observability.js";
+import { RuntimeMetrics } from "./metrics.js";
+
+const context: RequestGuardContext = {
+  requestId: "request-safe",
+  startedAt: new Date().toISOString(),
+  actor: {
+    id: "user-secret-id",
+    type: "user",
+    name: "测试员",
+    roleCodes: [],
+    permissionKeys: [],
+  },
+};
+
+describe("HTTP observability", () => {
+  test("结构化日志只记录关联、方法、状态、耗时和 Actor 类型", () => {
+    const records: Record<string, unknown>[] = [];
+    const metrics = new RuntimeMetrics();
+    const observer = new HttpObservability(metrics, {
+      info(fields) {
+        records.push(fields);
+      },
+    });
+    const observation = observer.begin("GET");
+    observer.complete({
+      request: new Request("https://example.test/api/search?q=secret-value"),
+      guardContext: context,
+      observation,
+      responseValue: new Response(null, { status: 404 }),
+    });
+
+    expect(records).toEqual([
+      expect.objectContaining({
+        event: "http.request.completed",
+        requestId: "request-safe",
+        method: "GET",
+        statusCode: 404,
+        actorType: "user",
+      }),
+    ]);
+    const serialized = JSON.stringify(records);
+    expect(serialized).not.toContain("secret-value");
+    expect(serialized).not.toContain("user-secret-id");
+  });
+
+  test("优先使用真实 Response 状态", () => {
+    expect(responseStatus(new Response(null, { status: 503 }), 200)).toBe(503);
+    expect(responseStatus({}, 201)).toBe(201);
+  });
+});

package/template/apps/server/src/observability/http-observability.ts

@@ -0,0 +1,54 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { RequestObservation, RuntimeMetrics } from "./metrics.js";
+
+export interface StructuredRequestLogger {
+  info(fields: Record<string, unknown>, message: string): void;
+}
+
+export class HttpObservability {
+  constructor(
+    private readonly metrics: RuntimeMetrics,
+    private readonly logger: StructuredRequestLogger,
+  ) {}
+
+  begin(method: string): RequestObservation {
+    return this.metrics.beginRequest(method);
+  }
+
+  complete(input: {
+    request: Request;
+    guardContext: RequestGuardContext;
+    observation: RequestObservation;
+    responseValue: unknown;
+    status?: number | string;
+  }): void {
+    const statusCode = responseStatus(input.responseValue, input.status);
+    const durationMs = this.metrics.finishRequest(
+      input.observation,
+      statusCode,
+    );
+    this.logger.info(
+      {
+        event: "http.request.completed",
+        requestId: input.guardContext.requestId,
+        method: input.request.method,
+        statusCode,
+        durationMs: Number(durationMs.toFixed(3)),
+        actorType: input.guardContext.actor.type,
+      },
+      "HTTP 请求完成",
+    );
+  }
+}
+
+export function responseStatus(
+  responseValue: unknown,
+  configured?: number | string,
+): number {
+  if (responseValue instanceof Response) return responseValue.status;
+  if (typeof configured === "number") return configured;
+  const parsed = typeof configured === "string" ? Number(configured) : 200;
+  return Number.isInteger(parsed) && parsed >= 100 && parsed <= 599
+    ? parsed
+    : 200;
+}

package/template/apps/server/src/observability/metrics.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { RuntimeMetrics } from "./metrics.js";
+
+describe("RuntimeMetrics", () => {
+  test("输出无 URL、资源 ID 和请求内容标签的 Prometheus 指标", () => {
+    const metrics = new RuntimeMetrics();
+    const observation = metrics.beginRequest("GET");
+    metrics.finishRequest(observation, 201);
+    metrics.observeSchedulerTick({
+      scheduled: 2,
+      retried: 1,
+      blocked: 0,
+      failed: 1,
+    });
+
+    const output = metrics.render();
+    expect(output).toContain(
+      'windy_http_requests_total{method="GET",status_class="2xx"} 1',
+    );
+    expect(output).toContain(
+      'windy_scheduler_runs_total{outcome="scheduled"} 2',
+    );
+    expect(output).not.toContain("path=");
+    expect(output).not.toContain("requestId");
+  });
+
+  test("同一次 observation 只完成一次", () => {
+    const metrics = new RuntimeMetrics();
+    const observation = metrics.beginRequest("POST");
+    metrics.finishRequest(observation, 500);
+    metrics.finishRequest(observation, 500);
+    expect(metrics.render()).toContain(
+      'windy_http_requests_total{method="POST",status_class="5xx"} 1',
+    );
+  });
+});