object-storage

对象存储多供应商 Skill（OSS / COS / S3）

让"存哪家"变成一行 env。所有 <PLACEHOLDER> 替换为项目实际值。核心是 UploadService 抽象——业务代码只调 uploadFile() / getFileUrl()，不关心底层是本地磁盘还是哪家云。

1. 供应商选型矩阵

跨区域策略：国内数据 → OSS/COS（国内节点快、合规）；海外数据 → S3（就近）。可按数据 country 路由（类比 maps-location）,或简单起见全站一家 + CDN。

2. ★ UploadService 抽象（唯一入口）

// common/services/upload.service.ts
export interface UploadResult { filePath: string; url: string; size: number; }

@Injectable()
export class UploadService {
  private readonly driver = process.env.UPLOAD_STORAGE || 'local';   // local | oss | cos | s3

  async uploadFile(file: Express.Multer.File, opts: { module: string; tenantId: string }): Promise<UploadResult> {
    const key = this.buildKey(file, opts);          // ★ 路径统一由此生成，禁止业务层拼
    switch (this.driver) {
      case 'oss': return this.putOSS(key, file);
      case 'cos': return this.putCOS(key, file);
      case 's3':  return this.putS3(key, file);
      default:    return this.putLocal(key, file);
    }
  }

  getFileUrl(filePath: string): string {
    if (process.env.CDN_DOMAIN) return `${process.env.CDN_DOMAIN}/${filePath}`;   // 有 CDN 优先
    switch (this.driver) {
      case 'oss': return `https://${process.env.OSS_BUCKET}.${process.env.OSS_REGION}.aliyuncs.com/${filePath}`;
      case 'cos': return `https://${process.env.COS_BUCKET}.cos.${process.env.COS_REGION}.myqcloud.com/${filePath}`;
      case 's3':  return `https://${process.env.S3_BUCKET}.s3.${process.env.S3_REGION}.amazonaws.com/${filePath}`;
      default:    return `/uploads/${filePath}`;
    }
  }

  private buildKey(file, opts) {
    // module/tenantId/yyyymm/uuid.ext —— 统一路径规则
    return `${opts.module}/${opts.tenantId}/${yyyymm()}/${uuid()}${extname(file.originalname)}`;
  }
}

铁律（对应 nestjs-backend-conventions §14）：

• ★ 新增上传必须走 UploadService，禁止 writeFileSync 直接写盘
• ★ 禁止在业务 Service 拼上传路径,统一 buildKey
• ★ 切换供应商只改 env,业务代码零改动