create-windy 0.1.0

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

@@ -0,0 +1,173 @@
+import type {
+  ApiPermissionBinding,
+  FeatureFlagDefinition,
+  UserProfile,
+  UserProfileUpdate,
+} from "@windy/shared";
+import { recordMutationAudit } from "../audit/policy.js";
+import type { AuthRepository, AuthUserRecord } from "../auth/repository.js";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { resourceEvent, routeContext } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+const READ_BINDING = profileBinding("GET", "system.profile.read");
+const MANAGE_BINDING = profileBinding("PUT", "system.profile.manage");
+export const profileRouteImplementations = [READ_BINDING, MANAGE_BINDING];
+
+export function registerProfileRoutes(
+  app: Pick<RouteApp, "get" | "put">,
+  repository: AuthRepository,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+): void {
+  const feature = findFeature(features, "system.profile");
+
+  app.get(registrationPath(READ_BINDING), async (rawContext) => {
+    const { guardContext } = routeContext(rawContext);
+    const denied = await guard(runtime, guardContext, READ_BINDING, feature);
+    if (denied) return denied;
+    const user = await repository.findUserByReference(guardContext.actor.id);
+    return user ? toProfile(user) : profileNotFound();
+  });
+
+  app.put(registrationPath(MANAGE_BINDING), async (rawContext) => {
+    const { body, guardContext } = routeContext(rawContext);
+    const denied = await guard(runtime, guardContext, MANAGE_BINDING, feature);
+    if (denied) return denied;
+    const parsed = parseProfile(body);
+    if (!parsed.ok) {
+      return Response.json(
+        { error: "INVALID_USER_PROFILE", message: parsed.message },
+        { status: 400 },
+      );
+    }
+    let updated: AuthUserRecord | undefined;
+    try {
+      updated = await repository.updateUserProfile(
+        guardContext.actor.id,
+        parsed.value,
+        new Date(),
+        guardContext.actor.id,
+      );
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        return Response.json(
+          { error: "PROFILE_CONFLICT", message: "该手机号已被其他账号使用" },
+          { status: 409 },
+        );
+      }
+      throw error;
+    }
+    if (!updated) return profileNotFound();
+    await recordMutationAudit(
+      runtime,
+      "users",
+      resourceEvent(
+        guardContext,
+        "user.profile.update",
+        "user-profile",
+        updated.id,
+        { changedFields: ["displayName", "email", "phone"] },
+      ),
+    );
+    return toProfile(updated);
+  });
+}
+
+function registrationPath(binding: ApiPermissionBinding): string {
+  return binding.path.replace(/^\/api/, "");
+}
+
+async function guard(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  permission: ApiPermissionBinding,
+  feature: FeatureFlagDefinition | undefined,
+): Promise<Response | undefined> {
+  const decision = await evaluateRouteGuards(runtime, context, {
+    permission,
+    feature,
+  });
+  return decision.allowed
+    ? undefined
+    : Response.json(
+        { error: "FORBIDDEN", reason: decision.reason },
+        { status: 403 },
+      );
+}
+
+function profileBinding(
+  method: "GET" | "PUT",
+  permissionKey: string,
+): ApiPermissionBinding {
+  return {
+    method,
+    path: "/api/system/profile",
+    permissionKey,
+    featureKey: "system.profile",
+  };
+}
+
+function toProfile(user: AuthUserRecord): UserProfile {
+  return {
+    id: user.id,
+    username: user.username,
+    displayName: user.displayName,
+    email: user.email,
+    phone: user.phone,
+  };
+}
+
+type ProfileParseResult =
+  | { ok: true; value: UserProfileUpdate }
+  | { ok: false; message: string };
+
+function parseProfile(body: unknown): ProfileParseResult {
+  if (!body || typeof body !== "object") {
+    return { ok: false, message: "请求体必须是对象" };
+  }
+  const input = body as Record<string, unknown>;
+  const displayName = stringField(input.displayName);
+  if (!displayName || displayName.length > 120) {
+    return { ok: false, message: "姓名长度必须为 1 到 120 个字符" };
+  }
+  const email = stringField(input.email);
+  if (email && (email.length > 160 || !isEmail(email))) {
+    return { ok: false, message: "请输入有效的邮箱地址" };
+  }
+  const phone = stringField(input.phone);
+  if (phone && (phone.length > 32 || !/^[+\d][\d\s()-]*$/.test(phone))) {
+    return { ok: false, message: "请输入有效的手机或电话号码" };
+  }
+  return {
+    ok: true,
+    value: {
+      displayName,
+      email: email || undefined,
+      phone: phone || undefined,
+    },
+  };
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function isEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+
+function profileNotFound(): Response {
+  return Response.json({ error: "USER_NOT_FOUND" }, { status: 404 });
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return Boolean(
+    error &&
+    typeof error === "object" &&
+    "code" in error &&
+    error.code === "23505",
+  );
+}

package/template/apps/server/src/request-restriction.ts

@@ -0,0 +1,29 @@
+import type { RequestGuardContext } from "./guards.js";
+import { credentialRestrictedResponse } from "./auth/credential-restriction.js";
+// @windy-module system.license begin
+import type { GuardDecision } from "./guards.js";
+import {
+  evaluateRestrictedHttpRequest,
+  licenseRestrictedResponse,
+} from "./license/restriction.js";
+// @windy-module system.license end
+
+export function restrictedRequestResponse(
+  runtime: {
+    // @windy-module system.license begin
+    recordDecisions(decisions: GuardDecision[]): void;
+    // @windy-module system.license end
+  },
+  context: RequestGuardContext,
+  request: Request,
+): Response | undefined {
+  const credentialResponse = credentialRestrictedResponse(context, request);
+  if (credentialResponse) return credentialResponse;
+  // @windy-module system.license begin
+  const decision = evaluateRestrictedHttpRequest(context, request);
+  if (decision.allowed) return undefined;
+  runtime.recordDecisions([decision]);
+  return licenseRestrictedResponse(context);
+  // @windy-module system.license end
+  return undefined;
+}

package/template/apps/server/src/route-guards.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import { entitlementKey, featureKey } from "@windy/shared";
+import { evaluateAccessGuards } from "./access-guards.js";
+import { createServerRuntime } from "./runtime.js";
+
+const commercialFeature = {
+  key: featureKey("system.audit"),
+  label: "审计日志",
+  module: "system",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+  requiredEntitlement: entitlementKey("capability.audit"),
+};
+
+describe("access guard pipeline", () => {
+  test.each([
+    {
+      name: "缺少 Entitlement 优先拒绝",
+      entitlements: [],
+      featureEnabled: false,
+      permissionKeys: [],
+      expected: "entitlement-not-granted",
+    },
+    {
+      name: "商业授权通过后动态 Feature Flag 可拒绝",
+      entitlements: [entitlementKey("capability.audit")],
+      featureEnabled: false,
+      permissionKeys: [],
+      expected: "feature-disabled",
+    },
+    {
+      name: "前两层通过后 RBAC 可拒绝",
+      entitlements: [entitlementKey("capability.audit")],
+      featureEnabled: true,
+      permissionKeys: [],
+      expected: "missing-permission",
+    },
+    {
+      name: "三层全部通过时放行",
+      entitlements: [entitlementKey("capability.audit")],
+      featureEnabled: true,
+      permissionKeys: ["system.audit.read"],
+      expected: "allowed",
+    },
+  ])(
+    "$name",
+    async ({ entitlements, featureEnabled, permissionKeys, expected }) => {
+      const { runtime, context } = await fixture({
+        entitlements,
+        featureEnabled,
+        permissionKeys,
+      });
+
+      const result = await evaluateAccessGuards(runtime, context, {
+        permission: { permissionKey: "system.audit.read" },
+        feature: commercialFeature,
+      });
+
+      expect(result.decision.reason).toBe(expected);
+    },
+  );
+
+  test("基础功能不需要 License，edition 也不会参与赋权", async () => {
+    const { runtime, context } = await fixture({
+      entitlements: [],
+      featureEnabled: true,
+      permissionKeys: ["system.menu.read"],
+    });
+    const result = await evaluateAccessGuards(runtime, context, {
+      permission: { permissionKey: "system.menu.read" },
+      feature: {
+        ...commercialFeature,
+        key: featureKey("system.rbac"),
+        requiredEntitlement: undefined,
+      },
+    });
+
+    expect(result.decision.reason).toBe("allowed");
+    expect(context.license).toEqual({ entitlements: [] });
+    expect("edition" in context.license!).toBe(false);
+  });
+
+  test("缺少 Entitlement 时不读取 Feature 状态，开关不能绕过商业授权", async () => {
+    let featureResolveCount = 0;
+    const runtime = createServerRuntime(
+      {},
+      {
+        actorResolver: {
+          resolve: () => actor(["system.audit.read"]),
+        },
+        licenseResolver: { resolve: () => ({ entitlements: [] }) },
+        featureResolver: {
+          resolve: () => {
+            featureResolveCount += 1;
+            return { key: "system.audit", enabled: true, visible: "visible" };
+          },
+        },
+      },
+    );
+    const context = await runtime.createGuardContext(
+      new Request("http://local"),
+    );
+
+    const result = await evaluateAccessGuards(runtime, context, {
+      permission: { permissionKey: "system.audit.read" },
+      feature: commercialFeature,
+    });
+
+    expect(result.decision.reason).toBe("entitlement-not-granted");
+    expect(featureResolveCount).toBe(0);
+  });
+});
+
+async function fixture(input: {
+  entitlements: readonly ReturnType<typeof entitlementKey>[];
+  featureEnabled: boolean;
+  permissionKeys: readonly string[];
+}) {
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: { resolve: () => actor(input.permissionKeys) },
+      licenseResolver: {
+        resolve: () => ({ entitlements: [...input.entitlements] }),
+      },
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: input.featureEnabled,
+          visible: "visible",
+        }),
+      },
+    },
+  );
+  const context = await runtime.createGuardContext(new Request("http://local"));
+  return { runtime, context };
+}
+
+function actor(permissionKeys: readonly string[]) {
+  return {
+    id: "user_1",
+    type: "user" as const,
+    name: "测试用户",
+    roleCodes: ["operator"],
+    permissionKeys: [...permissionKeys],
+  };
+}

