@stackonward/cli 1.2.1 → 1.3.1

package/dist/resources/components/nuxt/site-source/app/composables/useConsent.ts

@@ -1,71 +1,319 @@
-export type ConsentValue = "accepted" | "rejected";
-
-export function useConsent(storageKey?: string) {
-  const site = useSiteShell();
-  const analytics = useAnalytics();
-  const analyticsConsent = useAnalyticsConsent();
-  const resolvedStorageKey = computed(() => storageKey ?? site.value.consent.storageKey);
-  const value = ref<ConsentValue | null>(null);
-  const ready = ref(false);
-
-  function applyStoredValue(stored: string | null): void {
-    value.value = stored === "accepted" || stored === "rejected" ? stored : null;
-    if (value.value === "accepted") {
-      analyticsConsent.grant();
-    } else if (value.value === "rejected") {
-      analyticsConsent.deny();
-    } else {
-      analyticsConsent.reset();
+import { computed, readonly } from "vue";
+import type { ComputedRef, Ref } from "vue";
+import type {
+  ConsentInitializationResult,
+  ConsentMutationResult,
+  ConsentState,
+  ConsentValue,
+  SiteConsentController,
+  SiteShellConsentConfig,
+} from "~/types/site-shell";
+
+const CONSENT_RECORD_VERSION = 1;
+const MAX_TIMER_DELAY = 2_147_483_647;
+
+interface ConsentRecord {
+  readonly version: typeof CONSENT_RECORD_VERSION;
+  readonly policyRevision: string;
+  readonly value: ConsentValue;
+  readonly expiresAt: string;
+}
+
+interface ConsentAnalyticsBridge {
+  readonly available: () => boolean;
+  readonly grant: () => void;
+  readonly deny: () => void;
+  readonly reset: () => void;
+}
+
+interface CreateSiteConsentControllerOptions {
+  readonly state: Ref<ConsentState>;
+  readonly config: Readonly<ComputedRef<SiteShellConsentConfig>>;
+  readonly analytics: ConsentAnalyticsBridge;
+}
+
+/** 在应用生命周期内协调同意状态、持久化和分析开关。 */
+export function createSiteConsentController(
+  options: CreateSiteConsentControllerOptions,
+): SiteConsentController {
+  let initialized = false;
+  let disposed = false;
+  let expiryTimer: ReturnType<typeof setTimeout> | undefined;
+  let initializationResult: ConsentInitializationResult = {
+    status: "undecided",
+    cleanup: "not-required",
+  };
+
+  const visible = computed(
+    () =>
+      options.config.value.enabled &&
+      options.analytics.available() &&
+      options.state.value.ready &&
+      (options.state.value.decision === null || options.state.value.settingsOpen),
+  );
+
+  function assertAvailable(
+    operation: ConsentLifecycleError["operation"],
+    requiresReady = true,
+  ): void {
+    if (disposed || (requiresReady && !options.state.value.ready)) {
+      throw new ConsentLifecycleError(operation);
     }
   }
 
-  function handleStorage(event: StorageEvent): void {
-    if (event.key === resolvedStorageKey.value) {
-      applyStoredValue(event.newValue);
+  function cancelExpiry(): void {
+    if (expiryTimer !== undefined) {
+      clearTimeout(expiryTimer);
+      expiryTimer = undefined;
     }
   }
 
-  onMounted(() => {
+  function scheduleExpiry(expiresAt: number): void {
+    cancelExpiry();
+    const remaining = expiresAt - Date.now();
+    if (remaining <= 0) {
+      expireCurrentDecision();
+      return;
+    }
+    expiryTimer = setTimeout(() => restoreStoredDecision(), Math.min(remaining, MAX_TIMER_DELAY));
+  }
+
+  function parseConsentRecord(raw: string): ConsentRecord | null {
+    let candidate: unknown;
     try {
-      applyStoredValue(window.localStorage.getItem(resolvedStorageKey.value));
+      candidate = JSON.parse(raw);
     } catch {
-      value.value = null;
-      analyticsConsent.reset();
+      return null;
+    }
+    if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) {
+      return null;
     }
-    window.addEventListener("storage", handleStorage);
-    ready.value = true;
-  });
+    const record = candidate as Record<string, unknown>;
+    if (
+      record.version !== CONSENT_RECORD_VERSION ||
+      record.policyRevision !== options.config.value.policyRevision ||
+      (record.value !== "accepted" && record.value !== "rejected") ||
+      typeof record.expiresAt !== "string"
+    ) {
+      return null;
+    }
+    const expiresAt = Date.parse(record.expiresAt);
+    if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+      return null;
+    }
+    return {
+      version: CONSENT_RECORD_VERSION,
+      policyRevision: record.policyRevision,
+      value: record.value,
+      expiresAt: record.expiresAt,
+    };
+  }
 
-  onBeforeUnmount(() => window.removeEventListener("storage", handleStorage));
+  function updateUndecided(
+    persistence: ConsentState["persistence"],
+    error: ConsentState["error"],
+  ): void {
+    cancelExpiry();
+    options.analytics.reset();
+    options.state.value = {
+      decision: null,
+      ready: true,
+      settingsOpen: false,
+      persistence,
+      error,
+    };
+  }
 
-  const visible = computed(
-    () =>
-      site.value.consent.enabled &&
-      analytics.status.value !== "disabled" &&
-      ready.value &&
-      value.value === null,
-  );
+  function clearInvalidRecord(): ConsentInitializationResult {
+    try {
+      window.localStorage.removeItem(options.config.value.storageKey);
+      updateUndecided("cleared", null);
+      return { status: "undecided", cleanup: "cleared" };
+    } catch {
+      updateUndecided("cleanup-failed", "clear-failed");
+      return { status: "undecided", cleanup: "failed", error: "clear-failed" };
+    }
+  }
 
-  function setConsent(next: ConsentValue): void {
-    value.value = next;
-    if (import.meta.client) {
-      try {
-        window.localStorage.setItem(resolvedStorageKey.value, next);
-      } catch {
-        // 浏览器拒绝持久化时，本次会话的明确选择仍然生效。
-      }
-      if (next === "accepted") {
-        analyticsConsent.grant();
-      } else {
-        analyticsConsent.deny();
+  function applyRecord(record: ConsentRecord): ConsentInitializationResult {
+    const expiresAt = Date.parse(record.expiresAt);
+    if (record.value === "accepted") {
+      options.analytics.grant();
+    } else {
+      options.analytics.deny();
+    }
+    options.state.value = {
+      decision: record.value,
+      ready: true,
+      settingsOpen: false,
+      persistence: "persisted",
+      error: null,
+    };
+    scheduleExpiry(expiresAt);
+    return { status: "restored", value: record.value };
+  }
+
+  function restoreStoredDecision(): ConsentInitializationResult {
+    let raw: string | null;
+    try {
+      raw = window.localStorage.getItem(options.config.value.storageKey);
+    } catch {
+      updateUndecided("none", "read-failed");
+      return { status: "storage-unavailable", error: "read-failed" };
+    }
+    if (raw === null) {
+      updateUndecided("none", null);
+      return { status: "undecided", cleanup: "not-required" };
+    }
+    const record = parseConsentRecord(raw);
+    return record ? applyRecord(record) : clearInvalidRecord();
+  }
+
+  function expireCurrentDecision(): void {
+    initializationResult = restoreStoredDecision();
+  }
+
+  function onStorage(event: StorageEvent): void {
+    if (event.key === options.config.value.storageKey) {
+      initializationResult = restoreStoredDecision();
+    }
+  }
+
+  function onVisibilityChange(): void {
+    if (document.visibilityState === "visible") {
+      initializationResult = restoreStoredDecision();
+    }
+  }
+
+  function initialize(): ConsentInitializationResult {
+    assertAvailable("initialize", false);
+    if (initialized) {
+      return initializationResult;
+    }
+    initialized = true;
+    initializationResult = restoreStoredDecision();
+    window.addEventListener("storage", onStorage);
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return initializationResult;
+  }
+
+  function persist(next: ConsentValue): ConsentMutationResult {
+    assertAvailable(next === "accepted" ? "accept" : "reject");
+    cancelExpiry();
+    if (next === "accepted") {
+      options.analytics.grant();
+    } else {
+      options.analytics.deny();
+    }
+
+    const expiresAt = new Date(
+      Date.now() + options.config.value.retentionDays * 24 * 60 * 60 * 1000,
+    );
+    const record: ConsentRecord = {
+      version: CONSENT_RECORD_VERSION,
+      policyRevision: options.config.value.policyRevision,
+      value: next,
+      expiresAt: expiresAt.toISOString(),
+    };
+
+    try {
+      window.localStorage.setItem(options.config.value.storageKey, JSON.stringify(record));
+      options.state.value = {
+        decision: next,
+        ready: true,
+        settingsOpen: false,
+        persistence: "persisted",
+        error: null,
+      };
+      scheduleExpiry(expiresAt.getTime());
+      return { status: "persisted", value: next };
+    } catch {
+      if (next === "rejected") {
+        try {
+          window.localStorage.removeItem(options.config.value.storageKey);
+          options.state.value = {
+            decision: next,
+            ready: true,
+            settingsOpen: true,
+            persistence: "cleared",
+            error: "write-failed",
+          };
+          return { status: "cleared", value: next, error: "write-failed" };
+        } catch {
+          options.state.value = {
+            decision: next,
+            ready: true,
+            settingsOpen: true,
+            persistence: "session-only",
+            error: "write-and-clear-failed",
+          };
+          return {
+            status: "session-only",
+            value: next,
+            error: "write-and-clear-failed",
+          };
+        }
       }
+      options.state.value = {
+        decision: next,
+        ready: true,
+        settingsOpen: true,
+        persistence: "session-only",
+        error: "write-failed",
+      };
+      return { status: "session-only", value: next, error: "write-failed" };
+    }
+  }
+
+  function openSettings(): void {
+    assertAvailable("open-settings");
+    options.state.value.settingsOpen = true;
+  }
+
+  function closeSettings(): void {
+    assertAvailable("close-settings");
+    if (options.state.value.decision === null) {
+      throw new ConsentLifecycleError("close-settings");
+    }
+    options.state.value.settingsOpen = false;
+  }
+
+  function dispose(): void {
+    if (disposed) return;
+    disposed = true;
+    cancelExpiry();
+    if (initialized) {
+      window.removeEventListener("storage", onStorage);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
     }
   }
 
   return {
-    value: readonly(value),
+    state: readonly(options.state),
     visible,
-    accept: () => setConsent("accepted"),
-    reject: () => setConsent("rejected"),
+    initialize,
+    accept: () => persist("accepted"),
+    reject: () => persist("rejected"),
+    openSettings,
+    closeSettings,
+    dispose,
+  };
+}
+
+export class ConsentLifecycleError extends Error {
+  readonly operation: "initialize" | "accept" | "reject" | "open-settings" | "close-settings";
+
+  constructor(operation: ConsentLifecycleError["operation"]) {
+    super(`Consent operation is unavailable: ${operation}`);
+    this.name = "ConsentLifecycleError";
+    this.operation = operation;
+  }
+}
+
+/** 返回 Nuxt 应用提供的唯一同意控制器。 */
+export function useConsent(): SiteConsentController {
+  const nuxtApp = useNuxtApp() as ReturnType<typeof useNuxtApp> & {
+    readonly $siteConsent: SiteConsentController;
   };
+  return nuxtApp.$siteConsent;
 }

package/dist/resources/components/nuxt/site-source/app/composables/useNavigation.ts

@@ -1,11 +1,54 @@
-export function useNavigation() {
+import type {
+  AppNavigationItem,
+  LocalizedNavigationItemConfig,
+  MarketingNavigationItem,
+  ResolvedSiteNavigation,
+} from "~/types/site-shell";
+
+/** 将产品配置中的资源键投影为当前语言可渲染的导航。 */
+export function useNavigation(): ResolvedSiteNavigation {
   const site = useSiteShell();
+  const { t } = useI18n();
+
+  function resolveMarketingItem(item: LocalizedNavigationItemConfig): MarketingNavigationItem {
+    return {
+      label: t(item.labelKey),
+      ...(item.to === undefined ? {} : { to: item.to }),
+      ...(item.external === undefined ? {} : { external: item.external }),
+      ...(item.descriptionKey === undefined ? {} : { description: t(item.descriptionKey) }),
+      ...(item.children === undefined ? {} : { children: item.children.map(resolveMarketingItem) }),
+    };
+  }
 
   return {
-    marketingNav: computed(() => site.value.navigation.marketing),
-    appNavGroups: computed(() => site.value.navigation.app),
-    footerGroups: computed(() => site.value.navigation.footer),
-    legalLinks: computed(() => site.value.navigation.legal),
-    socialLinks: computed(() => site.value.navigation.social),
+    marketingNav: computed(() => site.value.navigation.marketing.map(resolveMarketingItem)),
+    appNavGroups: computed(() =>
+      site.value.navigation.app.map((group) => ({
+        ...(group.labelKey === undefined ? {} : { label: t(group.labelKey) }),
+        items: group.items.map(
+          (item): AppNavigationItem => ({
+            label: t(item.labelKey),
+            to: item.to,
+            ...(item.icon === undefined ? {} : { icon: item.icon }),
+            ...(item.badge === undefined ? {} : { badge: item.badge }),
+          }),
+        ),
+      })),
+    ),
+    footerGroups: computed(() =>
+      site.value.navigation.footer.map((group) => ({
+        title: t(group.titleKey),
+        links: group.links.map(resolveMarketingItem),
+      })),
+    ),
+    legalLinks: computed(() => site.value.navigation.legal.map(resolveMarketingItem)),
+    socialLinks: computed(() =>
+      site.value.navigation.social.map((link) => ({
+        label: t(link.labelKey),
+        href: link.href,
+      })),
+    ),
+    primaryActionLabel: computed(() => t(site.value.primaryActionLabelKey)),
+    secondaryActionLabel: computed(() => t(site.value.secondaryActionLabelKey)),
   };
 }

package/dist/resources/components/nuxt/site-source/app/composables/useSeo.ts

@@ -15,14 +15,16 @@ function joinUrl(baseUrl: string, path: string): string {
 
 export function useSeo(input: SeoInput): void {
   const site = useSiteShell();
+  const { t } = useI18n();
   const route = useRoute();
   const canonical = computed(() => joinUrl(site.value.url, input.canonicalPath ?? route.path));
+  const description = computed(() => input.description ?? t(site.value.descriptionKey));
 
   useSeoMeta({
     title: input.title,
-    description: input.description ?? site.value.description,
+    description,
     ogTitle: input.title,
-    ogDescription: input.description ?? site.value.description,
+    ogDescription: description,
     ogImage: input.image,
     robots: input.robots,
   });

package/dist/resources/components/nuxt/site-source/app/composables/useSiteShell.ts

@@ -1,23 +1,39 @@
-import type { SiteShellConfig } from "~/types/site-shell";
+import type { ComputedRef } from "vue";
+import type {
+  SiteShellConfig,
+  SiteShellConsentConfig,
+  StorageDisclosureConfig,
+} from "~/types/site-shell";
+
+type SiteShellConfigInput = Omit<
+  Partial<SiteShellConfig>,
+  "consent" | "storageDisclosures" | "navigation" | "content"
+> & {
+  readonly consent?: Partial<SiteShellConsentConfig>;
+  readonly storageDisclosures?: readonly StorageDisclosureConfig[];
+  readonly navigation?: Partial<SiteShellConfig["navigation"]>;
+  readonly content?: Partial<SiteShellConfig["content"]>;
+};
 
 const DEFAULT_SITE_SHELL_CONFIG: SiteShellConfig = {
   name: "Product Studio",
-  description: "Premium product imagery and ad video production workspace.",
+  descriptionKey: "site.description",
   url: "",
   defaultLocale: "en",
   homePath: "/",
   appPath: "/app",
   logoText: "Product Studio",
-  primaryActionLabel: "Start creating",
-  secondaryActionLabel: "Sign in",
+  primaryActionLabelKey: "actions.start",
+  secondaryActionLabelKey: "actions.signIn",
   secondaryActionPath: "/app",
   consent: {
     enabled: true,
-    storageKey: "site-consent",
-    message: "This site can store optional preferences on this device.",
-    acceptLabel: "Allow",
-    rejectLabel: "Decline",
+    storageKey: "site-analytics-consent-v1",
+    policyRevision: "1",
+    retentionDays: 180,
+    policyPath: "/legal/cookies",
   },
+  storageDisclosures: [],
   navigation: {
     marketing: [],
     app: [],
@@ -33,7 +49,7 @@ const DEFAULT_SITE_SHELL_CONFIG: SiteShellConfig = {
   },
 };
 
-function mergeSiteShellConfig(input: Partial<SiteShellConfig> | undefined): SiteShellConfig {
+function mergeSiteShellConfig(input: SiteShellConfigInput | undefined): SiteShellConfig {
   return {
     ...DEFAULT_SITE_SHELL_CONFIG,
     ...input,
@@ -41,6 +57,7 @@ function mergeSiteShellConfig(input: Partial<SiteShellConfig> | undefined): Site
       ...DEFAULT_SITE_SHELL_CONFIG.consent,
       ...input?.consent,
     },
+    storageDisclosures: input?.storageDisclosures ?? DEFAULT_SITE_SHELL_CONFIG.storageDisclosures,
     navigation: {
       ...DEFAULT_SITE_SHELL_CONFIG.navigation,
       ...input?.navigation,
@@ -52,7 +69,8 @@ function mergeSiteShellConfig(input: Partial<SiteShellConfig> | undefined): Site
   };
 }
 
-export function useSiteShell() {
-  const appConfig = useAppConfig() as { siteShell?: Partial<SiteShellConfig> };
+/** 返回当前 Nuxt 应用拥有的站点配置只读视图。 */
+export function useSiteShell(): Readonly<ComputedRef<SiteShellConfig>> {
+  const appConfig = useAppConfig() as { readonly siteShell?: SiteShellConfigInput };
   return computed(() => mergeSiteShellConfig(appConfig.siteShell));
 }

package/dist/resources/components/nuxt/site-source/app/plugins/consent.ts

@@ -0,0 +1,43 @@
+import type { ConsentState } from "~/types/site-shell";
+
+export default defineNuxtPlugin({
+  name: "site:consent",
+  dependsOn: ["stackonward:analytics"],
+  setup(nuxtApp) {
+    const site = useSiteShell();
+    const analytics = useAnalytics();
+    const analyticsConsent = useAnalyticsConsent();
+    const state = useState<ConsentState>("site:consent", () => ({
+      decision: null,
+      ready: false,
+      settingsOpen: false,
+      persistence: "none",
+      error: null,
+    }));
+    const controller = createSiteConsentController({
+      state,
+      config: computed(() => site.value.consent),
+      analytics: {
+        available: () => analytics.status.value !== "disabled",
+        grant: () => {
+          analyticsConsent.grant();
+        },
+        deny: () => {
+          analyticsConsent.deny();
+        },
+        reset: () => {
+          analyticsConsent.reset();
+        },
+      },
+    });
+
+    if (import.meta.client) {
+      onNuxtReady(() => {
+        controller.initialize();
+      });
+      nuxtApp.vueApp.onUnmount(() => controller.dispose());
+    }
+
+    return { provide: { siteConsent: controller } };
+  },
+});