create-pardx-scaffold 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pardx-scaffold",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Scaffold a new project from PardxAI monorepo (git-tracked files)",
   "license": "MIT",
   "bin": "./cli.js",

package/template/apps/api/libs/infra/clients/internal/ip-info/dto/ip-info.dto.ts

@@ -0,0 +1,15 @@
+/**
+ * IP Info API Response DTO
+ *
+ * @description ipinfo.io API 返回的数据结构
+ */
+export interface IpInfoResponse {
+  ip: string;
+  country: string;
+  region?: string;
+  city?: string;
+  loc?: string;
+  org?: string;
+  postal?: string;
+  timezone?: string;
+}

package/template/apps/api/libs/infra/clients/internal/ip-info/index.ts

@@ -0,0 +1,3 @@
+export * from './ip-info.module';
+export * from './ip-info.client';
+export * from './dto/ip-info.dto';

package/template/apps/api/libs/infra/clients/internal/ip-info/ip-info.client.ts

@@ -0,0 +1,57 @@
+/**
+ * IP Info Client
+ *
+ * 职责：仅负责与 ipinfo.io API 通信
+ * - 调用 ipinfo.io API 获取 IP 地理位置信息
+ * - 不访问数据库
+ * - 不包含业务逻辑
+ */
+import { Injectable, Inject } from '@nestjs/common';
+import { HttpService } from '@nestjs/axios';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { ConfigService } from '@nestjs/config';
+import { firstValueFrom } from 'rxjs';
+import { IpInfoResponse } from './dto/ip-info.dto';
+import { IpInfoConfig } from '@/config/validation';
+
+@Injectable()
+export class IpInfoClient {
+  private readonly config: IpInfoConfig;
+
+  constructor(
+    private readonly httpService: HttpService,
+    private readonly configService: ConfigService,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {
+    this.config = configService.getOrThrow<IpInfoConfig>('ipinfo');
+  }
+
+  /**
+   * 获取 IP 地理位置信息
+   * @param ip IP 地址
+   * @returns IP 信息
+   */
+  async getIpInfo(ip: string): Promise<IpInfoResponse> {
+    const url = `${this.config.url}/${ip}?token=${this.config.token}`;
+
+    try {
+      const response = await firstValueFrom(
+        this.httpService.get<IpInfoResponse>(url, {
+          timeout: 10000,
+        }),
+      );
+
+      this.logger.debug(`IP info fetched for ${ip}`, {
+        country: response.data.country,
+      });
+
+      return response.data;
+    } catch (error) {
+      this.logger.error(`Failed to fetch IP info for ${ip}`, {
+        error: (error as Error).message,
+      });
+      throw error;
+    }
+  }
+}

package/template/apps/api/libs/infra/clients/internal/ip-info/ip-info.module.ts

@@ -0,0 +1,17 @@
+import { Module } from '@nestjs/common';
+import { HttpModule } from '@nestjs/axios';
+import { ConfigModule } from '@nestjs/config';
+import { IpInfoClient } from './ip-info.client';
+
+@Module({
+  imports: [
+    ConfigModule,
+    HttpModule.register({
+      timeout: 10000,
+      maxRedirects: 3,
+    }),
+  ],
+  providers: [IpInfoClient],
+  exports: [IpInfoClient],
+})
+export class IpInfoClientModule {}

package/template/apps/api/libs/infra/shared-services/file-storage/README.md

@@ -59,7 +59,7 @@ file-storage/
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { FileStorageServiceModule } from '@app/services/file-storage';
+import { FileStorageServiceModule } from '@app/shared-services/file-storage';
 
 @Module({
   imports: [FileStorageServiceModule],
@@ -71,7 +71,7 @@ export class VideoModule {}
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { FileStorageService } from '@app/services/file-storage';
+import { FileStorageService } from '@app/shared-services/file-storage';
 import { FileBucketVendor } from '@prisma/client';
 
 @Injectable()
@@ -244,7 +244,7 @@ const audioInfo = await fileStorage.getAudioInfo('oss', 'bucket', 'audio.mp3');
 用于高级场景，直接操作存储客户端。
 
 ```typescript
-import { FileStorageClientFactory } from '@app/services/file-storage';
+import { FileStorageClientFactory } from '@app/shared-services/file-storage';
 
 // 获取客户端
 const client = factory.getClient('oss', 'my-bucket');
@@ -267,7 +267,7 @@ const configs = factory.getAllBucketConfigs();
 用于存储桶解析的高级场景。
 
 ```typescript
-import { BucketResolver } from '@app/services/file-storage';
+import { BucketResolver } from '@app/shared-services/file-storage';
 
 // 解析存储桶
 const result = await resolver.resolve({

package/template/apps/api/libs/infra/shared-services/file-storage/bucket-resolver.ts

@@ -16,7 +16,7 @@ import { Logger } from 'winston';
 import { FileBucketVendor } from '@prisma/client';
 
 import { PardxUploader } from '@app/clients/internal/file-storage';
-import { IpInfoService } from '@app/services/ip-info';
+import { IpGeoService } from '@app/shared-services/ip-geo';
 import { AppConfig } from '@/config/validation';
 import arrayUtil from '@/utils/array.util';
 import enviromentUtil from '@/utils/enviroment.util';
@@ -89,12 +89,12 @@ export class BucketResolver {
    * 构造函数
    *
    * @param {ConfigService} configService - NestJS 配置服务
-   * @param {IpInfoService} ipInfoService - IP 信息服务
+   * @param {IpGeoService} ipGeoService - IP 地理位置服务（infra 层）
    * @param {Logger} logger - Winston 日志记录器
    */
   constructor(
     private readonly configService: ConfigService,
-    private readonly ipInfoService: IpInfoService,
+    private readonly ipGeoService: IpGeoService,
     @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
   ) {
     this.bucketConfigs =
@@ -178,7 +178,7 @@ export class BucketResolver {
     // 确定区域
     let zone = enviromentUtil.getBaseZone();
     if (ip) {
-      const continent = await this.ipInfoService.getContinent(ip);
+      const continent = await this.ipGeoService.getContinent(ip);
       zone = continent ?? zone;
     }
     locale = locale ?? zone;

package/template/apps/api/libs/infra/shared-services/file-storage/file-storage.module.ts

@@ -12,7 +12,7 @@
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import { HttpModule } from '@nestjs/axios';
-import { IpInfoServiceModule } from '@app/services/ip-info';
+import { IpGeoModule } from '@app/shared-services/ip-geo';
 import { RedisModule } from '@app/redis';
 import { FileStorageService } from './file-storage.service';
 import { FileStorageClientFactory } from './file-storage.factory';
@@ -32,7 +32,7 @@ import { BucketResolver } from './bucket-resolver';
  * - `ConfigModule`: 配置服务
  * - `HttpModule`: HTTP 客户端
  * - `RedisModule`: Redis 缓存
- * - `IpInfoServiceModule`: IP 信息服务（用于区域感知）
+ * - `IpGeoModule`: IP 地理位置服务（用于区域感知，纯 infra 层）
  *
  * @example
  * ```typescript
@@ -55,7 +55,7 @@ import { BucketResolver } from './bucket-resolver';
  * ```
  */
 @Module({
-  imports: [ConfigModule, RedisModule, IpInfoServiceModule, HttpModule],
+  imports: [ConfigModule, RedisModule, IpGeoModule, HttpModule],
   providers: [BucketResolver, FileStorageClientFactory, FileStorageService],
   exports: [FileStorageService, FileStorageClientFactory, BucketResolver],
 })

package/template/apps/api/libs/infra/shared-services/ip-geo/continent-mapping.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview 国家代码到大洲的静态映射
+ *
+ * 本文件提供纯静态的国家代码到大洲映射，不依赖数据库。
+ * 用于 infra 层的 IP 地理位置服务，避免 infra 依赖 domain。
+ *
+ * @module ip-geo/continent-mapping
+ */
+
+/**
+ * 大洲类型
+ */
+export type Continent = 'as' | 'eu' | 'na' | 'sa' | 'af' | 'oc' | 'an';
+
+/**
+ * 大洲到国家代码的映射
+ *
+ * 数据来源：ISO 3166-1 alpha-2 国家代码
+ */
+export const CONTINENT_COUNTRIES: Record<Continent, string[]> = {
+  // 亚洲 (Asia)
+  as: [
+    'AF', 'AM', 'AZ', 'BH', 'BD', 'BT', 'BN', 'KH', 'CN', 'CY', 'GE', 'HK',
+    'IN', 'ID', 'IR', 'IQ', 'IL', 'JP', 'JO', 'KZ', 'KW', 'KG', 'LA', 'LB',
+    'MO', 'MY', 'MV', 'MN', 'MM', 'NP', 'KP', 'OM', 'PK', 'PS', 'PH', 'QA',
+    'SA', 'SG', 'KR', 'LK', 'SY', 'TW', 'TJ', 'TH', 'TL', 'TR', 'TM', 'AE',
+    'UZ', 'VN', 'YE',
+  ],
+  // 欧洲 (Europe)
+  eu: [
+    'AL', 'AD', 'AT', 'BY', 'BE', 'BA', 'BG', 'HR', 'CZ', 'DK', 'EE', 'FI',
+    'FR', 'DE', 'GR', 'HU', 'IS', 'IE', 'IT', 'XK', 'LV', 'LI', 'LT', 'LU',
+    'MT', 'MD', 'MC', 'ME', 'NL', 'MK', 'NO', 'PL', 'PT', 'RO', 'RU', 'SM',
+    'RS', 'SK', 'SI', 'ES', 'SE', 'CH', 'UA', 'GB', 'VA',
+  ],
+  // 北美洲 (North America)
+  na: [
+    'AG', 'BS', 'BB', 'BZ', 'CA', 'CR', 'CU', 'DM', 'DO', 'SV', 'GD', 'GT',
+    'HT', 'HN', 'JM', 'MX', 'NI', 'PA', 'KN', 'LC', 'VC', 'TT', 'US',
+  ],
+  // 南美洲 (South America)
+  sa: [
+    'AR', 'BO', 'BR', 'CL', 'CO', 'EC', 'GY', 'PY', 'PE', 'SR', 'UY', 'VE',
+  ],
+  // 非洲 (Africa)
+  af: [
+    'DZ', 'AO', 'BJ', 'BW', 'BF', 'BI', 'CV', 'CM', 'CF', 'TD', 'KM', 'CG',
+    'CD', 'DJ', 'EG', 'GQ', 'ER', 'SZ', 'ET', 'GA', 'GM', 'GH', 'GN', 'GW',
+    'CI', 'KE', 'LS', 'LR', 'LY', 'MG', 'MW', 'ML', 'MR', 'MU', 'MA', 'MZ',
+    'NA', 'NE', 'NG', 'RW', 'ST', 'SN', 'SC', 'SL', 'SO', 'ZA', 'SS', 'SD',
+    'TZ', 'TG', 'TN', 'UG', 'ZM', 'ZW',
+  ],
+  // 大洋洲 (Oceania)
+  oc: [
+    'AU', 'FJ', 'KI', 'MH', 'FM', 'NR', 'NZ', 'PW', 'PG', 'WS', 'SB', 'TO',
+    'TV', 'VU',
+  ],
+  // 南极洲 (Antarctica) - 通常无常住人口
+  an: ['AQ'],
+};
+
+/**
+ * 国家代码到大洲的反向映射（运行时生成）
+ */
+export const COUNTRY_TO_CONTINENT: Record<string, Continent> = {};
+
+// 构建反向映射
+for (const [continent, countries] of Object.entries(CONTINENT_COUNTRIES)) {
+  for (const country of countries) {
+    COUNTRY_TO_CONTINENT[country] = continent as Continent;
+  }
+}
+
+/**
+ * 根据国家代码获取大洲
+ *
+ * @param countryCode - ISO 3166-1 alpha-2 国家代码
+ * @param defaultContinent - 默认大洲（找不到时返回）
+ * @returns 大洲代码
+ */
+export function getContinentByCountry(
+  countryCode: string,
+  defaultContinent: Continent = 'as',
+): Continent {
+  return COUNTRY_TO_CONTINENT[countryCode?.toUpperCase()] ?? defaultContinent;
+}

package/template/apps/api/libs/infra/shared-services/ip-geo/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview IP 地理位置服务导出入口（Infra 层）
+ *
+ * 本模块提供纯 infra 层的 IP 地理位置服务：
+ * - IpGeoService: IP 地理位置查询服务
+ * - IpGeoModule: NestJS 模块
+ * - getContinentByCountry: 静态大洲映射函数
+ *
+ * @example
+ * ```typescript
+ * import { IpGeoModule, IpGeoService } from '@app/shared-services/ip-geo';
+ *
+ * @Module({
+ *   imports: [IpGeoModule],
+ * })
+ * export class MyModule {}
+ *
+ * @Injectable()
+ * class MyService {
+ *   constructor(private readonly ipGeo: IpGeoService) {}
+ *
+ *   async getRegion(ip: string) {
+ *     return await this.ipGeo.getContinent(ip);
+ *   }
+ * }
+ * ```
+ *
+ * @module ip-geo
+ */
+export { IpGeoModule } from './ip-geo.module';
+export { IpGeoService } from './ip-geo.service';
+export {
+  getContinentByCountry,
+  Continent,
+  CONTINENT_COUNTRIES,
+  COUNTRY_TO_CONTINENT,
+} from './continent-mapping';

package/template/apps/api/libs/infra/shared-services/ip-geo/ip-geo.module.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview IP 地理位置服务模块（Infra 层）
+ *
+ * @module ip-geo/module
+ */
+import { Module } from '@nestjs/common';
+import { RedisModule } from '@app/redis';
+import { IpInfoClientModule } from '@app/clients/internal/ip-info';
+import { IpGeoService } from './ip-geo.service';
+
+/**
+ * IP 地理位置服务模块
+ *
+ * @description 提供纯 infra 层的 IP 地理位置服务，不依赖 domain 层。
+ */
+@Module({
+  imports: [RedisModule, IpInfoClientModule],
+  providers: [IpGeoService],
+  exports: [IpGeoService],
+})
+export class IpGeoModule {}

package/template/apps/api/libs/infra/shared-services/ip-geo/ip-geo.service.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview IP 地理位置服务（Infra 层）
+ *
+ * 本服务提供纯 infra 层的 IP 地理位置查询功能：
+ * - IP 信息查询（via IpInfoClient）
+ * - 国家代码查询
+ * - 大洲查询（使用静态映射，不依赖数据库）
+ *
+ * 注意：此服务不依赖 domain 层，可在 infra 层安全使用。
+ * 如需完整的 IP 信息服务（含数据库查询），请使用 domain/services/ip-info。
+ *
+ * @module ip-geo/service
+ */
+import { Injectable, Inject } from '@nestjs/common';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { RedisService } from '@app/redis';
+import { FastifyRequest } from 'fastify';
+import ipUtil from '@/utils/ip.util';
+import validateUtil from '@/utils/validate.util';
+import { PardxApp } from '@/config/dto/config.dto';
+import enviromentUtil from '@/utils/enviroment.util';
+import { getContinentByCountry, Continent } from './continent-mapping';
+import { IpInfoClient, IpInfoResponse } from '@app/clients/internal/ip-info';
+
+/**
+ * IP 地理位置服务（Infra 层）
+ *
+ * @description 提供 IP 地理位置查询功能，使用静态大洲映射，不依赖数据库。
+ *
+ * @class IpGeoService
+ */
+@Injectable()
+export class IpGeoService {
+  protected ipinfoRedisKey = 'ipinfo';
+
+  constructor(
+    private readonly redis: RedisService,
+    private readonly ipInfoClient: IpInfoClient,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  /**
+   * 从请求中提取 IP 地址
+   */
+  extractIp(req: FastifyRequest): string {
+    return ipUtil.extractIp(req);
+  }
+
+  /**
+   * 获取 IP 信息
+   */
+  async getIpInfo(ip: string): Promise<Partial<PardxApp.IPInfo>> {
+    if (enviromentUtil.getBaseZone() === 'cn') {
+      return {
+        ip,
+        country: 'CN',
+        region: 'Beijing',
+        city: 'Beijing',
+        loc: '1.2897,103.8501',
+        timezone: 'Asia/Shanghai',
+      };
+    }
+
+    if (validateUtil.isBlank(ip) || ip === '127.0.0.1') {
+      return {
+        ip,
+        country: 'SG',
+        region: 'Singapore',
+        city: 'Singapore',
+        loc: '1.2897,103.8501',
+        timezone: 'Asia/Singapore',
+      };
+    }
+
+    const ipinfo = await this.redis.getData(this.ipinfoRedisKey, ip);
+    if (ipinfo) return ipinfo;
+
+    try {
+      const response: IpInfoResponse = await this.ipInfoClient.getIpInfo(ip);
+      let ipInfoData: PardxApp.IPInfo = response;
+      this.logger.info('IP info:', { ipInfoData });
+      await this.redis.saveData(this.ipinfoRedisKey, ip, ipInfoData);
+
+      if (ipInfoData.country === 'CN') {
+        ipInfoData = {
+          ip,
+          country: 'SG',
+          region: 'Singapore',
+          city: 'Singapore',
+          loc: '1.2897,103.8501',
+          timezone: 'Asia/Singapore',
+        };
+      }
+      return ipInfoData;
+    } catch (error) {
+      this.logger.error('Failed to fetch IP info:', error);
+      return {
+        ip,
+        country: 'SG',
+        region: 'Singapore',
+        city: 'Singapore',
+        loc: '1.2897,103.8501',
+        timezone: 'Asia/Singapore',
+      };
+    }
+  }
+
+  /**
+   * 获取 IP 对应的国家代码
+   */
+  async getIpCountry(ip: string): Promise<string> {
+    const ipInfo = await this.getIpInfo(ip);
+    return ipInfo.country;
+  }
+
+  /**
+   * 获取 IP 对应的大洲
+   *
+   * @description 使用静态映射，不依赖数据库
+   */
+  async getContinent(ip: string): Promise<Continent> {
+    const countryCode = await this.getIpCountry(ip);
+    const defaultZone = enviromentUtil.getBaseZone() as Continent;
+    return getContinentByCountry(countryCode, defaultZone);
+  }
+
+  /**
+   * 获取 IP 对应的时区
+   */
+  async getTimeZone(ip: string): Promise<string> {
+    const ipInfo = await this.getIpInfo(ip);
+    return ipInfo.timezone;
+  }
+}

package/template/apps/api/libs/infra/shared-services/uploader/index.ts

@@ -1,2 +1,2 @@
 export { UploaderModule } from './uploader.module';
-export { UploaderService } from './uploader.service';
+export { UploaderService, TokenRequest, SignatureData } from './uploader.service';

package/template/apps/api/libs/infra/shared-services/uploader/uploader.service.ts

@@ -16,7 +16,11 @@ import enviromentUtil from '@/utils/enviroment.util';
 import fileUtil from '@/utils/file.util';
 import { FileBucketVendor } from '@prisma/client';
 
-interface SignatureData {
+/**
+ * 签名数据接口
+ * 从加密签名中解析出的数据结构
+ */
+export interface SignatureData {
   timestamp?: number;
   filename?: string;
   fileId?: string;
@@ -25,7 +29,11 @@ interface SignatureData {
   sha256?: string;
 }
 
-interface TokenRequest {
+/**
+ * 上传令牌请求接口
+ * 用于获取上传凭证的请求参数
+ */
+export interface TokenRequest {
   signature?: string;
   filename?: string;
   vendor?: FileBucketVendor;

package/template/apps/api/src/app.module.ts

@@ -17,8 +17,6 @@ import { HttpExceptionFilter } from '@/common/filter/exception/http.exception';
 import { WinstonModule } from 'nest-winston';
 import * as loggerUtil from '@/utils/logger.util';
 
-/** health module */
-import { HealthModule } from './modules/health/health.module';
 /** uploader module */
 import { UploaderModule } from './modules/uploader/uploader.module';
 
@@ -160,16 +158,6 @@ import { DbMetricsService } from '@app/prisma/db-metrics/src/db-metrics.service'
         };
       },
     }),
-    WinstonModule.forRootAsync({
-      imports: [ConfigModule],
-      useFactory: (configService: ConfigService) => {
-        const output =
-          configService.get<loggerUtil.LogOutputMode>('app.nestLogOutput') ||
-          'file';
-        return loggerUtil.getWinstonConfig(output);
-      },
-      inject: [ConfigService],
-    }),
     IpInfoServiceModule,
     ScheduleModule.forRoot(),
     RedisModule,
@@ -181,7 +169,6 @@ import { DbMetricsService } from '@app/prisma/db-metrics/src/db-metrics.service'
     VerifyModule,
     SystemHealthModule,
     JwtModule,
-    HealthModule,
     UploaderModule,
   ],
   providers: [

package/template/apps/api/src/modules/uploader/uploader.controller.ts

@@ -73,16 +73,10 @@ export class UploaderController {
       const userId = req.userId;
       const ip = ipUtil.extractIp(req);
 
-      this.uploaderService.checkValidateAndReturnSignatureData(
-        userId,
-        body as any,
-      );
+      // 签名验证 - body 类型由 ts-rest contract 的 Zod schema 推断
+      this.uploaderService.checkValidateAndReturnSignatureData(userId, body);
 
-      const result = await this.uploaderService.uploadThumbToken(
-        userId,
-        body as any,
-        ip,
-      );
+      const result = await this.uploaderService.uploadThumbToken(userId, body, ip);
 
       return success({
         token: result.token,
@@ -100,11 +94,9 @@ export class UploaderController {
       const userId = req.userId;
       const ip = ipUtil.extractIp(req);
 
+      // 签名验证
       const signatureData =
-        this.uploaderService.checkValidateAndReturnSignatureData(
-          userId,
-          body as any,
-        );
+        this.uploaderService.checkValidateAndReturnSignatureData(userId, body);
 
       const vendor =
         body.vendor ?? (this.appConfig.defaultVendor as FileBucketVendor);
@@ -166,15 +158,10 @@ export class UploaderController {
       const userId = req.userId;
       const ip = ipUtil.extractIp(req);
 
-      this.uploaderService.checkValidateAndReturnSignatureData(
-        userId,
-        body as any,
-      );
+      // 签名验证
+      this.uploaderService.checkValidateAndReturnSignatureData(userId, body);
 
-      const result = await this.uploaderService.getUploaderPresignedUrl(
-        body as any,
-        ip,
-      );
+      const result = await this.uploaderService.getUploaderPresignedUrl(body, ip);
 
       const defaultBucket = await this.fileStorageService.getDefaultBucket();
 
@@ -193,11 +180,9 @@ export class UploaderController {
       const userId = req.userId;
       const ip = ipUtil.extractIp(req);
 
+      // 签名验证
       const signatureData =
-        this.uploaderService.checkValidateAndReturnSignatureData(
-          userId,
-          body as any,
-        );
+        this.uploaderService.checkValidateAndReturnSignatureData(userId, body);
 
       const vendor =
         body.vendor ?? (this.appConfig.defaultVendor as FileBucketVendor);

package/template/apps/web/components/index.ts

@@ -8,3 +8,24 @@ export {
   PageErrorBoundary,
   ComponentErrorBoundary,
 } from './error-boundary';
+
+export {
+  Skeleton,
+  CardSkeleton,
+  ListItemSkeleton,
+  ListSkeleton,
+  TableSkeleton,
+  FormSkeleton,
+  DetailSkeleton,
+  AvatarSkeleton,
+  PageSkeleton,
+} from './skeletons';
+
+export {
+  AsyncBoundary,
+  CardBoundary,
+  ListBoundary,
+  PageBoundary,
+  withSuspense,
+  withAsyncBoundary,
+} from './suspense-utils';