create-windy 0.2.33 → 0.3.0

package/template/apps/web/src/services/notification-api.webtest.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import {
+  favoriteNotification,
+  getNotificationAudienceOptions,
+  getNotificationPreference,
+  listNotificationRevisions,
+  listNotifications,
+  unfavoriteNotification,
+  updateNotificationPreference,
+  updateNotification,
+} from "./notification-api";
+
+const mocks = vi.hoisted(() => ({
+  request: vi.fn(async () => ({ items: [], total: 0, page: 1, pageSize: 10 })),
+}));
+
+vi.mock("./http", () => ({ apiRequest: mocks.request }));
+
+describe("普通用户通知 API", () => {
+  beforeEach(() => {
+    mocks.request.mockClear();
+  });
+
+  test("旧分页调用保持原 URL 兼容", async () => {
+    await listNotifications(2, 20);
+
+    expect(mocks.request).toHaveBeenCalledWith(
+      "/notifications?page=2&pageSize=20",
+    );
+  });
+
+  test("关键词、分类、已读和收藏筛选统一编码到服务端查询", async () => {
+    await listNotifications(3, 15, {
+      q: "维护 窗口",
+      category: "系统/安全",
+      read: "unread",
+      favorite: false,
+    });
+
+    expect(mocks.request).toHaveBeenCalledWith(
+      "/notifications?page=3&pageSize=15&q=%E7%BB%B4%E6%8A%A4+%E7%AA%97%E5%8F%A3&category=%E7%B3%BB%E7%BB%9F%2F%E5%AE%89%E5%85%A8&read=unread&favorite=false",
+    );
+  });
+
+  test("收藏与取消收藏使用显式幂等方法", async () => {
+    await favoriteNotification("notice/1");
+    await unfavoriteNotification("notice/1");
+
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      1,
+      "/notifications/notice%2F1/favorite",
+      { method: "PUT" },
+    );
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      2,
+      "/notifications/notice%2F1/favorite",
+      { method: "DELETE" },
+    );
+  });
+
+  test("管理端修改公告并分页读取版本历史", async () => {
+    const input = {
+      title: "修改公告",
+      summary: "修改摘要",
+      content: "修改正文",
+      category: "系统",
+    };
+    await updateNotification("notice/1", input);
+    await listNotificationRevisions("notice/1", 2, 20);
+
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      1,
+      "/system/notifications/notice%2F1",
+      { method: "PUT", body: JSON.stringify(input) },
+    );
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      2,
+      "/system/notifications/notice%2F1/revisions?page=2&pageSize=20",
+    );
+  });
+
+  test("偏好和管理端受众选项走受 Guard 保护的稳定端点", async () => {
+    await getNotificationPreference();
+    await updateNotificationPreference({
+      enabledChannels: ["email"],
+      disabledCategories: ["营销"],
+    });
+    await getNotificationAudienceOptions();
+
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      1,
+      "/notifications/preferences",
+    );
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      2,
+      "/notifications/preferences",
+      {
+        method: "PUT",
+        body: JSON.stringify({
+          enabledChannels: ["email"],
+          disabledCategories: ["营销"],
+        }),
+      },
+    );
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      3,
+      "/system/notifications/audience-options",
+    );
+  });
+});

package/template/apps/web/src/services/search-api.ts

@@ -0,0 +1,39 @@
+import { apiRequest } from "./http";
+
+export interface SearchHit {
+  id: string;
+  resourceType: string;
+  maskedTitle: string;
+  maskedExcerpt?: string;
+  score?: number;
+  providerKey: string;
+  deepLink: {
+    surface: "business";
+    routeTemplate: string;
+    params: Record<string, string>;
+  };
+}
+
+export interface SearchResultGroup {
+  providerKey: string;
+  label: string;
+  hits: readonly SearchHit[];
+}
+
+export interface SearchResultPage {
+  groups: readonly SearchResultGroup[];
+  partial: boolean;
+  failures: Array<{
+    providerKey: string;
+    code: string;
+    message: string;
+  }>;
+}
+
+export function searchPlatform(query: string, signal?: AbortSignal) {
+  return apiRequest<SearchResultPage>("/search", {
+    method: "POST",
+    body: JSON.stringify({ query, limit: 8 }),
+    signal,
+  });
+}

package/template/apps/web/src/services/system-api.ts

