create-windy 0.1.0

package/template/apps/server/src/feature/manifest-feature-repository.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from "bun:test";
+import {
+  entitlementKey,
+  featureKey,
+  licenseVersionKey,
+  type FeatureFlagDefinition,
+} from "@windy/shared";
+import { InMemoryEntityRepository } from "../system/repository.js";
+import type { ManagedFeature } from "../system/entities.js";
+import { ManifestFeatureRepository } from "./manifest-feature-repository.js";
+
+const actor = {
+  id: "user_admin",
+  type: "user" as const,
+  name: "管理员",
+  roleCodes: ["developer"],
+  permissionKeys: ["system.feature.manage"],
+};
+
+describe("ManifestFeatureRepository", () => {
+  test("幂等注册 Manifest，并保留移除 Key 的历史状态", async () => {
+    const repository = createRepository();
+    const original = feature("system.reports");
+
+    expect(await repository.syncManifest([original])).toMatchObject({
+      created: 1,
+      metadataUpdated: 0,
+      archived: 0,
+    });
+    expect(await repository.syncManifest([original])).toMatchObject({
+      created: 0,
+      metadataUpdated: 0,
+      archived: 0,
+      unchanged: 1,
+    });
+
+    await repository.updateState(
+      original.key,
+      { enabled: false, visible: "hidden" },
+      actor,
+    );
+    const renamed = feature("system.analytics");
+    const renameResult = await repository.syncManifest([renamed]);
+
+    expect(renameResult).toMatchObject({ created: 1, archived: 1 });
+    expect(await repository.resolve(original.key)).toBeUndefined();
+    expect(await repository.all({ includeDeleted: true })).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          key: original.key,
+          enabled: false,
+          visible: "hidden",
+          status: "archived",
+        }),
+        expect.objectContaining({ key: renamed.key, status: "active" }),
+      ]),
+    );
+  });
+
+  test("同步只刷新 Manifest 元数据，不覆盖数据库开关状态", async () => {
+    const repository = createRepository();
+    const original = feature("system.reports");
+    await repository.syncManifest([original]);
+    await repository.updateState(original.key, { enabled: false }, actor);
+
+    const result = await repository.syncManifest([
+      {
+        ...original,
+        label: "经营分析",
+        stage: "stable",
+        requiredEntitlement: entitlementKey("capability.analytics"),
+      },
+    ]);
+    const current = await repository.get(original.key);
+
+    expect(result.metadataUpdated).toBe(1);
+    expect(current).toMatchObject({
+      label: "经营分析",
+      stage: "stable",
+      enabled: false,
+      visible: "visible",
+      requiredEntitlement: "capability.analytics",
+    });
+  });
+
+  test("重复 Manifest Key 会阻止启动同步", async () => {
+    const repository = createRepository();
+    const duplicate = feature("system.reports");
+
+    await expect(
+      repository.syncManifest([duplicate, { ...duplicate }]),
+    ).rejects.toThrow("重复 Key");
+  });
+
+  test("默认沿用 Manifest 的 License 范围", async () => {
+    const repository = createRepository();
+    const original = {
+      ...feature("system.reports"),
+      allowedLicenseVersions: ["advanced"],
+    } as FeatureFlagDefinition;
+    await repository.syncManifest([original]);
+
+    expect(await repository.get(original.key)).toMatchObject({
+      allowedLicenseVersions: ["advanced"],
+    });
+    expect((await repository.list()).items[0]).toMatchObject({
+      allowedLicenseVersions: ["advanced"],
+      licenseVersionSource: "manifest",
+    });
+  });
+
+  test("数据库覆盖 License 范围并可恢复 Manifest 默认", async () => {
+    const repository = createRepository();
+    const original = {
+      ...feature("system.reports"),
+      allowedLicenseVersions: [licenseVersionKey("advanced")],
+    };
+    await repository.syncManifest([original]);
+
+    await repository.updateState(
+      original.key,
+      { licenseVersionOverride: [licenseVersionKey("standard")] },
+      actor,
+    );
+
+    expect(await repository.get(original.key)).toMatchObject({
+      allowedLicenseVersions: ["standard"],
+      manifestAllowedLicenseVersions: ["advanced"],
+      licenseVersionOverride: ["standard"],
+      licenseVersionSource: "override",
+    });
+    expect(await repository.resolve(original.key)).toMatchObject({
+      allowedLicenseVersions: ["standard"],
+    });
+
+    await repository.updateState(
+      original.key,
+      { licenseVersionOverride: null },
+      actor,
+    );
+
+    expect(await repository.get(original.key)).toMatchObject({
+      allowedLicenseVersions: ["advanced"],
+      licenseVersionSource: "manifest",
+    });
+  });
+
+  test("空覆盖表示基础能力，不限制 License 版本", async () => {
+    const repository = createRepository();
+    const original = {
+      ...feature("system.reports"),
+      allowedLicenseVersions: [licenseVersionKey("advanced")],
+    };
+    await repository.syncManifest([original]);
+    await repository.updateState(
+      original.key,
+      { licenseVersionOverride: [] },
+      actor,
+    );
+
+    expect(await repository.get(original.key)).toMatchObject({
+      licenseVersionOverride: [],
+      licenseVersionSource: "override",
+    });
+    expect((await repository.get(original.key))?.allowedLicenseVersions).toBe(
+      undefined,
+    );
+  });
+});
+
+function createRepository() {
+  return new ManifestFeatureRepository(
+    new InMemoryEntityRepository<ManagedFeature>(),
+  );
+}
+
+function feature(key: string): FeatureFlagDefinition {
+  return {
+    key: featureKey(key),
+    label: "报表中心",
+    module: "system",
+    description: "经营数据报表。",
+    enabled: true,
+    visible: "visible",
+    stage: "beta",
+  };
+}

