create-pardx-scaffold 0.1.2 → 0.1.3

package/package.json

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

package/template/apps/api/libs/infra/common/ts-rest/response.helper.ts

@@ -42,6 +42,14 @@ export type TsRestResponse<T, S extends number = 200> = {
   body: SuccessBody<T> | ErrorBody;
 };
 
+/**
+ * ts-rest 成功响应类型（仅包含成功体）
+ */
+export type TsRestSuccessResponse<T, S extends number = 200> = {
+  status: S;
+  body: SuccessBody<T>;
+};
+
 /**
  * 创建成功响应
  *
@@ -56,7 +64,7 @@ export type TsRestResponse<T, S extends number = 200> = {
  * }
  * ```
  */
-export function success<T>(data: T, status: 200 = 200): TsRestResponse<T, 200> {
+export function success<T>(data: T, status: 200 = 200): TsRestSuccessResponse<T, 200> {
   return {
     status,
     body: {

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

@@ -64,7 +64,7 @@ export class UploaderService {
     try {
       const jsonString = rsaDecrypt(cmd.signature);
       if (!jsonString || jsonString.trim() === '') {
-        console.error(
+        this.logger.error(
           '[Signature Validation] Decryption failed: empty result',
           {
             signature: cmd.signature?.substring(0, 50) + '...',
@@ -75,7 +75,7 @@ export class UploaderService {
       }
       signatureData = JSON.parse(jsonString);
     } catch (e) {
-      console.error('[Signature Validation] Decryption or parsing failed:', {
+      this.logger.error('[Signature Validation] Decryption or parsing failed:', {
         error: e.message || e,
         signature: cmd.signature?.substring(0, 50) + '...',
         userId,
@@ -86,7 +86,7 @@ export class UploaderService {
       ? undefined
       : signatureData.userId;
     if (userId != uploaderUserId) {
-      console.error('[Signature Validation] UserId mismatch:', {
+      this.logger.error('[Signature Validation] UserId mismatch:', {
         expectedUserId: userId,
         signatureUserId: uploaderUserId,
         signatureData,
@@ -99,7 +99,7 @@ export class UploaderService {
       enviromentUtil.isProduction() &&
       now - signatureData.timestamp > 15 * 1000
     ) {
-      console.error('[Signature Validation] Timestamp expired:', {
+      this.logger.error('[Signature Validation] Timestamp expired:', {
         now,
         signatureTimestamp: signatureData.timestamp,
         diff: now - signatureData.timestamp,

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

@@ -19,6 +19,8 @@ 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';
 
 /** i18n */
 import {
@@ -179,6 +181,8 @@ 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

@@ -0,0 +1,305 @@
+import { Controller, Req, VERSION_NEUTRAL } from '@nestjs/common';
+import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
+import { uploaderContract as c } from '@repo/contracts/api';
+import { success } from '@/common/ts-rest/response.helper';
+import { UploaderService } from '@app/shared-services/uploader';
+import { FileSourceService } from '@app/db';
+import { FileStorageService } from '@app/shared-services/file-storage';
+import { ConfigService } from '@nestjs/config';
+import { AppConfig } from '@/config/validation';
+import fileUtil from '@/utils/file.util';
+import ipUtil from '@/utils/ip.util';
+import { FileBucketVendor } from '@prisma/client';
+import { AuthenticatedRequest } from '@app/auth';
+
+/**
+ * 文件上传控制器
+ *
+ * 提供文件上传相关的 API 端点，包括：
+ * - 获取上传凭证（私有/公开/缩略图）
+ * - 分片上传初始化和凭证获取
+ * - 上传完成确认
+ * - 上传取消
+ *
+ * @version VERSION_NEUTRAL
+ *
+ * 版本控制说明：
+ * - VERSION_NEUTRAL 表示该控制器为"版本中立"
+ * - 接受任何版本的请求，或者没有版本头的请求
+ * - 客户端调用时无需提供 `x-api-version` 请求头
+ * - 适用于上传接口这类稳定、不需要版本迭代的基础设施接口
+ *
+ * 如需版本控制，可改为：
+ * @example
+ * ```typescript
+ * // 指定版本（需要 x-api-version: 1 请求头）
+ * @Controller({ version: '1' })
+ *
+ * // 支持多版本
+ * @Controller({ version: ['1', '2'] })
+ * ```
+ */
+@Controller({
+  /**
+   * VERSION_NEUTRAL: 版本中立模式
+   *
+   * 在 Header 版本控制模式下（x-api-version）：
+   * - 接受任何版本号的请求
+   * - 接受没有版本头的请求
+   * - 不会因版本不匹配而拒绝请求
+   *
+   * 适用场景：
+   * - 基础设施接口（上传、健康检查等）
+   * - 不需要版本迭代的稳定接口
+   * - 需要向后兼容的公共接口
+   */
+  version: VERSION_NEUTRAL,
+})
+export class UploaderController {
+  private appConfig: AppConfig;
+
+  constructor(
+    private readonly uploaderService: UploaderService,
+    private readonly fileSourceDb: FileSourceService,
+    private readonly fileStorageService: FileStorageService,
+    private readonly configService: ConfigService,
+  ) {
+    this.appConfig = configService.get<AppConfig>('app');
+  }
+
+  @TsRestHandler(c.getPrivateThumbToken)
+  async getPrivateThumbToken(@Req() req: AuthenticatedRequest) {
+    return tsRestHandler(c.getPrivateThumbToken, async ({ body }) => {
+      const userId = req.userId;
+      const ip = ipUtil.extractIp(req);
+
+      this.uploaderService.checkValidateAndReturnSignatureData(
+        userId,
+        body as any,
+      );
+
+      const result = await this.uploaderService.uploadThumbToken(
+        userId,
+        body as any,
+        ip,
+      );
+
+      return success({
+        token: result.token,
+        key: result.key,
+        fileId: result.key,
+        bucket: result.bucket,
+        url: `${result.domain}/${result.key}`,
+      });
+    });
+  }
+
+  @TsRestHandler(c.initMultipart)
+  async initMultipart(@Req() req: AuthenticatedRequest) {
+    return tsRestHandler(c.initMultipart, async ({ body }) => {
+      const userId = req.userId;
+      const ip = ipUtil.extractIp(req);
+
+      const signatureData =
+        this.uploaderService.checkValidateAndReturnSignatureData(
+          userId,
+          body as any,
+        );
+
+      const vendor =
+        body.vendor ?? (this.appConfig.defaultVendor as FileBucketVendor);
+      const bucket = await this.fileStorageService.getBucketString(
+        body.bucket,
+        ip,
+        false,
+        body.locale,
+        vendor,
+      );
+
+      const ext = fileUtil.getFileExtension(body.filename);
+      const key = await this.fileStorageService.formatNewKeyString(
+        'private',
+        ext,
+        bucket,
+      );
+
+      // Create file source record
+      const fileSource = await this.fileSourceDb.create({
+        key,
+        bucket,
+        vendor,
+        fsize: body.fsize,
+        mimeType: fileUtil.getMimeType(body.filename),
+        ext,
+        sha256: body.sha256 || signatureData.sha256,
+        isUploaded: false,
+      });
+
+      // Get multipart upload ID
+      const uploadId = await this.fileStorageService.getMultipartUploadId(
+        vendor,
+        bucket,
+        key,
+        ip,
+      );
+
+      // Get presigned URL for first part
+      const token = await this.fileStorageService.getPresignedUrl(
+        vendor,
+        bucket,
+        { uploadId, key, partNumber: 1 },
+      );
+
+      return success({
+        token,
+        key,
+        fileId: fileSource.id,
+        bucket,
+        url: uploadId,
+      });
+    });
+  }
+
+  @TsRestHandler(c.getMultipartToken)
+  async getMultipartToken(@Req() req: AuthenticatedRequest) {
+    return tsRestHandler(c.getMultipartToken, async ({ body }) => {
+      const userId = req.userId;
+      const ip = ipUtil.extractIp(req);
+
+      this.uploaderService.checkValidateAndReturnSignatureData(
+        userId,
+        body as any,
+      );
+
+      const result = await this.uploaderService.getUploaderPresignedUrl(
+        body as any,
+        ip,
+      );
+
+      const defaultBucket = await this.fileStorageService.getDefaultBucket();
+
+      return success({
+        token: result.token,
+        key: result.fileKey,
+        fileId: body.key || result.fileKey,
+        bucket: body.bucket || defaultBucket,
+      });
+    });
+  }
+
+  @TsRestHandler(c.getPrivateToken)
+  async getPrivateToken(@Req() req: AuthenticatedRequest) {
+    return tsRestHandler(c.getPrivateToken, async ({ body }) => {
+      const userId = req.userId;
+      const ip = ipUtil.extractIp(req);
+
+      const signatureData =
+        this.uploaderService.checkValidateAndReturnSignatureData(
+          userId,
+          body as any,
+        );
+
+      const vendor =
+        body.vendor ?? (this.appConfig.defaultVendor as FileBucketVendor);
+      const bucket = await this.fileStorageService.getBucketString(
+        body.bucket,
+        ip,
+        false,
+        body.locale,
+        vendor,
+      );
+
+      const ext = fileUtil.getFileExtension(body.filename);
+      const key = await this.fileStorageService.formatNewKeyString(
+        'private',
+        ext,
+        bucket,
+      );
+
+      // Create file source record
+      const fileSource = await this.fileSourceDb.create({
+        key,
+        bucket,
+        vendor,
+        fsize: body.fsize,
+        mimeType: fileUtil.getMimeType(body.filename),
+        ext,
+        sha256: body.sha256 || signatureData.sha256,
+        isUploaded: false,
+      });
+
+      // Get upload token with callback
+      const result = await this.uploaderService.uploadTokenWithCallback(
+        vendor,
+        bucket,
+        key,
+        ip,
+        body.locale,
+      );
+
+      const config = await this.fileStorageService.getFileServiceConfig(
+        vendor,
+        bucket,
+        ip,
+      );
+
+      return success({
+        token: result.token,
+        key: result.fileKey,
+        fileId: fileSource.id,
+        bucket,
+        url: `${config.domain}/${result.fileKey}`,
+      });
+    });
+  }
+
+  @TsRestHandler(c.abort)
+  async abort(@Req() req: AuthenticatedRequest) {
+    return tsRestHandler(c.abort, async ({ body }) => {
+      const userId = req.userId;
+
+      this.uploaderService.checkValidateAndReturnSignatureData(userId, {
+        signature: body.signature,
+      });
+
+      // Mark file as deleted
+      await this.fileSourceDb.update({ id: body.fileId }, { isDeleted: true });
+
+      return success({ success: true });
+    });
+  }
+
+  @TsRestHandler(c.complete)
+  async complete(@Req() req: AuthenticatedRequest) {
+    return tsRestHandler(c.complete, async ({ body }) => {
+      const userId = req.userId;
+
+      this.uploaderService.checkValidateAndReturnSignatureData(userId, {
+        signature: body.signature,
+      });
+
+      // Get file source and mark as uploaded
+      const fileSource = await this.fileSourceDb.update(
+        { id: body.fileId },
+        { isUploaded: true },
+      );
+
+      const config = await this.fileStorageService.getFileServiceConfig(
+        fileSource.vendor,
+        fileSource.bucket,
+      );
+
+      return success({
+        id: fileSource.id,
+        key: fileSource.key,
+        bucket: fileSource.bucket,
+        fsize: fileSource.fsize,
+        mimeType: fileSource.mimeType,
+        ext: fileSource.ext,
+        sha256: fileSource.sha256,
+        isUploaded: fileSource.isUploaded,
+        url: `${config.domain}/${fileSource.key}`,
+      });
+    });
+  }
+}

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

@@ -0,0 +1,17 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { UploaderController } from './uploader.controller';
+import { UploaderModule as UploaderServiceModule } from '@app/shared-services/uploader';
+import { FileStorageServiceModule } from '@app/shared-services/file-storage';
+import { FileSourceModule } from '@app/db';
+
+@Module({
+  imports: [
+    ConfigModule,
+    UploaderServiceModule,
+    FileStorageServiceModule,
+    FileSourceModule,
+  ],
+  controllers: [UploaderController],
+})
+export class UploaderModule {}