create-windy 0.3.16 → 0.3.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "39074967cfcee6aca5ff6d3e2791b93ab90e70af",
-  "generatorVersion": "0.3.16",
+  "templateCommit": "267cc4a82fec7fa39819029ce6e967f93b4f0463",
+  "generatorVersion": "0.3.17",
   "modules": [
     {
       "name": "system",

package/template/AGENTS.md

@@ -69,7 +69,7 @@
 - `docs/development/custom-error-pages.md`：统一错误语义、Request ID 与业务页面
   替换方式。
 - `bun run dev`：复用 Docker 镜像启动 PostgreSQL、自动 migration、Server 与支持热更新的 Web。
-- `bun run dev:build`：依赖、Dockerfile 或 lockfile 变化后重建并启动开发环境。
+- `bun run dev:build`：依赖、Dockerfile 或 lockfile 变化后重建并启动开发环境；Web 与 Server 并发复用 BuildKit Bun 下载缓存，冷安装会周期输出不含凭据的心跳。
 - `bun run dev:web`：启动 Web 开发服务。
 - `bun run dev:server`：启动 Server 开发服务。
 - `bun run lint`、`bun run typecheck`、`bun run test`、`bun run build`：执行基础验证；未选择 Oxc 时没有 lint 脚本。

package/template/README.md

@@ -31,7 +31,9 @@ create-windy 已创建仅供本机使用且被 Git 忽略的 `.env`，其中两
 Drizzle migration，再启动 Server 与 Web；不要跳过 migration 后直接把 Server 连接到
 空数据库。首次启动需要本机已经安装并启动 Docker 与 Docker Compose，并可能需要下载
 基础镜像。后续 `bun run dev` 会复用已有镜像，不会重复构建；依赖、Dockerfile 或
-`bun.lock` 变化后运行 `bun run dev:build`。
+`bun.lock` 变化后运行 `bun run dev:build`。重建会让 Web 与 Server 并发复用
+BuildKit 中的 Bun 包下载缓存，只下载新增或发生变化的依赖；冷安装每 15 秒输出一次
+不含 registry 地址或凭据的进度心跳。
 
 | 服务 | 地址 |
 | ---- | ---- |

package/template/apps/server/Dockerfile

@@ -22,7 +22,7 @@ COPY packages/server-sdk/package.json packages/server-sdk/package.json
 COPY packages/shared/package.json packages/shared/package.json
 COPY packages/storage/package.json packages/storage/package.json
 # windy-copy:deps end
-RUN bun install --frozen-lockfile
+RUN --mount=type=cache,id=windy-bun-1.3.14,target=/root/.bun/install/cache,sharing=shared bun -e 'const child=Bun.spawn(["bun","install","--frozen-lockfile","--no-progress"],{stdin:"inherit",stdout:"inherit",stderr:"inherit"});const heartbeat=setInterval(()=>console.log("[windy] Bun 依赖安装仍在进行"),15000);const exitCode=await child.exited;clearInterval(heartbeat);process.exit(exitCode)'
 
 FROM deps AS runner
 COPY drizzle.config.ts drizzle.config.ts

package/template/apps/server/src/audit/contracts.ts

@@ -1,5 +1,11 @@
 export type AuditWritePolicy = "ordinary" | "critical";
 
+export type AuditRecoveryFailure =
+  | "permission-denied"
+  | "invalid-format"
+  | "io-error"
+  | "unknown";
+
 export interface AuditWriteStatus {
   state: "healthy" | "degraded";
   attempted: number;
@@ -10,6 +16,8 @@ export interface AuditWriteStatus {
   dropped: number;
   lastFailureAt?: string;
   lastSuccessAt?: string;
+  recoveryFailure?: AuditRecoveryFailure;
+  lastRecoveryFailureAt?: string;
   alert?: string;
 }
 

package/template/apps/server/src/audit/recovery-queue.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm, stat } from "node:fs/promises";
+import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import type { AuditEvent } from "@southwind-ai/shared";
@@ -39,4 +39,51 @@ describe("FileAuditRecoveryQueue", () => {
       await Array.fromAsync(new Bun.Glob("*.tmp").scan(directory)),
     ).toEqual([]);
   });
+
+  test("合法空队列保持可读", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "windy-audit-empty-"));
+    directories.push(directory);
+    const filePath = join(directory, "recovery.json");
+    const queue = new FileAuditRecoveryQueue(filePath);
+
+    await queue.replace([]);
+
+    await expect(queue.read()).resolves.toEqual([]);
+  });
+
+  test.each([
+    ["缺少 formatVersion", { events: [] }],
+    ["formatVersion 不受支持", { formatVersion: 2, events: [] }],
+    ["缺少 events", { formatVersion: 1 }],
+    ["events 不是数组", { formatVersion: 1, events: { secret: "不应泄露" } }],
+    [
+      "event 结构损坏",
+      {
+        formatVersion: 1,
+        events: [
+          {
+            id: "audit_invalid",
+            action: "auth.login",
+            outcome: "success",
+            actor: { id: "user_1", type: "invalid", name: "用户一" },
+            occurredAt: "2026-07-10T00:00:00.000Z",
+            secret: "不应泄露",
+          },
+        ],
+      },
+    ],
+  ])("%s 时以稳定无敏感内容错误拒绝", async (_, envelope) => {
+    const directory = await mkdtemp(join(tmpdir(), "windy-audit-invalid-"));
+    directories.push(directory);
+    const filePath = join(directory, "recovery.json");
+    await writeFile(filePath, JSON.stringify(envelope), "utf8");
+
+    const error = await new FileAuditRecoveryQueue(filePath)
+      .read()
+      .catch((failure: unknown) => failure);
+
+    expect(error).toBeInstanceOf(SyntaxError);
+    expect((error as Error).message).toBe("审计恢复队列文件格式无效");
+    expect(String(error)).not.toContain("不应泄露");
+  });
 });

