feat(collection): 采集箱开发

仅 align-items 不生效（block 布局），补 display: inline-flex，
面包屑每一层（nav/ol/li/link/crumb）均为 flex 垂直居中。

.env.example

@@ -0,0 +1,85 @@
+# Local PostgreSQL bootstrap administrator. It creates roles but must never be used by API or Worker.
+POSTGRES_ADMIN_USER=atlas_admin
+POSTGRES_ADMIN_PASSWORD=change-me-local-only
+# Database name and host port exposed by local Docker Compose.
+POSTGRES_DB=atlas
+POSTGRES_PORT=5432
+
+# Password for the schema-owning migrator role; only the migration runner may use it.
+ATLAS_MIGRATOR_PASSWORD=change-me-local-only
+# Password for the least-privileged API/Worker login role.
+ATLAS_APP_PASSWORD=change-me-local-only
+# API/Worker application connection. This role has no table ownership and is constrained by RLS.
+DATABASE_URL=postgresql://atlas_app_login:change-me-local-only@localhost:5432/atlas
+# Migration-only connection. Do not put this value in production API or Worker environments.
+MIGRATOR_DATABASE_URL=postgresql://atlas_migrator:change-me-local-only@localhost:5432/atlas
+
+# Runtime mode controls production-only safeguards such as Secure cookies.
+NODE_ENV=development
+# Browser origin allowed to send credentialed requests to this API.
+WEB_ORIGIN=http://localhost:8100
+# HTTP listener port for the NestJS API.
+API_PORT=8200
+
+# HMAC signing secret for short-lived access JWTs; replace with a unique 32+ character secret.
+AUTH_JWT_SECRET=replace-with-a-random-secret-of-at-least-32-characters
+# Separate HMAC secret used to pseudonymize IP/email values in Redis rate-limit keys.
+AUTH_RATE_LIMIT_KEY_SECRET=replace-with-a-different-random-secret-of-at-least-32-characters
+# AES-GCM 密钥材料，用来加密门店 API Key；只保存在服务端，轮换时变更版本号但保留旧密钥解密能力。
+STORE_SECRET_ENCRYPTION_KEY=replace-with-a-random-secret-of-at-least-32-characters
+# 当前门店密钥使用的加密密钥版本，会随密钥轮换递增。
+STORE_SECRET_ENCRYPTION_KEY_VERSION=v1
+# 对幂等请求内容生成 HMAC 摘要的独立密钥，避免数据库保存原始请求体或 API Key。
+IDEMPOTENCY_KEY_SECRET=replace-with-a-different-random-secret-of-at-least-32-characters
+# Server-side minimum password length. The browser must not weaken this rule.
+AUTH_PASSWORD_MIN_LENGTH=12
+# Maximum JSON or URL-encoded request size in bytes. Media files must use object-storage direct upload.
+API_BODY_LIMIT_BYTES=1048576
+# Shared fixed-window duration for authentication rate limits, in seconds.
+AUTH_RATE_LIMIT_WINDOW_SECONDS=900
+# Maximum login attempts per IP inside the window.
+AUTH_LOGIN_IP_LIMIT=10
+# Maximum login attempts per normalized email inside the window.
+AUTH_LOGIN_EMAIL_LIMIT=5
+# Maximum registration attempts per IP inside the window.
+AUTH_REGISTER_IP_LIMIT=5
+# Maximum registration attempts per normalized email inside the window.
+AUTH_REGISTER_EMAIL_LIMIT=3
+# Maximum refresh attempts per IP inside the window; refresh tokens have no trusted email before validation.
+AUTH_REFRESH_IP_LIMIT=30
+# 密码修改在同一限流窗口内允许的每 IP 最大次数。
+AUTH_CHANGE_PASSWORD_IP_LIMIT=10
+# 密码修改在同一限流窗口内允许的每已认证用户最大次数。
+AUTH_CHANGE_PASSWORD_USER_LIMIT=5
+
+# Comma-separated trusted reverse-proxy IPs/CIDRs. Keep empty for direct local access; never set to true.
+TRUSTED_PROXY_CIDRS=
+# Whether to expose Swagger UI at /api-docs.
+SWAGGER_ENABLED=true
+# Minimum structured-log severity: error, warn, log, or debug.
+LOG_LEVEL=log
+
+# Redis endpoint used by BullMQ and shared authentication rate limits.
+REDIS_URL=redis://localhost:6379
+
+# S3-compatible object storage. Local development falls back to MinIO root credentials above;
+# production must set dedicated, least-privileged OBJECT_STORAGE_ACCESS_KEY / SECRET_KEY values.
+OBJECT_STORAGE_ENDPOINT=http://localhost:9000
+OBJECT_STORAGE_BUCKET=atlas-assets
+OBJECT_STORAGE_FORCE_PATH_STYLE=true
+# OBJECT_STORAGE_ACCESS_KEY=
+# OBJECT_STORAGE_SECRET_KEY=
+
+# Local MinIO root account; it is only for Docker bootstrap, not browser credentials.
+MINIO_ROOT_USER=atlas_minio_local
+# Local MinIO root password; replace outside disposable local development.
+MINIO_ROOT_PASSWORD=change-me-local-only
+# S3-compatible API port for local MinIO.
+MINIO_PORT=9000
+# MinIO administrative console port.
+MINIO_CONSOLE_PORT=9001
+
+# Local Vite frontend port.
+WEB_PORT=8100
+# Local WXT browser-extension development port.
+EXTENSION_PORT=8110

.gitignore

@@ -11,7 +11,19 @@
 # Common future runtime/build artifacts
 node_modules/
 dist/
+.output/
 .venv/
 __pycache__/
 *.py[cod]
 *.log
+node_modules/
+.pnpm-store/
+.turbo/
+dist/
+coverage/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+data/

.nvmrc

@@ -0,0 +1 @@
+24.20.0

.prettierignore

@@ -0,0 +1,7 @@
+node_modules/
+.turbo/
+dist/
+apps/extension/.output/
+apps/extension/.wxt/
+docs/**
+!docs/architecture/project-structure.md

.prettierrc

@@ -0,0 +1,9 @@
+{
+    "singleQuote": true,
+    "trailingComma": "all",
+    "bracketSpacing": true,
+    "arrowParens": "always",
+    "printWidth": 80,
+    "tabWidth": 4,
+    "useTabs": false
+}

README.md

@@ -6,7 +6,9 @@ Atlas Seller Kit 是面向多用户、多门店、多平台与多国家市场的
 
 ## 当前状态
 
-仅完成产品与架构设计，尚未开始应用代码开发。开始新 AI 对话或开发前，请先阅读 [项目交接](./docs/project/HANDOFF.md)，再阅读 [文档导航](./docs/README.md)。
+项目已完成 monorepo 与本地基础设施初始化，并实现认证、个人工作空间、平台目录/上下文和门店管理 HTTP API。Web 已提供登录/注册、主布局、页头平台选择器和接入真实 API 的店铺管理页；其余业务页面仍为占位。门店凭据验证已接入 Outbox Dispatcher 与 Worker；仓库同步仍待实现。
+
+开始新 AI 对话或开发前，请先阅读 [项目交接](./docs/project/HANDOFF.md)，再阅读 [文档导航](./docs/README.md)。
 
 ## 设计目标
 

apps/api/.prettierrc

@@ -0,0 +1,9 @@
+{
+    "singleQuote": true,
+    "trailingComma": "all",
+    "bracketSpacing": true,
+    "arrowParens": "always",
+    "printWidth": 80,
+    "tabWidth": 4,
+    "useTabs": false
+}

apps/api/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@atlas/api",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "dev": "node scripts/dev.mjs",
+        "start": "node dist/main.js",
+        "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+        "test": "vitest run"
+    },
+    "dependencies": {
+        "@atlas/contracts": "workspace:*",
+        "@atlas/database": "workspace:*",
+        "@aws-sdk/client-s3": "3.1015.0",
+        "@aws-sdk/s3-request-presigner": "3.1015.0",
+        "@nestjs/common": "12.0.1",
+        "@nestjs/config": "12.0.0",
+        "@nestjs/core": "12.0.1",
+        "@nestjs/platform-express": "12.0.1",
+        "@nestjs/swagger": "12.0.1",
+        "helmet": "8.3.0",
+        "ioredis": "6.0.0",
+        "reflect-metadata": "0.2.2",
+        "rxjs": "7.8.2",
+        "zod": "4.5.4"
+    },
+    "devDependencies": {
+        "@nestjs/testing": "12.0.1",
+        "@types/express": "5.0.6",
+        "@types/node": "26.3.0",
+        "tsx": "4.23.13",
+        "typescript": "7.0.2",
+        "vitest": "^4.1.11"
+    }
+}

apps/api/scripts/dev.mjs

@@ -0,0 +1,72 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = dirname(fileURLToPath(import.meta.url));
+const repositoryRoot = resolve(scriptDirectory, '../../..');
+const environmentFile = resolve(repositoryRoot, '.env');
+const localEnvironment = existsSync(environmentFile)
+    ? parseEnvironment(readFileSync(environmentFile, 'utf8'))
+    : {};
+const apiPort = process.env.API_PORT ?? localEnvironment.API_PORT ?? '8200';
+const swaggerEnabled =
+    (process.env.SWAGGER_ENABLED ??
+        localEnvironment.SWAGGER_ENABLED ??
+        'true') === 'true';
+const nodeEnvironment =
+    process.env.NODE_ENV ?? localEnvironment.NODE_ENV ?? 'development';
+const swaggerUrl = `http://localhost:${apiPort}/api-docs`;
+const tsxCommand = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';
+const apiProcess = spawn(tsxCommand, ['watch', 'src/main.ts'], {
+    shell: process.platform === 'win32',
+    stdio: 'inherit',
+});
+
+if (
+    process.platform === 'darwin' &&
+    nodeEnvironment === 'development' &&
+    swaggerEnabled
+) {
+    void openSwaggerAfterApiIsReady();
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => apiProcess.kill(signal));
+}
+
+apiProcess.on('exit', (code, signal) => {
+    if (signal) process.exitCode = 1;
+    else process.exitCode = code ?? 0;
+});
+
+function parseEnvironment(content) {
+    return Object.fromEntries(
+        content
+            .split(/\r?\n/)
+            .map((line) => line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/))
+            .filter(Boolean)
+            .map((match) => [match[1], match[2]]),
+    );
+}
+
+async function openSwaggerAfterApiIsReady() {
+    const deadline = Date.now() + 30_000;
+    while (Date.now() < deadline) {
+        try {
+            const response = await fetch(`http://localhost:${apiPort}/health`);
+            if (response.ok) {
+                // 开发启动器进程不会随 tsx watch 的热重启重建，因此只会打开一次。
+                spawn('open', [swaggerUrl], {
+                    detached: true,
+                    stdio: 'ignore',
+                }).unref();
+                return;
+            }
+        } catch {
+            // API 仍在启动或热重启，继续等待到超时为止。
+        }
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, 250));
+    }
+    console.warn(`Swagger 未在 30 秒内就绪：${swaggerUrl}`);
+}

apps/api/src/app.module.ts

@@ -0,0 +1,53 @@
+import { Controller, Get, Inject, Module } from '@nestjs/common';
+import type { Database } from '@atlas/database';
+import { AuthModule } from './auth/auth.module.js';
+import { ApiError } from './common/api-error.js';
+import { Public } from './common/public.decorator.js';
+import { AppConfigModule } from './config/app-config.module.js';
+import { DATABASE, DatabaseModule } from './database/database.module.js';
+import { SecurityModule } from './security/security.module.js';
+import { StoresModule } from './stores/stores.module.js';
+import { WatermarksModule } from './watermarks/watermarks.module.js';
+import { MediaModule } from './media/media.module.js';
+import { CollectionModule } from './collection/collection.module.js';
+
+@Controller()
+class HealthController {
+    public constructor(@Inject(DATABASE) private readonly database: Database) {}
+
+    @Get('health')
+    @Public()
+    check() {
+        return { status: 'ok', service: 'api' };
+    }
+
+    @Get('ready')
+    @Public()
+    async ready() {
+        try {
+            await this.database.query('SELECT 1');
+            return { status: 'ready', service: 'api' };
+        } catch {
+            throw new ApiError(
+                503,
+                'DEPENDENCY_UNAVAILABLE',
+                '服务依赖暂不可用',
+            );
+        }
+    }
+}
+
+@Module({
+    imports: [
+        AppConfigModule,
+        DatabaseModule,
+        SecurityModule,
+        AuthModule,
+        StoresModule,
+        WatermarksModule,
+        MediaModule,
+        CollectionModule,
+    ],
+    controllers: [HealthController],
+})
+export class AppModule {}

apps/api/src/auth/auth.controller.ts

@@ -0,0 +1,323 @@
+import {
+    Body,
+    Controller,
+    Get,
+    Headers,
+    HttpCode,
+    Inject,
+    Patch,
+    Post,
+    Req,
+    Res,
+} from '@nestjs/common';
+import {
+    ApiBearerAuth,
+    ApiBody,
+    ApiNoContentResponse,
+    ApiOkResponse,
+    ApiOperation,
+    ApiTags,
+    ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
+import { createHash } from 'node:crypto';
+import {
+    changePasswordRequestSchema,
+    loginRequestSchema,
+    registerRequestSchema,
+    updateCurrentUserRequestSchema,
+    type Workspace,
+} from '@atlas/contracts';
+import { z } from 'zod';
+import { ApiError } from '../common/api-error.js';
+import { Public } from '../common/public.decorator.js';
+import type { AuthenticatedRequest } from './auth.guard.js';
+import { AuthService, type RequestMetadata } from './auth.service.js';
+import { CurrentWorkspace } from '../workspace/current-workspace.decorator.js';
+
+const refreshCookie = 'atlas_refresh';
+// 控制器只负责 HTTP 边界；账户、会话与工作空间的一致性由 AuthService 的事务保证。
+type HttpRequest = {
+    header: (name: string) => string | undefined;
+    ip?: string;
+};
+type HttpResponse = {
+    cookie: (
+        name: string,
+        value: string,
+        options: Record<string, unknown>,
+    ) => void;
+    clearCookie: (name: string, options: Record<string, unknown>) => void;
+};
+
+@ApiTags('Authentication')
+@Controller('auth')
+export class AuthController {
+    public constructor(
+        @Inject(AuthService) private readonly authService: AuthService,
+    ) {}
+
+    @Post('register')
+    @Public()
+    @ApiOperation({ summary: '注册账户并创建个人工作空间' })
+    @ApiBody({
+        schema: {
+            example: {
+                email: 'owner@example.com',
+                password: 'a-strong-password',
+                password_confirmation: 'a-strong-password',
+                display_name: 'Joey',
+            },
+        },
+    })
+    public async register(
+        @Body() body: unknown,
+        @Req() request: HttpRequest,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        const result = await this.authService.register(
+            parse(registerRequestSchema, body),
+            metadata(request),
+        );
+        setRefreshCookie(response, result.refreshToken);
+        return { data: result.payload };
+    }
+
+    @Post('login')
+    @Public()
+    @HttpCode(200)
+    @ApiOperation({ summary: '使用邮箱和密码登录' })
+    @ApiBody({
+        schema: {
+            example: {
+                email: 'owner@example.com',
+                password: 'a-strong-password',
+            },
+        },
+    })
+    public async login(
+        @Body() body: unknown,
+        @Req() request: HttpRequest,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        const result = await this.authService.login(
+            parse(loginRequestSchema, body),
+            metadata(request),
+        );
+        setRefreshCookie(response, result.refreshToken);
+        return { data: result.payload };
+    }
+
+    @Post('refresh')
+    @Public()
+    @HttpCode(200)
+    @ApiOperation({ summary: '轮换 refresh cookie 并获取新的 access token' })
+    public async refresh(
+        @Req() request: HttpRequest,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        try {
+            // refresh token 不进入 JSON body，仅从浏览器自动发送的 HttpOnly cookie 读取。
+            const result = await this.authService.refresh(
+                readCookie(request.header('cookie'), refreshCookie),
+                metadata(request),
+            );
+            setRefreshCookie(response, result.refreshToken);
+            return {
+                data: {
+                    access_token: result.payload.access_token,
+                    access_token_expires_in:
+                        result.payload.access_token_expires_in,
+                },
+            };
+        } catch (error) {
+            clearRefreshCookie(response);
+            throw error;
+        }
+    }
+
+    @Post('logout')
+    @HttpCode(204)
+    @ApiBearerAuth('access-token')
+    @ApiOperation({ summary: '撤销当前登录会话' })
+    @ApiNoContentResponse({ description: '会话已撤销' })
+    @ApiUnauthorizedResponse({ description: 'access token 无效或已过期' })
+    public async logout(
+        @Req() request: AuthenticatedRequest,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        await this.authService.logout(request.auth.sessionId);
+        clearRefreshCookie(response);
+    }
+
+    @Get('me')
+    @ApiBearerAuth('access-token')
+    @ApiOperation({ summary: '获取当前用户、工作空间和页头初始上下文' })
+    @ApiOkResponse({ description: '当前身份和工作空间' })
+    @ApiUnauthorizedResponse({ description: 'access token 无效或已过期' })
+    public async me(
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        return {
+            data: await this.authService.me(request.auth.userId, workspace),
+        };
+    }
+
+    @Patch('me')
+    @ApiBearerAuth('access-token')
+    @ApiOperation({ summary: '按版本更新当前账户的显示名称或头像素材引用' })
+    @ApiBody({
+        schema: {
+            example: {
+                display_name: 'Joey',
+                avatar_asset_id: 'b2b592e8-96b0-4d2b-afc4-2c6462f2065b',
+            },
+        },
+    })
+    public async updateProfile(
+        @Body() body: unknown,
+        @Headers('if-match') ifMatch: string | undefined,
+        @Headers('idempotency-key') idempotencyKey: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        return (
+            await this.authService.updateProfile(
+                workspace,
+                request.auth.userId,
+                requireIdempotencyKey(idempotencyKey),
+                parseRevision(ifMatch),
+                parse(updateCurrentUserRequestSchema, body),
+            )
+        ).body;
+    }
+
+    @Post('change-password')
+    @HttpCode(200)
+    @ApiBearerAuth('access-token')
+    @ApiOperation({ summary: '修改密码、撤销旧会话并轮换当前会话' })
+    @ApiBody({
+        schema: {
+            example: {
+                old_password: 'old-strong-password',
+                password: 'new-strong-password',
+                password_confirmation: 'new-strong-password',
+            },
+        },
+    })
+    public async changePassword(
+        @Body() body: unknown,
+        @Req() request: AuthenticatedRequest & HttpRequest,
+        @CurrentWorkspace() workspace: Workspace,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        const result = await this.authService.changePassword(
+            workspace,
+            request.auth.userId,
+            request.auth.sessionId,
+            parse(changePasswordRequestSchema, body),
+            metadata(request),
+        );
+        setRefreshCookie(response, result.refreshToken);
+        return {
+            data: {
+                access_token: result.payload.access_token,
+                access_token_expires_in: result.payload.access_token_expires_in,
+            },
+        };
+    }
+}
+
+function parse<
+    T extends {
+        safeParse: (value: unknown) => {
+            success: boolean;
+            data?: unknown;
+            error?: { issues: Array<{ path: PropertyKey[]; message: string }> };
+        };
+    },
+>(schema: T, value: unknown) {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return result.data as ReturnType<T['safeParse']> extends {
+            data: infer Data;
+        }
+            ? Data
+            : never;
+    throw new ApiError(
+        422,
+        'VALIDATION_FAILED',
+        '请求参数不符合要求',
+        result.error?.issues.map((issue) => ({
+            field: issue.path.join('.'),
+            code: 'INVALID_FIELD',
+            message: issue.message,
+        })),
+    );
+}
+function metadata(request: HttpRequest): RequestMetadata {
+    return {
+        ip: request.ip ?? null,
+        ipHash: request.ip
+            ? createHash('sha256').update(request.ip).digest('base64url')
+            : null,
+        userAgent: request.header('user-agent') ?? null,
+    };
+}
+function cookieOptions() {
+    // cookie 路径限制在认证接口，避免无关请求携带长期会话凭证。
+    return {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax' as const,
+        path: '/api/auth',
+        maxAge: 30 * 24 * 60 * 60 * 1000,
+    };
+}
+function setRefreshCookie(response: HttpResponse, token: string) {
+    response.cookie(refreshCookie, token, cookieOptions());
+}
+function clearRefreshCookie(response: HttpResponse) {
+    response.clearCookie(refreshCookie, {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax',
+        path: '/api/auth',
+    });
+}
+function readCookie(header: string | undefined, name: string) {
+    // 只解析本服务需要的单个 cookie，避免引入与认证无关的 cookie 状态。
+    return header
+        ?.split(';')
+        .map((part) => part.trim())
+        .find((part) => part.startsWith(`${name}=`))
+        ?.slice(name.length + 1);
+}
+function requireIdempotencyKey(value: string | undefined): string {
+    if (!value) {
+        throw new ApiError(
+            400,
+            'IDEMPOTENCY_KEY_REQUIRED',
+            '请求缺少 Idempotency-Key',
+        );
+    }
+    if (z.uuid().safeParse(value).success) return value;
+    throw new ApiError(422, 'VALIDATION_FAILED', '请求参数不符合要求', [
+        {
+            field: 'Idempotency-Key',
+            code: 'INVALID_FIELD',
+            message: 'Idempotency-Key 必须是 UUID',
+        },
+    ]);
+}
+function parseRevision(value: string | undefined): number {
+    const match = value?.match(/^"([1-9]\d*)"$/);
+    if (!match) {
+        throw new ApiError(
+            400,
+            'IF_MATCH_REQUIRED',
+            '请求必须携带形如 "1" 的 If-Match',
+        );
+    }
+    return Number(match[1]);
+}

apps/api/src/auth/auth.crypto.ts

@@ -0,0 +1,94 @@
+import {
+    createHash,
+    createHmac,
+    randomBytes,
+    scrypt as scryptCallback,
+    timingSafeEqual,
+} from 'node:crypto';
+import { promisify } from 'node:util';
+
+const scrypt = promisify(scryptCallback) as (
+    password: string,
+    salt: string,
+    keyLength: number,
+    options: { N: number; r: number; p: number; maxmem: number },
+) => Promise<Buffer>;
+// 使用较高成本的 scrypt 参数，控制离线破解密码哈希时的时间与内存成本。
+const scryptOptions = { N: 16_384, r: 8, p: 1, maxmem: 32 * 1024 * 1024 };
+
+export async function hashPassword(password: string): Promise<string> {
+    // 每个密码使用独立随机盐，数据库泄露时不能直接复用预计算结果。
+    const salt = randomBytes(16).toString('base64url');
+    const derived = (await scrypt(password, salt, 64, scryptOptions)) as Buffer;
+    return `scrypt$${salt}$${derived.toString('base64url')}`;
+}
+
+export async function verifyPassword(
+    password: string,
+    encoded: string,
+): Promise<boolean> {
+    const [algorithm, salt, expected] = encoded.split('$');
+    if (algorithm !== 'scrypt' || !salt || !expected) return false;
+    const actual = (await scrypt(password, salt, 64, scryptOptions)) as Buffer;
+    const expectedBuffer = Buffer.from(expected, 'base64url');
+    return (
+        expectedBuffer.length === actual.length &&
+        timingSafeEqual(expectedBuffer, actual)
+    );
+}
+
+export function createOpaqueToken(): string {
+    return randomBytes(48).toString('base64url');
+}
+export function tokenHash(token: string): string {
+    // refresh token 只以摘要形式存库；服务端无需保存可直接用于登录的原文。
+    return createHash('sha256').update(token).digest('base64url');
+}
+
+export type AccessTokenClaims = {
+    sub: string;
+    sid: string;
+    exp: number;
+    iat: number;
+};
+export function signAccessToken(
+    claims: AccessTokenClaims,
+    secret: string,
+): string {
+    // access token 是短期自包含凭证；真正可撤销的会话状态仍以 PostgreSQL 为准。
+    const header = Buffer.from(
+        JSON.stringify({ alg: 'HS256', typ: 'JWT' }),
+    ).toString('base64url');
+    const payload = Buffer.from(JSON.stringify(claims)).toString('base64url');
+    const signature = createHmac('sha256', secret)
+        .update(`${header}.${payload}`)
+        .digest('base64url');
+    return `${header}.${payload}.${signature}`;
+}
+export function verifyAccessToken(
+    token: string,
+    secret: string,
+): AccessTokenClaims | null {
+    const [header, payload, signature] = token.split('.');
+    if (!header || !payload || !signature) return null;
+    const expected = createHmac('sha256', secret)
+        .update(`${header}.${payload}`)
+        .digest();
+    const actual = Buffer.from(signature, 'base64url');
+    // 恒定时间比较可避免根据签名比对耗时推测正确前缀。
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+        return null;
+    try {
+        const claims = JSON.parse(
+            Buffer.from(payload, 'base64url').toString('utf8'),
+        ) as AccessTokenClaims;
+        return typeof claims.sub === 'string' &&
+            typeof claims.sid === 'string' &&
+            typeof claims.exp === 'number' &&
+            claims.exp > Math.floor(Date.now() / 1000)
+            ? claims
+            : null;
+    } catch {
+        return null;
+    }
+}

apps/api/src/auth/auth.guard.ts

@@ -0,0 +1,46 @@
+import {
+    CanActivate,
+    ExecutionContext,
+    Inject,
+    Injectable,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { Workspace } from '@atlas/contracts';
+import { IS_PUBLIC_ENDPOINT } from '../common/public.decorator.js';
+import { AuthService } from './auth.service.js';
+
+export type AuthenticatedRequest = {
+    header: (name: string) => string | undefined;
+    auth: {
+        userId: string;
+        sessionId: string;
+        workspace?: Workspace;
+    };
+};
+
+@Injectable()
+export class AccessTokenGuard implements CanActivate {
+    public constructor(
+        @Inject(Reflector) private readonly reflector: Reflector,
+        @Inject(AuthService) private readonly authService: AuthService,
+    ) {}
+    public async canActivate(context: ExecutionContext) {
+        // 公开端点必须显式声明，避免新路由因忘记添加守卫而意外暴露。
+        if (
+            this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_ENDPOINT, [
+                context.getHandler(),
+                context.getClass(),
+            ])
+        ) {
+            return true;
+        }
+        const request = context
+            .switchToHttp()
+            .getRequest<AuthenticatedRequest>();
+        // 只在此处解析 Authorization，后续守卫和控制器共享已验证的会话身份。
+        request.auth = await this.authService.authenticate(
+            request.header('authorization'),
+        );
+        return true;
+    }
+}

apps/api/src/auth/auth.module.ts

@@ -0,0 +1,20 @@
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { AuthController } from './auth.controller.js';
+import { AccessTokenGuard } from './auth.guard.js';
+import { AuthService } from './auth.service.js';
+import { WorkspaceContextGuard } from '../workspace/workspace-context.guard.js';
+import { IdempotencyService } from '../common/idempotency.service.js';
+
+@Module({
+    controllers: [AuthController],
+    providers: [
+        AuthService,
+        IdempotencyService,
+        AccessTokenGuard,
+        WorkspaceContextGuard,
+        { provide: APP_GUARD, useExisting: AccessTokenGuard },
+        { provide: APP_GUARD, useExisting: WorkspaceContextGuard },
+    ],
+})
+export class AuthModule {}

apps/api/src/auth/auth.service.ts

@@ -0,0 +1,512 @@
+import { Inject, Injectable, UnauthorizedException } from '@nestjs/common';
+import type {
+    AuthSessionResponse,
+    AuthUser,
+    ChangePasswordRequest,
+    LoginRequest,
+    RegisterRequest,
+    UpdateCurrentUserRequest,
+    Workspace,
+} 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 { AuthRateLimiter } from '../security/auth-rate-limiter.service.js';
+import {
+    createOpaqueToken,
+    hashPassword,
+    signAccessToken,
+    tokenHash,
+    verifyAccessToken,
+    verifyPassword,
+} from './auth.crypto.js';
+
+type UserRow = {
+    id: string;
+    email: string;
+    display_name: string | null;
+    avatar_asset_id: string | null;
+    email_verified_at: Date | null;
+    created_at: Date;
+    revision: number;
+    status: 'active' | 'disabled' | 'pending_review';
+    password_hash: string;
+};
+type WorkspaceRow = { id: string; name: string; role: Workspace['role'] };
+
+@Injectable()
+export class AuthService {
+    // access token 短期存在于浏览器内存；refresh session 的有效期更长且可服务端撤销。
+    private readonly accessTtlSeconds = 900;
+    private readonly refreshTtlDays = 30;
+
+    public constructor(
+        @Inject(DATABASE) private readonly database: Database,
+        @Inject(APP_CONFIG) private readonly config: AppConfig,
+        @Inject(AuthRateLimiter)
+        private readonly rateLimiter: AuthRateLimiter,
+        @Inject(IdempotencyService)
+        private readonly idempotency: IdempotencyService,
+    ) {}
+
+    public async register(input: RegisterRequest, metadata: RequestMetadata) {
+        if (input.password !== input.password_confirmation)
+            throw validationError(
+                'password_confirmation',
+                'PASSWORD_CONFIRMATION_MISMATCH',
+                '两次输入的密码不一致',
+            );
+        if (input.password.length < this.config.AUTH_PASSWORD_MIN_LENGTH)
+            throw validationError(
+                'password',
+                'PASSWORD_TOO_SHORT',
+                `密码至少需要 ${this.config.AUTH_PASSWORD_MIN_LENGTH} 个字符`,
+            );
+        const email = input.email.trim().toLowerCase();
+        // 限流必须早于密码哈希和用户查询，避免攻击者消耗 CPU 或探测账户状态。
+        await this.rateLimiter.consume('register', { ip: metadata.ip, email });
+        const passwordHash = await hashPassword(input.password);
+        try {
+            return await this.database.transaction(async (transaction) => {
+                // 用户、个人工作空间和 owner membership 必须原子创建，不能留下半成品租户。
+                const user = await insertUser(
+                    transaction,
+                    email,
+                    passwordHash,
+                    input.display_name?.trim() || null,
+                );
+                const workspace = await createPersonalWorkspace(
+                    transaction,
+                    user.id,
+                    user.display_name ?? email,
+                );
+                return this.createSessionResponse(
+                    transaction,
+                    user,
+                    workspace,
+                    metadata,
+                );
+            });
+        } catch (error: unknown) {
+            if (isUniqueViolation(error))
+                throw new ApiError(
+                    409,
+                    'EMAIL_ALREADY_REGISTERED',
+                    '该邮箱已注册',
+                    [
+                        {
+                            field: 'email',
+                            code: 'EMAIL_ALREADY_REGISTERED',
+                            message: '该邮箱已注册',
+                        },
+                    ],
+                );
+            throw error;
+        }
+    }
+
+    public async login(input: LoginRequest, metadata: RequestMetadata) {
+        const email = input.email.trim().toLowerCase();
+        // 限流与 citext 查询使用同一规范化邮箱，避免大小写绕过限流桶。
+        await this.rateLimiter.consume('login', { ip: metadata.ip, email });
+        const result = await this.database.query<UserRow>(
+            'SELECT id, email, display_name, avatar_asset_id, email_verified_at, created_at, revision, status, password_hash FROM atlas.users WHERE email = $1',
+            [email],
+        );
+        const user = result.rows[0];
+        if (
+            !user ||
+            !(await verifyPassword(input.password, user.password_hash))
+        )
+            throw new ApiError(401, 'INVALID_CREDENTIALS', '邮箱或密码错误');
+        if (user.status === 'disabled')
+            throw new ApiError(403, 'ACCOUNT_DISABLED', '账户已停用');
+        const workspace = await this.findWorkspace(user.id);
+        return this.database.transaction(async (transaction) => {
+            await transaction.query(
+                'UPDATE atlas.users SET last_login_at = now() WHERE id = $1',
+                [user.id],
+            );
+            return this.createSessionResponse(
+                transaction,
+                user,
+                workspace,
+                metadata,
+            );
+        });
+    }
+
+    public async refresh(
+        refreshToken: string | undefined,
+        metadata: RequestMetadata,
+    ) {
+        // refresh token 验证前没有可信邮箱，只能按 IP 维度限流。
+        await this.rateLimiter.consume('refresh', { ip: metadata.ip });
+        if (!refreshToken)
+            throw new ApiError(401, 'SESSION_EXPIRED', '登录会话已过期');
+        return this.database.transaction(async (transaction) => {
+            const sessions = await transaction.query<
+                UserRow & { session_id: string }
+            >(
+                `SELECT u.id, u.email, u.display_name, u.avatar_asset_id, u.email_verified_at, u.created_at, u.revision, u.status, u.password_hash, s.id AS session_id
+        FROM atlas.user_sessions s JOIN atlas.users u ON u.id = s.user_id
+        WHERE s.refresh_token_hash = $1 AND s.revoked_at IS NULL AND s.expires_at > now() FOR UPDATE`,
+                [tokenHash(refreshToken)],
+            );
+            const user = sessions.rows[0];
+            if (!user || user.status !== 'active')
+                throw new ApiError(401, 'SESSION_EXPIRED', '登录会话已过期');
+            // 行锁保证并发 refresh 时旧 token 只能成功使用一次。
+            await transaction.query(
+                'UPDATE atlas.user_sessions SET revoked_at = now() WHERE id = $1',
+                [user.session_id],
+            );
+            const workspace = await findWorkspaceInTransaction(
+                transaction,
+                user.id,
+            );
+            return this.createSessionResponse(
+                transaction,
+                user,
+                workspace,
+                metadata,
+            );
+        });
+    }
+
+    public async logout(sessionId: string) {
+        await this.database.query(
+            'UPDATE atlas.user_sessions SET revoked_at = now() WHERE id = $1 AND revoked_at IS NULL',
+            [sessionId],
+        );
+    }
+
+    public async authenticate(accessToken: string | undefined) {
+        const token = accessToken?.replace(/^Bearer\s+/i, '');
+        const claims = token
+            ? verifyAccessToken(token, this.config.AUTH_JWT_SECRET)
+            : null;
+        if (!claims) throw new UnauthorizedException();
+        // JWT 签名有效仍不足够；必须确认对应 session 未撤销且未过期。
+        const active = await this.database.query(
+            'SELECT 1 FROM atlas.user_sessions WHERE id = $1 AND user_id = $2 AND revoked_at IS NULL AND expires_at > now()',
+            [claims.sid, claims.sub],
+        );
+        if (!active.rowCount) throw new UnauthorizedException();
+        return { userId: claims.sub, sessionId: claims.sid };
+    }
+
+    public async me(userId: string, workspace: Workspace) {
+        // workspace 由全局守卫解析，避免控制器或服务各自选择租户造成边界不一致。
+        const users = await this.database.query<UserRow>(
+            'SELECT id, email, display_name, avatar_asset_id, email_verified_at, created_at, revision, status, password_hash FROM atlas.users WHERE id = $1',
+            [userId],
+        );
+        const user = users.rows[0];
+        if (!user) throw new UnauthorizedException();
+        const platforms = await this.database.workspaceTransaction(
+            workspace.id,
+            async (transaction) => {
+                const rows = await transaction.query<{
+                    id: string;
+                    code: string;
+                    name: string;
+                }>(
+                    "SELECT id, code, name FROM atlas.platforms WHERE status = 'active' ORDER BY CASE WHEN code = 'OZON' THEN 0 ELSE 1 END, name",
+                );
+                return rows.rows;
+            },
+        );
+        return {
+            user: publicUser(user),
+            workspace,
+            platforms,
+            suggested_context: {
+                platform_id: platforms[0]?.id ?? null,
+                default_store: null,
+            },
+        };
+    }
+
+    public async updateProfile(
+        workspace: Workspace,
+        userId: string,
+        idempotencyKey: string,
+        revision: number,
+        input: UpdateCurrentUserRequest,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId: workspace.id,
+                userId,
+                method: 'PATCH',
+                path: '/api/auth/me',
+                key: idempotencyKey,
+                request: { if_match: revision, ...input },
+            },
+            async (transaction) => {
+                const user = await findUserInTransaction(
+                    transaction,
+                    userId,
+                    true,
+                );
+                if (user.revision !== revision) {
+                    throw versionConflict(user.revision);
+                }
+                if (input.avatar_asset_id) {
+                    // 头像只能引用当前工作空间内已完成入库的素材，不能接受任意对象路径或 URL。
+                    const asset = await transaction.query<{ id: string }>(
+                        `SELECT id FROM atlas.media_assets WHERE id = $1`,
+                        [input.avatar_asset_id],
+                    );
+                    if (!asset.rows[0]) {
+                        throw new ApiError(
+                            422,
+                            'AVATAR_ASSET_UNAVAILABLE',
+                            '头像素材不存在或不属于当前工作空间',
+                        );
+                    }
+                }
+                const updated = await transaction.query<UserRow>(
+                    `UPDATE atlas.users
+                     SET display_name = CASE WHEN $1 THEN $2 ELSE display_name END,
+                         avatar_asset_id = CASE WHEN $3 THEN $4::uuid ELSE avatar_asset_id END,
+                         revision = revision + 1, updated_at = now()
+                     WHERE id = $5
+                     RETURNING id, email, display_name, avatar_asset_id, email_verified_at,
+                               created_at, revision, status, password_hash`,
+                    [
+                        Object.hasOwn(input, 'display_name'),
+                        input.display_name ?? null,
+                        Object.hasOwn(input, 'avatar_asset_id'),
+                        input.avatar_asset_id ?? null,
+                        userId,
+                    ],
+                );
+                return {
+                    status: 200,
+                    body: { data: publicUser(updated.rows[0]) },
+                };
+            },
+        );
+    }
+
+    public async changePassword(
+        workspace: Workspace,
+        userId: string,
+        sessionId: string,
+        input: ChangePasswordRequest,
+        metadata: RequestMetadata,
+    ) {
+        if (input.password !== input.password_confirmation) {
+            throw validationError(
+                'password_confirmation',
+                'PASSWORD_CONFIRMATION_MISMATCH',
+                '两次输入的密码不一致',
+            );
+        }
+        if (input.password.length < this.config.AUTH_PASSWORD_MIN_LENGTH) {
+            throw validationError(
+                'password',
+                'PASSWORD_TOO_SHORT',
+                `密码至少需要 ${this.config.AUTH_PASSWORD_MIN_LENGTH} 个字符`,
+            );
+        }
+        // 修改密码按已认证用户和来源 IP 双维度限流，避免已泄露会话被用于高频猜测旧密码。
+        await this.rateLimiter.consume('change_password', {
+            ip: metadata.ip,
+            userId,
+        });
+        return this.database.transaction(async (transaction) => {
+            const session = await transaction.query<{ id: string }>(
+                `SELECT id FROM atlas.user_sessions
+                 WHERE id = $1 AND user_id = $2 AND revoked_at IS NULL AND expires_at > now()
+                 FOR UPDATE`,
+                [sessionId, userId],
+            );
+            if (!session.rows[0]) throw new UnauthorizedException();
+            const user = await findUserInTransaction(transaction, userId, true);
+            if (user.status !== 'active') {
+                throw new ApiError(403, 'ACCOUNT_DISABLED', '账户已停用');
+            }
+            if (
+                !(await verifyPassword(input.old_password, user.password_hash))
+            ) {
+                throw validationError(
+                    'old_password',
+                    'CURRENT_PASSWORD_INVALID',
+                    '当前密码错误',
+                );
+            }
+            const passwordHash = await hashPassword(input.password);
+            const updated = await transaction.query<UserRow>(
+                `UPDATE atlas.users SET password_hash = $1, updated_at = now()
+                 WHERE id = $2
+                 RETURNING id, email, display_name, avatar_asset_id, email_verified_at,
+                           created_at, revision, status, password_hash`,
+                [passwordHash, userId],
+            );
+            // 先撤销所有旧 session，再创建新 session；旧 access token 会立即失效。
+            await transaction.query(
+                `UPDATE atlas.user_sessions SET revoked_at = now()
+                 WHERE user_id = $1 AND revoked_at IS NULL`,
+                [userId],
+            );
+            return this.createSessionResponse(
+                transaction,
+                updated.rows[0],
+                workspace,
+                metadata,
+            );
+        });
+    }
+
+    private async findWorkspace(userId: string) {
+        const result = await this.database.query<WorkspaceRow>(
+            `SELECT w.id, w.name, m.role FROM atlas.workspace_memberships m JOIN atlas.workspaces w ON w.id = m.workspace_id WHERE m.user_id = $1 AND w.status = 'active' ORDER BY m.joined_at LIMIT 1`,
+            [userId],
+        );
+        return requireWorkspace(result.rows[0]);
+    }
+    private async createSessionResponse(
+        transaction: DatabaseTransaction,
+        user: UserRow,
+        workspace: WorkspaceRow,
+        metadata: RequestMetadata,
+    ) {
+        // refresh token 仅通过 HttpOnly cookie 交给浏览器，响应体只暴露短期 access token。
+        const refreshToken = createOpaqueToken();
+        const session = await transaction.query<{ id: string }>(
+            `INSERT INTO atlas.user_sessions (user_id, refresh_token_hash, expires_at, ip_hash, user_agent)
+      VALUES ($1, $2, now() + ($3 || ' days')::interval, $4, $5) RETURNING id`,
+            [
+                user.id,
+                tokenHash(refreshToken),
+                this.refreshTtlDays,
+                metadata.ipHash,
+                metadata.userAgent,
+            ],
+        );
+        const now = Math.floor(Date.now() / 1000);
+        const accessToken = signAccessToken(
+            {
+                sub: user.id,
+                sid: session.rows[0].id,
+                iat: now,
+                exp: now + this.accessTtlSeconds,
+            },
+            this.config.AUTH_JWT_SECRET,
+        );
+        const payload: AuthSessionResponse = {
+            access_token: accessToken,
+            access_token_expires_in: this.accessTtlSeconds,
+            user: publicUser(user),
+            workspace,
+        };
+        return { payload, refreshToken };
+    }
+}
+
+export type RequestMetadata = {
+    ip: string | null;
+    ipHash: string | null;
+    userAgent: string | null;
+};
+function validationError(field: string, code: string, message: string) {
+    return new ApiError(422, 'VALIDATION_FAILED', '请求参数不符合要求', [
+        { field, code, message },
+    ]);
+}
+function isUniqueViolation(error: unknown): error is { code: string } {
+    return (
+        typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        (error as { code: string }).code === '23505'
+    );
+}
+async function findUserInTransaction(
+    transaction: DatabaseTransaction,
+    userId: string,
+    lock: boolean,
+): Promise<UserRow> {
+    const result = await transaction.query<UserRow>(
+        `SELECT id, email, display_name, avatar_asset_id, email_verified_at, created_at,
+                revision, status, password_hash
+         FROM atlas.users WHERE id = $1${lock ? ' FOR UPDATE' : ''}`,
+        [userId],
+    );
+    if (!result.rows[0]) throw new UnauthorizedException();
+    return result.rows[0];
+}
+function versionConflict(currentRevision: number) {
+    return new ApiError(409, 'VERSION_CONFLICT', '账户资料已被其他操作更新', [
+        {
+            field: 'If-Match',
+            code: 'VERSION_CONFLICT',
+            message: `当前版本为 ${currentRevision}`,
+            current_revision: currentRevision,
+        },
+    ]);
+}
+function publicUser(user: UserRow): AuthUser {
+    // 白名单映射防止 password_hash 等内部字段随查询结果泄露给客户端。
+    return {
+        id: user.id,
+        email: user.email,
+        display_name: user.display_name,
+        avatar_asset_id: user.avatar_asset_id,
+        email_verified_at: user.email_verified_at?.toISOString() ?? null,
+        created_at: user.created_at.toISOString(),
+        revision: user.revision,
+    };
+}
+async function insertUser(
+    transaction: DatabaseTransaction,
+    email: string,
+    passwordHash: string,
+    displayName: string | null,
+) {
+    // slug 使用用户 UUID，显示名称变化不会影响个人工作空间的稳定标识。
+    const result = await transaction.query<UserRow>(
+        'INSERT INTO atlas.users (email, password_hash, display_name) VALUES ($1, $2, $3) RETURNING id, email, display_name, avatar_asset_id, email_verified_at, created_at, revision, status, password_hash',
+        [email, passwordHash, displayName],
+    );
+    return result.rows[0];
+}
+async function createPersonalWorkspace(
+    transaction: DatabaseTransaction,
+    userId: string,
+    label: string,
+) {
+    const workspace = await transaction.query<{ id: string; name: string }>(
+        'INSERT INTO atlas.workspaces (name, slug) VALUES ($1, $2) RETURNING id, name',
+        [`${label} 的工作空间`, `personal-${userId}`],
+    );
+    await transaction.query(
+        "INSERT INTO atlas.workspace_memberships (workspace_id, user_id, role) VALUES ($1, $2, 'owner')",
+        [workspace.rows[0].id, userId],
+    );
+    return { ...workspace.rows[0], role: 'owner' as const };
+}
+async function findWorkspaceInTransaction(
+    transaction: DatabaseTransaction,
+    userId: string,
+): Promise<WorkspaceRow> {
+    const result = await transaction.query<WorkspaceRow>(
+        `SELECT w.id, w.name, m.role FROM atlas.workspace_memberships m JOIN atlas.workspaces w ON w.id = m.workspace_id WHERE m.user_id = $1 AND w.status = 'active' ORDER BY m.joined_at LIMIT 1`,
+        [userId],
+    );
+    return requireWorkspace(result.rows[0]);
+}
+function requireWorkspace(workspace: WorkspaceRow | undefined): WorkspaceRow {
+    if (!workspace)
+        throw new ApiError(
+            403,
+            'WORKSPACE_MEMBERSHIP_REQUIRED',
+            '当前账户没有可用工作空间',
+        );
+    return workspace;
+}

apps/api/src/collection/collection.controller.ts

@@ -0,0 +1,36 @@
+import { Body, Controller, Get, Headers, Inject, Param, Patch, Post, Query, Req, Res } from '@nestjs/common';
+import { z } from 'zod';
+import { bulkDeleteCollectionItemsRequestSchema, clearCollectionItemsRequestSchema, createCollectionItemRequestSchema, listCollectionItemsQuerySchema, retryCollectionAssetsRequestSchema, updateCollectionItemRequestSchema, type Workspace } from '@atlas/contracts';
+import { ApiError } from '../common/api-error.js';
+import type { AuthenticatedRequest } from '../auth/auth.guard.js';
+import { CurrentWorkspace } from '../workspace/current-workspace.decorator.js';
+import { CollectionService } from './collection.service.js';
+
+type Response = { status: (value: number) => Response };
+@Controller('collection-items')
+export class CollectionController {
+  public constructor(@Inject(CollectionService) private readonly collection: CollectionService) {}
+  @Get() async list(@Query() query: unknown, @Headers('x-atlas-platform-id') platformId: string | undefined, @CurrentWorkspace() workspace: Workspace) {
+    if (!platformId) throw new ApiError(400, 'PLATFORM_CONTEXT_REQUIRED', '请求缺少 X-Atlas-Platform-Id');
+    return this.collection.list(workspace.id, requireUuid('X-Atlas-Platform-Id', platformId), parse(listCollectionItemsQuerySchema, query));
+  }
+  @Post() async create(@Body() body: unknown, @Headers('idempotency-key') key: string | undefined, @Req() request: AuthenticatedRequest, @CurrentWorkspace() workspace: Workspace, @Res({ passthrough: true }) response: Response) {
+    const result = await this.collection.create(workspace.id, request.auth.userId, requireKey(key), parse(createCollectionItemRequestSchema, body)); response.status(result.status); return result.body;
+  }
+  @Patch(':id') async update(@Param('id') id: string, @Body() body: unknown, @Headers('idempotency-key') key: string | undefined, @Headers('if-match') match: string | undefined, @Req() request: AuthenticatedRequest, @CurrentWorkspace() workspace: Workspace) {
+    return (await this.collection.update(workspace.id, request.auth.userId, requireUuid('collection_item_id', id), requireKey(key), revision(match), parse(updateCollectionItemRequestSchema, body))).body;
+  }
+  @Post('bulk-delete') async bulkDelete(@Body() body: unknown, @Headers('idempotency-key') key: string | undefined, @Req() request: AuthenticatedRequest, @CurrentWorkspace() workspace: Workspace, @Res({ passthrough: true }) response: Response) {
+    const result = await this.collection.bulkDelete(workspace.id, request.auth.userId, requireKey(key), parse(bulkDeleteCollectionItemsRequestSchema, body)); response.status(result.status); return result.body;
+  }
+  @Post('clear') async clear(@Body() body: unknown, @Headers('idempotency-key') key: string | undefined, @Req() request: AuthenticatedRequest, @CurrentWorkspace() workspace: Workspace, @Res({ passthrough: true }) response: Response) {
+    const result = await this.collection.clear(workspace.id, request.auth.userId, requireKey(key), parse(clearCollectionItemsRequestSchema, body)); response.status(result.status); return result.body;
+  }
+  @Post(':id/asset-retries') async retry(@Param('id') id: string, @Body() body: unknown, @Headers('idempotency-key') key: string | undefined, @Req() request: AuthenticatedRequest, @CurrentWorkspace() workspace: Workspace, @Res({ passthrough: true }) response: Response) {
+    const result = await this.collection.retryAssets(workspace.id, request.auth.userId, requireUuid('collection_item_id', id), requireKey(key), parse(retryCollectionAssetsRequestSchema, body)); response.status(result.status); return result.body;
+  }
+}
+function parse<T extends { safeParse: (input: unknown) => { success: boolean; data?: unknown; error?: { issues: Array<{ path: PropertyKey[]; message: string }> } } }>(schema: T, input: unknown) { const result = schema.safeParse(input); if (result.success) return result.data as never; throw new ApiError(422, 'VALIDATION_FAILED', '请求参数不符合要求', result.error?.issues.map((x) => ({ field: x.path.join('.'), code: 'INVALID_FIELD', message: x.message }))); }
+function requireUuid(field: string, value: string) { if (z.uuid().safeParse(value).success) return value; throw new ApiError(422, 'VALIDATION_FAILED', '请求参数不符合要求', [{ field, code: 'INVALID_FIELD', message: `${field} 必须是 UUID` }]); }
+function requireKey(value: string | undefined) { if (!value) throw new ApiError(400, 'IDEMPOTENCY_KEY_REQUIRED', '请求缺少 Idempotency-Key'); return requireUuid('Idempotency-Key', value); }
+function revision(value: string | undefined) { const valueMatch = value?.match(/^"([1-9]\d*)"$/); if (!valueMatch) throw new ApiError(400, 'IF_MATCH_REQUIRED', '请求缺少或格式错误的 If-Match'); return Number(valueMatch[1]); }

apps/api/src/collection/collection.module.ts

@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+import { IdempotencyService } from '../common/idempotency.service.js';
+import { CollectionController } from './collection.controller.js';
+import { CollectionService } from './collection.service.js';
+
+@Module({ controllers: [CollectionController], providers: [IdempotencyService, CollectionService] })
+export class CollectionModule {}

apps/api/src/collection/collection.service.ts

@@ -0,0 +1,57 @@
+import { randomUUID } from 'node:crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import type { CreateCollectionItemRequest, ListCollectionItemsQuery, UpdateCollectionItemRequest } 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 { DATABASE } from '../database/database.module.js';
+
+type Row = { id: string; product_id: string; source_kind: 'platform' | 'manual'; platform_code: string | null; source_url: string | null; source_title: string | null; source_min_price: string | null; source_max_price: string | null; source_currency_code: string | null; note: string | null; status: string; created_at: Date | string; updated_at: Date | string; revision: number; variant_count: string; transfer_status: string | null };
+@Injectable()
+export class CollectionService {
+  public constructor(@Inject(IdempotencyService) private readonly idempotency: IdempotencyService, @Inject(DATABASE) private readonly database: Database) {}
+  async list(workspaceId: string, platformId: string, query: ListCollectionItemsQuery) {
+    const cursor = query.cursor ? decodeCursor(query.cursor) : null;
+    return this.database.workspaceTransaction(workspaceId, async (tx) => {
+      await this.requireHeaderPlatform(tx, platformId);
+      const rows = await tx.query<Row>(`${selectRow}
+        WHERE c.deleted_at IS NULL AND ($1::text IS NULL OR c.source_title ILIKE '%' || $1 || '%')
+          AND ($2::text IS NULL OR p.code = $2) AND ($3::text IS NULL OR $3 = 'not_listed')
+          AND ($4::timestamptz IS NULL OR (c.updated_at, c.id) < ($4, $5::uuid))
+        ${collectionGroupBy} ORDER BY c.updated_at DESC, c.id DESC LIMIT $6`, [query.q ?? null, query.source_platform_code ?? null, query.listing_status ?? null, cursor?.at ?? null, cursor?.id ?? null, query.limit + 1]);
+      const items = rows.rows.slice(0, query.limit).map(toItem); const last = items.at(-1);
+      const count = await tx.query<{ count: string; collection_item_limit: number }>('SELECT count(*)::text AS count, max(w.collection_item_limit)::int AS collection_item_limit FROM atlas.collection_items c CROSS JOIN atlas.workspaces w WHERE c.workspace_id = w.id AND c.deleted_at IS NULL');
+      return { data: items, meta: { has_more: rows.rows.length > query.limit, next_cursor: rows.rows.length > query.limit && last ? encodeCursor(last.updated_at, last.id) : null, active_count: Number(count.rows[0]?.count ?? 0), collection_limit: count.rows[0]?.collection_item_limit ?? 1000 } };
+    });
+  }
+  async create(workspaceId: string, userId: string, key: string, input: CreateCollectionItemRequest) {
+    return this.idempotency.run({ workspaceId, userId, method: 'POST', path: '/api/collection-items', key, request: input }, async (tx) => {
+      const item = await tx.query<{ id: string }>(`INSERT INTO atlas.collection_items (workspace_id, source_kind, source_item_key, source_title, note, status) VALUES (current_setting('app.workspace_id')::uuid, 'manual', $1, $2, $3, 'ready_for_edit') RETURNING id`, [randomUUID(), input.title ?? null, input.note ?? null]);
+      const product = await tx.query<{ id: string }>(`INSERT INTO atlas.products (workspace_id, collection_item_id, source_title) VALUES (current_setting('app.workspace_id')::uuid, $1, $2) RETURNING id`, [item.rows[0].id, input.title ?? null]);
+      await tx.query(`INSERT INTO atlas.product_variants (workspace_id, product_id, display_name, sort_order) VALUES (current_setting('app.workspace_id')::uuid, $1, '默认 SKU', 0)`, [product.rows[0].id]);
+      return { status: 201, body: { data: { collection_item: await this.requireItem(tx, item.rows[0].id), product_id: product.rows[0].id, editor_entry_path: `/collection-items/${item.rows[0].id}/edit` } } };
+    });
+  }
+  async update(workspaceId: string, userId: string, id: string, key: string, expected: number, input: UpdateCollectionItemRequest) {
+    return this.idempotency.run({ workspaceId, userId, method: 'PATCH', path: `/api/collection-items/${id}`, key, request: { if_match: expected, ...input } }, async (tx) => {
+      const result = await tx.query(`UPDATE atlas.collection_items SET note = $1, revision = revision + 1, updated_at = now() WHERE id = $2 AND deleted_at IS NULL AND revision = $3`, [input.note, id, expected]);
+      if (!result.rowCount) await this.versionConflict(tx, id, expected);
+      return { status: 200, body: { data: await this.requireItem(tx, id) } };
+    });
+  }
+  async bulkDelete(workspaceId: string, userId: string, key: string, ids: { ids: string[] }) { return this.removeMany(workspaceId, userId, key, '/api/collection-items/bulk-delete', ids, false); }
+  async clear(workspaceId: string, userId: string, key: string, input: { confirm: true; expected_active_count: number }) { return this.removeMany(workspaceId, userId, key, '/api/collection-items/clear', input, true); }
+  async retryAssets(workspaceId: string, userId: string, id: string, key: string, input: { transfer_ids: string[] }) { return this.idempotency.run({ workspaceId, userId, method: 'POST', path: `/api/collection-items/${id}/asset-retries`, key, request: input }, async (tx) => { await this.requireItem(tx, id); const result = await tx.query(`UPDATE atlas.collection_asset_transfers SET status = 'queued', error_payload = NULL, updated_at = now() WHERE collection_item_id = $1 AND id = ANY($2::uuid[]) AND status IN ('failed', 'cancelled')`, [id, input.transfer_ids]); if (result.rowCount !== input.transfer_ids.length) throw new ApiError(422, 'ASSET_RETRY_INVALID', '只能重试当前采集记录中失败或已取消的素材任务'); const operation = await this.operation(tx, userId, 'collection_asset_retry', id); await this.event(tx, id, 'collection.assets.retry.requested', { operation_id: operation.id, collection_item_id: id }); return { status: 202, body: { data: { operation } } }; }); }
+  private async removeMany(workspaceId: string, userId: string, key: string, path: string, input: unknown, clear: boolean) { return this.idempotency.run({ workspaceId, userId, method: 'POST', path, key, request: input }, async (tx) => { const requested = input as { ids?: string[]; expected_active_count?: number }; const count = await tx.query<{ count: string }>('SELECT count(*)::text AS count FROM atlas.collection_items WHERE deleted_at IS NULL'); if (clear && Number(count.rows[0].count) !== requested.expected_active_count) throw new ApiError(409, 'COLLECTION_COUNT_CHANGED', '采集箱数量已变化，请重新确认'); const deleted = await tx.query<{ id: string }>(clear ? `UPDATE atlas.collection_items SET status = 'deleted', deleted_at = now(), revision = revision + 1, updated_at = now() WHERE deleted_at IS NULL RETURNING id` : `UPDATE atlas.collection_items SET status = 'deleted', deleted_at = now(), revision = revision + 1, updated_at = now() WHERE id = ANY($1::uuid[]) AND deleted_at IS NULL RETURNING id`, clear ? [] : [requested.ids]); if (!clear && deleted.rows.length !== requested.ids?.length) throw new ApiError(404, 'RESOURCE_NOT_FOUND', '部分采集记录不存在'); const operation = await this.operation(tx, userId, 'collection_cleanup', deleted.rows[0]?.id ?? null); await this.event(tx, operation.id, 'collection.cleanup.requested', { operation_id: operation.id, collection_item_ids: deleted.rows.map((row) => row.id) }); return { status: 202, body: { data: { deleted_count: deleted.rows.length, operation } } }; }); }
+  private async operation(tx: DatabaseTransaction, userId: string, kind: string, resourceId: string | null) { const row = await tx.query<{ id: string; status: string; created_at: Date | string }>(`INSERT INTO atlas.operations (workspace_id, kind, resource_type, resource_id, created_by_user_id) VALUES (current_setting('app.workspace_id')::uuid, $1, 'collection_item', $2, $3) RETURNING id, status, created_at`, [kind, resourceId, userId]); return { id: row.rows[0].id, kind, status: row.rows[0].status, created_at: iso(row.rows[0].created_at), completed_at: null, error: null }; }
+  private async event(tx: DatabaseTransaction, aggregateId: string, type: string, payload: unknown) { await tx.query(`INSERT INTO atlas.outbox_events (workspace_id, aggregate_type, aggregate_id, event_type, event_payload, deduplication_key) VALUES (current_setting('app.workspace_id')::uuid, 'collection_item', $1, $2, $3, $4)`, [aggregateId, type, payload, `${type}:${aggregateId}`]); }
+  private async requireHeaderPlatform(tx: DatabaseTransaction, id: string) { const row = await tx.query(`SELECT id FROM atlas.platforms WHERE id = $1 AND status = 'active' AND coalesce((capabilities->>'can_be_header_context')::boolean, false)`, [id]); if (!row.rows[0]) throw new ApiError(422, 'PLATFORM_UNAVAILABLE', '当前平台不可用于 ERP 上下文'); }
+  private async requireItem(tx: DatabaseTransaction, id: string) { const row = await tx.query<Row>(`${selectRow} WHERE c.id = $1 AND c.deleted_at IS NULL ${collectionGroupBy}`, [id]); if (!row.rows[0]) throw new ApiError(404, 'RESOURCE_NOT_FOUND', '采集记录不存在'); return toItem(row.rows[0]); }
+  private async versionConflict(tx: DatabaseTransaction, id: string, expected: number) { const row = await tx.query<{ revision: number }>('SELECT revision FROM atlas.collection_items WHERE id = $1 AND deleted_at IS NULL', [id]); if (!row.rows[0]) throw new ApiError(404, 'RESOURCE_NOT_FOUND', '采集记录不存在'); if (row.rows[0].revision !== expected) throw new ApiError(409, 'VERSION_CONFLICT', '采集记录已被更新', [{ field: 'If-Match', code: 'VERSION_CONFLICT', message: `当前版本为 ${row.rows[0].revision}`, current_revision: row.rows[0].revision }]); }
+}
+const selectRow = `SELECT c.id, product.id AS product_id, c.source_kind, p.code AS platform_code, c.source_url, c.source_title, c.source_min_price::text, c.source_max_price::text, c.source_currency_code, c.note, c.status, c.created_at, c.updated_at, c.revision, count(DISTINCT v.id)::text AS variant_count, min(t.status) AS transfer_status FROM atlas.collection_items c JOIN atlas.products product ON product.collection_item_id = c.id LEFT JOIN atlas.platforms p ON p.id = c.source_platform_id LEFT JOIN atlas.product_variants v ON v.product_id = product.id AND v.deleted_at IS NULL LEFT JOIN atlas.collection_asset_transfers t ON t.collection_item_id = c.id`;
+const collectionGroupBy = 'GROUP BY c.id, product.id, p.code';
+function toItem(row: Row) { return { id: row.id, product_id: row.product_id, source: { kind: row.source_kind, platform_code: row.platform_code, url: row.source_url }, title: row.source_title, thumbnail: { asset_id: null, preview_url: null, status: row.transfer_status ?? 'none' }, source_price: { min: row.source_min_price, max: row.source_max_price, currency_code: row.source_currency_code }, variant_summary: { count: Number(row.variant_count), needs_review: row.status === 'needs_review' }, note: row.note, collection_status: row.status, listing_summary: { status: 'not_listed' as const, detail: '等待首次上架', last_error: null }, created_at: iso(row.created_at), updated_at: iso(row.updated_at), revision: row.revision }; }
+function iso(value: Date | string) { return value instanceof Date ? value.toISOString() : value; }
+function encodeCursor(at: string, id: string) { return Buffer.from(JSON.stringify({ at, id })).toString('base64url'); }
+function decodeCursor(cursor: string): { at: string; id: string } { try { const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as { at?: string; id?: string }; if (!value.at || !value.id || Number.isNaN(Date.parse(value.at))) throw new Error(); return { at: value.at, id: value.id }; } catch { throw new ApiError(422, 'VALIDATION_FAILED', '分页游标无效'); } }

apps/api/src/common/api-error.filter.ts

@@ -0,0 +1,64 @@
+import {
+    ArgumentsHost,
+    Catch,
+    ExceptionFilter,
+    HttpException,
+} from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+import { ApiError } from './api-error.js';
+import { AppLogger } from '../logging/app-logger.js';
+
+@Catch()
+export class ApiErrorFilter implements ExceptionFilter {
+    public constructor(private readonly logger: AppLogger) {}
+
+    public catch(exception: unknown, host: ArgumentsHost) {
+        const response = host.switchToHttp().getResponse<{
+            status: (status: number) => {
+                json: (body: unknown) => unknown;
+            };
+        }>();
+        const request = host.switchToHttp().getRequest<{
+            requestId?: string;
+            method?: string;
+            originalUrl?: string;
+        }>();
+        const requestId = request.requestId ?? `req_${randomUUID()}`;
+        if (exception instanceof ApiError) {
+            // 已知业务错误保留其稳定 code 与 details，方便前端精确处理。
+            const body = exception.getResponse() as {
+                error: Record<string, unknown>;
+            };
+            return response
+                .status(exception.getStatus())
+                .json({ error: { ...body.error, request_id: requestId } });
+        }
+        if (exception instanceof HttpException) {
+            // Nest 内部异常不泄露原始 message，避免暴露认证或解析实现细节。
+            return response.status(exception.getStatus()).json({
+                error: {
+                    code: 'HTTP_ERROR',
+                    message: '请求无法处理',
+                    request_id: requestId,
+                },
+            });
+        }
+        this.logger.error(
+            'unhandled_exception',
+            exception instanceof Error ? exception.stack : undefined,
+            {
+                request_id: requestId,
+                method: request.method,
+                path: request.originalUrl,
+            },
+        );
+        // 未预期异常只返回通用信息，request_id 用于从结构化日志定位根因。
+        return response.status(500).json({
+            error: {
+                code: 'INTERNAL_ERROR',
+                message: '服务器暂时无法处理请求',
+                request_id: requestId,
+            },
+        });
+    }
+}

apps/api/src/common/api-error.ts

@@ -0,0 +1,13 @@
+import { HttpException, HttpStatus } from '@nestjs/common';
+
+export class ApiError extends HttpException {
+    // 业务代码只能通过此类型抛出可预期错误，最终由全局过滤器统一封装为 error 信封。
+    public constructor(
+        status: HttpStatus,
+        code: string,
+        message: string,
+        details?: unknown[],
+    ) {
+        super({ error: { code, message, details } }, status);
+    }
+}

apps/api/src/common/idempotency.service.ts

@@ -0,0 +1,133 @@
+import { createHmac } from 'node:crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import type { Database, DatabaseTransaction } from '@atlas/database';
+import { APP_CONFIG, type AppConfig } from '../config/app-config.module.js';
+import { DATABASE } from '../database/database.module.js';
+import { ApiError } from './api-error.js';
+
+type IdempotentResponse = { status: number; body: unknown };
+type IdempotencyInput = {
+    workspaceId: string;
+    userId: string;
+    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    key: string;
+    request: unknown;
+};
+type IdempotencyRow = {
+    request_fingerprint: string;
+    status: 'in_progress' | 'completed';
+    response_status: number | null;
+    response_body: unknown;
+};
+
+@Injectable()
+export class IdempotencyService {
+    public constructor(
+        @Inject(DATABASE) private readonly database: Database,
+        @Inject(APP_CONFIG) private readonly config: AppConfig,
+    ) {}
+
+    /**
+     * 幂等记录与业务写入共用同一个工作空间事务。只有两者都提交，重试才会得到可靠的历史响应。
+     */
+    public async run(
+        input: IdempotencyInput,
+        work: (transaction: DatabaseTransaction) => Promise<IdempotentResponse>,
+    ): Promise<IdempotentResponse> {
+        const fingerprint = createHmac(
+            'sha256',
+            this.config.IDEMPOTENCY_KEY_SECRET,
+        )
+            .update(canonicalize(input.request))
+            .digest('base64url');
+
+        return this.database.workspaceTransaction(
+            input.workspaceId,
+            async (transaction) => {
+                const inserted = await transaction.query<IdempotencyRow>(
+                    `INSERT INTO atlas.idempotency_requests
+                        (workspace_id, user_id, http_method, request_path, idempotency_key, request_fingerprint)
+                     VALUES ($1, $2, $3, $4, $5, $6)
+                     ON CONFLICT (workspace_id, user_id, http_method, request_path, idempotency_key) DO NOTHING
+                     RETURNING request_fingerprint, status, response_status, response_body`,
+                    [
+                        input.workspaceId,
+                        input.userId,
+                        input.method,
+                        input.path,
+                        input.key,
+                        fingerprint,
+                    ],
+                );
+                if (!inserted.rows[0]) {
+                    // 冲突插入会等待首个事务结束；随后行锁确保只能读取完整的持久化结果。
+                    const existing = await transaction.query<IdempotencyRow>(
+                        `SELECT request_fingerprint, status, response_status, response_body
+                         FROM atlas.idempotency_requests
+                         WHERE workspace_id = $1 AND user_id = $2 AND http_method = $3
+                           AND request_path = $4 AND idempotency_key = $5
+                         FOR UPDATE`,
+                        [
+                            input.workspaceId,
+                            input.userId,
+                            input.method,
+                            input.path,
+                            input.key,
+                        ],
+                    );
+                    const row = existing.rows[0];
+                    if (!row || row.request_fingerprint !== fingerprint) {
+                        throw new ApiError(
+                            409,
+                            'IDEMPOTENCY_KEY_REUSED',
+                            '幂等键已用于不同请求',
+                        );
+                    }
+                    if (row.status !== 'completed' || !row.response_status) {
+                        throw new ApiError(
+                            409,
+                            'IDEMPOTENCY_REQUEST_IN_PROGRESS',
+                            '相同请求仍在处理中',
+                        );
+                    }
+                    return {
+                        status: row.response_status,
+                        body: row.response_body,
+                    };
+                }
+
+                const response = await work(transaction);
+                await transaction.query(
+                    `UPDATE atlas.idempotency_requests
+                     SET status = 'completed', response_status = $1, response_body = $2,
+                         completed_at = now()
+                     WHERE workspace_id = $3 AND user_id = $4 AND http_method = $5
+                       AND request_path = $6 AND idempotency_key = $7`,
+                    [
+                        response.status,
+                        response.body,
+                        input.workspaceId,
+                        input.userId,
+                        input.method,
+                        input.path,
+                        input.key,
+                    ],
+                );
+                return response;
+            },
+        );
+    }
+}
+
+/** 规范化排序后再签名，使 JSON 字段顺序不会改变同一请求的身份。 */
+function canonicalize(value: unknown): string {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) return `[${value.map(canonicalize).join(',')}]`;
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`)
+        .join(',')}}`;
+}

apps/api/src/common/public.decorator.ts

@@ -0,0 +1,6 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_PUBLIC_ENDPOINT = 'atlas:is-public-endpoint';
+
+// 全局认证守卫只跳过显式标记的端点，避免新接口因遗漏守卫而意外公开。
+export const Public = () => SetMetadata(IS_PUBLIC_ENDPOINT, true);

apps/api/src/config/app-config.module.ts

@@ -0,0 +1,165 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Global, Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { z } from 'zod';
+
+export const APP_CONFIG = Symbol('APP_CONFIG');
+
+function findEnvironmentFile(): string {
+    const directories = [
+        process.cwd(),
+        resolve(process.cwd(), '..'),
+        resolve(process.cwd(), '../..'),
+    ];
+    const environmentFile = directories
+        .map((directory) => resolve(directory, '.env'))
+        .find((file) => existsSync(file));
+
+    return environmentFile ?? resolve(process.cwd(), '.env');
+}
+
+// 此 schema 是 API 运行配置的唯一来源；默认值只允许用于不含秘密的本地开发场景。
+const environmentSchema = z.object({
+    NODE_ENV: z
+        .enum(['development', 'test', 'production'])
+        .default('development'),
+    API_PORT: z.coerce.number().int().min(1).max(65_535).default(8200),
+    WEB_ORIGIN: z.url().default('http://localhost:8100'),
+    DATABASE_URL: z.url(),
+    REDIS_URL: z.url(),
+    OBJECT_STORAGE_ENDPOINT: z.url().default('http://localhost:9000'),
+    OBJECT_STORAGE_BUCKET: z.string().min(3).max(63).default('atlas-assets'),
+    OBJECT_STORAGE_FORCE_PATH_STYLE: z.enum(['true', 'false']).default('true'),
+    OBJECT_STORAGE_ACCESS_KEY: z.string().min(3).optional(),
+    OBJECT_STORAGE_SECRET_KEY: z.string().min(8).optional(),
+    MINIO_ROOT_USER: z.string().min(3).optional(),
+    MINIO_ROOT_PASSWORD: z.string().min(8).optional(),
+    AUTH_JWT_SECRET: z.string().min(32),
+    AUTH_RATE_LIMIT_KEY_SECRET: z.string().min(32),
+    STORE_SECRET_ENCRYPTION_KEY: z.string().min(32),
+    STORE_SECRET_ENCRYPTION_KEY_VERSION: z
+        .string()
+        .min(1)
+        .max(64)
+        .default('v1'),
+    IDEMPOTENCY_KEY_SECRET: z.string().min(32),
+    AUTH_PASSWORD_MIN_LENGTH: z.coerce
+        .number()
+        .int()
+        .min(12)
+        .max(256)
+        .default(12),
+    API_BODY_LIMIT_BYTES: z.coerce
+        .number()
+        .int()
+        .min(1_024)
+        .max(10 * 1024 * 1024)
+        .default(1_048_576),
+    AUTH_RATE_LIMIT_WINDOW_SECONDS: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(86_400)
+        .default(900),
+    AUTH_LOGIN_IP_LIMIT: z.coerce.number().int().min(1).max(1000).default(10),
+    AUTH_LOGIN_EMAIL_LIMIT: z.coerce.number().int().min(1).max(1000).default(5),
+    AUTH_REGISTER_IP_LIMIT: z.coerce.number().int().min(1).max(1000).default(5),
+    AUTH_REGISTER_EMAIL_LIMIT: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .default(3),
+    AUTH_REFRESH_IP_LIMIT: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(10_000)
+        .default(30),
+    AUTH_CHANGE_PASSWORD_IP_LIMIT: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(1_000)
+        .default(10),
+    AUTH_CHANGE_PASSWORD_USER_LIMIT: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(1_000)
+        .default(5),
+    TRUSTED_PROXY_CIDRS: z.string().default(''),
+    SWAGGER_ENABLED: z.enum(['true', 'false']).default('true'),
+    LOG_LEVEL: z.enum(['error', 'warn', 'log', 'debug']).default('log'),
+});
+
+type Environment = z.infer<typeof environmentSchema>;
+export type AppConfig = Omit<
+    Environment,
+    'TRUSTED_PROXY_CIDRS' | 'SWAGGER_ENABLED'
+> & {
+    trustedProxyCidrs: string[];
+    swaggerEnabled: boolean;
+    objectStorageAccessKey: string;
+    objectStorageSecretKey: string;
+    objectStorageForcePathStyle: boolean;
+};
+
+function validateEnvironment(
+    environment: Record<string, unknown>,
+): Environment {
+    const result = environmentSchema.safeParse(environment);
+    if (result.success) return result.data;
+    // 在 Nest 开始监听前失败，避免半配置 API 对外提供不安全服务。
+    throw new Error(
+        `Invalid environment configuration: ${result.error.issues.map((issue) => issue.path.join('.')).join(', ')}`,
+    );
+}
+
+function createAppConfig(environment: Environment): AppConfig {
+    const objectStorageAccessKey =
+        environment.OBJECT_STORAGE_ACCESS_KEY ?? environment.MINIO_ROOT_USER;
+    const objectStorageSecretKey =
+        environment.OBJECT_STORAGE_SECRET_KEY ??
+        environment.MINIO_ROOT_PASSWORD;
+    if (!objectStorageAccessKey || !objectStorageSecretKey) {
+        throw new Error(
+            'OBJECT_STORAGE_ACCESS_KEY and OBJECT_STORAGE_SECRET_KEY are required',
+        );
+    }
+    return {
+        ...environment,
+        // 只有显式给出代理网段时才信任转发头，避免客户端伪造来源 IP。
+        trustedProxyCidrs: environment.TRUSTED_PROXY_CIDRS.split(',')
+            .map((value) => value.trim())
+            .filter(Boolean),
+        swaggerEnabled: environment.SWAGGER_ENABLED === 'true',
+        objectStorageAccessKey,
+        objectStorageSecretKey,
+        objectStorageForcePathStyle:
+            environment.OBJECT_STORAGE_FORCE_PATH_STYLE === 'true',
+    };
+}
+
+@Global()
+@Module({
+    imports: [
+        ConfigModule.forRoot({
+            isGlobal: true,
+            cache: true,
+            // Turbo 从 apps/api 运行脚本，但共享开发环境文件位于仓库根目录。
+            envFilePath: findEnvironmentFile(),
+        }),
+    ],
+    providers: [
+        {
+            provide: APP_CONFIG,
+            // 导出规范化配置，业务服务不得散落读取 process.env。
+            useFactory: (): AppConfig =>
+                createAppConfig(validateEnvironment(process.env)),
+        },
+    ],
+    exports: [APP_CONFIG],
+})
+export class AppConfigModule {}

apps/api/src/database/database.module.ts

@@ -0,0 +1,26 @@
+import { Global, Inject, Module, OnModuleDestroy } from '@nestjs/common';
+import { createApplicationDatabase, type Database } from '@atlas/database';
+import { APP_CONFIG, type AppConfig } from '../config/app-config.module.js';
+
+export const DATABASE = Symbol('DATABASE');
+
+@Global()
+@Module({
+    providers: [
+        {
+            provide: DATABASE,
+            inject: [APP_CONFIG],
+            // 业务代码只能拿到受限应用连接，迁移连接串绝不注入 API 容器。
+            useFactory: (config: AppConfig): Database =>
+                createApplicationDatabase(config.DATABASE_URL),
+        },
+    ],
+    exports: [DATABASE],
+})
+export class DatabaseModule implements OnModuleDestroy {
+    public constructor(@Inject(DATABASE) private readonly database: Database) {}
+    public async onModuleDestroy() {
+        // Nest 关闭时主动释放连接池，避免测试和热重启遗留连接。
+        await this.database.close();
+    }
+}

apps/api/src/logging/app-logger.ts

@@ -0,0 +1,62 @@
+import type { LoggerService } from '@nestjs/common';
+
+type LogLevel = 'error' | 'warn' | 'log' | 'debug';
+const severity: Record<LogLevel, number> = {
+    error: 0,
+    warn: 1,
+    log: 2,
+    debug: 3,
+};
+// 按字段名递归脱敏，日志中不得出现会话、密码、密钥或授权头原文。
+const sensitiveKeys = /authorization|cookie|password|secret|token|api[_-]?key/i;
+
+export class AppLogger implements LoggerService {
+    public constructor(private readonly minimumLevel: LogLevel) {}
+
+    public log(message: unknown, context?: unknown): void {
+        this.write('log', message, context);
+    }
+
+    public error(message: unknown, stack?: string, context?: unknown): void {
+        this.write('error', message, { stack, context });
+    }
+
+    public warn(message: unknown, context?: unknown): void {
+        this.write('warn', message, context);
+    }
+
+    public debug(message: unknown, context?: unknown): void {
+        this.write('debug', message, context);
+    }
+
+    public verbose(message: unknown, context?: unknown): void {
+        this.debug(message, context);
+    }
+
+    private write(level: LogLevel, message: unknown, context?: unknown): void {
+        if (severity[level] > severity[this.minimumLevel]) return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message: typeof message === 'string' ? message : sanitize(message),
+            context: sanitize(context),
+        };
+        // 每行独立 JSON，方便日志采集系统按字段索引 request_id、状态码等上下文。
+        const output = JSON.stringify(entry);
+        if (level === 'error') console.error(output);
+        else console.log(output);
+    }
+}
+
+function sanitize(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(sanitize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value).map(([key, child]) => [
+                key,
+                sensitiveKeys.test(key) ? '[REDACTED]' : sanitize(child),
+            ]),
+        );
+    }
+    return value;
+}

apps/api/src/main.ts

@@ -0,0 +1,144 @@
+import 'reflect-metadata';
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { NestFactory } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import type { NextFunction, Request, Response } from 'express';
+import helmet from 'helmet';
+
+import { AppModule } from './app.module.js';
+import { ApiErrorFilter } from './common/api-error.filter.js';
+import { APP_CONFIG, type AppConfig } from './config/app-config.module.js';
+import { AppLogger } from './logging/app-logger.js';
+
+type RequestWithId = Request & {
+    requestId?: string;
+};
+
+export async function createApplication() {
+    const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+        bodyParser: false,
+        // 自定义日志器安装前保留 Nest 启动日志，避免配置错误没有可见诊断。
+        logger: ['error', 'warn', 'log'],
+    });
+    const config = app.get<AppConfig>(APP_CONFIG);
+    const logger = new AppLogger(config.LOG_LEVEL);
+    app.useLogger(logger);
+
+    if (config.trustedProxyCidrs.length > 0) {
+        // 仅在部署明确声明代理网段时信任转发头，避免伪造客户端 IP。
+        app.getHttpAdapter()
+            .getInstance()
+            .set('trust proxy', config.trustedProxyCidrs);
+    }
+
+    app.enableCors({
+        origin: config.WEB_ORIGIN,
+        credentials: true,
+        methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+        allowedHeaders: [
+            'Authorization',
+            'Content-Type',
+            'Idempotency-Key',
+            'If-Match',
+            'X-Atlas-Platform-Id',
+            'X-Request-Id',
+        ],
+        exposedHeaders: ['X-Request-Id'],
+    });
+    // Helmet、body 限制、请求 ID 与全局错误过滤器必须在业务路由前注册。
+    app.use(helmet({ contentSecurityPolicy: false }));
+    app.useBodyParser('json', { limit: config.API_BODY_LIMIT_BYTES });
+    app.useBodyParser('urlencoded', {
+        limit: config.API_BODY_LIMIT_BYTES,
+        extended: true,
+    });
+    app.use(
+        (request: RequestWithId, response: Response, next: NextFunction) => {
+            const typedRequest = request;
+            const typedResponse = response;
+            const suppliedId = typedRequest.headers['x-request-id'];
+            // 合法调用方提供的 request ID 可贯穿上游链路；其他情况由服务端生成。
+            const requestId =
+                typeof suppliedId === 'string' &&
+                /^[A-Za-z0-9_-]{8,128}$/.test(suppliedId)
+                    ? suppliedId
+                    : `req_${randomUUID()}`;
+            const startedAt = performance.now();
+            typedRequest.requestId = requestId;
+            typedResponse.setHeader('X-Request-Id', requestId);
+            typedResponse.on('finish', () => {
+                logger.log('http_request_completed', {
+                    request_id: requestId,
+                    method: typedRequest.method,
+                    path: typedRequest.originalUrl,
+                    status_code: typedResponse.statusCode,
+                    duration_ms: Math.round(performance.now() - startedAt),
+                });
+            });
+            next();
+        },
+    );
+    app.useGlobalFilters(new ApiErrorFilter(logger));
+    app.setGlobalPrefix('api', { exclude: ['health', 'ready'] });
+    app.enableShutdownHooks();
+
+    if (config.swaggerEnabled) {
+        // Swagger 仅描述运行时已注册路由；冻结接口契约仍以 docs/api 为准。
+        const swaggerConfig = new DocumentBuilder()
+            .setTitle('Atlas Seller Kit API')
+            .setDescription('Atlas 卖家工作台 HTTP API 文档')
+            .setVersion('0.1.0')
+            .addBearerAuth(
+                { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+                'access-token',
+            )
+            .build();
+        const swaggerDocument = SwaggerModule.createDocument(
+            app,
+            swaggerConfig,
+        );
+        SwaggerModule.setup('api-docs', app, swaggerDocument, {
+            swaggerOptions: { persistAuthorization: true },
+        });
+    }
+
+    return { app, config, logger };
+}
+
+export async function bootstrap() {
+    const { app, config, logger } = await createApplication();
+    await app.listen(config.API_PORT);
+    logger.log('api_started', {
+        port: config.API_PORT,
+        swagger_enabled: config.swaggerEnabled,
+    });
+}
+
+// 测试复用应用工厂时不自动监听固定端口，只有直接运行入口才启动服务。
+if (
+    process.argv[1] &&
+    resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+    void bootstrap().catch((error: unknown) => {
+        const details =
+            error instanceof Error
+                ? {
+                      name: error.name,
+                      message: error.message,
+                      stack: error.stack,
+                  }
+                : error;
+        console.error(
+            JSON.stringify({
+                timestamp: new Date().toISOString(),
+                level: 'error',
+                message: 'api_startup_failed',
+                error: details,
+            }),
+        );
+        process.exitCode = 1;
+    });
+}

apps/api/src/media/media.controller.ts

@@ -0,0 +1,132 @@
+import {
+    Body,
+    Controller,
+    Headers,
+    Inject,
+    Param,
+    Post,
+    Req,
+} from '@nestjs/common';
+import {
+    ApiBearerAuth,
+    ApiCreatedResponse,
+    ApiOkResponse,
+    ApiTags,
+} from '@nestjs/swagger';
+import {
+    completeMediaUploadIntentRequestSchema,
+    createMediaAccessUrlRequestSchema,
+    createMediaUploadIntentRequestSchema,
+    type Workspace,
+} from '@atlas/contracts';
+import { z } from 'zod';
+import { ApiError } from '../common/api-error.js';
+import type { AuthenticatedRequest } from '../auth/auth.guard.js';
+import { CurrentWorkspace } from '../workspace/current-workspace.decorator.js';
+import { MediaService } from './media.service.js';
+
+@ApiTags('Media')
+@ApiBearerAuth('access-token')
+@Controller()
+export class MediaController {
+    public constructor(
+        @Inject(MediaService) private readonly media: MediaService,
+    ) {}
+
+    @Post('media/upload-intents')
+    @ApiCreatedResponse({ description: '已创建一次性预签名上传意图' })
+    public async createIntent(
+        @Body() body: unknown,
+        @Headers('idempotency-key') key: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        return (
+            await this.media.createIntent(
+                workspace.id,
+                request.auth.userId,
+                idempotencyKey(key),
+                parse(createMediaUploadIntentRequestSchema, body),
+            )
+        ).body;
+    }
+
+    @Post('media/upload-intents/:uploadId/complete')
+    @ApiCreatedResponse({ description: '已完成对象安全校验并创建素材' })
+    public async complete(
+        @Param('uploadId') uploadId: string,
+        @Body() body: unknown,
+        @Headers('idempotency-key') key: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        return (
+            await this.media.completeIntent(
+                workspace.id,
+                request.auth.userId,
+                uuid('upload_id', uploadId),
+                idempotencyKey(key),
+                parse(completeMediaUploadIntentRequestSchema, body),
+            )
+        ).body;
+    }
+
+    @Post('media-assets/:assetId/access-urls')
+    @ApiOkResponse({ description: '已签发短时预览 URL' })
+    public async accessUrl(
+        @Param('assetId') assetId: string,
+        @Body() body: unknown,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        parse(createMediaAccessUrlRequestSchema, body);
+        return {
+            data: await this.media.accessUrl(
+                workspace.id,
+                uuid('asset_id', assetId),
+            ),
+        };
+    }
+}
+
+function parse<
+    T extends {
+        safeParse: (input: unknown) => {
+            success: boolean;
+            data?: unknown;
+            error?: { issues: Array<{ path: PropertyKey[]; message: string }> };
+        };
+    },
+>(schema: T, input: unknown) {
+    const result = schema.safeParse(input);
+    if (result.success)
+        return result.data as ReturnType<T['safeParse']> extends {
+            data: infer Data;
+        }
+            ? Data
+            : never;
+    throw new ApiError(
+        422,
+        'VALIDATION_FAILED',
+        '请求参数不符合要求',
+        result.error?.issues.map((issue) => ({
+            field: issue.path.join('.'),
+            code: 'INVALID_FIELD',
+            message: issue.message,
+        })),
+    );
+}
+function uuid(field: string, value: string) {
+    if (z.uuid().safeParse(value).success) return value;
+    throw new ApiError(422, 'VALIDATION_FAILED', '请求参数不符合要求', [
+        { field, code: 'INVALID_FIELD', message: `${field} 必须是 UUID` },
+    ]);
+}
+function idempotencyKey(value: string | undefined) {
+    if (!value)
+        throw new ApiError(
+            400,
+            'IDEMPOTENCY_KEY_REQUIRED',
+            '请求缺少 Idempotency-Key',
+        );
+    return uuid('Idempotency-Key', value);
+}

apps/api/src/media/media.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { IdempotencyService } from '../common/idempotency.service.js';
+import { MediaController } from './media.controller.js';
+import { MediaService } from './media.service.js';
+
+@Module({
+    controllers: [MediaController],
+    providers: [IdempotencyService, MediaService],
+    exports: [MediaService],
+})
+export class MediaModule {}

apps/api/src/media/media.service.ts

@@ -0,0 +1,537 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+    CreateBucketCommand,
+    GetObjectCommand,
+    HeadBucketCommand,
+    HeadObjectCommand,
+    PutObjectCommand,
+    S3Client,
+} from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { Inject, Injectable } from '@nestjs/common';
+import type {
+    CompleteMediaUploadIntentRequest,
+    CreateMediaUploadIntentRequest,
+} 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';
+
+type IntentRow = {
+    id: string;
+    storage_provider: string;
+    bucket: string;
+    object_key: string;
+    expected_content_type: string;
+    expected_byte_size: string;
+    expected_checksum_sha256: string;
+    status: 'pending' | 'ready' | 'failed' | 'expired';
+    expires_at: Date | string;
+    asset_id: string | null;
+};
+type AssetRow = {
+    id: string;
+    content_type: string;
+    byte_size: string;
+    width_px: number | null;
+    height_px: number | null;
+    created_at: Date | string;
+};
+
+@Injectable()
+export class MediaService {
+    private readonly s3: S3Client;
+    private bucketReady: Promise<void> | null = null;
+
+    public constructor(
+        @Inject(IdempotencyService)
+        private readonly idempotency: IdempotencyService,
+        @Inject(DATABASE) private readonly database: Database,
+        @Inject(APP_CONFIG) private readonly config: AppConfig,
+    ) {
+        this.s3 = new S3Client({
+            endpoint: config.OBJECT_STORAGE_ENDPOINT,
+            region: 'us-east-1',
+            forcePathStyle: config.objectStorageForcePathStyle,
+            credentials: {
+                accessKeyId: config.objectStorageAccessKey,
+                secretAccessKey: config.objectStorageSecretKey,
+            },
+        });
+    }
+
+    public async createIntent(
+        workspaceId: string,
+        userId: string,
+        key: string,
+        input: CreateMediaUploadIntentRequest,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'POST',
+                path: '/api/media/upload-intents',
+                key,
+                request: input,
+            },
+            async (tx) => {
+                await this.ensureBucket();
+                const id = randomUUID();
+                const objectKey = `uploads/${workspaceId}/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)`,
+                    [
+                        id,
+                        this.config.OBJECT_STORAGE_BUCKET,
+                        objectKey,
+                        input.content_type,
+                        input.byte_size,
+                        input.checksum_sha256,
+                        expiresAt,
+                        userId,
+                    ],
+                );
+                const url = await getSignedUrl(
+                    this.s3,
+                    new PutObjectCommand({
+                        Bucket: this.config.OBJECT_STORAGE_BUCKET,
+                        Key: objectKey,
+                        ContentType: input.content_type,
+                    }),
+                    { expiresIn: 600 },
+                );
+                return {
+                    status: 201,
+                    body: {
+                        data: {
+                            upload_id: id,
+                            expires_at: expiresAt.toISOString(),
+                            upload: {
+                                method: 'PUT',
+                                url,
+                                headers: { 'content-type': input.content_type },
+                            },
+                        },
+                    },
+                };
+            },
+        );
+    }
+
+    public async completeIntent(
+        workspaceId: string,
+        userId: string,
+        intentId: string,
+        key: string,
+        input: CompleteMediaUploadIntentRequest,
+    ) {
+        try {
+            return await this.idempotency.run(
+                {
+                    workspaceId,
+                    userId,
+                    method: 'POST',
+                    path: `/api/media/upload-intents/${intentId}/complete`,
+                    key,
+                    request: input,
+                },
+                async (tx) => {
+                    const intent = await this.lockIntent(tx, intentId);
+                    if (intent.status === 'ready' && intent.asset_id) {
+                        return {
+                            status: 201,
+                            body: {
+                                data: {
+                                    asset: await this.requireAsset(
+                                        tx,
+                                        intent.asset_id,
+                                    ),
+                                },
+                            },
+                        };
+                    }
+                    if (intent.status === 'failed') {
+                        throw new ApiError(
+                            422,
+                            'UPLOAD_VALIDATION_FAILED',
+                            '该上传意图的文件未通过安全校验，请重新上传',
+                        );
+                    }
+                    if (intent.status === 'expired') {
+                        throw new ApiError(
+                            422,
+                            'UPLOAD_EXPIRED',
+                            '上传意图已过期，请重新发起上传',
+                        );
+                    }
+                    if (new Date(intent.expires_at).getTime() <= Date.now()) {
+                        throw new ApiError(
+                            422,
+                            'UPLOAD_EXPIRED',
+                            '上传意图已过期，请重新发起上传',
+                        );
+                    }
+                    if (
+                        input.checksum_sha256 !==
+                        intent.expected_checksum_sha256
+                    ) {
+                        throw new ApiError(
+                            422,
+                            'UPLOAD_CHECKSUM_MISMATCH',
+                            '完成请求的文件摘要与上传意图不一致',
+                        );
+                    }
+                    const inspected = await this.inspectObject(intent);
+                    if (
+                        inspected.byteSize !==
+                            Number(intent.expected_byte_size) ||
+                        inspected.checksum !==
+                            intent.expected_checksum_sha256 ||
+                        inspected.contentType !== intent.expected_content_type
+                    ) {
+                        throw new ApiError(
+                            422,
+                            'UPLOAD_VALIDATION_FAILED',
+                            '上传文件未通过安全校验',
+                        );
+                    }
+                    const existing = await tx.query<{ id: string }>(
+                        `SELECT id FROM atlas.media_assets WHERE checksum_sha256 = $1`,
+                        [inspected.checksum],
+                    );
+                    const assetId = existing.rows[0]?.id ?? randomUUID();
+                    if (!existing.rows[0]) {
+                        await tx.query(
+                            `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)`,
+                            [
+                                assetId,
+                                intent.bucket,
+                                intent.object_key,
+                                inspected.contentType,
+                                inspected.byteSize,
+                                inspected.checksum,
+                                inspected.width,
+                                inspected.height,
+                            ],
+                        );
+                    }
+                    await tx.query(
+                        `UPDATE atlas.media_upload_intents SET status = 'ready', asset_id = $2,
+                    completed_at = now(), error_code = NULL, error_message = NULL WHERE id = $1`,
+                        [intentId, assetId],
+                    );
+                    return {
+                        status: 201,
+                        body: {
+                            data: {
+                                asset: await this.requireAsset(tx, assetId),
+                            },
+                        },
+                    };
+                },
+            );
+        } catch (error) {
+            const code = apiErrorCode(error);
+            if (
+                code === 'UPLOAD_EXPIRED' ||
+                code === 'UPLOAD_OBJECT_MISSING' ||
+                code === 'UPLOAD_VALIDATION_FAILED'
+            ) {
+                await this.persistTerminalIntentStatus(
+                    workspaceId,
+                    intentId,
+                    code,
+                );
+            }
+            throw error;
+        }
+    }
+
+    public async accessUrl(workspaceId: string, assetId: string) {
+        return this.database.workspaceTransaction(workspaceId, async (tx) => {
+            const asset = await tx.query<{
+                bucket: string;
+                object_key: string;
+            }>(
+                `SELECT bucket, object_key FROM atlas.media_assets WHERE id = $1`,
+                [assetId],
+            );
+            if (!asset.rows[0])
+                throw new ApiError(404, 'RESOURCE_NOT_FOUND', '素材不存在');
+            const expiresAt = new Date(Date.now() + 10 * 60_000);
+            const url = await getSignedUrl(
+                this.s3,
+                new GetObjectCommand({
+                    Bucket: asset.rows[0].bucket,
+                    Key: asset.rows[0].object_key,
+                }),
+                { expiresIn: 600 },
+            );
+            return { url, expires_at: expiresAt.toISOString() };
+        });
+    }
+
+    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,
+             expected_checksum_sha256, status, expires_at, asset_id
+             FROM atlas.media_upload_intents WHERE id = $1 FOR UPDATE`,
+            [intentId],
+        );
+        if (!rows.rows[0])
+            throw new ApiError(404, 'RESOURCE_NOT_FOUND', '上传意图不存在');
+        return rows.rows[0];
+    }
+
+    private async requireAsset(tx: DatabaseTransaction, assetId: string) {
+        const rows = await tx.query<AssetRow>(
+            `SELECT id, content_type, byte_size, width_px, height_px, created_at
+             FROM atlas.media_assets WHERE id = $1`,
+            [assetId],
+        );
+        if (!rows.rows[0])
+            throw new ApiError(404, 'RESOURCE_NOT_FOUND', '素材不存在');
+        const asset = rows.rows[0];
+        return {
+            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,
+        };
+    }
+
+    private async inspectObject(intent: IntentRow) {
+        let head;
+        try {
+            head = await this.s3.send(
+                new HeadObjectCommand({
+                    Bucket: intent.bucket,
+                    Key: intent.object_key,
+                }),
+            );
+        } catch {
+            throw new ApiError(
+                422,
+                'UPLOAD_OBJECT_MISSING',
+                '尚未找到已上传文件',
+            );
+        }
+        if (!head.ContentLength || head.ContentLength > 5 * 1024 * 1024) {
+            throw new ApiError(
+                422,
+                'UPLOAD_VALIDATION_FAILED',
+                '上传文件大小不符合要求',
+            );
+        }
+        const declaredContentType = head.ContentType?.split(
+            ';',
+            1,
+        )[0]?.toLowerCase();
+        if (declaredContentType !== intent.expected_content_type) {
+            throw new ApiError(
+                422,
+                'UPLOAD_VALIDATION_FAILED',
+                '上传文件声明类型不符合要求',
+            );
+        }
+        const object = await this.s3.send(
+            new GetObjectCommand({
+                Bucket: intent.bucket,
+                Key: intent.object_key,
+            }),
+        );
+        if (!object.Body)
+            throw new ApiError(
+                422,
+                'UPLOAD_OBJECT_MISSING',
+                '尚未找到已上传文件',
+            );
+        const chunks: Buffer[] = [];
+        let byteSize = 0;
+        for await (const chunk of object.Body as AsyncIterable<Uint8Array>) {
+            byteSize += chunk.byteLength;
+            // HeadObject 和 GetObject 之间对象可能被替换；读取时也必须有硬上限。
+            if (byteSize > 5 * 1024 * 1024) {
+                throw new ApiError(
+                    422,
+                    'UPLOAD_VALIDATION_FAILED',
+                    '上传文件大小不符合要求',
+                );
+            }
+            chunks.push(Buffer.from(chunk));
+        }
+        const bytes = Buffer.concat(chunks, byteSize);
+        const detected = detectImage(bytes);
+        if (
+            !detected ||
+            detected.contentType !== intent.expected_content_type
+        ) {
+            throw new ApiError(
+                422,
+                'UPLOAD_VALIDATION_FAILED',
+                '上传文件类型或内容不符合要求',
+            );
+        }
+        return {
+            contentType: detected.contentType,
+            width: detected.width,
+            height: detected.height,
+            byteSize,
+            checksum: createHash('sha256').update(bytes).digest('hex'),
+        };
+    }
+
+    private async ensureBucket() {
+        if (!this.bucketReady)
+            this.bucketReady = (async () => {
+                try {
+                    await this.s3.send(
+                        new HeadBucketCommand({
+                            Bucket: this.config.OBJECT_STORAGE_BUCKET,
+                        }),
+                    );
+                } catch {
+                    await this.s3.send(
+                        new CreateBucketCommand({
+                            Bucket: this.config.OBJECT_STORAGE_BUCKET,
+                        }),
+                    );
+                }
+            })();
+        return this.bucketReady;
+    }
+
+    private async persistTerminalIntentStatus(
+        workspaceId: string,
+        intentId: string,
+        code:
+            | 'UPLOAD_EXPIRED'
+            | 'UPLOAD_OBJECT_MISSING'
+            | 'UPLOAD_VALIDATION_FAILED',
+    ) {
+        await this.database.workspaceTransaction(workspaceId, async (tx) => {
+            const expired = code === 'UPLOAD_EXPIRED';
+            await tx.query(
+                `UPDATE atlas.media_upload_intents
+                 SET status = $2, error_code = $3, error_message = $4, completed_at = now()
+                 WHERE id = $1 AND status = 'pending'`,
+                [
+                    intentId,
+                    expired ? 'expired' : 'failed',
+                    code,
+                    expired ? '上传意图已过期' : '上传文件未通过安全校验',
+                ],
+            );
+        });
+    }
+}
+
+function apiErrorCode(error: unknown): string | undefined {
+    if (!(error instanceof ApiError)) return undefined;
+    const response = error.getResponse();
+    if (typeof response !== 'object' || !response || !('error' in response))
+        return undefined;
+    const apiError = response.error;
+    return typeof apiError === 'object' &&
+        apiError &&
+        'code' in apiError &&
+        typeof apiError.code === 'string'
+        ? 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;
+}

apps/api/src/security/auth-rate-limiter.service.ts

@@ -0,0 +1,131 @@
+import {
+    Inject,
+    Injectable,
+    OnModuleDestroy,
+    OnModuleInit,
+} from '@nestjs/common';
+import { createHmac } from 'node:crypto';
+import { Redis } from 'ioredis';
+import { ApiError } from '../common/api-error.js';
+import { APP_CONFIG, type AppConfig } from '../config/app-config.module.js';
+
+type AuthAction = 'login' | 'register' | 'refresh' | 'change_password';
+type Limit = { ip: number; email?: number; user?: number };
+
+@Injectable()
+export class AuthRateLimiter implements OnModuleInit, OnModuleDestroy {
+    private readonly redis: Redis;
+
+    public constructor(@Inject(APP_CONFIG) private readonly config: AppConfig) {
+        // Redis 让限流计数在多个 API 实例间共享，不会随单个实例重启清零。
+        this.redis = new Redis(config.REDIS_URL, {
+            enableOfflineQueue: false,
+            lazyConnect: true,
+            maxRetriesPerRequest: 1,
+        });
+    }
+
+    public async onModuleInit(): Promise<void> {
+        // 在开始接收认证请求前完成连接，避免首个请求命中 Redis 连接竞态而被误判为 503。
+        await this.redis.connect();
+    }
+
+    public async consume(
+        action: AuthAction,
+        identifiers: { ip: string | null; email?: string; userId?: string },
+    ): Promise<void> {
+        const limit = this.limitFor(action);
+        await this.consumeBucket(
+            action,
+            'ip',
+            identifiers.ip ?? 'unknown',
+            limit.ip,
+        );
+        if (identifiers.email && limit.email) {
+            await this.consumeBucket(
+                action,
+                'email',
+                identifiers.email,
+                limit.email,
+            );
+        }
+        if (identifiers.userId && limit.user) {
+            await this.consumeBucket(
+                action,
+                'user',
+                identifiers.userId,
+                limit.user,
+            );
+        }
+    }
+
+    public async onModuleDestroy(): Promise<void> {
+        if (this.redis.status !== 'ready') {
+            this.redis.disconnect();
+            return;
+        }
+        await this.redis.quit();
+    }
+
+    private async consumeBucket(
+        action: AuthAction,
+        dimension: 'ip' | 'email' | 'user',
+        identifier: string,
+        limit: number,
+    ): Promise<void> {
+        const digest = createHmac(
+            'sha256',
+            this.config.AUTH_RATE_LIMIT_KEY_SECRET,
+        )
+            .update(identifier)
+            .digest('base64url');
+        // Redis key 只保存 IP/邮箱的 HMAC，不暴露可被日志或运维工具读取的原文。
+        const key = `atlas:auth-rate-limit:${action}:${dimension}:${digest}`;
+        try {
+            // INCR 与首次 EXPIRE 必须原子执行，避免并发下产生永不过期的限流 key。
+            const count = await this.redis.eval(
+                "local value = redis.call('INCR', KEYS[1]); if value == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]); end; return value;",
+                1,
+                key,
+                this.config.AUTH_RATE_LIMIT_WINDOW_SECONDS,
+            );
+            if (Number(count) > limit) {
+                throw new ApiError(
+                    429,
+                    'AUTH_RATE_LIMITED',
+                    '请求过于频繁，请稍后重试',
+                );
+            }
+        } catch (error) {
+            if (error instanceof ApiError) throw error;
+            // 认证限流故障时必须拒绝请求；静默跳过会扩大暴力破解风险。
+            throw new ApiError(
+                503,
+                'AUTH_RATE_LIMIT_UNAVAILABLE',
+                '认证服务暂时不可用',
+            );
+        }
+    }
+
+    private limitFor(action: AuthAction): Limit {
+        if (action === 'login') {
+            return {
+                ip: this.config.AUTH_LOGIN_IP_LIMIT,
+                email: this.config.AUTH_LOGIN_EMAIL_LIMIT,
+            };
+        }
+        if (action === 'register') {
+            return {
+                ip: this.config.AUTH_REGISTER_IP_LIMIT,
+                email: this.config.AUTH_REGISTER_EMAIL_LIMIT,
+            };
+        }
+        if (action === 'change_password') {
+            return {
+                ip: this.config.AUTH_CHANGE_PASSWORD_IP_LIMIT,
+                user: this.config.AUTH_CHANGE_PASSWORD_USER_LIMIT,
+            };
+        }
+        return { ip: this.config.AUTH_REFRESH_IP_LIMIT };
+    }
+}

apps/api/src/security/security.module.ts

@@ -0,0 +1,6 @@
+import { Global, Module } from '@nestjs/common';
+import { AuthRateLimiter } from './auth-rate-limiter.service.js';
+
+@Global()
+@Module({ providers: [AuthRateLimiter], exports: [AuthRateLimiter] })
+export class SecurityModule {}

apps/api/src/stores/platforms.service.ts

@@ -0,0 +1,130 @@
+import { Inject, Injectable } from '@nestjs/common';
+import type { Database, DatabaseTransaction } from '@atlas/database';
+import { ApiError } from '../common/api-error.js';
+import { DATABASE } from '../database/database.module.js';
+
+type PlatformRow = {
+    id: string;
+    code: string;
+    name: string;
+    capabilities: Record<string, unknown>;
+    supported_currencies: string[];
+};
+
+@Injectable()
+export class PlatformsService {
+    public constructor(@Inject(DATABASE) private readonly database: Database) {}
+
+    public async list() {
+        const rows = await this.database.query<PlatformRow>(
+            `SELECT p.id, p.code, p.name, p.capabilities,
+                    coalesce(array_agg(pcs.currency_code ORDER BY pcs.currency_code)
+                        FILTER (WHERE pcs.is_enabled AND c.is_enabled), ARRAY[]::char(3)[]) AS supported_currencies
+             FROM atlas.platforms p
+             LEFT JOIN atlas.platform_currency_support pcs ON pcs.platform_id = p.id
+             LEFT JOIN atlas.currencies c ON c.code = pcs.currency_code
+             WHERE p.status = 'active'
+               AND coalesce((p.capabilities->>'can_be_header_context')::boolean, false)
+             GROUP BY p.id
+             ORDER BY CASE WHEN p.code = 'OZON' THEN 0 ELSE 1 END, p.name`,
+        );
+        return rows.rows.map((platform) => ({
+            id: platform.id,
+            code: platform.code,
+            name: platform.name,
+            supported_currencies: platform.supported_currencies,
+            // 能力未配置时使用 null，而不是把 Ozon 的市场或语言假设扩散到通用模型。
+            default_market_code: stringCapability(
+                platform.capabilities,
+                'default_market_code',
+            ),
+            default_locale: stringCapability(
+                platform.capabilities,
+                'default_locale',
+            ),
+            default_currency_code: stringCapability(
+                platform.capabilities,
+                'default_currency_code',
+            ),
+        }));
+    }
+
+    public async context(workspaceId: string, platformId: string) {
+        return this.database.workspaceTransaction(
+            workspaceId,
+            async (transaction) => {
+                const platform = await this.requireActivePlatform(
+                    transaction,
+                    platformId,
+                );
+                const stores = await transaction.query<{
+                    id: string;
+                    name: string;
+                    status: string;
+                    credential_status: string;
+                    count: string;
+                }>(
+                    `SELECT s.id, s.name, s.status, s.credential_status,
+                            count(*) OVER ()::text AS count
+                     FROM atlas.stores s
+                     WHERE s.platform_id = $1 AND s.deleted_at IS NULL AND s.is_default
+                     LIMIT 1`,
+                    [platformId],
+                );
+                // 默认门店不存在时仍要正确返回总数，不能用默认行的窗口函数猜测。
+                const count = await transaction.query<{ count: string }>(
+                    `SELECT count(*)::text AS count FROM atlas.stores
+                     WHERE platform_id = $1 AND deleted_at IS NULL`,
+                    [platformId],
+                );
+                const defaultStore = stores.rows[0];
+                return {
+                    platform: {
+                        id: platform.id,
+                        code: platform.code,
+                        name: platform.name,
+                    },
+                    default_store: defaultStore
+                        ? {
+                              id: defaultStore.id,
+                              name: defaultStore.name,
+                              status: defaultStore.status,
+                              credential_status: defaultStore.credential_status,
+                          }
+                        : null,
+                    store_count: Number(count.rows[0]?.count ?? 0),
+                };
+            },
+        );
+    }
+
+    private async requireActivePlatform(
+        transaction: DatabaseTransaction,
+        platformId: string,
+    ) {
+        const rows = await transaction.query<{
+            id: string;
+            code: string;
+            name: string;
+        }>(
+            `SELECT id, code, name FROM atlas.platforms WHERE id = $1 AND status = 'active'`,
+            [platformId],
+        );
+        if (!rows.rows[0]) {
+            throw new ApiError(
+                422,
+                'PLATFORM_UNAVAILABLE',
+                '平台不存在或已停用',
+            );
+        }
+        return rows.rows[0];
+    }
+}
+
+function stringCapability(
+    capabilities: Record<string, unknown>,
+    key: string,
+): string | null {
+    const value = capabilities[key];
+    return typeof value === 'string' ? value : null;
+}

apps/api/src/stores/store-secret.crypto.ts

@@ -0,0 +1,58 @@
+import {
+    createDecipheriv,
+    createCipheriv,
+    createHash,
+    createHmac,
+    randomBytes,
+} from 'node:crypto';
+
+export type EncryptedStoreSecret = {
+    ciphertext: Buffer;
+    nonce: Buffer;
+    fingerprint: string;
+};
+
+/**
+ * 密钥只在此边界短暂以明文存在。数据库保存 AES-GCM 密文和随机 nonce，
+ * fingerprint 是不可逆 HMAC，仅用于安全地识别同一份密钥。
+ */
+export function encryptStoreSecret(
+    plaintext: string,
+    keyMaterial: string,
+): EncryptedStoreSecret {
+    const key = createHash('sha256').update(keyMaterial).digest();
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+        cipher.getAuthTag(),
+    ]);
+    return {
+        ciphertext,
+        nonce,
+        fingerprint: createHmac('sha256', key)
+            .update(plaintext)
+            .digest('base64url'),
+    };
+}
+
+/** 仅供受信任的后台 Worker 使用；调用方不得记录返回值。 */
+export function decryptStoreSecret(
+    ciphertextWithTag: Buffer,
+    nonce: Buffer,
+    keyMaterial: string,
+): string {
+    const authenticationTagLength = 16;
+    if (ciphertextWithTag.length <= authenticationTagLength) {
+        throw new Error('Invalid encrypted store secret');
+    }
+    const key = createHash('sha256').update(keyMaterial).digest();
+    const ciphertext = ciphertextWithTag.subarray(0, -authenticationTagLength);
+    const tag = ciphertextWithTag.subarray(-authenticationTagLength);
+    const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString(
+        'utf8',
+    );
+}

apps/api/src/stores/stores.controller.ts

@@ -0,0 +1,340 @@
+import {
+    Body,
+    Controller,
+    Delete,
+    Get,
+    Headers,
+    HttpCode,
+    Inject,
+    Param,
+    Patch,
+    Post,
+    Query,
+    Req,
+    Res,
+} from '@nestjs/common';
+import {
+    ApiAcceptedResponse,
+    ApiBearerAuth,
+    ApiNoContentResponse,
+    ApiOkResponse,
+    ApiOperation,
+    ApiTags,
+} from '@nestjs/swagger';
+import {
+    createStoreRequestSchema,
+    listStoresQuerySchema,
+    updateStoreRequestSchema,
+} from '@atlas/contracts';
+import { z } from 'zod';
+import { ApiError } from '../common/api-error.js';
+import type { AuthenticatedRequest } from '../auth/auth.guard.js';
+import { CurrentWorkspace } from '../workspace/current-workspace.decorator.js';
+import type { Workspace } from '@atlas/contracts';
+import { PlatformsService } from './platforms.service.js';
+import { StoresService } from './stores.service.js';
+
+type HttpResponse = { status: (status: number) => HttpResponse };
+
+@ApiTags('Platforms')
+@ApiBearerAuth('access-token')
+@Controller()
+export class PlatformsController {
+    // tsx/esbuild 不生成 design:paramtypes 元数据，控制器依赖必须显式 @Inject（与 auth.controller 一致）
+    public constructor(
+        @Inject(PlatformsService)
+        private readonly platformsService: PlatformsService,
+    ) {}
+
+    @Get('platforms')
+    @ApiOperation({ summary: '获取已启用的平台及非敏感能力目录' })
+    @ApiOkResponse({ description: '平台目录' })
+    public async list() {
+        return { data: await this.platformsService.list() };
+    }
+
+    @Get('platform-context')
+    @ApiOperation({ summary: '获取页头所选平台的默认门店上下文' })
+    @ApiOkResponse({ description: '平台、默认门店和门店总数' })
+    public async context(
+        @Headers('x-atlas-platform-id') platformId: string | undefined,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        if (!platformId) {
+            throw new ApiError(
+                400,
+                'PLATFORM_CONTEXT_REQUIRED',
+                '请求缺少 X-Atlas-Platform-Id',
+            );
+        }
+        return {
+            data: await this.platformsService.context(
+                workspace.id,
+                requireUuid('X-Atlas-Platform-Id', platformId),
+            ),
+        };
+    }
+}
+
+@ApiTags('Stores')
+@ApiBearerAuth('access-token')
+@Controller('stores')
+export class StoresController {
+    public constructor(
+        @Inject(StoresService) private readonly storesService: StoresService,
+    ) {}
+
+    @Get()
+    @ApiOperation({ summary: '按平台分页列出当前工作空间的门店' })
+    @ApiOkResponse({ description: '门店列表与不透明游标' })
+    public async list(
+        @Query() query: unknown,
+        @Headers('x-atlas-platform-id') platformHeader: string | undefined,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        if (platformHeader) {
+            throw new ApiError(
+                400,
+                'PLATFORM_CONTEXT_CONFLICT',
+                '门店管理列表不能同时使用平台 header 和 platform_id 查询参数',
+            );
+        }
+        return this.storesService.list(
+            workspace.id,
+            parse(listStoresQuerySchema, query),
+        );
+    }
+
+    @Get(':storeId')
+    @ApiOperation({ summary: '读取单个门店' })
+    public async get(
+        @Param('storeId') storeId: string,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        return {
+            data: await this.storesService.get(
+                workspace.id,
+                requireUuid('store_id', storeId),
+            ),
+        };
+    }
+
+    @Post()
+    @ApiOperation({ summary: '创建门店连接，并请求异步凭据验证' })
+    @ApiAcceptedResponse({ description: '已加密保存凭据，并创建验证操作' })
+    public async create(
+        @Body() body: unknown,
+        @Headers('idempotency-key') idempotencyKey: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        return withStatus(
+            response,
+            await this.storesService.create(
+                workspace.id,
+                request.auth.userId,
+                requireIdempotencyKey(idempotencyKey),
+                parse(createStoreRequestSchema, body),
+            ),
+        );
+    }
+
+    @Patch(':storeId')
+    @ApiOperation({ summary: '按版本编辑门店；更新密钥会重新请求验证' })
+    @ApiOkResponse({ description: '普通字段已更新' })
+    @ApiAcceptedResponse({ description: '新密钥已保存，并创建验证操作' })
+    public async update(
+        @Param('storeId') storeId: string,
+        @Body() body: unknown,
+        @Headers('idempotency-key') idempotencyKey: string | undefined,
+        @Headers('if-match') ifMatch: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        return withStatus(
+            response,
+            await this.storesService.update(
+                workspace.id,
+                request.auth.userId,
+                requireUuid('store_id', storeId),
+                requireIdempotencyKey(idempotencyKey),
+                parseRevision(ifMatch),
+                parse(updateStoreRequestSchema, body),
+            ),
+        );
+    }
+
+    @Post(':storeId/set-default')
+    @ApiOperation({ summary: '设为当前平台默认门店' })
+    public async setDefault(
+        @Param('storeId') storeId: string,
+        @Headers('idempotency-key') idempotencyKey: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        return withStatus(
+            response,
+            await this.storesService.setDefault(
+                workspace.id,
+                request.auth.userId,
+                requireUuid('store_id', storeId),
+                requireIdempotencyKey(idempotencyKey),
+            ),
+        );
+    }
+
+    @Post(':storeId/credential-verifications')
+    @ApiOperation({ summary: '手动请求重新验证门店凭据' })
+    @ApiAcceptedResponse({ description: '凭据验证操作已入队' })
+    public async credentialVerification(
+        @Param('storeId') storeId: string,
+        @Headers('idempotency-key') idempotencyKey: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        return withStatus(
+            response,
+            await this.storesService.requestCredentialVerification(
+                workspace.id,
+                request.auth.userId,
+                requireUuid('store_id', storeId),
+                requireIdempotencyKey(idempotencyKey),
+            ),
+        );
+    }
+
+    @Post(':storeId/warehouse-syncs')
+    @ApiOperation({ summary: '请求异步同步门店仓库' })
+    @ApiAcceptedResponse({ description: '仓库同步操作已入队' })
+    public async warehouseSync(
+        @Param('storeId') storeId: string,
+        @Headers('idempotency-key') idempotencyKey: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        return withStatus(
+            response,
+            await this.storesService.requestWarehouseSync(
+                workspace.id,
+                request.auth.userId,
+                requireUuid('store_id', storeId),
+                requireIdempotencyKey(idempotencyKey),
+            ),
+        );
+    }
+
+    @Get(':storeId/warehouses')
+    @ApiOperation({ summary: '读取最近成功同步的仓库摘要' })
+    public async warehouses(
+        @Param('storeId') storeId: string,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        return this.storesService.warehouses(
+            workspace.id,
+            requireUuid('store_id', storeId),
+        );
+    }
+
+    @Delete(':storeId')
+    @HttpCode(204)
+    @ApiOperation({ summary: '软删除门店连接并撤销当前密钥' })
+    @ApiNoContentResponse({ description: '门店已删除' })
+    public async remove(
+        @Param('storeId') storeId: string,
+        @Headers('idempotency-key') idempotencyKey: string | undefined,
+        @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace,
+        @Res({ passthrough: true }) response: HttpResponse,
+    ) {
+        return withStatus(
+            response,
+            await this.storesService.remove(
+                workspace.id,
+                request.auth.userId,
+                requireUuid('store_id', storeId),
+                requireIdempotencyKey(idempotencyKey),
+            ),
+        );
+    }
+}
+
+@ApiTags('Operations')
+@ApiBearerAuth('access-token')
+@Controller('operations')
+export class OperationsController {
+    public constructor(
+        @Inject(StoresService) private readonly storesService: StoresService,
+    ) {}
+
+    @Get(':operationId')
+    @ApiOperation({ summary: '读取当前工作空间的异步操作状态' })
+    public async get(
+        @Param('operationId') operationId: string,
+        @CurrentWorkspace() workspace: Workspace,
+    ) {
+        return {
+            data: await this.storesService.operation(
+                workspace.id,
+                requireUuid('operation_id', operationId),
+            ),
+        };
+    }
+}
+
+function withStatus(
+    response: HttpResponse,
+    result: { status: number; body: unknown },
+) {
+    response.status(result.status);
+    return result.body;
+}
+
+function requireIdempotencyKey(value: string | undefined): string {
+    if (!value) {
+        throw new ApiError(
+            400,
+            'IDEMPOTENCY_KEY_REQUIRED',
+            '请求缺少 Idempotency-Key',
+        );
+    }
+    return requireUuid('Idempotency-Key', value);
+}
+
+function requireUuid(field: string, value: string): string {
+    if (z.uuid().safeParse(value).success) return value;
+    throw new ApiError(422, 'VALIDATION_FAILED', '请求参数不符合要求', [
+        { field, code: 'INVALID_FIELD', message: `${field} 必须是 UUID` },
+    ]);
+}
+
+function parseRevision(value: string | undefined): number {
+    const match = value?.match(/^"([1-9]\d*)"$/);
+    if (!match) {
+        throw new ApiError(
+            400,
+            'IF_MATCH_REQUIRED',
+            '请求必须携带形如 "1" 的 If-Match',
+        );
+    }
+    return Number(match[1]);
+}
+
+function parse<T>(schema: z.ZodType<T>, value: unknown): T {
+    const result = schema.safeParse(value);
+    if (result.success) return result.data;
+    throw new ApiError(
+        422,
+        'VALIDATION_FAILED',
+        '请求参数不符合要求',
+        result.error.issues.map((issue) => ({
+            field: issue.path.join('.'),
+            code: 'INVALID_FIELD',
+            message: issue.message,
+        })),
+    );
+}

apps/api/src/stores/stores.module.ts

@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+import { IdempotencyService } from '../common/idempotency.service.js';
+import {
+    OperationsController,
+    PlatformsController,
+    StoresController,
+} from './stores.controller.js';
+import { PlatformsService } from './platforms.service.js';
+import { StoresService } from './stores.service.js';
+
+@Module({
+    controllers: [PlatformsController, StoresController, OperationsController],
+    providers: [IdempotencyService, PlatformsService, StoresService],
+})
+export class StoresModule {}

apps/api/src/stores/stores.service.ts

@@ -0,0 +1,757 @@
+import { Inject, Injectable } from '@nestjs/common';
+import type {
+    CreateStoreRequest,
+    ListStoresQuery,
+    Operation,
+    Store,
+    UpdateStoreRequest,
+} 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 { encryptStoreSecret } from './store-secret.crypto.js';
+
+type StoreRow = Omit<Store, keyof { created_at: never; updated_at: never }> & {
+    credential_checked_at: Date | string | null;
+    api_key_expires_at: Date | string | null;
+    product_limit_checked_at: Date | string | null;
+    warehouses_synced_at: Date | string | null;
+    created_at: Date | string;
+    updated_at: Date | string;
+};
+type StoreLockRow = {
+    id: string;
+    platform_id: string;
+    revision: number;
+    is_default: boolean;
+    status: string;
+};
+type OperationRow = {
+    id: string;
+    kind: string;
+    status: string;
+    created_at: Date | string;
+    completed_at: Date | string | null;
+    error_code: string | null;
+    error_message: string | null;
+};
+type WarehouseRow = {
+    id: string;
+    platform_warehouse_id: string;
+    name: string;
+    fulfillment: string;
+    is_rfbs: boolean | null;
+    status: string;
+    synced_at: Date | string;
+};
+
+@Injectable()
+export class StoresService {
+    public constructor(
+        @Inject(IdempotencyService)
+        private readonly idempotency: IdempotencyService,
+        @Inject(DATABASE) private readonly database: Database,
+        @Inject(APP_CONFIG) private readonly config: AppConfig,
+    ) {}
+
+    public async list(workspaceId: string, query: ListStoresQuery) {
+        const cursor = query.cursor ? decodeCursor(query.cursor) : null;
+        return this.database.workspaceTransaction(
+            workspaceId,
+            async (transaction: DatabaseTransaction) => {
+                const rows = await transaction.query<StoreRow>(
+                    `${storeSelect}
+                     WHERE s.platform_id = $1 AND s.deleted_at IS NULL
+                       AND ($2::timestamptz IS NULL OR (s.created_at, s.id) < ($2::timestamptz, $3::uuid))
+                     GROUP BY s.id, binding.value
+                     ORDER BY s.created_at DESC, s.id DESC
+                     LIMIT $4`,
+                    [
+                        query.platform_id,
+                        cursor?.createdAt ?? null,
+                        cursor?.id ?? null,
+                        query.limit + 1,
+                    ],
+                );
+                const hasMore = rows.rows.length > query.limit;
+                const items = rows.rows.slice(0, query.limit).map(toStore);
+                const last = items.at(-1);
+                return {
+                    data: items,
+                    meta: {
+                        next_cursor:
+                            hasMore && last
+                                ? encodeCursor(last.created_at, last.id)
+                                : null,
+                        has_more: hasMore,
+                    },
+                };
+            },
+        );
+    }
+
+    public async get(workspaceId: string, storeId: string): Promise<Store> {
+        return this.database.workspaceTransaction(
+            workspaceId,
+            async (transaction: DatabaseTransaction) =>
+                this.requireStore(transaction, storeId),
+        );
+    }
+
+    public async create(
+        workspaceId: string,
+        userId: string,
+        idempotencyKey: string,
+        input: CreateStoreRequest,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'POST',
+                path: '/api/stores',
+                key: idempotencyKey,
+                request: input,
+            },
+            async (transaction) => {
+                await this.assertPlatformCurrency(
+                    transaction,
+                    input.platform_id,
+                    input.currency_code,
+                );
+                // 同一平台的默认店铺修改串行化，避免两个并发创建都错误地判断自己是首店。
+                await lockPlatform(transaction, workspaceId, input.platform_id);
+                const existing = await transaction.query<{ id: string }>(
+                    `SELECT id FROM atlas.stores
+                     WHERE platform_id = $1 AND platform_client_id = $2
+                     LIMIT 1`,
+                    [input.platform_id, input.client_id],
+                );
+                if (existing.rows[0]) {
+                    throw new ApiError(
+                        409,
+                        'STORE_CONNECTION_ALREADY_EXISTS',
+                        '该平台账户已绑定为门店',
+                    );
+                }
+                const currentStores = await transaction.query<{
+                    count: string;
+                }>(
+                    `SELECT count(*)::text AS count FROM atlas.stores
+                     WHERE platform_id = $1 AND deleted_at IS NULL`,
+                    [input.platform_id],
+                );
+                const becomesDefault =
+                    Number(currentStores.rows[0]?.count ?? 0) === 0 ||
+                    input.is_default;
+                if (becomesDefault) {
+                    await transaction.query(
+                        `UPDATE atlas.stores SET is_default = false, revision = revision + 1, updated_at = now()
+                         WHERE platform_id = $1 AND is_default AND deleted_at IS NULL`,
+                        [input.platform_id],
+                    );
+                }
+                const created = await transaction.query<{ id: string }>(
+                    `INSERT INTO atlas.stores
+                        (workspace_id, platform_id, name, platform_client_id, currency_code, is_default, note)
+                     VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3, $4, $5, $6)
+                     RETURNING id`,
+                    [
+                        input.platform_id,
+                        input.name,
+                        input.client_id,
+                        input.currency_code,
+                        becomesDefault,
+                        input.note ?? null,
+                    ],
+                );
+                const storeId = created.rows[0].id;
+                await this.replaceApiKey(transaction, storeId, input.api_key);
+                const operation = await this.createOperation(
+                    transaction,
+                    userId,
+                    storeId,
+                    'store_credential_verification',
+                );
+                return {
+                    status: 202,
+                    body: {
+                        data: {
+                            store: await this.requireStore(
+                                transaction,
+                                storeId,
+                            ),
+                            operation,
+                        },
+                    },
+                };
+            },
+        );
+    }
+
+    public async update(
+        workspaceId: string,
+        userId: string,
+        storeId: string,
+        idempotencyKey: string,
+        revision: number,
+        input: UpdateStoreRequest,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'PATCH',
+                path: `/api/stores/${storeId}`,
+                key: idempotencyKey,
+                request: { if_match: revision, ...input },
+            },
+            async (transaction) => {
+                const current = await this.lockStore(transaction, storeId);
+                this.assertRevision(current, revision);
+                if (input.currency_code) {
+                    await this.assertPlatformCurrency(
+                        transaction,
+                        current.platform_id,
+                        input.currency_code,
+                    );
+                }
+                const replacingKey = input.api_key !== undefined;
+                await transaction.query(
+                    `UPDATE atlas.stores
+                     SET name = COALESCE($1, name), currency_code = COALESCE($2, currency_code),
+                         note = CASE WHEN $3 THEN $4 ELSE note END,
+                         status = CASE WHEN $5 THEN 'verifying'::atlas.store_status ELSE status END,
+                         credential_status = CASE WHEN $5 THEN 'unknown'::atlas.credential_status ELSE credential_status END,
+                         last_error_code = CASE WHEN $5 THEN NULL ELSE last_error_code END,
+                         last_error_message = CASE WHEN $5 THEN NULL ELSE last_error_message END,
+                         last_error_at = CASE WHEN $5 THEN NULL ELSE last_error_at END,
+                         revision = revision + 1, updated_at = now()
+                     WHERE id = $6`,
+                    [
+                        input.name ?? null,
+                        input.currency_code ?? null,
+                        Object.hasOwn(input, 'note'),
+                        input.note ?? null,
+                        replacingKey,
+                        storeId,
+                    ],
+                );
+                if (input.api_key !== undefined) {
+                    await this.replaceApiKey(
+                        transaction,
+                        storeId,
+                        input.api_key,
+                    );
+                    const operation = await this.createOperation(
+                        transaction,
+                        userId,
+                        storeId,
+                        'store_credential_verification',
+                    );
+                    return {
+                        status: 202,
+                        body: {
+                            data: {
+                                store: await this.requireStore(
+                                    transaction,
+                                    storeId,
+                                ),
+                                operation,
+                            },
+                        },
+                    };
+                }
+                return {
+                    status: 200,
+                    body: {
+                        data: await this.requireStore(transaction, storeId),
+                    },
+                };
+            },
+        );
+    }
+
+    public async setDefault(
+        workspaceId: string,
+        userId: string,
+        storeId: string,
+        idempotencyKey: string,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'POST',
+                path: `/api/stores/${storeId}/set-default`,
+                key: idempotencyKey,
+                request: {},
+            },
+            async (transaction) => {
+                const current = await this.lockStore(transaction, storeId);
+                await lockPlatform(
+                    transaction,
+                    workspaceId,
+                    current.platform_id,
+                );
+                await transaction.query(
+                    `UPDATE atlas.stores SET is_default = false, revision = revision + 1, updated_at = now()
+                     WHERE platform_id = $1 AND is_default AND deleted_at IS NULL AND id <> $2`,
+                    [current.platform_id, storeId],
+                );
+                if (!current.is_default) {
+                    await transaction.query(
+                        `UPDATE atlas.stores SET is_default = true, revision = revision + 1, updated_at = now()
+                         WHERE id = $1`,
+                        [storeId],
+                    );
+                }
+                return {
+                    status: 200,
+                    body: {
+                        data: await this.requireStore(transaction, storeId),
+                    },
+                };
+            },
+        );
+    }
+
+    public async requestCredentialVerification(
+        workspaceId: string,
+        userId: string,
+        storeId: string,
+        idempotencyKey: string,
+    ) {
+        return this.requestOperation(
+            workspaceId,
+            userId,
+            storeId,
+            idempotencyKey,
+            'credential-verifications',
+            'store_credential_verification',
+            false,
+        );
+    }
+
+    public async requestWarehouseSync(
+        workspaceId: string,
+        userId: string,
+        storeId: string,
+        idempotencyKey: string,
+    ) {
+        return this.requestOperation(
+            workspaceId,
+            userId,
+            storeId,
+            idempotencyKey,
+            'warehouse-syncs',
+            'store_warehouse_sync',
+            true,
+        );
+    }
+
+    public async remove(
+        workspaceId: string,
+        userId: string,
+        storeId: string,
+        idempotencyKey: string,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'DELETE',
+                path: `/api/stores/${storeId}`,
+                key: idempotencyKey,
+                request: {},
+            },
+            async (transaction) => {
+                const current = await this.lockStore(transaction, storeId);
+                if (current.is_default) {
+                    const replacement = await transaction.query<{ id: string }>(
+                        `SELECT id FROM atlas.stores
+                         WHERE platform_id = $1 AND id <> $2 AND deleted_at IS NULL LIMIT 1`,
+                        [current.platform_id, storeId],
+                    );
+                    if (replacement.rows[0]) {
+                        throw new ApiError(
+                            422,
+                            'DEFAULT_STORE_REPLACEMENT_REQUIRED',
+                            '删除默认门店前必须先选择同平台的其他默认门店',
+                        );
+                    }
+                }
+                await transaction.query(
+                    `UPDATE atlas.stores
+                     SET deleted_at = now(), status = 'deleted', is_default = false,
+                         revision = revision + 1, updated_at = now()
+                     WHERE id = $1`,
+                    [storeId],
+                );
+                // 删除连接后立刻撤销可用密钥，避免后台任务或未来恢复流程继续使用它。
+                await transaction.query(
+                    `UPDATE atlas.store_secrets SET revoked_at = now(), updated_at = now()
+                     WHERE store_id = $1 AND revoked_at IS NULL`,
+                    [storeId],
+                );
+                return { status: 204, body: null };
+            },
+        );
+    }
+
+    public async warehouses(workspaceId: string, storeId: string) {
+        return this.database.workspaceTransaction(
+            workspaceId,
+            async (transaction: DatabaseTransaction) => {
+                const store = await this.requireStore(transaction, storeId);
+                const rows = await transaction.query<WarehouseRow>(
+                    `SELECT id, platform_warehouse_id, name, fulfillment, is_rfbs, status, synced_at
+                     FROM atlas.store_warehouses WHERE store_id = $1 ORDER BY name, id`,
+                    [storeId],
+                );
+                return {
+                    data: rows.rows.map((row) => ({
+                        ...row,
+                        synced_at: toIso(row.synced_at),
+                    })),
+                    meta: { warehouses_synced_at: store.warehouses_synced_at },
+                };
+            },
+        );
+    }
+
+    public async operation(workspaceId: string, operationId: string) {
+        return this.database.workspaceTransaction(
+            workspaceId,
+            async (transaction: DatabaseTransaction) => {
+                const rows = await transaction.query<OperationRow>(
+                    `SELECT id, kind, status, created_at, completed_at, error_code, error_message
+                     FROM atlas.operations WHERE id = $1`,
+                    [operationId],
+                );
+                if (!rows.rows[0]) throw notFound('操作');
+                return toOperation(rows.rows[0]);
+            },
+        );
+    }
+
+    private async requestOperation(
+        workspaceId: string,
+        userId: string,
+        storeId: string,
+        idempotencyKey: string,
+        pathSuffix: string,
+        kind: string,
+        requiresValidCredential: boolean,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'POST',
+                path: `/api/stores/${storeId}/${pathSuffix}`,
+                key: idempotencyKey,
+                request: {},
+            },
+            async (transaction) => {
+                const store = await this.requireStore(transaction, storeId);
+                if (store.status === 'disabled') {
+                    throw new ApiError(422, 'STORE_DISABLED', '门店已停用');
+                }
+                if (
+                    requiresValidCredential &&
+                    store.credential_status !== 'valid'
+                ) {
+                    throw new ApiError(
+                        422,
+                        'STORE_CREDENTIAL_UNAVAILABLE',
+                        '门店凭据尚未验证通过，无法同步仓库',
+                    );
+                }
+                if (kind === 'store_credential_verification') {
+                    await transaction.query(
+                        `UPDATE atlas.stores SET status = 'verifying', credential_status = 'unknown',
+                         last_error_code = NULL, last_error_message = NULL, last_error_at = NULL,
+                         revision = revision + 1, updated_at = now() WHERE id = $1`,
+                        [storeId],
+                    );
+                    await transaction.query(
+                        `UPDATE atlas.store_secrets SET status = 'unknown', updated_at = now()
+                         WHERE store_id = $1 AND kind = 'seller_api_key' AND revoked_at IS NULL`,
+                        [storeId],
+                    );
+                }
+                const operation = await this.createOperation(
+                    transaction,
+                    userId,
+                    storeId,
+                    kind,
+                );
+                return { status: 202, body: { data: { operation } } };
+            },
+        );
+    }
+
+    private async assertPlatformCurrency(
+        transaction: DatabaseTransaction,
+        platformId: string,
+        currencyCode: string,
+    ) {
+        const platform = await transaction.query<{ id: string }>(
+            `SELECT id FROM atlas.platforms WHERE id = $1 AND status = 'active'`,
+            [platformId],
+        );
+        if (!platform.rows[0]) {
+            throw new ApiError(
+                422,
+                'PLATFORM_UNAVAILABLE',
+                '平台不存在或已停用',
+            );
+        }
+        const supported = await transaction.query<{ currency_code: string }>(
+            `SELECT pcs.currency_code FROM atlas.platform_currency_support pcs
+             JOIN atlas.currencies c ON c.code = pcs.currency_code
+             WHERE pcs.platform_id = $1 AND pcs.currency_code = $2
+               AND pcs.is_enabled AND c.is_enabled`,
+            [platformId, currencyCode],
+        );
+        if (!supported.rows[0]) {
+            throw new ApiError(
+                422,
+                'PLATFORM_CURRENCY_UNSUPPORTED',
+                '该平台不支持此默认计价币种',
+            );
+        }
+    }
+
+    private async lockStore(transaction: DatabaseTransaction, storeId: string) {
+        const rows = await transaction.query<StoreLockRow>(
+            `SELECT id, platform_id, revision, is_default, status
+             FROM atlas.stores WHERE id = $1 AND deleted_at IS NULL FOR UPDATE`,
+            [storeId],
+        );
+        if (!rows.rows[0]) throw notFound('门店');
+        return rows.rows[0];
+    }
+
+    private assertRevision(current: StoreLockRow, expected: number) {
+        if (current.revision !== expected) {
+            throw new ApiError(
+                409,
+                'VERSION_CONFLICT',
+                '门店已被其他操作更新',
+                [
+                    {
+                        field: 'If-Match',
+                        code: 'VERSION_CONFLICT',
+                        message: `当前版本为 ${current.revision}`,
+                        current_revision: current.revision,
+                    },
+                ],
+            );
+        }
+    }
+
+    private async replaceApiKey(
+        transaction: DatabaseTransaction,
+        storeId: string,
+        apiKey: string,
+    ) {
+        const secret = encryptStoreSecret(
+            apiKey,
+            this.config.STORE_SECRET_ENCRYPTION_KEY,
+        );
+        const existing = await transaction.query<{ id: string }>(
+            `SELECT id FROM atlas.store_secrets
+             WHERE store_id = $1 AND kind = 'seller_api_key' AND fingerprint = $2
+             FOR UPDATE`,
+            [storeId, secret.fingerprint],
+        );
+        await transaction.query(
+            `UPDATE atlas.store_secrets SET revoked_at = now(), updated_at = now()
+             WHERE store_id = $1 AND kind = 'seller_api_key' AND revoked_at IS NULL`,
+            [storeId],
+        );
+        if (existing.rows[0]) {
+            // 同一密钥可被重新提交用于验证；恢复历史行避免违反防重指纹唯一约束。
+            await transaction.query(
+                `UPDATE atlas.store_secrets
+                 SET secret_ciphertext = $1, secret_nonce = $2, encryption_key_version = $3,
+                     status = 'unknown', revoked_at = NULL, updated_at = now()
+                 WHERE id = $4`,
+                [
+                    secret.ciphertext,
+                    secret.nonce,
+                    this.config.STORE_SECRET_ENCRYPTION_KEY_VERSION,
+                    existing.rows[0].id,
+                ],
+            );
+            return;
+        }
+        await transaction.query(
+            `INSERT INTO atlas.store_secrets
+                (workspace_id, store_id, kind, secret_ciphertext, secret_nonce, encryption_key_version, fingerprint)
+             VALUES (current_setting('app.workspace_id')::uuid, $1, 'seller_api_key', $2, $3, $4, $5)`,
+            [
+                storeId,
+                secret.ciphertext,
+                secret.nonce,
+                this.config.STORE_SECRET_ENCRYPTION_KEY_VERSION,
+                secret.fingerprint,
+            ],
+        );
+    }
+
+    private async createOperation(
+        transaction: DatabaseTransaction,
+        userId: string,
+        storeId: string,
+        kind: string,
+    ): Promise<Operation> {
+        const created = await transaction.query<OperationRow>(
+            `INSERT INTO atlas.operations
+                (workspace_id, kind, resource_type, resource_id, created_by_user_id)
+             VALUES (current_setting('app.workspace_id')::uuid, $1, 'store', $2, $3)
+             RETURNING id, kind, status, created_at, completed_at, error_code, error_message`,
+            [kind, storeId, userId],
+        );
+        const operation = toOperation(created.rows[0]);
+        const payload: { store_id: string; operation_id: string; secret_id?: string } = {
+            store_id: storeId,
+            operation_id: operation.id,
+        };
+        // 验证任务绑定创建当刻的密钥行；密钥后来被替换时，旧任务不得验证或覆盖新状态。
+        if (kind === 'store_credential_verification') {
+            const secret = await transaction.query<{ id: string }>(
+                `SELECT id FROM atlas.store_secrets
+                 WHERE store_id = $1 AND kind = 'seller_api_key' AND revoked_at IS NULL`,
+                [storeId],
+            );
+            if (!secret.rows[0]) throw new Error('Current store secret is missing');
+            payload.secret_id = secret.rows[0].id;
+        }
+        await transaction.query(
+            `INSERT INTO atlas.outbox_events
+                (workspace_id, aggregate_type, aggregate_id, event_type, event_payload, deduplication_key)
+             VALUES (current_setting('app.workspace_id')::uuid, 'store', $1, $2, $3, $4)`,
+            [
+                storeId,
+                `${kind}.requested`,
+                payload,
+                operation.id,
+            ],
+        );
+        return operation;
+    }
+
+    private async requireStore(
+        transaction: DatabaseTransaction,
+        storeId: string,
+    ): Promise<Store> {
+        const rows = await transaction.query<StoreRow>(
+            `${storeSelect}
+             WHERE s.id = $1 AND s.deleted_at IS NULL
+             GROUP BY s.id, binding.value`,
+            [storeId],
+        );
+        if (!rows.rows[0]) throw notFound('门店');
+        return toStore(rows.rows[0]);
+    }
+}
+
+const storeSelect = `
+    SELECT s.id, s.platform_id, s.name, s.platform_client_id, s.currency_code,
+           s.is_default, s.note, s.status, s.credential_status, s.credential_checked_at,
+           CASE WHEN s.last_error_code IS NULL THEN NULL
+                ELSE jsonb_build_object('code', s.last_error_code, 'message', s.last_error_message, 'at', s.last_error_at)
+           END AS last_error,
+           s.api_key_expires_at, s.product_limit, s.product_limit_checked_at,
+           count(sw.id)::integer AS warehouse_count, max(sw.synced_at) AS warehouses_synced_at,
+           binding.value AS watermark_template, s.created_at, s.updated_at, s.revision
+    FROM atlas.stores s
+    LEFT JOIN atlas.store_warehouses sw ON sw.store_id = s.id
+    LEFT JOIN LATERAL (
+        SELECT jsonb_build_object('id', wt.id, 'name', wt.name) AS value
+        FROM atlas.store_watermark_bindings wb
+        JOIN atlas.watermark_templates wt ON wt.id = wb.template_id
+        WHERE wb.store_id = s.id AND wb.unbound_at IS NULL
+        LIMIT 1
+    ) binding ON true`;
+
+function toStore(row: StoreRow): Store {
+    return {
+        ...row,
+        credential_checked_at: toIso(row.credential_checked_at),
+        api_key_expires_at: toIso(row.api_key_expires_at),
+        product_limit_checked_at: toIso(row.product_limit_checked_at),
+        warehouses_synced_at: toIso(row.warehouses_synced_at),
+        created_at: toRequiredIso(row.created_at),
+        updated_at: toRequiredIso(row.updated_at),
+        cookie_status: null,
+    };
+}
+
+function toOperation(row: OperationRow): Operation {
+    return {
+        id: row.id,
+        kind: row.kind,
+        status: row.status,
+        created_at: toRequiredIso(row.created_at),
+        completed_at: toIso(row.completed_at),
+        error:
+            row.error_code && row.error_message
+                ? { code: row.error_code, message: row.error_message }
+                : null,
+    };
+}
+
+function toIso(value: Date | string | null): string | null {
+    if (value === null) return null;
+    return value instanceof Date ? value.toISOString() : value;
+}
+
+function toRequiredIso(value: Date | string): string {
+    return value instanceof Date ? value.toISOString() : value;
+}
+
+function notFound(resource: string) {
+    return new ApiError(404, 'RESOURCE_NOT_FOUND', `${resource}不存在`);
+}
+
+async function lockPlatform(
+    transaction: DatabaseTransaction,
+    workspaceId: string,
+    platformId: string,
+) {
+    await transaction.query(
+        `SELECT pg_advisory_xact_lock(hashtextextended($1, 0))`,
+        [`${workspaceId}:${platformId}`],
+    );
+}
+
+function encodeCursor(createdAt: string, id: string): string {
+    return Buffer.from(JSON.stringify({ createdAt, id })).toString('base64url');
+}
+
+function decodeCursor(cursor: string): { createdAt: string; id: string } {
+    try {
+        const value = JSON.parse(
+            Buffer.from(cursor, 'base64url').toString('utf8'),
+        ) as { createdAt?: unknown; id?: unknown };
+        if (
+            typeof value.createdAt !== 'string' ||
+            Number.isNaN(Date.parse(value.createdAt)) ||
+            typeof value.id !== 'string' ||
+            !/^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(value.id)
+        ) {
+            throw new Error('invalid cursor');
+        }
+        return { createdAt: value.createdAt, id: value.id };
+    } catch {
+        throw new ApiError(422, 'VALIDATION_FAILED', '分页游标无效', [
+            { field: 'cursor', code: 'INVALID_FIELD', message: '分页游标无效' },
+        ]);
+    }
+}

apps/api/src/watermarks/watermarks.controller.ts

@@ -0,0 +1,91 @@
+import {
+    Body, Controller, Delete, Get, Headers, HttpCode, Inject, Param, Patch, Post, Put, Query, Req,
+} from '@nestjs/common';
+import { ApiBearerAuth, ApiCreatedResponse, ApiNoContentResponse, ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+    bindStoreWatermarkRequestSchema, createWatermarkTemplateRequestSchema,
+    listWatermarkTemplatesQuerySchema, updateWatermarkTemplateRequestSchema, type Workspace,
+} from '@atlas/contracts';
+import { z } from 'zod';
+import { ApiError } from '../common/api-error.js';
+import type { AuthenticatedRequest } from '../auth/auth.guard.js';
+import { CurrentWorkspace } from '../workspace/current-workspace.decorator.js';
+import { WatermarksService } from './watermarks.service.js';
+
+@ApiTags('Watermarks')
+@ApiBearerAuth('access-token')
+@Controller()
+export class WatermarksController {
+    public constructor(@Inject(WatermarksService) private readonly watermarks: WatermarksService) {}
+
+    @Get('watermark-fonts')
+    @ApiOperation({ summary: '读取当前渲染服务可用字体' })
+    public async fonts() { return { data: await this.watermarks.fonts() }; }
+
+    @Get('watermark-templates')
+    @ApiOperation({ summary: '分页读取当前工作空间活动水印模板' })
+    public async list(@Query() query: unknown, @CurrentWorkspace() workspace: Workspace) {
+        return this.watermarks.list(workspace.id, parse(listWatermarkTemplatesQuerySchema, query));
+    }
+
+    @Get('watermark-templates/:templateId')
+    @ApiOperation({ summary: '读取水印模板当前版本' })
+    public async get(@Param('templateId') templateId: string, @CurrentWorkspace() workspace: Workspace) {
+        return { data: await this.watermarks.get(workspace.id, uuid('template_id', templateId)) };
+    }
+
+    @Post('watermark-templates')
+    @ApiCreatedResponse({ description: '已创建水印模板及首个渲染版本' })
+    public async create(@Body() body: unknown, @Headers('idempotency-key') key: string | undefined,
+        @Req() request: AuthenticatedRequest, @CurrentWorkspace() workspace: Workspace) {
+        return (await this.watermarks.create(workspace.id, request.auth.userId, idempotencyKey(key),
+            parse(createWatermarkTemplateRequestSchema, body))).body;
+    }
+
+    @Patch('watermark-templates/:templateId')
+    @ApiOkResponse({ description: '已更新水印模板' })
+    public async update(@Param('templateId') templateId: string, @Body() body: unknown,
+        @Headers('idempotency-key') key: string | undefined, @Headers('if-match') ifMatch: string | undefined,
+        @Req() request: AuthenticatedRequest, @CurrentWorkspace() workspace: Workspace) {
+        return (await this.watermarks.update(workspace.id, request.auth.userId, uuid('template_id', templateId),
+            idempotencyKey(key), revision(ifMatch), parse(updateWatermarkTemplateRequestSchema, body))).body;
+    }
+
+    @Delete('watermark-templates/:templateId')
+    @HttpCode(204)
+    @ApiNoContentResponse({ description: '已软删除模板并解除当前店铺绑定' })
+    public async remove(@Param('templateId') templateId: string, @Headers('idempotency-key') key: string | undefined,
+        @Req() request: AuthenticatedRequest, @CurrentWorkspace() workspace: Workspace) {
+        await this.watermarks.remove(workspace.id, request.auth.userId, uuid('template_id', templateId), idempotencyKey(key));
+    }
+
+    @Put('stores/:storeId/watermark-binding')
+    @ApiOkResponse({ description: '已更新店铺推荐水印' })
+    public async bindStore(@Param('storeId') storeId: string, @Body() body: unknown,
+        @Headers('idempotency-key') key: string | undefined, @Req() request: AuthenticatedRequest,
+        @CurrentWorkspace() workspace: Workspace) {
+        const input = parse(bindStoreWatermarkRequestSchema, body) as { template_id: string | null };
+        return (await this.watermarks.bindStore(workspace.id, request.auth.userId, uuid('store_id', storeId),
+            idempotencyKey(key), input.template_id)).body;
+    }
+}
+
+function parse<T extends { safeParse: (input: unknown) => { success: boolean; data?: unknown; error?: { issues: Array<{ path: PropertyKey[]; message: string }> } } }>(schema: T, input: unknown) {
+    const result = schema.safeParse(input);
+    if (result.success) return result.data as ReturnType<T['safeParse']> extends { data: infer Data } ? Data : never;
+    throw new ApiError(422, 'VALIDATION_FAILED', '请求参数不符合要求',
+        result.error?.issues.map((issue) => ({ field: issue.path.join('.'), code: 'INVALID_FIELD', message: issue.message })));
+}
+function uuid(field: string, value: string) {
+    if (z.uuid().safeParse(value).success) return value;
+    throw new ApiError(422, 'VALIDATION_FAILED', '请求参数不符合要求', [{ field, code: 'INVALID_FIELD', message: `${field} 必须是 UUID` }]);
+}
+function idempotencyKey(value: string | undefined) {
+    if (!value) throw new ApiError(400, 'IDEMPOTENCY_KEY_REQUIRED', '请求缺少 Idempotency-Key');
+    return uuid('Idempotency-Key', value);
+}
+function revision(value: string | undefined) {
+    const match = value?.match(/^"([1-9]\d*)"$/);
+    if (!match) throw new ApiError(400, 'IF_MATCH_REQUIRED', '请求缺少或格式错误的 If-Match');
+    return Number(match[1]);
+}

apps/api/src/watermarks/watermarks.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { IdempotencyService } from '../common/idempotency.service.js';
+import { WatermarksController } from './watermarks.controller.js';
+import { WatermarksService } from './watermarks.service.js';
+
+@Module({
+    controllers: [WatermarksController],
+    providers: [IdempotencyService, WatermarksService],
+})
+export class WatermarksModule {}

apps/api/src/watermarks/watermarks.service.ts

@@ -0,0 +1,478 @@
+import { Inject, Injectable } from '@nestjs/common';
+import type {
+    CreateWatermarkTemplateRequest,
+    ListWatermarkTemplatesQuery,
+    UpdateWatermarkTemplateRequest,
+} 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 { DATABASE } from '../database/database.module.js';
+
+type TemplateRow = {
+    id: string;
+    name: string;
+    kind: 'text' | 'image';
+    current_version: number;
+    created_at: Date | string;
+    updated_at: Date | string;
+    revision: number;
+    text_content: string | null;
+    image_asset_id: string | null;
+    font_code: string | null;
+    font_size_px: number | null;
+    opacity: string;
+    scale_ratio: string | null;
+    position: string;
+};
+type TemplateConfig = Record<string, unknown>;
+
+@Injectable()
+export class WatermarksService {
+    public constructor(
+        @Inject(IdempotencyService)
+        private readonly idempotency: IdempotencyService,
+        @Inject(DATABASE) private readonly database: Database,
+    ) {}
+
+    public async fonts() {
+        const fonts = await this.database.query<{
+            code: string;
+            display_name: string;
+        }>(
+            `SELECT code, display_name FROM atlas.watermark_fonts
+             WHERE status = 'active' ORDER BY display_name, code`,
+        );
+        return fonts.rows;
+    }
+
+    public async list(workspaceId: string, query: ListWatermarkTemplatesQuery) {
+        const cursor = query.cursor ? decodeCursor(query.cursor) : null;
+        return this.database.workspaceTransaction(workspaceId, async (tx) => {
+            const rows = await tx.query<TemplateRow>(
+                `${templateSelect}
+                 WHERE template.status = 'active' AND template.deleted_at IS NULL
+                   AND ($1::timestamptz IS NULL OR (template.created_at, template.id) < ($1::timestamptz, $2::uuid))
+                 ORDER BY template.created_at DESC, template.id DESC LIMIT $3`,
+                [
+                    cursor?.createdAt ?? null,
+                    cursor?.id ?? null,
+                    query.limit + 1,
+                ],
+            );
+            const items = rows.rows.slice(0, query.limit).map(toTemplate);
+            const last = items.at(-1);
+            return {
+                data: items,
+                meta: {
+                    has_more: rows.rows.length > query.limit,
+                    next_cursor:
+                        rows.rows.length > query.limit && last
+                            ? encodeCursor(last.created_at, last.id)
+                            : null,
+                },
+            };
+        });
+    }
+
+    public async get(workspaceId: string, templateId: string) {
+        return this.database.workspaceTransaction(workspaceId, (tx) =>
+            this.requireTemplate(tx, templateId),
+        );
+    }
+
+    public async create(
+        workspaceId: string,
+        userId: string,
+        idempotencyKey: string,
+        input: CreateWatermarkTemplateRequest,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'POST',
+                path: '/api/watermark-templates',
+                key: idempotencyKey,
+                request: input,
+            },
+            async (tx) => {
+                await this.validateConfig(tx, input.kind, input.config);
+                const inserted = await tx.query<{ id: string }>(
+                    `INSERT INTO atlas.watermark_templates (workspace_id, name, kind)
+                     VALUES (current_setting('app.workspace_id')::uuid, $1, $2) RETURNING id`,
+                    [input.name, input.kind],
+                );
+                await this.insertVersion(
+                    tx,
+                    inserted.rows[0].id,
+                    1,
+                    input.kind,
+                    input.config,
+                    userId,
+                );
+                return {
+                    status: 201,
+                    body: {
+                        data: await this.requireTemplate(
+                            tx,
+                            inserted.rows[0].id,
+                        ),
+                    },
+                };
+            },
+        );
+    }
+
+    public async update(
+        workspaceId: string,
+        userId: string,
+        templateId: string,
+        idempotencyKey: string,
+        revision: number,
+        input: UpdateWatermarkTemplateRequest,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'PATCH',
+                path: `/api/watermark-templates/${templateId}`,
+                key: idempotencyKey,
+                request: { if_match: revision, ...input },
+            },
+            async (tx) => {
+                const current = await this.lockTemplate(tx, templateId);
+                if (current.revision !== revision)
+                    throw versionConflict(current.revision);
+                const nextKind = input.kind ?? current.kind;
+                if (
+                    input.kind &&
+                    input.kind !== current.kind &&
+                    !input.config
+                ) {
+                    throw new ApiError(
+                        422,
+                        'VALIDATION_FAILED',
+                        '切换水印类型时必须提交新类型完整配置',
+                    );
+                }
+                // 同类型编辑允许只提交变化字段；切换类型时旧类型字段不会通过新类型校验。
+                const nextConfig = normalizeConfig(nextKind, {
+                    ...configFromRow(current),
+                    ...(input.config ?? {}),
+                });
+                await this.validateConfig(tx, nextKind, nextConfig);
+                const renderingChanged =
+                    input.config !== undefined || nextKind !== current.kind;
+                await tx.query(
+                    `UPDATE atlas.watermark_templates SET name = COALESCE($1, name), kind = $2,
+                     current_version = current_version + CASE WHEN $3 THEN 1 ELSE 0 END,
+                     revision = revision + 1, updated_at = now() WHERE id = $4`,
+                    [
+                        input.name ?? null,
+                        nextKind,
+                        renderingChanged,
+                        templateId,
+                    ],
+                );
+                if (renderingChanged) {
+                    await this.insertVersion(
+                        tx,
+                        templateId,
+                        current.current_version + 1,
+                        nextKind,
+                        nextConfig,
+                        userId,
+                    );
+                }
+                return {
+                    status: 200,
+                    body: { data: await this.requireTemplate(tx, templateId) },
+                };
+            },
+        );
+    }
+
+    public async remove(
+        workspaceId: string,
+        userId: string,
+        templateId: string,
+        idempotencyKey: string,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'DELETE',
+                path: `/api/watermark-templates/${templateId}`,
+                key: idempotencyKey,
+                request: {},
+            },
+            async (tx) => {
+                await this.lockTemplate(tx, templateId);
+                await tx.query(
+                    `UPDATE atlas.store_watermark_bindings SET unbound_at = now()
+                    WHERE template_id = $1 AND unbound_at IS NULL`,
+                    [templateId],
+                );
+                await tx.query(
+                    `UPDATE atlas.watermark_templates SET status = 'archived', deleted_at = now(),
+                    revision = revision + 1, updated_at = now() WHERE id = $1`,
+                    [templateId],
+                );
+                return { status: 204, body: null };
+            },
+        );
+    }
+
+    public async bindStore(
+        workspaceId: string,
+        userId: string,
+        storeId: string,
+        idempotencyKey: string,
+        templateId: string | null,
+    ) {
+        return this.idempotency.run(
+            {
+                workspaceId,
+                userId,
+                method: 'PUT',
+                path: `/api/stores/${storeId}/watermark-binding`,
+                key: idempotencyKey,
+                request: { template_id: templateId },
+            },
+            async (tx) => {
+                const store = await tx.query<{ id: string }>(
+                    `SELECT id FROM atlas.stores WHERE id = $1 AND deleted_at IS NULL FOR UPDATE`,
+                    [storeId],
+                );
+                if (!store.rows[0])
+                    throw new ApiError(404, 'RESOURCE_NOT_FOUND', '门店不存在');
+                if (templateId) await this.requireTemplate(tx, templateId);
+                await tx.query(
+                    `UPDATE atlas.store_watermark_bindings SET unbound_at = now()
+                    WHERE store_id = $1 AND unbound_at IS NULL`,
+                    [storeId],
+                );
+                if (templateId) {
+                    await tx.query(
+                        `INSERT INTO atlas.store_watermark_bindings
+                        (workspace_id, store_id, template_id, bound_by_user_id)
+                        VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3)`,
+                        [storeId, templateId, userId],
+                    );
+                }
+                const result = templateId
+                    ? await this.requireTemplate(tx, templateId)
+                    : null;
+                return {
+                    status: 200,
+                    body: {
+                        data: {
+                            watermark_template: result
+                                ? { id: result.id, name: result.name }
+                                : null,
+                        },
+                    },
+                };
+            },
+        );
+    }
+
+    private async lockTemplate(
+        tx: DatabaseTransaction,
+        id: string,
+    ): Promise<TemplateRow> {
+        const rows = await tx.query<TemplateRow>(
+            `${templateSelect} WHERE template.id = $1
+            AND template.status = 'active' AND template.deleted_at IS NULL FOR UPDATE`,
+            [id],
+        );
+        if (!rows.rows[0])
+            throw new ApiError(404, 'RESOURCE_NOT_FOUND', '水印模板不存在');
+        return rows.rows[0];
+    }
+
+    private async requireTemplate(tx: DatabaseTransaction, id: string) {
+        const rows = await tx.query<TemplateRow>(
+            `${templateSelect} WHERE template.id = $1
+            AND template.status = 'active' AND template.deleted_at IS NULL`,
+            [id],
+        );
+        if (!rows.rows[0])
+            throw new ApiError(404, 'RESOURCE_NOT_FOUND', '水印模板不存在');
+        return toTemplate(rows.rows[0]);
+    }
+
+    private async validateConfig(
+        tx: DatabaseTransaction,
+        kind: 'text' | 'image',
+        config: TemplateConfig,
+    ) {
+        if (
+            typeof config.opacity !== 'string' ||
+            typeof config.position !== 'string'
+        ) {
+            throw new ApiError(422, 'VALIDATION_FAILED', '水印配置不完整');
+        }
+        if (kind === 'text') {
+            const fontCode = config.font_code;
+            if (
+                typeof fontCode !== 'string' ||
+                typeof config.text_content !== 'string' ||
+                typeof config.font_size_px !== 'number'
+            ) {
+                throw new ApiError(
+                    422,
+                    'VALIDATION_FAILED',
+                    '文字水印配置不完整',
+                );
+            }
+            const font = await tx.query(
+                `SELECT code FROM atlas.watermark_fonts WHERE code = $1 AND status = 'active'`,
+                [fontCode],
+            );
+            if (!font.rows[0])
+                throw new ApiError(
+                    422,
+                    'WATERMARK_FONT_UNAVAILABLE',
+                    '所选字体不可用',
+                );
+            return;
+        }
+        const assetId = config.image_asset_id;
+        if (
+            typeof assetId !== 'string' ||
+            typeof config.scale_ratio !== 'string'
+        ) {
+            throw new ApiError(422, 'VALIDATION_FAILED', '图片水印配置不完整');
+        }
+        const asset = await tx.query<{ id: string }>(
+            `SELECT id FROM atlas.media_assets WHERE id = $1
+             AND content_type IN ('image/png', 'image/jpeg', 'image/webp')`,
+            [assetId],
+        );
+        if (!asset.rows[0])
+            throw new ApiError(
+                422,
+                'WATERMARK_IMAGE_UNAVAILABLE',
+                '水印图片不存在或不属于当前工作空间',
+            );
+    }
+
+    private async insertVersion(
+        tx: DatabaseTransaction,
+        templateId: string,
+        version: number,
+        kind: 'text' | 'image',
+        config: TemplateConfig,
+        userId: string,
+    ) {
+        await tx.query(
+            `INSERT INTO atlas.watermark_template_versions
+            (workspace_id, template_id, version, kind, text_content, image_asset_id, font_code, font_size_px, opacity, scale_ratio, position, created_by_user_id)
+            VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
+            [
+                templateId,
+                version,
+                kind,
+                config.text_content ?? null,
+                config.image_asset_id ?? null,
+                config.font_code ?? null,
+                config.font_size_px ?? null,
+                config.opacity,
+                config.scale_ratio ?? null,
+                config.position,
+                userId,
+            ],
+        );
+    }
+}
+
+const templateSelect = `SELECT template.id, template.name, template.kind, template.current_version,
+    template.created_at, template.updated_at, template.revision, version.text_content, version.image_asset_id,
+    version.font_code, version.font_size_px, version.opacity::text AS opacity, version.scale_ratio::text AS scale_ratio,
+    version.position FROM atlas.watermark_templates template JOIN atlas.watermark_template_versions version
+    ON version.template_id = template.id AND version.version = template.current_version`;
+
+function toTemplate(row: TemplateRow) {
+    return {
+        id: row.id,
+        name: row.name,
+        kind: row.kind,
+        current_version: row.current_version,
+        config: configFromRow(row),
+        created_at: iso(row.created_at),
+        updated_at: iso(row.updated_at),
+        revision: row.revision,
+    };
+}
+function configFromRow(row: TemplateRow): TemplateConfig {
+    return row.kind === 'text'
+        ? {
+              text_content: row.text_content,
+              font_code: row.font_code,
+              font_size_px: row.font_size_px,
+              opacity: row.opacity,
+              position: row.position,
+          }
+        : {
+              image_asset_id: row.image_asset_id,
+              scale_ratio: row.scale_ratio,
+              opacity: row.opacity,
+              position: row.position,
+          };
+}
+function normalizeConfig(
+    kind: 'text' | 'image',
+    config: TemplateConfig,
+): TemplateConfig {
+    return kind === 'text'
+        ? {
+              text_content: config.text_content,
+              font_code: config.font_code,
+              font_size_px: config.font_size_px,
+              opacity: config.opacity,
+              position: config.position,
+          }
+        : {
+              image_asset_id: config.image_asset_id,
+              scale_ratio: config.scale_ratio,
+              opacity: config.opacity,
+              position: config.position,
+          };
+}
+function iso(value: Date | string) {
+    return value instanceof Date ? value.toISOString() : value;
+}
+function versionConflict(currentRevision: number) {
+    return new ApiError(409, 'VERSION_CONFLICT', '水印模板已被其他操作更新', [
+        {
+            field: 'If-Match',
+            code: 'VERSION_CONFLICT',
+            message: `当前版本为 ${currentRevision}`,
+            current_revision: currentRevision,
+        },
+    ]);
+}
+function encodeCursor(createdAt: string, id: string) {
+    return Buffer.from(JSON.stringify({ createdAt, id })).toString('base64url');
+}
+function decodeCursor(cursor: string): { createdAt: string; id: string } {
+    try {
+        const value = JSON.parse(
+            Buffer.from(cursor, 'base64url').toString('utf8'),
+        ) as { createdAt?: unknown; id?: unknown };
+        if (
+            typeof value.createdAt !== 'string' ||
+            Number.isNaN(Date.parse(value.createdAt)) ||
+            typeof value.id !== 'string' ||
+            !/^[0-9a-f-]{36}$/i.test(value.id)
+        )
+            throw new Error();
+        return { createdAt: value.createdAt, id: value.id };
+    } catch {
+        throw new ApiError(422, 'VALIDATION_FAILED', '分页游标无效');
+    }
+}

apps/api/src/workspace/current-workspace.decorator.ts

@@ -0,0 +1,13 @@
+import { createParamDecorator, type ExecutionContext } from '@nestjs/common';
+import type { Workspace } from '@atlas/contracts';
+import type { WorkspaceAuthenticatedRequest } from './workspace-context.guard.js';
+
+// 受保护接口经全局工作空间守卫验证后，只能从这里读取当前工作空间。
+export const CurrentWorkspace = createParamDecorator(
+    (_data: unknown, context: ExecutionContext): Workspace => {
+        const request = context
+            .switchToHttp()
+            .getRequest<WorkspaceAuthenticatedRequest>();
+        return request.auth.workspace;
+    },
+);

apps/api/src/workspace/workspace-context.guard.ts

@@ -0,0 +1,63 @@
+import {
+    CanActivate,
+    ExecutionContext,
+    Inject,
+    Injectable,
+} from '@nestjs/common';
+import type { Workspace } from '@atlas/contracts';
+import type { Database } from '@atlas/database';
+import { Reflector } from '@nestjs/core';
+import { ApiError } from '../common/api-error.js';
+import { IS_PUBLIC_ENDPOINT } from '../common/public.decorator.js';
+import { DATABASE } from '../database/database.module.js';
+import type { AuthenticatedRequest } from '../auth/auth.guard.js';
+
+export type WorkspaceAuthenticatedRequest = AuthenticatedRequest & {
+    auth: AuthenticatedRequest['auth'] & { workspace: Workspace };
+};
+
+@Injectable()
+export class WorkspaceContextGuard implements CanActivate {
+    public constructor(
+        @Inject(Reflector) private readonly reflector: Reflector,
+        @Inject(DATABASE) private readonly database: Database,
+    ) {}
+
+    public async canActivate(context: ExecutionContext): Promise<boolean> {
+        if (
+            this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_ENDPOINT, [
+                context.getHandler(),
+                context.getClass(),
+            ])
+        ) {
+            return true;
+        }
+
+        const request = context
+            .switchToHttp()
+            .getRequest<AuthenticatedRequest>();
+        // 当前一期每位用户只有一个个人工作空间；后续多人协作时此处将按显式选择的工作空间校验 membership。
+        const workspace = await this.findCurrentWorkspace(request.auth.userId);
+        if (!workspace) {
+            throw new ApiError(
+                403,
+                'WORKSPACE_MEMBERSHIP_REQUIRED',
+                '当前账户没有可用工作空间',
+            );
+        }
+        // 后续控制器和服务只使用此处验证过的上下文，绝不相信客户端传入 workspace_id。
+        request.auth.workspace = workspace;
+        return true;
+    }
+
+    private async findCurrentWorkspace(
+        userId: string,
+    ): Promise<Workspace | null> {
+        // 排序规则是首期“唯一有效工作空间”的临时选择策略，不是未来的工作空间切换协议。
+        const result = await this.database.query<Workspace>(
+            `SELECT w.id, w.name, m.role FROM atlas.workspace_memberships m JOIN atlas.workspaces w ON w.id = m.workspace_id WHERE m.user_id = $1 AND w.status = 'active' ORDER BY m.joined_at LIMIT 1`,
+            [userId],
+        );
+        return result.rows[0] ?? null;
+    }
+}

apps/api/test/auth.e2e.test.ts

@@ -0,0 +1,430 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import type { AddressInfo } from 'node:net';
+import type { Database } from '@atlas/database';
+import type { NestExpressApplication } from '@nestjs/platform-express';
+import { afterAll, beforeAll, describe, it } from 'vitest';
+import { DATABASE } from '../src/database/database.module.js';
+import { createApplication } from '../src/main.js';
+
+type SuccessResponse<T> = { data: T };
+type ErrorResponse = {
+    error: {
+        code: string;
+        message: string;
+        request_id: string;
+        details?: Array<{ field: string; code: string; message: string }>;
+    };
+};
+type SessionPayload = {
+    access_token: string;
+    access_token_expires_in: number;
+    user: {
+        id: string;
+        email: string;
+        display_name: string | null;
+        avatar_asset_id: string | null;
+        revision: number;
+    };
+    workspace: { id: string; name: string; role: string };
+};
+
+const password = 'correct-horse-battery-staple-123';
+const testUsers: Array<{ userId: string; workspaceId: string }> = [];
+let app: NestExpressApplication;
+let database: Database;
+let baseUrl: string;
+
+function email(label: string): string {
+    return `${label}-${randomUUID()}@example.test`;
+}
+
+async function request(
+    path: string,
+    init: RequestInit = {},
+): Promise<{ response: Response; body: unknown }> {
+    const response = await fetch(`${baseUrl}${path}`, {
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            ...init.headers,
+        },
+    });
+    return {
+        response,
+        body: response.status === 204 ? undefined : await response.json(),
+    };
+}
+
+function expectSuccess<T>(body: unknown): SuccessResponse<T> {
+    assert.ok(body && typeof body === 'object' && 'data' in body);
+    return body as SuccessResponse<T>;
+}
+
+function expectError(body: unknown): ErrorResponse {
+    assert.ok(body && typeof body === 'object' && 'error' in body);
+    return body as ErrorResponse;
+}
+
+function refreshCookie(response: Response): string {
+    const cookie = response.headers.get('set-cookie');
+    assert.ok(cookie, '认证成功响应必须写入 refresh cookie');
+    assert.match(cookie, /HttpOnly/i);
+    const match = cookie.match(/atlas_refresh=[^;]+/);
+    assert.ok(match, '响应必须包含 atlas_refresh cookie');
+    return match[0];
+}
+
+describe('认证 HTTP 集成测试', () => {
+    beforeAll(async () => {
+        Object.assign(process.env, {
+            NODE_ENV: 'test',
+            SWAGGER_ENABLED: 'false',
+            AUTH_LOGIN_IP_LIMIT: '100',
+            AUTH_LOGIN_EMAIL_LIMIT: '2',
+            AUTH_REGISTER_IP_LIMIT: '100',
+            AUTH_REGISTER_EMAIL_LIMIT: '100',
+            AUTH_REFRESH_IP_LIMIT: '100',
+        });
+        const application = await createApplication();
+        app = application.app;
+        database = app.get<Database>(DATABASE);
+        await app.listen(0, '127.0.0.1');
+        const address = app.getHttpServer().address() as AddressInfo;
+        baseUrl = `http://127.0.0.1:${address.port}`;
+    });
+
+    afterAll(async () => {
+        for (const user of testUsers) {
+            await database.workspaceTransaction(
+                user.workspaceId,
+                async (tx) => {
+                    await tx.query(
+                        'DELETE FROM atlas.idempotency_requests WHERE workspace_id = $1',
+                        [user.workspaceId],
+                    );
+                },
+            );
+            await database.query(
+                'DELETE FROM atlas.workspace_memberships WHERE user_id = $1',
+                [user.userId],
+            );
+            await database.query('DELETE FROM atlas.workspaces WHERE id = $1', [
+                user.workspaceId,
+            ]);
+            await database.query('DELETE FROM atlas.users WHERE id = $1', [
+                user.userId,
+            ]);
+        }
+        await app.close();
+    });
+
+    it('健康与 readiness 端点保持公开', async () => {
+        const health = await request('/health');
+        assert.equal(health.response.status, 200);
+        assert.deepEqual(health.body, { status: 'ok', service: 'api' });
+
+        const readiness = await request('/ready');
+        assert.equal(readiness.response.status, 200);
+        assert.deepEqual(readiness.body, { status: 'ready', service: 'api' });
+    });
+
+    it('注册、重复邮箱和参数校验遵守响应契约', async () => {
+        const registrationEmail = email('register');
+        const registration = await request('/api/auth/register', {
+            method: 'POST',
+            body: JSON.stringify({
+                email: registrationEmail,
+                password,
+                password_confirmation: password,
+                display_name: '集成测试用户',
+            }),
+        });
+        assert.equal(registration.response.status, 201);
+        const payload = expectSuccess<SessionPayload>(registration.body).data;
+        assert.equal(payload.user.email, registrationEmail);
+        assert.equal(payload.workspace.role, 'owner');
+        assert.ok(payload.access_token);
+        assert.ok(payload.access_token_expires_in > 0);
+        refreshCookie(registration.response);
+        testUsers.push({
+            userId: payload.user.id,
+            workspaceId: payload.workspace.id,
+        });
+
+        const duplicate = await request('/api/auth/register', {
+            method: 'POST',
+            body: JSON.stringify({
+                email: registrationEmail,
+                password,
+                password_confirmation: password,
+            }),
+        });
+        assert.equal(duplicate.response.status, 409);
+        assert.equal(
+            expectError(duplicate.body).error.code,
+            'EMAIL_ALREADY_REGISTERED',
+        );
+
+        const invalid = await request('/api/auth/register', {
+            method: 'POST',
+            body: JSON.stringify({
+                email: 'not-an-email',
+                password,
+                password_confirmation: password,
+            }),
+        });
+        assert.equal(invalid.response.status, 422);
+        assert.equal(expectError(invalid.body).error.code, 'VALIDATION_FAILED');
+    });
+
+    it('登录、刷新、退出和当前用户读取可形成完整会话闭环', async () => {
+        const accountEmail = email('session');
+        const registration = await request('/api/auth/register', {
+            method: 'POST',
+            body: JSON.stringify({
+                email: accountEmail,
+                password,
+                password_confirmation: password,
+            }),
+        });
+        const registered = expectSuccess<SessionPayload>(
+            registration.body,
+        ).data;
+        testUsers.push({
+            userId: registered.user.id,
+            workspaceId: registered.workspace.id,
+        });
+
+        const login = await request('/api/auth/login', {
+            method: 'POST',
+            body: JSON.stringify({ email: accountEmail, password }),
+        });
+        assert.equal(login.response.status, 200);
+        const loggedIn = expectSuccess<SessionPayload>(login.body).data;
+        const loginRefreshCookie = refreshCookie(login.response);
+
+        const currentUser = await request('/api/auth/me', {
+            headers: { Authorization: `Bearer ${loggedIn.access_token}` },
+        });
+        assert.equal(currentUser.response.status, 200);
+        const me = expectSuccess<{
+            user: { id: string };
+            workspace: { id: string };
+        }>(currentUser.body).data;
+        assert.equal(me.user.id, registered.user.id);
+        assert.equal(me.workspace.id, registered.workspace.id);
+
+        const refresh = await request('/api/auth/refresh', {
+            method: 'POST',
+            headers: { Cookie: loginRefreshCookie },
+        });
+        assert.equal(refresh.response.status, 200);
+        const refreshed = expectSuccess<{
+            access_token: string;
+            access_token_expires_in: number;
+        }>(refresh.body).data;
+        assert.ok(refreshed.access_token);
+        const refreshedCookie = refreshCookie(refresh.response);
+
+        const reusedRefresh = await request('/api/auth/refresh', {
+            method: 'POST',
+            headers: { Cookie: loginRefreshCookie },
+        });
+        assert.equal(reusedRefresh.response.status, 401);
+        assert.equal(
+            expectError(reusedRefresh.body).error.code,
+            'SESSION_EXPIRED',
+        );
+
+        const logout = await request('/api/auth/logout', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${refreshed.access_token}`,
+                Cookie: refreshedCookie,
+            },
+        });
+        assert.equal(logout.response.status, 204);
+        assert.equal(logout.body, undefined);
+
+        const revoked = await request('/api/auth/me', {
+            headers: { Authorization: `Bearer ${refreshed.access_token}` },
+        });
+        assert.equal(revoked.response.status, 401);
+    });
+
+    it('拒绝错误密码、无效访问令牌和超过邮箱限额的登录请求', async () => {
+        const accountEmail = email('rejected');
+        const wrongPassword = await request('/api/auth/login', {
+            method: 'POST',
+            body: JSON.stringify({ email: accountEmail, password }),
+        });
+        assert.equal(wrongPassword.response.status, 401);
+        const wrongPasswordError = expectError(wrongPassword.body).error;
+        assert.equal(wrongPasswordError.code, 'INVALID_CREDENTIALS');
+        assert.equal(
+            wrongPasswordError.request_id,
+            wrongPassword.response.headers.get('x-request-id'),
+        );
+
+        const invalidToken = await request('/api/auth/me', {
+            headers: { Authorization: 'Bearer invalid-access-token' },
+        });
+        assert.equal(invalidToken.response.status, 401);
+        assert.equal(expectError(invalidToken.body).error.code, 'HTTP_ERROR');
+
+        const rateLimitedEmail = email('rate-limit');
+        for (const expectedStatus of [401, 401, 429]) {
+            const response = await request('/api/auth/login', {
+                method: 'POST',
+                body: JSON.stringify({ email: rateLimitedEmail, password }),
+            });
+            assert.equal(response.response.status, expectedStatus);
+            if (expectedStatus === 429) {
+                assert.equal(
+                    expectError(response.body).error.code,
+                    'AUTH_RATE_LIMITED',
+                );
+            }
+        }
+    });
+
+    it('更新资料遵守版本与幂等约束，改密会撤销旧会话并轮换当前会话', async () => {
+        const accountEmail = email('profile-password');
+        const registration = await request('/api/auth/register', {
+            method: 'POST',
+            body: JSON.stringify({
+                email: accountEmail,
+                password,
+                password_confirmation: password,
+                display_name: '原始名称',
+            }),
+        });
+        const registered = expectSuccess<SessionPayload>(
+            registration.body,
+        ).data;
+        testUsers.push({
+            userId: registered.user.id,
+            workspaceId: registered.workspace.id,
+        });
+
+        const profileKey = randomUUID();
+        const update = await request('/api/auth/me', {
+            method: 'PATCH',
+            headers: {
+                Authorization: `Bearer ${registered.access_token}`,
+                'If-Match': `"${registered.user.revision}"`,
+                'Idempotency-Key': profileKey,
+            },
+            body: JSON.stringify({ display_name: '更新后的名称' }),
+        });
+        assert.equal(update.response.status, 200);
+        const updatedUser = expectSuccess<SessionPayload['user']>(
+            update.body,
+        ).data;
+        assert.equal(updatedUser.display_name, '更新后的名称');
+        assert.equal(updatedUser.avatar_asset_id, null);
+        assert.equal(updatedUser.revision, registered.user.revision + 1);
+
+        const replay = await request('/api/auth/me', {
+            method: 'PATCH',
+            headers: {
+                Authorization: `Bearer ${registered.access_token}`,
+                'If-Match': `"${registered.user.revision}"`,
+                'Idempotency-Key': profileKey,
+            },
+            body: JSON.stringify({ display_name: '更新后的名称' }),
+        });
+        assert.equal(replay.response.status, 200);
+        assert.deepEqual(replay.body, update.body);
+
+        const stale = await request('/api/auth/me', {
+            method: 'PATCH',
+            headers: {
+                Authorization: `Bearer ${registered.access_token}`,
+                'If-Match': `"${registered.user.revision}"`,
+                'Idempotency-Key': randomUUID(),
+            },
+            body: JSON.stringify({ display_name: '过期修改' }),
+        });
+        assert.equal(stale.response.status, 409);
+        assert.equal(expectError(stale.body).error.code, 'VERSION_CONFLICT');
+
+        const invalidAvatar = await request('/api/auth/me', {
+            method: 'PATCH',
+            headers: {
+                Authorization: `Bearer ${registered.access_token}`,
+                'If-Match': `"${updatedUser.revision}"`,
+                'Idempotency-Key': randomUUID(),
+            },
+            body: JSON.stringify({ avatar_asset_id: randomUUID() }),
+        });
+        assert.equal(invalidAvatar.response.status, 422);
+        assert.equal(
+            expectError(invalidAvatar.body).error.code,
+            'AVATAR_ASSET_UNAVAILABLE',
+        );
+
+        const secondLogin = await request('/api/auth/login', {
+            method: 'POST',
+            body: JSON.stringify({ email: accountEmail, password }),
+        });
+        const otherSession = expectSuccess<SessionPayload>(
+            secondLogin.body,
+        ).data;
+
+        const changed = await request('/api/auth/change-password', {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${registered.access_token}` },
+            body: JSON.stringify({
+                old_password: password,
+                password: 'new-correct-horse-battery-staple-456',
+                password_confirmation: 'new-correct-horse-battery-staple-456',
+            }),
+        });
+        assert.equal(changed.response.status, 200);
+        const rotated = expectSuccess<{
+            access_token: string;
+            access_token_expires_in: number;
+        }>(changed.body).data;
+        assert.ok(rotated.access_token);
+        refreshCookie(changed.response);
+
+        const formerCurrent = await request('/api/auth/me', {
+            headers: { Authorization: `Bearer ${registered.access_token}` },
+        });
+        assert.equal(formerCurrent.response.status, 401);
+        const revokedOther = await request('/api/auth/me', {
+            headers: { Authorization: `Bearer ${otherSession.access_token}` },
+        });
+        assert.equal(revokedOther.response.status, 401);
+        const current = await request('/api/auth/me', {
+            headers: { Authorization: `Bearer ${rotated.access_token}` },
+        });
+        assert.equal(current.response.status, 200);
+
+        const oldPasswordChange = await request('/api/auth/change-password', {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${rotated.access_token}` },
+            body: JSON.stringify({
+                old_password: password,
+                password: 'another-correct-horse-battery-staple-789',
+                password_confirmation:
+                    'another-correct-horse-battery-staple-789',
+            }),
+        });
+        assert.equal(oldPasswordChange.response.status, 422);
+        assert.equal(
+            expectError(oldPasswordChange.body).error.code,
+            'VALIDATION_FAILED',
+        );
+        const newPasswordLogin = await request('/api/auth/login', {
+            method: 'POST',
+            body: JSON.stringify({
+                email: accountEmail,
+                password: 'new-correct-horse-battery-staple-456',
+            }),
+        });
+        assert.equal(newPasswordLogin.response.status, 200);
+    });
+});

apps/api/test/collection.e2e.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import type { AddressInfo } from 'node:net';
+import type { Database } from '@atlas/database';
+import type { NestExpressApplication } from '@nestjs/platform-express';
+import { afterAll, beforeAll, describe, it } from 'vitest';
+import { DATABASE } from '../src/database/database.module.js';
+import { createApplication } from '../src/main.js';
+
+let app: NestExpressApplication; let database: Database; let baseUrl: string; let userId = ''; let workspaceId = ''; let token = ''; let platformId = '';
+async function request(path: string, init: RequestInit = {}) { const response = await fetch(`${baseUrl}${path}`, { ...init, headers: { 'Content-Type': 'application/json', ...init.headers } }); return { response, body: response.status === 204 ? undefined : await response.json() as any }; }
+function headers(extra: Record<string, string> = {}) { return { Authorization: `Bearer ${token}`, ...extra }; }
+describe('采集箱 HTTP 集成测试', () => {
+  beforeAll(async () => { Object.assign(process.env, { NODE_ENV: 'test', SWAGGER_ENABLED: 'false', AUTH_REGISTER_IP_LIMIT: '100', AUTH_REGISTER_EMAIL_LIMIT: '100' }); const application = await createApplication(); app = application.app; database = app.get<Database>(DATABASE); await app.listen(0, '127.0.0.1'); baseUrl = `http://127.0.0.1:${(app.getHttpServer().address() as AddressInfo).port}`; const registration = await request('/api/auth/register', { method: 'POST', body: JSON.stringify({ email: `collection-${randomUUID()}@example.test`, password: 'correct-horse-battery-staple-123', password_confirmation: 'correct-horse-battery-staple-123' }) }); assert.equal(registration.response.status, 201); token = registration.body.data.access_token; userId = registration.body.data.user.id; workspaceId = registration.body.data.workspace.id; const platforms = await request('/api/platforms', { headers: headers() }); platformId = platforms.body.data[0].id; });
+  afterAll(async () => { await database.workspaceTransaction(workspaceId, async (tx) => { await tx.query('DELETE FROM atlas.idempotency_requests WHERE workspace_id = $1', [workspaceId]); await tx.query('DELETE FROM atlas.outbox_events WHERE workspace_id = $1', [workspaceId]); await tx.query('DELETE FROM atlas.operations WHERE workspace_id = $1', [workspaceId]); await tx.query('DELETE FROM atlas.product_variants WHERE workspace_id = $1', [workspaceId]); await tx.query('DELETE FROM atlas.products WHERE workspace_id = $1', [workspaceId]); await tx.query('DELETE FROM atlas.collection_items WHERE workspace_id = $1', [workspaceId]); }); await database.query('DELETE FROM atlas.workspace_memberships WHERE user_id = $1', [userId]); await database.query('DELETE FROM atlas.workspaces WHERE id = $1', [workspaceId]); await database.query('DELETE FROM atlas.users WHERE id = $1', [userId]); await app.close(); });
+  it('创建、查询、乐观锁更新与软删除采集草稿', async () => { const key = randomUUID(); const created = await request('/api/collection-items', { method: 'POST', headers: headers({ 'Idempotency-Key': key }), body: JSON.stringify({ title: '手动商品', note: '初始备注' }) }); assert.equal(created.response.status, 201); const item = created.body.data.collection_item; assert.equal(item.variant_summary.count, 1); const replay = await request('/api/collection-items', { method: 'POST', headers: headers({ 'Idempotency-Key': key }), body: JSON.stringify({ title: '手动商品', note: '初始备注' }) }); assert.deepEqual(replay.body, created.body); const listed = await request('/api/collection-items', { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }); assert.equal(listed.response.status, 200); assert.equal(listed.body.data[0].id, item.id); const updated = await request(`/api/collection-items/${item.id}`, { method: 'PATCH', headers: headers({ 'Idempotency-Key': randomUUID(), 'If-Match': `"${item.revision}"` }), body: JSON.stringify({ note: '已修改' }) }); assert.equal(updated.response.status, 200); const stale = await request(`/api/collection-items/${item.id}`, { method: 'PATCH', headers: headers({ 'Idempotency-Key': randomUUID(), 'If-Match': `"${item.revision}"` }), body: JSON.stringify({ note: '过期写入' }) }); assert.equal(stale.response.status, 409); const removed = await request('/api/collection-items/bulk-delete', { method: 'POST', headers: headers({ 'Idempotency-Key': randomUUID() }), body: JSON.stringify({ ids: [item.id] }) }); assert.equal(removed.response.status, 202); assert.equal(removed.body.data.deleted_count, 1); });
+});

apps/api/test/stores.e2e.test.ts

@@ -0,0 +1,311 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import type { AddressInfo } from 'node:net';
+import type { Database } from '@atlas/database';
+import type { NestExpressApplication } from '@nestjs/platform-express';
+import { afterAll, beforeAll, describe, it } from 'vitest';
+import { DATABASE } from '../src/database/database.module.js';
+import { createApplication } from '../src/main.js';
+
+type SuccessResponse<T> = { data: T };
+type ErrorResponse = { error: { code: string } };
+type Session = {
+    access_token: string;
+    user: { id: string };
+    workspace: { id: string };
+};
+type Store = {
+    id: string;
+    name: string;
+    is_default: boolean;
+    status: string;
+    credential_status: string;
+    revision: number;
+};
+
+const password = 'correct-horse-battery-staple-123';
+const testUsers: Array<{ userId: string; workspaceId: string }> = [];
+let app: NestExpressApplication;
+let database: Database;
+let baseUrl: string;
+
+function email(label: string) {
+    return `${label}-${randomUUID()}@example.test`;
+}
+
+async function request(path: string, init: RequestInit = {}) {
+    const response = await fetch(`${baseUrl}${path}`, {
+        ...init,
+        headers: { 'Content-Type': 'application/json', ...init.headers },
+    });
+    return {
+        response,
+        body: response.status === 204 ? undefined : await response.json(),
+    };
+}
+
+function success<T>(body: unknown): SuccessResponse<T> {
+    assert.ok(body && typeof body === 'object' && 'data' in body);
+    return body as SuccessResponse<T>;
+}
+
+function error(body: unknown): ErrorResponse {
+    assert.ok(body && typeof body === 'object' && 'error' in body);
+    return body as ErrorResponse;
+}
+
+async function register(label: string): Promise<Session> {
+    const result = await request('/api/auth/register', {
+        method: 'POST',
+        body: JSON.stringify({
+            email: email(label),
+            password,
+            password_confirmation: password,
+        }),
+    });
+    assert.equal(result.response.status, 201);
+    const session = success<Session>(result.body).data;
+    testUsers.push({
+        userId: session.user.id,
+        workspaceId: session.workspace.id,
+    });
+    return session;
+}
+
+function headers(session: Session, idempotencyKey?: string) {
+    return {
+        Authorization: `Bearer ${session.access_token}`,
+        ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+    };
+}
+
+describe('门店 HTTP 集成测试', () => {
+    beforeAll(async () => {
+        Object.assign(process.env, {
+            NODE_ENV: 'test',
+            SWAGGER_ENABLED: 'false',
+            AUTH_LOGIN_IP_LIMIT: '100',
+            AUTH_LOGIN_EMAIL_LIMIT: '100',
+            AUTH_REGISTER_IP_LIMIT: '100',
+            AUTH_REGISTER_EMAIL_LIMIT: '100',
+            AUTH_REFRESH_IP_LIMIT: '100',
+        });
+        const application = await createApplication();
+        app = application.app;
+        database = app.get<Database>(DATABASE);
+        await app.listen(0, '127.0.0.1');
+        const address = app.getHttpServer().address() as AddressInfo;
+        baseUrl = `http://127.0.0.1:${address.port}`;
+    });
+
+    afterAll(async () => {
+        for (const user of testUsers) {
+            // 门店测试会创建操作和 Outbox；先在工作空间事务内清理这些受 RLS 保护的记录。
+            await database.workspaceTransaction(
+                user.workspaceId,
+                async (tx) => {
+                    await tx.query(
+                        'DELETE FROM atlas.idempotency_requests WHERE workspace_id = $1',
+                        [user.workspaceId],
+                    );
+                    await tx.query(
+                        'DELETE FROM atlas.outbox_events WHERE workspace_id = $1',
+                        [user.workspaceId],
+                    );
+                    await tx.query(
+                        'DELETE FROM atlas.operations WHERE workspace_id = $1',
+                        [user.workspaceId],
+                    );
+                    await tx.query(
+                        'DELETE FROM atlas.stores WHERE workspace_id = $1',
+                        [user.workspaceId],
+                    );
+                },
+            );
+            await database.query(
+                'DELETE FROM atlas.workspace_memberships WHERE user_id = $1',
+                [user.userId],
+            );
+            await database.query('DELETE FROM atlas.workspaces WHERE id = $1', [
+                user.workspaceId,
+            ]);
+            await database.query('DELETE FROM atlas.users WHERE id = $1', [
+                user.userId,
+            ]);
+        }
+        await app.close();
+    });
+
+    it('创建门店时加密保存凭据、创建操作，并能安全重放相同请求', async () => {
+        const owner = await register('stores-owner');
+        const platforms = await request('/api/platforms', {
+            headers: headers(owner),
+        });
+        assert.equal(platforms.response.status, 200);
+        const platform = success<
+            Array<{
+                id: string;
+                code: string;
+                default_market_code: string | null;
+                default_locale: string | null;
+            }>
+        >(platforms.body).data.find((item) => item.code === 'OZON');
+        assert.ok(platform);
+        assert.equal(platform.default_market_code, 'RU');
+        assert.equal(platform.default_locale, 'ru-RU');
+
+        const idempotencyKey = randomUUID();
+        const createBody = {
+            platform_id: platform.id,
+            name: '测试 Ozon 主店',
+            client_id: `client-${randomUUID()}`,
+            api_key: 'secret-only-in-request',
+            currency_code: 'RUB',
+            is_default: false,
+            note: '首家门店仍应成为默认门店',
+        };
+        const created = await request('/api/stores', {
+            method: 'POST',
+            headers: headers(owner, idempotencyKey),
+            body: JSON.stringify(createBody),
+        });
+        assert.equal(created.response.status, 202);
+        const createdData = success<{
+            store: Store & { platform_client_id: string };
+            operation: { id: string; status: string };
+        }>(created.body).data;
+        assert.equal(createdData.store.is_default, true);
+        assert.equal(createdData.store.status, 'verifying');
+        assert.equal(createdData.store.credential_status, 'unknown');
+        assert.equal(
+            createdData.store.platform_client_id,
+            createBody.client_id,
+        );
+        assert.equal(createdData.operation.status, 'queued');
+        assert.equal(
+            JSON.stringify(created.body).includes(createBody.api_key),
+            false,
+        );
+
+        const replay = await request('/api/stores', {
+            method: 'POST',
+            headers: headers(owner, idempotencyKey),
+            body: JSON.stringify(createBody),
+        });
+        assert.equal(replay.response.status, 202);
+        assert.deepEqual(replay.body, created.body);
+
+        const mismatchedReplay = await request('/api/stores', {
+            method: 'POST',
+            headers: headers(owner, idempotencyKey),
+            body: JSON.stringify({ ...createBody, name: '不同请求' }),
+        });
+        assert.equal(mismatchedReplay.response.status, 409);
+        assert.equal(
+            error(mismatchedReplay.body).error.code,
+            'IDEMPOTENCY_KEY_REUSED',
+        );
+
+        const context = await request('/api/platform-context', {
+            headers: {
+                ...headers(owner),
+                'X-Atlas-Platform-Id': platform.id,
+            },
+        });
+        assert.equal(context.response.status, 200);
+        assert.equal(
+            success<{ store_count: number; default_store: { id: string } }>(
+                context.body,
+            ).data.store_count,
+            1,
+        );
+
+        const operation = await request(
+            `/api/operations/${createdData.operation.id}`,
+            { headers: headers(owner) },
+        );
+        assert.equal(operation.response.status, 200);
+        assert.equal(
+            success<{ status: string }>(operation.body).data.status,
+            'queued',
+        );
+    });
+
+    it('更新版本、切换默认门店、删除和工作空间隔离都遵守契约', async () => {
+        const owner = await register('stores-lifecycle');
+        const otherOwner = await register('stores-isolation');
+        const platforms = await request('/api/platforms', {
+            headers: headers(owner),
+        });
+        const platform = success<Array<{ id: string; code: string }>>(
+            platforms.body,
+        ).data.find((item) => item.code === 'OZON');
+        assert.ok(platform);
+
+        const first = await createStore(owner, platform.id, '第一家门店');
+        const updated = await request(`/api/stores/${first.id}`, {
+            method: 'PATCH',
+            headers: {
+                ...headers(owner, randomUUID()),
+                'If-Match': `"${first.revision}"`,
+            },
+            body: JSON.stringify({ name: '第一家门店（已修改）' }),
+        });
+        assert.equal(updated.response.status, 200);
+        const updatedStore = success<Store>(updated.body).data;
+        assert.equal(updatedStore.revision, first.revision + 1);
+
+        const stale = await request(`/api/stores/${first.id}`, {
+            method: 'PATCH',
+            headers: {
+                ...headers(owner, randomUUID()),
+                'If-Match': `"${first.revision}"`,
+            },
+            body: JSON.stringify({ name: '过期修改' }),
+        });
+        assert.equal(stale.response.status, 409);
+        assert.equal(error(stale.body).error.code, 'VERSION_CONFLICT');
+
+        const second = await createStore(owner, platform.id, '第二家门店');
+        const makeDefault = await request(
+            `/api/stores/${second.id}/set-default`,
+            {
+                method: 'POST',
+                headers: headers(owner, randomUUID()),
+            },
+        );
+        assert.equal(makeDefault.response.status, 200);
+        assert.equal(success<Store>(makeDefault.body).data.is_default, true);
+
+        const foreignRead = await request(`/api/stores/${first.id}`, {
+            headers: headers(otherOwner),
+        });
+        assert.equal(foreignRead.response.status, 404);
+
+        const deleted = await request(`/api/stores/${first.id}`, {
+            method: 'DELETE',
+            headers: headers(owner, randomUUID()),
+        });
+        assert.equal(deleted.response.status, 204);
+        const absent = await request(`/api/stores/${first.id}`, {
+            headers: headers(owner),
+        });
+        assert.equal(absent.response.status, 404);
+    });
+});
+
+async function createStore(owner: Session, platformId: string, name: string) {
+    const result = await request('/api/stores', {
+        method: 'POST',
+        headers: headers(owner, randomUUID()),
+        body: JSON.stringify({
+            platform_id: platformId,
+            name,
+            client_id: `client-${randomUUID()}`,
+            api_key: `key-${randomUUID()}`,
+            currency_code: 'RUB',
+        }),
+    });
+    assert.equal(result.response.status, 202);
+    return success<{ store: Store }>(result.body).data.store;
+}

apps/api/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "rootDir": "src",
+        "outDir": "dist",
+        "types": ["node"],
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true
+    },
+    "include": ["src/**/*.ts"]
+}

apps/api/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "rootDir": ".",
+        "noEmit": true
+    },
+    "include": ["src/**/*.ts", "test/**/*.ts", "vitest.config.ts"]
+}

apps/api/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        include: ['test/**/*.test.ts'],
+        fileParallelism: false,
+        testTimeout: 30_000,
+    },
+});

apps/extension/.wxt/tsconfig.json

@@ -0,0 +1,55 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "paths": {
+      "@": [
+        ".."
+      ],
+      "@/*": [
+        "../*"
+      ],
+      "~": [
+        ".."
+      ],
+      "~/*": [
+        "../*"
+      ],
+      "@@": [
+        ".."
+      ],
+      "@@/*": [
+        "../*"
+      ],
+      "~~": [
+        ".."
+      ],
+      "~~/*": [
+        "../*"
+      ]
+    }
+  },
+  "include": [
+    "../**/*",
+    "./wxt.d.ts"
+  ],
+  "exclude": [
+    "../**/node_modules",
+    "../.output"
+  ]
+}

apps/extension/.wxt/types/globals.d.ts

@@ -0,0 +1,15 @@
+// Generated by wxt
+interface ImportMetaEnv {
+  readonly MANIFEST_VERSION: 2 | 3;
+  readonly BROWSER: string;
+  readonly CHROME: boolean;
+  readonly FIREFOX: boolean;
+  readonly SAFARI: boolean;
+  readonly EDGE: boolean;
+  readonly OPERA: boolean;
+  readonly COMMAND: "build" | "serve";
+  readonly ENTRYPOINT: string;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

apps/extension/.wxt/types/i18n.d.ts

@@ -0,0 +1,81 @@
+// Generated by wxt
+import "wxt/browser";
+
+declare module "wxt/browser" {
+  /**
+   * See https://developer.chrome.com/docs/extensions/reference/i18n/#method-getMessage
+   */
+  interface GetMessageOptions {
+    /**
+     * See https://developer.chrome.com/docs/extensions/reference/i18n/#method-getMessage
+     */
+    escapeLt?: boolean
+  }
+
+  export interface WxtI18n extends I18n.Static {
+    /**
+     * The extension or app ID; you might use this string to construct URLs for resources inside the extension. Even non-localized extensions can use this message.
+     * Note: You can't use this message in a manifest file.
+     *
+     * "<browser.runtime.id>"
+     */
+    getMessage(
+      messageName: "@@extension_id",
+      substitutions?: string | string[],
+      options?: GetMessageOptions,
+    ): string;
+    /**
+     * "<browser.i18n.getUiLocale()>"
+     */
+    getMessage(
+      messageName: "@@ui_locale",
+      substitutions?: string | string[],
+      options?: GetMessageOptions,
+    ): string;
+    /**
+     * The text direction for the current locale, either "ltr" for left-to-right languages such as English or "rtl" for right-to-left languages such as Japanese.
+     *
+     * "<ltr|rtl>"
+     */
+    getMessage(
+      messageName: "@@bidi_dir",
+      substitutions?: string | string[],
+      options?: GetMessageOptions,
+    ): string;
+    /**
+     * If the @@bidi_dir is "ltr", then this is "rtl"; otherwise, it's "ltr".
+     *
+     * "<rtl|ltr>"
+     */
+    getMessage(
+      messageName: "@@bidi_reversed_dir",
+      substitutions?: string | string[],
+      options?: GetMessageOptions,
+    ): string;
+    /**
+     * If the @@bidi_dir is "ltr", then this is "left"; otherwise, it's "right".
+     *
+     * "<left|right>"
+     */
+    getMessage(
+      messageName: "@@bidi_start_edge",
+      substitutions?: string | string[],
+      options?: GetMessageOptions,
+    ): string;
+    /**
+     * If the @@bidi_dir is "ltr", then this is "right"; otherwise, it's "left".
+     *
+     * "<right|left>"
+     */
+    getMessage(
+      messageName: "@@bidi_end_edge",
+      substitutions?: string | string[],
+      options?: GetMessageOptions,
+    ): string;
+    getMessage(
+      messageName: "@@extension_id" | "@@ui_locale" | "@@bidi_dir" | "@@bidi_reversed_dir" | "@@bidi_start_edge" | "@@bidi_end_edge",
+      substitutions?: string | string[],
+      options?: GetMessageOptions,
+    ): string;
+  }
+}

apps/extension/.wxt/types/imports-module.d.ts

@@ -0,0 +1,21 @@
+// Generated by wxt
+// Types for the #import virtual module
+declare module '#imports' {
+  export { browser, Browser } from 'wxt/browser';
+  export { storage, WxtStorage, WxtStorageItem, StorageArea, StorageItemKey, StorageAreaChanges, MigrationError } from 'wxt/utils/storage';
+  export { getAppConfig, useAppConfig } from 'wxt/utils/app-config';
+  export { ContentScriptContext, WxtWindowEventMap } from 'wxt/utils/content-script-context';
+  export { createIframeUi, IframeContentScriptUi, IframeContentScriptUiOptions } from 'wxt/utils/content-script-ui/iframe';
+  export { createIntegratedUi, IntegratedContentScriptUi, IntegratedContentScriptUiOptions } from 'wxt/utils/content-script-ui/integrated';
+  export { createShadowRootUi, ShadowRootContentScriptUi, ShadowRootContentScriptUiOptions } from 'wxt/utils/content-script-ui/shadow-root';
+  export { ContentScriptUi, ContentScriptUiOptions, ContentScriptOverlayAlignment, ContentScriptAppendMode, ContentScriptInlinePositioningOptions, ContentScriptOverlayPositioningOptions, ContentScriptModalPositioningOptions, ContentScriptPositioningOptions, ContentScriptAnchoredOptions, AutoMountOptions, StopAutoMount, AutoMount } from 'wxt/utils/content-script-ui/types';
+  export { defineAppConfig, WxtAppConfig } from 'wxt/utils/define-app-config';
+  export { defineBackground } from 'wxt/utils/define-background';
+  export { defineContentScript } from 'wxt/utils/define-content-script';
+  export { defineUnlistedScript } from 'wxt/utils/define-unlisted-script';
+  export { defineWxtPlugin } from 'wxt/utils/define-wxt-plugin';
+  export { injectScript, ScriptPublicPath, InjectScriptOptions } from 'wxt/utils/inject-script';
+  export { InvalidMatchPattern, MatchPattern } from 'wxt/utils/match-patterns';
+  export { useState, useCallback, useMemo, useEffect, useRef, useContext, useReducer } from 'react';
+  export { fakeBrowser } from 'wxt/testing/fake-browser';
+}

apps/extension/.wxt/types/imports.d.ts

@@ -0,0 +1,58 @@
+// Generated by wxt
+export {}
+declare global {
+  const ContentScriptContext: typeof import('wxt/utils/content-script-context').ContentScriptContext
+  const InvalidMatchPattern: typeof import('wxt/utils/match-patterns').InvalidMatchPattern
+  const MatchPattern: typeof import('wxt/utils/match-patterns').MatchPattern
+  const browser: typeof import('wxt/browser').browser
+  const createIframeUi: typeof import('wxt/utils/content-script-ui/iframe').createIframeUi
+  const createIntegratedUi: typeof import('wxt/utils/content-script-ui/integrated').createIntegratedUi
+  const createShadowRootUi: typeof import('wxt/utils/content-script-ui/shadow-root').createShadowRootUi
+  const defineAppConfig: typeof import('wxt/utils/define-app-config').defineAppConfig
+  const defineBackground: typeof import('wxt/utils/define-background').defineBackground
+  const defineContentScript: typeof import('wxt/utils/define-content-script').defineContentScript
+  const defineUnlistedScript: typeof import('wxt/utils/define-unlisted-script').defineUnlistedScript
+  const defineWxtPlugin: typeof import('wxt/utils/define-wxt-plugin').defineWxtPlugin
+  const fakeBrowser: typeof import('wxt/testing/fake-browser').fakeBrowser
+  const getAppConfig: typeof import('wxt/utils/app-config').getAppConfig
+  const injectScript: typeof import('wxt/utils/inject-script').injectScript
+  const storage: typeof import('wxt/utils/storage').storage
+  const useAppConfig: typeof import('wxt/utils/app-config').useAppConfig
+  const useCallback: typeof import('react').useCallback
+  const useContext: typeof import('react').useContext
+  const useEffect: typeof import('react').useEffect
+  const useMemo: typeof import('react').useMemo
+  const useReducer: typeof import('react').useReducer
+  const useRef: typeof import('react').useRef
+  const useState: typeof import('react').useState
+}
+// for type re-export
+declare global {
+  // @ts-ignore
+  export type { Browser } from 'wxt/browser'
+  import('wxt/browser')
+  // @ts-ignore
+  export type { WxtStorage, WxtStorageItem, StorageArea, StorageItemKey, StorageAreaChanges, MigrationError } from 'wxt/utils/storage'
+  import('wxt/utils/storage')
+  // @ts-ignore
+  export type { WxtWindowEventMap } from 'wxt/utils/content-script-context'
+  import('wxt/utils/content-script-context')
+  // @ts-ignore
+  export type { IframeContentScriptUi, IframeContentScriptUiOptions } from 'wxt/utils/content-script-ui/iframe'
+  import('wxt/utils/content-script-ui/iframe')
+  // @ts-ignore
+  export type { IntegratedContentScriptUi, IntegratedContentScriptUiOptions } from 'wxt/utils/content-script-ui/integrated'
+  import('wxt/utils/content-script-ui/integrated')
+  // @ts-ignore
+  export type { ShadowRootContentScriptUi, ShadowRootContentScriptUiOptions } from 'wxt/utils/content-script-ui/shadow-root'
+  import('wxt/utils/content-script-ui/shadow-root')
+  // @ts-ignore
+  export type { ContentScriptUi, ContentScriptUiOptions, ContentScriptOverlayAlignment, ContentScriptAppendMode, ContentScriptInlinePositioningOptions, ContentScriptOverlayPositioningOptions, ContentScriptModalPositioningOptions, ContentScriptPositioningOptions, ContentScriptAnchoredOptions, AutoMountOptions, StopAutoMount, AutoMount } from 'wxt/utils/content-script-ui/types'
+  import('wxt/utils/content-script-ui/types')
+  // @ts-ignore
+  export type { WxtAppConfig } from 'wxt/utils/define-app-config'
+  import('wxt/utils/define-app-config')
+  // @ts-ignore
+  export type { ScriptPublicPath, InjectScriptOptions } from 'wxt/utils/inject-script'
+  import('wxt/utils/inject-script')
+}

apps/extension/.wxt/types/paths.d.ts

@@ -0,0 +1,14 @@
+// Generated by wxt
+import "wxt/browser";
+
+declare module "wxt/browser" {
+  export type PublicPath =
+    | ""
+    | "/"
+    | "/background.js"
+  type HtmlPublicPath = Extract<PublicPath, `${string}.html`>
+  export interface WxtRuntime {
+    getURL(path: PublicPath): string;
+    getURL(path: `${HtmlPublicPath}${string}`): string;
+  }
+}

apps/extension/.wxt/wxt.d.ts

@@ -0,0 +1,8 @@
+// Generated by wxt
+/// <reference types="wxt/vite-builder-env" />
+/// <reference types="@wxt-dev/module-react" />
+/// <reference path="./types/paths.d.ts" />
+/// <reference path="./types/i18n.d.ts" />
+/// <reference path="./types/globals.d.ts" />
+/// <reference path="./types/imports-module.d.ts" />
+/// <reference path="./types/imports.d.ts" />

apps/extension/entrypoints/background.ts

@@ -0,0 +1,3 @@
+export default defineBackground(() => {
+    console.info('Atlas collector background started.');
+});

apps/extension/package.json

@@ -0,0 +1,23 @@
+{
+    "name": "@atlas/extension",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "build": "wxt build",
+        "dev": "wxt",
+        "typecheck": "wxt prepare && tsc -p tsconfig.json --noEmit"
+    },
+    "dependencies": {
+        "@atlas/contracts": "workspace:*",
+        "@wxt-dev/module-react": "1.2.2",
+        "react": "19.2.8",
+        "react-dom": "19.2.8"
+    },
+    "devDependencies": {
+        "@types/react": "19.2.18",
+        "@types/react-dom": "19.2.5",
+        "typescript": "7.0.2",
+        "wxt": "0.21.4"
+    }
+}

apps/extension/tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "jsx": "react-jsx",
+        "noEmit": true
+    },
+    "include": ["**/*.ts", "**/*.tsx", ".wxt/**/*.ts"]
+}

apps/extension/wxt.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'wxt';
+
+export default defineConfig({
+    modules: ['@wxt-dev/module-react'],
+    // 扩展 dev server 固定 8110：默认取 3000–3010 第一个空闲端口，会漂移且易与常见服务冲突
+    dev: {
+        server: {
+            port: Number(process.env.EXTENSION_PORT ?? 8110),
+            strictPort: true,
+        },
+    },
+    manifest: {
+        name: 'Atlas Seller Kit Collector',
+        description: '将已确认的来源商品采集到 Atlas 工作空间。',
+        permissions: ['storage', 'identity'],
+        host_permissions: [
+            '*://*.ozon.ru/*',
+            '*://*.ozon.kz/*',
+            '*://*.ozon.by/*',
+            '*://*.1688.com/*',
+            '*://*.taobao.com/*',
+            '*://*.tmall.com/*',
+        ],
+    },
+});

apps/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Atlas Seller Kit</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>

apps/web/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@atlas/web",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "build": "tsc -b && vite build",
+        "dev": "vite",
+        "typecheck": "tsc -b --pretty false"
+    },
+    "dependencies": {
+        "@ant-design/icons": "6.3.4",
+        "@atlas/contracts": "workspace:*",
+        "antd": "6.6.2",
+        "axios": "1.20.0",
+        "dayjs": "1.11.23",
+        "react": "19.2.8",
+        "react-dom": "19.2.8",
+        "react-router-dom": "7.18.3"
+    },
+    "devDependencies": {
+        "@types/node": "26.3.0",
+        "@types/react": "19.2.18",
+        "@types/react-dom": "19.2.5",
+        "@vitejs/plugin-react": "6.1.1",
+        "typescript": "7.0.2",
+        "vite": "8.2.2"
+    }
+}

apps/web/prettier.config.mjs

@@ -0,0 +1,15 @@
+export default {
+    printWidth: 100,
+    tabWidth: 4,
+    useTabs: false,
+    semi: true,
+    singleQuote: true,
+    quoteProps: 'as-needed',
+    jsxSingleQuote: false,
+    trailingComma: 'es5',
+    bracketSpacing: true,
+    bracketSameLine: false,
+    arrowParens: 'always',
+    endOfLine: 'lf',
+    embeddedLanguageFormatting: 'auto',
+};

apps/web/src/App.css

@@ -0,0 +1,175 @@
+/* 全局应用级样式补充（主题变量见 index.css） */
+
+/* ── 设置类页面（修改资料 / 修改密码）：内容区居中卡片 ── */
+.settings-page {
+    display: flex;
+    justify-content: center;
+}
+
+.settings-card {
+    width: 100%;
+    max-width: 560px;
+    background: #fff;
+    border-radius: 10px;
+    /* 四周柔和阴影，与内容区背景拉开层次 */
+    box-shadow: 0 0 24px 0 rgba(17, 24, 39, 0.12);
+}
+
+.settings-card-title {
+    padding: 20px 32px;
+    font-size: 16px;
+    font-weight: 600;
+    color: var(--text-primary);
+    border-bottom: 1px solid var(--border-color);
+}
+
+.settings-card-body {
+    padding: 32px;
+}
+
+.settings-field-label {
+    font-size: 14px;
+    color: var(--text-primary);
+    margin-bottom: 12px;
+}
+
+.avatar-upload-area {
+    display: flex;
+    justify-content: center;
+}
+
+.avatar-upload-placeholder {
+    position: relative;
+    cursor: pointer;
+    border-radius: 50%;
+}
+
+.avatar-upload-overlay {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 4px;
+    color: #6b7280;
+    font-size: 13px;
+    border-radius: 50%;
+    background: transparent;
+    transition: background 0.2s;
+}
+
+.avatar-upload-placeholder:hover .avatar-upload-overlay {
+    background: rgba(255, 255, 255, 0.55);
+}
+
+.avatar-preview {
+    cursor: pointer;
+}
+
+.avatar-upload-hint {
+    text-align: center;
+    color: var(--text-secondary);
+    font-size: 12px;
+    line-height: 1.8;
+    margin: 12px 0 24px;
+}
+
+.profile-form {
+    max-width: 420px;
+    margin: 0 auto;
+}
+
+.settings-actions {
+    display: flex;
+    justify-content: center;
+    gap: 12px;
+    margin-top: 8px;
+}
+
+/* ── 水印管理 ── */
+.watermarks-load-more {
+    display: flex;
+    justify-content: center;
+    margin-top: 16px;
+}
+
+/* 3x3 水印位置九宫格 */
+.position-grid {
+    display: grid;
+    grid-template-columns: repeat(3, 44px);
+    grid-auto-rows: 44px;
+    gap: 8px;
+}
+
+.position-grid-cell {
+    border: 1px solid var(--border-color);
+    border-radius: 6px;
+    background: #f5f5f5;
+    cursor: pointer;
+    transition: all 0.2s;
+    padding: 0;
+}
+
+.position-grid-cell:hover {
+    border-color: var(--primary-light);
+}
+
+.position-grid-cell.active {
+    border-color: var(--primary-color);
+    background: rgba(139, 92, 246, 0.12);
+}
+
+/* 水印预览：模拟透明底图的棋盘格 */
+.watermark-preview {
+    display: flex;
+    padding: 12px;
+    box-sizing: border-box;
+    border: 1px dashed var(--border-color);
+    border-radius: 4px;
+    background-image: conic-gradient(#ececec 0 25%, #ffffff 0 50%, #ececec 0 75%, #ffffff 0);
+    background-size: 24px 24px;
+    overflow: hidden;
+}
+
+.watermark-form-actions {
+    display: flex;
+    justify-content: center;
+    gap: 12px;
+    margin-top: 8px;
+}
+
+/* ── 水印图片上传框 ── */
+.watermark-image-box {
+    width: 120px;
+    height: 120px;
+    border: 1px dashed var(--border-color);
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    overflow: hidden;
+    transition: border-color 0.2s;
+    position: relative;
+    background: #fafafa;
+}
+
+.watermark-image-box:hover {
+    border-color: var(--primary-color);
+}
+
+.watermark-image-box img {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+}
+
+.watermark-image-uploading {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(255, 255, 255, 0.7);
+}

apps/web/src/App.tsx

@@ -0,0 +1,40 @@
+import { ConfigProvider, App as AntdApp } from 'antd';
+import zhCN from 'antd/locale/zh_CN';
+import { RouterProvider } from 'react-router-dom';
+import { router } from './router';
+import { SessionProvider } from '@/services/session';
+import './App.css';
+
+function App() {
+    return (
+        <ConfigProvider
+            locale={zhCN}
+            theme={{
+                token: {
+                    colorPrimary: '#8b5cf6',
+                    // 全局圆角 10px，输入框/按钮/卡片等同步生效
+                    borderRadius: 10,
+                    // 全局正文字号 14px；输入类控件经 components 单独放大
+                    fontSize: 14,
+                    controlHeight: 34,
+                    controlHeightSM: 26,
+                },
+                components: {
+                    // 文本框：文本 16px、高度同步加高；按钮与表格/菜单等保持全局默认
+                    Input: { fontSize: 16, controlHeight: 40 },
+                    Select: { fontSize: 16, controlHeight: 40 },
+                    InputNumber: { fontSize: 16, controlHeight: 40 },
+                    DatePicker: { fontSize: 16, controlHeight: 40 },
+                },
+            }}
+        >
+            <AntdApp>
+                <SessionProvider>
+                    <RouterProvider router={router} />
+                </SessionProvider>
+            </AntdApp>
+        </ConfigProvider>
+    );
+}
+
+export default App;

apps/web/src/components/PagePlaceholder.tsx

@@ -0,0 +1,23 @@
+import { Card, Empty } from 'antd';
+
+interface PagePlaceholderProps {
+    title: string;
+    description: string;
+}
+
+/** 业务模块实现前的统一占位页 */
+const PagePlaceholder = ({ title, description }: PagePlaceholderProps) => (
+    <Card>
+        <Empty
+            image={Empty.PRESENTED_IMAGE_SIMPLE}
+            description={
+                <>
+                    <div>{title}</div>
+                    <div>{description}</div>
+                </>
+            }
+        />
+    </Card>
+);
+
+export default PagePlaceholder;

apps/web/src/components/SessionSplash.tsx

@@ -0,0 +1,18 @@
+import { Spin } from 'antd';
+
+/** 应用启动会话恢复期间的全屏占位，避免守卫闪烁跳转 */
+const SessionSplash = () => (
+    <div
+        style={{
+            minHeight: '100vh',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: 'var(--bg-color)',
+        }}
+    >
+        <Spin size="large" />
+    </div>
+);
+
+export default SessionSplash;

apps/web/src/components/WatermarkPreview.tsx

@@ -0,0 +1,97 @@
+import { useState } from 'react';
+import type { CSSProperties } from 'react';
+import { Typography } from 'antd';
+import type { WatermarkPosition } from '@atlas/contracts';
+import type { WatermarkTemplateConfig } from '@atlas/contracts';
+
+/** 九宫格位置选项，顺序与编辑器 3x3 网格一致 */
+export const WATERMARK_POSITION_OPTIONS: Array<{
+    value: WatermarkPosition;
+    label: string;
+    row: 0 | 1 | 2;
+    col: 0 | 1 | 2;
+}> = [
+    { value: 'top_left', label: '左上角', row: 0, col: 0 },
+    { value: 'top_center', label: '上居中', row: 0, col: 1 },
+    { value: 'top_right', label: '右上角', row: 0, col: 2 },
+    { value: 'middle_left', label: '左居中', row: 1, col: 0 },
+    { value: 'center', label: '正居中', row: 1, col: 1 },
+    { value: 'middle_right', label: '右居中', row: 1, col: 2 },
+    { value: 'bottom_left', label: '左下角', row: 2, col: 0 },
+    { value: 'bottom_center', label: '下居中', row: 2, col: 1 },
+    { value: 'bottom_right', label: '右下角', row: 2, col: 2 },
+];
+
+export const watermarkPositionLabel = (position: string): string =>
+    WATERMARK_POSITION_OPTIONS.find((option) => option.value === position)?.label ?? position;
+
+const POSITION_FLEX: Record<
+    WatermarkPosition,
+    Pick<CSSProperties, 'justifyContent' | 'alignItems'>
+> = {
+    top_left: { justifyContent: 'flex-start', alignItems: 'flex-start' },
+    top_center: { justifyContent: 'center', alignItems: 'flex-start' },
+    top_right: { justifyContent: 'flex-end', alignItems: 'flex-start' },
+    middle_left: { justifyContent: 'flex-start', alignItems: 'center' },
+    center: { justifyContent: 'center', alignItems: 'center' },
+    middle_right: { justifyContent: 'flex-end', alignItems: 'center' },
+    bottom_left: { justifyContent: 'flex-start', alignItems: 'flex-end' },
+    bottom_center: { justifyContent: 'center', alignItems: 'flex-end' },
+    bottom_right: { justifyContent: 'flex-end', alignItems: 'flex-end' },
+};
+
+interface WatermarkPreviewProps {
+    /** 允许传入部分字段：编辑弹窗按当前表单值实时渲染 */
+    config: Partial<WatermarkTemplateConfig>;
+    width?: number;
+    height?: number;
+}
+
+/**
+ * 按模板 config 在内置演示底图上实时渲染水印效果（docs/api/watermarks-and-assets.md §3.1），
+ * 不调用服务端渲染；图片使用响应中的短时 preview_url，过期时提示重新读取。
+ */
+const WatermarkPreview = ({ config, width = 320, height = 420 }: WatermarkPreviewProps) => {
+    const [imageBroken, setImageBroken] = useState(false);
+    const position = config.position ?? 'bottom_right';
+    const flex = POSITION_FLEX[position] ?? POSITION_FLEX.bottom_right;
+    const previewUrl = config.image_asset?.preview_url;
+
+    return (
+        <div
+            className="watermark-preview"
+            style={{ width, height, ...flex, opacity: Number(config.opacity ?? '1') }}
+        >
+            {config.image_asset ? (
+                imageBroken || !previewUrl ? (
+                    <Typography.Text type="secondary">图片预览已过期或不可用</Typography.Text>
+                ) : (
+                    <img
+                        src={previewUrl}
+                        alt="水印图片"
+                        style={{
+                            // scale_ratio 以底图短边为基准的视觉近似：1.0 ≈ 底图宽度的 60%
+                            width: Math.round(Number(config.scale_ratio ?? '1') * width * 0.6),
+                            maxWidth: '80%',
+                        }}
+                        onError={() => setImageBroken(true)}
+                    />
+                )
+            ) : (
+                <span
+                    style={{
+                        fontSize: config.font_size_px ?? 24,
+                        fontWeight: 600,
+                        color: '#111827',
+                        whiteSpace: 'nowrap',
+                        textShadow: '0 0 2px rgba(255,255,255,0.8)',
+                    }}
+                >
+                    {config.text_content || '文字水印'}
+                </span>
+            )}
+        </div>
+    );
+};
+
+export default WatermarkPreview;

apps/web/src/config/env.ts

@@ -0,0 +1,16 @@
+/**
+ * 环境变量配置（Vite 仅暴露 VITE_ 前缀变量）
+ */
+
+interface EnvConfig {
+    /** API 基础路径：开发环境由 vite 代理转发到 NestJS API */
+    apiBaseUrl: string;
+    appName: string;
+    debug: boolean;
+}
+
+export const envConfig: EnvConfig = {
+    apiBaseUrl: import.meta.env.VITE_API_BASE_URL ?? '/api',
+    appName: import.meta.env.VITE_APP_NAME ?? 'Atlas Seller Kit',
+    debug: import.meta.env.VITE_DEBUG === 'true',
+};

apps/web/src/index.css

@@ -0,0 +1,37 @@
+:root {
+    --primary-color: #8b5cf6;
+    --primary-light: #a78bfa;
+    --primary-dark: #7c3aed;
+    /* 侧边菜单背景（纯色，中间调；想再调直接改这里） */
+    --sider-bg: #6d28d9;
+    --text-primary: #1f2937;
+    --text-secondary: #6b7280;
+    --bg-color: #f9fafb;
+    --card-bg: #ffffff;
+    --border-color: #e5e7eb;
+}
+
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    font-family:
+        -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB',
+        'Microsoft YaHei', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans',
+        'Helvetica Neue', sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    background-color: var(--bg-color);
+    color: var(--text-primary);
+    /* 全局默认字号 14px，与 antd 主题 token 的 fontSize 保持一致 */
+    font-size: 14px;
+    line-height: 1.6;
+}
+
+#root {
+    min-height: 100vh;
+}

apps/web/src/layouts/AuthLayout.css

@@ -0,0 +1,70 @@
+.auth-page {
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 24px;
+    background:
+        radial-gradient(1000px 500px at 15% -10%, rgba(139, 92, 246, 0.14), transparent 60%),
+        radial-gradient(900px 480px at 95% 110%, rgba(109, 40, 217, 0.1), transparent 55%);
+}
+
+.auth-panel {
+    width: 100%;
+    max-width: 400px;
+}
+
+.auth-brand {
+    text-align: center;
+    margin-bottom: 24px;
+}
+
+.auth-logo {
+    font-size: 26px;
+    font-weight: 700;
+    color: var(--primary-dark);
+}
+
+.auth-logo-subtitle {
+    font-size: 13px;
+    color: var(--text-secondary);
+    margin-top: 2px;
+}
+
+.auth-card {
+    background: var(--card-bg);
+    border: 1px solid var(--border-color);
+    border-radius: 12px;
+    box-shadow: 0 10px 30px rgba(17, 24, 39, 0.06);
+    padding: 32px 28px;
+}
+
+.auth-title {
+    font-size: 20px;
+    font-weight: 600;
+    color: var(--text-primary);
+}
+
+.auth-subtitle {
+    font-size: 14px;
+    color: var(--text-secondary);
+    margin: 4px 0 20px;
+}
+
+.auth-footer {
+    margin-top: 16px;
+    text-align: center;
+    font-size: 14px;
+    color: var(--text-secondary);
+}
+
+.auth-footer a {
+    color: var(--primary-color);
+    font-weight: 500;
+}
+
+@media (max-width: 768px) {
+    .auth-card {
+        padding: 24px 20px;
+    }
+}

apps/web/src/layouts/AuthLayout.tsx

@@ -0,0 +1,39 @@
+import { useEffect } from 'react';
+import type { ReactNode } from 'react';
+import './AuthLayout.css';
+
+interface AuthLayoutProps {
+    /** 页面标题，如「登录」 */
+    title: string;
+    /** 标题下的一行说明 */
+    subtitle: string;
+    /** 卡片底部的切换入口 */
+    footer: ReactNode;
+    children: ReactNode;
+}
+
+/** 注册/登录共用的居中卡片布局，品牌视觉与 MainLayout 一致 */
+const AuthLayout = ({ title, subtitle, footer, children }: AuthLayoutProps) => {
+    useEffect(() => {
+        document.title = `${title} - Atlas Seller Kit`;
+    }, [title]);
+
+    return (
+        <div className="auth-page">
+            <div className="auth-panel">
+                <div className="auth-brand">
+                    <div className="auth-logo">Atlas Kit</div>
+                    <div className="auth-logo-subtitle">商品工作台</div>
+                </div>
+                <div className="auth-card">
+                    <div className="auth-title">{title}</div>
+                    <div className="auth-subtitle">{subtitle}</div>
+                    {children}
+                    <div className="auth-footer">{footer}</div>
+                </div>
+            </div>
+        </div>
+    );
+};
+
+export default AuthLayout;

apps/web/src/layouts/MainLayout.css

@@ -0,0 +1,225 @@
+.main-layout {
+    min-height: 100vh;
+}
+
+.main-sider {
+    background: var(--sider-bg) !important;
+    display: flex;
+    flex-direction: column;
+}
+
+.sidebar-header {
+    padding: 24px 20px;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+    text-align: center;
+    transition: padding 0.2s ease;
+}
+
+/* 折叠态收窄水平留白，与宽度动画同步 */
+.ant-layout-sider-collapsed .sidebar-header {
+    padding: 20px 8px;
+}
+
+.logo {
+    position: relative;
+    height: 31px;
+    line-height: 31px;
+    font-size: 22px;
+    font-weight: 700;
+    color: white;
+    margin-bottom: 4px;
+}
+
+/* 全称与缩写叠加存放，折叠时交叉淡入淡出 */
+.logo-full,
+.logo-short {
+    display: block;
+    white-space: nowrap;
+    transition:
+        opacity 0.2s ease,
+        transform 0.2s ease;
+}
+
+.logo-short {
+    position: absolute;
+    inset: 0;
+    opacity: 0;
+    transform: scale(0.5);
+}
+
+.ant-layout-sider-collapsed .logo-full {
+    opacity: 0;
+    transform: scale(0.5);
+}
+
+.ant-layout-sider-collapsed .logo-short {
+    opacity: 1;
+    transform: scale(1);
+}
+
+/* 副标题折叠时渐隐并收起占位高度 */
+.logo-subtitle {
+    max-height: 18px;
+    overflow: hidden;
+    opacity: 1;
+    font-size: 12px;
+    color: rgba(255, 255, 255, 0.8);
+    transition:
+        opacity 0.2s ease,
+        max-height 0.2s ease;
+}
+
+.ant-layout-sider-collapsed .logo-subtitle {
+    max-height: 0;
+    opacity: 0;
+}
+
+.main-header {
+    background: white !important;
+    padding: 0 20px 0 10px !important;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    box-shadow:
+        0 1px 3px 0 rgba(0, 0, 0, 0.1),
+        0 1px 2px 0 rgba(0, 0, 0, 0.06);
+    position: sticky;
+    top: 0;
+    z-index: 100;
+    height: 50px;
+    line-height: 1;
+}
+
+.header-left {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+}
+
+.header-right {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+}
+
+/* 页头平台选择器：图标 + 无边框下拉，视觉与用户触发区一致 */
+.platform-selector {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    padding: 2px 8px;
+    border-radius: 6px;
+    transition: background 0.2s;
+}
+
+.platform-selector:hover {
+    background: #f3f4f6;
+}
+
+.platform-selector-icon {
+    color: var(--primary-color);
+    font-size: 15px;
+}
+
+/* 头像 + 用户名触发区：hover 有浅色背景反馈，暗示可下拉 */
+.header-user-trigger {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 4px 8px;
+    border-radius: 6px;
+    cursor: pointer;
+    transition: background 0.2s;
+    max-width: 240px;
+}
+
+.header-user-trigger:hover {
+    background: #f3f4f6;
+}
+
+/* 用户名超长省略 */
+.header-user-name {
+    font-size: 13px;
+    font-weight: 600;
+    color: #1f2937;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.collapse-trigger,
+.mobile-menu-trigger {
+    font-size: 16px;
+    cursor: pointer;
+    color: #1f2937;
+    border-radius: 4px;
+    transition: background 0.2s;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    flex-shrink: 0;
+}
+
+.collapse-trigger:hover,
+.mobile-menu-trigger:hover {
+    background: #f9fafb;
+}
+
+.page-breadcrumb {
+    font-size: 14px;
+    line-height: 1;
+    white-space: nowrap;
+    /* 与 collapse-trigger 一致的 28px 盒子，内部垂直居中 */
+    min-height: 28px;
+    display: flex;
+    align-items: center;
+}
+
+/* 条目与分隔图标按垂直中心对齐，避免不同字号图标基线错位 */
+.page-breadcrumb ol {
+    display: flex;
+    align-items: center;
+}
+
+.page-breadcrumb li {
+    display: inline-flex;
+    align-items: center;
+}
+
+.page-breadcrumb .ant-breadcrumb-link {
+    display: inline-flex;
+    align-items: center;
+    color: #1f2937;
+}
+
+.breadcrumb-crumb {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+}
+
+.breadcrumb-crumb .anticon {
+    font-size: 15px;
+}
+
+.page-breadcrumb .ant-breadcrumb-separator {
+    color: #9ca3af;
+}
+
+.main-content {
+    padding: 20px;
+    background: #f3f4f6;
+    min-height: calc(100vh - 50px);
+}
+
+@media (max-width: 768px) {
+    .main-content {
+        padding: 16px;
+    }
+
+    .main-header {
+        padding: 0 16px !important;
+    }
+}

apps/web/src/layouts/MainLayout.tsx

@@ -0,0 +1,189 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Outlet, useLocation, useNavigate } from 'react-router-dom';
+import { Avatar, Breadcrumb, Drawer, Dropdown, Layout } from 'antd';
+import type { MenuProps } from 'antd';
+import {
+    LockOutlined,
+    LogoutOutlined,
+    MenuFoldOutlined,
+    MenuUnfoldOutlined,
+    RightOutlined,
+    UserOutlined,
+} from '@ant-design/icons';
+import SidebarMenu from './SidebarMenu';
+import PlatformSelector from './PlatformSelector';
+import { getBreadcrumbItems } from './menuConfig';
+import { useSession } from '@/services/session';
+import './MainLayout.css';
+
+const { Header, Sider, Content } = Layout;
+
+const MainLayout = () => {
+    const [collapsed, setCollapsed] = useState(false);
+    const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+    const [isMobile, setIsMobile] = useState(false);
+    const [loggingOut, setLoggingOut] = useState(false);
+    const location = useLocation();
+    const navigate = useNavigate();
+    const { session, logout } = useSession();
+
+    const breadcrumbItems = useMemo(
+        () =>
+            getBreadcrumbItems(location.pathname).map((crumb) => ({
+                title: (
+                    <span className="breadcrumb-crumb">
+                        {crumb.icon}
+                        <span>{crumb.label}</span>
+                    </span>
+                ),
+            })),
+        [location.pathname]
+    );
+
+    const userDisplayName = session ? (session.user.display_name ?? session.user.email) : '';
+    const userInitial = userDisplayName.charAt(0).toUpperCase();
+
+    const handleLogout = async () => {
+        setLoggingOut(true);
+        try {
+            await logout();
+        } finally {
+            setLoggingOut(false);
+            navigate('/login', { replace: true });
+        }
+    };
+
+    const handleUserMenuClick: MenuProps['onClick'] = ({ key }) => {
+        if (key === 'profile') {
+            navigate('/settings/profile');
+        } else if (key === 'password') {
+            navigate('/settings/password');
+        } else if (key === 'logout') {
+            void handleLogout();
+        }
+    };
+
+    const userMenuItems: MenuProps['items'] = [
+        { key: 'profile', icon: <UserOutlined />, label: '修改资料' },
+        { key: 'password', icon: <LockOutlined />, label: '修改密码' },
+        { type: 'divider' },
+        {
+            key: 'logout',
+            icon: <LogoutOutlined />,
+            label: loggingOut ? '退出中…' : '退出登录',
+            disabled: loggingOut,
+        },
+    ];
+
+    useEffect(() => {
+        const checkMobile = () => {
+            setIsMobile(window.innerWidth < 768);
+            if (window.innerWidth >= 768) setMobileMenuOpen(false);
+        };
+        checkMobile();
+        window.addEventListener('resize', checkMobile);
+        return () => window.removeEventListener('resize', checkMobile);
+    }, []);
+
+    return (
+        <Layout className="main-layout">
+            {!isMobile && (
+                <Sider
+                    className="main-sider"
+                    width={200}
+                    collapsedWidth={60}
+                    collapsed={collapsed}
+                    theme="dark"
+                    style={{
+                        overflow: 'auto',
+                        height: '100vh',
+                        position: 'fixed',
+                        left: 0,
+                        top: 0,
+                        bottom: 0,
+                    }}
+                >
+                    <div className="sidebar-header">
+                        <div className="logo">
+                            <span className="logo-full">Atlas Kit</span>
+                            <span className="logo-short">A</span>
+                        </div>
+                        <div className="logo-subtitle">商品工作台</div>
+                    </div>
+                    <SidebarMenu collapsed={collapsed} />
+                </Sider>
+            )}
+
+            {isMobile && (
+                <Drawer
+                    title="Atlas Kit"
+                    placement="left"
+                    onClose={() => setMobileMenuOpen(false)}
+                    open={mobileMenuOpen}
+                    styles={{ body: { padding: 0, background: 'var(--sider-bg)' } }}
+                    width={200}
+                >
+                    <SidebarMenu collapsed={false} onMenuClick={() => setMobileMenuOpen(false)} />
+                </Drawer>
+            )}
+
+            <Layout
+                className="main-content-layout"
+                style={{
+                    marginLeft: isMobile ? 0 : collapsed ? 60 : 200,
+                    transition: 'margin-left 0.2s',
+                }}
+            >
+                <Header className="main-header">
+                    <div className="header-left">
+                        {isMobile && (
+                            <MenuFoldOutlined
+                                className="mobile-menu-trigger"
+                                onClick={() => setMobileMenuOpen(true)}
+                            />
+                        )}
+                        {!isMobile && (
+                            <div
+                                className="collapse-trigger"
+                                onClick={() => setCollapsed(!collapsed)}
+                            >
+                                {collapsed ? <MenuUnfoldOutlined /> : <MenuFoldOutlined />}
+                            </div>
+                        )}
+                        <Breadcrumb
+                            className="page-breadcrumb"
+                            separator={<RightOutlined style={{ fontSize: 12 }} />}
+                            items={breadcrumbItems}
+                        />
+                    </div>
+                    {session && (
+                        <div className="header-right">
+                            <PlatformSelector />
+                            <Dropdown
+                                menu={{ items: userMenuItems, onClick: handleUserMenuClick }}
+                                trigger={['hover']}
+                                placement="bottomRight"
+                            >
+                                <div className="header-user-trigger" title={userDisplayName}>
+                                    <Avatar
+                                        size={28}
+                                        style={{ backgroundColor: 'var(--sider-bg)' }}
+                                    >
+                                        {userInitial}
+                                    </Avatar>
+                                    <span className="header-user-name">{userDisplayName}</span>
+                                </div>
+                            </Dropdown>
+                        </div>
+                    )}
+                </Header>
+
+                <Content className="main-content">
+                    <Outlet />
+                </Content>
+            </Layout>
+        </Layout>
+    );
+};
+
+export default MainLayout;

apps/web/src/layouts/PlatformSelector.tsx

@@ -0,0 +1,40 @@
+import { GlobalOutlined } from '@ant-design/icons';
+import { Select, Tooltip } from 'antd';
+import { usePlatform } from '@/services/platform';
+
+/**
+ * 页头平台选择器：采集编辑、发布等动作按页头当前平台取得发布配置与默认店铺
+ * （docs/requirements/collector-browser-extension.md 的页头平台上下文约定）。
+ * 首次使用默认选中目录第一家（Ozon 优先），选择结果仅作为非敏感 UI 偏好本地记忆。
+ */
+const PlatformSelector = () => {
+    const { platforms, currentPlatform, selectPlatform, context, contextLoading } = usePlatform();
+
+    if (platforms.length === 0) return null;
+
+    const tooltip = context?.default_store
+        ? `当前平台：${currentPlatform?.name}，默认店铺：${context.default_store.name}`
+        : '选择当前平台';
+
+    return (
+        <Tooltip title={tooltip}>
+            <div className="platform-selector">
+                <GlobalOutlined className="platform-selector-icon" />
+                <Select
+                    variant="borderless"
+                    loading={contextLoading && !currentPlatform}
+                    value={currentPlatform?.id}
+                    onChange={selectPlatform}
+                    options={platforms.map((platform) => ({
+                        value: platform.id,
+                        label: platform.name,
+                    }))}
+                    popupMatchSelectWidth={false}
+                    aria-label="选择当前平台"
+                />
+            </div>
+        </Tooltip>
+    );
+};
+
+export default PlatformSelector;

apps/web/src/layouts/SidebarMenu.css

@@ -0,0 +1,162 @@
+.sidebar-menu-container {
+    flex: 1;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+}
+
+.sidebar-menu {
+    background: transparent !important;
+    border: none;
+    height: 100%;
+    overflow-y: auto;
+    overflow-x: hidden;
+}
+
+.sidebar-menu .ant-menu-item {
+    margin: 0 !important;
+    padding: 12px 20px !important;
+    height: auto !important;
+    line-height: 1.5 !important;
+    transition: all 0.3s !important;
+    font-size: 15px !important;
+    font-weight: 600 !important;
+}
+
+.sidebar-menu .ant-menu-item .ant-menu-title-content {
+    font-size: 15px !important;
+    font-weight: 600 !important;
+    /* antd 默认只过渡 color，会覆盖下面的 width/opacity 过渡；必须 !important 提权 */
+    transition:
+        transform 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+        width 0.2s ease,
+        opacity 0.2s ease,
+        margin 0.3s,
+        color 0.3s !important;
+    display: inline-block;
+    /* 显式宽度让折叠时 width→0 可插值，配合裁剪+渐隐平滑收起（auto→0 无法动画） */
+    width: 100%;
+    opacity: 1;
+    overflow: hidden;
+    white-space: nowrap;
+    vertical-align: middle;
+}
+
+.sidebar-menu .ant-menu-item:hover {
+    background: rgba(255, 255, 255, 0.1) !important;
+}
+
+.sidebar-menu .ant-menu-item-selected {
+    background: rgba(255, 255, 255, 0.2) !important;
+    border-left: 3px solid white;
+}
+
+.sidebar-menu .ant-menu-item-selected .ant-menu-title-content {
+    transform: translateX(8px);
+}
+
+.sidebar-menu .ant-menu-item-selected:hover {
+    background: rgba(255, 255, 255, 0.25) !important;
+}
+
+.sidebar-menu .ant-menu-item-selected:hover .ant-menu-title-content {
+    transform: translateX(8px);
+}
+
+.sidebar-menu .ant-menu-item-group-title {
+    padding: 12px 20px 8px !important;
+    font-size: 12px !important;
+    color: rgba(255, 255, 255, 0.7) !important;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    font-weight: 500;
+    /* 折叠时渐隐并收起占位高度（!important 防止被 antd 默认 transition 覆盖） */
+    max-height: 40px;
+    opacity: 1;
+    overflow: hidden;
+    transition:
+        opacity 0.2s ease,
+        max-height 0.2s ease,
+        padding 0.2s ease !important;
+}
+
+.sidebar-menu .ant-menu-item-icon {
+    transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    font-size: 18px !important;
+    display: inline-flex;
+    align-items: center;
+}
+
+/* hover 放大只作用于非选中项；选中项图标固定 translateX(8px)，hover 时不得变 transform 导致跳动 */
+.sidebar-menu .ant-menu-item:hover:not(.ant-menu-item-selected) .ant-menu-item-icon {
+    transform: scale(1.05);
+}
+
+.sidebar-menu .ant-menu-item-selected .ant-menu-item-icon {
+    transform: translateX(8px);
+}
+
+@media (max-width: 768px) {
+    .sidebar-menu .ant-menu-item {
+        padding: 14px 20px !important;
+    }
+}
+
+/* ── 折叠态（60px）：图标居中，覆盖展开态的左对齐 padding/位移 ── */
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item,
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item-group-title {
+    padding: 12px 0 !important;
+    text-align: center;
+}
+
+/* 分组标题折叠时渐隐并完全收起，不占纵向空间 */
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item-group-title {
+    max-height: 0;
+    opacity: 0;
+    padding-top: 0 !important;
+    padding-bottom: 0 !important;
+}
+
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+}
+
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item .ant-menu-title-content,
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item-selected .ant-menu-title-content {
+    transform: none !important;
+}
+
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item .ant-menu-item-icon,
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item:hover .ant-menu-item-icon,
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item-selected .ant-menu-item-icon {
+    transform: none !important;
+    margin: 0;
+}
+
+/* 折叠时去掉左侧 3px 选中边框（会挤偏图标）；只过渡宽度，避免 none 突变 */
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item-selected {
+    border-left-width: 0 !important;
+}
+
+/* 折叠时菜单文字平滑收起：width 100%→0 插值 + 裁剪 + 渐隐；
+   不用 display:none（无法过渡，文字瞬间消失） */
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item .ant-menu-title-content,
+.sidebar-menu.ant-menu-vertical .ant-menu-item .ant-menu-title-content {
+    width: 0 !important;
+    opacity: 0 !important;
+}
+
+/* 兼容：部分版本折叠态用 vertical 类渲染，同样居中 */
+.sidebar-menu.ant-menu-vertical .ant-menu-item,
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item {
+    padding-left: 0 !important;
+    padding-right: 0 !important;
+}
+
+/* 折叠态 flex 子元素居中（display:flex 已生效，缺 justify-content） */
+.sidebar-menu.ant-menu-inline-collapsed .ant-menu-item {
+    justify-content: center !important;
+}

apps/web/src/layouts/SidebarMenu.tsx

@@ -0,0 +1,63 @@
+import { useMemo } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import { Menu } from 'antd';
+import type { MenuProps } from 'antd';
+import { routeMenuConfig } from './menuConfig';
+import './SidebarMenu.css';
+
+interface SidebarMenuProps {
+    collapsed: boolean;
+    onMenuClick?: () => void;
+}
+
+const SidebarMenu = ({ collapsed, onMenuClick }: SidebarMenuProps) => {
+    const location = useLocation();
+    const navigate = useNavigate();
+
+    // 分组标题保持常驻，折叠时的隐藏由 CSS 过渡完成，避免文字瞬间消失
+    const menuItems: MenuProps['items'] = useMemo(() => {
+        const children = routeMenuConfig.map((config) => ({
+            key: config.key,
+            icon: config.icon,
+            label: config.label,
+        }));
+        return [
+            {
+                type: 'group' as const,
+                label: '主要功能',
+                className: 'menu-section-title',
+                children,
+            },
+        ];
+    }, []);
+
+    const selectedKeys = useMemo(() => {
+        const path = location.pathname;
+        if (path === '/' || path === '') {
+            return [routeMenuConfig[0].key];
+        }
+        const config = routeMenuConfig.find((item) => path.startsWith(item.path));
+        return [config ? config.key : path];
+    }, [location.pathname]);
+
+    const handleMenuClick: MenuProps['onClick'] = ({ key }) => {
+        navigate(key);
+        if (onMenuClick) onMenuClick();
+    };
+
+    return (
+        <div className="sidebar-menu-container">
+            <Menu
+                theme="dark"
+                mode="inline"
+                inlineCollapsed={collapsed}
+                selectedKeys={selectedKeys}
+                items={menuItems}
+                onClick={handleMenuClick}
+                className="sidebar-menu"
+            />
+        </div>
+    );
+};
+
+export default SidebarMenu;

apps/web/src/layouts/menuConfig.tsx

@@ -0,0 +1,87 @@
+import {
+    CalculatorOutlined,
+    CodeSandboxOutlined,
+    EditOutlined,
+    GlobalOutlined,
+    InboxOutlined,
+    LockOutlined,
+    PictureOutlined,
+    SettingOutlined,
+    ShopOutlined,
+    UserOutlined,
+} from '@ant-design/icons';
+import type { ReactNode } from 'react';
+
+export interface RouteMenuConfig {
+    /** 路由路径 */
+    path: string;
+    /** 菜单键值（与 path 相同） */
+    key: string;
+    /** 菜单图标（菜单与页头面包屑共用） */
+    icon: ReactNode;
+    /** 菜单标签 */
+    label: string;
+}
+
+/** 左侧一级菜单，顺序与 docs/requirements/account-store-watermark.md 的导航约定一致 */
+export const routeMenuConfig: RouteMenuConfig[] = [
+    {
+        path: '/online-products',
+        key: '/online-products',
+        icon: <GlobalOutlined />,
+        label: '在线商品',
+    },
+    {
+        path: '/collection',
+        key: '/collection',
+        icon: <InboxOutlined />,
+        label: '采集箱',
+    },
+    {
+        path: '/shops',
+        key: '/shops',
+        icon: <ShopOutlined />,
+        label: '店铺管理',
+    },
+    {
+        path: '/watermarks',
+        key: '/watermarks',
+        icon: <PictureOutlined />,
+        label: '水印管理',
+    },
+    {
+        path: '/pricing',
+        key: '/pricing',
+        icon: <CalculatorOutlined />,
+        label: '定价工具',
+    },
+];
+
+export interface BreadcrumbCrumb {
+    icon: ReactNode;
+    label: string;
+}
+
+/** 页头面包屑：一级菜单页显示单级；不在菜单中的页面显示两级 */
+export const getBreadcrumbItems = (path: string): BreadcrumbCrumb[] => {
+    if (path.startsWith('/products/')) {
+        return [
+            { icon: <CodeSandboxOutlined />, label: '商品' },
+            { icon: <EditOutlined />, label: '商品编辑' },
+        ];
+    }
+    if (path === '/settings/profile') {
+        return [
+            { icon: <SettingOutlined />, label: '设置' },
+            { icon: <UserOutlined />, label: '修改资料' },
+        ];
+    }
+    if (path === '/settings/password') {
+        return [
+            { icon: <SettingOutlined />, label: '设置' },
+            { icon: <LockOutlined />, label: '修改密码' },
+        ];
+    }
+    const config = routeMenuConfig.find((item) => path.startsWith(item.path)) ?? routeMenuConfig[0];
+    return [{ icon: config.icon, label: config.label }];
+};

apps/web/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './index.css';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <App />
+    </StrictMode>
+);

apps/web/src/pages/auth/LoginPage.tsx

@@ -0,0 +1,112 @@
+import { useState } from 'react';
+import { Link, useLocation, useNavigate } from 'react-router-dom';
+import { App as AntdApp, Button, Form, Input } from 'antd';
+import { LockOutlined, MailOutlined } from '@ant-design/icons';
+import axios from 'axios';
+import AuthLayout from '@/layouts/AuthLayout';
+import { apiErrorDetails, apiErrorMessage } from '@/services/api';
+import { authApi } from '@/services/auth';
+import { useSession } from '@/services/session';
+import { emailFormatRule } from '@/utils/validators';
+
+interface LoginFormValues {
+    email: string;
+    password: string;
+}
+
+/** 登录页，契约见 docs/api/auth.md §3 */
+const LoginPage = () => {
+    const navigate = useNavigate();
+    const location = useLocation();
+    const { message } = AntdApp.useApp();
+    const { applyAuthSession } = useSession();
+    const [form] = Form.useForm<LoginFormValues>();
+    const [submitting, setSubmitting] = useState(false);
+
+    const handleFinish = async (values: LoginFormValues) => {
+        setSubmitting(true);
+        try {
+            const session = await authApi.login({
+                email: values.email.trim(),
+                password: values.password,
+            });
+            applyAuthSession(session);
+            message.success('登录成功');
+            // 守卫记住的来源路径优先，默认进入在线商品首页
+            const from = (location.state as { from?: string } | null)?.from;
+            navigate(from && from.startsWith('/') ? from : '/online-products', {
+                replace: true,
+            });
+        } catch (error) {
+            // 契约约定登录失败统一返回 401 INVALID_CREDENTIALS，不区分邮箱不存在或密码错误
+            if (axios.isAxiosError(error) && error.response?.status === 401) {
+                message.error('邮箱或密码不正确');
+                return;
+            }
+            // 422 VALIDATION_FAILED 等带字段明细的错误，逐项落到对应表单项
+            const details = apiErrorDetails(error);
+            if (details.length > 0) {
+                form.setFields(
+                    details.map((item) => ({
+                        name: item.field as keyof LoginFormValues,
+                        errors: [item.message],
+                    }))
+                );
+            } else {
+                message.error(apiErrorMessage(error));
+            }
+        } finally {
+            setSubmitting(false);
+        }
+    };
+
+    return (
+        <AuthLayout
+            title="登录"
+            subtitle="登录 Atlas Seller Kit，继续管理你的商品"
+            footer={
+                <>
+                    还没有账户？<Link to="/register">立即注册</Link>
+                </>
+            }
+        >
+            <Form<LoginFormValues>
+                form={form}
+                layout="vertical"
+                requiredMark={false}
+                onFinish={handleFinish}
+            >
+                <Form.Item
+                    name="email"
+                    label="邮箱"
+                    rules={[{ required: true, message: '请输入邮箱' }, emailFormatRule]}
+                >
+                    <Input
+                        prefix={<MailOutlined style={{ color: 'var(--text-secondary)' }} />}
+                        placeholder="请输入邮箱"
+                        autoComplete="email"
+                        autoFocus
+                    />
+                </Form.Item>
+                <Form.Item
+                    name="password"
+                    label="密码"
+                    rules={[{ required: true, message: '请输入密码' }]}
+                >
+                    <Input.Password
+                        prefix={<LockOutlined style={{ color: 'var(--text-secondary)' }} />}
+                        placeholder="请输入密码"
+                        autoComplete="current-password"
+                    />
+                </Form.Item>
+                <Form.Item style={{ marginBottom: 0, marginTop: 8 }}>
+                    <Button type="primary" htmlType="submit" block loading={submitting}>
+                        登录
+                    </Button>
+                </Form.Item>
+            </Form>
+        </AuthLayout>
+    );
+};
+
+export default LoginPage;

apps/web/src/pages/auth/RegisterPage.tsx

@@ -0,0 +1,147 @@
+import { useState } from 'react';
+import { Link, useNavigate } from 'react-router-dom';
+import { App as AntdApp, Button, Form, Input } from 'antd';
+import { LockOutlined, MailOutlined, UserOutlined } from '@ant-design/icons';
+import axios from 'axios';
+import AuthLayout from '@/layouts/AuthLayout';
+import { apiErrorDetails, apiErrorMessage } from '@/services/api';
+import { authApi } from '@/services/auth';
+import { useSession } from '@/services/session';
+import { emailFormatRule } from '@/utils/validators';
+
+interface RegisterFormValues {
+    display_name?: string;
+    email: string;
+    password: string;
+    password_confirmation: string;
+}
+
+/** 注册页，契约见 docs/api/auth.md §2；密码长度与复杂度由服务端唯一校验，前端不自行放宽或收窄 */
+const RegisterPage = () => {
+    const navigate = useNavigate();
+    const { message } = AntdApp.useApp();
+    const { applyAuthSession } = useSession();
+    const [form] = Form.useForm<RegisterFormValues>();
+    const [submitting, setSubmitting] = useState(false);
+
+    const handleFinish = async (values: RegisterFormValues) => {
+        setSubmitting(true);
+        try {
+            const session = await authApi.register({
+                email: values.email.trim(),
+                password: values.password,
+                password_confirmation: values.password_confirmation,
+                display_name: values.display_name?.trim() || undefined,
+            });
+            // 注册成功即在同一事务创建用户、个人工作空间和登录会话
+            applyAuthSession(session);
+            message.success('注册成功，已进入你的工作空间');
+            navigate('/online-products', { replace: true });
+        } catch (error) {
+            // 重复邮箱返回 409 EMAIL_ALREADY_REGISTERED，落到邮箱字段上提示
+            if (axios.isAxiosError(error) && error.response?.status === 409) {
+                form.setFields([{ name: 'email', errors: ['该邮箱已注册，请直接登录'] }]);
+                return;
+            }
+            // 422 VALIDATION_FAILED 等带字段明细的错误，逐项落到对应表单项
+            const details = apiErrorDetails(error);
+            if (details.length > 0) {
+                form.setFields(
+                    details.map((item) => ({
+                        name: item.field as keyof RegisterFormValues,
+                        errors: [item.message],
+                    }))
+                );
+            } else {
+                message.error(apiErrorMessage(error));
+            }
+        } finally {
+            setSubmitting(false);
+        }
+    };
+
+    return (
+        <AuthLayout
+            title="注册"
+            subtitle="创建账户后自动创建个人工作空间，注册即登录"
+            footer={
+                <>
+                    已有账户？<Link to="/login">直接登录</Link>
+                </>
+            }
+        >
+            <Form<RegisterFormValues>
+                form={form}
+                layout="vertical"
+                requiredMark={false}
+                onFinish={handleFinish}
+            >
+                <Form.Item
+                    name="display_name"
+                    label="显示名称"
+                    extra="选填，最多 80 个字符"
+                    rules={[{ max: 80, message: '显示名称最多 80 个字符' }]}
+                >
+                    <Input
+                        prefix={<UserOutlined style={{ color: 'var(--text-secondary)' }} />}
+                        placeholder="选填"
+                        maxLength={80}
+                        autoComplete="nickname"
+                    />
+                </Form.Item>
+                <Form.Item
+                    name="email"
+                    label="邮箱"
+                    rules={[{ required: true, message: '请输入邮箱' }, emailFormatRule]}
+                >
+                    <Input
+                        prefix={<MailOutlined style={{ color: 'var(--text-secondary)' }} />}
+                        placeholder="请输入邮箱"
+                        autoComplete="email"
+                    />
+                </Form.Item>
+                <Form.Item
+                    name="password"
+                    label="密码"
+                    extra="至少 12 个字符；长度与复杂度以服务端安全校验为准"
+                    rules={[{ required: true, message: '请输入密码' }]}
+                >
+                    <Input.Password
+                        prefix={<LockOutlined style={{ color: 'var(--text-secondary)' }} />}
+                        placeholder="请输入密码"
+                        autoComplete="new-password"
+                    />
+                </Form.Item>
+                <Form.Item
+                    name="password_confirmation"
+                    label="确认密码"
+                    dependencies={['password']}
+                    rules={[
+                        { required: true, message: '请再次输入密码' },
+                        ({ getFieldValue }) => ({
+                            validator(_, value) {
+                                if (!value || getFieldValue('password') === value) {
+                                    return Promise.resolve();
+                                }
+                                return Promise.reject(new Error('两次输入的密码不一致'));
+                            },
+                        }),
+                    ]}
+                >
+                    <Input.Password
+                        prefix={<LockOutlined style={{ color: 'var(--text-secondary)' }} />}
+                        placeholder="请再次输入密码"
+                        autoComplete="new-password"
+                    />
+                </Form.Item>
+                <Form.Item style={{ marginBottom: 0, marginTop: 8 }}>
+                    <Button type="primary" htmlType="submit" block loading={submitting}>
+                        创建账户
+                    </Button>
+                </Form.Item>
+            </Form>
+        </AuthLayout>
+    );
+};
+
+export default RegisterPage;

apps/web/src/pages/collection/CollectionPage.tsx

@@ -0,0 +1,26 @@
+import { useCallback, useEffect, useState } from 'react';
+import { App as AntdApp, Button, Card, Form, Input, Modal, Progress, Select, Space, Table, Tag, Typography } from 'antd';
+import type { TableProps } from 'antd';
+import { DeleteOutlined, PlusOutlined, ReloadOutlined } from '@ant-design/icons';
+import type { CollectionItem } from '@atlas/contracts';
+import { collectionApi } from '@/services/collection';
+import { apiErrorMessage } from '@/services/api';
+import { usePlatform } from '@/services/platform';
+
+const statusLabel: Record<string, string> = { received: '已接收', materializing: '素材处理中', ready_for_edit: '可编辑', needs_review: '待确认', failed: '采集失败' };
+export default function CollectionPage() {
+  const { message, modal } = AntdApp.useApp(); const { currentPlatform } = usePlatform(); const [items, setItems] = useState<CollectionItem[]>([]); const [meta, setMeta] = useState({ active_count: 0, collection_limit: 1000 }); const [loading, setLoading] = useState(false); const [selected, setSelected] = useState<string[]>([]); const [q, setQ] = useState(''); const [source, setSource] = useState<string>(); const [createOpen, setCreateOpen] = useState(false); const [form] = Form.useForm<{ title?: string; note?: string }>();
+  const load = useCallback(async () => { if (!currentPlatform) return; setLoading(true); try { const result = await collectionApi.list(currentPlatform.id, { ...(q.trim() ? { q: q.trim() } : {}), ...(source ? { source_platform_code: source as 'OZON' } : {}) }); setItems(result.data); setMeta(result.meta); } catch (error) { message.error(apiErrorMessage(error)); } finally { setLoading(false); } }, [currentPlatform, message, q, source]);
+  useEffect(() => { void load(); }, [load]);
+  const create = async (values: { title?: string; note?: string }) => { try { await collectionApi.create({ title: values.title?.trim() || undefined, note: values.note?.trim() || null }); message.success('商品草稿已加入采集箱'); setCreateOpen(false); form.resetFields(); await load(); } catch (error) { message.error(apiErrorMessage(error)); } };
+  const remove = (ids: string[], all = false) => modal.confirm({ title: all ? '清空采集箱' : '删除采集商品', content: all ? `将清空当前 ${meta.active_count} 条采集草稿，不会删除或下架任何平台商品。确定继续吗？` : '仅删除 Atlas 内的采集草稿，不会删除或下架任何平台商品。确定继续吗？', okText: all ? '清空' : '删除', okButtonProps: { danger: true }, onOk: async () => { try { const result = all ? await collectionApi.clear(meta.active_count) : await collectionApi.bulkDelete(ids); message.success(`已删除 ${result.deleted_count} 条采集草稿`); setSelected([]); await load(); } catch (error) { message.error(apiErrorMessage(error)); } } });
+  const columns: TableProps<CollectionItem>['columns'] = [
+    { title: '产品名称', dataIndex: 'title', render: (value) => value || '未命名商品' }, { title: '来源', dataIndex: 'source', width: 110, render: (value) => <Tag>{value.kind === 'manual' ? '手动创建' : value.platform_code}</Tag> }, { title: 'SKU', dataIndex: 'variant_summary', width: 80, render: (value) => value.count }, { title: '采集状态', dataIndex: 'collection_status', width: 120, render: (value) => statusLabel[value] ?? value }, { title: '当前平台上架', dataIndex: 'listing_summary', width: 150, render: (value) => <Typography.Text type="secondary">{value.detail}</Typography.Text> }, { title: '备注', dataIndex: 'note', ellipsis: true, render: (value) => value || '—' }, { title: '更新时间', dataIndex: 'updated_at', width: 170, render: (value) => new Date(value).toLocaleString('zh-CN', { hour12: false }) }, { title: '操作', width: 150, render: (_, item) => <Space><Button type="link" size="small" onClick={() => message.info('商品编辑将在下一任务提供')}>编辑上架</Button><Button type="link" danger size="small" onClick={() => remove([item.id])}>删除</Button></Space> },
+  ];
+  return <Card title="采集箱" extra={<Space><Button icon={<ReloadOutlined />} onClick={() => void load()} /><Button danger disabled={!items.length} onClick={() => remove([], true)}>清空采集箱</Button><Button danger icon={<DeleteOutlined />} disabled={!selected.length} onClick={() => remove(selected)}>批量删除</Button><Button type="primary" icon={<PlusOutlined />} onClick={() => setCreateOpen(true)}>手动创建商品</Button></Space>}>
+    <Progress percent={meta.collection_limit ? Math.round(meta.active_count / meta.collection_limit * 100) : 0} format={() => `${meta.active_count} / ${meta.collection_limit}`} style={{ maxWidth: 420, marginBottom: 18 }} />
+    <Space wrap style={{ marginBottom: 16 }}><Input value={q} onChange={(e) => setQ(e.target.value)} placeholder="搜索产品名称" allowClear style={{ width: 220 }} /><Select allowClear placeholder="采集来源" value={source} onChange={setSource} style={{ width: 140 }} options={[{ value: 'OZON', label: 'Ozon' }, { value: '1688', label: '1688' }, { value: 'TAOBAO', label: '淘宝' }, { value: 'TMALL', label: '天猫' }]} /><Button type="primary" onClick={() => void load()}>查询</Button></Space>
+    <Table rowKey="id" loading={loading} columns={columns} dataSource={items} pagination={false} rowSelection={{ selectedRowKeys: selected, onChange: (keys) => setSelected(keys.map(String)) }} locale={{ emptyText: '暂无采集商品，点击右上角手动创建商品' }} />
+    <Modal title="手动创建商品" open={createOpen} footer={null} onCancel={() => setCreateOpen(false)} destroyOnHidden><Form form={form} layout="vertical" onFinish={create}><Form.Item name="title" label="商品名称"><Input maxLength={300} placeholder="可稍后在商品编辑中完善" /></Form.Item><Form.Item name="note" label="备注"><Input.TextArea maxLength={2000} /></Form.Item><Space><Button type="primary" htmlType="submit">创建草稿</Button><Button onClick={() => setCreateOpen(false)}>取消</Button></Space></Form></Modal>
+  </Card>;
+}

apps/web/src/pages/online-products/OnlineProductsPage.tsx

@@ -0,0 +1,11 @@
+import PagePlaceholder from '@/components/PagePlaceholder';
+
+/** 在线商品：按 SKU 查看平台已上架商品与同步状态（业务模块尚未实现） */
+const OnlineProductsPage = () => (
+    <PagePlaceholder
+        title="在线商品"
+        description="按 SKU 查看平台已上架商品与同步状态，模块开发中。"
+    />
+);
+
+export default OnlineProductsPage;

apps/web/src/pages/pricing/PricingPage.tsx

@@ -0,0 +1,8 @@
+import PagePlaceholder from '@/components/PagePlaceholder';
+
+/** 定价工具：独立试算与物流计价规则（业务模块尚未实现） */
+const PricingPage = () => (
+    <PagePlaceholder title="定价工具" description="独立试算与物流计价规则，模块开发中。" />
+);
+
+export default PricingPage;

apps/web/src/pages/products/ProductEditPage.tsx

@@ -0,0 +1,16 @@
+import { useParams } from 'react-router-dom';
+import PagePlaceholder from '@/components/PagePlaceholder';
+
+/** 商品 AI 编辑页：编辑 SPU/SKU、媒体、定价与首次发布（业务模块尚未实现） */
+const ProductEditPage = () => {
+    const { id } = useParams<{ id: string }>();
+
+    return (
+        <PagePlaceholder
+            title={`商品编辑（${id ?? '未知 ID'}）`}
+            description="商品 AI 编辑页：SPU/SKU、媒体、定价与发布，模块开发中。"
+        />
+    );
+};
+
+export default ProductEditPage;

apps/web/src/pages/settings/PasswordSettingsPage.tsx

@@ -0,0 +1,128 @@
+import { useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { App as AntdApp, Button, Form, Input } from 'antd';
+import axios from 'axios';
+import { authApi } from '@/services/auth';
+import { authToken } from '@/services/authToken';
+import { apiErrorDetails, apiErrorMessage } from '@/services/api';
+
+interface PasswordFormValues {
+    old_password: string;
+    password: string;
+    password_confirmation: string;
+}
+
+/**
+ * 修改密码页，契约见 docs/api/auth.md（POST /api/auth/change-password）。
+ * 成功后所有旧 session 失效：立即用响应中的新 access token 替换内存值
+ * （本设备经新的 refresh cookie 保持登录），清理表单状态后回到首页。
+ */
+const PasswordSettingsPage = () => {
+    const { message } = AntdApp.useApp();
+    const navigate = useNavigate();
+    const [form] = Form.useForm<PasswordFormValues>();
+    const [submitting, setSubmitting] = useState(false);
+
+    const handleFinish = async (values: PasswordFormValues) => {
+        setSubmitting(true);
+        try {
+            const result = await authApi.changePassword({
+                old_password: values.old_password,
+                password: values.password,
+                password_confirmation: values.password_confirmation,
+            });
+            authToken.set(result.access_token);
+            form.resetFields();
+            message.success('密码已修改');
+            navigate('/online-products', { replace: true });
+        } catch (error) {
+            if (axios.isAxiosError(error) && error.response?.status === 401) {
+                message.error('原密码不正确');
+            } else {
+                const details = apiErrorDetails(error);
+                if (details.length > 0) {
+                    form.setFields(
+                        details.map((item) => ({
+                            name: item.field as keyof PasswordFormValues,
+                            errors: [item.message],
+                        }))
+                    );
+                } else {
+                    message.error(apiErrorMessage(error));
+                }
+            }
+        } finally {
+            setSubmitting(false);
+        }
+    };
+
+    return (
+        <div className="settings-page">
+            <div className="settings-card">
+                <div className="settings-card-title">修改密码</div>
+                <div className="settings-card-body">
+                    <Form<PasswordFormValues>
+                        form={form}
+                        layout="vertical"
+                        onFinish={handleFinish}
+                        className="profile-form"
+                    >
+                        <Form.Item
+                            name="old_password"
+                            label="原密码"
+                            rules={[{ required: true, message: '请输入原密码' }]}
+                        >
+                            <Input.Password
+                                placeholder="请输入原密码"
+                                autoComplete="current-password"
+                            />
+                        </Form.Item>
+                        <Form.Item
+                            name="password"
+                            label="新密码"
+                            extra="至少 12 个字符；长度与复杂度以服务端安全校验为准"
+                            rules={[
+                                { required: true, message: '请输入新密码' },
+                                { min: 12, message: '新密码至少需要 12 个字符' },
+                            ]}
+                        >
+                            <Input.Password
+                                placeholder="请输入新密码"
+                                autoComplete="new-password"
+                            />
+                        </Form.Item>
+                        <Form.Item
+                            name="password_confirmation"
+                            label="确认新密码"
+                            dependencies={['password']}
+                            rules={[
+                                { required: true, message: '请再次输入新密码' },
+                                ({ getFieldValue }) => ({
+                                    validator(_, value) {
+                                        if (!value || getFieldValue('password') === value) {
+                                            return Promise.resolve();
+                                        }
+                                        return Promise.reject(new Error('两次输入的新密码不一致'));
+                                    },
+                                }),
+                            ]}
+                        >
+                            <Input.Password
+                                placeholder="请再次输入新密码"
+                                autoComplete="new-password"
+                            />
+                        </Form.Item>
+                        <div className="settings-actions">
+                            <Button type="primary" htmlType="submit" loading={submitting}>
+                                保存修改
+                            </Button>
+                            <Button onClick={() => navigate('/')}>取消</Button>
+                        </div>
+                    </Form>
+                </div>
+            </div>
+        </div>
+    );
+};
+
+export default PasswordSettingsPage;

apps/web/src/pages/settings/ProfileSettingsPage.tsx

@@ -0,0 +1,114 @@
+import { useMemo, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { App as AntdApp, Avatar, Button, Form, Input } from 'antd';
+import axios from 'axios';
+import { authApi } from '@/services/auth';
+import { useSession } from '@/services/session';
+import { apiErrorDetails, apiErrorMessage } from '@/services/api';
+
+interface ProfileFormValues {
+    display_name: string;
+}
+
+/**
+ * 修改资料页，契约见 docs/api/auth.md（PATCH /api/auth/me，If-Match + Idempotency-Key）。
+ * 头像持久化依赖素材预签名直传接口（尚未交付）：当前仅展示默认头像的禁用态，不提供上传。
+ */
+const ProfileSettingsPage = () => {
+    const { message } = AntdApp.useApp();
+    const navigate = useNavigate();
+    const { session, applyProfileUpdate } = useSession();
+    const [form] = Form.useForm<ProfileFormValues>();
+    const [saving, setSaving] = useState(false);
+
+    const displayName = session?.user.display_name ?? session?.user.email ?? '';
+    const initial = useMemo(() => displayName.charAt(0).toUpperCase(), [displayName]);
+
+    if (!session) return null;
+
+    const handleSave = async (values: ProfileFormValues) => {
+        setSaving(true);
+        try {
+            const user = await authApi.updateProfile(
+                { display_name: values.display_name.trim() },
+                // 幂等键每次提交重新生成；以提交时的 revision 做乐观锁
+                { revision: session.user.revision, idempotencyKey: crypto.randomUUID() }
+            );
+            applyProfileUpdate(user);
+            message.success('资料已更新');
+        } catch (error) {
+            // 乐观锁版本过期：服务端返回 409 与当前 revision，提示刷新后重试
+            if (axios.isAxiosError(error) && error.response?.status === 409) {
+                message.error('资料已被其他操作更新，请刷新页面获取最新资料后重试');
+            } else {
+                const details = apiErrorDetails(error);
+                if (details.length > 0) {
+                    form.setFields(
+                        details
+                            .filter((item) => item.field !== 'If-Match')
+                            .map((item) => ({
+                                name: item.field as keyof ProfileFormValues,
+                                errors: [item.message],
+                            }))
+                    );
+                } else {
+                    message.error(apiErrorMessage(error));
+                }
+            }
+        } finally {
+            setSaving(false);
+        }
+    };
+
+    const handleReset = () => {
+        form.setFieldValue('display_name', session.user.display_name ?? '');
+    };
+
+    return (
+        <div className="settings-page">
+            <div className="settings-card">
+                <div className="settings-card-title">修改个人信息</div>
+                <div className="settings-card-body">
+                    <div className="settings-field-label">头像</div>
+                    <div className="avatar-upload-area">
+                        <Avatar size={160} style={{ backgroundColor: 'var(--sider-bg)' }}>
+                            {initial}
+                        </Avatar>
+                    </div>
+                    <div className="avatar-upload-hint">头像上传即将支持，敬请期待</div>
+
+                    <Form<ProfileFormValues>
+                        form={form}
+                        layout="vertical"
+                        initialValues={{ display_name: session.user.display_name ?? '' }}
+                        onFinish={handleSave}
+                        className="profile-form"
+                    >
+                        <Form.Item
+                            name="display_name"
+                            label="昵称"
+                            required
+                            rules={[{ required: true, message: '请输入昵称' }]}
+                        >
+                            <Input
+                                maxLength={80}
+                                showCount
+                                placeholder="请输入昵称"
+                                autoComplete="nickname"
+                            />
+                        </Form.Item>
+                        <div className="settings-actions">
+                            <Button type="primary" htmlType="submit" loading={saving}>
+                                保存修改
+                            </Button>
+                            <Button onClick={handleReset}>重 置</Button>
+                            <Button onClick={() => navigate('/')}>取消</Button>
+                        </div>
+                    </Form>
+                </div>
+            </div>
+        </div>
+    );
+};
+
+export default ProfileSettingsPage;

apps/web/src/pages/shops/ShopsPage.css

@@ -0,0 +1,11 @@
+.shops-page {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+}
+
+.shops-load-more {
+    display: flex;
+    justify-content: center;
+    margin-top: 16px;
+}

apps/web/src/pages/shops/ShopsPage.tsx

@@ -0,0 +1,735 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+    App as AntdApp,
+    Button,
+    Card,
+    Dropdown,
+    Empty,
+    Form,
+    Input,
+    Modal,
+    Select,
+    Space,
+    Switch,
+    Table,
+    Tag,
+    Tooltip,
+    Typography,
+} from 'antd';
+import type { MenuProps, TableProps } from 'antd';
+import {
+    ApiOutlined,
+    CloudDownloadOutlined,
+    DeleteOutlined,
+    MoreOutlined,
+    PlusOutlined,
+    ReloadOutlined,
+} from '@ant-design/icons';
+import axios from 'axios';
+import type { Store, WatermarkTemplate } from '@atlas/contracts';
+import { apiErrorCode, apiErrorMessage } from '@/services/api';
+import { storesApi } from '@/services/stores';
+import { watermarksApi } from '@/services/watermarks';
+import { operationsApi, OPERATION_TERMINAL_STATUSES } from '@/services/operations';
+import { usePlatform } from '@/services/platform';
+import './ShopsPage.css';
+
+const STORE_STATUS_MAP: Record<string, { color: string; text: string }> = {
+    verifying: { color: 'gold', text: '验证中' },
+    active: { color: 'green', text: '正常' },
+    credential_invalid: { color: 'red', text: '凭据无效' },
+    sync_error: { color: 'orange', text: '同步异常' },
+    disabled: { color: 'default', text: '已停用' },
+    deleted: { color: 'default', text: '已删除' },
+};
+
+interface StoreStatusView {
+    color: string;
+    text: string;
+    /** 状态附注，如「等待平台验证结果」或凭据验证的脱敏原因 */
+    note?: string;
+}
+
+/**
+ * 把门店生命周期状态（status）与凭据状态（credential_status）派生为单一展示状态，
+ * 避免两个内部状态并列渲染造成「验证中 + 未验证」的误导：
+ * - verifying（或凭据仍 unknown，Atlas 尚未拿到验证结果）：只显示「验证中」并附注
+ * - active 且凭据 valid：正常
+ * - 凭据验证失败：401 → 凭据无效；403 → 访问被拒绝（提示检查 Client ID/API Key 归属与权限）
+ * - 同步异常：直接展示 last_error.message——HTTP 400/404/422、超时/429/5xx 等
+ *   验证请求失败不代表 API Key 无效（OZON_VERIFICATION_UNAVAILABLE 的消息即「暂时无法验证」）
+ * 未穷举的组合按凭据状态（过期/待轮换）或生命周期兜底。
+ */
+function deriveStoreStatusView(store: Store): StoreStatusView {
+    const { status, credential_status: credential, last_error } = store;
+    if (status === 'verifying' || credential === 'unknown') {
+        return { color: 'gold', text: '验证中', note: '等待平台验证结果' };
+    }
+    if (status === 'credential_invalid' || credential === 'invalid') {
+        if (last_error?.code === 'OZON_CREDENTIAL_FORBIDDEN') {
+            return {
+                color: 'red',
+                text: '访问被拒绝',
+                note: '请检查 Client ID、API Key 是否同账户，以及密钥是否有读取权限',
+            };
+        }
+        return { color: 'red', text: '凭据无效' };
+    }
+    if (status === 'sync_error') {
+        return {
+            color: 'orange',
+            text: '同步异常',
+            note: last_error?.message ?? '同步过程出现异常，可重新发起仓库同步或凭据验证',
+        };
+    }
+    if (status === 'active' && credential === 'valid') {
+        return { color: 'green', text: '正常' };
+    }
+    if (credential === 'expired') {
+        return { color: 'red', text: '凭据已过期' };
+    }
+    if (credential === 'rotation_required') {
+        return { color: 'gold', text: '凭据待轮换' };
+    }
+    const fallback = STORE_STATUS_MAP[status];
+    return fallback ?? { color: 'default', text: status };
+}
+
+function formatDateTime(value: string | null): string {
+    if (!value) return '—';
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? '—' : date.toLocaleString('zh-CN', { hour12: false });
+}
+
+interface CreateFormValues {
+    name: string;
+    client_id: string;
+    api_key: string;
+    currency_code: string;
+    is_default: boolean;
+    note?: string;
+}
+
+interface EditFormValues {
+    name: string;
+    currency_code: string;
+    note?: string;
+    api_key?: string;
+    watermark_template_id?: string | null;
+}
+
+/**
+ * 店铺管理页，契约见 docs/api/stores-and-platforms.md。
+ * 列表按页头当前平台过滤（platform_id 查询参数）；创建与密钥替换为异步验证，
+ * Worker 消费验证操作前店铺会停留在「验证中」状态。
+ */
+const ShopsPage = () => {
+    const { message, modal } = AntdApp.useApp();
+    const {
+        currentPlatform,
+        platforms,
+        error: platformError,
+        reload,
+        refreshContext,
+    } = usePlatform();
+
+    const [stores, setStores] = useState<Store[]>([]);
+    const [nextCursor, setNextCursor] = useState<string | null>(null);
+    const [loading, setLoading] = useState(false);
+    const [loadingMore, setLoadingMore] = useState(false);
+    const [pendingStoreId, setPendingStoreId] = useState<string | null>(null);
+
+    const [createOpen, setCreateOpen] = useState(false);
+    const [creating, setCreating] = useState(false);
+    const [createForm] = Form.useForm<CreateFormValues>();
+
+    const [editingStore, setEditingStore] = useState<Store | null>(null);
+    const [saving, setSaving] = useState(false);
+    const [editForm] = Form.useForm<EditFormValues>();
+
+    // 水印模板选项（工作空间全量活动模板，量小一次拉取）
+    const [watermarkTemplates, setWatermarkTemplates] = useState<WatermarkTemplate[]>([]);
+    const bindingBeforeRef = useRef<string | null>(null);
+
+    const platformId = currentPlatform?.id ?? null;
+    const currencyOptions = useMemo(
+        () =>
+            (currentPlatform?.supported_currencies ?? []).map((code) => ({
+                value: code,
+                label: code,
+            })),
+        [currentPlatform]
+    );
+
+    const loadStores = useCallback(
+        async (targetPlatformId: string) => {
+            setLoading(true);
+            try {
+                const result = await storesApi.list(targetPlatformId);
+                setStores(result.data);
+                setNextCursor(result.meta.next_cursor);
+            } catch (err) {
+                message.error(apiErrorMessage(err));
+            } finally {
+                setLoading(false);
+            }
+        },
+        [message]
+    );
+
+    useEffect(() => {
+        if (!platformId) return;
+        void loadStores(platformId);
+    }, [platformId, loadStores]);
+
+    const loadMore = async () => {
+        if (!platformId || !nextCursor) return;
+        setLoadingMore(true);
+        try {
+            const result = await storesApi.list(platformId, nextCursor);
+            setStores((prev) => [...prev, ...result.data]);
+            setNextCursor(result.meta.next_cursor);
+        } catch (err) {
+            message.error(apiErrorMessage(err));
+        } finally {
+            setLoadingMore(false);
+        }
+    };
+
+    // 水印模板选项与平台无关（工作空间全量），挂载后拉取一次
+    useEffect(() => {
+        void watermarksApi
+            .list()
+            .then((result) => setWatermarkTemplates(result.data))
+            .catch(() => setWatermarkTemplates([]));
+    }, []);
+
+    /** 任何变更后同时刷新列表与页头默认门店摘要 */
+    const refreshAll = useCallback(async () => {
+        if (!platformId) return;
+        await loadStores(platformId);
+        await refreshContext();
+    }, [platformId, loadStores, refreshContext]);
+
+    // 组件卸载后停止轮询
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+
+    /**
+     * 轮询异步验证/同步操作至终态，随后刷新列表。
+     * 页面最终状态以刷新后的店铺资源为准（成败原因看店铺 last_error），不以 operation 为准；
+     * 超时未终态则停止轮询并刷新一次，用户可手动刷新继续观察。
+     */
+    const pollOperation = useCallback(
+        async (operationId: string) => {
+            const intervalMs = 2500;
+            const maxAttempts = 40;
+            for (let attempt = 0; attempt < maxAttempts; attempt++) {
+                await new Promise((resolve) => setTimeout(resolve, intervalMs));
+                if (!mountedRef.current) return;
+                try {
+                    const operation = await operationsApi.get(operationId);
+                    if (OPERATION_TERMINAL_STATUSES.has(operation.status)) break;
+                } catch {
+                    // 单次查询失败（网络抖动等）忽略，继续下一轮
+                }
+            }
+            if (mountedRef.current) await refreshAll();
+        },
+        [refreshAll]
+    );
+
+    const openCreate = () => {
+        createForm.resetFields();
+        createForm.setFieldsValue({
+            is_default: stores.length === 0,
+            currency_code: currentPlatform?.default_currency_code ?? currencyOptions[0]?.value,
+        });
+        setCreateOpen(true);
+    };
+
+    const handleCreate = async (values: CreateFormValues) => {
+        if (!currentPlatform) return;
+        setCreating(true);
+        try {
+            const result = await storesApi.create({
+                platform_id: currentPlatform.id,
+                name: values.name.trim(),
+                client_id: values.client_id.trim(),
+                api_key: values.api_key,
+                currency_code: values.currency_code,
+                is_default: values.is_default,
+                note: values.note?.trim() ? values.note.trim() : null,
+            });
+            message.success('店铺已创建，正在验证凭据，结果将自动刷新');
+            setCreateOpen(false);
+            await refreshAll();
+            // 轮询验证操作至终态后自动刷新，无需手动刷新页面
+            if (result?.operation) void pollOperation(result.operation.id);
+        } catch (err) {
+            message.error(apiErrorMessage(err));
+        } finally {
+            setCreating(false);
+        }
+    };
+
+    const openEdit = (store: Store) => {
+        setEditingStore(store);
+        bindingBeforeRef.current = store.watermark_template?.id ?? null;
+        editForm.setFieldsValue({
+            name: store.name,
+            currency_code: store.currency_code,
+            note: store.note ?? '',
+            watermark_template_id: store.watermark_template?.id ?? null,
+        });
+    };
+
+    const handleEditSave = async (values: EditFormValues) => {
+        if (!editingStore) return;
+        const storeId = editingStore.id;
+        const bindingBefore = bindingBeforeRef.current;
+        const bindingAfter = values.watermark_template_id ?? null;
+        const bindingChanged = bindingBefore !== bindingAfter;
+        setSaving(true);
+        try {
+            const result = await storesApi.update(
+                storeId,
+                {
+                    name: values.name.trim(),
+                    currency_code: values.currency_code,
+                    note: values.note?.trim() ? values.note.trim() : null,
+                    // 留空表示保留旧密钥；填写则替换并重新触发验证
+                    ...(values.api_key ? { api_key: values.api_key } : {}),
+                },
+                { revision: editingStore.revision }
+            );
+            // 水印绑定是独立接口，仅在与打开弹窗时不同才提交
+            if (bindingChanged) {
+                await storesApi.bindWatermark(storeId, bindingAfter);
+            }
+            if (result && 'operation' in result && result.operation) {
+                message.success('已保存，正在验证新密钥，结果将自动刷新');
+                setEditingStore(null);
+                await refreshAll();
+                void pollOperation(result.operation.id);
+            } else {
+                message.success('店铺已保存');
+                setEditingStore(null);
+                await refreshAll();
+            }
+        } catch (err) {
+            // 乐观锁版本过期：提示后刷新列表，用户重新编辑拿到新 revision
+            if (axios.isAxiosError(err) && err.response?.status === 409) {
+                message.error('店铺信息已被其他操作更新，列表已刷新，请重新编辑');
+                setEditingStore(null);
+                await refreshAll();
+            } else {
+                message.error(apiErrorMessage(err));
+            }
+        } finally {
+            setSaving(false);
+        }
+    };
+
+    const withPending = async (store: Store, action: () => Promise<unknown>) => {
+        setPendingStoreId(store.id);
+        try {
+            await action();
+            await refreshAll();
+        } catch (err) {
+            message.error(apiErrorMessage(err));
+        } finally {
+            setPendingStoreId(null);
+        }
+    };
+
+    const handleSetDefault = (store: Store) =>
+        withPending(store, async () => {
+            await storesApi.setDefault(store.id);
+            message.success(`已将「${store.name}」设为默认店铺`);
+        });
+
+    const handleVerify = (store: Store) =>
+        withPending(store, async () => {
+            const result = await storesApi.requestCredentialVerification(store.id);
+            message.success('已发起凭据验证，结果将自动刷新');
+            if (result?.operation) void pollOperation(result.operation.id);
+        });
+
+    const handleSyncWarehouses = (store: Store) =>
+        withPending(store, async () => {
+            const result = await storesApi.requestWarehouseSync(store.id);
+            message.success('已发起仓库同步，结果将自动刷新');
+            if (result?.operation) void pollOperation(result.operation.id);
+        });
+
+    const handleDelete = (store: Store) => {
+        modal.confirm({
+            title: '删除店铺',
+            content: `仅删除 Atlas 内的店铺连接，不影响平台后台。确定删除「${store.name}」吗？`,
+            okText: '删除',
+            okButtonProps: { danger: true },
+            cancelText: '取消',
+            onOk: () =>
+                withPending(store, async () => {
+                    try {
+                        await storesApi.remove(store.id);
+                        message.success('店铺已删除');
+                    } catch (err) {
+                        if (apiErrorCode(err) === 'DEFAULT_STORE_REPLACEMENT_REQUIRED') {
+                            message.error(
+                                '该店铺是默认店铺，请先将同平台的其他店铺设为默认，再删除'
+                            );
+                            return;
+                        }
+                        throw err;
+                    }
+                }),
+        });
+    };
+
+    const rowMenu = (store: Store): MenuProps['items'] => [
+        {
+            key: 'set-default',
+            icon: <ApiOutlined />,
+            label: '设为默认店铺',
+            disabled: store.is_default,
+        },
+        { key: 'verify', icon: <ReloadOutlined />, label: '重新验证凭据' },
+        { key: 'sync', icon: <CloudDownloadOutlined />, label: '同步仓库' },
+        { type: 'divider' },
+        { key: 'delete', icon: <DeleteOutlined />, label: '删除店铺', danger: true },
+    ];
+
+    const handleRowMenuClick =
+        (store: Store): MenuProps['onClick'] =>
+        ({ key }) => {
+            if (key === 'set-default') void handleSetDefault(store);
+            else if (key === 'verify') void handleVerify(store);
+            else if (key === 'sync') void handleSyncWarehouses(store);
+            else if (key === 'delete') handleDelete(store);
+        };
+
+    const columns: TableProps<Store>['columns'] = [
+        {
+            title: '店铺名称',
+            dataIndex: 'name',
+            width: 220,
+            render: (_, store) => (
+                <Space size={6}>
+                    <span>{store.name}</span>
+                    {store.is_default && <Tag color="purple">默认</Tag>}
+                </Space>
+            ),
+        },
+        {
+            title: 'Client ID',
+            dataIndex: 'platform_client_id',
+            width: 150,
+            render: (value: string) => (
+                <Typography.Text copyable={{ text: value }}>{value}</Typography.Text>
+            ),
+        },
+        {
+            title: '币种',
+            dataIndex: 'currency_code',
+            width: 80,
+        },
+        {
+            title: '状态',
+            dataIndex: 'status',
+            width: 200,
+            render: (_, store) => {
+                const view = deriveStoreStatusView(store);
+                return (
+                    <Space size={4} wrap>
+                        <Tag color={view.color}>{view.text}</Tag>
+                        {view.note && (
+                            <Typography.Text
+                                type="secondary"
+                                style={{ fontSize: 12, maxWidth: 180 }}
+                                ellipsis={{ tooltip: view.note }}
+                            >
+                                {view.note}
+                            </Typography.Text>
+                        )}
+                    </Space>
+                );
+            },
+        },
+        {
+            title: '仓库',
+            dataIndex: 'warehouse_count',
+            width: 90,
+            render: (count: number, store) => (
+                <Tooltip
+                    title={
+                        store.warehouses_synced_at
+                            ? `同步于 ${formatDateTime(store.warehouses_synced_at)}`
+                            : '尚未同步仓库'
+                    }
+                >
+                    <span>{store.warehouses_synced_at ? count : '—'}</span>
+                </Tooltip>
+            ),
+        },
+        {
+            title: '水印模板',
+            dataIndex: 'watermark_template',
+            width: 130,
+            render: (template: Store['watermark_template']) =>
+                template ? (
+                    template.name
+                ) : (
+                    <Typography.Text type="secondary">未绑定</Typography.Text>
+                ),
+        },
+        {
+            title: '备注',
+            dataIndex: 'note',
+            ellipsis: true,
+            render: (note: string | null) =>
+                note ? (
+                    <Typography.Text ellipsis>{note}</Typography.Text>
+                ) : (
+                    <Typography.Text type="secondary">—</Typography.Text>
+                ),
+        },
+        {
+            title: '更新时间',
+            dataIndex: 'updated_at',
+            width: 170,
+            render: (value: string) => (
+                <Typography.Text type="secondary">{formatDateTime(value)}</Typography.Text>
+            ),
+        },
+        {
+            title: '操作',
+            key: 'actions',
+            width: 140,
+            fixed: 'right',
+            render: (_, store) => (
+                <Space size={4}>
+                    <Button type="link" size="small" onClick={() => openEdit(store)}>
+                        编辑
+                    </Button>
+                    <Dropdown
+                        menu={{ items: rowMenu(store), onClick: handleRowMenuClick(store) }}
+                        trigger={['click']}
+                    >
+                        <Button
+                            type="text"
+                            size="small"
+                            icon={<MoreOutlined />}
+                            loading={pendingStoreId === store.id}
+                        />
+                    </Dropdown>
+                </Space>
+            ),
+        },
+    ];
+
+    if (platformError) {
+        return (
+            <Card className="shops-page">
+                <Empty description={`平台目录加载失败：${platformError}`}>
+                    <Button onClick={reload}>重试</Button>
+                </Empty>
+            </Card>
+        );
+    }
+
+    return (
+        <div className="shops-page">
+            <Card
+                title={`店铺管理${currentPlatform ? ` · ${currentPlatform.name}` : ''}`}
+                extra={
+                    <Button
+                        type="primary"
+                        icon={<PlusOutlined />}
+                        disabled={!currentPlatform}
+                        onClick={openCreate}
+                    >
+                        添加店铺
+                    </Button>
+                }
+            >
+                {platforms.length === 0 && !currentPlatform ? (
+                    <Empty description="暂无可用平台" />
+                ) : (
+                    <>
+                        <Table
+                            rowKey="id"
+                            columns={columns}
+                            dataSource={stores}
+                            loading={loading}
+                            pagination={false}
+                            scroll={{ x: 1100 }}
+                            locale={{
+                                emptyText: currentPlatform
+                                    ? `当前平台还没有店铺，点击右上角「添加店铺」完成 ${currentPlatform.name} 授权`
+                                    : '请先在页头选择平台',
+                            }}
+                        />
+                        {nextCursor && (
+                            <div className="shops-load-more">
+                                <Button loading={loadingMore} onClick={() => void loadMore()}>
+                                    加载更多
+                                </Button>
+                            </div>
+                        )}
+                    </>
+                )}
+            </Card>
+
+            <Modal
+                title={`添加${currentPlatform?.name ?? ''}店铺`}
+                open={createOpen}
+                onCancel={() => setCreateOpen(false)}
+                onOk={() => createForm.submit()}
+                confirmLoading={creating}
+                okText="创建并验证"
+                cancelText="取消"
+                destroyOnHidden
+                maskClosable={false}
+            >
+                <Form<CreateFormValues> form={createForm} layout="vertical" onFinish={handleCreate}>
+                    <Form.Item
+                        name="name"
+                        label="店铺名称"
+                        required
+                        rules={[{ required: true, whitespace: true, message: '请输入店铺名称' }]}
+                    >
+                        <Input maxLength={120} placeholder="例如：Ozon 俄罗斯主店" />
+                    </Form.Item>
+                    <Form.Item
+                        name="client_id"
+                        label="Client ID"
+                        required
+                        rules={[
+                            { required: true, whitespace: true, message: '请输入平台 Client ID' },
+                        ]}
+                    >
+                        <Input maxLength={120} placeholder="平台后台的 Client ID" />
+                    </Form.Item>
+                    <Form.Item
+                        name="api_key"
+                        label="API Key"
+                        required
+                        rules={[
+                            { required: true, whitespace: true, message: '请输入平台 API Key' },
+                        ]}
+                        extra="仅用于服务端加密保存与凭据验证，不会出现在日志或响应中"
+                    >
+                        {/* 契约上限 8192（packages/contracts/src/stores.ts），不自行收紧 */}
+                        <Input.Password
+                            maxLength={8192}
+                            placeholder="平台后台的 API Key"
+                            autoComplete="new-password"
+                        />
+                    </Form.Item>
+                    <Form.Item
+                        name="currency_code"
+                        label="默认计价币种"
+                        required
+                        rules={[{ required: true, message: '请选择币种' }]}
+                    >
+                        <Select options={currencyOptions} placeholder="选择币种" />
+                    </Form.Item>
+                    <Form.Item name="is_default" label="设为默认店铺" valuePropName="checked">
+                        <Switch />
+                    </Form.Item>
+                    <Form.Item
+                        name="note"
+                        label="备注"
+                        rules={[{ max: 2000, message: '备注不能超过 2000 字' }]}
+                    >
+                        <Input.TextArea rows={2} maxLength={2000} placeholder="选填" />
+                    </Form.Item>
+                </Form>
+            </Modal>
+
+            <Modal
+                title={editingStore ? `编辑店铺：${editingStore.name}` : '编辑店铺'}
+                open={!!editingStore}
+                onCancel={() => setEditingStore(null)}
+                onOk={() => editForm.submit()}
+                confirmLoading={saving}
+                okText="保存"
+                cancelText="取消"
+                destroyOnHidden
+                maskClosable={false}
+            >
+                {editingStore && (
+                    <Form<EditFormValues>
+                        form={editForm}
+                        layout="vertical"
+                        onFinish={handleEditSave}
+                    >
+                        <Form.Item
+                            name="name"
+                            label="店铺名称"
+                            required
+                            rules={[{ required: true, message: '请输入店铺名称' }]}
+                        >
+                            <Input maxLength={120} />
+                        </Form.Item>
+                        <Form.Item
+                            name="currency_code"
+                            label="默认计价币种"
+                            required
+                            rules={[{ required: true, message: '请选择币种' }]}
+                        >
+                            <Select options={currencyOptions} />
+                        </Form.Item>
+                        <Form.Item
+                            name="note"
+                            label="备注"
+                            rules={[{ max: 2000, message: '备注不能超过 2000 字' }]}
+                        >
+                            <Input.TextArea rows={2} maxLength={2000} placeholder="选填" />
+                        </Form.Item>
+                        <Form.Item
+                            name="api_key"
+                            label="替换 API Key"
+                            extra="留空保留现有密钥；填写后将替换并重新验证凭据"
+                        >
+                            <Input.Password
+                                maxLength={8192}
+                                placeholder="不修改请留空"
+                                autoComplete="new-password"
+                            />
+                        </Form.Item>
+                        <Form.Item
+                            name="watermark_template_id"
+                            label="水印模板"
+                            extra="作为商品图片编辑时的推荐水印；可随时更换或清空"
+                        >
+                            <Select
+                                allowClear
+                                placeholder="暂不绑定"
+                                notFoundContent="暂无水印模板，可在水印管理页创建"
+                                options={watermarkTemplates.map((template) => ({
+                                    value: template.id,
+                                    label: template.name,
+                                }))}
+                            />
+                        </Form.Item>
+                        <Form.Item label="Client ID">
+                            <Typography.Text type="secondary">
+                                {editingStore.platform_client_id}（平台与账户不可修改）
+                            </Typography.Text>
+                        </Form.Item>
+                    </Form>
+                )}
+            </Modal>
+        </div>
+    );
+};
+
+export default ShopsPage;

apps/web/src/pages/watermarks/WatermarksPage.tsx

@@ -0,0 +1,990 @@
+import dayjs from 'dayjs';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+    App as AntdApp,
+    Button,
+    Card,
+    DatePicker,
+    Form,
+    Input,
+    InputNumber,
+    Modal,
+    Select,
+    Slider,
+    Space,
+    Spin,
+    Table,
+    Tag,
+    Tooltip,
+    Typography,
+    Upload,
+} from 'antd';
+import type { TableProps, UploadFile } from 'antd';
+import {
+    FileImageOutlined,
+    PlusOutlined,
+    ReloadOutlined,
+    RestOutlined,
+} from '@ant-design/icons';
+import axios from 'axios';
+import type {
+    UpdateWatermarkTemplateRequest,
+    WatermarkTemplate,
+    WatermarkTemplateConfig,
+} from '@atlas/contracts';
+import WatermarkPreview, {
+    WATERMARK_POSITION_OPTIONS,
+    watermarkPositionLabel,
+} from '@/components/WatermarkPreview';
+import { apiErrorDetails, apiErrorMessage } from '@/services/api';
+import { watermarksApi } from '@/services/watermarks';
+import { mediaApi } from '@/services/media';
+import {
+    uploadWatermarkImage,
+    WATERMARK_IMAGE_ACCEPT,
+    WATERMARK_IMAGE_MAX_BYTES,
+} from '@/services/media';
+
+type WatermarkPositionValue = (typeof WATERMARK_POSITION_OPTIONS)[number]['value'];
+type WatermarkKind = 'text' | 'image';
+
+interface WatermarkFormValues {
+    name: string;
+    kind: WatermarkKind;
+    text_content: string;
+    font_code: string;
+    font_size_px: number;
+    opacityPercent: number;
+    scalePercent: number;
+    position: WatermarkPositionValue;
+}
+
+type KindFilter = 'all' | 'text' | 'image';
+
+const KIND_TAG: Record<string, { color: string; text: string }> = {
+    image: { color: 'green', text: '图片水印' },
+    text: { color: 'blue', text: '文字水印' },
+};
+
+const percentToOpacity = (percent: number): string => {
+    const value = percent / 100;
+    return value === 0 ? '0' : value === 1 ? '1' : String(Number(value.toFixed(4)));
+};
+
+const percentToScale = (percent: number): string => {
+    const value = percent / 100;
+    return value === 2 ? '2' : String(Number(value.toFixed(4)));
+};
+
+const formatDateTime = (value: string): string =>
+    new Date(value).toLocaleString('zh-CN', { hour12: false });
+
+/**
+ * 水印管理页，契约见 docs/api/watermarks-and-assets.md。
+ * 列表接口只有 cursor/limit 参数，类型/名称/日期筛选为纯客户端过滤；
+ * 图片水印经三步直传创建素材（services/media.ts），编辑弹窗按 config 实时渲染预览。
+ */
+const WatermarksPage = () => {
+    const { message, modal } = AntdApp.useApp();
+
+    const [templates, setTemplates] = useState<WatermarkTemplate[]>([]);
+    const [nextCursor, setNextCursor] = useState<string | null>(null);
+    const [loading, setLoading] = useState(false);
+    const [loadingMore, setLoadingMore] = useState(false);
+
+    const [fonts, setFonts] = useState<Array<{ code: string; display_name: string }>>([]);
+
+    // 筛选：输入草稿 + 点击「查询」后生效的已应用条件（纯客户端过滤）
+    const [kindDraft, setKindDraft] = useState<KindFilter>('all');
+    const [nameDraft, setNameDraft] = useState('');
+    const [dateDraft, setDateDraft] = useState<[string, string] | null>(null);
+    const [kindFilter, setKindFilter] = useState<KindFilter>('all');
+    const [nameFilter, setNameFilter] = useState('');
+    const [dateFilter, setDateFilter] = useState<[string, string] | null>(null);
+
+    const [selectedIds, setSelectedIds] = useState<string[]>([]);
+    const [batchDeleting, setBatchDeleting] = useState(false);
+
+    const [editorOpen, setEditorOpen] = useState(false);
+    const [saving, setSaving] = useState(false);
+    const [editing, setEditing] = useState<WatermarkTemplate | null>(null);
+    const [previewing, setPreviewing] = useState<WatermarkTemplate | null>(null);
+    const [form] = Form.useForm<WatermarkFormValues>();
+
+    // 图片水印：已上传（或既有）的素材；previewUrl 用于本地/短时预览
+    const [uploadingImage, setUploadingImage] = useState(false);
+    const [imageAsset, setImageAsset] = useState<{ id: string; previewUrl: string } | null>(null);
+
+    // 图片素材短时预览 URL 缓存（列表不返回 preview_url，按需经 access-urls 换取）
+    const [assetPreviewUrls, setAssetPreviewUrls] = useState<Record<string, string>>({});
+
+    // 实时预览：随渲染相关字段变化
+    const [previewValues, setPreviewValues] = useState<WatermarkFormValues | null>(null);
+
+    const loadTemplates = useCallback(
+        async (cursor?: string) => {
+            if (!cursor) setLoading(true);
+            else setLoadingMore(true);
+            try {
+                const result = await watermarksApi.list(cursor);
+                setTemplates((prev) => (cursor ? [...prev, ...result.data] : result.data));
+                setNextCursor(result.meta.has_more ? result.meta.next_cursor : null);
+            } catch (err) {
+                message.error(apiErrorMessage(err));
+            } finally {
+                setLoading(false);
+                setLoadingMore(false);
+            }
+        },
+        [message]
+    );
+
+    useEffect(() => {
+        void loadTemplates();
+        void watermarksApi
+            .fonts()
+            .then(setFonts)
+            .catch(() => setFonts([]));
+    }, [loadTemplates]);
+
+    // 为图片模板按需换取短时预览 URL（缓存后 10 分钟内复用）
+    useEffect(() => {
+        const missing = templates.filter(
+            (template) =>
+                template.kind === 'image' &&
+                template.config.image_asset &&
+                !assetPreviewUrls[template.config.image_asset.id]
+        );
+        for (const template of missing) {
+            const assetId = template.config.image_asset!.id;
+            mediaApi
+                .createPreviewUrl(assetId)
+                .then(({ url }) => setAssetPreviewUrls((prev) => ({ ...prev, [assetId]: url })))
+                .catch(() => undefined);
+        }
+    }, [templates, assetPreviewUrls]);
+
+    /**
+     * 模板列表不承诺始终带预览 URL；编辑既有图片模板时按需换取新的短时地址。
+     * 这样不会把对象存储 URL 写入模板数据，也避免打开编辑框时只显示空占位。
+     */
+    const loadAssetPreviewUrl = useCallback(
+        async (assetId: string): Promise<string> => {
+            const cached = assetPreviewUrls[assetId];
+            if (cached) return cached;
+            const access = await mediaApi.createPreviewUrl(assetId);
+            setAssetPreviewUrls((previous) => ({ ...previous, [assetId]: access.url }));
+            return access.url;
+        },
+        [assetPreviewUrls]
+    );
+
+    const filtered = useMemo(
+        () =>
+            templates.filter((template) => {
+                if (kindFilter !== 'all' && template.kind !== kindFilter) return false;
+                if (nameFilter && !template.name.includes(nameFilter.trim())) return false;
+                if (dateFilter) {
+                    const created = template.created_at.slice(0, 10);
+                    const [start, end] = dateFilter;
+                    if (start && created < start) return false;
+                    if (end && created > end) return false;
+                }
+                return true;
+            }),
+        [templates, kindFilter, nameFilter, dateFilter]
+    );
+
+    /** 创建/编辑成功后就地更新列表数据（服务端返回完整模板资源） */
+    const applyTemplate = (template: WatermarkTemplate) => {
+        setTemplates((prev) => {
+            const index = prev.findIndex((item) => item.id === template.id);
+            if (index === -1) return [template, ...prev];
+            const next = [...prev];
+            next[index] = template;
+            return next;
+        });
+    };
+
+    const openCreate = () => {
+        setEditing(null);
+        setImageAsset(null);
+        const initial: WatermarkFormValues = {
+            name: '',
+            kind: 'text',
+            text_content: '',
+            font_code: fonts[0]?.code ?? '',
+            font_size_px: 24,
+            opacityPercent: 80,
+            scalePercent: 25,
+            position: 'bottom_right',
+        };
+        form.setFieldsValue(initial);
+        setPreviewValues(initial);
+        setEditorOpen(true);
+    };
+
+    const openEdit = (template: WatermarkTemplate) => {
+        setEditing(template);
+        const config = template.config;
+        const assetId = config.image_asset?.id ?? config.image_asset_id ?? null;
+        setImageAsset(
+            template.kind === 'image' && assetId
+                ? { id: assetId, previewUrl: assetPreviewUrls[assetId] ?? '' }
+                : null
+        );
+        const initial: WatermarkFormValues = {
+            name: template.name,
+            kind: template.kind,
+            text_content: config.text_content ?? '',
+            font_code: config.font_code ?? fonts[0]?.code ?? '',
+            font_size_px: config.font_size_px ?? 24,
+            opacityPercent: Math.round(Number(config.opacity ?? '0.8') * 100),
+            scalePercent: Math.round(Number(config.scale_ratio ?? '0.25') * 100),
+            position: config.position,
+        };
+        form.setFieldsValue(initial);
+        setPreviewValues(initial);
+        setEditorOpen(true);
+
+        if (template.kind === 'image' && assetId && !assetPreviewUrls[assetId]) {
+            void loadAssetPreviewUrl(assetId)
+                .then((previewUrl) => {
+                    setImageAsset((current) =>
+                        current?.id === assetId
+                            ? { id: assetId, previewUrl }
+                            : current
+                    );
+                })
+                .catch(() => undefined);
+        }
+    };
+
+    /**
+     * 类型切换会丢弃另一种类型的专属配置（尤其是已上传图片），先明确告知用户。
+     * 表单字段由这里显式写入，避免 Select 在确认框出现前就提交了类型变更。
+     */
+    const requestKindChange = (nextKind: WatermarkKind) => {
+        const currentKind = form.getFieldValue('kind') as WatermarkKind | undefined;
+        if (!currentKind || currentKind === nextKind) return;
+        const applyChange = () => {
+            form.setFieldValue('kind', nextKind);
+            setPreviewValues((previous) => ({
+                ...(previous ?? (form.getFieldsValue() as WatermarkFormValues)),
+                kind: nextKind,
+            }));
+            if (currentKind === 'image') setImageAsset(null);
+        };
+        modal.confirm({
+            title: '切换水印类型',
+            content: '切换后将清空当前类型的专属配置，是否继续？',
+            okText: '继续切换',
+            cancelText: '取消',
+            onOk: applyChange,
+        });
+    };
+
+    const handleBeforeUpload = async (file: UploadFile): Promise<boolean> => {
+        const okTypes = ['image/png', 'image/jpeg', 'image/webp'];
+        if (!okTypes.includes(file.type ?? '')) {
+            message.error('仅支持 JPG、PNG、WebP 格式图片');
+            return false;
+        }
+        if ((file.size ?? 0) > WATERMARK_IMAGE_MAX_BYTES) {
+            message.error('图片大小不能超过 5MB');
+            return false;
+        }
+        setUploadingImage(true);
+        try {
+            const asset = await uploadWatermarkImage(file as unknown as File);
+            setImageAsset({
+                id: asset.id,
+                previewUrl: URL.createObjectURL(file as unknown as File),
+            });
+            message.success('图片已上传并通过校验');
+        } catch (err) {
+            message.error(apiErrorMessage(err));
+        } finally {
+            setUploadingImage(false);
+        }
+        // 阻止 antd 自动上传：上传由三步直传流程接管
+        return false;
+    };
+
+    const handleSave = async (values: WatermarkFormValues) => {
+        if (values.kind === 'image' && !imageAsset) {
+            message.error('请先上传水印图片');
+            return;
+        }
+        setSaving(true);
+        try {
+            // 滑杆字段在类型切换后可能缺值，统一兜底默认值，避免 NaN
+            const opacity = percentToOpacity(values.opacityPercent ?? 80);
+            const scaleRatio = percentToScale(values.scalePercent ?? 25);
+            // 编辑时只提交有变化的字段：渲染参数未变时仅改名，
+            // 服务端不会创建新的渲染版本（docs/api/watermarks-and-assets.md §3.3）；
+            // 切换类型必须提交新类型的完整 config。
+            if (editing) {
+                let payload: UpdateWatermarkTemplateRequest;
+                if (editing.kind !== values.kind) {
+                    // 切换类型：提交新类型完整 config
+                    let config: UpdateWatermarkTemplateRequest['config'];
+                    if (values.kind === 'text') {
+                        config = {
+                            text_content: values.text_content?.trim() ?? '',
+                            font_code: values.font_code,
+                            font_size_px: values.font_size_px,
+                            opacity,
+                            position: values.position,
+                        };
+                    } else {
+                        config = {
+                            image_asset_id: imageAsset?.id ?? '',
+                            scale_ratio: scaleRatio,
+                            opacity,
+                            position: values.position,
+                        };
+                    }
+                    payload = { kind: values.kind, config };
+                    if (values.name.trim() !== editing.name) {
+                        payload.name = values.name.trim();
+                    }
+                } else if (values.kind === 'text') {
+                    const current = editing.config;
+                    const diff: UpdateWatermarkTemplateRequest = {};
+                    if (values.name.trim() !== editing.name) {
+                        diff.name = values.name.trim();
+                    }
+                    const configPatch: NonNullable<UpdateWatermarkTemplateRequest['config']> = {};
+                    if (values.text_content?.trim() !== current.text_content) {
+                        configPatch.text_content = values.text_content.trim();
+                    }
+                    if (values.font_code !== current.font_code) {
+                        configPatch.font_code = values.font_code;
+                    }
+                    if (values.font_size_px !== current.font_size_px) {
+                        configPatch.font_size_px = values.font_size_px;
+                    }
+                    if (Number(opacity) !== Number(current.opacity)) {
+                        configPatch.opacity = opacity;
+                    }
+                    if (values.position !== current.position) {
+                        configPatch.position = values.position;
+                    }
+                    if (Object.keys(configPatch).length > 0) {
+                        diff.config = configPatch;
+                    }
+                    payload = diff;
+                } else {
+                    const current = editing.config;
+                    const diff: UpdateWatermarkTemplateRequest = {};
+                    if (values.name.trim() !== editing.name) {
+                        diff.name = values.name.trim();
+                    }
+                    const configPatch: NonNullable<UpdateWatermarkTemplateRequest['config']> = {};
+                    const currentAssetId = current.image_asset?.id ?? current.image_asset_id;
+                    if (imageAsset && imageAsset.id !== currentAssetId) {
+                        configPatch.image_asset_id = imageAsset.id;
+                    }
+                    if (percentToScale(values.scalePercent) !== current.scale_ratio) {
+                        configPatch.scale_ratio = scaleRatio;
+                    }
+                    if (Number(opacity) !== Number(current.opacity)) {
+                        configPatch.opacity = opacity;
+                    }
+                    if (values.position !== current.position) {
+                        configPatch.position = values.position;
+                    }
+                    if (Object.keys(configPatch).length > 0) {
+                        diff.config = configPatch;
+                    }
+                    payload = diff;
+                }
+                if (Object.keys(payload).length === 0) {
+                    message.info('内容没有变化，无需保存');
+                    setEditorOpen(false);
+                    return;
+                }
+                const template = await watermarksApi.update(editing.id, payload, {
+                    revision: editing.revision,
+                });
+                applyTemplate(template);
+                message.success('水印模板已保存');
+            } else if (values.kind === 'text') {
+                const template = await watermarksApi.create({
+                    name: values.name.trim(),
+                    kind: 'text',
+                    config: {
+                        text_content: values.text_content.trim(),
+                        font_code: values.font_code,
+                        font_size_px: values.font_size_px,
+                        opacity,
+                        position: values.position,
+                    },
+                });
+                applyTemplate(template);
+                message.success('水印模板已创建');
+            } else {
+                const template = await watermarksApi.create({
+                    name: values.name.trim(),
+                    kind: 'image',
+                    config: {
+                        image_asset_id: imageAsset?.id ?? '',
+                        scale_ratio: scaleRatio,
+                        opacity,
+                        position: values.position,
+                    },
+                });
+                applyTemplate(template);
+                message.success('水印模板已创建');
+            }
+            setEditorOpen(false);
+        } catch (err) {
+            if (axios.isAxiosError(err) && err.response?.status === 409) {
+                message.error('模板已被其他操作更新，请关闭后重新打开编辑');
+            } else {
+                const details = apiErrorDetails(err);
+                const knownFields: Array<keyof WatermarkFormValues> = [
+                    'name',
+                    'kind',
+                    'text_content',
+                    'font_code',
+                    'font_size_px',
+                    'opacityPercent',
+                    'scalePercent',
+                    'position',
+                ];
+                if (details.length > 0) {
+                    const fieldErrors = [];
+                    for (const item of details) {
+                        const field = item.field.replace(/^config\./, '');
+                        if (knownFields.includes(field as keyof WatermarkFormValues)) {
+                            fieldErrors.push({
+                                name: field as keyof WatermarkFormValues,
+                                errors: [item.message],
+                            });
+                        } else {
+                            message.error(item.message);
+                        }
+                    }
+                    if (fieldErrors.length > 0) {
+                        form.setFields(fieldErrors);
+                    }
+                } else {
+                    message.error(apiErrorMessage(err));
+                }
+            }
+        } finally {
+            setSaving(false);
+        }
+    };
+
+    /** 查看效果前刷新图片短时预览 URL（10 分钟有效） */
+    const openPreview = async (template: WatermarkTemplate) => {
+        if (template.kind === 'image') {
+            const assetId = template.config.image_asset?.id ?? template.config.image_asset_id ?? '';
+            // 缓存优先，缺失/过期时重新换取短时预览 URL
+            let url = assetPreviewUrls[assetId];
+            if (!url) {
+                try {
+                    url = await loadAssetPreviewUrl(assetId);
+                } catch {
+                    // 换取失败按原样打开，图片渲染失败会显示不可用提示
+                }
+            }
+            setPreviewing({
+                ...template,
+                config: {
+                    ...template.config,
+                    image_asset: {
+                        id: assetId,
+                        preview_url: url ?? '',
+                        preview_url_expires_at: '',
+                    },
+                },
+            });
+            return;
+        }
+        setPreviewing(template);
+    };
+
+    const confirmDelete = (targets: WatermarkTemplate[]) => {
+        const label =
+            targets.length === 1 ? `「${targets[0].name}」` : `${targets.length} 个水印模板`;
+        modal.confirm({
+            title: '删除水印模板',
+            content: `将删除${label}并解除所有店铺绑定，已生成的图片不受影响。确定删除吗？`,
+            okText: '删除',
+            okButtonProps: { danger: true },
+            cancelText: '取消',
+            onOk: async () => {
+                try {
+                    if (targets.length === 1) {
+                        await watermarksApi.remove(targets[0].id);
+                        message.success('水印模板已删除');
+                    } else {
+                        setBatchDeleting(true);
+                        let failed = 0;
+                        for (const template of targets) {
+                            try {
+                                await watermarksApi.remove(template.id);
+                            } catch (err) {
+                                failed += 1;
+                                message.error(`${template.name}：${apiErrorMessage(err)}`);
+                            }
+                        }
+                        if (failed === 0) {
+                            message.success(`已删除 ${targets.length} 个模板`);
+                        } else {
+                            message.warning(`已删除 ${targets.length - failed} 个，${failed} 个失败`);
+                        }
+                    }
+                    setSelectedIds([]);
+                    await loadTemplates();
+                } catch (err) {
+                    message.error(apiErrorMessage(err));
+                } finally {
+                    setBatchDeleting(false);
+                }
+            },
+        });
+    };
+
+    const columns: TableProps<WatermarkTemplate>['columns'] = [
+        {
+            title: '序号',
+            key: 'index',
+            width: 70,
+            render: (_, _record, index) => index + 1,
+        },
+        {
+            title: '模板名称',
+            dataIndex: 'name',
+            width: 220,
+            ellipsis: true,
+        },
+        {
+            title: '水印类型',
+            dataIndex: 'kind',
+            width: 110,
+            render: (kind: string) => {
+                const tag = KIND_TAG[kind] ?? { color: 'default', text: kind };
+                return <Tag color={tag.color}>{tag.text}</Tag>;
+            },
+        },
+        {
+            title: '水印内容',
+            key: 'content',
+            render: (_, template) => {
+                if (template.kind === 'image') {
+                    const assetId =
+                        template.config.image_asset?.id ?? template.config.image_asset_id;
+                    const previewUrl = assetId ? assetPreviewUrls[assetId] : undefined;
+                    return previewUrl ? (
+                        <img
+                            src={previewUrl}
+                            alt={template.name}
+                            style={{ width: 48, height: 48, objectFit: 'contain', borderRadius: 4 }}
+                        />
+                    ) : (
+                        <Tooltip title="正在获取图片预览">
+                            <FileImageOutlined style={{ fontSize: 20, color: '#9ca3af' }} />
+                        </Tooltip>
+                    );
+                }
+                return (
+                    <div>
+                        <div style={{ fontWeight: 600 }}>{template.config.text_content}</div>
+                        <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+                            {template.config.font_code}, {template.config.font_size_px}px, ■
+                        </Typography.Text>
+                    </div>
+                );
+            },
+        },
+        {
+            title: '水印位置',
+            key: 'position',
+            width: 110,
+            render: (_, template) => watermarkPositionLabel(template.config.position),
+        },
+        {
+            title: '版本',
+            dataIndex: 'current_version',
+            width: 70,
+            render: (version: number) => `v${version}`,
+        },
+        {
+            title: '创建时间',
+            dataIndex: 'created_at',
+            width: 170,
+            render: (value: string) => (
+                <Typography.Text type="secondary">{formatDateTime(value)}</Typography.Text>
+            ),
+        },
+        {
+            title: '操作',
+            key: 'actions',
+            width: 190,
+            render: (_, template) => (
+                <Space size={4}>
+                    <Button type="link" size="small" onClick={() => void openPreview(template)}>
+                        查看效果
+                    </Button>
+                    <Button type="link" size="small" onClick={() => openEdit(template)}>
+                        编辑
+                    </Button>
+                    <Button
+                        type="link"
+                        size="small"
+                        danger
+                        onClick={() => confirmDelete([template])}
+                    >
+                        删除
+                    </Button>
+                </Space>
+            ),
+        },
+    ];
+
+    const previewConfig = useMemo<Partial<WatermarkTemplateConfig>>(() => {
+        if (!previewValues) return {};
+        if (previewValues.kind === 'image') {
+            return {
+                image_asset: {
+                    id: imageAsset?.id ?? '',
+                    preview_url: imageAsset?.previewUrl ?? '',
+                    preview_url_expires_at: '',
+                },
+                scale_ratio: percentToScale(previewValues.scalePercent),
+                opacity: percentToOpacity(previewValues.opacityPercent),
+                position: previewValues.position,
+            };
+        }
+        return {
+            text_content: previewValues.text_content,
+            font_code: previewValues.font_code,
+            font_size_px: previewValues.font_size_px,
+            opacity: percentToOpacity(previewValues.opacityPercent),
+            position: previewValues.position,
+        };
+    }, [previewValues, imageAsset]);
+
+    return (
+        <div className="watermarks-page">
+            <Card
+                title="水印管理"
+                extra={
+                    <Space>
+                        <Button icon={<ReloadOutlined />} onClick={() => void loadTemplates()} />
+                        <Button
+                            danger
+                            icon={<RestOutlined />}
+                            disabled={selectedIds.length === 0 || batchDeleting}
+                            loading={batchDeleting}
+                            onClick={() => {
+                                const targets = templates.filter((item) =>
+                                    selectedIds.includes(item.id)
+                                );
+                                confirmDelete(targets);
+                            }}
+                        >
+                            批量删除
+                        </Button>
+                        <Button type="primary" icon={<PlusOutlined />} onClick={openCreate}>
+                            添加模板
+                        </Button>
+                    </Space>
+                }
+            >
+                <Space wrap style={{ marginBottom: 16 }} size={8}>
+                    <Select<KindFilter>
+                        value={kindDraft}
+                        onChange={setKindDraft}
+                        style={{ width: 130 }}
+                        options={[
+                            { value: 'all', label: '全部类型' },
+                            { value: 'text', label: '文字水印' },
+                            { value: 'image', label: '图片水印' },
+                        ]}
+                    />
+                    <Input
+                        placeholder="请输入模板名称"
+                        value={nameDraft}
+                        onChange={(event) => setNameDraft(event.target.value)}
+                        style={{ width: 180 }}
+                        allowClear
+                    />
+                    <DatePicker.RangePicker
+                        value={
+                            dateDraft
+                                ? ([dayjsOrNull(dateDraft[0]), dayjsOrNull(dateDraft[1])] as never)
+                                : null
+                        }
+                        onChange={(_, dateString) =>
+                            setDateDraft(
+                                dateString[0] && dateString[1]
+                                    ? [dateString[0], dateString[1]]
+                                    : null
+                            )
+                        }
+                    />
+                    <Button
+                        type="primary"
+                        onClick={() => {
+                            setKindFilter(kindDraft);
+                            setNameFilter(nameDraft.trim());
+                            setDateFilter(dateDraft);
+                        }}
+                    >
+                        查询
+                    </Button>
+                    <Button
+                        onClick={() => {
+                            setKindDraft('all');
+                            setNameDraft('');
+                            setDateDraft(null);
+                            setKindFilter('all');
+                            setNameFilter('');
+                            setDateFilter(null);
+                        }}
+                    >
+                        重 置
+                    </Button>
+                </Space>
+
+                <Table<WatermarkTemplate>
+                    rowKey="id"
+                    columns={columns}
+                    dataSource={filtered}
+                    loading={loading}
+                    pagination={false}
+                    rowSelection={{
+                        selectedRowKeys: selectedIds,
+                        onChange: (keys) => setSelectedIds(keys.map(String)),
+                    }}
+                    locale={{ emptyText: '暂无水印模板，点击右上角「添加模板」创建' }}
+                />
+                {nextCursor && (
+                    <div className="watermarks-load-more">
+                        <Button
+                            loading={loadingMore}
+                            onClick={() => void loadTemplates(nextCursor)}
+                        >
+                            加载更多
+                        </Button>
+                    </div>
+                )}
+            </Card>
+
+            <Modal
+                title={editing ? '编辑水印模板' : '添加水印模板'}
+                open={editorOpen}
+                onCancel={() => setEditorOpen(false)}
+                footer={null}
+                width={720}
+                destroyOnHidden
+                maskClosable={false}
+            >
+                <Form<WatermarkFormValues>
+                    form={form}
+                    layout="vertical"
+                    onValuesChange={(_, values) => setPreviewValues(values as WatermarkFormValues)}
+                    onFinish={handleSave}
+                >
+                    <Form.Item
+                        name="name"
+                        label="模板名称"
+                        required
+                        rules={[{ required: true, whitespace: true, message: '请输入模板名称' }]}
+                    >
+                        <Input maxLength={120} placeholder="例如：右下角品牌水印" />
+                    </Form.Item>
+
+                    <Form.Item label="水印类型" required>
+                        <Select
+                            value={previewValues?.kind ?? form.getFieldValue('kind') ?? 'text'}
+                            onChange={requestKindChange}
+                            options={[
+                                { value: 'text', label: '文字水印' },
+                                { value: 'image', label: '图片水印' },
+                            ]}
+                        />
+                    </Form.Item>
+
+                    <Form.Item noStyle shouldUpdate={(prev, next) => prev.kind !== next.kind}>
+                        {({ getFieldValue }) =>
+                            getFieldValue('kind') === 'image' ? (
+                                <>
+                                    <Form.Item label="上传图片" required>
+                                        <Upload
+                                            accept={WATERMARK_IMAGE_ACCEPT}
+                                            showUploadList={false}
+                                            beforeUpload={handleBeforeUpload}
+                                            disabled={uploadingImage}
+                                        >
+                                            <div className="watermark-image-box">
+                                                {imageAsset?.previewUrl ? (
+                                                    <img
+                                                        src={imageAsset.previewUrl}
+                                                        alt="水印图片"
+                                                    />
+                                                ) : (
+                                                    <FileImageOutlined
+                                                        style={{ fontSize: 28, color: '#9ca3af' }}
+                                                    />
+                                                )}
+                                                {uploadingImage && (
+                                                    <div className="watermark-image-uploading">
+                                                        <Spin size="small" />
+                                                    </div>
+                                                )}
+                                            </div>
+                                        </Upload>
+                                    </Form.Item>
+                                    <Typography.Paragraph
+                                        type="secondary"
+                                        style={{ fontSize: 12, marginTop: -8 }}
+                                    >
+                                        推荐使用透明底的 PNG 格式图片；支持 JPG、PNG、WebP，不超过
+                                        5MB
+                                    </Typography.Paragraph>
+                                    <Form.Item
+                                        name="scalePercent"
+                                        label="图片缩放"
+                                        preserve={false}
+                                    >
+                                        <Slider
+                                            min={10}
+                                            max={200}
+                                            step={1}
+                                            tooltip={{ formatter: (value) => `${value ?? 0}%` }}
+                                        />
+                                    </Form.Item>
+                                </>
+                            ) : (
+                                <>
+                                    <Form.Item
+                                        name="text_content"
+                                        label="水印文字"
+                                        required
+                                        rules={[
+                                            {
+                                                required: true,
+                                                whitespace: true,
+                                                message: '请输入水印文字',
+                                            },
+                                        ]}
+                                    >
+                                        <Input maxLength={200} placeholder="例如：Atlas Store" />
+                                    </Form.Item>
+                                    <Form.Item
+                                        name="font_code"
+                                        label="字体"
+                                        required
+                                        preserve={false}
+                                    >
+                                        <Select
+                                            placeholder="选择字体"
+                                            notFoundContent="渲染服务暂无可用字体"
+                                            options={fonts.map((font) => ({
+                                                value: font.code,
+                                                label: font.display_name,
+                                            }))}
+                                        />
+                                    </Form.Item>
+                                    <Form.Item
+                                        name="font_size_px"
+                                        label="字号（px）"
+                                        required
+                                        rules={[{ required: true, message: '请输入字号' }]}
+                                    >
+                                        <InputNumber
+                                            min={12}
+                                            max={60}
+                                            precision={0}
+                                            style={{ width: 140 }}
+                                        />
+                                    </Form.Item>
+                                </>
+                            )
+                        }
+                    </Form.Item>
+
+                    <Form.Item name="opacityPercent" label="不透明度">
+                        <Slider
+                            min={0}
+                            max={100}
+                            step={1}
+                            tooltip={{ formatter: (value) => `${value ?? 0}%` }}
+                        />
+                    </Form.Item>
+
+                    <Form.Item label="水印位置" required>
+                        <Form.Item name="position" noStyle>
+                            <PositionGrid />
+                        </Form.Item>
+                    </Form.Item>
+
+                    <Form.Item label="预览效果">
+                        <WatermarkPreview config={previewConfig} />
+                    </Form.Item>
+
+                    <div className="watermark-form-actions">
+                        <Button type="primary" htmlType="submit" loading={saving}>
+                            保 存
+                        </Button>
+                        <Button onClick={() => setEditorOpen(false)}>取 消</Button>
+                    </div>
+                </Form>
+            </Modal>
+
+            <Modal
+                title={previewing ? `查看效果：${previewing.name}` : '查看效果'}
+                open={!!previewing}
+                onCancel={() => setPreviewing(null)}
+                footer={null}
+                width={420}
+                destroyOnHidden
+            >
+                {previewing && <WatermarkPreview config={previewing.config} />}
+            </Modal>
+        </div>
+    );
+};
+
+const dayjsOrNull = (value: string) => {
+    const parsed = dayjs(value);
+    return parsed.isValid() ? parsed : null;
+};
+
+/** 3x3 水印位置九宫格选择器：选中格高亮，旁边显示位置名称 */
+const PositionGrid = ({
+    value,
+    onChange,
+}: {
+    value?: WatermarkPositionValue;
+    onChange?: (value: WatermarkPositionValue) => void;
+}) => {
+    const selected = WATERMARK_POSITION_OPTIONS.find((option) => option.value === value);
+    return (
+        <Space size={12} align="center">
+            <div className="position-grid">
+                {WATERMARK_POSITION_OPTIONS.map((option) => (
+                    <button
+                        key={option.value}
+                        type="button"
+                        className={`position-grid-cell${option.value === value ? ' active' : ''}`}
+                        aria-label={option.label}
+                        onClick={() => onChange?.(option.value)}
+                    />
+                ))}
+            </div>
+            <Typography.Text type="secondary">{positionGridLabel(selected?.label)}</Typography.Text>
+        </Space>
+    );
+};
+
+const positionGridLabel = (label?: string) => label ?? '请选择位置';
+
+export default WatermarksPage;

apps/web/src/router/index.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from 'react';
+import { Navigate, useLocation, createBrowserRouter } from 'react-router-dom';
+import MainLayout from '@/layouts/MainLayout';
+import SessionSplash from '@/components/SessionSplash';
+import CollectionPage from '@/pages/collection/CollectionPage';
+import LoginPage from '@/pages/auth/LoginPage';
+import OnlineProductsPage from '@/pages/online-products/OnlineProductsPage';
+import PasswordSettingsPage from '@/pages/settings/PasswordSettingsPage';
+import PricingPage from '@/pages/pricing/PricingPage';
+import ProductEditPage from '@/pages/products/ProductEditPage';
+import ProfileSettingsPage from '@/pages/settings/ProfileSettingsPage';
+import RegisterPage from '@/pages/auth/RegisterPage';
+import ShopsPage from '@/pages/shops/ShopsPage';
+import WatermarksPage from '@/pages/watermarks/WatermarksPage';
+import { PlatformProvider } from '@/services/platform';
+import { useSession } from '@/services/session';
+
+/** 主布局守卫：会话恢复中显示启动屏；未认证跳登录页并记住来源路径 */
+function RequireSession({ children }: { children: ReactNode }) {
+    const { status } = useSession();
+    const location = useLocation();
+
+    if (status === 'restoring') {
+        return <SessionSplash />;
+    }
+    if (status === 'anonymous') {
+        return <Navigate to="/login" replace state={{ from: location.pathname }} />;
+    }
+    return children;
+}
+
+/** 认证页互斥：已登录访问 /login、/register 时回到来源页或主布局 */
+function RedirectIfAuthenticated({ children }: { children: ReactNode }) {
+    const { status } = useSession();
+    const location = useLocation();
+
+    if (status === 'authenticated') {
+        const from = (location.state as { from?: string } | null)?.from;
+        return <Navigate to={from && from.startsWith('/') ? from : '/'} replace />;
+    }
+    return children;
+}
+
+export const router = createBrowserRouter([
+    {
+        path: '/',
+        element: (
+            <RequireSession>
+                {/* 平台上下文仅在登录后可用，随主布局挂载 */}
+                <PlatformProvider>
+                    <MainLayout />
+                </PlatformProvider>
+            </RequireSession>
+        ),
+        children: [
+            { index: true, element: <Navigate to="/online-products" replace /> },
+            { path: 'online-products', element: <OnlineProductsPage /> },
+            { path: 'collection', element: <CollectionPage /> },
+            { path: 'shops', element: <ShopsPage /> },
+            { path: 'watermarks', element: <WatermarksPage /> },
+            { path: 'pricing', element: <PricingPage /> },
+            // 商品 AI 编辑页：从采集箱/在线商品进入，不在左侧菜单中出现
+            { path: 'products/:id', element: <ProductEditPage /> },
+            // 个人中心设置页：从页头用户菜单进入，不在左侧菜单中出现
+            { path: 'settings/profile', element: <ProfileSettingsPage /> },
+            { path: 'settings/password', element: <PasswordSettingsPage /> },
+        ],
+    },
+    {
+        path: 'login',
+        element: (
+            <RedirectIfAuthenticated>
+                <LoginPage />
+            </RedirectIfAuthenticated>
+        ),
+    },
+    {
+        path: 'register',
+        element: (
+            <RedirectIfAuthenticated>
+                <RegisterPage />
+            </RedirectIfAuthenticated>
+        ),
+    },
+    { path: '*', element: <Navigate to="/" replace /> },
+]);

apps/web/src/services/api.ts

@@ -0,0 +1,164 @@
+import axios from 'axios';
+import type {
+    AxiosInstance,
+    AxiosRequestConfig,
+    AxiosResponse,
+    InternalAxiosRequestConfig,
+} from 'axios';
+import { envConfig } from '@/config/env';
+import { authToken } from '@/services/authToken';
+
+declare module 'axios' {
+    export interface AxiosRequestConfig {
+        /** 401 刷新重放标记，防止无限重试 */
+        _retried?: boolean;
+    }
+}
+
+const apiClient: AxiosInstance = axios.create({
+    baseURL: envConfig.apiBaseUrl,
+    timeout: 30000,
+    // 不设全局 Content-Type：axios 1.x 遇到「默认 JSON 头 + FormData」会把表单转成 JSON 发送，
+    // 导致素材上传等表单接口解析失败。对象请求体 axios 会自动补 JSON 头。
+});
+
+// access token 仅在内存中短暂持有（docs/api/conventions.md §1），每次请求动态附加 Bearer 头
+apiClient.interceptors.request.use((config: InternalAxiosRequestConfig) => {
+    const token = authToken.get();
+    if (token) {
+        config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+});
+
+// 认证接口自身的失败不进入刷新流程
+const AUTH_PATHS = ['/auth/login', '/auth/register', '/auth/refresh', '/auth/logout'];
+
+let refreshTask: Promise<string | null> | null = null;
+
+/** 并发 401 只触发一次刷新请求；刷新依赖 HttpOnly refresh cookie */
+function refreshAccessToken(): Promise<string | null> {
+    refreshTask ??= apiClient
+        .post('/auth/refresh')
+        .then((res) => {
+            const token = unwrapEnvelope<{ access_token: string }>(res).access_token;
+            authToken.set(token);
+            return token;
+        })
+        .catch(() => {
+            authToken.clear();
+            return null;
+        })
+        .finally(() => {
+            refreshTask = null;
+        });
+    return refreshTask;
+}
+
+apiClient.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+        if (envConfig.debug) {
+            console.error('请求失败:', error.response?.data || error.message);
+        }
+        const config = error.config as AxiosRequestConfig | undefined;
+        const url = config?.url ?? '';
+        const isAuthPath = AUTH_PATHS.some((path) => url.includes(path));
+        // access token 过期时用 refresh cookie 换新 token 并重放一次；
+        // 刷新失败说明会话已失效，整页跳转登录页（后续可换成路由内跳转并保留来源）
+        if (error.response?.status === 401 && config && !config._retried && !isAuthPath) {
+            config._retried = true;
+            const token = await refreshAccessToken();
+            if (token) {
+                return apiClient.request(config);
+            }
+            window.location.assign('/login');
+        }
+        return Promise.reject(error);
+    }
+);
+
+/**
+ * 统一解包强制响应信封：成功为 { data: T }，204 No Content 无响应体
+ * （docs/api/conventions.md §3.1）。服务层泛型 T 指业务负载本身；
+ * 列表接口使用 getList 保留分页 meta。
+ */
+function unwrapEnvelope<T>(response: AxiosResponse): T {
+    const body = response.data as { data?: unknown } | undefined;
+    if (body === null || body === undefined) {
+        return undefined as T;
+    }
+    return body.data as T;
+}
+
+/** 列表响应信封为 { data: T[], meta: PaginationMeta }（docs/api/conventions.md §3），meta 需要原样保留 */
+function unwrapListEnvelope<T, M>(response: AxiosResponse): { data: T[]; meta: M } {
+    const body = response.data as { data?: unknown; meta?: unknown } | undefined;
+    return {
+        data: Array.isArray(body?.data) ? (body.data as T[]) : [],
+        meta: (body?.meta ?? {}) as M,
+    };
+}
+
+export const api = {
+    get: <T = unknown>(url: string, config?: AxiosRequestConfig) =>
+        apiClient.get<T>(url, config).then((res) => unwrapEnvelope<T>(res)),
+
+    getList: <T = unknown, M = unknown>(url: string, config?: AxiosRequestConfig) =>
+        apiClient.get(url, config).then((res) => unwrapListEnvelope<T, M>(res)),
+
+    post: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) =>
+        apiClient.post<T>(url, data, config).then((res) => unwrapEnvelope<T>(res)),
+
+    put: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) =>
+        apiClient.put<T>(url, data, config).then((res) => unwrapEnvelope<T>(res)),
+
+    patch: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) =>
+        apiClient.patch<T>(url, data, config).then((res) => unwrapEnvelope<T>(res)),
+
+    delete: <T = unknown>(url: string, config?: AxiosRequestConfig) =>
+        apiClient.delete<T>(url, config).then((res) => unwrapEnvelope<T>(res)),
+};
+
+/** 统一错误格式为 { error: { code, message, request_id } }（docs/api/conventions.md），提取可展示信息 */
+export function apiErrorMessage(error: unknown): string {
+    if (axios.isAxiosError(error)) {
+        const data = error.response?.data as
+            { error?: { message?: unknown }; message?: unknown } | undefined;
+        if (data?.error?.message) return String(data.error.message);
+        if (data?.message) return String(data.message);
+        if (error.response) return `请求失败（HTTP ${error.response.status}）`;
+        return '网络连接失败，请稍后重试';
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+
+/** 提取业务错误码（如 VERSION_CONFLICT、DEFAULT_STORE_REPLACEMENT_REQUIRED），无则返回 null */
+export function apiErrorCode(error: unknown): string | null {
+    if (!axios.isAxiosError(error)) return null;
+    const code = (error.response?.data as { error?: { code?: unknown } } | undefined)?.error?.code;
+    return typeof code === 'string' ? code : null;
+}
+
+export interface ApiErrorDetail {
+    field: string;
+    code: string;
+    message: string;
+}
+
+/** 提取错误信封中的字段级明细 details: [{ field, code, message }]（docs/api/conventions.md §4） */
+export function apiErrorDetails(error: unknown): ApiErrorDetail[] {
+    if (!axios.isAxiosError(error)) return [];
+    const details = (error.response?.data as { error?: { details?: unknown } } | undefined)?.error
+        ?.details;
+    if (!Array.isArray(details)) return [];
+    return details.filter(
+        (item): item is ApiErrorDetail =>
+            !!item &&
+            typeof item === 'object' &&
+            typeof (item as ApiErrorDetail).field === 'string' &&
+            typeof (item as ApiErrorDetail).message === 'string'
+    );
+}
+
+export default apiClient;

apps/web/src/services/auth.ts

@@ -0,0 +1,48 @@
+import type {
+    AuthMeResponse,
+    AuthRefreshResponse,
+    AuthSessionResponse,
+    AuthUser,
+    ChangePasswordRequest,
+    LoginRequest,
+    RegisterRequest,
+    UpdateCurrentUserRequest,
+} from '@atlas/contracts';
+import { api } from '@/services/api';
+
+export interface UpdateProfileOptions {
+    /** 提交时的乐观锁版本，取自当前会话 user.revision */
+    revision: number;
+    /** 幂等键，重试安全；成功响应携带新 revision */
+    idempotencyKey: string;
+}
+
+/** 账户与会话接口，契约见 docs/api/auth.md；类型全部来自 @atlas/contracts */
+export const authApi = {
+    register: (payload: RegisterRequest) =>
+        api.post<AuthSessionResponse>('/auth/register', payload),
+
+    login: (payload: LoginRequest) => api.post<AuthSessionResponse>('/auth/login', payload),
+
+    refresh: () => api.post<AuthRefreshResponse>('/auth/refresh'),
+
+    logout: () => api.post<void>('/auth/logout'),
+
+    me: () => api.get<AuthMeResponse>('/auth/me'),
+
+    /**
+     * 修改资料：If-Match 乐观锁 + Idempotency-Key 幂等（docs/api/conventions.md §5）。
+     * 版本过期返回 409 VERSION_CONFLICT（details.current_revision 为服务端当前版本）。
+     */
+    updateProfile: (payload: UpdateCurrentUserRequest, options: UpdateProfileOptions) =>
+        api.patch<AuthUser>('/auth/me', payload, {
+            headers: {
+                'If-Match': `"${options.revision}"`,
+                'Idempotency-Key': options.idempotencyKey,
+            },
+        }),
+
+    /** 修改密码：成功后所有旧 session 失效；响应携带新 access token，必须立即替换内存值 */
+    changePassword: (payload: ChangePasswordRequest) =>
+        api.post<AuthRefreshResponse>('/auth/change-password', payload),
+};

apps/web/src/services/authToken.ts

@@ -0,0 +1,16 @@
+/**
+ * access token 仅在内存中短暂持有（docs/api/conventions.md §1），
+ * 不得写入 localStorage 等持久化存储；页面刷新后由 /auth/refresh 通过
+ * HttpOnly cookie 恢复会话（接入会话恢复逻辑时实现）。
+ */
+let accessToken: string | null = null;
+
+export const authToken = {
+    get: () => accessToken,
+    set: (token: string) => {
+        accessToken = token;
+    },
+    clear: () => {
+        accessToken = null;
+    },
+};

apps/web/src/services/collection.ts

@@ -0,0 +1,9 @@
+import type { CollectionItem, CreateCollectionItemRequest, CursorPaginationMeta, ListCollectionItemsQuery, UpdateCollectionItemRequest } from '@atlas/contracts';
+import { api } from './api';
+export const collectionApi = {
+  list: (platformId: string, query: Partial<ListCollectionItemsQuery> = {}) => api.getList<CollectionItem, CursorPaginationMeta & { active_count: number; collection_limit: number }>('/collection-items', { headers: { 'X-Atlas-Platform-Id': platformId }, params: { limit: 20, ...query } }),
+  create: (payload: CreateCollectionItemRequest) => api.post<{ collection_item: CollectionItem; product_id: string; editor_entry_path: string }>('/collection-items', payload, { headers: { 'Idempotency-Key': crypto.randomUUID() } }),
+  update: (id: string, payload: UpdateCollectionItemRequest, revision: number) => api.patch<CollectionItem>(`/collection-items/${id}`, payload, { headers: { 'Idempotency-Key': crypto.randomUUID(), 'If-Match': `"${revision}"` } }),
+  bulkDelete: (ids: string[]) => api.post<{ deleted_count: number }>('/collection-items/bulk-delete', { ids }, { headers: { 'Idempotency-Key': crypto.randomUUID() } }),
+  clear: (expected_active_count: number) => api.post<{ deleted_count: number }>('/collection-items/clear', { confirm: true, expected_active_count }, { headers: { 'Idempotency-Key': crypto.randomUUID() } }),
+};

apps/web/src/services/media.ts

@@ -0,0 +1,71 @@
+import type {
+    CreateMediaUploadIntentRequest,
+    MediaAccessUrl,
+    MediaAsset,
+    MediaUploadIntent,
+} from '@atlas/contracts';
+import { api } from '@/services/api';
+
+/** 水印图片的用途与限制（docs/api/watermarks-and-assets.md §1） */
+export const WATERMARK_IMAGE_ACCEPT = '.jpg,.jpeg,.png,.webp';
+export const WATERMARK_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+
+/** 异步操作查询，契约见 docs/api/conventions.md §5（GET /api/operations/{operation_id}） */
+export const mediaApi = {
+    createUploadIntent: (payload: CreateMediaUploadIntentRequest) =>
+        api.post<MediaUploadIntent>('/media/upload-intents', payload, {
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        }),
+
+    completeUpload: (uploadId: string, checksumSha256: string) =>
+        api.post<{ asset: MediaAsset }>(
+            `/media/upload-intents/${uploadId}/complete`,
+            { checksum_sha256: checksumSha256 },
+            { headers: { 'Idempotency-Key': crypto.randomUUID() } }
+        ),
+
+    /** 短时预览 URL：过期后重新请求，不能写回业务表或长期缓存 */
+    createPreviewUrl: (assetId: string) =>
+        api.post<MediaAccessUrl>(
+            `/media-assets/${assetId}/access-urls`,
+            { purpose: 'preview' },
+            { headers: { 'Idempotency-Key': crypto.randomUUID() } }
+        ),
+};
+
+/** 浏览器端计算文件的 SHA-256 十六进制摘要（complete 校验用） */
+export async function sha256Hex(file: File): Promise<string> {
+    const digest = await crypto.subtle.digest('SHA-256', await file.arrayBuffer());
+    return Array.from(new Uint8Array(digest))
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+
+/**
+ * 图片水印素材三步直传（docs/api/watermarks-and-assets.md §1）：
+ * 创建上传意图 → 按返回的 method/url/headers 原样 PUT 到对象存储 → 完成校验换取素材。
+ * 返回已通过校验的素材，可直接用于图片水印模板的 image_asset_id。
+ */
+export async function uploadWatermarkImage(file: File): Promise<MediaAsset> {
+    const checksumSha256 = await sha256Hex(file);
+    const intent = await mediaApi.createUploadIntent({
+        purpose: 'watermark_image',
+        filename: file.name,
+        content_type: file.type as CreateMediaUploadIntentRequest['content_type'],
+        byte_size: file.size,
+        checksum_sha256: checksumSha256,
+    });
+
+    // 必须以服务端返回的 method、URL 与 headers 原样上传，不能自行拼接对象路径
+    const putResponse = await fetch(intent.upload.url, {
+        method: intent.upload.method,
+        headers: intent.upload.headers,
+        body: file,
+    });
+    if (!putResponse.ok) {
+        throw new Error(`图片上传到对象存储失败（HTTP ${putResponse.status}）`);
+    }
+
+    const completed = await mediaApi.completeUpload(intent.upload_id, checksumSha256);
+    return completed.asset;
+}

apps/web/src/services/operations.ts

@@ -0,0 +1,10 @@
+import type { Operation } from '@atlas/contracts';
+import { api } from '@/services/api';
+
+/** operation 的终态集合；页面最终状态以刷新后的店铺资源为准，不以 operation 为准 */
+export const OPERATION_TERMINAL_STATUSES = new Set(['succeeded', 'failed', 'cancelled']);
+
+/** 异步操作查询，契约见 docs/api/conventions.md §5（GET /api/operations/{operation_id}） */
+export const operationsApi = {
+    get: (operationId: string) => api.get<Operation>(`/operations/${operationId}`),
+};

apps/web/src/services/platform.tsx

@@ -0,0 +1,143 @@
+import {
+    createContext,
+    useCallback,
+    useContext,
+    useEffect,
+    useMemo,
+    useRef,
+    useState,
+} from 'react';
+import type { ReactNode } from 'react';
+import type { Platform, PlatformContext } from '@atlas/contracts';
+import { api, apiErrorMessage } from '@/services/api';
+
+/** 平台选择的本地记忆键：仅保存平台 id 这一非敏感 UI 偏好 */
+const PLATFORM_STORAGE_KEY = 'atlas.platform_id';
+
+interface PlatformContextValue {
+    /** 已启用的平台目录；加载失败时为空数组并置 error */
+    platforms: Platform[];
+    /** 页头当前选中的平台；目录未加载完成或为空时为 null */
+    currentPlatform: Platform | null;
+    /** 目录加载失败信息；非空时提供重试入口 */
+    error: string | null;
+    /** 当前平台的默认门店上下文（GET /api/platform-context） */
+    context: PlatformContext | null;
+    contextLoading: boolean;
+    selectPlatform: (platformId: string) => void;
+    /** 门店变更后刷新默认门店摘要 */
+    refreshContext: () => Promise<void>;
+    /** 目录加载失败后重试 */
+    reload: () => void;
+}
+
+const PlatformContextContext = createContext<PlatformContextValue | null>(null);
+
+/** 平台上下文：页头平台选择器的数据源，门店等模块据此确定当前平台（目录接口将 Ozon 排在最前） */
+export function PlatformProvider({ children }: { children: ReactNode }) {
+    const [platforms, setPlatforms] = useState<Platform[]>([]);
+    const [selectedId, setSelectedId] = useState<string | null>(() =>
+        localStorage.getItem(PLATFORM_STORAGE_KEY)
+    );
+    const [error, setError] = useState<string | null>(null);
+    const [context, setContext] = useState<PlatformContext | null>(null);
+    const [contextLoading, setContextLoading] = useState(false);
+    // 快速切换平台时丢弃过期响应与 loading：只接受最后一次请求的结果
+    const contextRequestIdRef = useRef(0);
+
+    const loadPlatforms = useCallback(async () => {
+        setError(null);
+        try {
+            const list = await api.get<Platform[]>('/platforms');
+            setPlatforms(list);
+            // 已保存的选择失效（平台下线或首次使用）时回退到目录第一家（Ozon 优先）
+            setSelectedId((prev) =>
+                prev && list.some((item) => item.id === prev) ? prev : (list[0]?.id ?? null)
+            );
+        } catch (err) {
+            setError(apiErrorMessage(err));
+        }
+    }, []);
+
+    useEffect(() => {
+        void loadPlatforms();
+    }, [loadPlatforms]);
+
+    const currentPlatform = useMemo(
+        () => platforms.find((item) => item.id === selectedId) ?? null,
+        [platforms, selectedId]
+    );
+
+    const loadContext = useCallback(async (platformId: string) => {
+        const requestId = ++contextRequestIdRef.current;
+        setContextLoading(true);
+        try {
+            const next = await api.get<PlatformContext>('/platform-context', {
+                headers: { 'X-Atlas-Platform-Id': platformId },
+            });
+            if (contextRequestIdRef.current !== requestId) return;
+            setContext(next);
+        } catch {
+            // 上下文读取失败不阻塞页面：门店页等业务接口自会报错
+            if (contextRequestIdRef.current !== requestId) return;
+            setContext(null);
+        } finally {
+            if (contextRequestIdRef.current === requestId) {
+                setContextLoading(false);
+            }
+        }
+    }, []);
+
+    useEffect(() => {
+        if (!currentPlatform) {
+            setContext(null);
+            return;
+        }
+        void loadContext(currentPlatform.id);
+    }, [currentPlatform, loadContext]);
+
+    const selectPlatform = useCallback((platformId: string) => {
+        setSelectedId(platformId);
+        localStorage.setItem(PLATFORM_STORAGE_KEY, platformId);
+    }, []);
+
+    const refreshContext = useCallback(async () => {
+        if (!currentPlatform) return;
+        await loadContext(currentPlatform.id);
+    }, [currentPlatform, loadContext]);
+
+    const value = useMemo(
+        () => ({
+            platforms,
+            currentPlatform,
+            error,
+            context,
+            contextLoading,
+            selectPlatform,
+            refreshContext,
+            reload: () => void loadPlatforms(),
+        }),
+        [
+            platforms,
+            currentPlatform,
+            error,
+            context,
+            contextLoading,
+            selectPlatform,
+            refreshContext,
+            loadPlatforms,
+        ]
+    );
+
+    return (
+        <PlatformContextContext.Provider value={value}>{children}</PlatformContextContext.Provider>
+    );
+}
+
+export function usePlatform(): PlatformContextValue {
+    const context = useContext(PlatformContextContext);
+    if (!context) {
+        throw new Error('usePlatform 必须在 PlatformProvider 内使用');
+    }
+    return context;
+}

apps/web/src/services/session.tsx

@@ -0,0 +1,116 @@
+import {
+    createContext,
+    useCallback,
+    useContext,
+    useEffect,
+    useMemo,
+    useRef,
+    useState,
+} from 'react';
+import type { ReactNode } from 'react';
+import axios from 'axios';
+import type { AuthMeResponse, AuthSessionResponse } from '@atlas/contracts';
+import { authApi } from '@/services/auth';
+import { authToken } from '@/services/authToken';
+
+export type SessionStatus = 'restoring' | 'authenticated' | 'anonymous';
+
+export interface SessionState {
+    user: AuthMeResponse['user'];
+    workspace: AuthMeResponse['workspace'];
+}
+
+interface SessionContextValue {
+    status: SessionStatus;
+    session: SessionState | null;
+    /** 登录 / 注册成功后写入会话 */
+    applyAuthSession: (payload: AuthSessionResponse) => void;
+    /** 修改资料成功后更新本地会话中的用户信息 */
+    applyProfileUpdate: (user: SessionState['user']) => void;
+    /** 撤销服务端会话并清除本地状态；网络失败也保证本地登出 */
+    logout: () => Promise<void>;
+}
+
+const SessionContext = createContext<SessionContextValue | null>(null);
+
+// 模块级去重：StrictMode 双挂载或并发恢复时只发一次 refresh（refresh 会轮换会话，重复调用会互相失效）
+let restoreTask: Promise<void> | null = null;
+
+/** 会话上下文：应用启动时经 HttpOnly refresh cookie 恢复会话，登录/注册/登出统一在此维护状态 */
+export function SessionProvider({ children }: { children: ReactNode }) {
+    const [status, setStatus] = useState<SessionStatus>('restoring');
+    const [session, setSession] = useState<SessionState | null>(null);
+    const mountedRef = useRef(true);
+
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+
+    useEffect(() => {
+        restoreTask ??= (async () => {
+            try {
+                const refreshed = await authApi.refresh();
+                authToken.set(refreshed.access_token);
+                const me = await authApi.me();
+                if (!mountedRef.current) return;
+                setSession({ user: me.user, workspace: me.workspace });
+                setStatus('authenticated');
+            } catch {
+                if (!mountedRef.current) return;
+                authToken.clear();
+                setStatus('anonymous');
+            } finally {
+                restoreTask = null;
+            }
+        })();
+        void restoreTask;
+    }, []);
+
+    const applyAuthSession = useCallback((payload: AuthSessionResponse) => {
+        authToken.set(payload.access_token);
+        setSession({ user: payload.user, workspace: payload.workspace });
+        setStatus('authenticated');
+    }, []);
+
+    const applyProfileUpdate = useCallback((user: SessionState['user']) => {
+        setSession((prev) => (prev ? { ...prev, user } : prev));
+    }, []);
+
+    const logout = useCallback(async () => {
+        try {
+            await authApi.logout();
+        } catch (error) {
+            // access token 已过期时先刷新一次再重试，确保服务端会话被撤销；
+            // 仍失败则仅做本地登出，等待服务端会话自然过期
+            if (axios.isAxiosError(error) && error.response?.status === 401) {
+                const refreshed = await authApi.refresh().catch(() => null);
+                if (refreshed) {
+                    authToken.set(refreshed.access_token);
+                    await authApi.logout().catch(() => undefined);
+                }
+            }
+        } finally {
+            authToken.clear();
+            setSession(null);
+            setStatus('anonymous');
+        }
+    }, []);
+
+    const value = useMemo(
+        () => ({ status, session, applyAuthSession, applyProfileUpdate, logout }),
+        [status, session, applyAuthSession, applyProfileUpdate, logout]
+    );
+
+    return <SessionContext.Provider value={value}>{children}</SessionContext.Provider>;
+}
+
+export function useSession(): SessionContextValue {
+    const context = useContext(SessionContext);
+    if (!context) {
+        throw new Error('useSession 必须在 SessionProvider 内使用');
+    }
+    return context;
+}

apps/web/src/services/stores.ts

@@ -0,0 +1,83 @@
+import type {
+    CreateStoreRequest,
+    CursorPaginationMeta,
+    Store,
+    StoreOperationResponse,
+    UpdateStoreRequest,
+} from '@atlas/contracts';
+import { api } from '@/services/api';
+
+export interface StoreListResult {
+    data: Store[];
+    meta: CursorPaginationMeta;
+}
+
+export interface UpdateStoreOptions {
+    /** 提交时的乐观锁版本，取自门店资源 revision */
+    revision: number;
+}
+
+/**
+ * 门店管理接口，契约见 docs/api/stores-and-platforms.md。
+ * 列表必须用 platform_id 查询参数（管理列表禁止携带 X-Atlas-Platform-Id header）。
+ */
+export const storesApi = {
+    list: (platformId: string, cursor?: string) =>
+        api.getList<Store, CursorPaginationMeta>('/stores', {
+            params: { platform_id: platformId, limit: 20, ...(cursor ? { cursor } : {}) },
+        }),
+
+    get: (storeId: string) => api.get<Store>(`/stores/${storeId}`),
+
+    /** 创建后店铺处于 verifying 状态，凭据验证由后台异步执行 */
+    create: (payload: CreateStoreRequest) =>
+        api.post<StoreOperationResponse>('/stores', payload, {
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        }),
+
+    /**
+     * 编辑：If-Match 乐观锁。未传 api_key 返回更新后的店铺；
+     * 传入新 api_key 返回 202 与验证 operation（响应仍是 { store, operation }）。
+     */
+    update: (storeId: string, payload: UpdateStoreRequest, options: UpdateStoreOptions) =>
+        api.patch<Store | StoreOperationResponse>(`/stores/${storeId}`, payload, {
+            headers: {
+                'If-Match': `"${options.revision}"`,
+                'Idempotency-Key': crypto.randomUUID(),
+            },
+        }),
+
+    setDefault: (storeId: string) =>
+        api.post<Store>(`/stores/${storeId}/set-default`, undefined, {
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        }),
+
+    requestCredentialVerification: (storeId: string) =>
+        api.post<StoreOperationResponse>(`/stores/${storeId}/credential-verifications`, undefined, {
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        }),
+
+    requestWarehouseSync: (storeId: string) =>
+        api.post<StoreOperationResponse>(`/stores/${storeId}/warehouse-syncs`, undefined, {
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        }),
+
+    /** 删除当前默认店铺时同平台还有其他店铺会返回 422 DEFAULT_STORE_REPLACEMENT_REQUIRED */
+    remove: (storeId: string) =>
+        api.delete<void>(`/stores/${storeId}`, {
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        }),
+
+    /**
+     * 绑定水印模板，契约见 docs/api/stores-and-platforms.md（PUT /api/stores/{id}/watermark-binding）。
+     * 传 null 表示「暂不绑定」；模板必须是当前工作空间的活动模板，返回店铺水印摘要。
+     */
+    bindWatermark: (storeId: string, templateId: string | null) =>
+        api.put<Store>(
+            `/stores/${storeId}/watermark-binding`,
+            { template_id: templateId },
+            {
+                headers: { 'Idempotency-Key': crypto.randomUUID() },
+            }
+        ),
+};

apps/web/src/services/watermarks.ts

@@ -0,0 +1,58 @@
+import type {
+    CreateWatermarkTemplateRequest,
+    UpdateWatermarkTemplateRequest,
+    WatermarkFont,
+    WatermarkTemplate,
+} from '@atlas/contracts';
+import { api } from '@/services/api';
+import type { CursorPaginationMeta } from '@atlas/contracts';
+
+export interface WatermarkListResult {
+    data: WatermarkTemplate[];
+    meta: CursorPaginationMeta;
+}
+
+export interface UpdateWatermarkOptions {
+    /** 提交时的乐观锁版本，取自模板 revision */
+    revision: number;
+}
+
+/**
+ * 水印模板接口，契约见 docs/api/watermarks-and-assets.md §2/§3。
+ * 列表/详情的图片模板携带短时 preview_url，过期后重新读取即可。
+ */
+export const watermarksApi = {
+    /** 渲染服务已部署的可用字体；字体 code 是模板的稳定保存值 */
+    fonts: () => api.get<WatermarkFont[]>('/watermark-fonts'),
+
+    list: (cursor?: string) =>
+        api.getList<WatermarkTemplate, CursorPaginationMeta>('/watermark-templates', {
+            params: { limit: 100, ...(cursor ? { cursor } : {}) },
+        }),
+
+    get: (templateId: string) => api.get<WatermarkTemplate>(`/watermark-templates/${templateId}`),
+
+    create: (payload: CreateWatermarkTemplateRequest) =>
+        api.post<WatermarkTemplate>('/watermark-templates', payload, {
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        }),
+
+    /** 渲染参数变更由服务端创建不可变版本并递增 current_version；仅改名不创建版本 */
+    update: (
+        templateId: string,
+        payload: UpdateWatermarkTemplateRequest,
+        options: UpdateWatermarkOptions
+    ) =>
+        api.patch<WatermarkTemplate>(`/watermark-templates/${templateId}`, payload, {
+            headers: {
+                'If-Match': `"${options.revision}"`,
+                'Idempotency-Key': crypto.randomUUID(),
+            },
+        }),
+
+    /** 软删除并解除所有店铺绑定，返回 204 */
+    remove: (templateId: string) =>
+        api.delete<void>(`/watermark-templates/${templateId}`, {
+            headers: { 'Idempotency-Key': crypto.randomUUID() },
+        }),
+};