create-windy 0.3.19 → 0.4.0

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

@@ -2,6 +2,7 @@ import { describe, expect, test } from "vitest";
 import type { RouteRecordRaw } from "vue-router";
 import routerSource from "./index.ts?raw";
 import fixtureSource from "./router-test-fixtures.ts?raw";
+import compositionSource from "../app/web-composition.ts?raw";
 import { collectRouteAccess } from "./router-test-fixtures";
 
 describe("Router shared-scaffold 中性契约", () => {
@@ -25,16 +26,21 @@ describe("Router shared-scaffold 中性契约", () => {
     expect(routerSource).toContain("component: errorPageComponents.network");
   });
 
-  test("平台路由组合 project-owned 业务注册表且保持在兜底页之前", () => {
+  test("平台路由组合 project-owned Admin UI 声明且保持在兜底页之前", () => {
     expect(routerSource).toContain(
-      'import { installedBusinessAdminRoutes } from "@/app/business-routes";',
+      'import { webAdminUiComposition } from "./web-composition-host";',
     );
     const businessIndex = routerSource.indexOf(
-      "...materializeBusinessAdminRoutes(installedBusinessAdminRoutes)",
+      "...materializeBusinessAdminRoutes(webAdminUiComposition.modules)",
+    );
+    const fallbackIndex = routerSource.indexOf(
+      "path: reservedWebRoutePaths.notFound",
     );
-    const fallbackIndex = routerSource.indexOf('path: "/:pathMatch(.*)*"');
     expect(businessIndex).toBeGreaterThan(0);
     expect(businessIndex).toBeLessThan(fallbackIndex);
+    expect(compositionSource).toContain("defineWebComposition");
+    expect(compositionSource).not.toContain("featureKey");
+    expect(compositionSource).not.toContain("permissionKey");
   });
 
   test("测试快照只从项目注入路由递归派生访问键", () => {

package/template/apps/web/src/router/web-composition-host.ts

@@ -0,0 +1,20 @@
+import {
+  systemAdminUiManifests,
+  validateProjectModuleAssembly,
+} from "@southwind-ai/modules/admin-ui";
+import { installedAdminUiModules } from "virtual:windy-admin-ui-modules";
+import moduleAssembly from "../../../../windy.modules.json";
+import { webComposition } from "../app/web-composition";
+import { resolveAdminUiComposition } from "./admin-ui-composition";
+
+/**
+ * Host 对项目组合声明的唯一解析入口。
+ *
+ * Router、Navigation 和 Vite 构建门禁必须消费同一结果，避免运行时与构建时规则漂移。
+ */
+export const webAdminUiComposition = resolveAdminUiComposition({
+  declaration: webComposition,
+  assembly: validateProjectModuleAssembly(moduleAssembly),
+  platformModules: systemAdminUiManifests(),
+  installedModules: installedAdminUiModules,
+});

package/template/apps/web/src/services/work-order-api.ts

@@ -0,0 +1,16 @@
+import type {
+  WorkOrderListQuery,
+  WorkOrderPage,
+} from "@southwind-ai/example-work-order/contract";
+import { apiRequest } from "./http";
+
+export function listWorkOrders(query: WorkOrderListQuery = {}) {
+  const params = new URLSearchParams();
+  if (query.page !== undefined) params.set("page", String(query.page));
+  if (query.pageSize !== undefined) {
+    params.set("pageSize", String(query.pageSize));
+  }
+  if (query.q?.trim()) params.set("q", query.q.trim());
+  const search = params.toString();
+  return apiRequest<WorkOrderPage>(`/work-orders${search ? `?${search}` : ""}`);
+}

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

@@ -0,0 +1,21 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  request: vi.fn(),
+}));
+
+vi.mock("./http", () => ({ apiRequest: mocks.request }));
+
+import { listWorkOrders } from "./work-order-api";
+
+describe("示例工单 API", () => {
+  beforeEach(() => mocks.request.mockReset());
+
+  test("列表查询保留分页与搜索条件", () => {
+    listWorkOrders({ page: 2, pageSize: 20, q: "登录" });
+
+    expect(mocks.request).toHaveBeenCalledWith(
+      "/work-orders?page=2&pageSize=20&q=%E7%99%BB%E5%BD%95",
+    );
+  });
+});

package/template/apps/web/src/virtual-admin-ui-modules.d.ts

@@ -0,0 +1,5 @@
+declare module "virtual:windy-admin-ui-modules" {
+  import type { AdminUiModule } from "./router/admin-ui-composition";
+
+  export const installedAdminUiModules: readonly AdminUiModule[];
+}

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

@@ -1,16 +1,37 @@
+import { spawnSync } from "node:child_process";
 import { fileURLToPath, URL } from "node:url";
 import tailwindcss from "@tailwindcss/vite";
 import vue from "@vitejs/plugin-vue";
 import { defineConfig } from "vite";
+import moduleAssembly from "../../windy.modules.json";
+import { validateProjectModuleAssembly } from "../../packages/modules/src/project-module-assembly";
 import { projectFingerprint, windyDevIdentityPlugin } from "./dev/dev-identity";
+import { adminUiCompositionValidationPlugin } from "./src/router/admin-ui-composition-plugin";
+import { adminUiModuleRegistryPlugin } from "./src/router/admin-ui-module-registry-plugin";
 
 const fingerprint =
   process.env.WINDY_DEV_FINGERPRINT || projectFingerprint(process.cwd());
 const devPort = Number(process.env.WINDY_DEV_PORT || 8_746);
 const usePolling = process.env.WINDY_DEV_USE_POLLING === "1";
+const adminUiValidatorEntry = fileURLToPath(
+  new URL("./scripts/validate-admin-ui-composition.ts", import.meta.url),
+);
 
 export default defineConfig({
-  plugins: [vue(), tailwindcss(), windyDevIdentityPlugin(fingerprint)],
+  plugins: [
+    adminUiModuleRegistryPlugin(validateProjectModuleAssembly(moduleAssembly)),
+    adminUiCompositionValidationPlugin({
+      validatorEntry: adminUiValidatorEntry,
+      runValidator: (entry) => {
+        const result = spawnSync("bun", [entry], { stdio: "inherit" });
+        if (result.error) throw result.error;
+        return result.status ?? 1;
+      },
+    }),
+    vue(),
+    tailwindcss(),
+    windyDevIdentityPlugin(fingerprint),
+  ],
   resolve: {
     alias: {
       "@": fileURLToPath(new URL("./src", import.meta.url)),

package/template/docs/architecture/migration-bundle.md

@@ -1,6 +1,6 @@
 # Migration Bundle 契约
 
-更新时间：2026-07-25。
+更新时间：2026-07-29。
 
 ## 目标与边界
 
@@ -22,8 +22,9 @@ Migration Bundle 是模块级的数据库迁移机制：业务模块把迁移作
 - `formatVersion`：固定为 `"1"`，其它版本直接拒绝；
 - `module` / `version`：必须与 Manifest 的 `name` / `version` 完全一致，
   `version` 必须是 semver（`x.y.z`，允许预发布后缀）；
-- `dependencies`：可选，声明本模块依赖的其它模块，必须与 Manifest `dependencies`
-  一致；被依赖模块当前也必须携带 Bundle，否则按“依赖未安装模块”拒绝；
+- `dependencies`：可选，只声明 DDL 排序所需的其它 Migration Bundle，必须是
+  Manifest `dependencies` 的子集；Manifest 可以额外声明没有数据库迁移关系的运行时
+  依赖。Bundle 中的每个依赖当前都必须携带 Bundle，否则按“依赖未安装模块”拒绝；
 - `migrations`：`BundleMigrationDefinition` 列表，字段为 `id`、`module`、
   `description`、`direction`、`checksum`、可选 `dependsOn` 和 `run(context)`。
 
@@ -43,9 +44,9 @@ Migration Bundle 是模块级的数据库迁移机制：业务模块把迁移作
 （不依赖 drizzle），`@southwind-ai/database` 的 runner 与
 `@southwind-ai/modules` 的启动校验共用同一份实现：
 
-- `normalizeManifestBundles(modules)`：校验 Bundle 与 Manifest 的
-  module/version/dependencies/migrations 完全一致，且 `schemaExports` 只引用
-  Bundle 中存在的 Migration；
+- `normalizeManifestBundles(modules)`：校验 Bundle 与 Manifest 的 module/version
+  一致、Bundle dependencies 是 Manifest runtime dependencies 的子集、migrations
+  一致，且 `schemaExports` 只引用 Bundle 中存在的 Migration；
 - `validateAndOrderBundles(bundles)`：拒绝格式版本不支持、非 semver 版本、
   重复模块、重复 Migration ID、未声明的跨模块 `dependsOn`，并对模块依赖做
   拓扑排序，循环依赖即抛错；
@@ -64,7 +65,9 @@ Migration Bundle 是模块级的数据库迁移机制：业务模块把迁移作
    才把显式 Bundle 交给 PostgreSQL runner。
 
 示例：`packages/example-work-order` 的 `workOrderMigrationBundle` 是唯一随
-仓库分发的业务 Bundle，其合法性由启动链路的回归测试覆盖。
+仓库分发的业务 Bundle。它的 Manifest 依赖身份、搜索、调度和存储等运行时模块，但
+Bundle 没有跨模块 DDL 排序要求，因此不复制这些运行时依赖；其合法性由启动链路的
+回归测试覆盖。
 
 ## PostgreSQL 启动执行
 

package/template/docs/architecture/module-manifest-composition.md

@@ -1,10 +1,13 @@
 # Module Manifest 组合契约
 
-更新时间：2026-07-23。
+更新时间：2026-07-29。
 
 ## 目标与边界
 
-Module Manifest 是模块公开能力的唯一声明 Interface；Server、Web 等宿主只提供具体 Implementation，并在 Composition Root 通过同一个 `validateModuleComposition` Seam 完成 fail-fast 校验。本批不实现业务搜索，只提供通用 Provider 注册位。
+Module Manifest 是模块公开能力的唯一声明 Interface；Server、Web 等宿主只提供具体
+Implementation，并在 Composition Root 通过同一个 `validateModuleComposition` Seam
+完成 fail-fast 校验。搜索等业务实现由模块 Provider 提供，平台只拥有通用注册、治理和
+执行契约。
 
 Manifest 当前覆盖：
 
@@ -42,12 +45,48 @@ License 配置必须引用同一 Manifest 中已注册的 Feature/Permission。
 项目构建时和服务监听前。这样权限目录与 License/Feature 目录不会依赖第二份手写 Key
 列表，也不会出现只注册页面或 API 的“幽灵功能”。
 
+### 当前执行状态
+
+第一批运行时组合门禁已经落地：非目录菜单、Admin Route、非匿名 API、定时任务、
+Agent Tool、AI Operation 与 Provider 必须同时声明 Permission 和 Feature；缺少任一
+Guard 会由 `validateModuleComposition` 在宿主开始监听前拒绝。匿名基础设施 API 是
+显式例外，不通过字段可选性隐式放行。
+
+Feature 管理页面和 API 由 `system.feature` Feature 与 `system.feature.*` Permission
+共同保护。为避免控制面自锁，`system.feature` 是不可关闭、隐藏或附加 License 限制的
+核心恢复能力；关闭 `system.rbac` 后，具备管理权限的开发或超级管理员仍可重新开启它。
+
+第二批同基础 Key 门禁已经启用：每个 Permission 必须存在去掉末段动作后的 Feature，
+所有受 Guard 保护的入口和数据治理策略也必须引用该 Feature。用户、角色、部门、菜单和
+字典分别使用 `system.user`、`system.role`、`system.department`、`system.menu` 与
+`system.dict`，并显式依赖总开关 `system.rbac`；关闭总开关会让资源能力以
+`dependency-missing` fail closed，但不会锁死独立的 Feature 恢复控制面。
+
+API、Task、Tool、AI Operation、Provider 与受治理资源的 Audit Action 已进入 Manifest
+引用校验。分发目录会交叉校验运行时依赖，并在生命周期命令写文件前检查 Windy range、
+依赖、冲突、runtime activation 与 deployment install 能力；当前内置模块都需要
+project-owned Composition，因此部署后的 add/update/remove 会在计划阶段 fail closed。
+
+普通 Web build 会加载每个启用 package 的 `./admin` 和 canonical `./manifest`，核对窄
+投影、Host range、页面实现与路由碰撞。Server build 和普通启动会通过无数据库预检子
+进程执行完整 Composition、实现、依赖闭包和 attachment 校验，再允许审计恢复、
+Migration、Worker 与监听。不存在“构建通过、启动时才第一次发现未知能力”的宽松路径。
+
+平台静态 HTTP Route 通过 `createManifestAuthorizedRouteApp()` 包装，并由
+`createStaticRouteAuthorizer()` 使用同一 Manifest Feature、Permission、License 与
+模块启用状态完成请求时 Guard；实际 Elysia Route 也必须反向存在于 Manifest。只有显式
+标记 `immutableCoreAccess` 的健康探针和认证恢复入口可以跳过运行态 Guard，但它们仍须
+具有 Manifest 声明，不能用匿名字段隐式绕过。
+
 ## 模块与 Adapter
 
 - `@southwind-ai/modules` 是深 Module：拥有声明类型、依赖排序、引用规则和组合验证，不依赖 Elysia 或 Vue。
 - `systemModuleFactories` 是 15 个平台模块的运行时目录；`systemFoundationModule()` 仅保留为兼容聚合视图，不再作为 Composition Root 中唯一的巨型平台模块。
 - 多个模块可以向同一菜单目录贡献入口；`composeModuleMenus()` 合并一致的目录壳，并在标题、类型、顺序或 Guard 漂移时 fail fast。
-- Server Adapter 提供 API Route、Task、Tool、Provider Handler Key；启动监听前验证。
+- Server Adapter 提供 API Route、Task、Tool、Provider 与 Durable Handler Key；启动
+  监听前验证。Durable Handler 还必须绑定 Manifest 中同一能力的 Feature、Permission
+  与 Audit Action；Host 冻结该绑定，并在每次首次执行、重试和恢复领取时按当前
+  Actor、License、Feature 与 RBAC 状态重新 Guard。
 - 业务模块可在 `auditActions` 中直接注册包含 Key、名称和说明的动作定义；组合后的
   Audit Action Catalog 与 License Catalog 会通过 Foundation / Admin Bootstrap 契约开放，
   管理端筛选与展示不维护第二份静态业务 Key。
@@ -59,6 +98,45 @@ License 配置必须引用同一 Manifest 中已注册的 Feature/Permission。
 
 这种边界允许宿主替换实现，同时保持 Manifest 的能力语义稳定。
 
+## 项目装配与 Host 协议
+
+`windy.modules.json` 是 Web 与 Server 共用的 project-owned 装配声明：
+
+- `package=null` 表示由 Host 提供实现的平台模块；其它项使用稳定 npm package 名称；
+- `enabled` 控制模块是否进入运行组合，`admin.visible` 只控制入口呈现；
+- `order`、`config` 属于项目选择；版本仍由 `package.json` 与 `bun.lock` 决定；
+- 两个核心模块必须启用，依赖必须形成已启用闭包，重复名称/顺序或非法 package 名称
+  直接拒绝。
+
+`system.settings` 的 Admin Route 引用外部 `system.admin`，`system.storage` 承载
+Settings 声明的公共品牌文件 Route，`system.data-governance` 也向其它 Feature
+贡献治理能力；Host 会拒绝只通过 registry 停用这三类跨模块贡献者。需要排除时必须在
+创建期物理裁剪，或由已部署项目执行人工迁移。
+
+Web 的 Vite virtual registry 只静态 import 启用 package 的 `${package}/admin`。该导出
+只含 `AdminUiManifest`、Host range 和页面 loader；构建时再与
+`${package}/manifest` 的精确窄投影比对。项目在
+`apps/web/src/app/web-composition.ts` 只覆盖页面 loader 和呈现，不复制治理字段。
+整个 `apps/web/src` 都是 project-owned；Host 源码可替换，但失去协议后构建只诊断，
+不会覆盖项目实现。
+
+Server package 的 canonical 声明来自 `${package}/manifest`。根
+`windyServerModule`、本地 Adapter 返回的 `module.manifest`，以及根可选的
+`windyModuleManifest` 都必须复用该同一对象。`self-contained` Adapter 可以由 Host
+动态加载；`project-attachment` 只能在 project-owned
+`apps/server/src/app/server-composition.ts` 中声明，并通过同名 attachment 接收项目
+Repository 等 runtime。整组 attachment 会先于任何 `setup()` 完成校验，避免部分注册。
+
+## License 激活边界
+
+未选择 `system.license` 或没有启用 License 配置时，Server 使用明确的 free/no-license
+路径：License 版本、Entitlement 与限制态 Guard 不阻止产品功能，Feature 与 RBAC 仍
+照常执行。模块已生成但在 registry 中禁用时，已声明 License runtime API Route 仍保留，
+统一 `StaticRouteAuthorizer` 会以 `feature-disabled` 返回 403，不能因省略 Route
+破坏声明/实现完整性，也不能绕过 Guard。只有模块与配置都启用后，后端 License Provider
+才执行最终授权；限制态下只有显式 License 恢复入口拥有窄
+`admin-admission` 例外，Admin 的普通开关和页面不能自行放行。
+
 ## Capability Key 重命名边界
 
 平台当前没有 Module、Feature、Permission、Task、Tool、Operation 或 API Key 的通用
@@ -75,5 +153,9 @@ rename/alias seam。Composition、Guard、history 和审计都按 Manifest 中
 - 第一批：类型、声明级验证和失败回归。
 - 第二批（已完成）：Server 直接读取 Elysia 实际路由表、Scheduler definitions 和 Agent Tool Handler Registry，在 `listen` 与 Worker 启动前执行 fail-fast。无数据库开发模式下不会注册的密码管理与个人资料路由，由其实际注册函数导出 Implementation 描述，避免把条件装配误判成缺少代码实现。
 - 第三批（已完成）：Web 只注册页面组件、name 和 props，path、标题、Permission 与 Feature 由 Manifest Admin Route Adapter 生成；模块加载时校验所有 Admin Route 都有实现。License 恢复页的“已认证即可直访”作为 `directAccess: authenticated` 显式声明，Sidebar 可见性仍使用 Manifest Permission/Feature。
+- 第四批（已完成）：Web/Server 共用 `windy.modules.json`，package 使用
+  `./admin`、`./manifest` 与 `windyServerModule` 标准导出；Web build、Server build
+  和普通启动执行 canonical projection/identity、Host range、依赖闭包、实现完整性与
+  runtime attachment 门禁。
 
 每批都必须更新本文件与产品任务状态后再提交。

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

@@ -92,4 +92,9 @@ Composition Root 把 Server 实际注册的搜索 API 与 Provider Handler Key
 
 示例 Work Order 已注册 `work-order.ticket.search`，Provider 只调用 `WorkOrderService.list`，后者把查询、count、分页与服务端 dataScope 一起交给 scoped Repository；测试会让裸 `Repository.list` 主动抛错，并确认本人范围不会返回其他负责人的匹配工单。另一个实现相同 Key/版本的测试 Provider 可以在不修改 Core 的情况下替换工单 Adapter。
 
-生成器默认产物保留 Work Order Provider；`--no-example` 完整移除业务 Provider、schema 与 migration 引用，但保留搜索 Core、Guarded API 和类型化空 Registry。`bun run test:create-windy` 对两种生成物执行真实安装、typecheck、test、build 和 Server 启动，并显式断言该移除边界；`bun run test:db:data-scope` 在真实 PostgreSQL 中分别验证核心用户资源与可删除工单资源的 Repository 级范围约束。
+首次创建显式选择 `--module work-order` 时才包含 Work Order Provider；默认选择和
+`--no-example` 都会完整移除业务 Provider、schema 与 migration 引用，但保留搜索 Core、
+Guarded API 和类型化空 Registry。`bun run test:create-windy` 对包含/排除示例的生成物
+执行真实安装、typecheck、test、build 和 Server 启动，并显式断言该移除边界；
+`bun run test:db:data-scope` 在真实 PostgreSQL 中分别验证核心用户资源与可删除工单资源
+的 Repository 级范围约束。

package/template/docs/architecture/server-module-interface.md

@@ -2,29 +2,88 @@
 
 ## 定位
 
-Server Module Interface 是可安装业务模块与平台宿主之间的唯一契约：下游业务包（独立仓库）以一个 `InstallableServerModule` 同时贡献 `manifest`（声明）与 `setup(host)`（实现注册），宿主按统一顺序装配 Route、Task、Tool、Upload Policy、Role Preset、Search Provider 与 Migration Bundle，不再为每个模块手工接线。
+Server Module Interface 是业务模块与平台宿主之间的唯一契约：业务 package 以
+`InstallableServerModule` 同时贡献 `manifest`（声明）与 `setup(host)`（实现注册），
+宿主按统一顺序装配 Route、Task、Tool、Upload Policy、Role Preset、Search Provider
+与 Migration Bundle，不再为每个模块手工维护能力 Key。
 
 分层：
 
 - `packages/server-sdk`：公开 Interface。纯类型加少量校验辅助，不依赖 Elysia / Drizzle / 宿主内部类型；
 - `apps/server/src/module-host/`：宿主实现。注册收集、Manifest 一致性校验、Guarded Route 安装、受限 Port 构造与各子系统适配；
-- `packages/example-work-order`：拥有 Manifest 与 `setup(host)` 注册过程；
-- `apps/server/src/example-modules.ts`：只注入 Repository、Handler 等宿主适配器，并提供统一的运行时 attach；
-- `apps/server/src/installed-business-modules.ts`：唯一安装清单，Foundation、Host 初始化和运行时 attach 都从该清单派生。
+- `packages/example-work-order`：拥有 canonical Manifest、`setup(host)` 注册过程和
+  package Adapter；
+- `apps/server/src/app/server-composition.ts`：project-owned 组合声明，读取
+  `windy.modules.json`，选择本地 Adapter 与 runtime attachment；
+- `apps/server/src/module-host/project-composition.ts`：解析 package、Host range、
+  Manifest identity、启用依赖闭包和运行模式。
+
+## package 与项目组合
+
+标准 package 始终使用 canonical Manifest，并按运行模式选择 Adapter：
+
+- `${package}/manifest` 导出 `windyModuleManifest`，是 Host 的 canonical 声明；
+- self-contained package 根导出 `windyServerModule`；
+- 需要项目 runtime 的 package 在 project Composition 注册本地 Adapter，不要求动态
+  根 Adapter；
+- package 根若同时导出 `windyModuleManifest`，必须与 `./manifest` 是同一对象；
+- Adapter `create()` 返回的 `module.manifest` 也必须是该 canonical 对象。
+
+`WindyServerModuleAdapter.runtimeMode` 有两个值：
+
+- `self-contained`：Host 可从 package 根动态加载；不能获得数据库或项目内部
+  Repository；
+- `project-attachment`：只允许项目 Composition Root 显式注册，并由同名 attachment
+  在预校验成功后接收项目 runtime。
+
+动态 package 宣称 `project-attachment` 会被拒绝。本地 Adapter 也必须加载并复用
+`${package}/manifest`，不能用一份内容相同但独立创建的 Manifest 绕过身份校验。
+
+### 0.3.17 project-owned 装配兼容
+
+最低支持基线只有 `apps/server/src/installed-business-modules.ts`，没有后来的
+`app/server-composition.ts`。普通更新必须保留这份客户文件，因此受管 Host 通过
+`module-host/runtime-composition.ts` 同时读取旧 `installedBusinessModules` 契约和
+新版声明式 Composition，而不要求旧文件新增导出。
+
+同名模块优先使用旧 project-owned 实例，Manifest 内容不一致时 fail closed；只有新版
+Composition 独有的模块才由新版 attachment 挂载。这样旧实例的 `setup()` 与
+`attach()` 仍成对执行，也不会因为目标模板出现同名 Adapter 而重复挂载。新生成项目的
+旧兼容列表为空，全部走声明式 Composition。
 
 ## 声明与实现的一致性
 
 Manifest 是能力的唯一事实源，双向校验保证不漂移：
 
-- 注册时（`initializeModuleHosts`）：安装单元的 Manifest 必须与平台能力目录是同一声明；实现必须与 Manifest 声明一致——路由绑定、任务、工具、Provider 未声明即抛错；角色预设的权限必须属于本模块声明；
+- 组合时：每个启用模块必须存在于 `windy.modules.json`，平台模块必须使用
+  `package=null`，两个核心模块必须启用；Manifest dependencies 必须形成已启用闭包，
+  Host range 必须兼容；
+- 注册时（`initializeModuleHosts`）：安装单元的 Manifest 必须与平台能力目录是同一声明；实现必须与 Manifest 声明一致——路由绑定、任务、工具、Provider 未声明即抛错；Durable Handler 必须精确绑定本模块已声明的 Feature、Permission 与 Audit Action 组合；角色预设的权限必须属于本模块声明；
 - 装配后（`validateServerModuleComposition`）：声明了没实现（缺 Handler）与实现了没声明（`moduleRegistrations` 比对）都在启动前报错；
 - 所有 Key 强制模块命名空间（等于模块名或以 `<moduleName>.` 开头），跨模块重复注册立即失败。
 
+attachment 在任一模块 `setup()` 前完成整组预校验，避免前半组已经产生注册副作用后才
+发现缺失或重复 attachment。`setup()` 后再次校验 Manifest identity，模块若在注册期间
+替换声明会被拒绝。
+
+同一套完整组合门禁会在 Server build 和普通启动的无数据库子进程中执行；只有通过后
+才允许审计恢复、Migration、Worker 和 HTTP listener。安装命令尚不能接入
+self-contained package 时，也必须在写项目之前 fail closed。
+
+平台自身的静态 Route 也不在 Host 契约之外：`createManifestAuthorizedRouteApp()` 将
+实际 Handler 交给 `StaticRouteAuthorizer`，按 Manifest 的模块启用状态、License、
+Feature 与 Permission 执行请求时 Guard。只有显式 `immutableCoreAccess` 的健康探针与
+认证恢复入口可以跳过运行态 Guard，但仍必须在 Manifest 注册；其它实际 Elysia Route
+找不到声明时，build/start 预检直接失败。
+
 ## 受限 Port 的取舍
 
 - **Actor 只读白名单视图**：宿主为 `ModuleActor` 构造冻结的最小对象，不把凭据状态与数据范围令牌带入模块运行时。宿主内部通过不可伪造的映射恢复原始 `RequestActor`，外部模块无法扩权或伪造该关联。
 - **初始化两阶段**：`setup(host)` 在 Storage / Durable Worker 创建之前运行，只能登记定义；需要宿主服务的实现（路由 Handler、任务执行体、Provider）通过延迟绑定（`requireService` 闭包 + 安装清单统一 `attach()`）解析，与平台既有 `DeferredLegacyExecutor` 模式一致。
 - **Queue 与提交人不可伪造**：模块 Jobs Port 只能提交本模块命名空间的 Handler，Queue 强制为模块名，提交人由宿主以当前 Actor 补齐；Worker 与 Repository 始终由宿主持有。
+- **持久任务每次领取都重新授权**：Host 冻结注册时通过校验的 Durable Handler
+  能力绑定；首次执行、重试和进程恢复后的领取都重新解析当前 Actor，并按当前
+  License、Feature 与 RBAC 状态执行 Guard。提交时曾获授权不能成为永久通行证。
 - **审计白名单**：模块只能 emit 自己 Manifest 注册的审计动作；Guard 拒绝（`security.denied`）由宿主统一记录，模块无法关闭。
 - **存储最小授权**：上传 purpose 强制属于本模块已注册 Upload Policy，Owner 由宿主
   以当前 Actor 补齐。Owner 读取保持用途约束；跨上传者读取的 purpose 只可来自当前
@@ -34,6 +93,10 @@ Manifest 是能力的唯一事实源，双向校验保证不漂移：
   Repository 或任意 manage 能力。
 - **角色预设非破坏性合并**：预设随内置角色同步，手工追加的授权保留；与既有角色 Code 冲突直接启动失败，不做静默覆盖。
 
-## 暂不迁移的部分
+## 当前边界
 
-系统模块（auth / license / storage / scheduler 等平台能力）仍保持原有的宿主内部接线，不经过 ModuleHost 路由注册；Module Interface 面向的是业务模块。平台任务的硬编码 Handler 映射（`createPlatformTaskDefinitions`）同样保留，业务任务一律改走 `registerTaskHandlers`。
+平台系统模块仍有部分 Host 内部接线；业务模块使用 ModuleHost。当前目录里的内置模块
+是创建期 source/template distribution，没有一个已取得部署后 add/update/remove 的
+self-contained H3 证据。整个 `apps/server/src/app` 由项目拥有，默认装配入口是
+`server-composition.ts`；普通更新不会覆盖。若客户移除协议实现，平台只能诊断，不能
+重写这些文件。

package/template/docs/development/business-web-routes.md

@@ -1,66 +1,69 @@
-# project-owned 业务 Web 路由
+# project-owned Web 与 Admin UI 组合
 
-Windy Starter 把平台 Router 和访问快照 Guard 保留在
-`apps/web/src/router/`，客户业务路由只注册到
-`apps/web/src/app/business-routes.ts`。整个 `apps/web/src/app/` 在
-`.windy/files.json` 中属于 `project-owned`：更新器不会覆盖客户新增、修改或删除的
-路由注册与页面源码。
+更新时间：2026-07-29。
 
-## 注册一个页面
+整个 `apps/web/src` 都是 project-owned 应用源码。布局、页面、组件库封装、Router、
+导航呈现与 Host 实现均可由项目修改、替换或删除；普通 `windy update` 和模块命令不能
+为了接入入口而重写这些文件。
 
-先在业务 Module Manifest 中用同一个能力基础 Key 声明 Feature、Permission、菜单和
-Admin Route，再在 `installedBusinessAdminRoutes` 中注册页面实现：
+## package 默认贡献
 
-```ts
-import CaseRecordsPage from "./case-records/CaseRecordsPage.vue";
+带管理面的业务 package 必须同时提供：
 
-export const installedBusinessAdminRoutes = [
-  {
-    key: "case.record",
-    path: "/cases",
-    name: "case-records",
-    title: "案件",
-    component: CaseRecordsPage,
-    featureKey: "case.record",
-    permissionKey: "case.record.read",
-  },
-] satisfies readonly BusinessAdminRouteRegistration[];
-```
+- `${package}/manifest`：导出 canonical `windyModuleManifest`；
+- `${package}/admin`：只导出 browser-safe 的 `windyAdminUiModule`，其中
+  `AdminUiManifest` 仅投影模块身份、版本和 `adminRoutes`；
+- 每个 Admin Route 的 `routeKey -> lazy loader` 页面绑定及 `hostRange`。
 
-注册表必须与 Module Manifest 使用相同的 `key`、`path`、`featureKey` 和
-`permissionKey`。服务端仍是最终授权边界；Web Router 会把注册项统一转换为
-`layout: "admin"` 路由，并在每次导航时使用访问快照检查 Feature 与 Permission。
-空 Guard、重复业务 Route Key、相对路径和业务兜底路径会在启动组合时被拒绝。
+Vite 在构建时读取 `windy.modules.json`，为其中 `enabled=true` 且 `package` 非空的
+项生成静态 virtual registry。禁用模块不会被 import 或进入 Web bundle。构建脚本还会
+独立加载 `./manifest`，要求 `./admin` 的窄 Manifest 与 canonical 投影完全一致，并
+检查 Host range、缺失页面、重复 route key/path 和保留路径碰撞。
 
-页面组件及其 composable、表单和状态放在 `apps/web/src/app/` 下。不要为了增加业务
-页面修改以下 shared-scaffold：
+Migration、Task、Provider、Audit、Schema 与持久化元数据不得通过 `./admin` 进入浏览器
+bundle。页面 loader 失败或没有合法 `default` 导出时，只显示 Admin shell 内的模块失败
+页，不卸载整个应用。
 
-- `apps/web/src/router/index.ts`
-- `apps/web/src/router/business-routes.ts`
-- `apps/web/src/layout/AppSidebar.vue`
-- `apps/web/src/layout/navigation.ts`
+## 项目覆盖
 
-## 导航来源
+项目在 `apps/web/src/app/web-composition.ts` 只覆盖自己接管的页面 loader 和呈现偏好，
+不重复 path、title、Feature 或 Permission：
 
-侧栏和导航搜索不会读取 Web 注册表来复制一份菜单。服务端启动时从已安装业务 Module
-Manifest 同步菜单，`/api/foundation` 返回经过 License、Feature 和 RBAC 裁剪的访问
-快照，Web 外壳据此渲染导航。这样路径、权限、Feature 和菜单身份仍由 Manifest
-统一治理，客户只在 project-owned 注册表绑定 Vue 页面实现。
+```ts
+export const webComposition = defineWebComposition({
+  overrides: [
+    {
+      moduleName: "case",
+      pages: [
+        {
+          routeKey: "case.review.queue",
+          load: () => import("../pages/case/CaseReviewQueuePage.vue"),
+        },
+      ],
+    },
+  ],
+  presentation: [
+    {
+      routeKey: "case.review.queue",
+      title: "材料审核",
+      order: 120,
+    },
+  ],
+});
+```
 
-如果页面可直达但侧栏没有入口，优先检查服务端
-`apps/server/src/installed-business-modules.ts` 是否已经安装对应业务 Module、Manifest
-是否声明菜单，以及当前账号是否具有 Permission；不要在 AppSidebar 手写菜单。
+路径与 Guard 始终来自同一完整 Manifest。服务端是最终授权边界；Web Router 只使用
+Foundation 访问快照改善导航和直达体验。`admin.visible=false` 只隐藏该模块的菜单入口，
+不删除路由，也不替代 Server Guard。
 
 ## 升级行为
 
-首次生成时，`business-routes.ts` 会记为 `project-owned`。后续 target 即使提供了新的
-默认内容，也不能把 source manifest 中的该路径降级成 `shared-scaffold` 或
-`windy-managed`：
+`apps/web/src` 在 `.windy/files.json` 中整体标为 `project-owned`：
 
-- 客户修改继续保留；
-- 客户删除会以 tombstone 跨版本保留；
-- 客户重新创建后，清单刷新采纳新正文 hash，但仍保持 `project-owned`；
-- 平台只升级 Router Adapter 与 Guard，实现变更通过 shared-scaffold 三方合并进入。
+- 客户保留、修改与删除均由项目决定；
+- 删除以 tombstone 跨版本保留；
+- 模块 package 更新只改变依赖与自身导出，不改客户 layout、Router 或页面；
+- Host 不再实现协议时，CLI/构建只诊断并 fail closed，不能覆盖客户实现。
 
-升级前可运行 `bun run windy update --dry-run` 查看所有权和冲突计划。纯业务页面与
-注册表变更不应产生平台侧源码覆盖。
+未来若提供整套 Admin 预设更新，它必须是独立、显式选择的三方合并能力；当前没有
+`windy admin update` 命令，不能把该目标写成已交付的日常路径。