package/template/apps/server/src/route-guards.ts

@@ -0,0 +1,63 @@
+import type {
+  ApiPermissionBinding,
+  FeatureFlagDefinition,
+} from "@windy/shared";
+import { evaluateAccessGuards } from "./access-guards.js";
+import type { GuardDecision, RequestGuardContext } from "./guards.js";
+import type { createServerRuntime } from "./runtime.js";
+
+type ServerRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "recordDecisions" | "resolveFeature"
+>;
+
+export interface RouteGuardPolicy {
+  permission: ApiPermissionBinding;
+  feature?: FeatureFlagDefinition;
+  restrictedModeAccess?: "backup-export" | "admin-admission";
+}
+
+export async function evaluateRouteGuards(
+  runtime: ServerRuntime,
+  context: RequestGuardContext,
+  policy: RouteGuardPolicy,
+  options: { record?: boolean } = {},
+): Promise<GuardDecision> {
+  return (await evaluateAccessGuards(runtime, context, policy, options))
+    .decision;
+}
+
+export function routeForbidden(reason: string) {
+  return Response.json({ error: "FORBIDDEN", reason }, { status: 403 });
+}
+
+export function findFeature(
+  features: FeatureFlagDefinition[],
+  key: string,
+): FeatureFlagDefinition | undefined {
+  return features.find((feature) => feature.key === key);
+}
+
+export function systemFeatureKeyForResource(resourceName: string): string {
+  const resourceFeatures: Record<string, string> = {
+    agent: "system.agent",
+    audit: "system.audit",
+    license: "system.license",
+    ops: "system.ops",
+    scheduler: "system.scheduler",
+    settings: "system.settings",
+  };
+  return resourceFeatures[resourceName] || "system.rbac";
+}
+
+export function findSystemFeature(
+  features: FeatureFlagDefinition[],
+  resourceName: string,
+): FeatureFlagDefinition | undefined {
+  return findFeature(features, systemFeatureKeyForResource(resourceName));
+}
+
+export function systemFeatureKeyForPermission(permissionKey: string): string {
+  const resource = permissionKey.split(".").at(1) || "";
+  return systemFeatureKeyForResource(resource);
+}

package/template/apps/server/src/runtime-audit-list.test.ts

@@ -0,0 +1,98 @@
+import { randomUUIDv7 } from "bun";
+import { describe, expect, test } from "bun:test";
+import { createServerRuntime } from "./runtime.js";
+
+describe("server runtime audit list", () => {
+  test("无数据库时按动作筛选并优先返回最新事件", async () => {
+    const runtime = createServerRuntime();
+    const baseEvent = {
+      outcome: "success",
+      actor: { id: "user_1", type: "user", name: "测试用户" },
+      target: { type: "features", id: "system.audit" },
+    } as const;
+    runtime.auditSink.recordEvent({
+      ...baseEvent,
+      id: randomUUIDv7(),
+      action: "feature.update",
+      occurredAt: "2026-07-14T01:00:00.000Z",
+    });
+    runtime.auditSink.recordEvent({
+      ...baseEvent,
+      id: randomUUIDv7(),
+      action: "security.denied",
+      outcome: "denied",
+      occurredAt: "2026-07-14T01:01:00.000Z",
+    });
+    runtime.auditSink.recordEvent({
+      ...baseEvent,
+      id: randomUUIDv7(),
+      action: "feature.update",
+      occurredAt: "2026-07-14T01:02:00.000Z",
+    });
+
+    const result = await runtime.listAuditEvents({
+      page: 1,
+      pageSize: 20,
+      action: "feature.update",
+    });
+
+    expect(result.total).toBe(2);
+    expect(result.items.map(({ occurredAt }) => occurredAt)).toEqual([
+      "2026-07-14T01:02:00.000Z",
+      "2026-07-14T01:00:00.000Z",
+    ]);
+  });
+
+  test("无数据库时按操作者和时间范围筛选", async () => {
+    const runtime = createServerRuntime();
+    for (const [actorId, occurredAt] of [
+      ["user_1", "2026-07-13T23:59:59.000Z"],
+      ["user_1", "2026-07-14T01:00:00.000Z"],
+      ["user_2", "2026-07-14T02:00:00.000Z"],
+    ] as const) {
+      runtime.auditSink.recordEvent({
+        id: randomUUIDv7(),
+        action: "feature.update",
+        outcome: "success",
+        actor: { id: actorId, type: "user", name: actorId },
+        occurredAt,
+      });
+    }
+
+    const result = await runtime.listAuditEvents({
+      page: 1,
+      pageSize: 10,
+      actorId: "user_1",
+      occurredAfter: "2026-07-14T00:00:00.000Z",
+    });
+
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0]?.occurredAt).toBe("2026-07-14T01:00:00.000Z");
+  });
+
+  test("无数据库时默认排除平台调度器事件", async () => {
+    const runtime = createServerRuntime();
+    for (const [id, actorId] of [
+      ["audit_user", "user_1"],
+      ["audit_scheduler", "system_scheduler"],
+    ] as const) {
+      runtime.auditSink.recordEvent({
+        id,
+        action: "task.execute",
+        outcome: "success",
+        actor: { id: actorId, type: "service", name: actorId },
+        occurredAt: "2026-07-14T01:00:00.000Z",
+      });
+    }
+
+    const hidden = await runtime.listAuditEvents({ page: 1, pageSize: 10 });
+    const included = await runtime.listAuditEvents({
+      page: 1,
+      pageSize: 10,
+      includeScheduler: true,
+    });
+
+    expect(hidden.items.map(({ id }) => id)).toEqual(["audit_user"]);
+    expect(included.total).toBe(2);
+  });
+});

