@hz-9/a5-tenant 0.2.0-alpha.26

package/README.md

@@ -0,0 +1,129 @@
+# @hz-9/a5-tenant
+
+Tenant module for the @hz-9/a5-* series of repositories.
+
+## Features
+
+- ✅ 租户检查 Guard
+- ✅ 从 headers 和 route params 中提取租户 ID
+- ✅ 可配置的租户 Service
+- ✅ TypeScript 完整类型支持
+- ✅ 全局模块支持
+
+## Installation
+
+```bash
+pnpm add @hz-9/a5-tenant
+```
+
+## Quick Start
+
+### 1. 实现租户 Service
+
+```typescript
+import { Injectable } from '@nestjs/common'
+import { A5TenantService, A5TenantCheckResult } from '@hz-9/a5-tenant'
+
+@Injectable()
+export class MyTenantService implements A5TenantService {
+  async checkTenant(tenantId: string, userId?: string): Promise<A5TenantCheckResult> {
+    // 在此实现你的租户检查逻辑
+    const tenant = await this.db.tenant.findUnique({ where: { id: tenantId } })
+
+    if (!tenant) {
+      return {
+        valid: false,
+        message: 'Tenant not found',
+      }
+    }
+
+    return {
+      valid: true,
+      context: {
+        tenantId,
+        userId,
+      },
+    }
+  }
+}
+```
+
+### 2. 注册模块
+
+```typescript
+import { Module } from '@nestjs/common'
+import { A5TenantModule } from '@hz-9/a5-tenant'
+import { MyTenantService } from './my-tenant.service'
+
+@Module({
+  imports: [
+    A5TenantModule.forRoot({
+      tenantService: new MyTenantService(),
+      isGlobal: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 3. 使用 Guard
+
+```typescript
+import { Controller, Get, UseGuards } from '@nestjs/common'
+import { A5TenantGuard } from '@hz-9/a5-tenant'
+
+@Controller('/api/data')
+@UseGuards(A5TenantGuard)
+export class DataController {
+  @Get()
+  getData() {
+    return { data: 'example' }
+  }
+}
+```
+
+## 获取租户 ID
+
+在控制器中可以通过 request 对象获取租户信息：
+
+```typescript
+import { Controller, Get, Req, UseGuards } from '@nestjs/common'
+import { FastifyRequest } from '@hz-9/a5-core/interface/http'
+import { A5TenantGuard } from '@hz-9/a5-tenant'
+
+@Controller('/api/data')
+@UseGuards(A5TenantGuard)
+export class DataController {
+  @Get()
+  getData(@Req() request: FastifyRequest) {
+    const tenantId = (request as any).tenantId
+    const tenantContext = (request as any).tenantContext
+    return { tenantId, tenantContext }
+  }
+}
+```
+
+## 租户 ID 来源
+
+Guard 会依次从以下位置尝试获取租户 ID：
+
+1. **Headers**: `x-tenant-id` header
+2. **Route Params**: `tenantId` 路由参数
+
+## 配置选项
+
+### A5TenantModuleOptions
+
+```typescript
+interface A5TenantModuleOptions {
+  // 租户 Service 提供者
+  tenantService: A5TenantService | ProviderConfig
+
+  // 是否为全局模块（默认：true）
+  isGlobal?: boolean
+}
+```
+
+## License
+
+MIT

package/dist/all.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @packageDocumentation
+ * A5 Tenant Module - Tenant management and validation for A5 framework
+ */
+
+import { A5TenantGuardConstructorOptions as A5TenantGuardConstructorOptions_2 } from '../interfaces';
+import { CanActivate } from '@nestjs/common';
+import { ConfigurableModuleCls } from '@nestjs/common';
+import { ExecutionContext } from '@nestjs/common';
+import type { FastifyRequest } from '@hz-9/a5-core/interface/http';
+
+/**
+ * @public
+ */
+export declare const A5_REQUEST_TENANT_ID: "A5_REQUEST_TENANT_ID";
+
+/**
+ * @public
+ */
+export declare const A5_REQUEST_TENANT_PAYLOAD: "A5_REQUEST_TENANT_PAYLOAD";
+
+/**
+ * @public
+ */
+export declare const A5_TENANT_ID_HEADER: "x-tenant-id";
+
+/**
+ * @public
+ */
+export declare const A5_TENANT_ID_PARAM: "tenantId";
+
+/**
+ * @public
+ */
+export declare const A5_TENANT_MODULE_OPTIONS: string | symbol;
+
+/**
+ * Tenant Service Token
+ * @public
+ */
+export declare const A5_TENANT_SERVICE_TOKEN: "A5_TENANT_SERVICE_TOKEN";
+
+/**
+ * @public
+ */
+export declare const A5TenantConfigurableModule: ConfigurableModuleCls<A5TenantGuardConstructorOptions_2, "forRoot", "createOptions", {
+isGlobal: boolean;
+}>;
+
+/**
+ * @public
+ */
+export declare const A5TenantCurrentTenant: (...dataOrPipes: unknown[]) => ParameterDecorator;
+
+/**
+ * @public
+ */
+export declare const A5TenantCurrentTenantId: (...dataOrPipes: unknown[]) => ParameterDecorator;
+
+/**
+ * 租户检查 Guard
+ *
+ * 从 headers 或 route params 中获取租户 ID，并检查租户是否存在
+ *
+ * @public
+ */
+export declare class A5TenantGuard implements CanActivate {
+    private readonly tenantService;
+    private readonly options;
+    constructor(options: A5TenantGuardConstructorOptions, tenantService: A5TenantService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private parseFromHeaders;
+    /**
+     * 从 headers 中获取租户 ID
+     *
+     * @param request - FastifyRequest 对象
+     * @returns 租户 ID 或 undefined
+     */
+    private getTenantIdFromHeaders;
+}
+
+/**
+ * @public
+ */
+export declare interface A5TenantGuardConstructorOptions {
+    /**
+     * 是否启用空白自动转换为默认租户功能
+     *
+     * @defaultValue true
+     */
+    emptyToDefault?: boolean;
+    /**
+     * 默认租户 ID
+     *
+     * @defaultValue '-'
+     */
+    defaultTenantId?: string;
+}
+
+/**
+ * @public
+ */
+export declare type A5TenantGuardOptions = Required<A5TenantGuardConstructorOptions>;
+
+/**
+ * @public
+ */
+export declare class A5TenantModule extends A5TenantConfigurableModule {
+}
+
+/**
+ * A5 缓存模块异步配置选项接口
+ *
+ * @public
+ */
+export declare interface A5TenantModuleAsyncOptions {
+    /**
+     * 工厂函数，返回 A5TenantModuleOptions 配置对象
+     */
+    useFactory?: (...args: unknown[]) => Promise<A5TenantModuleOptions> | A5TenantModuleOptions;
+    /**
+     * 需要注入到 useFactory 函数中的依赖项
+     */
+    inject?: unknown[];
+    /**
+     * 需要导入的模块列表
+     */
+    imports?: unknown[];
+}
+
+/**
+ * A5 缓存模块配置选项
+ *
+ * @public
+ */
+export declare type A5TenantModuleOptions = A5TenantGuardConstructorOptions;
+
+/**
+ * @public
+ *
+ * 载荷信息
+ *
+ */
+export declare interface A5TenantPayloadBo {
+    tenantId: string;
+}
+
+/**
+ * @public
+ */
+export declare interface A5TenantService {
+    /**
+     * 获取租户信息，如果没有，则返回 null
+     *
+     * @param tenantId - 租户 ID
+     * @returns 检查结果
+     */
+    getTenant(tenantId: string): Promise<A5TenantPayloadBo | null>;
+    /**
+     * 返回默认租户信息
+     *
+     * @param tenantId - 租户 ID
+     * @returns 检查结果
+     */
+    getDefaultTenant(defaultTenantId: string): Promise<A5TenantPayloadBo>;
+}
+
+/**
+ * @public
+ */
+export declare type FastifyRequestWithTenant = FastifyRequest & {
+    [A5_REQUEST_TENANT_ID]?: string;
+    [A5_REQUEST_TENANT_PAYLOAD]?: A5TenantPayloadBo;
+};
+
+export { }

package/dist/bos/index.d.ts

@@ -0,0 +1 @@
+export * from './tenant-payload.bo';

package/dist/bos/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./tenant-payload.bo"), exports);
+//# sourceMappingURL=index.js.map

package/dist/bos/tenant-payload.bo.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @public
+ *
+ * 载荷信息
+ *
+ */
+export interface A5TenantPayloadBo {
+    tenantId: string;
+}

package/dist/bos/tenant-payload.bo.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=tenant-payload.bo.js.map

package/dist/const/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tenant Service Token
+ * @public
+ */
+export declare const A5_TENANT_SERVICE_TOKEN: "A5_TENANT_SERVICE_TOKEN";
+/**
+ * @public
+ */
+export declare const A5_TENANT_ID_HEADER: "x-tenant-id";
+/**
+ * @public
+ */
+export declare const A5_TENANT_ID_PARAM: "tenantId";
+/**
+ * @public
+ */
+export declare const A5_REQUEST_TENANT_ID: "A5_REQUEST_TENANT_ID";
+/**
+ * @public
+ */
+export declare const A5_REQUEST_TENANT_PAYLOAD: "A5_REQUEST_TENANT_PAYLOAD";

package/dist/const/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5_REQUEST_TENANT_PAYLOAD = exports.A5_REQUEST_TENANT_ID = exports.A5_TENANT_ID_PARAM = exports.A5_TENANT_ID_HEADER = exports.A5_TENANT_SERVICE_TOKEN = void 0;
+/**
+ * Tenant Service Token
+ * @public
+ */
+exports.A5_TENANT_SERVICE_TOKEN = 'A5_TENANT_SERVICE_TOKEN';
+/**
+ * @public
+ */
+exports.A5_TENANT_ID_HEADER = 'x-tenant-id';
+/**
+ * @public
+ */
+exports.A5_TENANT_ID_PARAM = 'tenantId';
+/**
+ * @public
+ */
+exports.A5_REQUEST_TENANT_ID = 'A5_REQUEST_TENANT_ID';
+/**
+ * @public
+ */
+exports.A5_REQUEST_TENANT_PAYLOAD = 'A5_REQUEST_TENANT_PAYLOAD';
+//# sourceMappingURL=index.js.map

package/dist/core/a5-tenant.guard.d.ts

@@ -0,0 +1,24 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import type { A5TenantGuardConstructorOptions } from '../interfaces/tenant';
+import type { A5TenantService } from './a5-tenant.service';
+/**
+ * 租户检查 Guard
+ *
+ * 从 headers 或 route params 中获取租户 ID，并检查租户是否存在
+ *
+ * @public
+ */
+export declare class A5TenantGuard implements CanActivate {
+    private readonly tenantService;
+    private readonly options;
+    constructor(options: A5TenantGuardConstructorOptions, tenantService: A5TenantService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private parseFromHeaders;
+    /**
+     * 从 headers 中获取租户 ID
+     *
+     * @param request - FastifyRequest 对象
+     * @returns 租户 ID 或 undefined
+     */
+    private getTenantIdFromHeaders;
+}

package/dist/core/a5-tenant.guard.js

@@ -0,0 +1,86 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5TenantGuard = void 0;
+const common_1 = require("@nestjs/common");
+const const_1 = require("../const");
+const module_definition_1 = require("./module-definition");
+const optionsWithDefaults = (options) => ({
+    emptyToDefault: true,
+    defaultTenantId: '-',
+    ...options,
+});
+/**
+ * 租户检查 Guard
+ *
+ * 从 headers 或 route params 中获取租户 ID，并检查租户是否存在
+ *
+ * @public
+ */
+let A5TenantGuard = class A5TenantGuard {
+    constructor(options, tenantService) {
+        this.tenantService = tenantService;
+        this.options = optionsWithDefaults(options);
+    }
+    async canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        // TODO 后续可以基于 metadata 信息，对解析方案进行自定义优化
+        return this.parseFromHeaders(request);
+    }
+    async parseFromHeaders(request) {
+        // 尝试从 headers 中获取租户 ID
+        let tenantId = this.getTenantIdFromHeaders(request);
+        if (!tenantId) {
+            if (this.options.emptyToDefault) {
+                tenantId = this.options.defaultTenantId;
+                const tenant = await this.tenantService.getDefaultTenant(tenantId);
+                // 将租户信息存储到 request 对象中供后续使用
+                // eslint-disable-next-line require-atomic-updates
+                request[const_1.A5_REQUEST_TENANT_ID] = tenantId;
+                // eslint-disable-next-line require-atomic-updates
+                request[const_1.A5_REQUEST_TENANT_PAYLOAD] = tenant;
+                return true;
+            }
+            throw new common_1.UnauthorizedException('No tenant ID found');
+        }
+        // 检查租户是否存在和有效
+        const tenant = await this.tenantService.getTenant(tenantId);
+        if (!tenant) {
+            throw new common_1.ForbiddenException('tenant ID is not valid');
+        }
+        // 将租户信息存储到 request 对象中供后续使用
+        // eslint-disable-next-line require-atomic-updates
+        request[const_1.A5_REQUEST_TENANT_ID] = tenantId;
+        // eslint-disable-next-line require-atomic-updates
+        request[const_1.A5_REQUEST_TENANT_PAYLOAD] = tenant;
+        return true;
+    }
+    /**
+     * 从 headers 中获取租户 ID
+     *
+     * @param request - FastifyRequest 对象
+     * @returns 租户 ID 或 undefined
+     */
+    getTenantIdFromHeaders(request) {
+        return request.headers[const_1.A5_TENANT_ID_HEADER];
+    }
+};
+exports.A5TenantGuard = A5TenantGuard;
+exports.A5TenantGuard = A5TenantGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(module_definition_1.A5_TENANT_MODULE_OPTIONS)),
+    __param(1, (0, common_1.Inject)(const_1.A5_TENANT_SERVICE_TOKEN)),
+    __metadata("design:paramtypes", [Object, Object])
+], A5TenantGuard);
+//# sourceMappingURL=a5-tenant.guard.js.map

package/dist/core/a5-tenant.module.d.ts

@@ -0,0 +1,6 @@
+import { A5TenantConfigurableModule } from './module-definition';
+/**
+ * @public
+ */
+export declare class A5TenantModule extends A5TenantConfigurableModule {
+}

package/dist/core/a5-tenant.module.js

@@ -0,0 +1,37 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5TenantModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const a5_tenant_guard_1 = require("./a5-tenant.guard");
+const module_definition_1 = require("./module-definition");
+/**
+ * @public
+ */
+let A5TenantModule = class A5TenantModule extends module_definition_1.A5TenantConfigurableModule {
+};
+exports.A5TenantModule = A5TenantModule;
+exports.A5TenantModule = A5TenantModule = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        providers: [
+            {
+                provide: core_1.APP_GUARD,
+                useClass: a5_tenant_guard_1.A5TenantGuard,
+            },
+        ],
+        // exports: [
+        //   {
+        //     provide: APP_GUARD,
+        //     useClass: A5TenantGuard,
+        //   },
+        // ],
+    })
+], A5TenantModule);
+//# sourceMappingURL=a5-tenant.module.js.map

package/dist/core/a5-tenant.service.d.ts

@@ -0,0 +1,20 @@
+import { A5TenantPayloadBo } from '../bos/tenant-payload.bo';
+/**
+ * @public
+ */
+export interface A5TenantService {
+    /**
+     * 获取租户信息，如果没有，则返回 null
+     *
+     * @param tenantId - 租户 ID
+     * @returns 检查结果
+     */
+    getTenant(tenantId: string): Promise<A5TenantPayloadBo | null>;
+    /**
+     * 返回默认租户信息
+     *
+     * @param tenantId - 租户 ID
+     * @returns 检查结果
+     */
+    getDefaultTenant(defaultTenantId: string): Promise<A5TenantPayloadBo>;
+}

package/dist/core/a5-tenant.service.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=a5-tenant.service.js.map

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export * from './a5-tenant.guard';
+export * from './a5-tenant.module';
+export * from './a5-tenant.service';
+export * from './module-definition';

package/dist/core/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./a5-tenant.guard"), exports);
+__exportStar(require("./a5-tenant.module"), exports);
+__exportStar(require("./a5-tenant.service"), exports);
+__exportStar(require("./module-definition"), exports);
+//# sourceMappingURL=index.js.map

package/dist/core/module-definition.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @public
+ */
+export declare const A5TenantConfigurableModule: import("@nestjs/common").ConfigurableModuleCls<import("../interfaces").A5TenantGuardConstructorOptions, "forRoot", "createOptions", {
+    isGlobal: boolean;
+}>;
+/**
+ * @public
+ */
+export declare const A5_TENANT_MODULE_OPTIONS: string | symbol;

package/dist/core/module-definition.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5_TENANT_MODULE_OPTIONS = exports.A5TenantConfigurableModule = void 0;
+const common_1 = require("@nestjs/common");
+// eslint-disable-next-line @rushstack/typedef-var
+const moduleDefinition = new common_1.ConfigurableModuleBuilder({
+    moduleName: 'A5Tenant',
+})
+    .setExtras({
+    isGlobal: true,
+}, (definition, options) => ({
+    ...definition,
+    global: options.isGlobal,
+}))
+    .setClassMethodName('forRoot')
+    .setFactoryMethodName('createOptions')
+    .build();
+/**
+ * @public
+ */
+// eslint-disable-next-line @rushstack/typedef-var
+exports.A5TenantConfigurableModule = moduleDefinition.ConfigurableModuleClass;
+/**
+ * @public
+ */
+// eslint-disable-next-line @rushstack/typedef-var
+exports.A5_TENANT_MODULE_OPTIONS = moduleDefinition.MODULE_OPTIONS_TOKEN;
+//# sourceMappingURL=module-definition.js.map

package/dist/decorators/a5-tenant-current-tenant-id.decorator.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @public
+ */
+export declare const A5TenantCurrentTenantId: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/a5-tenant-current-tenant-id.decorator.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5TenantCurrentTenantId = void 0;
+/* eslint-disable @rushstack/typedef-var */
+const common_1 = require("@nestjs/common");
+const tenant_util_1 = require("../utils/tenant.util");
+/**
+ * @public
+ */
+exports.A5TenantCurrentTenantId = (0, common_1.createParamDecorator)((data, ctx) => {
+    const request = ctx.switchToHttp().getRequest();
+    return tenant_util_1.A5TenantUtil.getTenantIdFromRequest(request);
+});
+//# sourceMappingURL=a5-tenant-current-tenant-id.decorator.js.map

package/dist/decorators/a5-tenant-current-tenant.decorator.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @public
+ */
+export declare const A5TenantCurrentTenant: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/a5-tenant-current-tenant.decorator.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5TenantCurrentTenant = void 0;
+/* eslint-disable @rushstack/typedef-var */
+const common_1 = require("@nestjs/common");
+const tenant_util_1 = require("../utils/tenant.util");
+/**
+ * @public
+ */
+exports.A5TenantCurrentTenant = (0, common_1.createParamDecorator)((data, ctx) => {
+    const request = ctx.switchToHttp().getRequest();
+    return tenant_util_1.A5TenantUtil.getTenantFromRequest(request);
+});
+//# sourceMappingURL=a5-tenant-current-tenant.decorator.js.map