create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/redis/redis.service.ts

@@ -6,10 +6,16 @@ import Redis from 'ioredis'
 export class RedisService {
   constructor(@InjectRedis() private readonly redis: Redis) {}
 
+  /**
+   * 执行 Redis PING，验证当前连接可用。
+   */
   async ping() {
     return this.redis.ping()
   }
 
+  /**
+   * 写入字符串键值，可按秒设置正数有效期；未提供有效 TTL 时永久保存。
+   */
   async set(key: string, value: string, ttlSeconds?: number) {
     if (ttlSeconds && ttlSeconds > 0) {
       await this.redis.set(key, value, 'EX', ttlSeconds)
@@ -19,18 +25,30 @@ export class RedisService {
     return 'Ok'
   }
 
+  /**
+   * 读取字符串键的值，键不存在时返回 null。
+   */
   async get(key: string) {
     return this.redis.get(key)
   }
 
+  /**
+   * 删除指定 Redis 键并返回实际删除数量。
+   */
   async del(key: string) {
     return this.redis.del(key)
   }
 
+  /**
+   * 检查指定 Redis 键是否存在并返回布尔结果。
+   */
   async exist(key: string) {
     return (await this.redis.exists(key)) === 1
   }
 
+  /**
+   * 按 Redis 通配模式列出匹配键，供开发联调检查数据使用。
+   */
   async keys(pattern: string) {
     return this.redis.keys(pattern)
   }

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/dto/upload-params.dto.ts

@@ -10,6 +10,6 @@ export const uploadPartParamsSchema = uploadSessionParamsSchema.extend({
   partNumber: z.coerce.number().int().min(1).max(UPLOAD_MAX_PARTS),
 })
 
-export class UploadSessionParamsDto extends createZodDto(uploadPartParamsSchema) {}
+export class UploadSessionParamsDto extends createZodDto(uploadSessionParamsSchema) {}
 
 export class UploadPartParamsDto extends createZodDto(uploadPartParamsSchema) {}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/storage/exact-size.transform.ts

@@ -2,6 +2,9 @@ import { TransformCallback } from 'node:stream'
 import { Transform } from 'stream'
 
 export class ExactSizeError extends Error {
+  /**
+   * 记录期望与实际字节数，使上层能够识别上传内容长度不匹配。
+   */
   constructor(
     readonly expectedBytes: number,
     readonly receivedBytes: number,
@@ -14,10 +17,16 @@ export class ExactSizeError extends Error {
 export class ExactSizeTransform extends Transform {
   receivedBytes = 0
 
+  /**
+   * 记录流所要求的精确字节数，用于后续长度验证。
+   */
   constructor(private readonly expectedBytes: number) {
     super()
   }
 
+  /**
+   * 累计并透传数据块；一旦实际字节数超过期望值，立即通过回调使流失败。
+   */
   override _transform(chunk: any, encoding: BufferEncoding, callback: TransformCallback): void {
     const byteLength = Buffer.isBuffer(chunk)
       ? chunk.length
@@ -33,9 +42,8 @@ export class ExactSizeTransform extends Transform {
   }
 
   /**
-   * 出场质检
-   * @param callback
-   * @returns
+   * 在输入流结束时核对总字节数，发现不足或不一致时通过回调报告长度错误。
+   * @param callback 通知流框架完成刷新，或传递长度校验异常。
    */
   override _flush(callback: TransformCallback): void {
     if (this.receivedBytes !== this.expectedBytes) {
@@ -47,6 +55,9 @@ export class ExactSizeTransform extends Transform {
   }
 }
 
+/**
+ * 沿最多八层 cause 链查找长度校验异常，未找到时返回 null。
+ */
 export function findExactSizeError(cause: unknown): ExactSizeError | null {
   let current = cause
 

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/storage/minio-storage.adapter.ts

@@ -20,6 +20,9 @@ import {
   UploadPartInput,
 } from './storage.port'
 
+/**
+ * 兼容 AWS SDK 的 name 与 S3 响应的 Code 字段，判断存储错误类别。
+ */
 function hasErrorName(cause: unknown, expected: string): boolean {
   if (typeof cause !== 'object' || cause === null) {
     return false
@@ -28,6 +31,9 @@ function hasErrorName(cause: unknown, expected: string): boolean {
   return record.name === expected || record.Code === expected
 }
 
+/**
+ * 将 NoSuchUpload 转换为存储端口约定的异常，其余错误保留原始原因并抛出。
+ */
 function throwMappedMultipartError(cause: unknown): never {
   if (hasErrorName(cause, 'NoSuchUpload')) {
     throw new StorageMultipartNotFoundError(cause)
@@ -41,6 +47,9 @@ export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
   private readonly client: S3Client
   private readonly bucket: string
 
+  /**
+   * 根据存储配置创建 S3 客户端，并禁用不可回放上传流的自动重试。
+   */
   constructor(config: ConfigService) {
     this.bucket = config.getOrThrow<string>('storage.bucket')
     this.client = new S3Client({
@@ -58,6 +67,9 @@ export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
     })
   }
 
+  /**
+   * 通过 HeadBucket 验证目标桶存在且可访问，失败交由调用方处理。
+   */
   private async assertBucketAvailable(): Promise<void> {
     await this.client.send(
       new HeadBucketCommand({
@@ -66,14 +78,24 @@ export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
     )
   }
 
+  /**
+   * 在模块销毁时释放 S3 客户端的网络资源。
+   */
   onModuleDestroy() {
     this.client.destroy()
   }
 
+  /**
+   * 在模块初始化时探测上传桶，及早暴露配置或存储访问异常。
+   */
   async onModuleInit() {
     await this.assertBucketAvailable()
   }
 
+  /**
+   * 向对象存储创建分片上传，写入内容类型和元数据并返回 UploadId。
+   * @throws 存储未返回 UploadId 时抛出错误。
+   */
   async createMultipartUpload(input: CreateMultipartInput) {
     const response = await this.client.send(
       new CreateMultipartUploadCommand({
@@ -93,6 +115,9 @@ export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
     }
   }
 
+  /**
+   * 流式上传指定分片并传递取消信号，返回后续合并所需的 ETag。
+   */
   async uploadPart(input: UploadPartInput) {
     try {
       const response = await this.client.send(
@@ -121,6 +146,9 @@ export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
     }
   }
 
+  /**
+   * 逐页读取全部已上传分片，校验记录与游标有效性，并按分片序号升序返回。
+   */
   async listParts(input: MultipartIdentity): Promise<StoragePart[]> {
     const parts: StoragePart[] = []
     let partNumberMarker: string | undefined
@@ -164,6 +192,9 @@ export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
     return parts.sort((left, right) => left.partNumber - right.partNumber)
   }
 
+  /**
+   * 提交分片序号和 ETag 列表完成对象合并，返回存储对象的 ETag。
+   */
   async completeMultipartUpload(input: MultipartIdentity & { parts: readonly StoragePart[] }) {
     try {
       const response = await this.client.send(
@@ -187,6 +218,9 @@ export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
     }
   }
 
+  /**
+   * 取消对象存储中的分片上传；UploadId 已不存在时视为成功，保持取消操作幂等。
+   */
   async abortMultipartUpload(input: MultipartIdentity): Promise<void> {
     try {
       await this.client.send(
@@ -204,6 +238,9 @@ export class MinioStorageAdapter implements StoragePort, OnModuleDestroy {
     }
   }
 
+  /**
+   * 读取对象大小、ETag 及元数据；确认仅对象缺失时返回 null，桶不可用时仍抛出错误。
+   */
   async headObject(input: { bucket: string; objectKey: string }): Promise<StorageObject | null> {
     try {
       const response = await this.client.send(

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/storage/storage.port.ts

@@ -3,6 +3,9 @@ import { Readable } from 'stream'
 export const STORAGE_PORT = Symbol('STORAGE_PORT')
 
 export class StorageMultipartNotFoundError extends Error {
+  /**
+   * 封装存储分片上传不存在的错误，并保留原始原因供上层映射和排查。
+   */
   constructor(cause: unknown) {
     super('Multipart upload does not exist', { cause })
     this.name = StorageMultipartNotFoundError.name
@@ -45,17 +48,35 @@ export interface StorageObject {
 }
 
 export interface StoragePort {
+  /**
+   * 在指定桶创建分片上传并返回后续请求使用的存储 UploadId。
+   */
   createMultipartUpload(input: CreateMultipartInput): Promise<{ storageUploadId: string }>
 
+  /**
+   * 写入指定序号的分片流，支持取消信号，并返回合并所需的 ETag。
+   */
   uploadPart(input: UploadPartInput): Promise<{ etag: string }>
 
+  /**
+   * 返回按序号排列的全部已上传分片，供续传和完整性校验使用。
+   */
   listParts(input: MultipartIdentity): Promise<StoragePart[]>
 
+  /**
+   * 按已校验的分片列表合并对象，返回对象 ETag。
+   */
   completeMultipartUpload(
     input: MultipartIdentity & { parts: readonly StoragePart[] },
   ): Promise<{ etag: string | null }>
 
+  /**
+   * 清理指定上传的未合并分片，重复取消应保持幂等。
+   */
   abortMultipartUpload(input: MultipartIdentity): Promise<void>
 
+  /**
+   * 读取对象的长度、ETag 和元数据；对象不存在时返回 null。
+   */
   headObject(input: { bucket: string; objectKey: string }): Promise<StorageObject | null>
 }

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/upload.constants.ts

@@ -2,10 +2,19 @@ export const UPLOAD_PART_SIZE = 10 * 1024 * 1024
 export const UPLOAD_MAX_PARTS = 10_000
 export const UPLOAD_MAX_FILE_SIZE = 90 * 1024 * 1024 * 1024
 
+/**
+ * 按固定分片大小向上取整，计算文件上传所需分片数。
+ * @param fileSize 文件字节数。
+ */
 export function calculateTotalParts(fileSize: number): number {
   return Math.ceil(fileSize / UPLOAD_PART_SIZE)
 }
 
+/**
+ * 计算指定分片应有的字节数，最后一片使用文件剩余长度。
+ * @param partNumber 从 1 开始的分片序号。
+ * @throws 分片序号超出上传范围时抛出 RangeError。
+ */
 export function calculateExpectedPartSize(
   fileSize: number,
   totalParts: number,

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/upload.controller.ts

@@ -1,4 +1,5 @@
 import { CurrentAuth } from '@/common/decorators/current-auth.decorator'
+import { Authenticated } from '@/common/decorators/access-policy.decorator'
 import {
   Body,
   Controller,
@@ -28,21 +29,32 @@ type OctetStreamRequest = FastifyRequest & {
 @ApiTags('大文件分片上传')
 @ApiBearerAuth('session')
 @Controller('uploads/multipart')
+@Authenticated()
 export class UploadController {
   constructor(private readonly uploadService: UploadService) {}
 
+  /**
+   * 为当前认证用户初始化分片上传，客户端上传标识用于幂等复用。
+   */
   @ApiOperation({ summary: '初始化大文件分片上传' })
   @Post()
   initiate(@CurrentAuth() auth: CurrentAuthType, @Body() body: InitiateMultipartUploadDto) {
     return this.uploadService.initiate(auth.userId, body)
   }
 
+  /**
+   * 查询当前用户上传会话的状态及已上传分片。
+   */
   @ApiOperation({ summary: '查询上传状态和已上传分片' })
   @Get(':uploadSessionId')
   getStatus(@CurrentAuth() auth: CurrentAuthType, @Param() params: UploadSessionParamsDto) {
     return this.uploadService.getStatus(auth.userId, params.uploadSessionId)
   }
 
+  /**
+   * 将原始二进制请求流交给分片服务，并在连接中断时取消存储请求。
+   * @remarks 请求结束后排空未消费字节并移除监听器，避免连接和事件处理器泄漏。
+   */
   @ApiOperation({ summary: '上传一个原始二进制分片' })
   @ApiConsumes('application/octet-stream')
   @ApiBody({
@@ -62,7 +74,13 @@ export class UploadController {
     @Res({ passthrough: true }) reply: FastifyReply,
   ) {
     const abortController = new AbortController()
+    /**
+     * 在客户端中止请求时触发存储上传的取消信号。
+     */
     const onAborted = () => abortController.abort()
+    /**
+     * 响应尚未正常结束而连接已关闭时，取消正在进行的存储上传。
+     */
     const onReplyClose = () => {
       if (!reply.raw.writableEnded) {
         abortController.abort()
@@ -82,6 +100,7 @@ export class UploadController {
         body: request.body,
         abortSignal: abortController.signal,
       })
+      /** 无论前置校验还是存储操作成功与否，均排空请求流并释放连接监听器。 */
       .finally(() => {
         // 前置校验失败时 Service 可能尚未 pipe 请求体。
         // 统一排空剩余字节，避免连接一直占用到代理超时；这里不会聚合 Buffer。
@@ -94,6 +113,9 @@ export class UploadController {
       })
   }
 
+  /**
+   * 以当前用户身份请求校验并完成指定分片上传。
+   */
   @ApiOperation({ summary: '校验并完成分片上传' })
   @HttpCode(HttpStatus.OK)
   @Post(':uploadSessionId/complete')
@@ -101,6 +123,9 @@ export class UploadController {
     return this.uploadService.complete(auth.userId, params.uploadSessionId)
   }
 
+  /**
+   * 以当前用户身份取消指定上传会话并清理存储分片。
+   */
   @ApiOperation({ summary: '取消分片上传' })
   @Delete(':uploadSessionId')
   abort(@CurrentAuth() auth: CurrentAuthType, @Param() params: UploadSessionParamsDto) {

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/upload.reponsitory.ts

@@ -10,6 +10,9 @@ export type CreateUploadSession = typeof uploadSessions.$inferInsert
 export class UploadRepository {
   constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
 
+  /**
+   * 插入上传会话，用户与客户端上传标识冲突时返回 null，供上层处理并发初始化。
+   */
   async create(input: CreateUploadSession): Promise<UploadSession | null> {
     const [session] = await this.db
       .insert(uploadSessions)
@@ -22,6 +25,9 @@ export class UploadRepository {
     return session ?? null
   }
 
+  /**
+   * 按会话 ID 和所属用户查询上传记录，不存在或不属于当前用户时返回 null。
+   */
   async findById(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
     const [session] = await this.db
       .select()
@@ -31,6 +37,9 @@ export class UploadRepository {
     return session ?? null
   }
 
+  /**
+   * 查找用户已创建的客户端上传标识，支持重复初始化和断点续传。
+   */
   async findByClientUploadId(
     ownerId: string,
     clientUploadId: string,
@@ -46,6 +55,9 @@ export class UploadRepository {
     return session ?? null
   }
 
+  /**
+   * 仅将 uploading 会话原子更新为 completing，返回成功抢占的记录；状态不符时返回 null。
+   */
   async claimCompleting(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
     const [session] = await this.db
       .update(uploadSessions)
@@ -65,6 +77,9 @@ export class UploadRepository {
     return session ?? null
   }
 
+  /**
+   * 仅将 completing 会话标记为 completed，并保存对象 ETag 和完成时间。
+   */
   async markCompleted(
     ownerId: string,
     uploadSessionId: string,
@@ -91,6 +106,9 @@ export class UploadRepository {
     return session ?? null
   }
 
+  /**
+   * 将上传中、取消中或过期会话设为 aborting，允许重试取消但不会抢占完成流程。
+   */
   async claimAborting(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
     const [session] = await this.db
       .update(uploadSessions)
@@ -110,6 +128,9 @@ export class UploadRepository {
     return session ?? null
   }
 
+  /**
+   * 仅将 aborting 会话更新为 aborted，状态已变化时返回 null。
+   */
   async markAborted(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
     const [session] = await this.db
       .update(uploadSessions)
@@ -129,6 +150,9 @@ export class UploadRepository {
     return session ?? null
   }
 
+  /**
+   * 仅将仍在 uploading 的会话标记为 expired，返回需要清理存储分片的记录。
+   */
   async markExpired(ownerId: string, uploadSessionId: string): Promise<UploadSession | null> {
     const [session] = await this.db
       .update(uploadSessions)
@@ -148,6 +172,9 @@ export class UploadRepository {
     return session ?? null
   }
 
+  /**
+   * 在尚未发送存储合并请求时，将 completing 会话恢复为 uploading 以允许修正分片后重试。
+   */
   async resetCompleting(ownerId: string, uploadSessionId: string): Promise<void> {
     await this.db
       .update(uploadSessions)

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/upload.service.ts

@@ -64,6 +64,9 @@ export class UploadService {
   private readonly bucket: string
   private readonly sessionTtlMs: number
 
+  /**
+   * 读取上传目标桶及会话有效期，并注入上传记录与对象存储依赖。
+   */
   constructor(
     private readonly uploadRepository: UploadRepository,
     @Inject(STORAGE_PORT) private readonly storage: StoragePort,
@@ -73,6 +76,12 @@ export class UploadService {
     this.sessionTtlMs = config.getOrThrow<number>('storage.sessionTtlMs')
   }
 
+  /**
+   * 幂等创建分片上传会话与存储 UploadId；并发请求复用已创建会话，多余存储上传会被补偿取消。
+   * @param ownerId 上传所属用户 ID。
+   * @param input 文件元数据及客户端生成的上传标识。
+   * @returns 上传会话状态及已有分片信息。
+   */
   async initiate(ownerId: string, input: InitiateMultipartUploadDto) {
     this.validateNewFile(input.fileSize)
 
@@ -146,6 +155,10 @@ export class UploadService {
     }
   }
 
+  /**
+   * 拒绝空文件及超过上传大小上限的文件。
+   * @param fileSize 文件字节数。
+   */
   private validateNewFile(fileSize: number) {
     if (fileSize === 0) {
       throw new AppException(UPLOAD_ERRORS.FILE_EMPTY)
@@ -156,6 +169,9 @@ export class UploadService {
     }
   }
 
+  /**
+   * 检查同一客户端上传标识对应的名称、大小及内容类型一致，防止误复用其他文件会话。
+   */
   private assertSameClientFile(session: UploadSession, input: InitiateMultipartUploadDto): void {
     if (
       session.originalName !== input.fileName.trim() ||
@@ -166,6 +182,10 @@ export class UploadService {
     }
   }
 
+  /**
+   * 按用户归属读取上传会话，避免跨用户访问。
+   * @throws 当前用户下找不到会话时抛出会话不存在错误。
+   */
   private async requireSession(ownerId: string, uploadSessionId: string): Promise<UploadSession> {
     const session = await this.uploadRepository.findById(ownerId, uploadSessionId)
 
@@ -176,6 +196,9 @@ export class UploadService {
     return session
   }
 
+  /**
+   * 尽力取消多余或过期的存储分片上传，失败只记录警告，保留主流程的原始结果。
+   */
   private async safeAbort(identity: MultipartIdentity): Promise<void> {
     try {
       await this.storage.abortMultipartUpload(identity)
@@ -184,6 +207,9 @@ export class UploadService {
       this.logger.warn(`Compensating AbortMultipartUpload failed: ${message}`)
     }
   }
+  /**
+   * 从数据库上传会话提取对象存储定位所需的桶、对象键和 UploadId。
+   */
   private toMultipartIdentity(session: UploadSession): MultipartIdentity {
     return {
       bucket: session.bucket,
@@ -192,6 +218,10 @@ export class UploadService {
     }
   }
 
+  /**
+   * 检查上传期限；到期时标记会话过期并尽力清理存储分片。
+   * @throws 会话已到期时抛出上传过期错误。
+   */
   private async ensureNotExpired(session: UploadSession): Promise<void> {
     if (session.expiresAt.getTime() > Date.now()) {
       return
@@ -206,6 +236,9 @@ export class UploadService {
     throw new AppException(UPLOAD_ERRORS.UPLOAD_EXPIRED)
   }
 
+  /**
+   * 沿最多八层 cause 链识别请求取消错误，兼容 SDK 对 AbortError 的包装。
+   */
   private isAbortError(cause: unknown): boolean {
     let current = cause
 
@@ -229,6 +262,9 @@ export class UploadService {
     return false
   }
 
+  /**
+   * 在对象存储调用边界区分分片长度错误、上传丢失和取消，将其他失败转换为存储不可用。
+   */
   private async callStorage<T>(operation: () => Promise<T>): Promise<T> {
     try {
       return await operation()
@@ -253,6 +289,10 @@ export class UploadService {
     }
   }
 
+  /**
+   * 探测已合并对象并核对会话元数据与大小，恢复未成功落库的完成状态。
+   * @returns 恢复或已完成的上传记录，无法确认对象完成时返回 null。
+   */
   private async recoverCompletedObject(session: UploadSession): Promise<UploadSession | null> {
     const object = await this.callStorage(() =>
       this.storage.headObject({
@@ -284,6 +324,9 @@ export class UploadService {
     return latest?.status === 'completed' ? latest : null
   }
 
+  /**
+   * 将数据库会话及存储分片转换为客户端状态，日期统一输出为 ISO 字符串。
+   */
   private toStatusResponse(
     session: UploadSession,
     parts: readonly StoragePart[],
@@ -305,6 +348,9 @@ export class UploadService {
     }
   }
 
+  /**
+   * 读取上传状态和已上传分片，同时处理过期会话并尝试恢复正在完成的上传。
+   */
   async getStatus(ownerId: string, uploadSessionId: string): Promise<UploadStatusResponse> {
     let session = await this.requireSession(ownerId, uploadSessionId)
 
@@ -334,6 +380,10 @@ export class UploadService {
     return this.toStatusResponse(session, parts)
   }
 
+  /**
+   * 按客户端上传标识幂等创建分片会话，写库失败或并发冲突时补偿取消新建存储上传。
+   * @returns 可恢复上传的会话状态及已有分片信息。
+   */
   async initate(ownerId: string, input: InitiateMultipartUploadDto): Promise<UploadStatusResponse> {
     this.validateNewFile(input.fileSize)
 
@@ -408,6 +458,10 @@ export class UploadService {
     }
   }
 
+  /**
+   * 将 Content-Length 转换为正安全整数。
+   * @throws 请求头缺失或无法表示有效分片长度时抛出长度必填错误。
+   */
   private parseContentLength(value: string | undefined): number {
     if (!value) {
       throw new AppException(UPLOAD_ERRORS.PART_LENGTH_REQUIRED)
@@ -421,6 +475,12 @@ export class UploadService {
     return parsed
   }
 
+  /**
+   * 校验会话归属、状态、分片序号和字节数后，将受长度约束的请求流写入对象存储。
+   * @param input 包含请求体、声明长度和取消信号的分片上传命令。
+   * @returns 上传分片的序号、字节数和 ETag。
+   * @remarks 失败或结束时解除管道及监听器，必要时排空剩余请求字节。
+   */
   async uploadPart(input: UploadPartCommandInput) {
     const session = await this.requireSession(input.ownerId, input.uploadSessionId)
 
@@ -451,6 +511,9 @@ export class UploadService {
     }
 
     const exactSizeStream = new ExactSizeTransform(expectedSize)
+    /**
+     * 将请求体错误传递给长度校验流，使下游存储上传及时失败。
+     */
     const onSourceError = (cause: Error) => exactSizeStream.destroy(cause)
     input.body.once('error', onSourceError)
 
@@ -489,6 +552,9 @@ export class UploadService {
     }
   }
 
+  /**
+   * 从已完成的上传记录生成客户端所需的对象键与 ETag。
+   */
   private toCompletedResponse(session: UploadSession): CompletedUploadResponse {
     return {
       uploadSessionId: session.id,
@@ -498,6 +564,10 @@ export class UploadService {
     }
   }
 
+  /**
+   * 检查分片数量、连续序号、ETag 和每片长度，确保总字节数与原文件完全一致。
+   * @throws 分片缺失或大小不匹配时抛出分片不完整错误。
+   */
   private assertCompleteParts(session: UploadSession, parts: readonly StoragePart[]): void {
     if (parts.length !== session.totalParts) {
       throw new AppException(UPLOAD_ERRORS.PARTS_INCOMPLETE)
@@ -531,6 +601,10 @@ export class UploadService {
     }
   }
 
+  /**
+   * 抢占完成状态后校验并合并分片，再持久化对象信息；重复调用可复用完成结果。
+   * @remarks 合并尚未发出时可回退上传状态；发出后无法确认结果时保留 completing 并尝试对象探测恢复。
+   */
   async complete(ownerId: string, uploadSessionId: string): Promise<CompletedUploadResponse> {
     let session = await this.requireSession(ownerId, uploadSessionId)
 
@@ -646,6 +720,10 @@ export class UploadService {
     }
   }
 
+  /**
+   * 抢占取消状态、清理存储分片并记录取消结果；已取消会话可重复调用。
+   * @throws 已完成或正在完成的会话不允许取消。
+   */
   async abort(ownerId: string, uploadSessionId: string) {
     let session = await this.requireSession(ownerId, uploadSessionId)
     if (session.status === 'aborted') {

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/upload/utils/object-key.ts

@@ -1,3 +1,7 @@
+/**
+ * 按用户、UTC 年月和上传会话 ID 生成对象键，不使用客户端文件名。
+ * @param now 用于目录分区的时间，默认当前时间。
+ */
 export function buildUploadObjectKey(
   ownerId: string,
   uploadSessionId: string,

package/template-vp-monorepo-react-nestjs/apps/server/src/utils/server-address.ts

@@ -6,10 +6,16 @@ const color = {
   bold: (text: string) => `\x1b[1m${text}\x1b[0m`,
 }
 
+/**
+ * 为地址添加 OSC 8 超链接和颜色，使支持该协议的终端可以直接打开链接。
+ */
 function terminalLink(url: string) {
   return `\x1b]8;;${url}\x1b\\${color.cyan(url)}\x1b]8;;\x1b\\`
 }
 
+/**
+ * 枚举本机非回环 IPv4 网卡，生成给定服务端口的局域网访问地址。
+ */
 export function getNetworkUrls(port: number) {
   return Object.values(networkInterfaces())
     .flatMap((items) => items ?? [])