@@ -154,3 +154,21 @@ export function quickCreateDepartment(payload: Record<string, unknown>) {
     body: JSON.stringify(payload),
   });
 }
+
+export function transitionDepartment(
+  departmentId: string,
+  payload: {
+    action: "disable" | "delete";
+    targetDepartmentId?: string;
+  },
+) {
+  return apiRequest<{
+    department: SystemRecord;
+    movedChildren: number;
+    movedUsers: number;
+    updatedRoles: number;
+  }>(`/system/departments/${departmentId}/transition`, {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}

package/template/apps/web/vitest.config.ts

@@ -9,6 +9,7 @@ export default mergeConfig(
       include: ["src/**/*.webtest.ts"],
       clearMocks: true,
       restoreMocks: true,
+      testTimeout: 15_000,
     },
   }),
 );

package/template/docker-compose.yml

@@ -46,6 +46,10 @@ services:
       AGENT_SERVER_URL: http://agent-server:8080
       AGENT_TOOL_HOST_URL: http://server:9747
       AGENT_SERVER_INTERNAL_TOKEN: ${AGENT_SERVER_INTERNAL_TOKEN:-}
+      OPENSEARCH_URL: ${OPENSEARCH_URL:-}
+      OPENSEARCH_USERNAME: ${OPENSEARCH_USERNAME:-}
+      OPENSEARCH_PASSWORD: ${OPENSEARCH_PASSWORD:-}
+      OPENSEARCH_WORK_ORDER_INDEX: ${OPENSEARCH_WORK_ORDER_INDEX:-windy-work-orders-v1}
     ports:
       - "9747:9747"
     volumes:
@@ -56,6 +60,29 @@ services:
       migrate:
         condition: service_completed_successfully
 
+  opensearch:
+    profiles: ["search"]
+    image: opensearchproject/opensearch:2.19.3
+    environment:
+      discovery.type: single-node
+      DISABLE_INSTALL_DEMO_CONFIG: "true"
+      DISABLE_SECURITY_PLUGIN: "true"
+      OPENSEARCH_JAVA_OPTS: "-Xms512m -Xmx512m"
+    ports:
+      - "127.0.0.1:19200:9200"
+    volumes:
+      - opensearch-data:/usr/share/opensearch/data
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "curl -fsS http://127.0.0.1:9200/_cluster/health?wait_for_status=yellow",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+
+
   agent-server:
     profiles: ["agent"]
     build:
@@ -64,6 +91,8 @@ services:
     environment:
       AGENT_SERVER_INTERNAL_TOKEN: ${AGENT_SERVER_INTERNAL_TOKEN:-}
       AGENT_RUN_STORE_PATH: /app/data/agent/runs.sqlite3
+      AI_PROVIDER_AUDIT_STORE_PATH: /app/data/agent/provider-audit.sqlite3
+      AI_PROVIDER_AUDIT_RETENTION_DAYS: ${AI_PROVIDER_AUDIT_RETENTION_DAYS:-90}
       QWEN_API_URL: ${QWEN_API_URL:-}
       QWEN_API_KEY: ${QWEN_API_KEY:-}
       QWEN_MODEL: ${QWEN_MODEL:-}
@@ -77,6 +106,44 @@ services:
       server:
         condition: service_started
 
+  adk-web-debug:
+    profiles: ["agent-debug"]
+    build:
+      context: .
+      dockerfile: apps/agent-server/Dockerfile
+    command:
+      [
+        "adk",
+        "web",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8000",
+        "--no-reload",
+        "--session_service_uri",
+        "memory://",
+        "--artifact_service_uri",
+        "memory://",
+        "--logo-text",
+        "Windy ADK 开发调试（无业务工具）",
+        "--logo-image-url",
+        "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E",
+        "/app/apps/agent-server/adk_web_agents",
+      ]
+    ports:
+      - "127.0.0.1:8000:8000"
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/', timeout=3)",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
   web:
     build:
       context: .
@@ -111,3 +178,4 @@ volumes:
   postgres-data:
   server-audit-data:
   agent-run-data:
+  opensearch-data:

package/template/docs/architecture/ai-egress.md

@@ -23,6 +23,27 @@ Operation 分别声明 Provider egress 与 Tool execution network policy：
     mode: "configured-endpoint",
     deploymentKey: "ai.openai-compatible",
   },
