create-windy 0.2.32 → 0.2.34

package/template/apps/web/src/router/index.ts

@@ -6,9 +6,9 @@ import {
 } from "vue-router";
 import DashboardPage from "@/pages/dashboard/DashboardPage.vue";
 import HomePage from "@/app/home/HomePage.vue";
+import { loginPageComponent } from "@/app/auth/login-page";
 import AccessDeniedPage from "@/pages/AccessDeniedPage.vue";
 import ServiceUnavailablePage from "@/pages/ServiceUnavailablePage.vue";
-import LoginPage from "@/pages/auth/LoginPage.vue";
 import ChangePasswordPage from "@/pages/auth/ChangePasswordPage.vue";
 // @windy-module system.license begin
 import LicensePage from "@/pages/license/LicensePage.vue";
@@ -72,7 +72,7 @@ export const routes: RouteRecordRaw[] = [
   {
     path: "/login",
     name: "login",
-    component: LoginPage,
+    component: loginPageComponent,
     meta: { title: "登录", layout: "auth", public: true, guestOnly: true },
   },
   {

package/template/apps/web/src/router/shared-scaffold-neutrality.webtest.ts

@@ -5,10 +5,11 @@ import fixtureSource from "./router-test-fixtures.ts?raw";
 import { collectRouteAccess } from "./router-test-fixtures";
 
 describe("Router shared-scaffold 中性契约", () => {
-  test("平台登录页使用中性共享页面", () => {
+  test("平台登录路由使用 project-owned 业务选择 seam", () => {
     expect(routerSource).toContain(
-      'import LoginPage from "@/pages/auth/LoginPage.vue";',
+      'import { loginPageComponent } from "@/app/auth/login-page";',
     );
+    expect(routerSource).toContain("component: loginPageComponent");
     expect(fixtureSource).toContain("collectRouteAccess");
   });
 

package/template/docker-compose.yml

@@ -64,6 +64,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:-}

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

@@ -272,13 +272,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)。
 

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/development/custom-login-page.md

@@ -0,0 +1,90 @@
+# 业务项目定制登录页
+
+Windy 允许业务项目替换完整登录页，但认证、会话和跳转安全仍复用平台能力。扩展入口是：
+
+```text
+apps/web/src/app/auth/login-page.ts
+```
+
+该文件在 `.windy/files.json` 中属于 `project-owned`。Windy 升级会为旧项目新增它，
+但一旦文件存在，后续 `windy update` 只会保留，不会覆盖业务选择。平台默认登录页
+`apps/web/src/pages/auth/LoginPage.vue` 仍是 `windy-managed`，Router 仍是
+`shared-scaffold`；业务项目不应直接修改这两处。
+
+## 默认行为
+
+新项目和未定制的升级项目默认把 selector 指向平台登录页，因此视觉、品牌设置、开发
+认证提示和认证流程与原有 Windy 体验一致：
+
+```ts
+import PlatformLoginPage from "@/pages/auth/LoginPage.vue";
+import { defineLoginPageComponent } from "@/pages/auth/login-page-extension";
+
+export const loginPageComponent = defineLoginPageComponent(PlatformLoginPage);
+```
+
+`defineLoginPageComponent` 是类型化 Composition seam。Router 只消费这个稳定导出，
+不感知具体业务页面。
+
+## 完整业务页面
+
+将业务页面放在同一个 project-owned 目录，例如
+`apps/web/src/app/auth/SharpSwordLoginPage.vue`，然后只修改 selector：
+
+```ts
+import SharpSwordLoginPage from "./SharpSwordLoginPage.vue";
+import { defineLoginPageComponent } from "@/pages/auth/login-page-extension";
+
+export const loginPageComponent = defineLoginPageComponent(SharpSwordLoginPage);
+```
+
+业务 SFC 使用 Vue 3 Composition API 和 TypeScript。认证提交必须复用
+`useLoginFlow()`，不要直接复制登录 API 或解析 `returnTo`：
+
+```vue
+<script setup lang="ts">
+import DevelopmentAuthWarning from "@/components/auth/DevelopmentAuthWarning.vue";
+import LoginForm from "@/components/auth/LoginForm.vue";
+import { useLoginFlow } from "@/composables/useLoginFlow";
+import { developmentAuthStatus } from "@/services/http";
+
+const flow = useLoginFlow();
+const developmentAuth = developmentAuthStatus();
+</script>
+
+<template>
+  <main>
+    <DevelopmentAuthWarning v-if="developmentAuth.configured" />
+    <LoginForm
+      :loading="flow.loading.value"
+      :error="flow.submitError.value"
+      @submit="flow.submit"
+    />
+  </main>
+</template>
+```
+
+`useLoginFlow` 负责调用真实账号认证、重置 Access/License/Session 派生状态，并通过
+`safeReturnTo` 只允许站内目标。它会拒绝外部 URL、协议相对 URL、反斜杠、控制字符、
+过长路径和登录页自循环。真实密码登录还会停用开发 Bearer Token；自定义页面应继续
+显示 `DevelopmentAuthWarning`，避免把本地直通误认为生产认证。
+
+品牌名、Logo 和说明可以通过 `usePlatformSettings()` 复用。业务页面可以完全重做
+布局和内容，但不应绕过 Router 的 `guestOnly` Guard、首次改密跳转或平台认证
+composable。
+
+## 从 0.2.32 升级
+
+先提交当前业务改动并保持 Git 工作区干净，然后执行：
+
+```bash
+bunx --bun create-windy@0.2.34 update --check --cwd .
+bunx --bun create-windy@0.2.34 update --dry-run --cwd .
+bunx --bun create-windy@0.2.34 update --cwd .
+bun install
+```
+
+计划中应看到 selector 以 `project-owned` 新增，Router 通过三方合并接入 selector。
+若旧业务登录页曾放在 `apps/web/src/pages/auth/LoginPage.vue` 或直接改 Router，应将
+业务 SFC 移到 `apps/web/src/app/auth/`，改 selector 指向它，再恢复受管文件。后续升级
+会保留 selector 和业务 SFC。

package/template/docs/platform/agent-runtime.md

@@ -37,12 +37,34 @@ providerEgress: {
   mode: "configured-endpoint",
   deploymentKey: "ai.openai-compatible",
 },
+providerDataPolicy: {
+  inputFields: [
+    {
+      jsonPointer: "/content",
+      classification: "internal",
+      dlpAction: "redact",
+    },
+  ],
+  envelopeFields: [
+    {
+      field: "instructions",
+      classification: "internal",
+      dlpAction: "reject",
+    },
+    {
+      field: "user-prompt",
+      classification: "internal",
+      dlpAction: "redact",
+    },
+  ],
+},
 toolNetworkPolicy: {
   mode: "forbidden",
 },
 ```
 
-Provider URL 与 Secret 不在 Manifest 或浏览器 DTO 中；Agent Server 只允许当前启动
+Provider URL 与 Secret 不在 Manifest 或浏览器 DTO 中；Server 只把 `inputFields`
+选出的治理后输入交给 Handler，Agent Server 只允许当前启动
 配置的 Deployment。Tool policy 缺省为 forbidden，且不继承 Provider egress。完整
 威胁模型、兼容行为与尚未覆盖项见
 [Agent Provider 与 Tool 网络边界](../architecture/ai-egress.md)。
@@ -104,6 +126,7 @@ QWEN_API_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
 QWEN_API_KEY=<服务端密钥>
 QWEN_MODEL=qwen-plus
 AI_PROVIDER_HTTPS_HOST_ALLOWLIST=dashscope-intl.aliyuncs.com
+AI_PROVIDER_AUDIT_RETENTION_DAYS=90
 
 # 可选安全上限
 # AI_PROVIDER_CONNECT_TIMEOUT_MS=5000
@@ -125,10 +148,30 @@ bun run dev:agent
 ```text
 GET http://agent-server:8080/health/live
 GET http://agent-server:8080/health/ready
+GET http://agent-server:8080/health/provider-governance
 ```
 
 `ready` 会访问 Provider 的 `/models`。失败只返回稳定错误，不回显 Provider body、
 Authorization、Secret、Endpoint query 或底层异常文本。
+`provider-governance` 需要内部 Bearer Token，只返回留存、允许/拒绝/脱敏和 TTL 清理
+聚合，不返回 Run ID、prompt 或正文。
+
+## 字段治理迁移
+
+启用 `providerEgress.mode=configured-endpoint` 的既有业务 Operation 必须同时新增
+`providerDataPolicy`。升级后缺少策略会在 Manifest Composition 阶段以
+`Provider 字段发送 allowlist 缺失` fail fast，不会静默发送或降级放行。
+
+迁移时先枚举业务 input schema 中确实需要出境的最小 JSON Pointer；为每个字段声明
+分类与 `reject/redact`。再枚举 outbound envelope：无 Tool 的单轮问答通常只需要
+`instructions` 和 `user-prompt`；Tool schema、模型上一轮 Tool Call 和 Tool result
+分别需要 `tool-definitions`、`provider-output`、`tool-results`。不要为消除启动错误
+一次性允许全部字段。原始 input 会在进入 `prepare` 前裁剪，因此 Handler 必须只依赖
+allowlist 中的字段。
+
+Agent profile 还必须挂载 `AI_PROVIDER_AUDIT_STORE_PATH`。create-windy Starter 使用
+`/app/data/agent/provider-audit.sqlite3` 并复用单副本持久卷；自行维护 Compose 的项目
+需要显式补齐该变量。未配置时 Provider 启动 fail closed，并给出缺失变量名。
 
 ## 客户端协议
 

package/template/docs/platform/business-user-directory.md

@@ -0,0 +1,82 @@
+# 业务模块只读用户目录
+
+## Ownership 与 Seam
+
+用户账号、启停状态、部门关系和数据范围属于 `system.identity`。业务模块需要选择案件
+成员、协作人或负责人时，不得导入 Admin Repository、Drizzle schema 或 Server 内部
+`RequestActor`。稳定 seam 是 `ModuleRequestContext.userDirectory`，其公开 Interface
+只有一个方法：
+
+```ts
+const page = await context.userDirectory.list({
+  page: 1,
+  pageSize: 20,
+  q: "张",
+});
+// page.items: Array<{ id: string; displayName: string }>
+```
+
+这个深 Module 把授权、范围、状态过滤、搜索、分页、投影和审计藏在宿主 Adapter 中，
+业务调用方只需学习查询条件与稳定错误码。删除该 Module 会迫使每个业务模块重复实现
+同一组安全约束，因此该 seam 提供了跨模块的 leverage 和维护 locality。
+
+## 安全不变量
+
+- Actor、租户、部门和 Data Scope 只来自已验证请求的宿主
+  `RequestGuardContext`。Interface 不接受这些字段；HTTP body/query 中同名字段不能覆盖。
+- V1 的 `tenantId` 是宿主 nominal `ScopeContext` 中的固定
+  `single-tenant`，不是忽略租户。`tenant` grant 仍经 Repository predicate 执行；未来
+  多租户只替换宿主 Adapter，不扩大业务 Interface。
+- `all`、`tenant`、`department`、`department-and-children`、`custom` 和 `self`
+  都编译为用户 Repository 的查询条件，与启用状态、搜索、count 和分页共用同一个
+  `WHERE`。缺少 nominal `ScopeContext` 时返回 `data-scope-denied`，不会回退全量。
+- 只返回启用、未删除用户的 `id` 和 `displayName`。部门、用户名、联系方式、角色、
+  凭据状态和审计字段不跨 seam 暴露。
+- 调用者必须同时具备启用的 `system.user-directory` Feature 和
+  `system.user-directory.read` Permission。拒绝走统一 `security.denied` 审计。
+- 每次成功查询在返回结果前以 critical 策略持久化
+  `system.user-directory.query`，元数据只含页码、页大小、结果数和总数，不记录搜索词
+  或返回用户明细；生产审计不可用时查询 fail closed。
+- 页码与页大小必须为正整数；页码最多 10000、页大小最多 100，搜索词必须是最多 100
+  字符的字符串。非法输入返回 `USER_DIRECTORY_INVALID_QUERY`。
+
+## 业务角色接入
+
+业务 `ModuleRolePreset` 只能注册本模块命名空间内的 Permission，不能夹带
+`system.user-directory.read` 绕过平台 ownership。部署管理员应在角色管理中显式为
+需要选择用户的办案角色授予该平台 Permission，并根据角色配置 `all`、`tenant`、
+部门、`custom` 或 `self` 数据范围。
+
+业务 Handler 不要把浏览器提交的 `actorId`、`tenantId`、`departmentId` 或 scope
+转发为授权参数：
+
+```ts
+handler: async (context) => {
+  const page = await context.userDirectory.list({
+    page: Number(context.query.page || 1),
+    pageSize: Number(context.query.pageSize || 20),
+    q: context.query.q,
+  });
+  return page;
+};
+```
+
+未挂载平台 Adapter 时返回 `USER_DIRECTORY_UNAVAILABLE`；Permission 或 Feature 拒绝
+返回 `USER_DIRECTORY_FORBIDDEN`。业务路由可以把稳定错误码映射为自己的 HTTP 错误
+语义，但不得捕获后改用 Admin 用户接口或裸 Repository。
+
+## 生成与升级
+
+`packages/server-sdk` 的 Interface、Server Adapter、Composition Root、Manifest、
+本文件和 Starter skill 都是 Windy 模板受管内容。新项目自动生成这些文件；既有项目
+由 `windy update` 通过 Base/Ours/Theirs 创建新增文件并合并 Composition Root。
+升级后由管理员授予 Permission，再由 project-owned 业务 Handler 调用 Port；升级器
+不会自动修改客户业务角色或业务页面。
+
+运维排查顺序：
+
+1. 确认 `system.user-directory` 在 Feature 管理中启用；
+2. 确认 Actor 拥有 `system.user-directory.read`；
+3. 检查 Actor 的角色数据范围与部门关系；
+4. 查询 `security.denied` 和 `system.user-directory.query` 审计；
+5. 若返回 `USER_DIRECTORY_UNAVAILABLE`，检查 Starter Composition Root 是否完成升级。

package/template/docs/platform/platform-shell-settings.md

@@ -54,29 +54,34 @@
 - 页面入口：全局设置 / 页面水印，不注册独立 Sidebar 菜单
 
 水印是平台级强制策略，不是用户偏好。`PlatformWatermarkPolicy` 包含总开关
-`enabled`、业务页范围开关 `businessPagesEnabled` 与最长 80 字符的
-`customContent`。策略由 Admin 的全局设置页面维护，写入
+`enabled`、默认开启的业务页范围开关 `businessPagesEnabled`、`low / medium / high`
+密度、内容字段勾选与最长 80 字符的 `customContent`。可选内容为用户名、姓名、手机号、
+邮箱和自定义内容，至少保留一项；缺少已勾选的用户资料时不会渲染空片段，所有选项均无值时
+兜底使用用户名。策略由 Admin 的全局设置页面维护，写入
 `platform_watermark_policies`；每次保存都记录 `config.update` 审计，目标为
 `platform-watermark/platform`。用户应用端没有水印开关，也不使用 localStorage
 保存或覆盖策略。
 
 管理接口 `GET/PUT /api/system/settings/watermark` 分别经过
 `system.watermark.read/manage`、Feature 与 License Guard。业务应用通过公开只读接口
-`GET /api/platform/watermark-policy` 获取相同策略；公开响应只包含三个非敏感策略字段。
+`GET /api/platform/watermark-policy` 获取相同策略；公开响应只包含上述非敏感策略字段。
 Feature 最终有效且 `enabled=true` 时 Admin 页面显示水印；业务页面还要求
 `businessPagesEnabled=true`。Admin 设置区本身仍要求读取权限，但普通业务用户不需要
 水印读取权限，也不能覆盖全局策略。
 
-`customContent` 留空时，客户端从当前 Actor 派生身份水印，顺序为用户名加手机、邮箱或
-姓名；填写后所有用户显示相同的管理员指定内容。水印通过 Vue `Teleport` 直接挂到
-`body`，脱离应用壳的层叠上下文；稳定审计顶层类 `z-[60]` 高于平台统一使用的
+客户端按管理员勾选顺序从当前 Actor 派生身份水印，自定义内容只有被勾选时才加入。
+渲染算法先按字符视觉宽度自动换行，再根据旋转后文本包围盒与密度预设计算 SVG 平铺
+单元尺寸；每个单元都包含额外横纵安全间距，因此长文本和高密度模式不会让相邻水印重叠。
+水印通过 CSS Mask 平铺并由 Vue `Teleport` 直接挂到 `body`，脱离应用壳的层叠上下文；
+稳定审计顶层类 `z-[60]` 高于平台统一使用的
 `z-50` Sidebar、Drawer、Overlay 与 Modal，并配合 `isolate`、`transform-gpu`
 保证截图审计信息不会被浮层遮住。容器必须始终保留 `pointer-events-none` 与
 `aria-hidden=true`，不能阻塞点击或进入辅助技术阅读顺序。
 
-数据库迁移 `0031_panoramic_typhoid_mary.sql` 新增策略表。历史版本只保存过浏览器偏好，
-没有可自动提升为全局策略的服务端真源；升级后采用默认策略（总开关开启、业务页关闭），
-管理员应在全局设置中确认范围并保存一次。
+数据库迁移 `0031_panoramic_typhoid_mary.sql` 新增策略表，
+`0034_funny_mesmero.sql` 新增密度与内容字段。升级时，已有自定义文字的策略自动迁移为
+勾选“自定义内容”，避免改变既有展示；其它已有策略采用中密度与“用户名 + 姓名”。
+未持久化策略采用默认值（总开关开启、业务页开启、中密度、用户名加姓名）。
 
 ## 个人设置
 

package/template/docs/platform/web-system-crud.md

@@ -83,7 +83,7 @@ VITE_DEV_ADMIN_TOKEN=<显式开发 Token>
 - Feature 管理页在列表最右侧操作栏直接显示启停开关，不再打开通用编辑弹窗；修改仍调用受 Guard 和关键审计保护的 Server API。
 - Feature 开关成功修改会写入 `feature.update`，可在审计日志页通过“功能开关变更”直接查看。
 - 系统资源表和字典后台任务表加载时保留表头与列宽，并显示带 `animate-pulse` 的骨架行；加载失败和空数据仍使用各自独立状态。
-- 全局水印默认开启，内容按“用户名 + 手机号 / 邮箱 / 姓名”的顺序从当前会话 Actor 派生。管理员在“全局设置”中维护持久化的总开关、业务页面范围和最多 80 个字符的自定义内容；保存写入审计并立即成为所有用户的只读策略。用户应用端不提供开关，也不使用 localStorage。`system.watermark` Feature 控制最终生效态，管理区另需 `system.watermark.read/manage` 权限。水印使用专用审计顶层覆盖 Sidebar、Drawer、Overlay 和 Modal，同时保持 `pointer-events-none`。服务端只向当前用户自己的会话响应补充这些身份字段。
+- 全局水印与业务页面范围默认开启。管理员在“全局设置”中维护总开关、低/中/高密度，并勾选用户名、姓名、手机号、邮箱或最多 80 个字符的自定义内容；保存写入审计并立即成为所有用户的只读策略。客户端按旋转文本包围盒自动计算平铺尺寸与安全间距，长内容和高密度模式也不会相互重叠。用户应用端不提供开关，也不使用 localStorage。`system.watermark` Feature 控制最终生效态，管理区另需 `system.watermark.read/manage` 权限。水印使用专用审计顶层覆盖 Sidebar、Drawer、Overlay 和 Modal，同时保持 `pointer-events-none`。服务端只向当前用户自己的会话响应补充这些身份字段。
 - 站内通知由 PostgreSQL `platform_notifications` 和 `notification_reads` 持久化；管理人员可在 `/system/notifications` 广播发布和归档，用户从 Header 收件箱阅读正文并幂等写入已读回执。归档是生命周期操作，不物理删除通知或回执。当前发布范围是全体有阅读权限的用户，尚未提供组织、角色、用户定向和外部渠道投递。
 - 字典页已切换为后台 NDJSON 导入导出，展示本人任务状态、进度、重试和终态文件下载；其它系统资源仍保留小数据同步 JSON 入口。详细契约见 [批量导入导出后台任务](./bulk-data-jobs.md)。当前 artifact 存在 10 MiB、50,000 行和 256 KiB 单行上限，扩大容量前需要对象存储 Adapter。
 - 审计日志配置 `DATABASE_URL` 后读取 PostgreSQL `audit_logs`。可靠写入器提供有界重试、降级状态、关键事件本地恢复队列和健康信息；页面仍只读，且不会展示恢复队列中的事件正文。

package/template/packages/database/drizzle/0034_funny_mesmero.sql

@@ -0,0 +1,5 @@
+ALTER TABLE "platform_watermark_policies" ADD COLUMN "density" varchar(16) DEFAULT 'medium' NOT NULL;--> statement-breakpoint
+ALTER TABLE "platform_watermark_policies" ADD COLUMN "content_fields" jsonb DEFAULT '["username","displayName"]'::jsonb NOT NULL;--> statement-breakpoint
+UPDATE "platform_watermark_policies"
+SET "content_fields" = '["custom"]'::jsonb
+WHERE btrim("custom_content") <> '';