package/template/apps/server/src/feature/manifest-feature-repository.ts

@@ -0,0 +1,200 @@
+import type { FeatureFlagDefinition } from "@windy/shared";
+import type { FeatureFlagRuntimeState } from "../runtime.js";
+import type { RequestActor } from "../guards.js";
+import type { ManagedFeature } from "../system/entities.js";
+import type {
+  EntityListQuery,
+  EntityRepository,
+} from "../system/repository.js";
+
+const systemActor: RequestActor = {
+  id: "system",
+  type: "service",
+  name: "Feature Manifest 同步",
+  roleCodes: ["system"],
+  permissionKeys: [],
+};
+
+export interface FeatureManifestSyncResult {
+  created: number;
+  metadataUpdated: number;
+  archived: number;
+  unchanged: number;
+}
+
+export class ManifestFeatureRepository {
+  private definitionsByKey = new Map<string, FeatureFlagDefinition>();
+
+  constructor(private readonly repository: EntityRepository<ManagedFeature>) {}
+
+  async list(
+    query?: EntityListQuery,
+    searchFields?: Array<keyof ManagedFeature>,
+  ) {
+    const page = await this.repository.list(query, searchFields);
+    return {
+      ...page,
+      items: page.items.map((item) => this.withManifest(item)),
+    };
+  }
+
+  async all(
+    query?: EntityListQuery,
+    searchFields?: Array<keyof ManagedFeature>,
+  ) {
+    return (await this.repository.all(query, searchFields)).map((item) =>
+      this.withManifest(item),
+    );
+  }
+
+  async get(key: string) {
+    const item = await this.repository.get(key);
+    return item ? this.withManifest(item) : undefined;
+  }
+
+  async resolve(key: string): Promise<FeatureFlagRuntimeState | undefined> {
+    const feature = await this.repository.get(key);
+    const effective = feature ? this.withManifest(feature) : undefined;
+    return effective?.status === "active"
+      ? {
+          key: effective.key,
+          enabled: effective.enabled,
+          visible: effective.visible,
+          allowedLicenseVersions: effective.allowedLicenseVersions,
+        }
+      : undefined;
+  }
+
+  async updateState(
+    key: string,
+    input: Partial<
+      Pick<ManagedFeature, "enabled" | "visible" | "licenseVersionOverride">
+    >,
+    actor: RequestActor,
+  ): Promise<ManagedFeature | undefined> {
+    const current = await this.repository.get(key);
+    if (!current || current.status !== "active") return undefined;
+    const patch: Partial<ManagedFeature> = {};
+    if (typeof input.enabled === "boolean") patch.enabled = input.enabled;
+    if (input.visible === "visible" || input.visible === "hidden") {
+      patch.visible = input.visible;
+    }
+    if (input.licenseVersionOverride !== undefined) {
+      patch.licenseVersionOverride = input.licenseVersionOverride;
+    }
+    const updated = await this.repository.update(key, patch, actor);
+    return updated ? this.withManifest(updated) : undefined;
+  }
+
+  async syncManifest(
+    definitions: FeatureFlagDefinition[],
+  ): Promise<FeatureManifestSyncResult> {
+    assertUniqueKeys(definitions);
+    this.definitionsByKey = new Map(
+      definitions.map((definition) => [definition.key, definition]),
+    );
+    const existing = await this.repository.all({ includeDeleted: true });
+    const existingByKey = new Map(existing.map((item) => [item.key, item]));
+    const manifestKeys = new Set<string>(
+      definitions.map((definition) => definition.key),
+    );
+    const result: FeatureManifestSyncResult = {
+      created: 0,
+      metadataUpdated: 0,
+      archived: 0,
+      unchanged: 0,
+    };
+
+    for (const definition of definitions) {
+      const current = existingByKey.get(definition.key);
+      if (!current) {
+        await this.repository.create(newFeature(definition), systemActor);
+        result.created += 1;
+        continue;
+      }
+      const patch = manifestMetadataPatch(current, definition);
+      if (Object.keys(patch).length === 0) {
+        result.unchanged += 1;
+        continue;
+      }
+      await this.repository.update(current.id, patch, systemActor);
+      result.metadataUpdated += 1;
+    }
+
+    for (const current of existing) {
+      if (manifestKeys.has(current.key) || current.status === "archived")
+        continue;
+      await this.repository.update(
+        current.id,
+        { status: "archived" },
+        systemActor,
+      );
+      result.archived += 1;
+    }
+
+    return result;
+  }
+
+  private withManifest(item: ManagedFeature): ManagedFeature {
+    const manifestAllowedLicenseVersions = this.definitionsByKey.get(
+      item.key,
+    )?.allowedLicenseVersions;
+    const hasOverride = Array.isArray(item.licenseVersionOverride);
+    const override = item.licenseVersionOverride || [];
+    return {
+      ...item,
+      allowedLicenseVersions: hasOverride
+        ? override.length
+          ? override
+          : undefined
+        : manifestAllowedLicenseVersions,
+      manifestAllowedLicenseVersions,
+      licenseVersionSource: hasOverride ? "override" : "manifest",
+    };
+  }
+}
+
+function newFeature(
+  definition: FeatureFlagDefinition,
+): Partial<ManagedFeature> {
+  return {
+    ...definition,
+    id: definition.key,
+    status: "active",
+  };
+}
+
+function manifestMetadataPatch(
+  current: ManagedFeature,
+  definition: FeatureFlagDefinition,
+): Partial<ManagedFeature> {
+  const patch: Partial<ManagedFeature> = {};
+  if (current.label !== definition.label) patch.label = definition.label;
+  if (current.module !== definition.module) patch.module = definition.module;
+  if ((current.description ?? undefined) !== definition.description) {
+    patch.description = definition.description;
+  }
+  if (current.stage !== definition.stage) patch.stage = definition.stage;
+  if (current.requiredEntitlement !== definition.requiredEntitlement) {
+    patch.requiredEntitlement = definition.requiredEntitlement;
+  }
+  if (!sameArray(current.dependencies, definition.dependencies)) {
+    patch.dependencies = definition.dependencies || [];
+  }
+  if (current.status !== "active") patch.status = "active";
+  return patch;
+}
+
+function sameArray(left?: string[], right?: string[]): boolean {
+  return JSON.stringify(left || []) === JSON.stringify(right || []);
+}
+
+function assertUniqueKeys(definitions: FeatureFlagDefinition[]): void {
+  const seen = new Set<string>();
+  for (const definition of definitions) {
+    if (seen.has(definition.key)) {
+      throw new Error(`Feature Manifest 存在重复 Key：${definition.key}`);
+    }
+    seen.add(definition.key);
+  }
+}

