feat: 完成 SKU 图片选择及素材导入后端

2026-09-24 17:46:34 +08:00
parent d24ce8f4e0
commit e670d06ca6
26 changed files with 2287 additions and 119 deletions
@@ -0,0 +1,87 @@
+export function detectImage(
+    bytes: Buffer,
+    maxDimension = 8192,
+): {
+    contentType: 'image/png' | 'image/jpeg' | 'image/webp';
+    width: number;
+    height: number;
+} | null {
+    if (
+        bytes.length >= 24 &&
+        bytes
+            .subarray(0, 8)
+            .equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+    ) {
+        return dimensions(
+            'image/png',
+            bytes.readUInt32BE(16),
+            bytes.readUInt32BE(20),
+            maxDimension,
+        );
+    }
+    if (
+        bytes.length >= 12 &&
+        bytes.subarray(0, 4).toString() === 'RIFF' &&
+        bytes.subarray(8, 12).toString() === 'WEBP'
+    ) {
+        const type = bytes.subarray(12, 16).toString();
+        if (type === 'VP8X' && bytes.length >= 30) {
+            return dimensions(
+                'image/webp',
+                1 + bytes.readUIntLE(24, 3),
+                1 + bytes.readUIntLE(27, 3),
+                maxDimension,
+            );
+        }
+        if (
+            type === 'VP8 ' &&
+            bytes.length >= 30 &&
+            bytes[23] === 0x9d &&
+            bytes[24] === 0x01 &&
+            bytes[25] === 0x2a
+        ) {
+            return dimensions(
+                'image/webp',
+                bytes.readUInt16LE(26) & 0x3fff,
+                bytes.readUInt16LE(28) & 0x3fff,
+                maxDimension,
+            );
+        }
+    }
+    if (bytes.length > 4 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+        for (let offset = 2; offset + 9 < bytes.length;) {
+            if (bytes[offset] !== 0xff) return null;
+            const marker = bytes[offset + 1];
+            const length = bytes.readUInt16BE(offset + 2);
+            if (length < 2 || offset + 2 + length > bytes.length) return null;
+            if (
+                [
+                    0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb,
+                    0xcd, 0xce, 0xcf,
+                ].includes(marker)
+            ) {
+                return dimensions(
+                    'image/jpeg',
+                    bytes.readUInt16BE(offset + 7),
+                    bytes.readUInt16BE(offset + 5),
+                    maxDimension,
+                );
+            }
+            offset += 2 + length;
+        }
+    }
+    return null;
+}
+function dimensions(
+    contentType: 'image/png' | 'image/jpeg' | 'image/webp',
+    width: number,
+    height: number,
+    maxDimension: number,
+) {
+    return width >= 1 &&
+        height >= 1 &&
+        width <= maxDimension &&
+        height <= maxDimension
+        ? { contentType, width, height }
+        : null;
+}
@@ -3,6 +3,7 @@ import {
    Controller,
    Headers,
    Inject,
+    Get,
    Param,
    Post,
    Req,
@@ -17,6 +18,7 @@ import {
    completeMediaUploadIntentRequestSchema,
    createMediaAccessUrlRequestSchema,
    createMediaUploadIntentRequestSchema,
+    importProductImageRequestSchema,
    type Workspace,
 } from '@atlas/contracts';
 import { z } from 'zod';
@@ -33,6 +35,34 @@ export class MediaController {
        @Inject(MediaService) private readonly media: MediaService,
    ) {}

+    @Get('media-assets/product-uploads')
+    @ApiOkResponse({ description: '最近上传的商品图片及短时预览地址' })
+    public async productUploads(@CurrentWorkspace() workspace: Workspace) {
+        return { data: await this.media.productUploads(workspace.id) };
+    }
+
+    @Get('media-assets/product-imports')
+    @ApiOkResponse({ description: '最近导入的网络商品图片及短时预览地址' })
+    public async productImports(@CurrentWorkspace() workspace: Workspace) {
+        return { data: await this.media.productImports(workspace.id) };
+    }
+
+    @Post('media-assets/product-imports')
+    @ApiCreatedResponse({ description: '已下载并校验网络图片，创建正式素材' })
+    public async importProductImage(
+        @Body() body: unknown,
+        @Headers('idempotency-key') key: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        return (await this.media.importProductImage(
+            workspace.id,
+            request.auth.userId,
+            idempotencyKey(key),
+            parse(importProductImageRequestSchema, body),
+        )).body;
+    }
+
    @Post('media/upload-intents')
    @ApiCreatedResponse({ description: '已创建一次性预签名上传意图' })
    public async createIntent(
@@ -12,15 +12,19 @@ import { Inject, Injectable } from '@nestjs/common';
 import type {
    CompleteMediaUploadIntentRequest,
    CreateMediaUploadIntentRequest,
+    ImportProductImageRequest,
 } from '@atlas/contracts';
 import type { Database, DatabaseTransaction } from '@atlas/database';
 import { ApiError } from '../common/api-error.js';
 import { IdempotencyService } from '../common/idempotency.service.js';
 import { APP_CONFIG, type AppConfig } from '../config/app-config.module.js';
 import { DATABASE } from '../database/database.module.js';
+import { detectImage } from './media-image-validation.js';
+import { downloadProductImage } from './product-image-download.js';

 type IntentRow = {
    id: string;
+    purpose: 'watermark_image' | 'product_image';
    storage_provider: string;
    bucket: string;
    object_key: string;
@@ -80,16 +84,17 @@ export class MediaService {
            async (tx) => {
                await this.ensureBucket();
                const id = randomUUID();
-                const objectKey = `uploads/${workspaceId}/watermark-images/${id}`;
+                const objectKey = `uploads/${workspaceId}/${input.purpose === 'product_image' ? 'product-images' : 'watermark-images'}/${id}`;
                const expiresAt = new Date(Date.now() + 10 * 60_000);
                await tx.query(
                    `INSERT INTO atlas.media_upload_intents
                     (id, workspace_id, purpose, storage_provider, bucket, object_key, expected_content_type,
                      expected_byte_size, expected_checksum_sha256, expires_at, created_by_user_id)
-                     VALUES ($1, current_setting('app.workspace_id')::uuid, 'watermark_image', 'local_minio',
-                      $2, $3, $4, $5, $6, $7, $8)`,
+                     VALUES ($1, current_setting('app.workspace_id')::uuid, $2, 'local_minio',
+                      $3, $4, $5, $6, $7, $8, $9)`,
                    [
                        id,
+                        input.purpose,
                        this.config.OBJECT_STORAGE_BUCKET,
                        objectKey,
                        input.content_type,
@@ -282,12 +287,150 @@ export class MediaService {
        });
    }

+    /** 返回工作空间最近上传的商品素材，预览 URL 仅在本次响应中签发。 */
+    public async productUploads(workspaceId: string) {
+        return this.database.workspaceTransaction(workspaceId, async (tx) => {
+            const uploads = await tx.query<AssetRow & { bucket: string; object_key: string }>(
+                `SELECT a.id, a.content_type, a.byte_size::text, a.width_px, a.height_px,
+                        a.created_at, a.bucket, a.object_key, max(i.completed_at) AS uploaded_at
+                 FROM atlas.media_assets a
+                 JOIN atlas.media_upload_intents i ON i.asset_id = a.id
+                 WHERE i.purpose = 'product_image' AND i.status = 'ready'
+                 GROUP BY a.id
+                 ORDER BY uploaded_at DESC, a.id DESC
+                 LIMIT 100`,
+            );
+            const expiresAt = new Date(Date.now() + 10 * 60_000).toISOString();
+            return Promise.all(uploads.rows.map(async (asset) => ({
+                id: asset.id,
+                content_type: asset.content_type,
+                byte_size: Number(asset.byte_size),
+                width_px: asset.width_px,
+                height_px: asset.height_px,
+                created_at: asset.created_at instanceof Date
+                    ? asset.created_at.toISOString()
+                    : asset.created_at,
+                preview_url: await getSignedUrl(
+                    this.s3,
+                    new GetObjectCommand({ Bucket: asset.bucket, Key: asset.object_key }),
+                    { expiresIn: 600 },
+                ),
+                preview_url_expires_at: expiresAt,
+            })));
+        });
+    }
+
+    /** 网络图片先做公网下载与内容校验，再登记为工作空间正式素材。 */
+    public async importProductImage(
+        workspaceId: string,
+        userId: string,
+        key: string,
+        input: ImportProductImageRequest,
+    ) {
+        return this.idempotency.run(
+            { workspaceId, userId, method: 'POST', path: '/api/media-assets/product-imports', key, request: input },
+            async (tx) => {
+                const image = await downloadProductImage(input.url);
+                const checksum = createHash('sha256').update(image.bytes).digest('hex');
+                const existing = await tx.query<{ id: string }>(
+                    'SELECT id FROM atlas.media_assets WHERE checksum_sha256 = $1',
+                    [checksum],
+                );
+                let assetId = existing.rows[0]?.id ?? randomUUID();
+                if (!existing.rows[0]) {
+                    await this.ensureBucket();
+                    const objectKey = `product-imports/${workspaceId}/${checksum}`;
+                    await this.s3.send(new PutObjectCommand({
+                        Bucket: this.config.OBJECT_STORAGE_BUCKET,
+                        Key: objectKey,
+                        Body: image.bytes,
+                        ContentType: image.contentType,
+                    }));
+                    const inserted = await tx.query<{ id: string }>(
+                        `INSERT INTO atlas.media_assets
+                         (id, workspace_id, storage_provider, bucket, object_key, content_type,
+                          byte_size, checksum_sha256, width_px, height_px)
+                         VALUES ($1, current_setting('app.workspace_id')::uuid, 'local_minio',
+                          $2, $3, $4, $5, $6, $7, $8)
+                         ON CONFLICT (workspace_id, checksum_sha256) DO NOTHING
+                         RETURNING id`,
+                        [assetId, this.config.OBJECT_STORAGE_BUCKET, objectKey, image.contentType,
+                            image.bytes.length, checksum, image.width, image.height],
+                    );
+                    assetId = inserted.rows[0]?.id ?? (await tx.query<{ id: string }>(
+                        'SELECT id FROM atlas.media_assets WHERE checksum_sha256 = $1',
+                        [checksum],
+                    )).rows[0].id;
+                }
+                await tx.query(
+                    `INSERT INTO atlas.product_image_imports
+                     (workspace_id, source_url, asset_id, created_by_user_id)
+                     VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3)
+                     ON CONFLICT (workspace_id, source_url)
+                     DO UPDATE SET asset_id = EXCLUDED.asset_id, updated_at = now()`,
+                    [input.url, assetId, userId],
+                );
+                const asset = await this.requireAsset(tx, assetId);
+                const stored = await tx.query<{ bucket: string; object_key: string }>(
+                    'SELECT bucket, object_key FROM atlas.media_assets WHERE id = $1',
+                    [assetId],
+                );
+                const expiresAt = new Date(Date.now() + 10 * 60_000);
+                const previewUrl = await getSignedUrl(this.s3, new GetObjectCommand({
+                    Bucket: stored.rows[0].bucket,
+                    Key: stored.rows[0].object_key,
+                }), { expiresIn: 600 });
+                return {
+                    status: 201,
+                    body: { data: { ...asset, source_url: input.url,
+                        preview_url: previewUrl, preview_url_expires_at: expiresAt.toISOString() } },
+                };
+            },
+        );
+    }
+
+    public async productImports(workspaceId: string) {
+        return this.database.workspaceTransaction(workspaceId, async (tx) => {
+            const imports = await tx.query<AssetRow & {
+                bucket: string;
+                object_key: string;
+                source_url: string;
+            }>(
+                `SELECT a.id, a.content_type, a.byte_size::text, a.width_px, a.height_px,
+                        a.created_at, a.bucket, a.object_key, i.source_url
+                 FROM (
+                     SELECT DISTINCT ON (asset_id) asset_id, source_url, updated_at, id
+                     FROM atlas.product_image_imports
+                     ORDER BY asset_id, updated_at DESC, id DESC
+                 ) i
+                 JOIN atlas.media_assets a ON a.id = i.asset_id
+                 ORDER BY i.updated_at DESC, i.id DESC
+                 LIMIT 100`,
+            );
+            const expiresAt = new Date(Date.now() + 10 * 60_000).toISOString();
+            return Promise.all(imports.rows.map(async (asset) => ({
+                id: asset.id,
+                content_type: asset.content_type,
+                byte_size: Number(asset.byte_size),
+                width_px: asset.width_px,
+                height_px: asset.height_px,
+                created_at: asset.created_at instanceof Date
+                    ? asset.created_at.toISOString() : asset.created_at,
+                source_url: asset.source_url,
+                preview_url: await getSignedUrl(this.s3, new GetObjectCommand({
+                    Bucket: asset.bucket, Key: asset.object_key,
+                }), { expiresIn: 600 }),
+                preview_url_expires_at: expiresAt,
+            })));
+        });
+    }
+
    private async lockIntent(
        tx: DatabaseTransaction,
        intentId: string,
    ): Promise<IntentRow> {
        const rows = await tx.query<IntentRow>(
-            `SELECT id, storage_provider, bucket, object_key, expected_content_type, expected_byte_size,
+            `SELECT id, purpose, storage_provider, bucket, object_key, expected_content_type, expected_byte_size,
             expected_checksum_sha256, status, expires_at, asset_id
             FROM atlas.media_upload_intents WHERE id = $1 FOR UPDATE`,
            [intentId],
@@ -335,7 +478,8 @@ export class MediaService {
                '尚未找到已上传文件',
            );
        }
-        if (!head.ContentLength || head.ContentLength > 5 * 1024 * 1024) {
+        const byteLimit = intent.purpose === 'product_image' ? 20 * 1024 * 1024 : 5 * 1024 * 1024;
+        if (!head.ContentLength || head.ContentLength > byteLimit) {
            throw new ApiError(
                422,
                'UPLOAD_VALIDATION_FAILED',
@@ -370,7 +514,7 @@ export class MediaService {
        for await (const chunk of object.Body as AsyncIterable<Uint8Array>) {
            byteSize += chunk.byteLength;
            // HeadObject 和 GetObject 之间对象可能被替换；读取时也必须有硬上限。
-            if (byteSize > 5 * 1024 * 1024) {
+            if (byteSize > byteLimit) {
                throw new ApiError(
                    422,
                    'UPLOAD_VALIDATION_FAILED',
@@ -380,7 +524,7 @@ export class MediaService {
            chunks.push(Buffer.from(chunk));
        }
        const bytes = Buffer.concat(chunks, byteSize);
-        const detected = detectImage(bytes);
+        const detected = detectImage(bytes, intent.purpose === 'product_image' ? 10_000 : 8192);
        if (
            !detected ||
            detected.contentType !== intent.expected_content_type
@@ -458,80 +602,3 @@ function apiErrorCode(error: unknown): string | undefined {
        ? apiError.code
        : undefined;
 }
-
-function detectImage(bytes: Buffer): {
-    contentType: 'image/png' | 'image/jpeg' | 'image/webp';
-    width: number;
-    height: number;
-} | null {
-    if (
-        bytes.length >= 24 &&
-        bytes
-            .subarray(0, 8)
-            .equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
-    ) {
-        return dimensions(
-            'image/png',
-            bytes.readUInt32BE(16),
-            bytes.readUInt32BE(20),
-        );
-    }
-    if (
-        bytes.length >= 12 &&
-        bytes.subarray(0, 4).toString() === 'RIFF' &&
-        bytes.subarray(8, 12).toString() === 'WEBP'
-    ) {
-        const type = bytes.subarray(12, 16).toString();
-        if (type === 'VP8X' && bytes.length >= 30) {
-            return dimensions(
-                'image/webp',
-                1 + bytes.readUIntLE(24, 3),
-                1 + bytes.readUIntLE(27, 3),
-            );
-        }
-        if (
-            type === 'VP8 ' &&
-            bytes.length >= 30 &&
-            bytes[23] === 0x9d &&
-            bytes[24] === 0x01 &&
-            bytes[25] === 0x2a
-        ) {
-            return dimensions(
-                'image/webp',
-                bytes.readUInt16LE(26) & 0x3fff,
-                bytes.readUInt16LE(28) & 0x3fff,
-            );
-        }
-    }
-    if (bytes.length > 4 && bytes[0] === 0xff && bytes[1] === 0xd8) {
-        for (let offset = 2; offset + 9 < bytes.length;) {
-            if (bytes[offset] !== 0xff) return null;
-            const marker = bytes[offset + 1];
-            const length = bytes.readUInt16BE(offset + 2);
-            if (length < 2 || offset + 2 + length > bytes.length) return null;
-            if (
-                [
-                    0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb,
-                    0xcd, 0xce, 0xcf,
-                ].includes(marker)
-            ) {
-                return dimensions(
-                    'image/jpeg',
-                    bytes.readUInt16BE(offset + 7),
-                    bytes.readUInt16BE(offset + 5),
-                );
-            }
-            offset += 2 + length;
-        }
-    }
-    return null;
-}
-function dimensions(
-    contentType: 'image/png' | 'image/jpeg' | 'image/webp',
-    width: number,
-    height: number,
-) {
-    return width >= 1 && height >= 1 && width <= 8192 && height <= 8192
-        ? { contentType, width, height }
-        : null;
-}
@@ -0,0 +1,137 @@
+import { lookup } from 'node:dns/promises';
+import { request as httpsRequest } from 'node:https';
+import type { IncomingMessage } from 'node:http';
+import { isIP } from 'node:net';
+import { ApiError } from '../common/api-error.js';
+import { detectImage } from './media-image-validation.js';
+
+const MAX_BYTES = 5 * 1024 * 1024;
+
+function invalidImage(): never {
+    throw new ApiError(
+        422,
+        'PRODUCT_IMAGE_IMPORT_INVALID',
+        '网络图片链接无效或图片不符合要求',
+    );
+}
+
+export function publicIpv4(address: string) {
+    if (isIP(address) !== 4) return false;
+    const [a, b, c] = address.split('.').map(Number);
+    return !(
+        a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        a >= 224 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 &&
+            (b === 168 || (b === 0 && c === 0) || (b === 0 && c === 2))) ||
+        (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) ||
+        (a === 203 && b === 0 && c === 113)
+    );
+}
+
+/** 每次重定向重新解析域名，并将 HTTPS 连接固定到已检查的公网 IPv4。 */
+async function requestPublicImage(url: URL): Promise<IncomingMessage> {
+    if (
+        url.protocol !== 'https:' ||
+        url.username ||
+        url.password ||
+        url.port ||
+        isIP(url.hostname)
+    )
+        invalidImage();
+    const addresses = await lookup(url.hostname, {
+        all: true,
+        family: 4,
+    }).catch(() => []);
+    if (
+        !addresses.length ||
+        addresses.some((item) => !publicIpv4(item.address))
+    )
+        invalidImage();
+    const address = addresses[0].address;
+    return new Promise<IncomingMessage>((resolve, reject) => {
+        const request = httpsRequest(
+            url,
+            {
+                lookup: (_hostname, _options, callback) =>
+                    callback(null, address, 4),
+                headers: {
+                    Accept: 'image/jpeg,image/png',
+                    'User-Agent': 'Atlas-Image-Importer/0.1',
+                },
+                timeout: 15_000,
+            },
+            resolve,
+        );
+        request.on('error', reject);
+        request.on('timeout', () =>
+            request.destroy(new Error('网络图片下载超时')),
+        );
+        request.end();
+    });
+}
+
+/** 仅导入公开 HTTPS 的 JPG/PNG，硬限制 5 MiB 并验证文件内容。 */
+export async function downloadProductImage(source: string) {
+    let url = new URL(source);
+    for (let redirect = 0; redirect < 4; redirect += 1) {
+        let response: IncomingMessage;
+        try {
+            response = await requestPublicImage(url);
+        } catch (error) {
+            if (error instanceof ApiError) throw error;
+            invalidImage();
+        }
+        if ([301, 302, 303, 307, 308].includes(response.statusCode ?? 0)) {
+            const location = response.headers.location;
+            response.resume();
+            if (!location) invalidImage();
+            url = new URL(location, url);
+            continue;
+        }
+        if (
+            response.statusCode !== 200 ||
+            Number(response.headers['content-length'] ?? 0) > MAX_BYTES
+        ) {
+            response.resume();
+            invalidImage();
+        }
+        const chunks: Buffer[] = [];
+        let total = 0;
+        try {
+            for await (const chunk of response) {
+                total += chunk.length;
+                if (total > MAX_BYTES) {
+                    response.destroy();
+                    invalidImage();
+                }
+                chunks.push(Buffer.from(chunk));
+            }
+        } catch (error) {
+            if (error instanceof ApiError) throw error;
+            invalidImage();
+        }
+        const bytes = Buffer.concat(chunks, total);
+        const detected = detectImage(bytes, 10_000);
+        if (
+            !detected ||
+            !['image/jpeg', 'image/png'].includes(detected.contentType)
+        )
+            invalidImage();
+        const declared = response.headers['content-type']
+            ?.split(';', 1)[0]
+            ?.toLowerCase();
+        if (declared && declared !== detected.contentType) invalidImage();
+        return {
+            bytes,
+            contentType: detected.contentType,
+            width: detected.width,
+            height: detected.height,
+        };
+    }
+    invalidImage();
+}