Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,26 @@
import { describe, expect, it } from "vitest";
import { resolveConnectorNavState } from "./connectorNavState";
describe("resolveConnectorNavState", () => {
it("maps an allowed decision to 'active'", () => {
expect(resolveConnectorNavState({ allowed: true })).toBe("active");
expect(resolveConnectorNavState({ allowed: true, reason: "included" })).toBe("active");
});
it("maps blueprint/role/override denials to 'hidden'", () => {
expect(resolveConnectorNavState({ allowed: false, reason: "blueprint-disabled" })).toBe("hidden");
expect(resolveConnectorNavState({ allowed: false, reason: "tenant-role-missing" })).toBe("hidden");
expect(resolveConnectorNavState({ allowed: false, reason: "tenant-override-disabled" })).toBe("hidden");
expect(resolveConnectorNavState({ allowed: false, reason: "tenant-override-not-toggleable" })).toBe("hidden");
});
it("maps entitlement/plan denials to 'locked' (upsell)", () => {
expect(resolveConnectorNavState({ allowed: false, reason: "not-included" })).toBe("locked");
expect(resolveConnectorNavState({ allowed: false, reason: "limit-reached" })).toBe("locked");
expect(resolveConnectorNavState({ allowed: false, reason: "no-subscription" })).toBe("locked");
});
it("defaults to 'locked' when a denial carries no reason", () => {
expect(resolveConnectorNavState({ allowed: false })).toBe("locked");
});
});
@@ -0,0 +1,33 @@
/**
* Konnektor → Sidebar-Zustand (R-P1c).
*
* Bildet eine Konnektor-Entscheidung (aus {@link tenantHasModule} / `resolveTenantProductAccess`)
* auf die drei Sidebar-Zustände ab, die das Walking-Skeleton exemplarisch demonstriert:
*
* - `active` — Tenant darf das Modul nutzen → Eintrag sichtbar + klickbar.
* - `locked` — Modul ist im Produkt-Blueprint, aber nicht im Abo des Tenants → sichtbar,
* aber `disabled` (Upsell-Hinweis).
* - `hidden` — Modul gilt für diesen Tenant/User gar nicht (nicht im Blueprint, Rolle fehlt,
* per Override abgeschaltet) → kein Eintrag (404 statt 403, Bauprinzip A.5.3).
*/
export type ConnectorNavState = "active" | "locked" | "hidden";
export interface ConnectorDecisionLike {
readonly allowed: boolean;
readonly reason?: string;
}
// Gründe, bei denen das Modul für diesen Tenant/User schlicht nicht existiert → ausblenden.
const HIDDEN_REASONS = new Set<string>(["blueprint-disabled", "tenant-role-missing", "tenant-override-disabled", "tenant-override-not-toggleable"]);
export function resolveConnectorNavState(decision: ConnectorDecisionLike): ConnectorNavState {
if (decision.allowed) {
return "active";
}
if (decision.reason && HIDDEN_REASONS.has(decision.reason)) {
return "hidden";
}
// Übrige Gründe (Entitlement nicht enthalten / Limit erreicht / kein Abo) = im Blueprint, aber
// nicht gebucht → gesperrt mit Upsell.
return "locked";
}
@@ -0,0 +1,101 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
// Cache-Abstraktion: getFreshValue direkt durchreichen (deterministisch, kein Cache-State zwischen Tests).
vi.mock("~/utils/cache.server", () => ({
cachified: vi.fn(async (opts: { getFreshValue: () => Promise<unknown> }) => opts.getFreshValue()),
clearCacheKeyPrefix: vi.fn(),
}));
vi.mock("~/utils/entitlements/.server/productAccess.server", () => ({
resolveTenantProductAccess: vi.fn(),
}));
vi.mock("~/utils/services/.server/subscriptionService", () => ({
getActiveTenantSubscriptions: vi.fn(async () => null),
}));
vi.mock("~/utils/services/.server/featureFlagEvaluator.server", () => ({
evaluateFlagForContext: vi.fn(),
}));
import { clearCacheKeyPrefix } from "~/utils/cache.server";
import { resolveTenantProductAccess } from "~/utils/entitlements/.server/productAccess.server";
import { getActiveTenantSubscriptions } from "~/utils/services/.server/subscriptionService";
import { evaluateFlagForContext } from "~/utils/services/.server/featureFlagEvaluator.server";
import { invalidateTenantModuleAccessCache, tenantHasFlag, tenantHasModule } from "./tenantConnector.server";
const resolveMock = vi.mocked(resolveTenantProductAccess);
const subscriptionMock = vi.mocked(getActiveTenantSubscriptions);
const flagMock = vi.mocked(evaluateFlagForContext);
const clearPrefixMock = vi.mocked(clearCacheKeyPrefix);
describe("tenantHasModule", () => {
beforeEach(() => {
vi.clearAllMocks();
subscriptionMock.mockResolvedValue(null as never);
});
it("returns true when the product-access decision allows the module", async () => {
resolveMock.mockResolvedValue({ allowed: true } as never);
const allowed = await tenantHasModule({ tenantId: "t1", userId: "u1", moduleKey: "crm-basic" });
expect(allowed).toBe(true);
expect(subscriptionMock).toHaveBeenCalledWith("t1");
expect(resolveMock).toHaveBeenCalledWith(
expect.objectContaining({ tenantId: "t1", userId: "u1", featureKey: "crm-basic" })
);
});
it("returns false when the product-access decision denies the module", async () => {
resolveMock.mockResolvedValue({ allowed: false } as never);
const allowed = await tenantHasModule({ tenantId: "t1", userId: "u1", moduleKey: "kwp" });
expect(allowed).toBe(false);
});
it("forwards the bypassTenantRolePermission flag to the resolver", async () => {
resolveMock.mockResolvedValue({ allowed: true } as never);
await tenantHasModule({ tenantId: "t1", userId: "u1", moduleKey: "crm-basic", bypassTenantRolePermission: true });
expect(resolveMock).toHaveBeenCalledWith(expect.objectContaining({ bypassTenantRolePermission: true }));
});
});
describe("tenantHasFlag", () => {
beforeEach(() => {
vi.clearAllMocks();
});
it("returns the evaluator's enabled boolean", async () => {
flagMock.mockResolvedValue({ enabled: true } as never);
const enabled = await tenantHasFlag({ flagKey: "new-dashboard", tenantId: "t1", userId: "u1" });
expect(enabled).toBe(true);
expect(flagMock).toHaveBeenCalledWith("new-dashboard", { flagName: "new-dashboard", tenantId: "t1", userId: "u1" });
});
it("normalizes missing tenant/user context to null", async () => {
flagMock.mockResolvedValue({ enabled: false } as never);
const enabled = await tenantHasFlag({ flagKey: "beta" });
expect(enabled).toBe(false);
expect(flagMock).toHaveBeenCalledWith("beta", { flagName: "beta", tenantId: null, userId: null });
});
});
describe("invalidateTenantModuleAccessCache", () => {
beforeEach(() => {
vi.clearAllMocks();
});
it("clears every cached module decision for the tenant", () => {
invalidateTenantModuleAccessCache("t1");
expect(clearPrefixMock).toHaveBeenCalledWith("connector:module:t1:");
});
});
@@ -0,0 +1,94 @@
import { cachified, clearCacheKeyPrefix } from "~/utils/cache.server";
import { resolveTenantProductAccess } from "~/utils/entitlements/.server/productAccess.server";
import { getActiveTenantSubscriptions } from "~/utils/services/.server/subscriptionService";
import { evaluateFlagForContext } from "~/utils/services/.server/featureFlagEvaluator.server";
/**
* Konnektor (R-P1b) — das kanonische Pflicht-Gate jeder Modul-Phase.
*
* Zwei Boolean-Checks, auf die jedes Folge-Modul aufsetzt (Reachability / Sidebar-Gating /
* Loader-Guard). Beide bauen auf bestehende Resolver auf, statt sie nachzubauen:
*
* - `tenantHasModule()` — "Darf dieser Tenant dieses Modul nutzen?" Brücke Billing↔Feature-Gate:
* prüft Abo/Entitlement (`SubscriptionFeature` über das aktive Tenant-Abo), Produkt-Blueprint,
* Tenant-Override und ggf. Tenant-Rollen-Permission via {@link resolveTenantProductAccess}.
* Die Modul-Entscheidung wird auf Connector-Ebene gecacht (`getActiveTenantSubscriptions` ist
* bereits gecacht; die zusätzlichen Konfigurations-/Override-/Permission-Queries nicht).
*
* - `tenantHasFlag()` — "Ist dieses Feature-Flag für diesen Kontext aktiv?" Delegiert an den
* v2-Evaluator {@link evaluateFlagForContext}, der bereits eigenen Eval-Cache mitbringt.
*
* Cache-Backing ist die App-Cache-Abstraktion (`~/utils/cache.server`, LRU heute, per
* `redisCacheAdapter` Redis-swappbar — Infra-Schalter, kein Logik-Eingriff).
*/
const MODULE_CACHE_TTL_MS = 60_000;
const MODULE_CACHE_PREFIX = "connector:module:";
export interface TenantModuleAccessInput {
/** Tenant, dessen Abo/Entitlement geprüft wird. */
readonly tenantId: string;
/** Aktueller User (für Tenant-Rollen-Permission + Super-Admin-Bypass). */
readonly userId: string;
/** Modul-/Feature-Code (z.B. "crm-basic"), wie in `SubscriptionFeature.name` / `featureKeys`. */
readonly moduleKey: string;
/** Rollen-Permission-Prüfung umgehen (z.B. System-/Hintergrund-Kontext). */
readonly bypassTenantRolePermission?: boolean;
}
function moduleCacheKey(input: TenantModuleAccessInput): string {
const scope = input.bypassTenantRolePermission ? "bypass" : "rbac";
return `${MODULE_CACHE_PREFIX}${input.tenantId}:${input.userId}:${input.moduleKey}:${scope}`;
}
/**
* Konnektor-Gate: Ist das Modul für den Tenant freigeschaltet?
*
* @returns `true`, wenn der Tenant das Modul nutzen darf (Abo + Blueprint + Override + Rolle ok).
*/
export async function tenantHasModule(input: TenantModuleAccessInput): Promise<boolean> {
return cachified({
key: moduleCacheKey(input),
ttl: MODULE_CACHE_TTL_MS,
getFreshValue: async () => {
const subscription = await getActiveTenantSubscriptions(input.tenantId);
const decision = await resolveTenantProductAccess({
tenantId: input.tenantId,
userId: input.userId,
featureKey: input.moduleKey,
subscription,
bypassTenantRolePermission: input.bypassTenantRolePermission,
});
return decision.allowed;
},
});
}
export interface TenantFlagContext {
/** Flag-Name/-Key wie in der FeatureFlag-Tabelle. */
readonly flagKey: string;
readonly tenantId?: string | null;
readonly userId?: string | null;
}
/**
* Konnektor-Gate: Ist das Feature-Flag für den Kontext aktiv?
*
* @returns `true`, wenn das Flag (global/Tenant/User-scoped + Regeln) enabled ist.
*/
export async function tenantHasFlag(input: TenantFlagContext): Promise<boolean> {
const result = await evaluateFlagForContext(input.flagKey, {
flagName: input.flagKey,
tenantId: input.tenantId ?? null,
userId: input.userId ?? null,
});
return result.enabled;
}
/**
* Verwirft alle gecachten Modul-Entscheidungen eines Tenants. Aufrufen nach Abo-/Override-/
* Rollen-Änderungen (z.B. Stripe-Webhook, Admin-Plan-Wechsel), damit das Gate sofort nachzieht.
*/
export function invalidateTenantModuleAccessCache(tenantId: string): void {
clearCacheKeyPrefix(`${MODULE_CACHE_PREFIX}${tenantId}:`);
}