[Runtime] 内核多租户 Runtime 协议升级 — Tenant Context + Router + Deploy Pipeline 合同

[hotlong]

Summary

升级 @objectstack/spec 内核协议层，为 Cloud 多租户 "注册即开通" 架构提供完整的类型定义和服务合同。

背景

spec v3.0 已完成 TenantSchema、TenantIsolationLevel、KernelContextSchema 等基础协议。现在需要扩展以支持：

• 请求级租户上下文注入
• 租户路由合同（session → tenantId → DB connection）
• 元数据驱动部署流水线合同
• 配额与用量追踪协议
• 应用安装生命周期合同

开发任务

Part A: Tenant Runtime Context 扩展

• A1. TenantRuntimeContextSchema — 扩展 packages/spec/src/kernel/context.zod.ts

  // 在 KernelContextSchema 基础上扩展
  TenantRuntimeContextSchema = KernelContextSchema.extend({
    tenantId: z.string().describe('Current tenant ID from session'),
    tenantPlan: z.enum(['free', 'pro', 'enterprise']).describe('Tenant subscription plan'),
    tenantRegion: z.string().optional().describe('Primary database region'),
    tenantDbUrl: z.string().describe('Turso DB connection URL for current tenant'),
    tenantQuotas: TenantQuotaSchema.optional(),
  });

  • 更新 context.test.ts 增加新字段测试
  • 确保向后兼容（新字段可选或有默认值）

• A2. TenantUsageSchema — 新增到 packages/spec/src/system/tenant.zod.ts

  TenantUsageSchema = z.object({
    currentUsers: z.number().int(),
    currentStorageBytes: z.number().int(),
    currentObjectCount: z.number().int(),
    currentRecordCount: z.number().int(),
    deploymentsToday: z.number().int(),
    apiRequestsThisMinute: z.number().int(),
  });

• A3. 扩展 TenantQuotaSchema — 增加以下字段

  • maxObjects: z.number().int().optional() — 最大对象数
  • maxRecordsPerObject: z.number().int().optional() — 每对象最大记录数
  • maxDeploymentsPerDay: z.number().int().optional() — 每日最大部署次数
  • 更新现有测试

Part B: 服务合同定义

• B1. ITenantRouter 合同 — packages/spec/src/contracts/tenant-router.ts (NEW)

  export interface ITenantRouter {
    resolveTenant(session: AuthSession): Promise<TenantRuntimeContext>;
    getTenantDriver(tenantId: string): Promise<Driver>;
    invalidateCache(tenantId: string): void;
  }

  • 注意：Driver 类型引用 @objectql/types 中已有的 Driver interface

• B2. IDeployPipelineService 合同 — packages/spec/src/contracts/deploy-pipeline-service.ts (NEW)

  export interface IDeployPipelineService {
    validateBundle(bundle: DeployBundle): DeployValidationResult;
    planDeployment(tenantId: string, bundle: DeployBundle): Promise<MigrationPlan>;
    executeDeployment(tenantId: string, plan: MigrationPlan): Promise<DeployResult>;
    rollbackDeployment(tenantId: string, deploymentId: string): Promise<void>;
  }

• B3. IProvisioningService 合同 — packages/spec/src/contracts/provisioning-service.ts (NEW)

  export interface IProvisioningService {
    provisionTenant(request: TenantProvisioningRequest): Promise<TenantProvisioningResult>;
    suspendTenant(tenantId: string): Promise<void>;
    resumeTenant(tenantId: string): Promise<void>;
    destroyTenant(tenantId: string): Promise<void>;
    getTenantStatus(tenantId: string): Promise<TenantProvisioningStatus>;
  }

• B4. IAppLifecycleService 合同 — packages/spec/src/contracts/app-lifecycle-service.ts (NEW)

  export interface IAppLifecycleService {
    checkCompatibility(tenantId: string, manifest: AppManifest): Promise<CompatibilityResult>;
    installApp(tenantId: string, manifest: AppManifest): Promise<AppInstallResult>;
    upgradeApp(tenantId: string, appId: string, newManifest: AppManifest): Promise<AppInstallResult>;
    uninstallApp(tenantId: string, appId: string): Promise<void>;
  }

Part C: 数据 Schema 定义

• C1. TenantProvisioningSchema — packages/spec/src/system/provisioning.zod.ts (NEW)

  • TenantProvisioningRequestSchema — 输入：orgId, plan, region
  • TenantProvisioningResultSchema — 输出：tenantId, connectionUrl, status
  • TenantProvisioningStatusEnum — 'provisioning' | 'active' | 'suspended' | 'failed' | 'destroying'
  • ProvisioningStepSchema — 单步状态追踪

• C2. DeployBundleSchema — packages/spec/src/system/deploy-bundle.zod.ts (NEW)

  • DeployBundleSchema — objects[], views[], flows[], permissions[], seedData[]
  • DeployManifestSchema — version, checksum, metadata
  • DeployDiffSchema — added/modified/removed
  • MigrationPlanSchema — 有序 DDL 列表
  • DeployStatusEnum — 'validating' | 'diffing' | 'migrating' | 'registering' | 'ready' | 'failed'

• C3. AppManifestSchema — packages/spec/src/system/app-install.zod.ts (NEW)

  • AppManifestSchema — name, version, objects[], views[], flows[], seedData[]
  • AppInstallResultSchema — installed objects, created tables, seeded records
  • AppCompatibilityCheckSchema — kernel version check, conflict detection

• C4. 扩展 TenantSchema — 修改 packages/spec/src/system/tenant.zod.ts

  • 新增 databaseProvider: z.enum(['turso', 'postgres', 'memory']).optional()
  • 新增 provisioningStatus: TenantProvisioningStatusEnum.optional()
  • 新增 plan: z.enum(['free', 'pro', 'enterprise']).optional()

Part D: 导出与文档

• D1. 更新 packages/spec/src/system/index.ts 导出新模块
• D2. 更新 packages/spec/src/contracts/index.ts 导出新合同
• D3. 运行 build-docs.ts 生成新 schema 的参考文档
• D4. 更新 ROADMAP.md Phase 6 进度

Acceptance Criteria

• 所有新 schema 有 .describe() 注释
• 所有 interface 为 async 纯定义（spec 中零实现）
• 新增 .test.ts ≥ 90% 分支覆盖
• pnpm test 全通过
• pnpm build 零 TypeScript 错误

Labels

protocol, runtime, multi-tenant, P0