+  providerDataPolicy: {
+    inputFields: [
+      {
+        jsonPointer: "/question",
+        classification: "internal",
+        dlpAction: "redact",
+      },
+    ],
+    envelopeFields: [
+      {
+        field: "instructions",
+        classification: "internal",
+        dlpAction: "reject",
+      },
+      {
+        field: "user-prompt",
+        classification: "internal",
+        dlpAction: "redact",
+      },
+    ],
+  },
   toolNetworkPolicy: {
     mode: "forbidden",
   },
@@ -36,6 +57,14 @@ Operation 分别声明 Provider egress 与 Tool execution network policy：
   不能携带 URL、Host 或 Secret。
 - 当前 Tool 网络策略只支持 `forbidden`，缺省也是 `forbidden`。Provider egress 不会
   继承给 Tool。
+- `inputFields` 是业务 raw input 的 JSON Pointer allowlist。Server 先选择并执行 DLP，
+  再把最小输入交给业务 `prepare` Handler；未列字段不会进入 Handler、Agent Server
+  DTO 或 Provider 请求。
+- `envelopeFields` 是 Provider outbound envelope 的语义字段 allowlist，当前包含
+  `instructions`、`user-prompt`、`tool-definitions`、`provider-output` 和
+  `tool-results`。每轮实际发送前重新检查，字段遗漏或未知角色 fail closed。
+- `dlpAction=reject` 在命中后禁止发送；`redact` 使用固定占位符替换。内置检测覆盖
+  credential/token、Bearer、邮箱、手机号、身份证号和银行卡/长账号。
 
 ## Provider 强制执行
 
@@ -50,9 +79,25 @@ Key。Agent Server 在发出模型请求前核对：
 2. Deployment Key 必须等于当前 Adapter 的配置 Key；
 3. 启动时已验证配置 Endpoint 的 HTTPS Host allowlist；
 4. URL 仍来自 Agent Server 配置，Key 仍由 `SecretRef` 最后时刻解析。
+5. raw input 已按 JSON Pointer allowlist 最小化，outbound envelope 也命中显式字段规则；
+6. DLP 已完成且本次 Provider attempt 审计成功落库。
 
 浏览器 API、SSE、错误响应和 Web 环境均不包含 URL、Host allowlist 或 API Key。
 
+## Provider attempt 审计与留存
+
+OpenAI-compatible Adapter 不启用隐式 HTTP retry。每次
+`POST /chat/completions` 都对应唯一 `(runId, attempt)`，在打开网络请求前追加一条
+Provider 发送审计；审计失败即禁止该次请求。记录只包含 Deployment、Operation、
+Run、Attempt、分类集合、实际序列化 HTTP request body 字节数、策略决定和时间，不
+保存 prompt、body、Tool result、Provider response 或 Secret。
+
+`AI_PROVIDER_AUDIT_STORE_PATH` 必须在配置 Provider 时存在；
+`AI_PROVIDER_AUDIT_RETENTION_DAYS` 默认 90 天、范围 1 到 3650 天。记录在留存期内
+append-only，只有 TTL 清理可以删除过期行，并保留最近/累计删除计数。需要内部 Token
+的 `GET /health/provider-governance` 只返回聚合计数与时间，不返回 Run ID 或内容。
+当前 SQLite Adapter 只支持单副本；共享多副本必须换成集中式 append-only Adapter。
+
 ## Tool 强制执行
 
 短时 Execution Grant 保存宿主校验过的 Operation。每次 Tool 回调重新读取 Grant，并
@@ -65,16 +110,13 @@ Key。Agent Server 在发出模型请求前核对：
 
 ## 尚未覆盖
 
-本 patch 完成契约拆分、Provider 精确配置绑定、HTTPS Host allowlist 和拒绝回归，但
+当前实现完成契约拆分、Provider 精确配置绑定、字段 allowlist、DLP、逐 attempt 审计、
+TTL 与聚合观测，但
 不把以下能力宣称为已完成：
 
-- 现有 `dataClassification` 是 Operation 级分类，尚未提供字段级数据分类、发送字段
-  allowlist、脱敏或 DLP 检查；
-- 现有 Run 与 Tool 审计不等于逐次 Provider 发送审计；尚未记录目标 Deployment、
-  数据分类、字节数与策略决定的独立 append-only 事实；
 - 同进程 project-owned Tool Handler 不是 OS 网络沙箱。平台契约不授予网络 Port，
   但无法拦截业务代码直接调用全局 `fetch`；生产 deny-egress 仍需容器网络策略或防火墙；
 - DNS 解析钉扎、代理治理和多 Provider/多 Endpoint 动态路由尚未实现。
 
-在这些能力补齐前，只能声明“Provider 与 Tool 授权语义已隔离”，不能声明业务 Tool 已
-获得进程级强制断网或完整数据出境治理。
+不能声明业务 Tool 已获得进程级强制断网。DLP 是保守的模式检测，不替代行业专用实体
+识别、人工审批或部署侧代理/防火墙。

package/template/docs/architecture/ai-runtime.md

@@ -1,12 +1,14 @@
 # Southwind AI Runtime 架构
 
-更新时间：2026-07-25。
+更新时间：2026-07-26。
 
 状态：架构已确认，首个可消费的文本 Agent 切片已实现。当前包含 Module AI Operation
 注册、Guarded Run facade、短时 Execution Grant、受限 Tool Host、OpenAI-compatible
 Provider、canonical HTTP/SSE、取消、cursor 重放和单副本有界 SQLite Store。未配置
-Provider 时仍安全拒绝。ADK Workflow、LiteLLM 多 Provider 路由、PostgreSQL 多副本
-Store、Document AI 和 Speech 运行进程尚未实现，不能据此宣称完整 AI Runtime 已交付。
+Provider 时仍安全拒绝。真实业务 Run 已在内部使用 ADK 2.5 Runner、Session、LlmAgent
+和 Event，并把事件转换为既有 canonical signal。ADK Workflow、LiteLLM 多 Provider
+路由、PostgreSQL 多副本 Store、Document AI 和 Speech 运行进程尚未实现，不能据此
+宣称完整 AI Runtime 已交付。
 
 ## 目标
 
@@ -272,13 +274,32 @@ interface ModuleAiOperationDefinition {
     mode: "forbidden" | "configured-endpoint";
     deploymentKey?: string;
   };
+  providerDataPolicy?: {
+    inputFields: readonly {
+      jsonPointer: string;
+      classification: "public" | "internal" | "sensitive";
+      dlpAction: "reject" | "redact";
+    }[];
+    envelopeFields: readonly {
+      field:
+        | "instructions"
+        | "user-prompt"
+        | "tool-definitions"
+        | "provider-output"
+        | "tool-results";
+      classification: "public" | "internal" | "sensitive";
+      dlpAction: "reject" | "redact";
+    }[];
+  };
   toolNetworkPolicy?: {
     mode: "forbidden";
   };
 }
 ```
 
-两项缺省均 fail closed。Provider 的实际 Endpoint 与 HTTPS Host allowlist 只存在于
+Provider 与 Tool 网络策略缺省均 fail closed。configured Provider 还必须声明字段
+allowlist；业务 raw input 会在 Handler 前按 JSON Pointer 裁剪，outbound envelope 在
+每个 Provider attempt 前再次治理。Provider 的实际 Endpoint 与 HTTPS Host allowlist 只存在于
 服务端 Deployment 配置，不由业务 Manifest、浏览器或模型提供。详见
 [Agent Provider 与 Tool 网络边界](./ai-egress.md)。
 
@@ -624,6 +645,12 @@ type DictationEvent =
 
 ADK Web 只在 developer profile 启动，绑定 localhost 或受控开发网络。它不是生产 Prompt 管理或生产 Debug 控制面。
 
+当前 Compose 使用独立 `agent-debug` profile，宿主机只发布
+`127.0.0.1:8000`。由于原生 ADK Web 没有 Southwind AI Server 签发的 Actor 与
+Execution Grant，它只加载一个无 Provider、无业务 Tool 的确定性调试 Agent。真实业务
+Operation 只能走 canonical HTTP/SSE → ADK Adapter → 受治理 Provider/Tool Host 链路；
+不得把 ADK Web 的调试会话解释为生产授权或业务执行证据。
+
 Prompt 和 Workflow 使用：
 
 ```text
@@ -709,8 +736,9 @@ LiteLLM 版本必须固定并通过供应链审查，客户现场禁止动态安
 
 当前已完成第 1、2、4 项和第 5 项的受限 Tool Host 基础闭环，并交付可直接连接
 OpenAI-compatible Provider 的文本 Agent Adapter。SQLite Store 提供单副本有界持久化，
-重启后保留终态和 cursor，但不替代后续 PostgreSQL 多副本 Store。ADK unavailable
-Adapter 保留为未配置 Provider 时的 fail-closed fallback。
+重启后保留终态和 cursor，但不替代后续 PostgreSQL 多副本 Store。配置 Provider 后，
+文本与 Tool Run 由 ADK Runner/Session/Event 执行；未配置 Provider 时同一 Adapter
+fail closed。开发 ADK Web 已作为 localhost-only 的受控调试入口交付，不是业务入口。
 
 1. 定义 Agent、Document、Speech Operation 与 Module Manifest 组合校验；
 2. 建立 Python Agent Server、ADK Adapter 和 deterministic test Adapter；

package/template/docs/architecture/data-scope-query-enforcement.md

@@ -24,3 +24,7 @@ Core 只理解 ownership dimension 的稳定 key/value 契约，不知道下游
 通用资源路由的 `dataAccess` 是必填判别联合：资源必须明确声明 `request` 并提供 scoped access，或声明 `platform`，不能因漏配可选字段静默回退裸 Repository。V1 异步 bulk handler 只接受显式 `platform` 资源，由服务端构造 nominal `all` context；需要继承申请人数据范围的异步资源必须先设计不可篡改的 context snapshot，不允许套用当前平台模式。工单运营快照同样使用服务端平台任务 Actor，不再暴露或调用裸 Repository。
 
 Search Provider 只能在 D1–D3 全部闭环后接入，不得先用 Provider 内存裁剪冒充 Repository 级强制。
+
+业务模块用户目录同样复用这条 Repository 强制链。V1 `tenantId=single-tenant` 是宿主
+nominal `ScopeContext` 的明确固定租户，不是省略租户判断；业务调用方只提交分页与
+搜索，不能提交 Actor、tenant、department 或 scope。

package/template/docs/architecture/object-storage.md

@@ -2,7 +2,10 @@
 
 ## 模块与 seam
 
-`@southwind-ai/storage` 是平台文件能力的唯一底层模块。业务模块只学习 `BlobStore` 接口：流式写入、流式打开和删除；文件名、MIME、上传会话、Owner、权限与审计不进入这个底层接口，由上层上传模块统一处理。
+`@southwind-ai/storage` 是平台文件能力的唯一底层模块。`BlobStore` 只供平台 Storage
+实现使用：流式写入、流式打开和删除；文件名、MIME、上传会话、Owner、权限与审计不
+进入这个底层接口，由上层上传模块统一处理。可安装业务模块只学习
+`@southwind-ai/server-sdk` 的 `ModuleStoragePort`。
 
 `ArtifactRef` 使用 `blob_` 加 128 位随机值，不包含目录、租户或内容摘要，不能由业务主键推算。`ContentHash` 当前固定为 SHA-256。调用方可以声明大小和摘要，本地 Adapter 会在写入过程中验证；任何不一致都不会发布 Blob。
 
@@ -60,14 +63,29 @@ Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只
 
 ## 模块受限 Upload/BlobRead Port
 
-业务模块不直接使用 `UploadService` / `FileService`，而是经 `ModuleRequestContext.storage` 获得 `ModuleStoragePort`（宿主实现见 `apps/server/src/module-host/storage-port.ts`）：
+业务模块不直接使用 `UploadService` / `FileService`，而是经
+`ModuleRequestContext.storage` 或 `ModuleToolContext.storage` 获得
+`ModuleStoragePort`（宿主实现见 `apps/server/src/module-host/storage-port.ts`）：
 
 - `createUploadSession` 的 purpose 强制属于本模块经 Host 注册的 Upload Policy；跨模块用途和平台基础用途（如 `bulk-data`、`branding-logo`）一律以 `UPLOAD_FORBIDDEN` 拒绝。Owner 由宿主以当前 Actor 补齐，模块无法代他人创建会话。
 - `openFile` 走 `FileService.open` 的 Owner 约束，并在返回前校验文件用途属于本模块——即使是本人文件，用途越界也拒绝。
 - `openPublicFile` 走 `FileService.openPublic` 的 Purpose 约束，且只允许本模块已注册用途。