package/template/apps/server/src/runtime-config.ts

@@ -0,0 +1,11 @@
+export function readSessionTtlSeconds(value: string | undefined): number {
+  return readPositiveInt(value, 60 * 60 * 8);
+}
+
+export function readPositiveInt(
+  value: string | undefined,
+  fallback: number,
+): number {
+  const parsed = value ? Number.parseInt(value, 10) : fallback;
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}

package/template/apps/server/src/runtime-development.ts

@@ -0,0 +1,68 @@
+import type { RequestActor } from "./guards.js";
+// @windy-module work-order begin
+import { exampleDevelopmentPermissionKeys } from "./example-permissions.js";
+// @windy-module work-order end
+import { buildActorScopeContexts } from "./data-access/context.js";
+
+export function developmentAdminActor(): RequestActor {
+  return {
+    id: "user_dev_admin",
+    type: "user",
+    name: "开发管理员",
+    username: "dev-admin",
+    displayName: "开发管理员",
+    roleCodes: ["developer"],
+    ...buildActorScopeContexts("user_dev_admin", "dept_platform", [
+      {
+        id: "role_super_admin",
+        code: "super-admin",
+        dataScope: "all",
+        departmentIds: [],
+      },
+    ]),
+    permissionKeys: [
+      "system.admin.access",
+      "system.menu.read",
+      "system.user.read",
+      "system.user.manage",
+      "system.role.read",
+      "system.role.manage",
+      "system.department.read",
+      "system.department.create",
+      "system.department.manage",
+      "system.menu.manage",
+      "system.dict.read",
+      "system.dict.manage",
+      "system.feature.read",
+      "system.feature.manage",
+      "system.search.read",
+      "system.search.manage",
+      "system.settings.read",
+      "system.settings.manage",
+      "system.watermark.read",
+      "system.watermark.manage",
+      // @windy-module system.license begin
+      "system.license.read",
+      "system.license.manage",
+      // @windy-module system.license end
+      "system.audit.read",
+      "system.agent.read",
+      "system.ops.read",
+      "system.scheduler.read",
+      "system.scheduler.manage",
+      "system.notification.read",
+      "system.notification.manage",
+      "system.bulk-data.manage",
+      "system.storage.read",
+      "system.storage.create",
+      "system.storage.manage",
+      "system.workflow.read",
+      "system.workflow.create",
+      "system.workflow.approve",
+      "system.workflow.manage",
+      // @windy-module work-order begin
+      ...exampleDevelopmentPermissionKeys,
+      // @windy-module work-order end
+    ],
+  };
+}