package/template/apps/server/src/feature/routes.authorization.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime, type AuditEventWriter } from "../runtime.js";
+import type { RouteApp } from "../system/routes.js";
+import { createSystemRepositories } from "../system/seed.js";
+import { registerFeatureFlagRoutes } from "./routes.js";
+
+class FakeRouteApp implements RouteApp {
+  readonly handlers = new Map<string, (context: unknown) => unknown>();
+
+  get(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`GET ${path}`, handler);
+  }
+
+  post(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`POST ${path}`, handler);
+  }
+
+  put(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`PUT ${path}`, handler);
+  }
+
+  delete(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`DELETE ${path}`, handler);
+  }
+
+  invoke(method: string, path: string, context: unknown): unknown {
+    const handler = this.handlers.get(`${method} ${path}`);
+    if (!handler) throw new Error(`未注册路由 ${method} ${path}`);
+    return handler(context);
+  }
+}
+
+describe("Feature Flag 管理授权", () => {
+  test.each(["super-admin", "developer"])(
+    "%s 角色可修改开关并写入审计",
+    async (roleCode) => {
+      const fixture = await createFixture(actor([roleCode], true));
+      const item = await updateFeature(fixture, { enabled: false });
+
+      expect(item).toMatchObject({ key: "system.profile", enabled: false });
+      expect(fixture.runtime.auditSink.list()).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            action: "feature.update",
+            actor: expect.objectContaining({ id: `user_${roleCode}` }),
+            target: expect.objectContaining({
+              type: "features",
+              id: "system.profile",
+            }),
+          }),
+        ]),
+      );
+    },
+  );
+
+  test("自定义管理员具有 manage 权限即可修改开关", async () => {
+    const fixture = await createFixture(actor(["admin"], true));
+    const item = await updateFeature(fixture, {
+      enabled: false,
+    });
+
+    expect(item).toMatchObject({ key: "system.profile", enabled: false });
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .some((event) => event.action === "feature.update"),
+    ).toBe(true);
+  });
+
+  test("普通用户直接调用更新 API 会在权限层返回 403", async () => {
+    const fixture = await createFixture(actor(["operator"], false));
+    const response = (await updateFeature(fixture, {
+      enabled: false,
+    })) as Response;
+
+    expect(response.status).toBe(403);
+    await expect(response.json()).resolves.toMatchObject({
+      error: "FORBIDDEN",
+      reason: "missing-permission",
+    });
+  });
+
+  test("RBAC Feature 已关闭时开发角色仍可进入控制面恢复开关", async () => {
+    const fixture = await createFixture(actor(["developer"], true));
+    await fixture.repositories.features.updateState(
+      "system.rbac",
+      { enabled: false },
+      fixture.guardContext.actor,
+    );
+
+    const item = await updateFeature(fixture, { enabled: true }, "system.rbac");
+
+    expect(item).toMatchObject({ key: "system.rbac", enabled: true });
+  });
+
+  test("Feature Flag 更新明确使用关键审计策略", async () => {
+    const policies: string[] = [];
+    const fixture = await createFixture(actor(["developer"], true), {
+      write: async (_event, policy) => void policies.push(policy || "ordinary"),
+    });
+
+    await updateFeature(fixture, { enabled: false });
+
+    expect(policies).toEqual(["critical"]);
+  });
+
+  // @windy-module system.bulk-data begin
+  test("管理员可持久化 License 范围覆盖并写入审计明细", async () => {
+    const fixture = await createFixture(actor(["developer"], true));
+
+    const item = await updateFeature(
+      fixture,
+      { licenseVersionOverride: ["advanced", "standard", "advanced"] },
+      "system.bulk-data",
+    );
+
+    expect(item).toMatchObject({
+      allowedLicenseVersions: ["standard", "advanced"],
+      licenseVersionOverride: ["standard", "advanced"],
+      licenseVersionSource: "override",
+    });
+    expect(fixture.runtime.auditSink.list()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          action: "feature.update",
+          metadata: expect.objectContaining({
+            licenseVersionOverride: ["standard", "advanced"],
+          }),
+        }),
+      ]),
+    );
+  });
+
+  test("未知 License 版本被 400 拒绝且不会写入审计", async () => {
+    const fixture = await createFixture(actor(["developer"], true));
+    const response = (await updateFeature(
+      fixture,
+      { licenseVersionOverride: ["enterprise"] },
+      "system.bulk-data",
+    )) as Response;
+
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toMatchObject({
+      error: "INVALID_FEATURE_LICENSE_POLICY",
+    });
+    expect(fixture.runtime.auditSink.list()).toHaveLength(0);
+  });
+  // @windy-module system.bulk-data end
+});
+
+async function createFixture(
+  actorRecord: RequestActor,
+  auditWriter?: AuditEventWriter,
+) {
+  const snapshot = createFoundationSnapshot();
+  const repositories = createSystemRepositories(snapshot);
+  await repositories.features.syncManifest(snapshot.features);
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: { resolve: () => actorRecord },
+      featureResolver: repositories.features,
+      auditWriter,
+    },
+  );
+  const app = new FakeRouteApp();
+  registerFeatureFlagRoutes(app, repositories.features, runtime);
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/system/features/system.profile"),
+  );
+  return { app, runtime, repositories, guardContext };
+}
+
+function updateFeature(
+  fixture: Awaited<ReturnType<typeof createFixture>>,
+  body: Record<string, unknown>,
+  id = "system.profile",
+) {
+  return fixture.app.invoke("PUT", "/system/features/:id", {
+    guardContext: fixture.guardContext,
+    params: { id },
+    query: {},
+    body,
+  });
+}
+
+function actor(roleCodes: string[], canManage: boolean): RequestActor {
+  return {
+    id: `user_${roleCodes[0]}`,
+    type: "user",
+    name: "平台用户",
+    roleCodes,
+    permissionKeys: ["system.feature.read"].concat(
+      canManage ? "system.feature.manage" : [],
+    ),
+  };
+}