+- `openResourceFile` 用于同一业务范围内的跨上传者读取。模块必须先通过
+  `registerResourceFileAccessPolicies()` 为精确 `purpose + resourceType` 注册
+  project-owned 授权 Resolver，并绑定同 Manifest 的 Feature、Permission 与 Audit
+  Action。Host 每次调用都使用当前请求或 Tool grant 的 Actor 与服务端 ScopeContext
+  重跑 Guard；Resolver 必须从业务 Repository 回查 `resourceId -> fileId` 绑定和案件/
+  项目成员资格，客户端传入的 ID 不是授权证据。
+- 资源读取只返回 `id/purpose/filename/mimeType/byteSize/sha256/body`；不会返回
+  Owner、ArtifactRef、对象存储 Key 或 Repository。成功和拒绝都写稳定审计，仅记录
+  `resourceType/resourceId/fileId/purpose`，不记录文件名、路径或内容。
 - 模块不直接接触 `BlobStore` 或 Upload Repository；宿主未挂载存储服务时，任何访问都以明确错误失败，不静默绕过。
 
 用途唯一性仍在 Host 注册时全局校验：命名空间重叠的模块（如 `shop` 与 `shop.sub`）注册同一 purpose 会在启动时失败。
+资源策略的 purpose 必须由当前模块或其 Manifest 显式依赖模块的 Upload Policy 注册；
+这允许 `media -> evidence` 之类的明确消费者关系，但拒绝平台基础用途和未声明的跨模块
+读取。Feature、Permission、Audit Action 和 resourceType 仍必须属于当前消费者模块，
+任一未知或越界都会在监听前失败。
 
 ## 当前切片
 
@@ -75,3 +93,5 @@ Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只
 - F2：上传会话、分片续传、文件元数据、校验和清理已完成。
 - F3：服务端授权下载、审计、bulk artifact 与 Logo 接入已完成。
 - F4：模块受限 Upload/BlobRead Port 已完成，业务模块经 Host 注册用途并受命名空间约束。
+- F5：Route 与 Tool 共用资源绑定读取 Port，支持受审计、受数据范围约束的跨上传者
+  业务文件流读取，不扩散 Storage/Admin Repository。

package/template/docs/architecture/search-provider-protocol.md

@@ -4,7 +4,7 @@
 
 平台通过一个稳定的 `SearchService` 聚合业务搜索结果，但不读取业务模块 Repository，也不把用户输入转换成跨模块 SQL。业务模块通过 Manifest 声明 `kind: "search"` 的 Provider，并提供同 Key、同版本的 Handler。Composition Root 启动时要求声明与实现一一对应，未知 Handler、缺失 Handler、重复 Key、协议版本或 Provider 版本漂移都会 fail-fast。
 
-默认部署不引入 OpenSearch、Elasticsearch 或其它外部搜索引擎。小数据量模块可以实现 Repository Provider；将来若替换为可重建索引 Provider，平台协议、调用方与业务详情授权边界不变，业务数据库仍是事实源。
+默认部署不引入 OpenSearch、Elasticsearch 或其它外部搜索引擎。小数据量模块可以实现 Repository Provider；需要外部索引时可以显式启动 OpenSearch 开发 profile。两种实现共用同一 Provider 协议、调用方与业务详情授权边界，业务数据库始终是事实源。
 
 ## 深模块边界
 
@@ -48,11 +48,47 @@ Provider 只负责在自身模块边界内执行搜索。它接收平台从已
 - `SEARCH_PROVIDER_KEYS` 是逗号分隔的启动白名单；未配置时按 Manifest 的 `enabledByDefault` 启用，显式空字符串关闭全部 Provider，未知、重复或非法 Key 使启动失败。
 - `SEARCH_PROVIDER_TIMEOUT_MS`、`SEARCH_HEALTH_TIMEOUT_MS` 允许 10-5000 毫秒；`SEARCH_MAX_REQUESTS_PER_MINUTE` 允许 1-300。非整数或越界配置使启动失败，不能被静默截断或钳制。
 
