create-windy 0.2.19 → 0.2.20

package/template/apps/server/src/work-order/search-provider.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { workOrderModule, type WorkOrder } from "@southwind-ai/example-work-order";
+import {
+  workOrderModule,
+  type WorkOrder,
+} from "@southwind-ai/example-work-order";
 import type { ModuleManifest } from "@southwind-ai/modules";
 import { licenseVersionKey } from "@southwind-ai/shared";
 import { buildScopeContext } from "../data-access/context.js";
@@ -11,6 +14,7 @@ import type { SearchProvider } from "../search/contracts.js";
 import { SearchService } from "../search/service.js";
 import type { ManagedDepartment } from "../system/entities.js";
 import { InMemoryEntityRepository } from "../system/repository.js";
+import { adaptModuleSearchProvider } from "../module-host.js";
 import { workOrderDataScopeBinding } from "./repository.js";
 import {
   WorkOrderSearchProvider,
@@ -40,10 +44,13 @@ describe("示例工单 SearchProvider", () => {
       throw new Error("搜索不得调用裸 Repository.list");
     };
     const service = searchService([
-      new WorkOrderSearchProvider(
-        new WorkOrderService(
-          repository,
-          new InMemoryEntityRepository<ManagedDepartment>(),
+      adaptModuleSearchProvider(
+        new WorkOrderSearchProvider(
+          () =>
+            new WorkOrderService(
+              repository,
+              new InMemoryEntityRepository<ManagedDepartment>(),
+            ),
         ),
       ),
     ]);
@@ -84,17 +91,18 @@ describe("示例工单 SearchProvider", () => {
   });
 
   test("Provider 游标映射到 scoped Repository 分页", async () => {
-    const provider = new WorkOrderSearchProvider(
-      new WorkOrderService(
-        new InMemoryScopedEntityRepository<WorkOrder>(
-          [
-            ticket("ticket_1", "user_self", "故障一"),
-            ticket("ticket_2", "user_self", "故障二"),
-          ],
-          workOrderDataScopeBinding,
-        ),
-        new InMemoryEntityRepository<ManagedDepartment>(),
+    const workOrders = new WorkOrderService(
+      new InMemoryScopedEntityRepository<WorkOrder>(
+        [
+          ticket("ticket_1", "user_self", "故障一"),
+          ticket("ticket_2", "user_self", "故障二"),
+        ],
+        workOrderDataScopeBinding,
       ),
+      new InMemoryEntityRepository<ManagedDepartment>(),
+    );
+    const provider = adaptModuleSearchProvider(
+      new WorkOrderSearchProvider(() => workOrders),
     );
     const service = searchService([provider]);
     const first = await service.search(

package/template/apps/server/src/work-order/search-provider.ts

@@ -1,9 +1,10 @@
 import type {
-  SearchExecutionContext,
-  SearchProvider,
-  SearchProviderPage,
-  SearchProviderQuery,
-} from "../search/contracts.js";
+  ModuleSearchContext,
+  ModuleSearchPage,
+  ModuleSearchProvider,
+  ModuleSearchQuery,
+} from "@southwind-ai/server-sdk";
+import { requestActorFromModule } from "../module-host/request-context.js";
 import { SearchProtocolError } from "../search/errors.js";
 import { maskSearchText } from "../search/masking.js";
 import type { WorkOrderService } from "./service.js";
@@ -11,21 +12,25 @@ import type { WorkOrderService } from "./service.js";
 export const WORK_ORDER_SEARCH_PROVIDER_KEY = "work-order.ticket.search";
 export const WORK_ORDER_SEARCH_PROVIDER_VERSION = "0.1.0";
 
-export class WorkOrderSearchProvider implements SearchProvider {
+/**
+ * 示例工单搜索 Provider，实现 server-sdk 的受限 Provider 协议。
+ * `requireService` 延迟解析宿主装配完成后才存在的模块服务。
+ */
+export class WorkOrderSearchProvider implements ModuleSearchProvider {
   readonly key = WORK_ORDER_SEARCH_PROVIDER_KEY;
   readonly providerVersion = WORK_ORDER_SEARCH_PROVIDER_VERSION;
 
-  constructor(private readonly service: WorkOrderService) {}
+  constructor(private readonly requireService: () => WorkOrderService) {}
 
   async search(
-    request: SearchProviderQuery,
-    context: SearchExecutionContext,
-  ): Promise<SearchProviderPage> {
+    request: ModuleSearchQuery,
+    context: ModuleSearchContext,
+  ): Promise<ModuleSearchPage> {
     if (request.signal.aborted) throw new Error("search aborted");
     const page = parseProviderCursor(request.cursor);
-    const result = await this.service.list(
+    const result = await this.requireService().list(
       { q: request.text, page, pageSize: request.limit },
-      context.actor,
+      requestActorFromModule(context.actor),
     );
     if (request.signal.aborted) throw new Error("search aborted");
     return {

package/template/apps/server/src/work-order/task.test.ts

@@ -1,21 +1,30 @@
 import { describe, expect, test } from "bun:test";
-import type { WorkOrder } from "@southwind-ai/example-work-order";
+import { type WorkOrder } from "@southwind-ai/example-work-order";
+import { createWorkOrderModule } from "../example-modules.js";
 import { createFoundationSnapshot } from "../foundation.js";
+import {
+  createModuleTaskDefinitions,
+  initializeModuleHosts,
+} from "../module-host.js";
 import { createServerRuntime } from "../runtime.js";
 import { InMemorySchedulerRepository } from "../scheduler/repository.js";
 import { SchedulerService } from "../scheduler/service.js";
 import type { ManagedDepartment } from "../system/entities.js";
 import { InMemoryEntityRepository } from "../system/repository.js";
 import { InMemoryScopedEntityRepository } from "../data-access/scoped-repository.js";
-import { WorkOrderService } from "./service.js";
 import { workOrderDataScopeBinding } from "./repository.js";
-import { createWorkOrderTaskDefinitions } from "./task.js";
 
 describe("示例工单后台任务", () => {
   test("通过统一调度 Guard 执行并把业务快照写入历史", async () => {
     const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token" });
-    const service = new WorkOrderService(
-      new InMemoryScopedEntityRepository<WorkOrder>(
+    const module = createWorkOrderModule();
+    const hosts = await initializeModuleHosts({
+      modules: [module.manifest],
+      installations: [module],
+    });
+    module.attach({
+      departments: new InMemoryEntityRepository<ManagedDepartment>(),
+      repository: new InMemoryScopedEntityRepository<WorkOrder>(
         [
           item("ticket_high", "high", "open"),
           item("ticket_progress", "medium", "in-progress"),
@@ -23,14 +32,10 @@ describe("示例工单后台任务", () => {
         ],
         workOrderDataScopeBinding,
       ),
-      new InMemoryEntityRepository<ManagedDepartment>(),
-    );
+    });
     const scheduler = new SchedulerService(
       new InMemorySchedulerRepository(),
-      createWorkOrderTaskDefinitions(
-        createFoundationSnapshot().features,
-        service,
-      ),
+      createModuleTaskDefinitions(hosts, createFoundationSnapshot().features),
       runtime,
     );
     await scheduler.initialize();

package/template/apps/web/Dockerfile

@@ -4,6 +4,7 @@ FROM oven/bun:1.3.14-alpine AS deps
 WORKDIR /app
 
 COPY package.json bun.lock ./
+# windy-copy:deps begin
 COPY apps/license/package.json apps/license/package.json
 COPY apps/server/package.json apps/server/package.json
 COPY apps/signing-service/package.json apps/signing-service/package.json
@@ -20,14 +21,16 @@ COPY packages/modules/package.json packages/modules/package.json
 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
 
 FROM deps AS build
+# windy-copy:build begin
 COPY apps/web apps/web
-COPY packages/example-work-order packages/example-work-order
 COPY packages/license-sdk packages/license-sdk
 COPY packages/modules packages/modules
 COPY packages/shared packages/shared
+# windy-copy:build end
 RUN bun run --cwd apps/web build
 
 FROM deps AS runner

package/template/apps/web/src/layout/GlobalWatermark.layering.webtest.ts

@@ -42,7 +42,10 @@ const state = vi.hoisted(() => {
 });
 
 vi.mock("@/composables/useAccessSnapshot", () => ({
-  useAccessSnapshot: () => ({ snapshot: state.access }),
+  useAccessSnapshot: () => ({
+    snapshot: state.access,
+    ensureLoaded: vi.fn(async () => state.access.value),
+  }),
 }));
 
 vi.mock("@/composables/useAuthSession", () => ({

package/template/apps/web/src/layout/GlobalWatermark.vue

@@ -18,6 +18,8 @@ const access = useAccessSnapshot();
 const watermark = useWatermarkSettings(auth.actor);
 onMounted(() => {
   void watermark.ensureLoaded();
+  // 业务页路由守卫不会预取访问快照，这里兜底加载，失败时保持水印隐藏。
+  void access.ensureLoaded().catch(() => undefined);
 });
 const allowed = computed(() => {
   const snapshot = access.snapshot.value;

package/template/apps/web/src/layout/GlobalWatermark.webtest.ts

@@ -45,7 +45,10 @@ const state = vi.hoisted(() => ({
 }));
 
 vi.mock("@/composables/useAccessSnapshot", () => ({
-  useAccessSnapshot: () => ({ snapshot: state.access }),
+  useAccessSnapshot: () => ({
+    snapshot: state.access,
+    ensureLoaded: vi.fn(async () => state.access.value),
+  }),
 }));
 
 vi.mock("@/composables/useAuthSession", () => ({

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

@@ -58,8 +58,20 @@ Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只
 - 删除为幂等操作；第一次存在时返回 `true`，重复删除返回 `false`。
 - 进程在 Blob 发布与元数据发布之间退出时可能产生孤儿内容；上传生命周期模块基于过期时间、引用集合与 grace period 清理。
 
+## 模块受限 Upload/BlobRead Port
+
+业务模块不直接使用 `UploadService` / `FileService`，而是经 `ModuleRequestContext.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 约束，且只允许本模块已注册用途。
+- 模块不直接接触 `BlobStore` 或 Upload Repository；宿主未挂载存储服务时，任何访问都以明确错误失败，不静默绕过。
+
+用途唯一性仍在 Host 注册时全局校验：命名空间重叠的模块（如 `shop` 与 `shop.sub`）注册同一 purpose 会在启动时失败。
+
 ## 当前切片
 
 - F1：Blob 端口、SHA-256、随机引用和本地流式 Adapter 已完成。
 - F2：上传会话、分片续传、文件元数据、校验和清理已完成。
 - F3：服务端授权下载、审计、bulk artifact 与 Logo 接入已完成。
+- F4：模块受限 Upload/BlobRead Port 已完成，业务模块经 Host 注册用途并受命名空间约束。

package/template/packages/config/index.test.ts

@@ -49,6 +49,63 @@ test("strict loader 对 unknown 与错误类型 fail-fast 且不回显输入值"
   }
 });
 
+test("WINDY_LICENSE_VERSIONS 解析宿主自定义 License 版本目录", () => {
+  const config = loadPlatformConfig({
+    WINDY_LICENSE_VERSIONS: JSON.stringify([
+      { key: "oem-basic", label: "OEM 基础版", order: 10 },
+      {
+        key: "oem-pro",
+        label: "OEM 专业版",
+        description: "含高级治理能力",
+        order: 20,
+      },
+    ]),
+  });
+
+  expect(config.license.versions).toEqual([
+    { key: "oem-basic", label: "OEM 基础版", description: "", order: 10 },
+    {
+      key: "oem-pro",
+      label: "OEM 专业版",
+      description: "含高级治理能力",
+      order: 20,
+    },
+  ]);
+  expect(loadPlatformConfig({}).license.versions).toBeUndefined();
+});
+
+test("WINDY_LICENSE_VERSIONS 非法 JSON 或非法结构时 fail-fast", () => {
+  expect(() =>
+    loadPlatformConfig({ WINDY_LICENSE_VERSIONS: "not-a-json" }),
+  ).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+      fieldPath: "license.versions",
+    }),
+  );
+  expect(() =>
+    loadPlatformConfig({
+      WINDY_LICENSE_VERSIONS: JSON.stringify([{ key: "missing-order" }]),
+    }),
+  ).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+    }),
+  );
+  expect(() =>
+    loadPlatformConfig({
+      WINDY_LICENSE_VERSIONS: JSON.stringify([
+        { key: "fractional", label: "小数版本", order: 1.5 },
+      ]),
+    }),
+  ).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+      fieldPath: "license.versions",
+    }),
+  );
+});
+
 test("必填 Secret 缺失时 fail-fast 且 registry 不暴露环境引用", () => {
   const definition = defineModuleConfig({
     key: "example.secure",

package/template/packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/config",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/config/src/platform.ts

@@ -1,4 +1,11 @@
-import type { DatabaseDialect } from "@southwind-ai/shared";
+import type {
+  DatabaseDialect,
+  LicenseCatalogDefinition,
+} from "@southwind-ai/shared";
+import {
+  parseLicenseCatalog,
+  parseLicenseCatalogJson,
+} from "@southwind-ai/shared";
 import { z } from "zod";
 import { defineModuleConfig, ModuleConfigRegistry } from "./definition.js";
 import {
@@ -33,6 +40,8 @@ export interface PlatformConfig {
     publicKeyId?: string;
     publicKey?: string;
     machineCode?: string;
+    /** 宿主自定义 License 版本目录；未配置时回退 shared 默认三级目录。 */
+    versions?: LicenseCatalogDefinition[];
   };
   audit: { enabled: boolean; redactFields: string[] };
   compatibility: {
@@ -75,6 +84,20 @@ const platformSchema: z.ZodType<PlatformConfig> = z.strictObject({
     publicKeyId: z.string().trim().min(1).optional(),
     publicKey: z.string().trim().min(1).optional(),
     machineCode: z.string().trim().min(1).optional(),
+    versions: z
+      .unknown()
+      .transform((value, context) => {
+        try {
+          return parseLicenseCatalog(value);
+        } catch (error) {
+          context.addIssue({
+            code: "custom",
+            message: error instanceof Error ? error.message : "版本目录无效",
+          });
+          return z.NEVER;
+        }
+      })
+      .optional(),
   }),
   audit: z.strictObject({
     enabled: z.boolean(),
@@ -105,6 +128,7 @@ export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
     "LICENSE_PUBLIC_KEY_ID",
     "LICENSE_PUBLIC_KEY",
     "LICENSE_MACHINE_CODE",
+    "WINDY_LICENSE_VERSIONS",
   ],
   environment: [
     value("PLATFORM_NAME", "name", "Windy Platform"),
@@ -133,6 +157,9 @@ export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
     value("LICENSE_PUBLIC_KEY_ID", "license.publicKeyId"),
     value("LICENSE_PUBLIC_KEY", "license.publicKey"),
     secret("LICENSE_MACHINE_CODE", "license.machineCode"),
+    value("WINDY_LICENSE_VERSIONS", "license.versions", undefined, (raw) =>
+      parseLicenseCatalogJson(raw, "WINDY_LICENSE_VERSIONS"),
+    ),
     value("AUDIT_ENABLED", "audit.enabled", true, strictBoolean),
     value(
       "AUDIT_REDACT_FIELDS",

package/template/packages/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/database",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/database/src/runner.ts

@@ -1,16 +1,14 @@
-import type {
-  BundleMigrationDefinition,
-  DatabaseCompatibilityAdapter,
-  DatabaseDialect,
-  MigrationBundle,
-  MigrationManifestSource,
-  MigrationStatement,
-} from "@southwind-ai/shared";
 import {
   normalizeManifestBundles,
   orderBundleMigrations,
   validateAndOrderBundles,
-} from "./bundle-validation.js";
+  type BundleMigrationDefinition,
+  type DatabaseCompatibilityAdapter,
+  type DatabaseDialect,
+  type MigrationBundle,
+  type MigrationManifestSource,
+  type MigrationStatement,
+} from "@southwind-ai/shared";
 import { createDialectAdapter } from "./dialects.js";
 import type { MigrationHistoryEntry, MigrationHistoryStore } from "./store.js";
 

package/template/packages/example-work-order/index.ts

@@ -2,3 +2,4 @@ export * from "./src/contract.js";
 export * from "./src/manifest.js";
 export * from "./src/migration-bundle.js";
 export * from "./src/schema.js";
+export * from "./src/server-module.js";

package/template/packages/example-work-order/package.json

@@ -4,6 +4,8 @@
   "private": true,
   "type": "module",
   "dependencies": {
+    "@southwind-ai/modules": "workspace:*",
+    "@southwind-ai/server-sdk": "workspace:*",
     "@southwind-ai/shared": "workspace:*",
     "zod": "^4.4.3"
   },

package/template/packages/example-work-order/src/server-module.ts

@@ -0,0 +1,61 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  InstallableServerModule,
+  ModuleRouteDefinition,
+  ModuleSearchProvider,
+  ModuleTaskHandler,
+} from "@southwind-ai/server-sdk";
+import { workOrderModule } from "./manifest.js";
+
+export interface WorkOrderServerBindings {
+  readonly routes: readonly ModuleRouteDefinition[];
+  readonly snapshot: ModuleTaskHandler;
+  readonly searchProvider: ModuleSearchProvider;
+}
+
+/**
+ * 工单业务包拥有 Manifest 与 Host 注册过程；宿主只注入具体业务实现。
+ */
+export function createWorkOrderServerModule(
+  bindings: WorkOrderServerBindings,
+): InstallableServerModule<ModuleManifest> {
+  return {
+    manifest: workOrderModule(),
+    setup(host) {
+      host.registerUploadPolicy({
+        purpose: "work-order.ticket.attachment",
+        maxByteSize: 20 * 1024 * 1024,
+        maxPartByteSize: 4 * 1024 * 1024,
+        sessionTtlMs: 2 * 60 * 60_000,
+        allowedTypes: {
+          "application/pdf": ["pdf"],
+          "image/png": ["png"],
+          "image/jpeg": ["jpg", "jpeg"],
+          "text/plain": ["txt"],
+        },
+        signature: "none",
+      });
+      host.registerRoutes(bindings.routes);
+      host.registerTaskHandlers([
+        {
+          taskKey: "work-order.ticket.snapshot",
+          handler: bindings.snapshot,
+        },
+      ]);
+      host.registerSearchProviders([bindings.searchProvider]);
+      host.registerRolePresets([
+        {
+          key: "work-order.ticket-manager",
+          label: "工单管理员",
+          description: "管理本部门及下级部门工单的模块角色预设。",
+          dataScope: "department-and-children",
+          permissionKeys: [
+            "work-order.ticket.create",
+            "work-order.ticket.manage",
+            "work-order.ticket.read",
+          ],
+        },
+      ]);
+    },
+  };
+}

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/jobs",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/jobs/src/types.ts

@@ -179,8 +179,14 @@ export interface SubmitDurableJobResult {
   created: boolean;
 }
 
-export interface DurableJobs {
+/**
+ * 只保留提交能力的窄接口，用于向模块等受限调用方暴露 Durable Jobs。
+ */
+export interface DurableJobSubmitter {
   submit(input: SubmitDurableJob): Promise<SubmitDurableJobResult>;
+}
+
+export interface DurableJobs extends DurableJobSubmitter {
   get(id: string): Promise<DurableJobSnapshot | undefined>;
   list(requestedBy: string, limit?: number): Promise<DurableJob[]>;
 }

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {