@lark-apaas/fullstack-nestjs-core 1.0.3-alpha.8 → 1.0.3

package/README.md

@@ -1,12 +1,15 @@
 # @lark-apaas/fullstack-nestjs-core
 
-FullStack NestJS Core 是一个为 NestJS 应用提供核心功能的工具包，包括 CSRF 保护、用户上下文管理和开发工具等。
+FullStack NestJS Core 是一个为 NestJS 全栈应用提供核心功能的工具包，包括平台集成、CSRF 保护、用户上下文管理和开发工具等。
 
 ## 特性
 
+- **平台模块**: 一站式集成 Config、Logger、Database、Auth 等核心功能
 - **CSRF 保护**: 提供完整的 CSRF Token 生成和验证机制
 - **用户上下文**: 自动从请求头中提取并注入用户上下文信息
-- **开发工具**: 自动生成 Swagger 文档、OpenAPI JSON 和客户端 SDK
+- **视图上下文**: 将用户信息和 CSRF Token 注入到模板渲染上下文
+- **开发工具**: 自动生成 Swagger 文档、OpenAPI JSON 和 TypeScript 客户端 SDK
+- **应用配置**: 一键配置 Logger、Cookie Parser、全局前缀等
 
 ## 安装
 
@@ -27,226 +30,330 @@ yarn add @lark-apaas/fullstack-nestjs-core
 
 ## 快速开始
 
-### 1. CSRF 保护
+### 方案 1: 使用 PlatformModule（推荐）
 
-CSRF 保护由两个中间件组成：`CsrfTokenMiddleware` 用于生成 token，`CsrfMiddleware` 用于验证 token。
+最简单的方式是使用 `PlatformModule`，它会自动集成所有核心功能：
 
-#### 使用默认配置
+```typescript
+import { Module } from '@nestjs/common';
+import { PlatformModule } from '@lark-apaas/fullstack-nestjs-core';
+
+@Module({
+  imports: [
+    PlatformModule.forRoot({
+      enableCsrf: true,           // 是否启用 CSRF 保护，默认 true
+      csrfRoutes: '/api/*',       // CSRF 保护的路由，默认 '/api/*'
+      alwaysNeedLogin: true,      // 是否所有路由都需要登录，默认 true
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`PlatformModule` 自动集成：
+- ✅ ConfigModule (环境变量配置)
+- ✅ LoggerModule (日志系统)
+- ✅ DataPaasModule (数据库连接)
+- ✅ AuthNPaasModule (认证系统)
+- ✅ UserContextMiddleware (用户上下文)
+- ✅ CsrfTokenMiddleware + CsrfMiddleware (CSRF 保护)
+- ✅ ViewContextMiddleware (视图上下文)
+- ✅ ValidationPipe (全局验证管道)
+
+### 方案 2: 使用 configureApp 辅助函数
+
+在 `main.ts` 中使用 `configureApp` 快速配置应用：
 
 ```typescript
-import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
-import { CsrfTokenMiddleware, CsrfMiddleware } from '@lark-apaas/fullstack-nestjs-core';
+import { NestFactory } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { configureApp } from '@lark-apaas/fullstack-nestjs-core';
+import { AppModule } from './app.module';
 
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    // 直接应用中间件，使用默认配置
-    consumer
-      .apply(CsrfTokenMiddleware)
-      .forRoutes('*'); // 所有路由都生成 token
+async function bootstrap() {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule);
 
-    consumer
-      .apply(CsrfMiddleware)
-      .forRoutes('*'); // 所有路由都验证 CSRF token
-  }
+  // 一键配置：Logger、CookieParser、GlobalPrefix、DevTools
+  await configureApp(app);
+
+  await app.listen(3000);
 }
+bootstrap();
 ```
 
-#### 自定义配置（可选）
+`configureApp` 会自动：
+- ✅ 注册 AppLogger
+- ✅ 注册 cookie-parser 中间件
+- ✅ 根据 `CLIENT_BASE_PATH` 环境变量设置全局前缀
+- ✅ 在非生产环境自动挂载 `DevToolsV2Module`
+
+### 方案 3: 手动配置各个模块
 
-如需自定义配置，可在应用中间件前调用 `configure` 方法：
+如果需要更细粒度的控制，可以单独使用各个模块：
 
 ```typescript
 import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
-import { CsrfTokenMiddleware, CsrfMiddleware } from '@lark-apaas/fullstack-nestjs-core';
+import {
+  CsrfTokenMiddleware,
+  CsrfMiddleware,
+  UserContextMiddleware,
+  ViewContextMiddleware,
+} from '@lark-apaas/fullstack-nestjs-core';
 
 @Module({})
 export class AppModule implements NestModule {
   configure(consumer: MiddlewareConsumer) {
-    // 自定义配置 CSRF Token 生成中间件
-    CsrfTokenMiddleware.configure({
-      cookieKey: 'CSRF-TOKEN',        // 默认: 'suda-csrf-token'
-      cookieMaxAge: 86400000,         // 默认: 2592000000 (30天)
-      cookiePath: '/',                // 默认: '/'
-    });
-
-    // 自定义配置 CSRF 验证中间件
-    CsrfMiddleware.configure({
-      headerKey: 'X-CSRF-TOKEN',      // 默认: 'x-suda-csrf-token'
-      cookieKey: 'CSRF-TOKEN',        // 默认: 'suda-csrf-token'
-    });
+    // 用户上下文中间件
+    consumer
+      .apply(UserContextMiddleware)
+      .forRoutes('*');
 
-    // 应用中间件
+    // CSRF Token 生成（用于视图渲染）
     consumer
       .apply(CsrfTokenMiddleware)
+      .exclude('/api/(.*)')
       .forRoutes('*');
 
+    // 视图上下文注入
     consumer
-      .apply(CsrfMiddleware)
+      .apply(ViewContextMiddleware)
+      .exclude('/api/(.*)')
       .forRoutes('*');
+
+    // CSRF 验证（用于 API 保护）
+    consumer
+      .apply(CsrfMiddleware)
+      .forRoutes('/api/*');
   }
 }
 ```
 
-**注意**: 如果使用自定义的 `cookieKey`，需要确保 `CsrfTokenMiddleware` 和 `CsrfMiddleware` 配置的 `cookieKey` 一致。
+## 核心模块
 
-### 2. 用户上下文
+### PlatformModule
 
-自动从请求头中提取用户信息并注入到请求对象中。
+全局平台模块，集成了所有核心功能。
 
-```typescript
-import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
-import { UserContextMiddleware } from '@lark-apaas/fullstack-nestjs-core';
+#### 配置选项
 
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer
-      .apply(UserContextMiddleware)
-      .forRoutes('*');
-  }
-}
-```
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| enableCsrf | boolean | `true` | 是否启用 CSRF 保护 |
+| csrfRoutes | string \| string[] | `'/api/*'` | CSRF 保护应用的路由 |
+| alwaysNeedLogin | boolean | `true` | 是否所有路由都需要登录 |
 
-在控制器中使用：
+#### 使用示例
 
 ```typescript
-import { Controller, Get, Req } from '@nestjs/common';
-import { Request } from 'express';
-
-@Controller()
-export class AppController {
-  @Get()
-  getUser(@Req() req: Request) {
-    // 访问用户上下文
-    const { userId, tenantId, appId } = req.userContext;
-    return { userId, tenantId, appId };
-  }
-}
+@Module({
+  imports: [
+    PlatformModule.forRoot({
+      enableCsrf: true,
+      csrfRoutes: ['/api/*', '/admin/*'],
+      alwaysNeedLogin: false,
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
-### 3. 开发工具模块
+### DevToolsV2Module（推荐）
+
+使用 `@hey-api/openapi-ts` 生成高质量的 TypeScript 客户端 SDK。
+
+**新特性：**
+- ✅ 使用最新的 `@hey-api/openapi-ts` 生成器
+- ✅ 自动注入 `baseURL` 配置到生成的客户端
+- ✅ 自动给所有生成的文件添加 `// @ts-nocheck` 注释
+
+#### 配置选项
 
-在开发环境中自动生成 Swagger 文档和客户端 SDK。
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| basePath | string | `'/'` | API 基础路径 |
+| docsPath | string | `'/api/docs'` | Swagger UI 的挂载路径 |
+| openapiOut | string | `'./client/src/api/gen/openapi.json'` | OpenAPI JSON 输出路径 |
+| needSetupServer | boolean | `false` | 是否挂载 Swagger UI 服务器 |
+| needGenerateClientSdk | boolean | `true` | 是否生成客户端 SDK |
+| clientSdkOut | string | `'./client/src/api/gen'` | 客户端 SDK 输出目录 |
+| swaggerOptions | object | - | Swagger 文档配置 |
+
+#### 使用示例
 
 ```typescript
 import { NestFactory } from '@nestjs/core';
-import { DevToolsModule } from '@lark-apaas/fullstack-nestjs-core';
+import { DevToolsV2Module } from '@lark-apaas/fullstack-nestjs-core';
 import { AppModule } from './app.module';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
 
-  // 挂载开发工具
-  await DevToolsModule.mount(app, {
-    docsPath: 'api-docs',
-    openapiOut: './openapi.json',
-    needSetupServer: true,
-    needGenerateClientSdk: true,
-    clientSdkOut: './src/sdk',
-    swaggerOptions: {
-      title: 'My API',
-      version: '1.0.0',
-      customSiteTitle: 'My API Documentation',
-    },
-  });
+  // 在开发环境挂载开发工具
+  if (process.env.NODE_ENV !== 'production') {
+    await DevToolsV2Module.mount(app, {
+      basePath: '/app',
+      docsPath: '/api_docs',
+      needSetupServer: true,
+      needGenerateClientSdk: true,
+      swaggerOptions: {
+        title: 'My API',
+        version: '1.0.0',
+      },
+    });
+  }
 
   await app.listen(3000);
 }
 bootstrap();
 ```
 
-## API 文档
+#### 生成的文件
+
+```
+client/src/api/gen/
+├── openapi.json              # OpenAPI 规范文件
+├── client.config.ts          # 客户端配置（自动生成 baseURL）
+├── types.gen.ts              # TypeScript 类型定义
+├── sdk.gen.ts                # SDK 函数
+└── client/
+    └── client.gen.ts         # Axios 客户端
+```
+
+所有生成的 `.ts` 文件都会自动添加 `// @ts-nocheck` 注释，避免类型检查错误。
+
+### DevToolsModule（旧版）
+
+使用 `openapi-typescript-codegen` 生成客户端 SDK（不推荐，建议迁移到 `DevToolsV2Module`）。
+
+```typescript
+import { DevToolsModule } from '@lark-apaas/fullstack-nestjs-core';
+
+await DevToolsModule.mount(app, {
+  docsPath: 'api-docs',
+  openapiOut: './openapi.json',
+  needSetupServer: true,
+  needGenerateClientSdk: true,
+  clientSdkOut: './src/sdk',
+});
+```
+
+## 中间件
 
 ### CsrfTokenMiddleware
 
-生成 CSRF Token 并设置到 Cookie 中。
+生成 CSRF Token 并设置到 Cookie 中，用于视图渲染场景。
 
-#### 配置选项 (CsrfTokenOptions)
+#### 配置选项
 
 | 选项 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| cookieKey | string | `'suda-csrf-token'` | Cookie 中存储 CSRF Token 的键名 |
-| cookieMaxAge | number | `2592000000` (30天) | Cookie 的过期时间（毫秒） |
-| cookiePath | string | `'/'` | Cookie 的路径 |
+| cookieKey | string | `'suda-csrf-token'` | Cookie 中存储 Token 的键名 |
+| cookieMaxAge | number | `2592000000` (30天) | Cookie 过期时间（毫秒） |
+| cookiePath | string | `'/'` | Cookie 路径 |
 
-#### 静态方法
+#### 使用示例
 
-- `configure(opts: CsrfTokenOptions)`: 配置中间件选项
+```typescript
+CsrfTokenMiddleware.configure({
+  cookieKey: 'my-csrf-token',
+  cookieMaxAge: 86400000, // 1天
+});
+
+consumer
+  .apply(CsrfTokenMiddleware)
+  .exclude('/api/(.*)')
+  .forRoutes('*');
+```
 
 ### CsrfMiddleware
 
-验证请求中的 CSRF Token。
+验证请求中的 CSRF Token，用于保护 API 接口。
 
-#### 配置选项 (CsrfOptions)
+#### 配置选项
 
 | 选项 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| headerKey | string | `'x-suda-csrf-token'` | 请求头中 CSRF Token 的键名 |
-| cookieKey | string | `'suda-csrf-token'` | Cookie 中 CSRF Token 的键名 |
+| headerKey | string | `'x-suda-csrf-token'` | 请求头中 Token 的键名 |
+| cookieKey | string | `'suda-csrf-token'` | Cookie 中 Token 的键名 |
 
-#### 静态方法
+#### 使用示例
 
-- `configure(opts: CsrfOptions)`: 配置中间件选项
-
-#### 验证规则
-
-1. 检查 Cookie 中是否存在 CSRF Token
-2. 检查请求头中是否存在 CSRF Token
-3. 验证两者是否匹配
+```typescript
+CsrfMiddleware.configure({
+  headerKey: 'x-my-csrf-token',
+  cookieKey: 'my-csrf-token',
+});
+
+consumer
+  .apply(CsrfMiddleware)
+  .forRoutes('/api/*');
+```
 
-如果任何一步验证失败，将返回 403 Forbidden。
+**注意**: 确保 `CsrfTokenMiddleware` 和 `CsrfMiddleware` 的 `cookieKey` 配置一致。
 
 ### UserContextMiddleware
 
-从请求头中提取用户上下文信息。
+从请求头中提取用户上下文信息并注入到 `req.userContext`。
 
 #### 注入的上下文
 
 ```typescript
 req.userContext = {
-  userId: string | undefined;    // 用户 ID
-  tenantId: string | undefined;  // 租户 ID
-  appId: string;                 // 应用 ID
+  userId: string | undefined;    // 用户 ID（来自 x-user-id 请求头）
+  tenantId: string | undefined;  // 租户 ID（来自 x-tenant-id 请求头）
+  appId: string;                 // 应用 ID（来自 x-app-id 请求头）
+}
+```
+
+#### 使用示例
+
+```typescript
+@Controller()
+export class AppController {
+  @Get('profile')
+  getProfile(@Req() req: Request) {
+    const { userId, tenantId, appId } = req.userContext;
+    return { userId, tenantId, appId };
+  }
 }
 ```
 
-### DevToolsModule
+### ViewContextMiddleware
 
-开发工具模块，用于生成 API 文档和客户端 SDK。
+将用户上下文和 CSRF Token 注入到 `res.locals`，用于模板渲染。
 
-#### 配置选项 (DevToolsOptions)
+#### 注入的变量
 
-| 选项 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| basePath | string | - | 基础路径 |
-| docsPath | string | - | Swagger UI 的挂载路径 |
-| openapiOut | string | - | OpenAPI JSON 文件的输出路径 |
-| needSetupServer | boolean | - | 是否需要挂载 Swagger UI |
-| needGenerateClientSdk | boolean | - | 是否生成客户端 SDK |
-| clientSdkOut | string | - | 客户端 SDK 的输出目录 |
-| swaggerOptions | object | - | Swagger 文档配置 |
-| swaggerOptions.title | string | - | Swagger 文档标题 |
-| swaggerOptions.version | string | - | API 版本号 |
-| swaggerOptions.customSiteTitle | string | - | 自定义站点标题 |
-| swaggerOptions.customCss | string | - | 自定义 CSS 样式 |
+```typescript
+res.locals = {
+  csrfToken: string;   // CSRF Token
+  userId: string;      // 用户 ID
+  tenantId: string;    // 租户 ID
+  appId: string;       // 应用 ID
+}
+```
 
-#### 静态方法
+#### 使用示例
 
-- `mount(app: INestApplication, opts?: DevToolsOptions)`: 挂载开发工具到应用
+```typescript
+// 在模板引擎中可以直接使用这些变量
+// EJS 示例：
+<input type="hidden" name="_csrf" value="<%= csrfToken %>">
+<div>User ID: <%= userId %></div>
+```
 
 ## TypeScript 支持
 
 本包完全使用 TypeScript 编写，并提供完整的类型定义。
 
-扩展 Express Request 类型：
+### 扩展 Express Request 类型
 
 ```typescript
 declare global {
   namespace Express {
     interface Request {
       csrfToken?: string;
-      userContext?: {
+      userContext: {
         userId?: string;
         tenantId?: string;
         appId: string;
@@ -256,6 +363,13 @@ declare global {
 }
 ```
 
+## 环境变量
+
+| 变量名 | 描述 | 默认值 |
+|--------|------|--------|
+| CLIENT_BASE_PATH | 应用的全局路径前缀 | - |
+| NODE_ENV | 运行环境 | - |
+
 ## 许可证
 
 MIT
@@ -266,3 +380,4 @@ MIT
 - nestjs
 - server
 - typescript
+- fullstack

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   CsrfMiddleware: () => CsrfMiddleware,
   CsrfTokenMiddleware: () => CsrfTokenMiddleware,
   DevToolsModule: () => DevToolsModule,
+  DevToolsV2Module: () => DevToolsV2Module,
   PlatformModule: () => PlatformModule,
   UserContextMiddleware: () => UserContextMiddleware,
   ViewContextMiddleware: () => ViewContextMiddleware,
@@ -89,7 +90,8 @@ var UserContextMiddleware = class {
     req.userContext = {
       userId: webUser?.user_id,
       tenantId: webUser?.tenant_id,
-      appId: webUser?.app_id ?? ""
+      appId: webUser?.app_id ?? "",
+      loginUrl: webUser?.login_url ?? ""
     };
     next();
   }
@@ -170,6 +172,12 @@ var ViewContextMiddleware = class {
   use(req, res, next) {
     const { userId, tenantId, appId } = req.userContext;
     const csrfToken = req.csrfToken;
+    req.__platform_data__ = {
+      csrfToken: csrfToken ?? "",
+      userId: userId ?? "",
+      appId: appId ?? "",
+      tenantId
+    };
     res.locals = {
       ...res.locals ?? {},
       csrfToken: csrfToken ?? "",
@@ -317,9 +325,7 @@ var PlatformModule = class _PlatformModule {
             };
           }, "useFactory")
         }),
-        import_nestjs_authnpaas.AuthNPaasModule.forRoot({
-          alwaysNeedLogin: options.alwaysNeedLogin ?? true
-        })
+        import_nestjs_authnpaas.AuthNPaasModule.forRoot()
       ],
       providers: [
         {
@@ -363,16 +369,14 @@ PlatformModule = _ts_decorate5([
 
 // src/setup.ts
 var import_nestjs_logger2 = require("@lark-apaas/nestjs-logger");
-var import_path = require("path");
-var import_hbs = require("hbs");
 var import_cookie_parser = __toESM(require("cookie-parser"), 1);
 
-// src/modules/devtool/index.ts
+// src/modules/devtool-v2/index.ts
 var import_swagger = require("@nestjs/swagger");
-var import_node_fs3 = require("fs");
-var import_node_path3 = require("path");
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
 
-// src/modules/devtool/helper.ts
+// src/modules/devtool-v2/helper.ts
 var import_node_path = require("path");
 var import_node_fs = require("fs");
 function normalizeBasePath(rawBasePath) {
@@ -409,14 +413,14 @@ function ensureDirAndWrite(filePath, content) {
 }
 __name(ensureDirAndWrite, "ensureDirAndWrite");
 
-// src/modules/devtool/plugins/client-config-generator.ts
+// src/modules/devtool-v2/plugins/client-config-generator.ts
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
 function generateClientConfig(options) {
   const configFilePath = (0, import_node_path2.resolve)(options.outputPath, "client.config.ts");
   const configContent = `// This file is auto-generated by @hey-api/openapi-ts
 import axios from 'axios';
-import type { CreateClientConfig } from './client/client.gen';
+import type { CreateClientConfig } from './client';
 export const createClientConfig: CreateClientConfig = (config) => ({
   axios
 });
@@ -426,10 +430,43 @@ export const createClientConfig: CreateClientConfig = (config) => ({
 }
 __name(generateClientConfig, "generateClientConfig");
 
-// src/modules/devtool/index.ts
-var DevToolsModule = class {
+// src/modules/devtool-v2/plugins/add-ts-nocheck.ts
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
+function addTsNocheckToGeneratedFiles(outputPath) {
+  const files = getAllTsFiles(outputPath);
+  for (const filePath of files) {
+    addTsNocheckToFile(filePath);
+  }
+}
+__name(addTsNocheckToGeneratedFiles, "addTsNocheckToGeneratedFiles");
+function getAllTsFiles(dirPath) {
+  const files = [];
+  const entries = (0, import_node_fs3.readdirSync)(dirPath);
+  for (const entry of entries) {
+    const fullPath = (0, import_node_path3.join)(dirPath, entry);
+    const stat = (0, import_node_fs3.statSync)(fullPath);
+    if (stat.isDirectory()) {
+      files.push(...getAllTsFiles(fullPath));
+    } else if (stat.isFile() && entry.endsWith(".ts")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+__name(getAllTsFiles, "getAllTsFiles");
+function addTsNocheckToFile(filePath) {
+  const content = (0, import_node_fs3.readFileSync)(filePath, "utf-8");
+  const newContent = `// @ts-nocheck
+${content}`;
+  (0, import_node_fs3.writeFileSync)(filePath, newContent, "utf-8");
+}
+__name(addTsNocheckToFile, "addTsNocheckToFile");
+
+// src/modules/devtool-v2/index.ts
+var DevToolsV2Module = class {
   static {
-    __name(this, "DevToolsModule");
+    __name(this, "DevToolsV2Module");
   }
   static async mount(app, opts = {}) {
     const options = resolveOptsWithDefaultValue(opts);
@@ -446,16 +483,13 @@ var DevToolsModule = class {
       });
       console.log(`[OpenAPI] Swagger UI \u5DF2\u6302\u8F7D\u81F3 ${options.docsPath}`);
     }
-    const openapiPath = (0, import_node_path3.resolve)(baseDirname, options.openapiOut);
+    const openapiPath = (0, import_node_path4.resolve)(baseDirname, options.openapiOut);
     ensureDirAndWrite(openapiPath, JSON.stringify(document, null, 2));
     if (options.needGenerateClientSdk) {
-      const clientSdkOutPath = (0, import_node_path3.resolve)(baseDirname, options.clientSdkOut);
-      (0, import_node_fs3.mkdirSync)(clientSdkOutPath, {
+      const clientSdkOutPath = (0, import_node_path4.resolve)(baseDirname, options.clientSdkOut);
+      (0, import_node_fs4.mkdirSync)(clientSdkOutPath, {
         recursive: true
       });
-      generateClientConfig({
-        outputPath: clientSdkOutPath
-      });
       const { createClient } = await import("@hey-api/openapi-ts");
       await createClient({
         input: openapiPath,
@@ -467,28 +501,29 @@ var DevToolsModule = class {
           "@hey-api/sdk",
           {
             name: "@hey-api/client-axios",
-            runtimeConfigPath: (0, import_node_path3.join)(clientSdkOutPath, "./client.config.ts")
+            runtimeConfigPath: (0, import_node_path4.join)(clientSdkOutPath, "./client.config.ts")
           }
         ]
       });
+      addTsNocheckToGeneratedFiles(clientSdkOutPath);
       ensureDirAndWrite(openapiPath, JSON.stringify(document, null, 2));
+      generateClientConfig({
+        outputPath: clientSdkOutPath
+      });
       console.log("[OpenAPI] \u5BFC\u51FA openapi.json \u5E76\u751F\u6210 axios SDK \u2705");
     }
   }
 };
 
 // src/setup.ts
-async function configureApp(app, options) {
+async function configureApp(app) {
   app.useLogger(app.get(import_nestjs_logger2.AppLogger));
   app.flushLogs();
   app.use((0, import_cookie_parser.default)());
   const globalPrefix = process.env.CLIENT_BASE_PATH ?? "";
   app.setGlobalPrefix(globalPrefix);
-  app.setBaseViewsDir((0, import_path.join)(process.cwd(), options?.viewsDir ?? "dist/client"));
-  app.setViewEngine("html");
-  app.engine("html", import_hbs.__express);
   if (process.env.NODE_ENV !== "production") {
-    await DevToolsModule.mount(app, {
+    await DevToolsV2Module.mount(app, {
       basePath: process.env.CLIENT_BASE_PATH,
       docsPath: "/api_docs"
     });
@@ -496,6 +531,90 @@ async function configureApp(app, options) {
 }
 __name(configureApp, "configureApp");
 
+// src/modules/devtool/index.ts
+var import_swagger2 = require("@nestjs/swagger");
+var import_node_fs6 = require("fs");
+var import_node_path6 = require("path");
+
+// src/modules/devtool/helper.ts
+var import_node_path5 = require("path");
+var import_node_fs5 = require("fs");
+function normalizeBasePath2(rawBasePath) {
+  const normalizedBasePath = rawBasePath.startsWith("/") ? rawBasePath : `/${rawBasePath}`;
+  return normalizedBasePath.endsWith("/") ? normalizedBasePath.slice(0, -1) : normalizedBasePath;
+}
+__name(normalizeBasePath2, "normalizeBasePath");
+function resolveOptsWithDefaultValue2(options) {
+  const basePath = normalizeBasePath2(options.basePath || "/");
+  const docsPath = normalizeBasePath2(options.docsPath || `api/docs`);
+  return {
+    ...options,
+    needSetupServer: options.needSetupServer ?? false,
+    basePath,
+    docsPath: `${basePath}${docsPath}`,
+    openapiOut: options.openapiOut || "./client/src/api/gen/openapi.json",
+    clientSdkOut: options.clientSdkOut || "./client/src/api/gen",
+    needGenerateClientSdk: options.needGenerateClientSdk ?? true,
+    swaggerOptions: {
+      title: options.swaggerOptions?.title ?? "NestJS Fullstack API",
+      version: options.swaggerOptions?.version ?? "1.0.0",
+      customSiteTitle: options.swaggerOptions?.customSiteTitle ?? "API Documentation",
+      customCss: options.swaggerOptions?.customCss ?? ".swagger-ui .topbar { display: none }"
+    }
+  };
+}
+__name(resolveOptsWithDefaultValue2, "resolveOptsWithDefaultValue");
+function ensureDirAndWrite2(filePath, content) {
+  const dir = (0, import_node_path5.dirname)(filePath);
+  (0, import_node_fs5.mkdirSync)(dir, {
+    recursive: true
+  });
+  (0, import_node_fs5.writeFileSync)(filePath, content);
+}
+__name(ensureDirAndWrite2, "ensureDirAndWrite");
+
+// src/modules/devtool/index.ts
+var DevToolsModule = class {
+  static {
+    __name(this, "DevToolsModule");
+  }
+  static async mount(app, opts = {}) {
+    const options = resolveOptsWithDefaultValue2(opts);
+    const baseDirname = process.cwd();
+    const builder = new import_swagger2.DocumentBuilder().setTitle(options.swaggerOptions.title).setVersion(options.swaggerOptions.version);
+    const document = import_swagger2.SwaggerModule.createDocument(app, builder.build(), {
+      operationIdFactory: /* @__PURE__ */ __name((_c, m) => m, "operationIdFactory")
+    });
+    if (options.needSetupServer) {
+      import_swagger2.SwaggerModule.setup(options.docsPath, app, document, {
+        customSiteTitle: options.swaggerOptions.customSiteTitle,
+        customCss: options.swaggerOptions.customCss,
+        swaggerOptions: {
+          persistAuthorization: true
+        }
+      });
+      console.log(`[OpenAPI] Swagger UI \u5DF2\u6302\u8F7D\u81F3 ${options.docsPath}`);
+    }
+    const openapiPath = (0, import_node_path6.resolve)(baseDirname, options.openapiOut);
+    ensureDirAndWrite2(openapiPath, JSON.stringify(document, null, 2));
+    if (options.needGenerateClientSdk) {
+      const clientSdkOutPath = (0, import_node_path6.resolve)(baseDirname, options.clientSdkOut);
+      (0, import_node_fs6.mkdirSync)(clientSdkOutPath, {
+        recursive: true
+      });
+      const { generate } = await import("openapi-typescript-codegen");
+      await generate({
+        input: openapiPath,
+        output: clientSdkOutPath,
+        httpClient: "axios",
+        useOptions: false,
+        exportServices: true
+      });
+      console.log("[OpenAPI] \u5BFC\u51FA openapi.json \u5E76\u751F\u6210 axios SDK \u2705");
+    }
+  }
+};
+
 // src/index.ts
 __reExport(index_exports, require("@lark-apaas/nestjs-authnpaas"), module.exports);
 __reExport(index_exports, require("@lark-apaas/nestjs-datapaas"), module.exports);
@@ -504,6 +623,7 @@ __reExport(index_exports, require("@lark-apaas/nestjs-datapaas"), module.exports
   CsrfMiddleware,
   CsrfTokenMiddleware,
   DevToolsModule,
+  DevToolsV2Module,
   PlatformModule,
   UserContextMiddleware,
   ViewContextMiddleware,

package/dist/index.d.cts

@@ -7,12 +7,19 @@ export * from '@lark-apaas/nestjs-datapaas';
 declare global {
   namespace Express {
     interface Request {
-      csrfToken?: string;
+      __platform_data__?: {
+        userId?: string;
+        tenantId?: number;
+        csrfToken?: string;
+        [key: string]: unknown;
+      };
       userContext: {
         userId?: string;
         tenantId?: number;
         appId?: string;
-      }
+        loginUrl?: string;
+      },
+      csrfToken?: string;
     }
   }
 }
@@ -31,11 +38,6 @@ interface PlatformModuleOptions {
      * 默认: '/api/*'
      */
     csrfRoutes?: string | string[];
-    /**
-     * AuthN 能力，是否全部依赖登录
-     * 默认：true
-     */
-    alwaysNeedLogin?: boolean;
 }
 
 declare class PlatformModule implements NestModule {
@@ -47,11 +49,9 @@ declare class PlatformModule implements NestModule {
     configure(consumer: MiddlewareConsumer): void;
 }
 
-declare function configureApp(app: NestExpressApplication, options?: {
-    viewsDir?: string;
-}): Promise<void>;
+declare function configureApp(app: NestExpressApplication): Promise<void>;
 
-interface DevToolsOptions {
+interface DevToolsOptions$1 {
     basePath?: string;
     docsPath?: string;
     openapiOut?: string;
@@ -66,7 +66,29 @@ interface DevToolsOptions {
     };
 }
 
+/**
+ * @deprecated 该模块已被废弃，不建议使用，建议使用 DevToolsV2Module
+ */
 declare class DevToolsModule {
+    static mount(app: INestApplication, opts?: DevToolsOptions$1): Promise<void>;
+}
+
+interface DevToolsOptions {
+    basePath?: string;
+    docsPath?: string;
+    openapiOut?: string;
+    needSetupServer?: boolean;
+    needGenerateClientSdk?: boolean;
+    clientSdkOut?: string;
+    swaggerOptions?: {
+        title?: string;
+        version?: string;
+        customSiteTitle?: string;
+        customCss?: string;
+    };
+}
+
+declare class DevToolsV2Module {
     static mount(app: INestApplication, opts?: DevToolsOptions): Promise<void>;
 }
 
@@ -101,4 +123,4 @@ declare class ViewContextMiddleware implements NestMiddleware {
     use(req: Request, res: Response, next: NextFunction): void;
 }
 
-export { CsrfMiddleware, CsrfTokenMiddleware, DevToolsModule, PlatformModule, type PlatformModuleOptions, UserContextMiddleware, ViewContextMiddleware, configureApp };
+export { CsrfMiddleware, CsrfTokenMiddleware, DevToolsModule, DevToolsV2Module, PlatformModule, type PlatformModuleOptions, UserContextMiddleware, ViewContextMiddleware, configureApp };

package/dist/index.d.ts

@@ -7,12 +7,19 @@ export * from '@lark-apaas/nestjs-datapaas';
 declare global {
   namespace Express {
     interface Request {
-      csrfToken?: string;
+      __platform_data__?: {
+        userId?: string;
+        tenantId?: number;
+        csrfToken?: string;
+        [key: string]: unknown;
+      };
       userContext: {
         userId?: string;
         tenantId?: number;
         appId?: string;
-      }
+        loginUrl?: string;
+      },
+      csrfToken?: string;
     }
   }
 }
@@ -31,11 +38,6 @@ interface PlatformModuleOptions {
      * 默认: '/api/*'
      */
     csrfRoutes?: string | string[];
-    /**
-     * AuthN 能力，是否全部依赖登录
-     * 默认：true
-     */
-    alwaysNeedLogin?: boolean;
 }
 
 declare class PlatformModule implements NestModule {
@@ -47,11 +49,9 @@ declare class PlatformModule implements NestModule {
     configure(consumer: MiddlewareConsumer): void;
 }
 
-declare function configureApp(app: NestExpressApplication, options?: {
-    viewsDir?: string;
-}): Promise<void>;
+declare function configureApp(app: NestExpressApplication): Promise<void>;
 
-interface DevToolsOptions {
+interface DevToolsOptions$1 {
     basePath?: string;
     docsPath?: string;
     openapiOut?: string;
@@ -66,7 +66,29 @@ interface DevToolsOptions {
     };
 }
 
+/**
+ * @deprecated 该模块已被废弃，不建议使用，建议使用 DevToolsV2Module
+ */
 declare class DevToolsModule {
+    static mount(app: INestApplication, opts?: DevToolsOptions$1): Promise<void>;
+}
+
+interface DevToolsOptions {
+    basePath?: string;
+    docsPath?: string;
+    openapiOut?: string;
+    needSetupServer?: boolean;
+    needGenerateClientSdk?: boolean;
+    clientSdkOut?: string;
+    swaggerOptions?: {
+        title?: string;
+        version?: string;
+        customSiteTitle?: string;
+        customCss?: string;
+    };
+}
+
+declare class DevToolsV2Module {
     static mount(app: INestApplication, opts?: DevToolsOptions): Promise<void>;
 }
 
@@ -101,4 +123,4 @@ declare class ViewContextMiddleware implements NestMiddleware {
     use(req: Request, res: Response, next: NextFunction): void;
 }
 
-export { CsrfMiddleware, CsrfTokenMiddleware, DevToolsModule, PlatformModule, type PlatformModuleOptions, UserContextMiddleware, ViewContextMiddleware, configureApp };
+export { CsrfMiddleware, CsrfTokenMiddleware, DevToolsModule, DevToolsV2Module, PlatformModule, type PlatformModuleOptions, UserContextMiddleware, ViewContextMiddleware, configureApp };

package/dist/index.js

@@ -48,7 +48,8 @@ var UserContextMiddleware = class {
     req.userContext = {
       userId: webUser?.user_id,
       tenantId: webUser?.tenant_id,
-      appId: webUser?.app_id ?? ""
+      appId: webUser?.app_id ?? "",
+      loginUrl: webUser?.login_url ?? ""
     };
     next();
   }
@@ -129,6 +130,12 @@ var ViewContextMiddleware = class {
   use(req, res, next) {
     const { userId, tenantId, appId } = req.userContext;
     const csrfToken = req.csrfToken;
+    req.__platform_data__ = {
+      csrfToken: csrfToken ?? "",
+      userId: userId ?? "",
+      appId: appId ?? "",
+      tenantId
+    };
     res.locals = {
       ...res.locals ?? {},
       csrfToken: csrfToken ?? "",
@@ -276,9 +283,7 @@ var PlatformModule = class _PlatformModule {
             };
           }, "useFactory")
         }),
-        AuthNPaasModule.forRoot({
-          alwaysNeedLogin: options.alwaysNeedLogin ?? true
-        })
+        AuthNPaasModule.forRoot()
       ],
       providers: [
         {
@@ -322,16 +327,14 @@ PlatformModule = _ts_decorate5([
 
 // src/setup.ts
 import { AppLogger as AppLogger2 } from "@lark-apaas/nestjs-logger";
-import { join as join2 } from "path";
-import { __express as hbsExpressEngine } from "hbs";
 import cookieParser from "cookie-parser";
 
-// src/modules/devtool/index.ts
+// src/modules/devtool-v2/index.ts
 import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";
 import { mkdirSync as mkdirSync2 } from "fs";
-import { resolve as resolve2, join } from "path";
+import { resolve as resolve2, join as join2 } from "path";
 
-// src/modules/devtool/helper.ts
+// src/modules/devtool-v2/helper.ts
 import { dirname } from "path";
 import { writeFileSync, mkdirSync } from "fs";
 function normalizeBasePath(rawBasePath) {
@@ -368,14 +371,14 @@ function ensureDirAndWrite(filePath, content) {
 }
 __name(ensureDirAndWrite, "ensureDirAndWrite");
 
-// src/modules/devtool/plugins/client-config-generator.ts
+// src/modules/devtool-v2/plugins/client-config-generator.ts
 import { writeFileSync as writeFileSync2 } from "fs";
 import { resolve } from "path";
 function generateClientConfig(options) {
   const configFilePath = resolve(options.outputPath, "client.config.ts");
   const configContent = `// This file is auto-generated by @hey-api/openapi-ts
 import axios from 'axios';
-import type { CreateClientConfig } from './client/client.gen';
+import type { CreateClientConfig } from './client';
 export const createClientConfig: CreateClientConfig = (config) => ({
   axios
 });
@@ -385,10 +388,43 @@ export const createClientConfig: CreateClientConfig = (config) => ({
 }
 __name(generateClientConfig, "generateClientConfig");
 
-// src/modules/devtool/index.ts
-var DevToolsModule = class {
+// src/modules/devtool-v2/plugins/add-ts-nocheck.ts
+import { readdirSync, readFileSync, writeFileSync as writeFileSync3, statSync } from "fs";
+import { join } from "path";
+function addTsNocheckToGeneratedFiles(outputPath) {
+  const files = getAllTsFiles(outputPath);
+  for (const filePath of files) {
+    addTsNocheckToFile(filePath);
+  }
+}
+__name(addTsNocheckToGeneratedFiles, "addTsNocheckToGeneratedFiles");
+function getAllTsFiles(dirPath) {
+  const files = [];
+  const entries = readdirSync(dirPath);
+  for (const entry of entries) {
+    const fullPath = join(dirPath, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      files.push(...getAllTsFiles(fullPath));
+    } else if (stat.isFile() && entry.endsWith(".ts")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+__name(getAllTsFiles, "getAllTsFiles");
+function addTsNocheckToFile(filePath) {
+  const content = readFileSync(filePath, "utf-8");
+  const newContent = `// @ts-nocheck
+${content}`;
+  writeFileSync3(filePath, newContent, "utf-8");
+}
+__name(addTsNocheckToFile, "addTsNocheckToFile");
+
+// src/modules/devtool-v2/index.ts
+var DevToolsV2Module = class {
   static {
-    __name(this, "DevToolsModule");
+    __name(this, "DevToolsV2Module");
   }
   static async mount(app, opts = {}) {
     const options = resolveOptsWithDefaultValue(opts);
@@ -412,9 +448,6 @@ var DevToolsModule = class {
       mkdirSync2(clientSdkOutPath, {
         recursive: true
       });
-      generateClientConfig({
-        outputPath: clientSdkOutPath
-      });
       const { createClient } = await import("@hey-api/openapi-ts");
       await createClient({
         input: openapiPath,
@@ -426,28 +459,29 @@ var DevToolsModule = class {
           "@hey-api/sdk",
           {
             name: "@hey-api/client-axios",
-            runtimeConfigPath: join(clientSdkOutPath, "./client.config.ts")
+            runtimeConfigPath: join2(clientSdkOutPath, "./client.config.ts")
           }
         ]
       });
+      addTsNocheckToGeneratedFiles(clientSdkOutPath);
       ensureDirAndWrite(openapiPath, JSON.stringify(document, null, 2));
+      generateClientConfig({
+        outputPath: clientSdkOutPath
+      });
       console.log("[OpenAPI] \u5BFC\u51FA openapi.json \u5E76\u751F\u6210 axios SDK \u2705");
     }
   }
 };
 
 // src/setup.ts
-async function configureApp(app, options) {
+async function configureApp(app) {
   app.useLogger(app.get(AppLogger2));
   app.flushLogs();
   app.use(cookieParser());
   const globalPrefix = process.env.CLIENT_BASE_PATH ?? "";
   app.setGlobalPrefix(globalPrefix);
-  app.setBaseViewsDir(join2(process.cwd(), options?.viewsDir ?? "dist/client"));
-  app.setViewEngine("html");
-  app.engine("html", hbsExpressEngine);
   if (process.env.NODE_ENV !== "production") {
-    await DevToolsModule.mount(app, {
+    await DevToolsV2Module.mount(app, {
       basePath: process.env.CLIENT_BASE_PATH,
       docsPath: "/api_docs"
     });
@@ -455,6 +489,90 @@ async function configureApp(app, options) {
 }
 __name(configureApp, "configureApp");
 
+// src/modules/devtool/index.ts
+import { SwaggerModule as SwaggerModule2, DocumentBuilder as DocumentBuilder2 } from "@nestjs/swagger";
+import { mkdirSync as mkdirSync4 } from "fs";
+import { resolve as resolve3 } from "path";
+
+// src/modules/devtool/helper.ts
+import { dirname as dirname2 } from "path";
+import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync3 } from "fs";
+function normalizeBasePath2(rawBasePath) {
+  const normalizedBasePath = rawBasePath.startsWith("/") ? rawBasePath : `/${rawBasePath}`;
+  return normalizedBasePath.endsWith("/") ? normalizedBasePath.slice(0, -1) : normalizedBasePath;
+}
+__name(normalizeBasePath2, "normalizeBasePath");
+function resolveOptsWithDefaultValue2(options) {
+  const basePath = normalizeBasePath2(options.basePath || "/");
+  const docsPath = normalizeBasePath2(options.docsPath || `api/docs`);
+  return {
+    ...options,
+    needSetupServer: options.needSetupServer ?? false,
+    basePath,
+    docsPath: `${basePath}${docsPath}`,
+    openapiOut: options.openapiOut || "./client/src/api/gen/openapi.json",
+    clientSdkOut: options.clientSdkOut || "./client/src/api/gen",
+    needGenerateClientSdk: options.needGenerateClientSdk ?? true,
+    swaggerOptions: {
+      title: options.swaggerOptions?.title ?? "NestJS Fullstack API",
+      version: options.swaggerOptions?.version ?? "1.0.0",
+      customSiteTitle: options.swaggerOptions?.customSiteTitle ?? "API Documentation",
+      customCss: options.swaggerOptions?.customCss ?? ".swagger-ui .topbar { display: none }"
+    }
+  };
+}
+__name(resolveOptsWithDefaultValue2, "resolveOptsWithDefaultValue");
+function ensureDirAndWrite2(filePath, content) {
+  const dir = dirname2(filePath);
+  mkdirSync3(dir, {
+    recursive: true
+  });
+  writeFileSync4(filePath, content);
+}
+__name(ensureDirAndWrite2, "ensureDirAndWrite");
+
+// src/modules/devtool/index.ts
+var DevToolsModule = class {
+  static {
+    __name(this, "DevToolsModule");
+  }
+  static async mount(app, opts = {}) {
+    const options = resolveOptsWithDefaultValue2(opts);
+    const baseDirname = process.cwd();
+    const builder = new DocumentBuilder2().setTitle(options.swaggerOptions.title).setVersion(options.swaggerOptions.version);
+    const document = SwaggerModule2.createDocument(app, builder.build(), {
+      operationIdFactory: /* @__PURE__ */ __name((_c, m) => m, "operationIdFactory")
+    });
+    if (options.needSetupServer) {
+      SwaggerModule2.setup(options.docsPath, app, document, {
+        customSiteTitle: options.swaggerOptions.customSiteTitle,
+        customCss: options.swaggerOptions.customCss,
+        swaggerOptions: {
+          persistAuthorization: true
+        }
+      });
+      console.log(`[OpenAPI] Swagger UI \u5DF2\u6302\u8F7D\u81F3 ${options.docsPath}`);
+    }
+    const openapiPath = resolve3(baseDirname, options.openapiOut);
+    ensureDirAndWrite2(openapiPath, JSON.stringify(document, null, 2));
+    if (options.needGenerateClientSdk) {
+      const clientSdkOutPath = resolve3(baseDirname, options.clientSdkOut);
+      mkdirSync4(clientSdkOutPath, {
+        recursive: true
+      });
+      const { generate } = await import("openapi-typescript-codegen");
+      await generate({
+        input: openapiPath,
+        output: clientSdkOutPath,
+        httpClient: "axios",
+        useOptions: false,
+        exportServices: true
+      });
+      console.log("[OpenAPI] \u5BFC\u51FA openapi.json \u5E76\u751F\u6210 axios SDK \u2705");
+    }
+  }
+};
+
 // src/index.ts
 export * from "@lark-apaas/nestjs-authnpaas";
 export * from "@lark-apaas/nestjs-datapaas";
@@ -462,6 +580,7 @@ export {
   CsrfMiddleware,
   CsrfTokenMiddleware,
   DevToolsModule,
+  DevToolsV2Module,
   PlatformModule,
   UserContextMiddleware,
   ViewContextMiddleware,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-nestjs-core",
-  "version": "1.0.3-alpha.8",
+  "version": "1.0.3",
   "description": "FullStack Nestjs Core",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,9 +19,7 @@
     "node": ">=18.0.0"
   },
   "files": [
-    "dist",
-    "templates",
-    "postinstall.config.mjs"
+    "dist"
   ],
   "exports": {
     ".": {
@@ -40,12 +38,12 @@
     "lint:fix": "eslint src --ext .ts --fix"
   },
   "dependencies": {
-    "@hey-api/openapi-ts": "^0.86.11",
+    "@hey-api/openapi-ts": "^0.87.0",
     "@lark-apaas/nestjs-authnpaas": "^1.0.0",
     "@lark-apaas/nestjs-datapaas": "^1.0.1",
     "@lark-apaas/nestjs-logger": "^1.0.0",
     "cookie-parser": "^1.4.7",
-    "hbs": "^4.2.0"
+    "openapi-typescript-codegen": "^0.29.0"
   },
   "devDependencies": {
     "@nestjs/common": "^10.4.20",
@@ -53,7 +51,6 @@
     "@nestjs/swagger": "^7.4.2",
     "@types/cookie-parser": "^1.4.9",
     "@types/express": "^5.0.3",
-    "@types/hbs": "^4.0.5",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.2",
     "drizzle-orm": "0.44.6",