+## Web 全局入口
+
+Header 的 `Ctrl/⌘ K` 全局搜索同时展示两类结果：
+
+- 平台导航在浏览器内只过滤 Admin Bootstrap 已下发且当前账号获准的菜单；
+- 业务数据只通过 `POST /api/search` 获取，并按 Manifest Provider 分组展示脱敏标题、摘要和业务深链。
+
+输入使用 250ms 延迟并在关键词变化或 Dialog 关闭时中止旧请求，避免迟到响应覆盖新结果。单个 Provider 超时或故障时显示“结果可能不完整”，其它 Provider 和菜单仍可使用。Web 不维护 Provider Key、目标权限或 Feature 的副本，也不接收 OpenSearch 地址和凭据。
+
+## 可选 OpenSearch Adapter
+
+根项目和包含 `system.search` 的 Starter 提供显式开发入口：
+
+```bash
+bun run dev:search
+```
+
+该命令设置容器内 `OPENSEARCH_URL=http://opensearch:9200`，并启动 Compose 的 `search` profile。普通 `bun run dev` 不设置地址，也不会启动或连接 OpenSearch。开发 profile 使用固定镜像、持久卷和健康检查；宿主端口只绑定 `127.0.0.1:19200`。`system.search` 被物理裁剪时，生成物同时移除 OpenSearch service、Server 环境变量、volume 和启动脚本。
+
+Server 可读取以下配置：
+
+- `OPENSEARCH_URL`：不含凭据、路径、查询参数的 HTTP(S) 根地址；未配置即使用原 Repository Provider；
+- `OPENSEARCH_USERNAME` / `OPENSEARCH_PASSWORD`：必须成对配置，只进入 Server 到 OpenSearch 的 Authorization Header；
+- `OPENSEARCH_REQUEST_TIMEOUT_MS`：100-30000ms，默认 3000ms；
+- `OPENSEARCH_WORK_ORDER_INDEX`：示例工单的可重建索引名，默认 `windy-work-orders-v1`。
+
+示例工单 Adapter 展示了项目业务层的正确接法：
+
+1. 第一次查询或索引失效后，从 PostgreSQL 事实源读取当前快照并重建索引；
+2. 创建、更新和归档成功后增量更新索引；OpenSearch 写失败只标记投影失效，不回滚已提交的业务事实；
+3. Provider 把服务端 `ScopeContext` 编译为 OpenSearch `term` / `terms` Filter，无授权分支使用 `match_none`；
+4. 命中 ID 返回前再次调用业务 Service 读取目标资源，防止陈旧索引绕过详情权限；
+5. 标题和摘要只从重新授权后的业务实体生成脱敏投影。
+
+这个 Compose profile 用于本地接入与回归，不是生产拓扑。生产环境应启用 OpenSearch TLS、认证、最小网络可达性、容量和快照策略；大规模增量索引应由项目自有 Outbox/Durable Job 驱动，不能把索引成功当成业务事务提交条件，也不能直接把开发 profile 暴露到客户网络。
+
 Composition Root 把 Server 实际注册的搜索 API 与 Provider Handler Key 一并交给 Module Composition 校验。没有业务 Provider 声明的项目允许 Core 以空 Registry 启动；只要 Manifest 与 Handler 不一致，启动就在监听端口前失败。
 
 ## 当前验证范围
 
-协议单元测试覆盖声明/实现/版本 fail-fast、启停与健康发现、目标权限裁剪、客户端不能扩大服务端身份和组织范围、分组与游标、Manifest 深链、明文响应拒绝、故障/超时隔离、部分失败、按 Actor 限流，以及审计中不出现原始查询词。Server API 测试另行覆盖入口权限先行、目标权限二次裁剪、Feature 关闭、只接受 POST body、稳定错误状态和直接 API 伪造身份/部门不能扩大 scoped Repository 结果。
+协议单元测试覆盖声明/实现/版本 fail-fast、启停与健康发现、目标权限裁剪、客户端不能扩大服务端身份和组织范围、分组与游标、Manifest 深链、明文响应拒绝、故障/超时隔离、部分失败、按 Actor 限流，以及审计中不出现原始查询词。Server API 测试另行覆盖入口权限先行、目标权限二次裁剪、Feature 关闭、只接受 POST body、稳定错误状态和直接 API 伪造身份/部门不能扩大 scoped Repository 结果。OpenSearch 测试覆盖默认关闭、配置拒绝、凭据只进入 Server 请求头、索引重建、范围 Filter 与无授权 `match_none`；Web 测试覆盖菜单检索、业务分组结果和深链跳转。
 
 示例 Work Order 已注册 `work-order.ticket.search`，Provider 只调用 `WorkOrderService.list`，后者把查询、count、分页与服务端 dataScope 一起交给 scoped Repository；测试会让裸 `Repository.list` 主动抛错，并确认本人范围不会返回其他负责人的匹配工单。另一个实现相同 Key/版本的测试 Provider 可以在不修改 Core 的情况下替换工单 Adapter。
 

package/template/docs/development/custom-error-pages.md

@@ -0,0 +1,78 @@
+# 业务项目定制错误页
+
+Windy 为 Web 提供统一的 404、500、维护中和网络异常页面，同时允许业务项目替换任意
+一种页面。业务选择入口是：
+
+```text
+apps/web/src/app/error-pages.ts
+```
+
+该文件在 `.windy/files.json` 中属于 `project-owned`。Windy 升级会给尚无此文件的
+项目创建默认选择器；文件存在后，后续更新只保留业务选择。平台默认页面
+`apps/web/src/pages/errors/PlatformErrorPage.vue` 属于 `windy-managed`，Router 和
+全局错误导航属于 `shared-scaffold`，业务项目不应为换视觉而修改这些文件。
+
+## 默认行为
+
+默认选择器让四种错误都使用平台页面：
+
+```ts
+import PlatformErrorPage from "@/pages/errors/PlatformErrorPage.vue";
+import { defineErrorPageComponents } from "@/pages/errors/error-page-extension";
+
+export const errorPageComponents = defineErrorPageComponents({
+  notFound: PlatformErrorPage,
+  internal: PlatformErrorPage,
+  maintenance: PlatformErrorPage,
+  network: PlatformErrorPage,
+});
+```
+
+错误来源与页面的稳定映射如下：
+
+| 来源                                                | 页面     |
+| --------------------------------------------------- | -------- |
+| Router 没有匹配业务路由                             | 404      |
+| Vue 渲染异常、Router 加载异常、HTTP 5xx（503 除外） | 500      |
+| HTTP 503                                            | 维护中   |
+| `fetch` 无法建立连接或传输中断                      | 网络异常 |
+
+HTTP 5xx 响应中的 `x-request-id` 会进入错误页，用户可将它直接提供给维护人员。调用方若
+要在当前交互内自行处理后台重试，可以给 `apiRequest` / `apiResponse` 传入
+`{ suppressFailureHandler: true }`，避免跳转全局错误页；这不改变原 Promise 的失败
+语义。
+
+## 替换业务页面
+
+把业务 SFC 放在 `apps/web/src/app/` 下，再只修改选择器。例如只替换网络异常页：
+
+```ts
+import NetworkErrorPage from "./NetworkErrorPage.vue";
+import PlatformErrorPage from "@/pages/errors/PlatformErrorPage.vue";
+import { defineErrorPageComponents } from "@/pages/errors/error-page-extension";
+
+export const errorPageComponents = defineErrorPageComponents({
+  notFound: PlatformErrorPage,
+  internal: PlatformErrorPage,
+  maintenance: PlatformErrorPage,
+  network: NetworkErrorPage,
+});
+```
+
+业务组件接收统一的只读 Props：
+
+```ts
+interface ErrorPageProps {
+  kind: "not-found" | "internal" | "maintenance" | "network";
+  from: string;
+  requestId?: string;
+}
+```
+
+`from` 已限制为站内绝对路径，错误页自身和外部 URL 会回退到 `/`。业务组件应使用
+文本插值展示地址和 Request ID，不使用 `v-html`；重试只导航到 `from`，不得把查询
+参数解释为外部链接。错误页是公共恢复入口，不应读取管理权限快照或把敏感信息写入
+页面。
+
+完整自定义也必须保留四个注册项。`defineErrorPageComponents` 会在 TypeScript 阶段
+检查 Key 是否齐全；Router 只依赖这个稳定导出，不感知业务组件实现。

package/template/docs/development/custom-login-page.md

@@ -78,9 +78,9 @@ composable。
 先提交当前业务改动并保持 Git 工作区干净，然后执行：
 
 ```bash
-bunx --bun create-windy@0.2.33 update --check --cwd .
-bunx --bun create-windy@0.2.33 update --dry-run --cwd .
-bunx --bun create-windy@0.2.33 update --cwd .
+bunx --bun create-windy@0.3.0 update --check --cwd .
+bunx --bun create-windy@0.3.0 update --dry-run --cwd .
+bunx --bun create-windy@0.3.0 update --cwd .
 bun install
 ```