package/template/apps/server/src/audit/recovery-queue.ts

@@ -2,6 +2,9 @@ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import type { AuditEvent } from "@southwind-ai/shared";
 
+const recoveryQueueFormatVersion = 1;
+const invalidRecoveryQueueMessage = "审计恢复队列文件格式无效";
+
 export interface AuditRecoveryQueue {
   read(): Promise<AuditEvent[]>;
   replace(events: AuditEvent[]): Promise<void>;
@@ -17,6 +20,9 @@ export class FileAuditRecoveryQueue implements AuditRecoveryQueue {
       return readEvents(value);
     } catch (error) {
       if (isMissingFile(error)) return [];
+      if (error instanceof SyntaxError) {
+        throw new SyntaxError(invalidRecoveryQueueMessage);
+      }
       throw error;
     }
   }
@@ -26,7 +32,7 @@ export class FileAuditRecoveryQueue implements AuditRecoveryQueue {
     const temporaryPath = `${this.filePath}.${process.pid}.tmp`;
     await writeFile(
       temporaryPath,
-      JSON.stringify({ formatVersion: 1, events }),
+      JSON.stringify({ formatVersion: recoveryQueueFormatVersion, events }),
       { encoding: "utf8", mode: 0o600 },
     );
     await rename(temporaryPath, this.filePath);
@@ -49,9 +55,72 @@ export class MemoryAuditRecoveryQueue implements AuditRecoveryQueue {
 }
 
 function readEvents(value: unknown): AuditEvent[] {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
-  const events = (value as Record<string, unknown>).events;
-  return Array.isArray(events) ? (events as AuditEvent[]) : [];
+  if (
+    !isRecord(value) ||
+    value.formatVersion !== recoveryQueueFormatVersion ||
+    !Array.isArray(value.events) ||
+    !value.events.every(isAuditEvent)
+  ) {
+    throw new SyntaxError(invalidRecoveryQueueMessage);
+  }
+  return value.events;
+}
+
+function isAuditEvent(value: unknown): value is AuditEvent {
+  if (!isRecord(value) || !isRecord(value.actor)) return false;
+  const actor = value.actor;
+  return (
+    typeof value.id === "string" &&
+    typeof value.action === "string" &&
+    (value.outcome === "attempted" ||
+      value.outcome === "success" ||
+      value.outcome === "failure" ||
+      value.outcome === "denied") &&
+    typeof actor.id === "string" &&
+    (actor.type === "user" ||
+      actor.type === "service" ||
+      actor.type === "system") &&
+    typeof actor.name === "string" &&
+    isOptionalStringArray(actor.roleCodes) &&
+    isOptionalString(actor.ip) &&
+    isOptionalString(actor.userAgent) &&
+    isOptionalTarget(value.target) &&
+    isOptionalString(value.module) &&
+    isOptionalString(value.requestId) &&
+    isOptionalString(value.message) &&
+    isOptionalRecord(value.metadata) &&
+    typeof value.occurredAt === "string"
+  );
+}
+
+function isOptionalTarget(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (isRecord(value) &&
+      typeof value.type === "string" &&
+      isOptionalString(value.id) &&
+      isOptionalString(value.label))
+  );
+}
+
+function isOptionalString(value: unknown): boolean {
+  return value === undefined || typeof value === "string";
+}
+
+function isOptionalStringArray(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (Array.isArray(value) &&
+      value.every((item): item is string => typeof item === "string"))
+  );
+}
+
+function isOptionalRecord(value: unknown): boolean {
+  return value === undefined || isRecord(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 function isMissingFile(error: unknown): boolean {

package/template/apps/server/src/audit/reliable-writer.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { AuditEvent } from "@southwind-ai/shared";
-import { MemoryAuditRecoveryQueue } from "./recovery-queue.js";
+import {
+  FileAuditRecoveryQueue,
+  MemoryAuditRecoveryQueue,
+} from "./recovery-queue.js";
 import {
   AuditWriteUnavailableError,
   ReliableAuditWriter,
@@ -127,6 +133,117 @@ describe("ReliableAuditWriter", () => {
     });
   });
 
+  test("恢复队列权限错误时降级启动并记录稳定诊断", async () => {
+    const queue = new MemoryAuditRecoveryQueue();
+    queue.failure = Object.assign(new Error("sensitive queue path"), {
+      code: "EACCES",
+    });
+    const alerts: string[] = [];
+    const writer = new ReliableAuditWriter(
+      { write: async () => undefined },
+      queue,
+      {
+        now: () => new Date("2026-07-28T10:00:00.000Z"),
+        onAlert: (status) => alerts.push(status.alert || ""),
+      },
+    );
+
+    await expect(writer.recover()).resolves.toBeUndefined();
+
+    expect(writer.status()).toMatchObject({
+      state: "degraded",
+      recoveryFailure: "permission-denied",
+      lastRecoveryFailureAt: "2026-07-28T10:00:00.000Z",
+      alert: "关键审计恢复队列不可用：文件权限不足",
+    });
+    expect(alerts).toEqual(["关键审计恢复队列不可用：文件权限不足"]);
+    expect(JSON.stringify(writer.status())).not.toContain(
+      "sensitive queue path",
+    );
+  });
+
+  test("恢复队列 JSON 损坏时降级启动且不泄露文件内容", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "windy-audit-corrupt-"));
+    const filePath = join(directory, "recovery.json");
+    await writeFile(filePath, '{"secret":"must-not-leak"', "utf8");
+    const writer = new ReliableAuditWriter(
+      { write: async () => undefined },
+      new FileAuditRecoveryQueue(filePath),
+      { now: () => new Date("2026-07-28T10:01:00.000Z") },
+    );
+
+    try {
+      await expect(writer.recover()).resolves.toBeUndefined();
+
+      expect(writer.status()).toMatchObject({
+        state: "degraded",
+        recoveryFailure: "invalid-format",
+        lastRecoveryFailureAt: "2026-07-28T10:01:00.000Z",
+        alert: "关键审计恢复队列不可用：队列文件格式无效",
+      });
+      expect(JSON.stringify(writer.status())).not.toContain("must-not-leak");
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+
+  test("普通审计落库成功不能清除恢复队列故障", async () => {
+    const queue = new MemoryAuditRecoveryQueue();
+    queue.events = [{ ...event(), id: "audit_queued" }];
+    queue.failure = Object.assign(new Error("queue unavailable"), {
+      code: "EIO",
+    });
+    const writer = new ReliableAuditWriter(
+      { write: async () => undefined },
+      queue,
+      { now: () => new Date("2026-07-28T10:02:00.000Z") },
+    );
+    await writer.recover();
+
+    await writer.write(event(), "ordinary");
+
+    expect(writer.status()).toMatchObject({
+      state: "degraded",
+      persisted: 1,
+      recoveryFailure: "io-error",
+      lastRecoveryFailureAt: "2026-07-28T10:02:00.000Z",
+      alert: "关键审计恢复队列不可用：文件读写失败",
+    });
+
+    queue.failure = undefined;
+    await writer.recover();
+
+    expect(writer.status()).toMatchObject({
+      state: "healthy",
+      persisted: 2,
+      queued: 0,
+    });
+    expect(queue.events).toEqual([]);
+    expect(writer.status().recoveryFailure).toBeUndefined();
+    expect(writer.status().lastRecoveryFailureAt).toBeUndefined();
+    expect(writer.status().alert).toBeUndefined();
+  });
+
+  test("恢复队列重新可写后以关键事件待重放状态替代队列故障", async () => {
+    const queue = new MemoryAuditRecoveryQueue();
+    queue.failure = Object.assign(new Error("queue unavailable"), {
+      code: "EACCES",
+    });
+    const writer = failingWriter(queue);
+    await writer.recover();
+    queue.failure = undefined;
+
+    await writer.write(event(), "critical");
+
+    expect(writer.status()).toMatchObject({
+      state: "degraded",
+      queued: 1,
+      alert: "关键审计已进入可恢复队列",
+    });
+    expect(writer.status().recoveryFailure).toBeUndefined();
+    expect(writer.status().lastRecoveryFailureAt).toBeUndefined();
+  });
+
   test("当前事件已落库但恢复文件故障时只告警且不误报丢弃", async () => {
     const queue = new MemoryAuditRecoveryQueue();
     let databaseAvailable = false;
@@ -152,7 +269,8 @@ describe("ReliableAuditWriter", () => {
       persisted: 1,
       queued: 1,
       dropped: 0,
-      alert: "关键审计恢复队列不可用",
+      recoveryFailure: "unknown",
+      alert: "关键审计恢复队列不可用：未知错误",
     });
   });
 

package/template/apps/server/src/audit/reliable-writer.ts

@@ -2,6 +2,7 @@ import type { AuditEvent } from "@southwind-ai/shared";
 import type { AuditEventWriter } from "../runtime.js";
 import {
   AuditWriteUnavailableError,
+  type AuditRecoveryFailure,
   type AuditWritePolicy,
   type AuditWriteStatus,
 } from "./contracts.js";
@@ -69,45 +70,62 @@ export class ReliableAuditWriter implements AuditEventWriter {
       await this.handlePersistenceFailure(redacted, policy);
       return;
     }
-    if (this.current.queued > 0) {
-      try {
-        await this.recover();
-      } catch {
-        // 当前事件已经持久化；恢复队列故障只触发告警，不回滚成功写入。
-      }
+    if (this.current.queued > 0 || this.current.recoveryFailure) {
+      await this.recover();
     }
   }
 
   async recover(): Promise<void> {
-    try {
-      await this.withQueueLock(async () => {
-        const events = await this.queue.read();
-        if (!events.length) {
-          this.current.queued = 0;
-          this.refreshState();
-          return;
-        }
-        const pending: AuditEvent[] = [];
-        for (let index = 0; index < events.length; index += 1) {
-          try {
-            await this.persistWithRetry(events[index]!);
-            this.markSuccess();
-          } catch {
-            pending.push(...events.slice(index));
-            break;
-          }
-        }
-        await this.queue.replace(pending);
-        this.current.queued = pending.length;
-        if (pending.length) {
-          this.markDegraded("关键审计恢复仍在等待持久化");
-        } else {
-          this.refreshState();
+    await this.withQueueLock(async () => {
+      const events = await this.readRecoveryQueue();
+      if (!events) return;
+      if (!events.length) {
+        this.current.queued = 0;
+        this.clearRecoveryFailure();
+        this.refreshState();
+        return;
+      }
+      const pending: AuditEvent[] = [];
+      for (let index = 0; index < events.length; index += 1) {
+        try {
+          await this.persistWithRetry(events[index]!);
+          this.markSuccess();
+        } catch {
+          pending.push(...events.slice(index));
+          break;
         }
-      });
+      }
+      if (!(await this.replaceRecoveryQueue(pending, events.length))) return;
+      this.current.queued = pending.length;
+      this.clearRecoveryFailure();
+      if (pending.length) {
+        this.markDegraded("关键审计恢复仍在等待持久化");
+      } else {
+        this.refreshState();
+      }
+    });
+  }
+
+  private async readRecoveryQueue(): Promise<AuditEvent[] | undefined> {
+    try {
+      return await this.queue.read();
     } catch (error) {
-      this.markDegraded("关键审计恢复队列不可用");
-      throw error;
+      this.markRecoveryDegraded(error);
+      return undefined;
+    }
+  }
+
+  private async replaceRecoveryQueue(
+    events: AuditEvent[],
+    currentQueueSize: number,
+  ): Promise<boolean> {
+    try {
+      await this.queue.replace(events);
+      return true;
+    } catch (error) {
+      this.current.queued = currentQueueSize;
+      this.markRecoveryDegraded(error);
+      return false;
     }
   }
 
@@ -133,6 +151,7 @@ export class ReliableAuditWriter implements AuditEventWriter {
         await this.queue.replace([...events, event]);
         this.current.queued = events.length + 1;
       });
+      this.clearRecoveryFailure();
       this.markDegraded("关键审计已进入可恢复队列");
     } catch {
       this.markDegraded("关键审计写入和恢复队列均不可用");
@@ -169,8 +188,20 @@ export class ReliableAuditWriter implements AuditEventWriter {
     this.options.onAlert?.(this.status());
   }
 
+  private markRecoveryDegraded(error: unknown): void {
+    const recoveryFailure = classifyRecoveryFailure(error);
+    this.current.recoveryFailure = recoveryFailure;
+    this.current.lastRecoveryFailureAt = this.now().toISOString();
+    this.markDegraded(recoveryFailureAlert(recoveryFailure));
+  }
+
+  private clearRecoveryFailure(): void {
+    delete this.current.recoveryFailure;
+    delete this.current.lastRecoveryFailureAt;
+  }
+
   private refreshState(): void {
-    if (this.current.queued === 0) {
+    if (this.current.queued === 0 && !this.current.recoveryFailure) {
       this.current.state = "healthy";
       delete this.current.alert;
     }
@@ -199,3 +230,36 @@ function boundedInteger(
 function sleep(milliseconds: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
+
+function classifyRecoveryFailure(error: unknown): AuditRecoveryFailure {
+  if (error instanceof SyntaxError) {
+    return "invalid-format";
+  }
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error.code === "EACCES" || error.code === "EPERM")
+  ) {
+    return "permission-denied";
+  }
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    typeof error.code === "string"
+  ) {
+    return "io-error";
+  }
+  return "unknown";
+}
+
+function recoveryFailureAlert(failure: AuditRecoveryFailure): string {
+  const detail = {
+    "permission-denied": "文件权限不足",
+    "invalid-format": "队列文件格式无效",
+    "io-error": "文件读写失败",
+    unknown: "未知错误",
+  } satisfies Record<AuditRecoveryFailure, string>;
+  return `关键审计恢复队列不可用：${detail[failure]}`;
+}

package/template/apps/web/Dockerfile

@@ -22,7 +22,7 @@ COPY packages/server-sdk/package.json packages/server-sdk/package.json
 COPY packages/shared/package.json packages/shared/package.json
 COPY packages/storage/package.json packages/storage/package.json
 # windy-copy:deps end
-RUN bun install --frozen-lockfile
+RUN --mount=type=cache,id=windy-bun-1.3.14,target=/root/.bun/install/cache,sharing=shared bun -e 'const child=Bun.spawn(["bun","install","--frozen-lockfile","--no-progress"],{stdin:"inherit",stdout:"inherit",stderr:"inherit"});const heartbeat=setInterval(()=>console.log("[windy] Bun 依赖安装仍在进行"),15000);const exitCode=await child.exited;clearInterval(heartbeat);process.exit(exitCode)'
 
 FROM deps AS build
 # windy-copy:build begin

package/template/docs/platform/audit-reliability.md

@@ -79,9 +79,19 @@ License 上传仍只记录候选摘要、可识别的 License ID、公钥 ID 和
 2. Server 启动、以及后续任一审计写入恢复成功时，会顺序重放队列。
 3. PostgreSQL 以事件 ID 幂等插入，连接超时后即使数据库实际已提交，重放也不会生成重复事件。
 4. 只有成功持久化的前缀会从队列移除；首次失败事件及其后续事件继续保留。
+5. 启动读取队列遇到权限、JSON 格式或其它文件 I/O 错误时，Server 仍以审计
+   `degraded` 状态启动并告警，不让审计恢复文件阻断全部无关业务。
+   未知 `formatVersion`、缺失或非数组 `events`、损坏的事件结构都属于格式错误；
+   平台不会把它们静默解释为空队列。
+6. 恢复故障只有在队列重新成功读取、且非空队列成功原子改写后才清除；单次普通审计
+   成功写入 PostgreSQL 不能把仍不可读的恢复队列误报为健康。
 
 恢复文件所在目录必须挂载到持久卷，并只允许 Server 运行账号访问。不要把它放到容器临时层、共享静态目录或备份公开目录。
 
+启动降级不改变两类写入策略：普通请求继续按 best-effort 审计语义执行；关键动作优先
+写 PostgreSQL，主库持续失败时再写恢复队列。只有主库与恢复队列同时不可用时，关键
+动作仍然 fail closed，不会因为 Server 已监听端口而降级放行。
+
 ## 可观测状态
 
 `GET /api/health` 的 `audit` 字段返回非敏感运行状态：
@@ -97,7 +107,9 @@ License 上传仍只记录候选摘要、可识别的 License ID、公钥 ID 和
   "dropped": 1,
   "lastFailureAt": "2026-07-10T08:00:00.000Z",
   "lastSuccessAt": "2026-07-10T07:59:00.000Z",
-  "alert": "关键审计已进入可恢复队列"
+  "recoveryFailure": "permission-denied",
+  "lastRecoveryFailureAt": "2026-07-10T08:00:01.000Z",
+  "alert": "关键审计恢复队列不可用：文件权限不足"
 }
 ```
 
@@ -105,6 +117,10 @@ License 上传仍只记录候选摘要、可识别的 License ID、公钥 ID 和
 - `retries` 是已经执行的重试次数。
 - `queued` 是当前仍待恢复的关键事件数。
 - `dropped` 是 PostgreSQL 持续失败后未进入持久队列的普通事件数。
+- `recoveryFailure` 是不包含路径或事件正文的稳定故障分类：
+  `permission-denied`、`invalid-format`、`io-error` 或 `unknown`。
+- `lastRecoveryFailureAt` 是最近一次恢复队列操作失败的时间；队列不可读时
+  `queued=0` 只代表没有已知计数，不能解释为文件内没有待恢复事件。
 - `state=degraded` 或 `queued/dropped > 0` 应触发运维告警。
 
 进入降级状态时 Server 同时写入结构化 error 日志，日志只包含上述状态，不包含事件正文。
@@ -130,10 +146,22 @@ License 上传仍只记录候选摘要、可识别的 License ID、公钥 ID 和
 
 1. 检查 `/api/health` 的 `audit` 状态和 Server 的“审计持久化进入降级状态”日志。
 2. 检查 PostgreSQL 连接、连接池容量、`audit_logs` 表和磁盘容量。
-3. 确认恢复文件所在持久卷可写、权限为 Server 账号私有，且队列未达到上限。
-4. 修复 PostgreSQL 后执行一个普通的已审计请求；写入成功会触发队列恢复。也可以重启 Server，在启动阶段恢复。
-5. 只有 `queued=0` 且状态恢复为 `healthy` 后才解除告警。`dropped` 是累计计数，不会自动归零，应结合故障窗口内的进程内事件和业务日志进行人工补查。
+3. 对恢复文件或持久卷先做只读备份或卷快照，再进行权限和内容处置。平台不会自动
+   丢弃、清空或覆盖不可读、格式损坏的队列，因为其中可能包含尚未落库的关键事件。
+4. `permission-denied` 时把目录和文件所有权恢复为 Server 运行账号，保持文件
+   `0600`、目录不对其它账号开放；不要用全局可写权限绕过问题。
+5. `invalid-format` 时保留原始备份，把损坏文件人工隔离到 Server 不会继续写入的位置，
+   离线核对可恢复事件后再修复或重建有效队列。未经审阅不要直接截断文件或创建空文件
+   覆盖原内容。
+6. `io-error` 时检查挂载、只读文件系统、磁盘容量和底层存储健康；修复后执行一个普通
+   的已审计请求触发恢复，也可以重启 Server 在启动阶段恢复。
+7. 只有 `recoveryFailure` 已清除、`queued=0` 且状态恢复为 `healthy` 后才解除告警。
+   `dropped` 是累计计数，不会自动归零，应结合故障窗口内的进程内事件和业务日志进行
+   人工补查。
 
 ## 验证覆盖
 
-自动测试覆盖瞬时故障后成功、退避上限、普通事件持续失败、关键事件入队、数据库恢复重放、数据库与队列同时失败、队列内容深层脱敏、License 损坏文件恢复上传入队，以及 PostgreSQL 事件 ID 幂等重放。真实 PostgreSQL 集成测试使用 `AUDIT_TEST_DATABASE_URL` 显式启用。
+自动测试覆盖瞬时故障后成功、退避上限、普通事件持续失败、关键事件入队、数据库恢复
+重放、启动读取权限错误和损坏 JSON 后降级、普通写入不得误清恢复故障、数据库与队列
+同时失败、队列内容深层脱敏、License 损坏文件恢复上传入队，以及 PostgreSQL 事件 ID
+幂等重放。真实 PostgreSQL 集成测试使用 `AUDIT_TEST_DATABASE_URL` 显式启用。

package/template/package.json

@@ -50,7 +50,7 @@
     "ops:db": "bun run scripts/production-database.ts",
     "ops:release": "bun run scripts/production-release.ts",
     "test:merge": "bun run scripts/merge-gate.ts",
-    "release:verify": "bun run scripts/release-verify.ts",
+    "release:verify": "bun run scripts/release-verify.ts --full",
     "release:candidate": "bun run scripts/release-candidate.ts",
     "release:verify:full": "bun run scripts/release-verify.ts --full",
     "test:packages:pack": "bun run scripts/platform-package-release.ts",
@@ -70,7 +70,8 @@
     "test": "bun test --path-ignore-patterns='packages/create-windy/template/**' && bun run --cwd apps/web test"
   },
   "lint-staged": {
-    "*.{cjs,css,cts,html,js,json,jsonc,jsx,less,md,mdx,mjs,mts,scss,ts,tsx,vue,yaml,yml}": [
+    "*.{css,html,json,jsonc,less,md,mdx,scss,yaml,yml}": "oxfmt --write",
+    "*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}": [
       "oxfmt --write",
       "oxlint"
     ]