package/template/apps/server/src/runtime-license.ts

@@ -0,0 +1,50 @@
+import {
+  licenseVersionKey,
+  type EntitlementKey,
+  type LicenseVersionKey,
+} from "@windy/shared";
+
+export interface LicenseEntitlementState {
+  versionKey?: LicenseVersionKey;
+  /** 仅供尚未迁移的业务配置读取。 */
+  entitlements?: EntitlementKey[];
+  status?: "valid" | "expired" | "clock-rollback" | "invalid" | "missing";
+  restricted?: boolean;
+}
+
+export interface LicenseEntitlementResolver {
+  resolve():
+    | Promise<LicenseEntitlementState | undefined>
+    | LicenseEntitlementState
+    | undefined;
+}
+
+export class InMemoryLicenseEntitlementStore {
+  constructor(private readonly state: LicenseEntitlementState) {}
+
+  resolve(): LicenseEntitlementState {
+    return this.state;
+  }
+}
+
+export function developmentLicenseState(
+  env: Record<string, string | undefined>,
+): LicenseEntitlementState {
+  if (env.NODE_ENV === "production") {
+    return { entitlements: [] };
+  }
+  return {
+    versionKey: licenseVersionKey(env.WINDY_LICENSE_VERSION || "advanced"),
+    entitlements: splitEntitlementKeys(env.WINDY_LICENSE_ENTITLEMENTS),
+  };
+}
+
+function splitEntitlementKeys(value: string | undefined): EntitlementKey[] {
+  return value
+    ? value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map((item) => item as EntitlementKey)
+    : [];
+}