From 388429dbd070525795750a2664431242cb9f8d57 Mon Sep 17 00:00:00 2001 From: R524809 Date: Fri, 18 Sep 2026 18:55:16 +0800 Subject: [PATCH] =?UTF-8?q?feat(category):=20=E7=B1=BB=E7=9B=AE=E6=A0=91?= =?UTF-8?q?=E3=80=81=E5=B1=9E=E6=80=A7=E3=80=81=E5=B1=9E=E6=80=A7=E5=AD=97?= =?UTF-8?q?=E5=85=B8=E7=BB=B4=E6=8A=A4=EF=BC=8C=E6=96=B0=E5=A2=9E=E7=B3=BB?= =?UTF-8?q?=E7=BB=9F=E7=AE=A1=E7=90=86=E5=91=98=E7=AE=A1=E7=90=86=E7=B1=BB?= =?UTF-8?q?=E7=9B=AE=E6=95=B0=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/api/src/app.module.ts | 2 + .../platform-catalog-admin.commands.ts | 219 ++++++++ .../platform-catalog-admin.controller.ts | 132 +++++ .../platform-catalog-admin.models.ts | 34 ++ .../platform-catalog-admin.module.ts | 13 + .../platform-catalog-admin.reads.ts | 158 ++++++ .../system-admin.guard.ts | 28 + .../product-editor.attribute-bindings.ts | 33 ++ .../product-editor.catalog-operations.ts | 43 +- .../product-editor.controller.ts | 18 + .../product-editor/product-editor.models.ts | 3 +- .../product-editor/product-editor.service.ts | 69 ++- .../product-editor.validation.ts | 320 ++++++++++++ .../test/platform-catalog-admin.unit.test.ts | 49 ++ apps/api/test/product-editor.e2e.test.ts | 493 ++++++++++++++---- apps/web/src/layouts/MainLayout.tsx | 8 + apps/web/src/layouts/SystemAdminLayout.css | 47 ++ apps/web/src/layouts/SystemAdminLayout.tsx | 52 ++ .../src/pages/products/ProductEditPage.css | 12 +- .../src/pages/products/ProductEditPage.tsx | 181 +++++-- .../components/DynamicAttributeFields.tsx | 230 ++++++++ .../components/ProductAttributeSection.css | 27 +- .../components/ProductAttributeSection.tsx | 389 ++++---------- .../components/ProductMainInfoSection.tsx | 6 +- .../components/ProductVariantSection.css | 29 ++ .../components/ProductVariantSection.tsx | 237 ++++++--- .../src/pages/system/SystemCatalogPage.css | 32 ++ .../src/pages/system/SystemCatalogPage.tsx | 272 ++++++++++ .../system/components/CatalogSourceModal.tsx | 55 ++ .../components/DictionaryValuesDrawer.tsx | 107 ++++ .../components/PlatformAttributesTable.tsx | 58 +++ .../components/PlatformCategoryTree.tsx | 83 +++ apps/web/src/router/index.tsx | 10 + apps/web/src/services/platformCatalogAdmin.ts | 68 +++ apps/web/src/services/productEditor.ts | 31 +- apps/web/src/services/useSystemAdminAccess.ts | 23 + apps/worker/src/main.ts | 42 +- apps/worker/src/ozon-client.ts | 83 ++- .../worker/src/platform-catalog-dispatcher.ts | 68 +++ apps/worker/src/platform-catalog-mappers.ts | 107 ++++ apps/worker/src/platform-catalog-scheduler.ts | 103 ++++ apps/worker/src/platform-catalog-sync.ts | 337 ++++++++++++ apps/worker/test/ozon-client.test.mjs | 95 ++++ .../test/platform-catalog-mappers.test.mjs | 53 ++ docs/README.md | 1 + docs/api/README.md | 3 +- docs/api/platform-catalog-admin.md | 56 ++ docs/api/product-editor-and-publishing.md | 51 +- docs/api/stores-and-platforms.md | 2 + .../platform-product-reference-catalog.md | 46 ++ .../architecture/product-domain-data-model.md | 2 + .../ozon-seller-api/02-category-tree.md | 44 +- .../ozon-seller-api/03-category-attributes.md | 47 +- ...on-dynamic-attributes-and-sku-form-plan.md | 12 +- docs/product/product-ai-editor.md | 2 +- docs/project/HANDOFF.md | 106 +++- packages/contracts/src/product-editor.ts | 30 ++ .../024_platform_catalog_management.sql | 126 +++++ 58 files changed, 4347 insertions(+), 640 deletions(-) create mode 100644 apps/api/src/platform-catalog-admin/platform-catalog-admin.commands.ts create mode 100644 apps/api/src/platform-catalog-admin/platform-catalog-admin.controller.ts create mode 100644 apps/api/src/platform-catalog-admin/platform-catalog-admin.models.ts create mode 100644 apps/api/src/platform-catalog-admin/platform-catalog-admin.module.ts create mode 100644 apps/api/src/platform-catalog-admin/platform-catalog-admin.reads.ts create mode 100644 apps/api/src/platform-catalog-admin/system-admin.guard.ts create mode 100644 apps/api/src/product-editor/product-editor.attribute-bindings.ts create mode 100644 apps/api/src/product-editor/product-editor.validation.ts create mode 100644 apps/api/test/platform-catalog-admin.unit.test.ts create mode 100644 apps/web/src/layouts/SystemAdminLayout.css create mode 100644 apps/web/src/layouts/SystemAdminLayout.tsx create mode 100644 apps/web/src/pages/products/components/DynamicAttributeFields.tsx create mode 100644 apps/web/src/pages/system/SystemCatalogPage.css create mode 100644 apps/web/src/pages/system/SystemCatalogPage.tsx create mode 100644 apps/web/src/pages/system/components/CatalogSourceModal.tsx create mode 100644 apps/web/src/pages/system/components/DictionaryValuesDrawer.tsx create mode 100644 apps/web/src/pages/system/components/PlatformAttributesTable.tsx create mode 100644 apps/web/src/pages/system/components/PlatformCategoryTree.tsx create mode 100644 apps/web/src/services/platformCatalogAdmin.ts create mode 100644 apps/web/src/services/useSystemAdminAccess.ts create mode 100644 apps/worker/src/platform-catalog-dispatcher.ts create mode 100644 apps/worker/src/platform-catalog-mappers.ts create mode 100644 apps/worker/src/platform-catalog-scheduler.ts create mode 100644 apps/worker/src/platform-catalog-sync.ts create mode 100644 apps/worker/test/ozon-client.test.mjs create mode 100644 apps/worker/test/platform-catalog-mappers.test.mjs create mode 100644 docs/api/platform-catalog-admin.md create mode 100644 docs/architecture/platform-product-reference-catalog.md create mode 100644 packages/database/migrations/024_platform_catalog_management.sql diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts index 530a0e7..15ed03f 100644 --- a/apps/api/src/app.module.ts +++ b/apps/api/src/app.module.ts @@ -12,6 +12,7 @@ import { MediaModule } from './media/media.module.js'; import { CollectionModule } from './collection/collection.module.js'; import { ExtensionModule } from './extension/extension.module.js'; import { ProductEditorModule } from './product-editor/product-editor.module.js'; +import { PlatformCatalogAdminModule } from './platform-catalog-admin/platform-catalog-admin.module.js'; @Controller() class HealthController { @@ -51,6 +52,7 @@ class HealthController { CollectionModule, ExtensionModule, ProductEditorModule, + PlatformCatalogAdminModule, ], controllers: [HealthController], }) diff --git a/apps/api/src/platform-catalog-admin/platform-catalog-admin.commands.ts b/apps/api/src/platform-catalog-admin/platform-catalog-admin.commands.ts new file mode 100644 index 0000000..60dcc2b --- /dev/null +++ b/apps/api/src/platform-catalog-admin/platform-catalog-admin.commands.ts @@ -0,0 +1,219 @@ +import { Inject, Injectable } from '@nestjs/common'; +import type { Database, DatabaseTransaction } from '@atlas/database'; +import { ApiError } from '../common/api-error.js'; +import { APP_CONFIG, type AppConfig } from '../config/app-config.module.js'; +import { DATABASE } from '../database/database.module.js'; +import { encryptStoreSecret } from '../stores/store-secret.crypto.js'; +import type { SourceInput, SyncInput } from './platform-catalog-admin.models.js'; + +type RunRow = { + id: string; + platform_id: string; + scope: string; + scope_key: string; + status: string; + trigger_kind: string; + created_at: Date; +}; + +@Injectable() +export class PlatformCatalogAdminCommands { + public constructor( + @Inject(DATABASE) private readonly database: Database, + @Inject(APP_CONFIG) private readonly config: AppConfig, + ) {} + + public async configureSource(platformId: string, userId: string, input: SourceInput) { + const encrypted = encryptStoreSecret(input.api_key, this.config.STORE_SECRET_ENCRYPTION_KEY); + return this.database.transaction(async (tx) => { + const platform = await tx.query<{ code: string }>( + 'SELECT code FROM atlas.platforms WHERE id = $1 FOR UPDATE', + [platformId], + ); + if (!platform.rows[0]) throw new ApiError(404, 'PLATFORM_NOT_FOUND', '平台不存在'); + if (platform.rows[0].code.toUpperCase() !== 'OZON') { + throw new ApiError(422, 'PLATFORM_CATALOG_UNSUPPORTED', '该平台尚未接入目录同步'); + } + const existing = await tx.query<{ + client_id: string; secret_fingerprint: string; revision: number; + }>( + `SELECT client_id, secret_fingerprint, revision + FROM atlas.platform_catalog_sources WHERE platform_id = $1 FOR UPDATE`, + [platformId], + ); + const unchanged = existing.rows[0]?.client_id === input.client_id && + existing.rows[0]?.secret_fingerprint === encrypted.fingerprint; + const revision = unchanged ? existing.rows[0].revision : (existing.rows[0]?.revision ?? 0) + 1; + if (!unchanged) { + await tx.query( + `INSERT INTO atlas.platform_catalog_sources + (platform_id, client_id, secret_ciphertext, secret_nonce, + secret_fingerprint, encryption_key_version, revision, updated_by_user_id) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8) + ON CONFLICT (platform_id) DO UPDATE + SET client_id = EXCLUDED.client_id, + secret_ciphertext = EXCLUDED.secret_ciphertext, + secret_nonce = EXCLUDED.secret_nonce, + secret_fingerprint = EXCLUDED.secret_fingerprint, + encryption_key_version = EXCLUDED.encryption_key_version, + revision = EXCLUDED.revision, + updated_by_user_id = EXCLUDED.updated_by_user_id, + updated_at = now()`, + [platformId, input.client_id, encrypted.ciphertext, encrypted.nonce, + encrypted.fingerprint, this.config.STORE_SECRET_ENCRYPTION_KEY_VERSION, + revision, userId], + ); + // 旧来源的任务即使已进队列，也不能拿新凭据执行。 + await tx.query( + `UPDATE atlas.platform_catalog_sync_runs + SET status = 'cancelled', completed_at = now(), + error_code = 'CATALOG_SOURCE_REPLACED', error_message = '同步来源已更新' + WHERE platform_id = $1 AND status IN ('queued', 'running')`, + [platformId], + ); + await enqueueRun(tx, { + platformId, scope: 'tree', scopeKey: 'tree', sourceRevision: revision, + trigger: 'source_configured', userId, + }); + } + return { + configured: true, + client_id_hint: `••••${input.client_id.slice(-4)}`, + revision, + changed: !unchanged, + }; + }); + } + + public async sync(platformId: string, userId: string, idempotencyKey: string, input: SyncInput) { + return this.database.transaction(async (tx) => { + const platform = await tx.query<{ code: string }>( + 'SELECT code FROM atlas.platforms WHERE id = $1 FOR UPDATE', + [platformId], + ); + if (!platform.rows[0]) throw new ApiError(404, 'PLATFORM_NOT_FOUND', '平台不存在'); + if (platform.rows[0].code.toUpperCase() !== 'OZON') { + throw new ApiError(422, 'PLATFORM_CATALOG_UNSUPPORTED', '该平台尚未接入目录同步'); + } + const source = await tx.query<{ revision: number }>( + 'SELECT revision FROM atlas.platform_catalog_sources WHERE platform_id = $1 FOR UPDATE', + [platformId], + ); + if (!source.rows[0]) { + throw new ApiError(422, 'CATALOG_SOURCE_REQUIRED', '请先配置平台目录同步来源'); + } + const target = await this.resolveTarget(tx, platformId, input); + const prior = await tx.query( + `SELECT run.id, run.platform_id, run.scope, run.scope_key, run.status, + run.trigger_kind, run.created_at + FROM atlas.platform_catalog_sync_requests request + JOIN atlas.platform_catalog_sync_runs run ON run.id = request.run_id + WHERE request.requested_by_user_id = $1 AND request.idempotency_key = $2`, + [userId, idempotencyKey], + ); + if (prior.rows[0]) { + if (prior.rows[0].platform_id !== platformId || prior.rows[0].scope_key !== target.scopeKey) { + throw new ApiError(409, 'IDEMPOTENCY_KEY_REUSED', '幂等键已用于其他同步请求'); + } + return presentRun(prior.rows[0]); + } + const run = await enqueueRun(tx, { + platformId, + scope: input.scope, + scopeKey: target.scopeKey, + categoryId: target.categoryId, + attributeId: target.attributeId, + sourceRevision: source.rows[0].revision, + trigger: 'manual', + userId, + idempotencyKey, + }); + await tx.query( + `INSERT INTO atlas.platform_catalog_sync_requests + (requested_by_user_id, idempotency_key, platform_id, scope_key, run_id) + VALUES ($1, $2, $3, $4, $5)`, + [userId, idempotencyKey, platformId, target.scopeKey, run.id], + ); + return presentRun(run); + }); + } + + private async resolveTarget(tx: DatabaseTransaction, platformId: string, input: SyncInput) { + if (input.scope === 'tree') return { scopeKey: 'tree' }; + if (input.scope === 'attributes') { + const category = await tx.query<{ id: string }>( + `SELECT id FROM atlas.platform_product_categories + WHERE id = $1 AND platform_id = $2 AND is_active + AND external_type_id IS NOT NULL AND external_type_id <> '0'`, + [input.category_id, platformId], + ); + if (!category.rows[0]) throw new ApiError(404, 'CATEGORY_NOT_FOUND', '商品类型不存在'); + return { scopeKey: `attributes:${input.category_id}`, categoryId: input.category_id }; + } + const attribute = await tx.query<{ platform_product_category_id: string }>( + `SELECT platform_product_category_id + FROM atlas.platform_product_category_attributes + WHERE id = $1 AND platform_id = $2 AND is_active AND dictionary_id IS NOT NULL`, + [input.attribute_id, platformId], + ); + if (!attribute.rows[0]) { + throw new ApiError(404, 'ATTRIBUTE_NOT_FOUND', '字典属性不存在'); + } + return { + scopeKey: `dictionary:${input.attribute_id}`, + categoryId: attribute.rows[0].platform_product_category_id, + attributeId: input.attribute_id, + }; + } +} + +type EnqueueInput = { + platformId: string; + scope: 'tree' | 'attributes' | 'dictionary'; + scopeKey: string; + categoryId?: string; + attributeId?: string; + sourceRevision: number; + trigger: 'manual' | 'scheduled' | 'source_configured'; + userId?: string; + idempotencyKey?: string; +}; + +/** 同一事务写入持久任务和平台 Outbox；活跃作用域复用已有任务。 */ +export async function enqueueRun(tx: DatabaseTransaction, input: EnqueueInput): Promise { + const active = await tx.query( + `SELECT id, platform_id, scope, scope_key, status, trigger_kind, created_at + FROM atlas.platform_catalog_sync_runs + WHERE platform_id = $1 AND scope_key = $2 AND status IN ('queued', 'running') + LIMIT 1`, + [input.platformId, input.scopeKey], + ); + if (active.rows[0]) return active.rows[0]; + const inserted = await tx.query( + `INSERT INTO atlas.platform_catalog_sync_runs + (platform_id, scope, scope_key, category_id, attribute_id, trigger_kind, + source_revision, requested_by_user_id, idempotency_key) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) + RETURNING id, platform_id, scope, scope_key, status, trigger_kind, created_at`, + [input.platformId, input.scope, input.scopeKey, input.categoryId ?? null, + input.attributeId ?? null, input.trigger, input.sourceRevision, + input.userId ?? null, input.idempotencyKey ?? null], + ); + const run = inserted.rows[0]; + await tx.query( + `INSERT INTO atlas.platform_catalog_outbox_events (run_id, platform_id) VALUES ($1, $2)`, + [run.id, input.platformId], + ); + return run; +} + +function presentRun(run: RunRow) { + return { + id: run.id, + platform_id: run.platform_id, + scope: run.scope, + status: run.status, + trigger: run.trigger_kind, + created_at: run.created_at, + }; +} diff --git a/apps/api/src/platform-catalog-admin/platform-catalog-admin.controller.ts b/apps/api/src/platform-catalog-admin/platform-catalog-admin.controller.ts new file mode 100644 index 0000000..730963f --- /dev/null +++ b/apps/api/src/platform-catalog-admin/platform-catalog-admin.controller.ts @@ -0,0 +1,132 @@ +import { + Body, Controller, Get, Headers, Inject, Param, Post, Put, Query, + Req, UseGuards, HttpCode, +} from '@nestjs/common'; +import { ApiBearerAuth, ApiTags } from '@nestjs/swagger'; +import type { Database } from '@atlas/database'; +import type { AuthenticatedRequest } from '../auth/auth.guard.js'; +import { ApiError } from '../common/api-error.js'; +import { DATABASE } from '../database/database.module.js'; +import { PlatformCatalogAdminCommands } from './platform-catalog-admin.commands.js'; +import { + parseInput, parseListLimit, parseUuid, sourceInputSchema, syncInputSchema, +} from './platform-catalog-admin.models.js'; +import { PlatformCatalogAdminReads } from './platform-catalog-admin.reads.js'; +import { hasSystemAdminGrant, SystemAdminGuard } from './system-admin.guard.js'; + +@ApiTags('System') +@ApiBearerAuth('access-token') +@Controller('system') +export class SystemAccessController { + public constructor(@Inject(DATABASE) private readonly database: Database) {} + + @Get('access') + public async access(@Req() request: AuthenticatedRequest) { + return { data: { is_system_admin: await hasSystemAdminGrant(this.database, request.auth.userId) } }; + } +} + +@ApiTags('System platform catalog') +@ApiBearerAuth('access-token') +@UseGuards(SystemAdminGuard) +@Controller('system/platform-catalog') +export class PlatformCatalogAdminController { + public constructor( + @Inject(PlatformCatalogAdminReads) private readonly reads: PlatformCatalogAdminReads, + @Inject(PlatformCatalogAdminCommands) private readonly commands: PlatformCatalogAdminCommands, + ) {} + + @Get('platforms') + public async platforms() { + return { data: await this.reads.platforms() }; + } + + @Put('platforms/:platformId/source') + public async configureSource( + @Param('platformId') platformId: string, + @Req() request: AuthenticatedRequest, + @Body() body: unknown, + ) { + return { + data: await this.commands.configureSource( + parseUuid(platformId, 'platform_id'), + request.auth.userId, + parseInput(sourceInputSchema, body), + ), + }; + } + + @Get('platforms/:platformId/categories') + public async categories(@Param('platformId') platformId: string) { + return { data: await this.reads.categories(parseUuid(platformId, 'platform_id')) }; + } + + @Get('platforms/:platformId/categories/:categoryId/attributes') + public async attributes( + @Param('platformId') platformId: string, + @Param('categoryId') categoryId: string, + ) { + return { + data: await this.reads.attributes( + parseUuid(platformId, 'platform_id'), + parseUuid(categoryId, 'category_id'), + ), + }; + } + + @Get('platforms/:platformId/attributes/:attributeId/values') + public async values( + @Param('platformId') platformId: string, + @Param('attributeId') attributeId: string, + @Query('q') keyword: string | undefined, + @Query('page') pageValue: string | undefined, + ) { + const page = pageValue === undefined ? 1 : Number(pageValue); + if (!Number.isInteger(page) || page < 1 || page > 100000) { + throw new ApiError(400, 'VALIDATION_FAILED', 'page 必须为正整数'); + } + if (keyword && keyword.length > 120) { + throw new ApiError(400, 'VALIDATION_FAILED', '搜索词不能超过 120 字符'); + } + return this.reads.values( + parseUuid(platformId, 'platform_id'), + parseUuid(attributeId, 'attribute_id'), + keyword, + page, + ); + } + + @Post('platforms/:platformId/syncs') + @HttpCode(202) + public async sync( + @Param('platformId') platformId: string, + @Headers('idempotency-key') idempotencyKey: string | undefined, + @Req() request: AuthenticatedRequest, + @Body() body: unknown, + ) { + if (!idempotencyKey) { + throw new ApiError(400, 'IDEMPOTENCY_KEY_REQUIRED', '请提供 Idempotency-Key'); + } + return { + data: await this.commands.sync( + parseUuid(platformId, 'platform_id'), + request.auth.userId, + parseUuid(idempotencyKey, 'Idempotency-Key'), + parseInput(syncInputSchema, body), + ), + }; + } + + @Get('platforms/:platformId/syncs') + public async syncs( + @Param('platformId') platformId: string, + @Query('limit') limit: string | undefined, + ) { + return { + data: await this.reads.runs( + parseUuid(platformId, 'platform_id'), + parseListLimit(limit), + ), + }; + } +} diff --git a/apps/api/src/platform-catalog-admin/platform-catalog-admin.models.ts b/apps/api/src/platform-catalog-admin/platform-catalog-admin.models.ts new file mode 100644 index 0000000..8b6ab95 --- /dev/null +++ b/apps/api/src/platform-catalog-admin/platform-catalog-admin.models.ts @@ -0,0 +1,34 @@ +import { z } from 'zod'; +import { ApiError } from '../common/api-error.js'; + +export const sourceInputSchema = z.object({ + client_id: z.string().trim().min(1).max(128), + api_key: z.string().trim().min(1).max(2048), +}).strict(); + +export const syncInputSchema = z.discriminatedUnion('scope', [ + z.object({ scope: z.literal('tree') }).strict(), + z.object({ scope: z.literal('attributes'), category_id: z.uuid() }).strict(), + z.object({ scope: z.literal('dictionary'), attribute_id: z.uuid() }).strict(), +]); + +export type SyncInput = z.infer; +export type SourceInput = z.infer; + +export function parseInput(schema: z.ZodType, input: unknown): T { + const parsed = schema.safeParse(input); + if (parsed.success) return parsed.data; + throw new ApiError(400, 'VALIDATION_FAILED', '请求参数不合法'); +} + +export function parseUuid(value: string, field: string): string { + if (z.uuid().safeParse(value).success) return value; + throw new ApiError(400, 'VALIDATION_FAILED', `${field} 不是有效 UUID`); +} + +export function parseListLimit(value: unknown, defaultValue = 20): number { + if (value === undefined) return defaultValue; + const count = Number(value); + if (Number.isInteger(count) && count >= 1 && count <= 50) return count; + throw new ApiError(400, 'VALIDATION_FAILED', 'limit 必须在 1 到 50 之间'); +} diff --git a/apps/api/src/platform-catalog-admin/platform-catalog-admin.module.ts b/apps/api/src/platform-catalog-admin/platform-catalog-admin.module.ts new file mode 100644 index 0000000..10d417c --- /dev/null +++ b/apps/api/src/platform-catalog-admin/platform-catalog-admin.module.ts @@ -0,0 +1,13 @@ +import { Module } from '@nestjs/common'; +import { + PlatformCatalogAdminController, SystemAccessController, +} from './platform-catalog-admin.controller.js'; +import { PlatformCatalogAdminCommands } from './platform-catalog-admin.commands.js'; +import { PlatformCatalogAdminReads } from './platform-catalog-admin.reads.js'; +import { SystemAdminGuard } from './system-admin.guard.js'; + +@Module({ + controllers: [SystemAccessController, PlatformCatalogAdminController], + providers: [SystemAdminGuard, PlatformCatalogAdminCommands, PlatformCatalogAdminReads], +}) +export class PlatformCatalogAdminModule {} diff --git a/apps/api/src/platform-catalog-admin/platform-catalog-admin.reads.ts b/apps/api/src/platform-catalog-admin/platform-catalog-admin.reads.ts new file mode 100644 index 0000000..bd473dd --- /dev/null +++ b/apps/api/src/platform-catalog-admin/platform-catalog-admin.reads.ts @@ -0,0 +1,158 @@ +import { Inject, Injectable } from '@nestjs/common'; +import type { Database } from '@atlas/database'; +import { ApiError } from '../common/api-error.js'; +import { DATABASE } from '../database/database.module.js'; + +@Injectable() +export class PlatformCatalogAdminReads { + public constructor(@Inject(DATABASE) private readonly database: Database) {} + + public async platforms() { + const rows = await this.database.query<{ + id: string; code: string; name: string; status: string; + client_id: string | null; source_updated_at: Date | null; + category_count: string; last_tree_sync_at: Date | null; last_error: string | null; + }>( + `SELECT p.id, p.code, p.name, p.status, + source.client_id, source.updated_at AS source_updated_at, + (SELECT count(*) FROM atlas.platform_product_categories category + WHERE category.platform_id = p.id AND category.is_active)::text AS category_count, + (SELECT max(completed_at) FROM atlas.platform_catalog_sync_runs run + WHERE run.platform_id = p.id AND run.scope = 'tree' AND run.status = 'succeeded') AS last_tree_sync_at, + (SELECT CASE WHEN run.status = 'failed' THEN run.error_message ELSE NULL END + FROM atlas.platform_catalog_sync_runs run + WHERE run.platform_id = p.id AND run.scope = 'tree' + ORDER BY run.created_at DESC LIMIT 1) AS last_error + FROM atlas.platforms p + LEFT JOIN atlas.platform_catalog_sources source ON source.platform_id = p.id + ORDER BY CASE WHEN upper(p.code) = 'OZON' THEN 0 ELSE 1 END, p.name`, + ); + return rows.rows.map((row) => ({ + id: row.id, + code: row.code, + name: row.name, + status: row.status, + source: { + configured: row.client_id !== null, + client_id_hint: row.client_id ? `••••${row.client_id.slice(-4)}` : null, + updated_at: row.source_updated_at, + }, + summary: { + category_count: Number(row.category_count), + last_tree_sync_at: row.last_tree_sync_at, + last_error: row.last_error, + }, + })); + } + + public async categories(platformId: string) { + await this.requirePlatform(platformId); + const result = await this.database.query( + `SELECT id, parent_id, external_category_id, external_type_id, name, path, + is_active, synced_at + FROM atlas.platform_product_categories + WHERE platform_id = $1 ORDER BY path, id LIMIT 20000`, + [platformId], + ); + return result.rows; + } + + public async attributes(platformId: string, categoryId: string) { + await this.requireCategory(platformId, categoryId); + const result = await this.database.query( + `SELECT attribute.id, attribute.platform_attribute_id, attribute.complex_id, + attribute.name, attribute.description, attribute.group_id, attribute.group_name, + attribute.value_type, attribute.is_required, attribute.is_aspect, + attribute.is_collection, attribute.max_value_count, attribute.dictionary_id, + attribute.category_dependent, attribute.is_active, attribute.synced_at, + (SELECT count(*)::int FROM atlas.platform_catalog_dictionary_values value + WHERE value.attribute_id = attribute.id AND value.is_active) AS dictionary_value_count + FROM atlas.platform_product_category_attributes attribute + WHERE attribute.platform_id = $1 AND attribute.platform_product_category_id = $2 + ORDER BY attribute.is_required DESC, attribute.group_name NULLS LAST, + attribute.name, attribute.platform_attribute_id`, + [platformId, categoryId], + ); + return result.rows; + } + + public async values( + platformId: string, + attributeId: string, + keyword: string | undefined, + page: number, + ) { + const attribute = await this.database.query<{ dictionary_id: string | null }>( + `SELECT dictionary_id FROM atlas.platform_product_category_attributes + WHERE id = $1 AND platform_id = $2 AND is_active`, + [attributeId, platformId], + ); + if (!attribute.rows[0]) throw new ApiError(404, 'ATTRIBUTE_NOT_FOUND', '属性不存在'); + if (!attribute.rows[0].dictionary_id) { + throw new ApiError(422, 'ATTRIBUTE_DICTIONARY_UNAVAILABLE', '该属性没有字典候选值'); + } + const q = keyword?.trim() ?? ''; + const [items, total, lastRun] = await Promise.all([ + this.database.query( + `SELECT id, external_value_id, value, info, picture + FROM atlas.platform_catalog_dictionary_values + WHERE attribute_id = $1 AND is_active + AND ($2 = '' OR value ILIKE '%' || $2 || '%' OR external_value_id = $2) + ORDER BY value, external_value_id LIMIT 100 OFFSET $3`, + [attributeId, q, (page - 1) * 100], + ), + this.database.query<{ count: string }>( + `SELECT count(*)::text AS count FROM atlas.platform_catalog_dictionary_values + WHERE attribute_id = $1 AND is_active + AND ($2 = '' OR value ILIKE '%' || $2 || '%' OR external_value_id = $2)`, + [attributeId, q], + ), + this.database.query<{ is_complete: boolean }>( + `SELECT COALESCE((result->>'is_complete')::boolean, false) AS is_complete + FROM atlas.platform_catalog_sync_runs + WHERE platform_id = $1 AND scope_key = $2 AND status = 'succeeded' + ORDER BY completed_at DESC LIMIT 1`, + [platformId, `dictionary:${attributeId}`], + ), + ]); + return { + data: items.rows, + meta: { + page, + page_size: 100, + total: Number(total.rows[0]?.count ?? 0), + is_complete: lastRun.rows[0]?.is_complete ?? false, + }, + }; + } + + public async runs(platformId: string, limit: number) { + await this.requirePlatform(platformId); + const result = await this.database.query( + `SELECT id, platform_id, scope, scope_key, category_id, attribute_id, + trigger_kind AS trigger, status, result, error_code, error_message, + attempt_count, created_at, started_at, completed_at + FROM atlas.platform_catalog_sync_runs + WHERE platform_id = $1 ORDER BY created_at DESC LIMIT $2`, + [platformId, limit], + ); + return result.rows; + } + + public async requirePlatform(platformId: string) { + const result = await this.database.query<{ code: string }>( + 'SELECT code FROM atlas.platforms WHERE id = $1', + [platformId], + ); + if (!result.rows[0]) throw new ApiError(404, 'PLATFORM_NOT_FOUND', '平台不存在'); + return result.rows[0]; + } + + public async requireCategory(platformId: string, categoryId: string) { + const result = await this.database.query( + `SELECT 1 FROM atlas.platform_product_categories WHERE id = $1 AND platform_id = $2`, + [categoryId, platformId], + ); + if (!result.rows[0]) throw new ApiError(404, 'CATEGORY_NOT_FOUND', '类目不属于当前平台'); + } +} diff --git a/apps/api/src/platform-catalog-admin/system-admin.guard.ts b/apps/api/src/platform-catalog-admin/system-admin.guard.ts new file mode 100644 index 0000000..5831940 --- /dev/null +++ b/apps/api/src/platform-catalog-admin/system-admin.guard.ts @@ -0,0 +1,28 @@ +import { CanActivate, ExecutionContext, Inject, Injectable } from '@nestjs/common'; +import type { Database } from '@atlas/database'; +import type { AuthenticatedRequest } from '../auth/auth.guard.js'; +import { ApiError } from '../common/api-error.js'; +import { DATABASE } from '../database/database.module.js'; + +@Injectable() +export class SystemAdminGuard implements CanActivate { + public constructor(@Inject(DATABASE) private readonly database: Database) {} + + public async canActivate(context: ExecutionContext): Promise { + const request = context.switchToHttp().getRequest(); + if (await hasSystemAdminGrant(this.database, request.auth.userId)) return true; + throw new ApiError(403, 'SYSTEM_ADMIN_REQUIRED', '需要系统管理员权限'); + } +} + +/** 授权实时查库；撤销后旧 JWT 不能继续使用后台接口。 */ +export async function hasSystemAdminGrant(database: Database, userId: string): Promise { + const result = await database.query( + `SELECT 1 FROM atlas.system_admin_grants grant_row + JOIN atlas.users user_row ON user_row.id = grant_row.user_id + WHERE grant_row.user_id = $1 AND grant_row.revoked_at IS NULL + AND user_row.status = 'active'`, + [userId], + ); + return !!result.rowCount; +} diff --git a/apps/api/src/product-editor/product-editor.attribute-bindings.ts b/apps/api/src/product-editor/product-editor.attribute-bindings.ts new file mode 100644 index 0000000..05506a2 --- /dev/null +++ b/apps/api/src/product-editor/product-editor.attribute-bindings.ts @@ -0,0 +1,33 @@ +import type { ProductAttributeSchema } from '@atlas/contracts'; + +type AttributeDefinition = Omit; +type EditorField = Exclude; + +/** Ozon 固定属性 ID 到编辑器内建字段的唯一映射，不使用任何名称或翻译文本判断。 */ +const editorFieldByAttributeId: Readonly> = { + '85': 'brand', + '9048': 'model', + '8229': 'category', + '23171': 'tags', + '11254': 'rich_content', + '4191': 'description', +}; + +/** 仅依据 Ozon 属性 ID 将类目属性绑定到编辑器内建字段。 */ +export function editorFieldForAttributeId( + platformAttributeId: string, +): ProductAttributeSchema['editor_field'] { + return editorFieldByAttributeId[platformAttributeId] ?? null; +} + +/** 为数据库中的原始类目属性补充前端和校验共用的内建字段绑定。 */ +export function bindEditorFields( + definitions: AttributeDefinition[], +): ProductAttributeSchema[] { + return definitions.map((definition) => ({ + ...definition, + editor_field: editorFieldForAttributeId( + definition.platform_attribute_id, + ), + })); +} diff --git a/apps/api/src/product-editor/product-editor.catalog-operations.ts b/apps/api/src/product-editor/product-editor.catalog-operations.ts index 5b76d1b..8607e0c 100644 --- a/apps/api/src/product-editor/product-editor.catalog-operations.ts +++ b/apps/api/src/product-editor/product-editor.catalog-operations.ts @@ -21,6 +21,26 @@ type CatalogSyncResult = { body: unknown; }; +type DictionaryCursor = { value: string; value_id: string; query: string }; + +/** 游标仅记录排序位置；类目、字典及搜索条件仍由当前请求的权限校验约束。 */ +function parseDictionaryCursor(cursor: string | undefined): DictionaryCursor | null { + if (!cursor) return null; + if (cursor.length > 2_000) throw new ApiError(400, 'VALIDATION_FAILED', '字典游标不合法'); + try { + const parsed: unknown = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')); + if ( + parsed && typeof parsed === 'object' && + typeof (parsed as DictionaryCursor).value === 'string' && + typeof (parsed as DictionaryCursor).value_id === 'string' && + typeof (parsed as DictionaryCursor).query === 'string' + ) return parsed as DictionaryCursor; + } catch { + // 无效游标统一返回参数错误。 + } + throw new ApiError(400, 'VALIDATION_FAILED', '字典游标不合法'); +} + type CatalogAccess = { requireProfileForPlatform: ( transaction: DatabaseTransaction, @@ -155,9 +175,11 @@ export class ProductEditorCatalogOperations { platformId: string, dictionaryId: string, search: string | undefined, + cursor: string | undefined, categoryId?: string, storeId?: string, ) { + const after = parseDictionaryCursor(cursor); return this.database.workspaceTransaction( workspaceId, async (transaction) => { @@ -202,6 +224,8 @@ export class ProductEditorCatalogOperations { '字典不属于当前类目的属性', ); const needle = search?.trim() ?? ''; + if (after && after.query !== needle) + throw new ApiError(400, 'VALIDATION_FAILED', '字典游标与搜索条件不匹配'); const values = await transaction.query<{ value_id: string; value: string; @@ -211,11 +235,20 @@ export class ProductEditorCatalogOperations { WHERE store_id = $1 AND store_product_category_id = $2 AND dictionary_id = $3 AND is_active AND ($4 = '' OR value ILIKE '%' || $4 || '%') + AND ($5::text IS NULL OR (value, external_value_id) > ($5, $6)) ORDER BY value, external_value_id - LIMIT 100`, - [selectedStoreId, selectedCategoryId, dictionaryId, needle], + LIMIT 201`, + [selectedStoreId, selectedCategoryId, dictionaryId, needle, + after?.value ?? null, after?.value_id ?? null], ); - return { items: values.rows, next_cursor: null }; + const items = values.rows.slice(0, 200); + const last = items.at(-1); + return { + items, + next_cursor: values.rows.length > 200 && last + ? Buffer.from(JSON.stringify({ ...last, query: needle })).toString('base64url') + : null, + }; }, ); } @@ -241,7 +274,7 @@ export class ProductEditorCatalogOperations { }); } - /** 创建带关键词限制的属性字典同步任务。 */ + /** 创建首批字典值或关键词搜索同步任务。 */ async requestAttributeDictionarySync( workspaceId: string, userId: string, @@ -252,7 +285,7 @@ export class ProductEditorCatalogOperations { dictionaryId: string, query: string, ) { - if (query.trim().length < 2) + if (query.trim().length === 1) throw new ApiError( 422, 'DICTIONARY_SEARCH_REQUIRED', diff --git a/apps/api/src/product-editor/product-editor.controller.ts b/apps/api/src/product-editor/product-editor.controller.ts index 94aff01..e16f458 100644 --- a/apps/api/src/product-editor/product-editor.controller.ts +++ b/apps/api/src/product-editor/product-editor.controller.ts @@ -108,6 +108,22 @@ export class ProductEditorController { }; } + /** 返回首次上架前的服务端发布就绪校验。 */ + @Get('product-platform-profiles/:profileId/validation') + async validation( + @Param('profileId') profileId: string, + @Headers('x-atlas-platform-id') platformId: string | undefined, + @CurrentWorkspace() workspace: Workspace, + ) { + return { + data: await this.editor.validation( + workspace.id, + requiredUuid('profile_id', profileId), + requiredUuid('X-Atlas-Platform-Id', platformId), + ), + }; + } + /** 幂等地创建所选类目属性定义的刷新任务。 */ @Post('product-platform-profiles/:profileId/attribute-schema-syncs') async attributeSchemaSync( @@ -139,6 +155,7 @@ export class ProductEditorController { @Param('profileId') profileId: string, @Param('dictionaryId') dictionaryId: string, @Query('q') query: string | undefined, + @Query('cursor') cursor: string | undefined, @Query('category_id') categoryId: string | undefined, @Query('store_id') storeId: string | undefined, @Headers('x-atlas-platform-id') platformId: string | undefined, @@ -153,6 +170,7 @@ export class ProductEditorController { requiredUuid('X-Atlas-Platform-Id', platformId), dictionaryId, query, + cursor, optionalUuid('category_id', categoryId), optionalUuid('store_id', storeId), ), diff --git a/apps/api/src/product-editor/product-editor.models.ts b/apps/api/src/product-editor/product-editor.models.ts index b76ce9f..1a958f9 100644 --- a/apps/api/src/product-editor/product-editor.models.ts +++ b/apps/api/src/product-editor/product-editor.models.ts @@ -28,6 +28,7 @@ export type ProductRow = { /** 商品在一个发布平台下的编辑配置行。 */ export type ProfileRow = { id: string; + product_id: string; revision: number; platform_id: string; market_code: string | null; @@ -57,7 +58,7 @@ export type OperationRow = { }; /** 统一读取发布配置及其目标店铺与类目展示信息的查询片段。 */ -export const profileSelect = `SELECT p.id, p.revision, p.platform_id, p.market_code, +export const profileSelect = `SELECT p.id, p.product_id, p.revision, p.platform_id, p.market_code, p.fulfillment, p.title, p.description, p.tags, p.store_product_category_id, p.platform_type_id, p.category_source, category.name AS category_name, category.path AS category_path, p.target_store_id, s.name AS store_name, diff --git a/apps/api/src/product-editor/product-editor.service.ts b/apps/api/src/product-editor/product-editor.service.ts index e7c7ee7..3b70417 100644 --- a/apps/api/src/product-editor/product-editor.service.ts +++ b/apps/api/src/product-editor/product-editor.service.ts @@ -16,6 +16,8 @@ import { profileSelect, } from './product-editor.models.js'; import { ProductEditorCatalogOperations } from './product-editor.catalog-operations.js'; +import { bindEditorFields } from './product-editor.attribute-bindings.js'; +import { ProductEditorValidationOperations } from './product-editor.validation.js'; import { latestProductAiSourceMaterial, normalizedCategoryPath as normalizeCapturedCategoryPath, @@ -35,6 +37,7 @@ import { @Injectable() export class ProductEditorService { private readonly catalog: ProductEditorCatalogOperations; + private readonly validationOperations: ProductEditorValidationOperations; /** 注入编辑工作流所需的事务数据库和幂等边界。 */ public constructor( @@ -45,12 +48,24 @@ export class ProductEditorService { this.catalog = new ProductEditorCatalogOperations(this.database, { requireProfileForPlatform: (...args) => this.requireProfileForPlatform(...args), - requireEditableStore: (...args) => this.requireEditableStore(...args), - requireActiveCategory: (...args) => this.requireActiveCategory(...args), + requireEditableStore: (...args) => + this.requireEditableStore(...args), + requireActiveCategory: (...args) => + this.requireActiveCategory(...args), attributeSchemaForCategory: (...args) => this.attributeSchemaForCategory(...args), requestCatalogSync: (input) => this.requestCatalogSync(input), }); + this.validationOperations = new ProductEditorValidationOperations( + this.database, + { + requireProfileForPlatform: (...args) => + this.requireProfileForPlatform(...args), + requireProduct: (...args) => this.requireProduct(...args), + attributeSchemaForCategory: (...args) => + this.attributeSchemaForCategory(...args), + }, + ); } /** 创建或复用平台发布配置，并返回编辑器导航上下文。 */ @@ -487,6 +502,19 @@ export class ProductEditorService { ); } + /** 按当前持久化草稿和 Ozon 类目 schema 计算首次上架就绪状态。 */ + async validation( + workspaceId: string, + profileId: string, + platformId: string, + ) { + return this.validationOperations.validation( + workspaceId, + profileId, + platformId, + ); + } + /** 仅从店铺本地缓存查询当前类目的字典值。 */ async attributeDictionary( workspaceId: string, @@ -494,6 +522,7 @@ export class ProductEditorService { platformId: string, dictionaryId: string, search: string | undefined, + cursor: string | undefined, categoryId?: string, storeId?: string, ) { @@ -503,6 +532,7 @@ export class ProductEditorService { platformId, dictionaryId, search, + cursor, categoryId, storeId, ); @@ -1002,7 +1032,10 @@ export class ProductEditorService { 'SKU 发布记录已变化，请重新加载编辑器', ); const listingByVariant = new Map( - listings.rows.map((listing) => [listing.product_variant_id, listing]), + listings.rows.map((listing) => [ + listing.product_variant_id, + listing, + ]), ); const assetIds = [ ...new Set(input.variants.flatMap((variant) => variant.assetIds)), @@ -1020,7 +1053,9 @@ export class ProductEditorService { [assetIds], ) : { rows: [] }; - const assetById = new Map(assets.rows.map((asset) => [asset.id, asset])); + const assetById = new Map( + assets.rows.map((asset) => [asset.id, asset]), + ); const existing = await transaction.query<{ product_variant_id: string; asset_id: string; @@ -1033,7 +1068,8 @@ export class ProductEditorService { ); const existingByVariant = new Map>(); for (const item of existing.rows) { - const ids = existingByVariant.get(item.product_variant_id) ?? new Set(); + const ids = + existingByVariant.get(item.product_variant_id) ?? new Set(); ids.add(item.asset_id); existingByVariant.set(item.product_variant_id, ids); } @@ -1058,7 +1094,8 @@ export class ProductEditorService { : { rows: [] }; const candidateVariants = new Map>(); for (const candidate of candidates.rows) { - const variants = candidateVariants.get(candidate.asset_id) ?? new Set(); + const variants = + candidateVariants.get(candidate.asset_id) ?? new Set(); variants.add(candidate.source_variant_id); candidateVariants.set(candidate.asset_id, variants); } @@ -1094,7 +1131,10 @@ export class ProductEditorService { if (existingByVariant.get(variant.variantId)?.has(assetId)) continue; const allowedFor = candidateVariants.get(assetId); - if (!allowedFor?.has(null) && !allowedFor?.has(variant.variantId)) + if ( + !allowedFor?.has(null) && + !allowedFor?.has(variant.variantId) + ) throw new ApiError( 422, 'LISTING_MEDIA_NOT_SELECTABLE', @@ -1252,6 +1292,16 @@ export class ProductEditorService { ); continue; } + // 主要信息字段是唯一事实来源；兼容旧页面提交的重复属性，但不再持久化。 + if (definition.editor_field) continue; + if (definition.is_aspect !== (attribute.scope === 'variant')) + throw new ApiError( + 422, + 'ATTRIBUTE_SCOPE_INVALID', + definition.is_aspect + ? `${definition.name} 必须按 SKU 填写` + : `${definition.name} 必须作为商品通用属性填写`, + ); if (attribute.scope === 'variant') { if (!attribute.variant_id) throw new ApiError( @@ -1441,7 +1491,7 @@ export class ProductEditorService { ORDER BY is_required DESC, is_aspect, name, platform_attribute_id, complex_id`, [storeId, categoryId], ); - return result.rows; + return bindEditorFields(result.rows); } /** 写入操作记录和 Outbox 事件，供异步刷新目录缓存。 */ @@ -1601,7 +1651,8 @@ export class ProductEditorService { WHERE item.id = $1 AND item.deleted_at IS NULL`, [product.collection_item_id], ); - if (sourcePlatform.rows[0]?.code.toUpperCase() !== 'OZON') return profile; + if (sourcePlatform.rows[0]?.code.toUpperCase() !== 'OZON') + return profile; const category = await transaction.query<{ id: string; diff --git a/apps/api/src/product-editor/product-editor.validation.ts b/apps/api/src/product-editor/product-editor.validation.ts new file mode 100644 index 0000000..5b45563 --- /dev/null +++ b/apps/api/src/product-editor/product-editor.validation.ts @@ -0,0 +1,320 @@ +import type { + ProductAttributeSchema, + ProductEditorValidation, +} from '@atlas/contracts'; +import type { Database, DatabaseTransaction } from '@atlas/database'; +import type { ProductRow, ProfileRow } from './product-editor.models.js'; + +type ValidationAccess = { + requireProfileForPlatform: ( + transaction: DatabaseTransaction, + profileId: string, + platformId: string, + ) => Promise; + requireProduct: ( + transaction: DatabaseTransaction, + productId: string, + ) => Promise; + attributeSchemaForCategory: ( + transaction: DatabaseTransaction, + storeId: string, + categoryId: string, + ) => Promise; +}; + +type VariantValidationRow = { + id: string; + display_name: string | null; + listing_status: string; + offer_id: string | null; + selling_price: string | null; + package_length_mm: string | null; + package_width_mm: string | null; + package_height_mm: string | null; + shipping_weight_g: string | null; + package_spec_status: string; + media_count: string; +}; + +type AttributeValidationRow = { + scope: 'common' | 'variant'; + product_variant_id: string | null; + platform_attribute_id: string; + complex_id: string; + values: unknown; + confirmation_status: string; +}; + +/** + * 计算商品草稿的首次上架就绪状态。 + * 草稿保存保持宽松，这里的结果供发布前校验和页面问题汇总使用。 + */ +export class ProductEditorValidationOperations { + /** 注入工作空间事务入口和编辑器统一访问边界。 */ + public constructor( + private readonly database: Database, + private readonly access: ValidationAccess, + ) {} + + /** 按当前持久化草稿和 Ozon 类目 schema 返回结构化校验结果。 */ + async validation( + workspaceId: string, + profileId: string, + platformId: string, + ): Promise { + return this.database.workspaceTransaction( + workspaceId, + async (transaction) => { + const profile = await this.access.requireProfileForPlatform( + transaction, + profileId, + platformId, + ); + const product = await this.access.requireProduct( + transaction, + profile.product_id, + ); + const variants = await this.readVariants( + transaction, + profile.id, + profile.product_id, + ); + const attributes = await this.readAttributes( + transaction, + profile.id, + ); + const schema = profile.store_product_category_id + ? await this.access.attributeSchemaForCategory( + transaction, + profile.target_store_id, + profile.store_product_category_id, + ) + : []; + + const profileIssues = this.profileIssues( + product, + profile, + schema, + attributes, + ); + const variantResults = variants.map((variant) => + this.variantResult(variant, schema, attributes), + ); + const publishableVariants = variantResults.filter( + (variant) => variant.status !== 'not_publishable_again', + ); + + return { + ready: + profileIssues.length === 0 && + publishableVariants.length > 0 && + publishableVariants.every((variant) => variant.ready), + profile: { + ready: profileIssues.length === 0, + issues: profileIssues, + }, + variants: variantResults, + }; + }, + ); + } + + /** 汇总商品级基础信息与通用类目属性问题。 */ + private profileIssues( + product: ProductRow, + profile: ProfileRow, + schema: ProductAttributeSchema[], + attributes: AttributeValidationRow[], + ): ProductEditorValidation['profile']['issues'] { + const issues: ProductEditorValidation['profile']['issues'] = []; + if (!product.source_title?.trim()) + issues.push({ + code: 'TITLE_REQUIRED', + field: 'common.source_title', + message: '请填写标题', + }); + if (!product.model?.trim()) + issues.push({ + code: 'MODEL_REQUIRED', + field: 'common.model', + message: '请填写型号', + }); + if (!product.brand?.trim()) + issues.push({ + code: 'BRAND_REQUIRED', + field: 'common.brand', + message: '请填写品牌', + }); + if (!profile.store_product_category_id) + issues.push({ + code: 'CATEGORY_REQUIRED', + field: 'profile.store_product_category_id', + message: '请选择产品类目', + }); + if (profile.store_product_category_id && !schema.length) + issues.push({ + code: 'ATTRIBUTE_SCHEMA_REQUIRED', + field: 'attributes', + message: '当前类目的 Ozon 属性尚未同步', + }); + + for (const definition of schema.filter( + (item) => item.is_required && !item.is_aspect && !item.editor_field, + )) { + if (!hasConfirmedValue(attributes, 'common', null, definition)) + issues.push({ + code: 'OZON_ATTRIBUTE_REQUIRED', + field: `attributes.${definition.platform_attribute_id}.${definition.complex_id}`, + message: `请填写${definition.name}`, + platform_attribute_id: definition.platform_attribute_id, + }); + } + return issues; + } + + /** 计算单个 SKU 的发布资格与缺失项。 */ + private variantResult( + variant: VariantValidationRow, + schema: ProductAttributeSchema[], + attributes: AttributeValidationRow[], + ): ProductEditorValidation['variants'][number] { + if (variant.listing_status === 'imported') + return { + variant_id: variant.id, + display_name: variant.display_name, + status: 'not_publishable_again', + ready: false, + issues: [], + }; + + const issues: ProductEditorValidation['variants'][number]['issues'] = + []; + if (!variant.offer_id?.trim()) + issues.push({ + code: 'OFFER_ID_REQUIRED', + field: `variants.${variant.id}.offer_id`, + message: '请填写卖家货号', + }); + if (!variant.selling_price) + issues.push({ + code: 'PRICE_REQUIRED', + field: `variants.${variant.id}.selling_price`, + message: '请先确认售价', + }); + if ( + variant.package_spec_status !== 'confirmed' || + !variant.package_length_mm || + !variant.package_width_mm || + !variant.package_height_mm || + !variant.shipping_weight_g + ) + issues.push({ + code: 'PACKAGE_SPEC_REQUIRED', + field: `variants.${variant.id}.package_spec`, + message: '请确认有效的包装重量和包装尺寸', + }); + if (Number(variant.media_count) < 1) + issues.push({ + code: 'IMAGE_REQUIRED', + field: `variants.${variant.id}.media_asset_ids`, + message: '请至少选择一张 SKU 图片', + }); + + for (const definition of schema.filter( + (item) => item.is_required && item.is_aspect && !item.editor_field, + )) { + if ( + !hasConfirmedValue( + attributes, + 'variant', + variant.id, + definition, + ) + ) + issues.push({ + code: 'OZON_ATTRIBUTE_REQUIRED', + field: `variants.${variant.id}.attributes.${definition.platform_attribute_id}.${definition.complex_id}`, + message: `请填写${definition.name}`, + platform_attribute_id: definition.platform_attribute_id, + }); + } + + return { + variant_id: variant.id, + display_name: variant.display_name, + status: issues.length ? 'blocked' : 'ready', + ready: issues.length === 0, + issues, + }; + } + + /** 一次读取 SKU 的售价、有效包装规格和素材数量。 */ + private async readVariants( + transaction: DatabaseTransaction, + profileId: string, + productId: string, + ) { + const variants = await transaction.query( + `SELECT v.id, v.display_name, listing.status AS listing_status, + listing.offer_id, listing.selling_price::text, + coalesce(v.package_length_mm, product.default_package_length_mm)::text AS package_length_mm, + coalesce(v.package_width_mm, product.default_package_width_mm)::text AS package_width_mm, + coalesce(v.package_height_mm, product.default_package_height_mm)::text AS package_height_mm, + coalesce(v.shipping_weight_g, product.default_shipping_weight_g)::text AS shipping_weight_g, + coalesce(v.package_spec_status, product.package_spec_status) AS package_spec_status, + count(media.id)::text AS media_count + FROM atlas.product_variants v + JOIN atlas.products product ON product.id = v.product_id + JOIN atlas.product_variant_platform_listings listing + ON listing.product_variant_id = v.id AND listing.profile_id = $1 + LEFT JOIN atlas.product_variant_listing_media media ON media.listing_id = listing.id + WHERE v.product_id = $2 AND v.deleted_at IS NULL + GROUP BY v.id, v.display_name, listing.status, listing.offer_id, + listing.selling_price, product.default_package_length_mm, + product.default_package_width_mm, product.default_package_height_mm, + product.default_shipping_weight_g, product.package_spec_status + ORDER BY v.sort_order, v.id`, + [profileId, productId], + ); + return variants.rows; + } + + /** 读取当前发布配置下已经持久化的动态属性值。 */ + private async readAttributes( + transaction: DatabaseTransaction, + profileId: string, + ) { + const attributes = await transaction.query( + `SELECT scope, product_variant_id, platform_attribute_id, complex_id, + values, confirmation_status + FROM atlas.product_attributes WHERE profile_id = $1`, + [profileId], + ); + return attributes.rows; + } +} + +/** 只有已确认且至少包含一个非空字符串的值才满足发布要求。 */ +function hasConfirmedValue( + attributes: AttributeValidationRow[], + scope: 'common' | 'variant', + variantId: string | null, + definition: ProductAttributeSchema, +) { + return attributes.some( + (attribute) => + attribute.scope === scope && + attribute.product_variant_id === variantId && + attribute.platform_attribute_id === + definition.platform_attribute_id && + attribute.complex_id === definition.complex_id && + attribute.confirmation_status === 'confirmed' && + stringValues(attribute.values).some((value) => value.trim()), + ); +} + +function stringValues(value: unknown): string[] { + return Array.isArray(value) + ? value.filter((item): item is string => typeof item === 'string') + : []; +} diff --git a/apps/api/test/platform-catalog-admin.unit.test.ts b/apps/api/test/platform-catalog-admin.unit.test.ts new file mode 100644 index 0000000..e1822d9 --- /dev/null +++ b/apps/api/test/platform-catalog-admin.unit.test.ts @@ -0,0 +1,49 @@ +import assert from 'node:assert/strict'; +import type { Database } from '@atlas/database'; +import { describe, it } from 'vitest'; +import { + parseInput, + sourceInputSchema, + syncInputSchema, +} from '../src/platform-catalog-admin/platform-catalog-admin.models.js'; +import { hasSystemAdminGrant } from '../src/platform-catalog-admin/system-admin.guard.js'; + +describe('平台目录系统管理员边界', () => { + it('只有未撤销且用户有效的数据库授权才被视为系统管理员', async () => { + const queries: Array<{ sql: string; parameters: unknown[] }> = []; + const database = { + query: async (sql: string, parameters: unknown[]) => { + queries.push({ sql, parameters }); + return { rowCount: 1, rows: [{ '?column?': 1 }] }; + }, + } as unknown as Database; + + assert.equal(await hasSystemAdminGrant(database, 'user-1'), true); + assert.deepEqual(queries[0].parameters, ['user-1']); + assert.match(queries[0].sql, /revoked_at IS NULL/); + assert.match(queries[0].sql, /user_row\.status = 'active'/); + }); + + it('同步请求不能混入其他作用域字段', () => { + assert.throws(() => parseInput(syncInputSchema, { + scope: 'tree', + category_id: '3f7e8462-c23c-4a38-ae86-0f3d78503870', + })); + assert.throws(() => parseInput(syncInputSchema, { + scope: 'dictionary', + attribute_id: 'not-a-uuid', + })); + }); + + it('同步来源仅接受 Client-Id 与 Api-Key', () => { + assert.deepEqual(parseInput(sourceInputSchema, { + client_id: ' 12345 ', + api_key: ' secret ', + }), { client_id: '12345', api_key: 'secret' }); + assert.throws(() => parseInput(sourceInputSchema, { + client_id: '12345', + api_key: 'secret', + workspace_id: 'forbidden', + })); + }); +}); diff --git a/apps/api/test/product-editor.e2e.test.ts b/apps/api/test/product-editor.e2e.test.ts index 782296b..8a48bc8 100644 --- a/apps/api/test/product-editor.e2e.test.ts +++ b/apps/api/test/product-editor.e2e.test.ts @@ -68,7 +68,14 @@ async function seedStoreCategory( (workspace_id, store_id, platform_id, external_category_id, external_type_id, name, path) VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3, $4, $5, $6) RETURNING id`, - [storeId, platformId, externalCategoryId, externalTypeId, name, path], + [ + storeId, + platformId, + externalCategoryId, + externalTypeId, + name, + path, + ], ); return { id: category.rows[0].id, storeId }; }); @@ -115,9 +122,10 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { '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.operations WHERE workspace_id = $1', + [workspaceId], + ); await tx.query( 'DELETE FROM atlas.product_unmapped_attributes WHERE workspace_id = $1', [workspaceId], @@ -161,9 +169,10 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { await tx.query('DELETE FROM atlas.stores WHERE workspace_id = $1', [ workspaceId, ]); - await tx.query('DELETE FROM atlas.media_assets WHERE workspace_id = $1', [ - workspaceId, - ]); + await tx.query( + 'DELETE FROM atlas.media_assets WHERE workspace_id = $1', + [workspaceId], + ); }); await database.query( 'DELETE FROM atlas.workspace_memberships WHERE user_id = $1', @@ -852,38 +861,64 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { ); }); - it('M3.4 按当前类目返回动态属性，并将类目切换后的旧属性保留为未映射草稿', async () => { + it('M3.4 返回去重语义的动态属性，并校验必填、scope 与类目切换', async () => { const dictionarySuffix = randomUUID(); const materialDictionaryId = `m34-material-${dictionarySuffix}`; const colorDictionaryId = `m34-color-${dictionarySuffix}`; seededDictionaryIds.push(materialDictionaryId, colorDictionaryId); - const categoryA = await seedStoreCategory(`m34-a-${randomUUID()}`, 'type-a', 'M3.4 收纳箱', '家居 › 收纳 › M3.4 收纳箱'); - const categoryB = await seedStoreCategory(`m34-b-${randomUUID()}`, 'type-b', 'M3.4 背包', '箱包 › 背包 › M3.4 背包'); + const categoryA = await seedStoreCategory( + `m34-a-${randomUUID()}`, + 'type-a', + 'M3.4 收纳箱', + '家居 › 收纳 › M3.4 收纳箱', + ); + const categoryB = await seedStoreCategory( + `m34-b-${randomUUID()}`, + 'type-b', + 'M3.4 背包', + '箱包 › 背包 › M3.4 背包', + ); seededCategoryIds.push(categoryA.id, categoryB.id); - await database.workspaceTransaction(workspaceId, (tx) => tx.query( - `INSERT INTO atlas.store_product_category_attributes + await database.workspaceTransaction(workspaceId, (tx) => + tx.query( + `INSERT INTO atlas.store_product_category_attributes (workspace_id, store_id, platform_id, store_product_category_id, platform_attribute_id, name, value_type, is_required, is_collection, max_value_count, dictionary_id, is_aspect) VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3, 'material', '材质', 'dictionary', true, false, 1, $5, false), (current_setting('app.workspace_id')::uuid, $1, $2, $3, 'color', '颜色', 'dictionary', true, false, 1, $6, true), + (current_setting('app.workspace_id')::uuid, $1, $2, $3, '85', '品牌', 'text', true, false, 1, NULL, false), + (current_setting('app.workspace_id')::uuid, $1, $2, $3, '9048', '型号名称', 'text', true, false, 1, NULL, false), + (current_setting('app.workspace_id')::uuid, $1, $2, $3, '8229', '类型', 'text', true, false, 1, NULL, false), + (current_setting('app.workspace_id')::uuid, $1, $2, $3, '23171', '主题标签', 'text', false, true, 10, NULL, false), + (current_setting('app.workspace_id')::uuid, $1, $2, $3, '11254', 'JSON 富内容', 'text', false, false, 1, NULL, false), + (current_setting('app.workspace_id')::uuid, $1, $2, $3, '4191', '简介', 'text', true, false, 1, NULL, false), (current_setting('app.workspace_id')::uuid, $1, $2, $4, 'capacity', '容量', 'integer', false, false, 1, NULL, false)`, - [ - categoryA.storeId, - platformId, - categoryA.id, - categoryB.id, - materialDictionaryId, - colorDictionaryId, - ], - )); - await database.workspaceTransaction(workspaceId, (tx) => tx.query( - `INSERT INTO atlas.store_attribute_dictionary_values + [ + categoryA.storeId, + platformId, + categoryA.id, + categoryB.id, + materialDictionaryId, + colorDictionaryId, + ], + ), + ); + await database.workspaceTransaction(workspaceId, (tx) => + tx.query( + `INSERT INTO atlas.store_attribute_dictionary_values (workspace_id, store_id, platform_id, store_product_category_id, dictionary_id, external_value_id, value) VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3, $4, 'cotton', '棉'), (current_setting('app.workspace_id')::uuid, $1, $2, $3, $5, 'black', '黑色')`, - [categoryA.storeId, platformId, categoryA.id, materialDictionaryId, colorDictionaryId], - )); + [ + categoryA.storeId, + platformId, + categoryA.id, + materialDictionaryId, + colorDictionaryId, + ], + ), + ); const categories = await request( `/api/product-platform-profiles/${first.profileId}/category-options?q=M3.4`, { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }, @@ -900,6 +935,10 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { headers: headers({ 'X-Atlas-Platform-Id': platformId }), }, ); + const attributeVariantId = + before.body.data.variants.find( + (variant: any) => variant.listing.status !== 'imported', + )?.id ?? before.body.data.variants[0].id; const variants = before.body.data.variants.map((variant: any) => ({ id: variant.id, client_key: null, @@ -945,7 +984,7 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { }, { scope: 'variant', - variant_id: variants[0].id, + variant_id: attributeVariantId, platform_attribute_id: 'color', complex_id: '0', values: ['black'], @@ -953,6 +992,16 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { source: 'manual', confirmation_status: 'confirmed', }, + { + scope: 'common', + variant_id: null, + platform_attribute_id: '85', + complex_id: '0', + values: ['重复品牌值'], + language_code: null, + source: 'manual', + confirmation_status: 'confirmed', + }, ], variants, }; @@ -981,6 +1030,48 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { ).is_aspect, true, ); + assert.equal( + schema.body.data.find( + (item: { platform_attribute_id: string }) => + item.platform_attribute_id === '85', + ).editor_field, + 'brand', + ); + assert.equal( + schema.body.data.find( + (item: { platform_attribute_id: string }) => + item.platform_attribute_id === '9048', + ).editor_field, + 'model', + ); + assert.equal( + schema.body.data.find( + (item: { platform_attribute_id: string }) => + item.platform_attribute_id === '8229', + ).editor_field, + 'category', + ); + assert.equal( + schema.body.data.find( + (item: { platform_attribute_id: string }) => + item.platform_attribute_id === '23171', + ).editor_field, + 'tags', + ); + assert.equal( + schema.body.data.find( + (item: { platform_attribute_id: string }) => + item.platform_attribute_id === '11254', + ).editor_field, + 'rich_content', + ); + assert.equal( + schema.body.data.find( + (item: { platform_attribute_id: string }) => + item.platform_attribute_id === '4191', + ).editor_field, + 'description', + ); const dictionary = await request( `/api/product-platform-profiles/${first.profileId}/attribute-dictionaries/${materialDictionaryId}?category_id=${categoryA.id}`, { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }, @@ -988,19 +1079,174 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { assert.deepEqual(dictionary.body.data.items, [ { value_id: 'cotton', value: '棉' }, ]); + await database.workspaceTransaction(workspaceId, (tx) => + tx.query( + `INSERT INTO atlas.store_attribute_dictionary_values + (workspace_id, store_id, platform_id, store_product_category_id, + dictionary_id, external_value_id, value) + SELECT current_setting('app.workspace_id')::uuid, $1, $2, $3, $4, + 'page-' || value::text, '测试选项' || lpad(value::text, 3, '0') + FROM generate_series(1, 205) AS series(value)`, + [categoryA.storeId, platformId, categoryA.id, materialDictionaryId], + ), + ); + const dictionaryPageOne = await request( + `/api/product-platform-profiles/${first.profileId}/attribute-dictionaries/${materialDictionaryId}?category_id=${categoryA.id}`, + { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }, + ); + assert.equal(dictionaryPageOne.body.data.items.length, 200); + assert.ok(dictionaryPageOne.body.data.next_cursor); + const dictionaryPageTwo = await request( + `/api/product-platform-profiles/${first.profileId}/attribute-dictionaries/${materialDictionaryId}?category_id=${categoryA.id}&cursor=${encodeURIComponent(dictionaryPageOne.body.data.next_cursor)}`, + { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }, + ); + assert.equal(dictionaryPageTwo.body.data.items.length, 6); + assert.equal(dictionaryPageTwo.body.data.next_cursor, null); + const invalidDictionaryCursor = await request( + `/api/product-platform-profiles/${first.profileId}/attribute-dictionaries/${materialDictionaryId}?category_id=${categoryA.id}&cursor=invalid`, + { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }, + ); + assert.equal(invalidDictionaryCursor.response.status, 400); const afterSave = await request( `/api/products/${first.productId}/editor`, { headers: headers({ 'X-Atlas-Platform-Id': platformId }), }, ); - assert.equal( - afterSave.body.data.profile.category.id, - categoryA.id, - ); + assert.equal(afterSave.body.data.profile.category.id, categoryA.id); assert.equal(afterSave.body.data.profile.category.name, 'M3.4 收纳箱'); assert.equal(afterSave.body.data.attributes.length, 2); + const validAttributes = await request( + `/api/product-platform-profiles/${first.profileId}/validation`, + { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }, + ); + assert.equal(validAttributes.response.status, 200); + assert.ok( + !validAttributes.body.data.profile.issues.some( + (issue: { code: string }) => + issue.code === 'OZON_ATTRIBUTE_REQUIRED', + ), + ); + assert.ok( + !validAttributes.body.data.variants + .find( + (variant: { variant_id: string }) => + variant.variant_id === attributeVariantId, + ) + .issues.some( + (issue: { code: string }) => + issue.code === 'OZON_ATTRIBUTE_REQUIRED', + ), + ); + + await database.workspaceTransaction(workspaceId, (tx) => + tx.query( + `DELETE FROM atlas.product_attributes + WHERE profile_id = $1 AND product_variant_id = $2 + AND platform_attribute_id = 'color'`, + [first.profileId, attributeVariantId], + ), + ); + const missingVariantAttribute = await request( + `/api/product-platform-profiles/${first.profileId}/validation`, + { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }, + ); + assert.ok( + missingVariantAttribute.body.data.variants + .find( + (variant: { variant_id: string }) => + variant.variant_id === attributeVariantId, + ) + .issues.some( + (issue: { code: string; platform_attribute_id?: string }) => + issue.code === 'OZON_ATTRIBUTE_REQUIRED' && + issue.platform_attribute_id === 'color', + ), + ); + await database.workspaceTransaction(workspaceId, (tx) => + tx.query( + `INSERT INTO atlas.product_attributes + (workspace_id, product_id, profile_id, product_variant_id, scope, + platform_attribute_id, complex_id, values, source, confirmation_status) + VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3, 'variant', + 'color', '0', '["black"]'::jsonb, 'manual', 'confirmed')`, + [first.productId, first.profileId, attributeVariantId], + ), + ); + + await database.workspaceTransaction(workspaceId, (tx) => + tx.query( + `DELETE FROM atlas.product_attributes + WHERE profile_id = $1 AND scope = 'common' + AND platform_attribute_id = 'material'`, + [first.profileId], + ), + ); + const missingCommonAttribute = await request( + `/api/product-platform-profiles/${first.profileId}/validation`, + { headers: headers({ 'X-Atlas-Platform-Id': platformId }) }, + ); + assert.ok( + missingCommonAttribute.body.data.profile.issues.some( + (issue: { code: string; platform_attribute_id?: string }) => + issue.code === 'OZON_ATTRIBUTE_REQUIRED' && + issue.platform_attribute_id === 'material', + ), + ); + await database.workspaceTransaction(workspaceId, (tx) => + tx.query( + `INSERT INTO atlas.product_attributes + (workspace_id, product_id, profile_id, product_variant_id, scope, + platform_attribute_id, complex_id, values, source, confirmation_status) + VALUES (current_setting('app.workspace_id')::uuid, $1, $2, NULL, 'common', + 'material', '0', '["cotton"]'::jsonb, 'manual', 'confirmed')`, + [first.productId, first.profileId], + ), + ); + + const invalidScope = { + ...draft, + ai_source_material: afterSave.body.data.source_material, + ai_source_overridden_fields: + afterSave.body.data.source_material_state.overridden_fields, + attributes: afterSave.body.data.attributes.map( + (attribute: any) => ({ + scope: + attribute.platform_attribute_id === 'color' + ? 'common' + : attribute.scope, + variant_id: + attribute.platform_attribute_id === 'color' + ? null + : attribute.variant_id, + platform_attribute_id: attribute.platform_attribute_id, + complex_id: attribute.complex_id, + values: attribute.values, + language_code: attribute.language_code, + source: attribute.source, + confirmation_status: attribute.confirmation_status, + }), + ), + }; + const invalidScopeSave = await request( + `/api/products/${first.productId}/editor-draft`, + { + method: 'PUT', + headers: headers({ + 'X-Atlas-Platform-Id': platformId, + 'Idempotency-Key': randomUUID(), + 'If-Match': `"${afterSave.body.data.product.revision}:${afterSave.body.data.profile.revision}"`, + }), + body: JSON.stringify(invalidScope), + }, + ); + assert.equal(invalidScopeSave.response.status, 422); + assert.equal( + invalidScopeSave.body.error.code, + 'ATTRIBUTE_SCOPE_INVALID', + ); + const categoryChanged = { ...draft, ai_source_material: afterSave.body.data.source_material, @@ -1059,8 +1305,18 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { it('M3.5 按 Ozon 采集层级回填空类目，且绝不覆盖已保存选择', async () => { const suffix = randomUUID(); - const captured = await seedStoreCategory(`m35-source-${suffix}`, 'source-type', 'M3.5 采集叶', 'M3.5 来源 › M3.5 采集叶'); - const manual = await seedStoreCategory(`m35-manual-${suffix}`, 'manual-type', 'M3.5 手动叶', 'M3.5 手动 › M3.5 手动叶'); + const captured = await seedStoreCategory( + `m35-source-${suffix}`, + 'source-type', + 'M3.5 采集叶', + 'M3.5 来源 › M3.5 采集叶', + ); + const manual = await seedStoreCategory( + `m35-manual-${suffix}`, + 'manual-type', + 'M3.5 手动叶', + 'M3.5 手动 › M3.5 手动叶', + ); seededCategoryIds.push(captured.id, manual.id); await database.workspaceTransaction(workspaceId, async (tx) => { await tx.query( @@ -1089,14 +1345,14 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { [first.profileId], ); }); - const resolved = await request(`/api/products/${first.productId}/editor`, { - headers: headers({ 'X-Atlas-Platform-Id': platformId }), - }); - assert.equal(resolved.response.status, 200); - assert.equal( - resolved.body.data.profile.category.id, - captured.id, + const resolved = await request( + `/api/products/${first.productId}/editor`, + { + headers: headers({ 'X-Atlas-Platform-Id': platformId }), + }, ); + assert.equal(resolved.response.status, 200); + assert.equal(resolved.body.data.profile.category.id, captured.id); assert.equal( resolved.body.data.profile.category.source, 'source_capture', @@ -1111,29 +1367,36 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { [manual.id, first.profileId], ), ); - const preserved = await request(`/api/products/${first.productId}/editor`, { - headers: headers({ 'X-Atlas-Platform-Id': platformId }), - }); - assert.equal(preserved.response.status, 200); - assert.equal( - preserved.body.data.profile.category.id, - manual.id, + const preserved = await request( + `/api/products/${first.productId}/editor`, + { + headers: headers({ 'X-Atlas-Platform-Id': platformId }), + }, ); + assert.equal(preserved.response.status, 200); + assert.equal(preserved.body.data.profile.category.id, manual.id); assert.equal(preserved.body.data.profile.category.source, 'manual'); }); it('M3.5 为类目属性和关键词字典搜索创建无密钥 outbox 任务', async () => { const dictionaryId = `m35-dictionary-${randomUUID()}`; - const category = await seedStoreCategory(`m35-category-${randomUUID()}`, 'm35-type', 'M3.5 测试类目', '测试 › M3.5 测试类目'); + const category = await seedStoreCategory( + `m35-category-${randomUUID()}`, + 'm35-type', + 'M3.5 测试类目', + '测试 › M3.5 测试类目', + ); seededCategoryIds.push(category.id); seededDictionaryIds.push(dictionaryId); - await database.workspaceTransaction(workspaceId, (tx) => tx.query( - `INSERT INTO atlas.store_product_category_attributes + await database.workspaceTransaction(workspaceId, (tx) => + tx.query( + `INSERT INTO atlas.store_product_category_attributes (workspace_id, store_id, platform_id, store_product_category_id, platform_attribute_id, name, value_type, is_required, is_collection, max_value_count, dictionary_id, is_aspect) VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3, 'm35-color', 'M3.5 颜色', 'dictionary', false, false, 1, $4, false)`, - [category.storeId, platformId, category.id, dictionaryId], - )); + [category.storeId, platformId, category.id, dictionaryId], + ), + ); await database.workspaceTransaction(workspaceId, async (tx) => { const profile = await tx.query<{ target_store_id: string }>( 'SELECT target_store_id FROM atlas.product_platform_profiles WHERE id = $1', @@ -1164,7 +1427,10 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { }, ); assert.equal(schema.response.status, 202); - assert.equal(schema.body.data.operation.kind, 'store_category_attribute_sync'); + assert.equal( + schema.body.data.operation.kind, + 'store_category_attribute_sync', + ); const dictionary = await request( `/api/product-platform-profiles/${first.profileId}/attribute-dictionaries/${dictionaryId}/syncs?category_id=${category.id}&q=%E9%BB%91%E8%89%B2`, { @@ -1176,74 +1442,107 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { }, ); assert.equal(dictionary.response.status, 202); - assert.equal(dictionary.body.data.operation.kind, 'store_attribute_dictionary_sync'); + assert.equal( + dictionary.body.data.operation.kind, + 'store_attribute_dictionary_sync', + ); + const initialDictionary = await request( + `/api/product-platform-profiles/${first.profileId}/attribute-dictionaries/${dictionaryId}/syncs?category_id=${category.id}`, + { + method: 'POST', + headers: headers({ + 'X-Atlas-Platform-Id': platformId, + 'Idempotency-Key': randomUUID(), + }), + }, + ); + assert.equal(initialDictionary.response.status, 202); await database.workspaceTransaction(workspaceId, async (tx) => { - const events = await tx.query<{ event_type: string; event_payload: unknown }>( + const events = await tx.query<{ + event_type: string; + event_payload: unknown; + }>( `SELECT event_type, event_payload FROM atlas.outbox_events WHERE aggregate_id = $1 AND event_type LIKE 'store_%_sync.requested' ORDER BY created_at`, [first.profileId], ); - assert.equal(events.rows.length, 2); + assert.equal(events.rows.length, 3); assert.deepEqual( - events.rows.map((event) => event.event_type), + events.rows.map((event) => event.event_type).sort(), [ - 'store_category_attribute_sync.requested', 'store_attribute_dictionary_sync.requested', + 'store_attribute_dictionary_sync.requested', + 'store_category_attribute_sync.requested', ], ); assert.ok( events.rows.every( (event) => - !JSON.stringify(event.event_payload).includes('m35-test-ciphertext'), + !JSON.stringify(event.event_payload).includes( + 'm35-test-ciphertext', + ), ), ); }); }); it('M3.6 仅允许当前 SKU 已转存候选作为有序正式素材', async () => { - const before = await request(`/api/products/${first.productId}/editor`, { - headers: headers({ 'X-Atlas-Platform-Id': platformId }), - }); + const before = await request( + `/api/products/${first.productId}/editor`, + { + headers: headers({ 'X-Atlas-Platform-Id': platformId }), + }, + ); const variant = before.body.data.variants[0]; - const asset = await database.workspaceTransaction(workspaceId, async (tx) => { - const created = await tx.query<{ id: string }>( - `INSERT INTO atlas.media_assets + const asset = await database.workspaceTransaction( + workspaceId, + async (tx) => { + const created = await tx.query<{ id: string }>( + `INSERT INTO atlas.media_assets (workspace_id, storage_provider, bucket, object_key, content_type, byte_size, checksum_sha256, width_px, height_px) VALUES (current_setting('app.workspace_id')::uuid, 'test', 'test', $1, 'image/jpeg', 1024, $2, 1200, 900) RETURNING id`, - [`m36/${randomUUID()}.jpg`, randomUUID().replaceAll('-', '')], - ); - const snapshot = await tx.query<{ source_snapshot_revision: string }>( - `SELECT source_snapshot_revision::text FROM atlas.collection_items WHERE id = $1`, - [first.collectionItemId], - ); - await tx.query( - `INSERT INTO atlas.collection_asset_transfers + [ + `m36/${randomUUID()}.jpg`, + randomUUID().replaceAll('-', ''), + ], + ); + const snapshot = await tx.query<{ + source_snapshot_revision: string; + }>( + `SELECT source_snapshot_revision::text FROM atlas.collection_items WHERE id = $1`, + [first.collectionItemId], + ); + await tx.query( + `INSERT INTO atlas.collection_asset_transfers (workspace_id, collection_item_id, product_id, source_variant_id, role, source_url, status, asset_id, source_snapshot_revision, completed_at) VALUES (current_setting('app.workspace_id')::uuid, $1, $2, $3, 'source_sku', 'https://example.test/m36.jpg', 'succeeded', $4, $5, now())`, - [ - first.collectionItemId, - first.productId, - variant.id, - created.rows[0].id, - snapshot.rows[0].source_snapshot_revision, - ], - ); - return created.rows[0].id; - }); + [ + first.collectionItemId, + first.productId, + variant.id, + created.rows[0].id, + snapshot.rows[0].source_snapshot_revision, + ], + ); + return created.rows[0].id; + }, + ); const payload = { ai_source_material: before.body.data.source_material, ai_source_overridden_fields: before.body.data.source_material_state.overridden_fields, common: { ...before.body.data.product.common, - default_physical_spec: before.body.data.product.default_physical_spec, - default_package_spec: before.body.data.product.default_package_spec, + default_physical_spec: + before.body.data.product.default_physical_spec, + default_package_spec: + before.body.data.product.default_package_spec, }, profile: { target_store_id: before.body.data.profile.target_store.id, @@ -1278,19 +1577,25 @@ describe('商品编辑 M3.0–M3.3 HTTP 集成测试', () => { media_asset_ids: item.id === variant.id ? [asset] : [], })), }; - const saved = await request(`/api/products/${first.productId}/editor-draft`, { - method: 'PUT', - headers: headers({ - 'X-Atlas-Platform-Id': platformId, - 'Idempotency-Key': randomUUID(), - 'If-Match': `"${before.body.data.product.revision}:${before.body.data.profile.revision}"`, - }), - body: JSON.stringify(payload), - }); + const saved = await request( + `/api/products/${first.productId}/editor-draft`, + { + method: 'PUT', + headers: headers({ + 'X-Atlas-Platform-Id': platformId, + 'Idempotency-Key': randomUUID(), + 'If-Match': `"${before.body.data.product.revision}:${before.body.data.profile.revision}"`, + }), + body: JSON.stringify(payload), + }, + ); assert.equal(saved.response.status, 200); const after = await request(`/api/products/${first.productId}/editor`, { headers: headers({ 'X-Atlas-Platform-Id': platformId }), }); - assert.deepEqual(after.body.data.variants[0].media.map((item: any) => item.asset_id), [asset]); + assert.deepEqual( + after.body.data.variants[0].media.map((item: any) => item.asset_id), + [asset], + ); }); }); diff --git a/apps/web/src/layouts/MainLayout.tsx b/apps/web/src/layouts/MainLayout.tsx index 96077f9..169406f 100644 --- a/apps/web/src/layouts/MainLayout.tsx +++ b/apps/web/src/layouts/MainLayout.tsx @@ -9,12 +9,14 @@ import { MenuUnfoldOutlined, RightOutlined, UserOutlined, + SafetyCertificateOutlined, } from '@ant-design/icons'; import SidebarMenu from './SidebarMenu'; import PlatformSelector from './PlatformSelector'; import { getBreadcrumbItems } from './menuConfig'; import { useSession } from '@/services/session'; import './MainLayout.css'; +import { useSystemAdminAccess } from '@/services/useSystemAdminAccess'; const { Header, Sider, Content } = Layout; @@ -26,6 +28,7 @@ const MainLayout = () => { const location = useLocation(); const navigate = useNavigate(); const { session, logout } = useSession(); + const systemAdminAccess = useSystemAdminAccess(); const breadcrumbItems = useMemo( () => @@ -60,12 +63,17 @@ const MainLayout = () => { navigate('/settings/password'); } else if (key === 'logout') { void handleLogout(); + } else if (key === 'system') { + navigate('/system/platform-catalog'); } }; const userMenuItems: MenuProps['items'] = [ { key: 'profile', icon: , label: '修改资料' }, { key: 'password', icon: , label: '修改密码' }, + ...(systemAdminAccess === 'allowed' + ? [{ key: 'system', icon: , label: '系统管理' }] + : []), { type: 'divider' }, { key: 'logout', diff --git a/apps/web/src/layouts/SystemAdminLayout.css b/apps/web/src/layouts/SystemAdminLayout.css new file mode 100644 index 0000000..a88a3bd --- /dev/null +++ b/apps/web/src/layouts/SystemAdminLayout.css @@ -0,0 +1,47 @@ +.system-admin-gate { + min-height: 100vh; + display: grid; + place-items: center; +} + +.system-admin-layout { + min-height: 100vh; +} + +.system-admin-sider { + background: var(--sider-bg) !important; +} + +.system-admin-brand { + color: #fff; + font-size: 17px; + font-weight: 700; + padding: 20px 18px; + border-bottom: 1px solid rgba(255, 255, 255, 0.14); +} + +.system-admin-sider .ant-menu { + background: transparent; +} + +.system-admin-header { + height: 56px; + line-height: 1; + padding: 0 24px; + background: #fff; + display: flex; + align-items: center; + justify-content: space-between; + border-bottom: 1px solid var(--border-color); + font-weight: 600; +} + +.system-admin-content { + padding: 24px; + background: var(--bg-color); +} + +@media (max-width: 768px) { + .system-admin-content { padding: 12px; } + .system-admin-header { padding: 0 12px; } +} diff --git a/apps/web/src/layouts/SystemAdminLayout.tsx b/apps/web/src/layouts/SystemAdminLayout.tsx new file mode 100644 index 0000000..8078690 --- /dev/null +++ b/apps/web/src/layouts/SystemAdminLayout.tsx @@ -0,0 +1,52 @@ +import { Button, Layout, Menu, Result, Spin } from 'antd'; +import { AppstoreOutlined, ArrowLeftOutlined, DatabaseOutlined } from '@ant-design/icons'; +import { Outlet, useLocation, useNavigate } from 'react-router-dom'; +import { useSystemAdminAccess } from '@/services/useSystemAdminAccess'; +import './SystemAdminLayout.css'; + +const { Sider, Header, Content } = Layout; + +/** 全局后台与租户工作台分离，避免页头平台/门店上下文影响系统级操作。 */ +export default function SystemAdminLayout() { + const access = useSystemAdminAccess(); + const location = useLocation(); + const navigate = useNavigate(); + if (access === 'checking') { + return
; + } + if (access === 'denied') { + return navigate('/online-products')}>返回工作台 + } />; + } + return ( + + +
+ Atlas 系统管理 +
+ , + label: '平台类目与属性', + }]} + onClick={({ key }) => navigate(key)} + /> + + +
+ 系统管理 / 平台类目与属性 + +
+ + + + ); +} diff --git a/apps/web/src/pages/products/ProductEditPage.css b/apps/web/src/pages/products/ProductEditPage.css index e7d3b96..6ef96c8 100644 --- a/apps/web/src/pages/products/ProductEditPage.css +++ b/apps/web/src/pages/products/ProductEditPage.css @@ -87,7 +87,7 @@ } /* - * 01 / 02 / 04 共用的横向表单：Label 与控件列作为最大 780px 的整体居中。 + * 01 / 02 / 04 共用的横向表单：Label 与控件列作为最大 850px 的整体居中。 * 宽度充足时控件不超过 680px；卡片变窄时先吃掉两侧留白，再收缩控件列。 * 容器查询以卡片实际宽度为准，不受左侧菜单或采集面板布局的间接影响。 */ @@ -99,18 +99,18 @@ min-width: 0; } .editor-horizontal-section .ant-form-item-label { - flex: 0 0 100px !important; - max-width: 100px !important; + flex: 0 0 170px !important; + max-width: 170px !important; } .editor-horizontal-section .ant-form-item-control { - flex: 0 1 min(680px, calc(100% - 100px)) !important; + flex: 0 1 min(680px, calc(100% - 170px)) !important; width: auto; - max-width: min(680px, calc(100% - 100px)) !important; + max-width: min(680px, calc(100% - 170px)) !important; min-width: 0; } /* - * 100px 标签列与包装尺寸输入组在 480px 以下已没有足够可读空间；此时才 + * 170px 标签列与包装尺寸输入组在 480px 以下已没有足够可读空间；此时才 * 切换为纵向表单。该断点读取卡片宽度，非浏览器窗口宽度。 */ @container (max-width: 479px) { diff --git a/apps/web/src/pages/products/ProductEditPage.tsx b/apps/web/src/pages/products/ProductEditPage.tsx index 716e565..d6cf53e 100644 --- a/apps/web/src/pages/products/ProductEditPage.tsx +++ b/apps/web/src/pages/products/ProductEditPage.tsx @@ -46,6 +46,7 @@ function missingAttributeDrafts( ) { const missing: AttributeDraft[] = []; for (const definition of schema) { + if (definition.editor_field) continue; const scopes = definition.is_aspect ? snapshot.variants.map((variant) => ({ scope: 'variant' as const, @@ -236,9 +237,8 @@ function normalizedValues(values: EditorFormValues): EditorFormValues { description: nullable(values.profile.description), tags: values.profile.tags.map((tag) => tag.trim()).filter(Boolean), }, - // Schema fields are rendered eagerly so the user can fill them immediately. - // Do not persist untouched optional fields: the API correctly requires every - // stored attribute to contain at least one non-empty value. + // schema 字段会预先加入表单供用户直接填写；未触碰的空选填项不落库， + // 因为服务端要求每条已提交属性至少包含一个非空值。 attributes: (values.attributes ?? []).flatMap((attribute) => { const attributeValues = attribute.values.map((value) => value.trim()).filter(Boolean); return attributeValues.length ? [{ ...attribute, values: attributeValues }] : []; @@ -376,7 +376,7 @@ const ProductEditPage = () => { const [categoryOptions, setCategoryOptions] = useState([]); const [categoryOptionsLoading, setCategoryOptionsLoading] = useState(false); const [categorySearch, setCategorySearch] = useState(''); - // 类目属性 schema 与字典值：仅在展开"更多特征"后按需加载。 + // 类目属性 schema 与字典值：选定类目后加载，必填属性始终展示。 const [attributeSchema, setAttributeSchema] = useState([]); const [attributeSchemaCategoryId, setAttributeSchemaCategoryId] = useState(null); const [attributeSchemaCatalogRefresh, setAttributeSchemaCatalogRefresh] = useState< @@ -387,8 +387,16 @@ const ProductEditPage = () => { const [dictionaryValues, setDictionaryValues] = useState< Record >({}); + const [dictionaryCursors, setDictionaryCursors] = useState>({}); + const dictionaryQueries = useRef>({}); + const dictionaryInitialSyncs = useRef(new Set()); + const dictionaryPageLoads = useRef(new Set()); + const dictionaryContext = `${snapshot?.profile.id ?? ''}:${selectedStoreId ?? ''}:${selectedCategoryId ?? ''}`; + const dictionaryContextRef = useRef(dictionaryContext); + dictionaryContextRef.current = dictionaryContext; const [catalogRefresh, setCatalogRefresh] = useState(0); const [catalogSyncing, setCatalogSyncing] = useState(null); + const catalogSyncToken = useRef(null); const [loading, setLoading] = useState(true); const [saving, setSaving] = useState(false); const [materializingTransferId, setMaterializingTransferId] = useState(null); @@ -412,6 +420,11 @@ const ProductEditPage = () => { : ([] as ProductAttributeSchema[]), [attributeSchema, attributeSchemaCategoryId, selectedCategoryId] ); + // 已由编辑器内建控件承载的 Ozon 属性不再重复展示或加载字典。 + const editableAttributeSchema = useMemo( + () => activeAttributeSchema.filter((attribute) => !attribute.editor_field), + [activeAttributeSchema] + ); /** 拉取编辑器快照并重置表单；保存成功或冲突后也会调用，以合并服务端最新状态。 */ const load = useCallback(async () => { @@ -460,8 +473,14 @@ const ProductEditPage = () => { active = false; }; }, [catalogRefresh, currentPlatform, selectedStoreId, snapshot]); - // 属性 schema：展开"更多特征"时才加载，同一类目与刷新版本只请求一次； - // 未选中类目时清空全部属性相关状态。 + // 切换店铺或类目后，不复用旧类目的字典搜索、游标和自动同步记录。 + useEffect(() => { + dictionaryQueries.current = {}; + dictionaryInitialSyncs.current.clear(); + dictionaryPageLoads.current.clear(); + setDictionaryCursors({}); + }, [selectedCategoryId, selectedStoreId, snapshot?.profile.id]); + // 属性 schema：同一类目与刷新版本只请求一次；未选中类目时清空相关状态。 useEffect(() => { if (!snapshot || !currentPlatform || !selectedCategoryId) { setAttributeSchema([]); @@ -470,14 +489,12 @@ const ProductEditPage = () => { setAttributeSchemaLoading(false); setAttributeSchemaError(null); setDictionaryValues({}); + setDictionaryCursors({}); return; } - // Attributes are an on-demand panel. Once loaded for the selected - // category, collapsing and reopening it must reuse the same schema. if ( - !moreFeaturesExpanded || - (attributeSchemaCategoryId === selectedCategoryId && - attributeSchemaCatalogRefresh === catalogRefresh) + attributeSchemaCategoryId === selectedCategoryId && + attributeSchemaCatalogRefresh === catalogRefresh ) return; let active = true; @@ -486,6 +503,7 @@ const ProductEditPage = () => { setAttributeSchema([]); setAttributeSchemaCategoryId(null); setDictionaryValues({}); + setDictionaryCursors({}); void productEditorApi .attributeSchema( snapshot.profile.id, @@ -525,7 +543,6 @@ const ProductEditPage = () => { catalogRefresh, currentPlatform, form, - moreFeaturesExpanded, selectedCategoryId, selectedStoreId, snapshot, @@ -535,13 +552,14 @@ const ProductEditPage = () => { if (!snapshot || !currentPlatform || !selectedCategoryId) return; const dictionaryIds = [ ...new Set( - activeAttributeSchema + editableAttributeSchema .map((attribute) => attribute.dictionary_id) .filter((dictionaryId): dictionaryId is string => !!dictionaryId) ), ]; if (!dictionaryIds.length) { setDictionaryValues({}); + setDictionaryCursors({}); return; } let active = true; @@ -563,20 +581,36 @@ const ProductEditPage = () => { ) .then((results) => { if (!active) return; - setDictionaryValues( - Object.fromEntries(results.map(([id, page]) => [id, page.items])) + setDictionaryValues((current) => + Object.fromEntries( + results.map(([id, page]) => [ + id, + dictionaryQueries.current[id] ? (current[id] ?? []) : page.items, + ]) + ) + ); + setDictionaryCursors((current) => + Object.fromEntries( + results.map(([id, page]) => [ + id, + dictionaryQueries.current[id] ? (current[id] ?? null) : page.next_cursor, + ]) + ) ); }) .catch(() => { - if (active) setDictionaryValues({}); + if (active) { + setDictionaryValues({}); + setDictionaryCursors({}); + } }); return () => { active = false; }; }, [ - activeAttributeSchema, catalogRefresh, currentPlatform, + editableAttributeSchema, selectedCategoryId, selectedStoreId, snapshot, @@ -773,19 +807,23 @@ const ProductEditPage = () => { } return null; }; - /** 发起一次 Ozon 目录同步并跟踪其异步 operation；成功后递增 catalogRefresh 触发缓存重拉。 */ + /** 跟踪 Ozon 目录同步；schema 成功后刷新目录，字典只重读对应选项。 */ const runCatalogSync = async ( syncKey: string, action: () => Promise<{ operation: { id: string } }>, - successMessage: string + successMessage: string | null, + refreshCatalog = true ) => { + const token = Symbol(syncKey); + catalogSyncToken.current = token; setCatalogSyncing(syncKey); try { const queued = await action(); const completed = await waitForCatalogOperation(queued.operation.id); if (completed?.status === 'succeeded') { - message.success(successMessage); - setCatalogRefresh((version) => version + 1); + if (successMessage) message.success(successMessage); + if (refreshCatalog) setCatalogRefresh((version) => version + 1); + return true; } else if (completed?.status === 'failed') { message.error(completed.error?.message ?? 'Ozon 同步失败，请稍后重试'); } else if (completed?.status === 'cancelled') { @@ -796,8 +834,12 @@ const ProductEditPage = () => { } catch (error) { message.error(apiErrorMessage(error)); } finally { - setCatalogSyncing(null); + if (catalogSyncToken.current === token) { + catalogSyncToken.current = null; + setCatalogSyncing(null); + } } + return false; }; const syncAttributeSchema = () => { if (!snapshot || !currentPlatform || !selectedCategoryId) return; @@ -812,25 +854,51 @@ const ProductEditPage = () => { '该类目的属性已同步' ); }; - const loadDictionaryValues = async (dictionaryId: string, query = '') => { + const loadDictionaryValues = async (dictionaryId: string, query = '', cursor?: string) => { if (!snapshot || !currentPlatform || !selectedCategoryId) return; - const page = await productEditorApi.attributeDictionary( - snapshot.profile.id, - currentPlatform.id, - dictionaryId, - query, - selectedCategoryId, - selectedStoreId - ); - setDictionaryValues((current) => ({ ...current, [dictionaryId]: page.items })); - }; - const syncDictionaryValues = (dictionaryId: string, query: string) => { - if (!snapshot || !currentPlatform || !selectedCategoryId) return; - if (query.length < 2) { - message.info('请输入至少 2 个字符后再从 Ozon 搜索'); - return; + const requestContext = dictionaryContext; + const requestKey = `${requestContext}:${dictionaryId}:${query}:${cursor ?? ''}`; + if (dictionaryPageLoads.current.has(requestKey)) return; + dictionaryPageLoads.current.add(requestKey); + if (!cursor) dictionaryQueries.current[dictionaryId] = query; + try { + const page = await productEditorApi.attributeDictionary( + snapshot.profile.id, + currentPlatform.id, + dictionaryId, + query, + selectedCategoryId, + selectedStoreId, + cursor + ); + if ( + dictionaryContextRef.current !== requestContext || + dictionaryQueries.current[dictionaryId] !== query + ) return; + setDictionaryValues((current) => ({ + ...current, + [dictionaryId]: cursor + ? [...(current[dictionaryId] ?? []), ...page.items].filter( + (value, index, all) => + all.findIndex((item) => item.value_id === value.value_id) === index + ) + : page.items, + })); + setDictionaryCursors((current) => ({ + ...current, + [dictionaryId]: page.next_cursor, + })); + } catch (error) { + message.error(apiErrorMessage(error)); + } finally { + dictionaryPageLoads.current.delete(requestKey); } - void runCatalogSync( + }; + const syncDictionaryValues = async (dictionaryId: string, query: string) => { + if (!snapshot || !currentPlatform || !selectedCategoryId || query.length === 1) + return false; + const requestContext = dictionaryContext; + const succeeded = await runCatalogSync( `dictionary:${dictionaryId}:${query}`, () => productEditorApi.syncAttributeDictionary( @@ -840,8 +908,28 @@ const ProductEditPage = () => { selectedCategoryId, query ), - '字典值已同步' - ).then(() => void loadDictionaryValues(dictionaryId, query)); + null, + false + ); + if ( + succeeded && dictionaryContextRef.current === requestContext && + dictionaryQueries.current[dictionaryId] === query + ) void loadDictionaryValues(dictionaryId, query); + return succeeded; + }; + const openDictionaryValues = (dictionaryId: string) => { + void loadDictionaryValues(dictionaryId, ''); + if (dictionaryInitialSyncs.current.has(dictionaryId)) return; + dictionaryInitialSyncs.current.add(dictionaryId); + const requestContext = dictionaryContext; + void syncDictionaryValues(dictionaryId, '').then((succeeded) => { + if (!succeeded && dictionaryContextRef.current === requestContext) + dictionaryInitialSyncs.current.delete(dictionaryId); + }); + }; + const loadMoreDictionaryValues = (dictionaryId: string, query: string) => { + const cursor = dictionaryCursors[dictionaryId]; + if (cursor) void loadDictionaryValues(dictionaryId, query, cursor); }; /** 把采集素材转存为可引用资产；完成后刷新采集证据，让对应 SKU 的图片立即可选。 */ const materializeCandidate = async (transferId: string) => { @@ -956,6 +1044,8 @@ const ProductEditPage = () => { void loadDictionaryValues(dictionaryId, query) } onSyncDictionaryValues={syncDictionaryValues} + onOpenDictionaryValues={openDictionaryValues} + onLoadMoreDictionaryValues={loadMoreDictionaryValues} onSyncAttributeSchema={syncAttributeSchema} /> @@ -964,7 +1054,16 @@ const ProductEditPage = () => { snapshot={snapshot} collectionRecord={collectionRecord} materializingTransferId={materializingTransferId} + activeAttributeSchema={activeAttributeSchema} + catalogSyncing={catalogSyncing} + dictionaryValues={dictionaryValues} onMaterialize={materializeCandidate} + onLoadDictionaryValues={(dictionaryId, query) => + void loadDictionaryValues(dictionaryId, query) + } + onSyncDictionaryValues={syncDictionaryValues} + onOpenDictionaryValues={openDictionaryValues} + onLoadMoreDictionaryValues={loadMoreDictionaryValues} onDirty={() => setDirty(true)} /> diff --git a/apps/web/src/pages/products/components/DynamicAttributeFields.tsx b/apps/web/src/pages/products/components/DynamicAttributeFields.tsx new file mode 100644 index 0000000..59c277c --- /dev/null +++ b/apps/web/src/pages/products/components/DynamicAttributeFields.tsx @@ -0,0 +1,230 @@ +import { useEffect, useRef, useState } from 'react'; +import { Button, Form, Input, Select, Typography } from 'antd'; +import type { FormInstance } from 'antd'; +import type { + ProductAttributeDictionaryValue, + ProductAttributeSchema, + SaveProductEditorDraftRequest, +} from '@atlas/contracts'; + +type EditorFormValues = SaveProductEditorDraftRequest; +type AttributeDraft = NonNullable[number]; +type NamePath = Array; + +type Props = { + form: FormInstance; + definitions: ProductAttributeSchema[]; + scope: 'common' | 'variant'; + variantId: string | null; + dictionaryValues: Record; + catalogSyncing: string | null; + onLoadDictionaryValues: (dictionaryId: string, query: string) => void; + onSyncDictionaryValues: (dictionaryId: string, query: string) => void; + onOpenDictionaryValues: (dictionaryId: string) => void; + onLoadMoreDictionaryValues: (dictionaryId: string, query: string) => void; + emptyText?: string; +}; + +/** 根据 schema 与归属找到顶层属性草稿的稳定数组位置。 */ +function attributeIndex( + attributes: AttributeDraft[], + definition: ProductAttributeSchema, + scope: Props['scope'], + variantId: string | null +) { + return attributes.findIndex( + (attribute) => + attribute.scope === scope && + attribute.variant_id === variantId && + attribute.platform_attribute_id === definition.platform_attribute_id && + attribute.complex_id === definition.complex_id + ); +} + +/** 渲染一个平台属性控件；必填星号只表达上架要求，不阻止保存草稿。 */ +function DynamicAttributeField({ + definition, + index, + dictionaryValues, + catalogSyncing, + onLoadDictionaryValues, + onSyncDictionaryValues, + onOpenDictionaryValues, + onLoadMoreDictionaryValues, +}: { + definition: ProductAttributeSchema; + index: number; + dictionaryValues: Props['dictionaryValues']; + catalogSyncing: string | null; + onLoadDictionaryValues: Props['onLoadDictionaryValues']; + onSyncDictionaryValues: Props['onSyncDictionaryValues']; + onOpenDictionaryValues: Props['onOpenDictionaryValues']; + onLoadMoreDictionaryValues: Props['onLoadMoreDictionaryValues']; +}) { + const [dictionaryQuery, setDictionaryQuery] = useState(''); + const onSyncRef = useRef(onSyncDictionaryValues); + onSyncRef.current = onSyncDictionaryValues; + useEffect(() => setDictionaryQuery(''), [definition.dictionary_id]); + useEffect(() => { + if (!definition.dictionary_id || dictionaryQuery.trim().length < 2) return; + const timer = window.setTimeout( + () => onSyncRef.current(definition.dictionary_id!, dictionaryQuery.trim()), + 400 + ); + return () => window.clearTimeout(timer); + }, [definition.dictionary_id, dictionaryQuery]); + + const valueName = ['attributes', index, 'values'] as NamePath; + const scalarValueName = [...valueName, 0] as NamePath; + const dictionaryOptions = definition.dictionary_id + ? (dictionaryValues[definition.dictionary_id] ?? []).map((value) => ({ + value: value.value_id, + label: value.value, + })) + : []; + + const input = + definition.value_type === 'dictionary' ? ( + + + + ) : definition.is_collection ? ( + + + + ); + + return ( + +
{input}
+ + ); +} + +/** 在产品或指定 SKU 的上下文中渲染一组动态属性。 */ +export function DynamicAttributeFields({ + form, + definitions, + scope, + variantId, + dictionaryValues, + catalogSyncing, + onLoadDictionaryValues, + onSyncDictionaryValues, + onOpenDictionaryValues, + onLoadMoreDictionaryValues, + emptyText, +}: Props) { + const attributes = (form.getFieldValue('attributes') ?? []) as AttributeDraft[]; + const fields = definitions.flatMap((definition) => { + const index = attributeIndex(attributes, definition, scope, variantId); + return index < 0 ? [] : [{ definition, index }]; + }); + + if (!fields.length) + return emptyText ? {emptyText} : null; + + return ( +
+ {fields.map(({ definition, index }) => ( + + ))} +
+ ); +} diff --git a/apps/web/src/pages/products/components/ProductAttributeSection.css b/apps/web/src/pages/products/components/ProductAttributeSection.css index 0bfdd36..079e417 100644 --- a/apps/web/src/pages/products/components/ProductAttributeSection.css +++ b/apps/web/src/pages/products/components/ProductAttributeSection.css @@ -34,9 +34,28 @@ display: grid; grid-template-columns: 1fr; } -.dynamic-attribute-item .ant-space-compact { +/* Ozon 属性名可能很长：Label 使用常规字重并完整换行，不能省略或裁切。 */ +.product-editor .editor-section .dynamic-attribute-item .ant-form-item-label { + height: auto; + overflow: visible; + text-align: right; + white-space: normal; +} +.product-editor .editor-section .dynamic-attribute-item .ant-form-item-label > label { + width: 100%; + height: auto; + align-items: flex-start; + justify-content: flex-end; + overflow: visible; + font-weight: 400; + line-height: 22px; + text-align: right; + text-overflow: clip; + white-space: normal; + word-break: break-word; +} +.dynamic-attribute-control, +.dynamic-attribute-control .ant-select, +.dynamic-attribute-control .ant-input { width: 100%; } -.dynamic-attribute-item .ant-btn-dangerous.ant-btn-text { - min-width: 56px; -} diff --git a/apps/web/src/pages/products/components/ProductAttributeSection.tsx b/apps/web/src/pages/products/components/ProductAttributeSection.tsx index 2bbcf55..4893720 100644 --- a/apps/web/src/pages/products/components/ProductAttributeSection.tsx +++ b/apps/web/src/pages/products/components/ProductAttributeSection.tsx @@ -1,4 +1,4 @@ -import { useEffect, useState } from 'react'; +import { useMemo, useState } from 'react'; import { Alert, Button, Card, Empty, Form, Input, Select, Space, Spin, Typography } from 'antd'; import type { FormInstance } from 'antd'; import { EditOutlined } from '@ant-design/icons'; @@ -9,12 +9,10 @@ import type { SaveProductEditorDraftRequest, } from '@atlas/contracts'; import { SectionTitle } from './SectionTitle'; +import { DynamicAttributeFields } from './DynamicAttributeFields'; import './ProductAttributeSection.css'; type EditorFormValues = SaveProductEditorDraftRequest; -type AttributeDraft = NonNullable[number]; -type NamePath = Array; - /** 把属性值（字符串/数组/对象）格式化为可读文本，用于旧类目属性提示。 */ function sourceValue(value: unknown): string { if (typeof value === 'string') return value || '—'; @@ -36,6 +34,8 @@ type Props = { dictionaryValues: Record; onLoadDictionaryValues: (dictionaryId: string, query: string) => void; onSyncDictionaryValues: (dictionaryId: string, query: string) => void; + onOpenDictionaryValues: (dictionaryId: string) => void; + onLoadMoreDictionaryValues: (dictionaryId: string, query: string) => void; onSyncAttributeSchema: () => void; }; @@ -59,15 +59,27 @@ export function ProductAttributeSection({ dictionaryValues, onLoadDictionaryValues, onSyncDictionaryValues, + onOpenDictionaryValues, + onLoadMoreDictionaryValues, onSyncAttributeSchema, }: Props) { // 富内容本地草稿：富内容能力接入前不写入表单、不随草稿保存。 const [richContent, setRichContent] = useState(''); - // 各字典下拉框的当前搜索词（仅本地状态）；切换类目时清空，避免残留到新类目。 - const [dictionarySearches, setDictionarySearches] = useState>({}); - useEffect(() => { - setDictionarySearches({}); - }, [selectedCategoryId]); + const commonDefinitions = useMemo( + () => + activeAttributeSchema.filter( + (definition) => !definition.is_aspect && !definition.editor_field + ), + [activeAttributeSchema] + ); + const requiredDefinitions = useMemo( + () => commonDefinitions.filter((definition) => definition.is_required), + [commonDefinitions] + ); + const optionalDefinitions = useMemo( + () => commonDefinitions.filter((definition) => !definition.is_required), + [commonDefinitions] + ); return (
- 更多特征 + Ozon 类目属性 - 根据所选类目填写 Ozon 平台属性 + 根据所选类目填写商品级平台属性；变体属性在对应 SKU 中填写
- + {optionalDefinitions.length > 0 && ( + + )}
- {expanded && - (!selectedCategoryId ? ( - - ) : attributeSchemaLoading ? ( -
- - 正在读取类目属性… -
- ) : !activeAttributeSchema.length ? ( - - - {attributeSchemaError ?? '该类目的属性 schema 尚未同步'} - - - + {!selectedCategoryId ? ( + + ) : attributeSchemaLoading ? ( +
+ + 正在读取类目属性… +
+ ) : !activeAttributeSchema.length ? ( + + + {attributeSchemaError ?? '该类目的属性 schema 尚未同步'} + + + + } + /> + ) : ( + + - ) : ( - - {(fields) => ( -
- {activeAttributeSchema.flatMap((definition) => { - // aspect（变体维度）属性按每个 SKU 展开一行，其余类目级一行。 - const scopes = definition.is_aspect - ? snapshot.variants.map((variant) => ({ - scope: 'variant' as const, - variantId: variant.id, - suffix: variant.display_name || '未命名 SKU', - })) - : [ - { - scope: 'common' as const, - variantId: null, - suffix: null, - }, - ]; - return scopes.map(({ scope, variantId, suffix }) => { - const field = fields.find((candidate) => { - const draft = form.getFieldValue([ - 'attributes', - candidate.name, - ]) as AttributeDraft | undefined; - return ( - draft?.scope === scope && - draft?.variant_id === variantId && - draft?.platform_attribute_id === - definition.platform_attribute_id && - draft?.complex_id === definition.complex_id - ); - }); - const label = suffix - ? `${definition.name} · ${suffix}` - : definition.name; - // Attribute rows are created together with - // the schema response. A transient render - // may still occur before Form.List receives - // the new field metadata. - if (!field) return null; - // 字典属性：选项来自页面预取的字典缓存；搜索时经 - // onLoadDictionaryValues 远程过滤，无结果时可通过 - // notFoundContent 的按钮发起 Ozon 同步。 - const dictionaryOptions = definition.dictionary_id - ? ( - dictionaryValues[definition.dictionary_id] ?? - [] - ).map((value) => ({ - value: value.value_id, - label: value.value, - })) - : []; - const dictionaryQuery = definition.dictionary_id - ? (dictionarySearches[definition.dictionary_id] ?? - '') - : ''; - const valueName = [field.name, 'values'] as NamePath; - const scalarValueName = [...valueName, 0] as NamePath; - const valueRules = definition.is_required - ? [ - { - validator: ( - _rule: unknown, - value: unknown - ) => { - const entries = Array.isArray(value) - ? value - : [value]; - return entries.some( - (entry) => - typeof entry === 'string' && - entry.trim() - ) - ? Promise.resolve() - : Promise.reject( - new Error( - `请填写${definition.name}` - ) - ); - }, - }, - ] - : undefined; - const input = - definition.value_type === 'dictionary' ? ( - - - - ) : definition.is_collection ? ( - - - - ); - return ( - - - {input} - - - - ); - }); - })} -
- )} - - ))} + {expanded && optionalDefinitions.length > 0 && ( + + )} + + )} {/* 切换类目后无法映射到新 schema 的旧属性：仅提示，不参与保存 */} {snapshot.unmapped_attributes.length > 0 && ( diff --git a/apps/web/src/pages/products/components/ProductMainInfoSection.tsx b/apps/web/src/pages/products/components/ProductMainInfoSection.tsx index c4b9ce7..92dd87c 100644 --- a/apps/web/src/pages/products/components/ProductMainInfoSection.tsx +++ b/apps/web/src/pages/products/components/ProductMainInfoSection.tsx @@ -15,11 +15,7 @@ type CategoryOption = { function PackageFields({ name }: { name: NamePath }) { return (
- + diff --git a/apps/web/src/pages/products/components/ProductVariantSection.css b/apps/web/src/pages/products/components/ProductVariantSection.css index 910dca6..e56c51a 100644 --- a/apps/web/src/pages/products/components/ProductVariantSection.css +++ b/apps/web/src/pages/products/components/ProductVariantSection.css @@ -148,6 +148,32 @@ text-overflow: ellipsis; white-space: nowrap; } + +/* Ozon 变体属性与 SKU 摘要同属卡片主体；必填项在折叠状态下也始终可见。 */ +.sku-attribute-panel { + margin-top: 12px; + padding: 12px 0 0 87px; + border-top: 1px solid #f0edf3; +} +.sku-attribute-panel h5.ant-typography { + margin: 0 0 10px; + font-size: 15px; +} +.sku-attribute-panel .ant-form-item { + margin-bottom: 10px; +} +.sku-attribute-panel .ant-form-item-label { + flex: 0 0 120px !important; + text-align: left; +} +.sku-attribute-panel .ant-form-item-label > label { + justify-content: flex-start; +} +.sku-card-expanded .sku-attribute-panel--optional { + margin: 0; + padding: 0; + border: 0; +} .sku-card-value strong { min-height: 32px; padding-top: 5px; @@ -314,6 +340,9 @@ } @media (max-width: 560px) { + .sku-attribute-panel { + padding-left: 0; + } .sku-inline-dimensions { grid-template-columns: 1fr; } diff --git a/apps/web/src/pages/products/components/ProductVariantSection.tsx b/apps/web/src/pages/products/components/ProductVariantSection.tsx index 1053695..9c73c2c 100644 --- a/apps/web/src/pages/products/components/ProductVariantSection.tsx +++ b/apps/web/src/pages/products/components/ProductVariantSection.tsx @@ -4,10 +4,13 @@ import type { FormInstance } from 'antd'; import { CopyOutlined, DeleteOutlined, DownOutlined, PlusOutlined } from '@ant-design/icons'; import type { CollectionItemInspection, + ProductAttributeDictionaryValue, + ProductAttributeSchema, ProductEditorSnapshot, SaveProductEditorDraftRequest, } from '@atlas/contracts'; import { SectionTitle } from './SectionTitle'; +import { DynamicAttributeFields } from './DynamicAttributeFields'; import './ProductVariantSection.css'; type EditorFormValues = SaveProductEditorDraftRequest; @@ -82,7 +85,14 @@ type Props = { snapshot: ProductEditorSnapshot; collectionRecord: CollectionItemInspection | null; materializingTransferId: string | null; + activeAttributeSchema: ProductAttributeSchema[]; + catalogSyncing: string | null; + dictionaryValues: Record; onMaterialize: (transferId: string) => void; + onLoadDictionaryValues: (dictionaryId: string, query: string) => void; + onSyncDictionaryValues: (dictionaryId: string, query: string) => void; + onOpenDictionaryValues: (dictionaryId: string) => void; + onLoadMoreDictionaryValues: (dictionaryId: string, query: string) => void; onDirty: () => void; }; @@ -98,13 +108,26 @@ export function ProductVariantSection({ snapshot, collectionRecord, materializingTransferId, + activeAttributeSchema, + catalogSyncing, + dictionaryValues, onMaterialize, + onLoadDictionaryValues, + onSyncDictionaryValues, + onOpenDictionaryValues, + onLoadMoreDictionaryValues, onDirty, }: Props) { // 实时监听变体草稿：驱动主图回显与候选图片的选中态。 const draftVariants = (Form.useWatch('variants', form) ?? []) as VariantValues[]; // 展开状态按 Form.List 的 field.key（而非下标）记录，增删/复制 SKU 后不会错位。 const [expandedVariantKeys, setExpandedVariantKeys] = useState>(() => new Set()); + const requiredAspectDefinitions = activeAttributeSchema.filter( + (definition) => definition.is_aspect && definition.is_required && !definition.editor_field + ); + const optionalAspectDefinitions = activeAttributeSchema.filter( + (definition) => definition.is_aspect && !definition.is_required && !definition.editor_field + ); return (
+ {requiredAspectDefinitions.length > 0 && ( +
+ + Ozon 变体属性 + + {sourceId ? ( + + ) : ( + + 保存新 SKU 后即可填写其 Ozon 变体属性。 + + )} +
+ )} {expanded && (
+ {optionalAspectDefinitions.length > 0 && + sourceId && ( +
+ + Ozon 选填变体属性 + + +
+ )}
SKU 图片 {imageCandidates.length ? (
- {imageCandidates.map((candidate, imageIndex) => { - // 仅"转存成功"的候选可直接勾选；待转存图片仅保留预览， - // 避免在此处重复提供后续素材选择流程的入口。 - const selectable = - candidate.status === - 'succeeded' && - !!candidate.asset_id; - const selected = - selectable && - selectedAssetIds.includes( - candidate.asset_id! - ); - return ( -
- {imageIndex === 0 && ( - - 主图 - - )} - 采集候选图片 - {selectable ? ( - - ) : candidate.status === - 'pending_selection' ? null : ( - + ) : candidate.status === + 'pending_selection' ? null : ( + - )} -
- ); - })} + } + disabled={ + candidate.status === + 'queued' || + candidate.status === + 'running' || + candidate.status === + 'failed' + } + onClick={() => + void onMaterialize( + candidate.id + ) + } + > + {candidate.status === + 'failed' + ? '转存失败' + : '转存中'} + + )} +
+ ); + } + )} {/* 仅提供素材选择入口的视觉占位，实际选择流程后续接入。 */} } + > + {attribute && + + 属性 ID {attribute.platform_attribute_id} · 字典 ID {attribute.dictionary_id} + + {!isComplete && } + setDraftKeyword(event.target.value)} + onSearch={(value) => { setKeyword(value.trim()); setPage(1); }} + /> + {error && } + {loading ?
+ : values.length ? + rowKey="id" + size="small" + pagination={false} + dataSource={values} + columns={[ + { title: '候选值', dataIndex: 'value', key: 'value', render: (value: string) => + {value} }, + { title: '值 ID', dataIndex: 'external_value_id', key: 'id', width: 145 }, + ]} + /> : } + `已缓存 ${count} 项`} + onChange={setPage} + /> + } + ; +} diff --git a/apps/web/src/pages/system/components/PlatformAttributesTable.tsx b/apps/web/src/pages/system/components/PlatformAttributesTable.tsx new file mode 100644 index 0000000..78cda25 --- /dev/null +++ b/apps/web/src/pages/system/components/PlatformAttributesTable.tsx @@ -0,0 +1,58 @@ +import { Button, Empty, Table, Tag, Tooltip, Typography } from 'antd'; +import type { ColumnsType } from 'antd/es/table'; +import type { CatalogAttribute } from '@/services/platformCatalogAdmin'; + +type Props = { + attributes: CatalogAttribute[]; + loading: boolean; + selectedCategoryName: string | null; + onValues: (attribute: CatalogAttribute) => void; +}; + +const typeLabels: Record = { + text: '文本', integer: '整数', decimal: '小数', boolean: '布尔', dictionary: '字典', +}; + +export default function PlatformAttributesTable({ + attributes, loading, selectedCategoryName, onValues, +}: Props) { + const columns: ColumnsType = [ + { + title: '属性', dataIndex: 'name', key: 'name', + render: (_value, row) =>
+ + {row.name} + + ID {row.platform_attribute_id} +
, + }, + { + title: '规则', key: 'rules', width: 178, + render: (_value, row) =>
+ {row.is_required && 必填} + {row.is_aspect && SKU 变体} + {!row.is_active && 已停用} + {typeLabels[row.value_type] ?? row.value_type} +
, + }, + { + title: '候选值', key: 'values', width: 118, + render: (_value, row) => row.dictionary_id + ? + : 自由填报, + }, + ]; + if (!selectedCategoryName) return ; + return + rowKey="id" + size="middle" + columns={columns} + dataSource={attributes} + loading={loading} + pagination={{ pageSize: 20, showSizeChanger: false }} + locale={{ emptyText: '该类型暂无已同步属性' }} + scroll={{ x: 640 }} + />; +} diff --git a/apps/web/src/pages/system/components/PlatformCategoryTree.tsx b/apps/web/src/pages/system/components/PlatformCategoryTree.tsx new file mode 100644 index 0000000..0d69293 --- /dev/null +++ b/apps/web/src/pages/system/components/PlatformCategoryTree.tsx @@ -0,0 +1,83 @@ +import { useMemo, useState } from 'react'; +import { Empty, Input, Spin, Tag, Tree, Typography } from 'antd'; +import type { DataNode } from 'antd/es/tree'; +import type { CatalogCategory } from '@/services/platformCatalogAdmin'; + +type Props = { + categories: CatalogCategory[]; + loading: boolean; + selectedId: string | null; + onSelect: (category: CatalogCategory) => void; +}; + +/** 目录节点保留展开能力，只有活动商品类型叶子可选择。 */ +export default function PlatformCategoryTree({ categories, loading, selectedId, onSelect }: Props) { + const [search, setSearch] = useState(''); + const categoryById = useMemo(() => new Map(categories.map((item) => [item.id, item])), [categories]); + const treeData = useMemo(() => { + const query = search.trim().toLowerCase(); + const visible = new Set(); + if (query) { + for (const category of categories) { + if (![category.name, category.path, category.external_category_id, + category.external_type_id ?? ''].some((value) => value.toLowerCase().includes(query))) continue; + let node: CatalogCategory | undefined = category; + while (node && !visible.has(node.id)) { + visible.add(node.id); + node = node.parent_id ? categoryById.get(node.parent_id) : undefined; + } + } + } + const childrenByParent = new Map(); + for (const category of categories) { + if (query && !visible.has(category.id)) continue; + const parentId = category.parent_id && categoryById.has(category.parent_id) + ? category.parent_id : null; + const group = childrenByParent.get(parentId) ?? []; + group.push(category); + childrenByParent.set(parentId, group); + } + const toNodes = (parentId: string | null): DataNode[] => + (childrenByParent.get(parentId) ?? []).map((category) => ({ + key: category.id, + selectable: category.is_active && category.external_type_id !== null && + category.external_type_id !== '0', + title: ( + + {category.name} + {category.external_type_id && category.external_type_id !== '0' && + #{category.external_type_id}} + {!category.is_active && category.external_type_id !== '0' && + 不可建品} + + ), + children: toNodes(category.id), + })); + return toNodes(null); + }, [categories, categoryById, search]); + + return ( +
+ setSearch(event.target.value)} + /> + {loading ?
+ : !treeData.length ? + : { + const category = categoryById.get(String(keys[0] ?? '')); + if (category) onSelect(category); + }} + />} +
+ ); +} diff --git a/apps/web/src/router/index.tsx b/apps/web/src/router/index.tsx index 06f59cc..576011b 100644 --- a/apps/web/src/router/index.tsx +++ b/apps/web/src/router/index.tsx @@ -16,6 +16,8 @@ import CategoryTreeDebugPage from '@/pages/shops/CategoryTreeDebugPage'; import WatermarksPage from '@/pages/watermarks/WatermarksPage'; import { PlatformProvider } from '@/services/platform'; import { useSession } from '@/services/session'; +import SystemAdminLayout from '@/layouts/SystemAdminLayout'; +import SystemCatalogPage from '@/pages/system/SystemCatalogPage'; /** 主布局守卫：会话恢复中显示启动屏；未认证跳登录页并记住来源路径 */ function RequireSession({ children }: { children: ReactNode }) { @@ -71,6 +73,14 @@ export const router = createBrowserRouter([ { path: 'settings/password', element: }, ], }, + { + path: '/system', + element: , + children: [ + { index: true, element: }, + { path: 'platform-catalog', element: }, + ], + }, { path: 'login', element: ( diff --git a/apps/web/src/services/platformCatalogAdmin.ts b/apps/web/src/services/platformCatalogAdmin.ts new file mode 100644 index 0000000..cd90e45 --- /dev/null +++ b/apps/web/src/services/platformCatalogAdmin.ts @@ -0,0 +1,68 @@ +import { api } from '@/services/api'; + +export type AdminPlatform = { + id: string; code: string; name: string; status: string; + source: { configured: boolean; client_id_hint: string | null; updated_at: string | null }; + summary: { category_count: number; last_tree_sync_at: string | null; last_error: string | null }; +}; + +export type CatalogCategory = { + id: string; parent_id: string | null; external_category_id: string; + external_type_id: string | null; name: string; path: string; + is_active: boolean; synced_at: string | null; +}; + +export type CatalogAttribute = { + id: string; platform_attribute_id: string; complex_id: string; + name: string; description: string | null; group_id: string | null; + group_name: string | null; value_type: string; is_required: boolean; + is_aspect: boolean; is_collection: boolean; max_value_count: number; + dictionary_id: string | null; category_dependent: boolean; + is_active: boolean; synced_at: string | null; dictionary_value_count: number; +}; + +export type CatalogValue = { + id: string; external_value_id: string; value: string; + info: string | null; picture: string | null; +}; + +export type CatalogRun = { + id: string; platform_id: string; scope: 'tree' | 'attributes' | 'dictionary'; + scope_key: string; category_id: string | null; attribute_id: string | null; + trigger: string; status: string; result: Record; + error_code: string | null; error_message: string | null; + attempt_count: number; created_at: string; + started_at: string | null; completed_at: string | null; +}; + +export type SyncRequest = + | { scope: 'tree' } + | { scope: 'attributes'; category_id: string } + | { scope: 'dictionary'; attribute_id: string }; + +export const platformCatalogAdminApi = { + access: () => api.get<{ is_system_admin: boolean }>('/system/access'), + platforms: () => api.get('/system/platform-catalog/platforms'), + configureSource: (platformId: string, input: { client_id: string; api_key: string }) => + api.put<{ configured: boolean; client_id_hint: string; revision: number; changed: boolean }>( + `/system/platform-catalog/platforms/${platformId}/source`, input, + ), + categories: (platformId: string) => + api.get(`/system/platform-catalog/platforms/${platformId}/categories`), + attributes: (platformId: string, categoryId: string) => + api.get( + `/system/platform-catalog/platforms/${platformId}/categories/${categoryId}/attributes`, + ), + values: (platformId: string, attributeId: string, page: number, keyword: string) => + api.getList( + `/system/platform-catalog/platforms/${platformId}/attributes/${attributeId}/values`, + { params: { page, q: keyword } }, + ), + sync: (platformId: string, input: SyncRequest) => + api.post<{ id: string; status: string }>( + `/system/platform-catalog/platforms/${platformId}/syncs`, input, + { headers: { 'Idempotency-Key': crypto.randomUUID() } }, + ), + runs: (platformId: string) => + api.get(`/system/platform-catalog/platforms/${platformId}/syncs?limit=20`), +}; diff --git a/apps/web/src/services/productEditor.ts b/apps/web/src/services/productEditor.ts index 7d5ed31..e97c5ac 100644 --- a/apps/web/src/services/productEditor.ts +++ b/apps/web/src/services/productEditor.ts @@ -4,6 +4,7 @@ import type { ProductEditorCategoryOption, ProductEditorContext, ProductEditorSnapshot, + ProductEditorValidation, Operation, SaveProductEditorDraftRequest, SaveProductEditorDraftResponse, @@ -39,22 +40,42 @@ export const productEditorApi = { 'If-Match': `"${revisions.product}:${revisions.profile}"`, }, }), - categoryOptions: (profileId: string, platformId: string, search?: string, storeId?: string | null) => + categoryOptions: ( + profileId: string, + platformId: string, + search?: string, + storeId?: string | null + ) => api.get( `/product-platform-profiles/${profileId}/category-options`, { - params: { ...(search ? { q: search } : {}), ...(storeId ? { store_id: storeId } : {}) }, + params: { + ...(search ? { q: search } : {}), + ...(storeId ? { store_id: storeId } : {}), + }, headers: { 'X-Atlas-Platform-Id': platformId }, } ), - attributeSchema: (profileId: string, platformId: string, categoryId?: string | null, storeId?: string | null) => + attributeSchema: ( + profileId: string, + platformId: string, + categoryId?: string | null, + storeId?: string | null + ) => api.get( `/product-platform-profiles/${profileId}/attribute-schema`, { - params: { ...(categoryId ? { category_id: categoryId } : {}), ...(storeId ? { store_id: storeId } : {}) }, + params: { + ...(categoryId ? { category_id: categoryId } : {}), + ...(storeId ? { store_id: storeId } : {}), + }, headers: { 'X-Atlas-Platform-Id': platformId }, } ), + validation: (profileId: string, platformId: string) => + api.get(`/product-platform-profiles/${profileId}/validation`, { + headers: { 'X-Atlas-Platform-Id': platformId }, + }), syncAttributeSchema: (profileId: string, platformId: string, categoryId: string) => api.post<{ operation: Operation }>( `/product-platform-profiles/${profileId}/attribute-schema-syncs`, @@ -74,6 +95,7 @@ export const productEditorApi = { search?: string, categoryId?: string | null, storeId?: string | null, + cursor?: string | null ) => api.get<{ items: ProductAttributeDictionaryValue[]; next_cursor: string | null }>( `/product-platform-profiles/${profileId}/attribute-dictionaries/${encodeURIComponent(dictionaryId)}`, @@ -82,6 +104,7 @@ export const productEditorApi = { ...(categoryId ? { category_id: categoryId } : {}), ...(storeId ? { store_id: storeId } : {}), ...(search ? { q: search } : {}), + ...(cursor ? { cursor } : {}), }, headers: { 'X-Atlas-Platform-Id': platformId }, } diff --git a/apps/web/src/services/useSystemAdminAccess.ts b/apps/web/src/services/useSystemAdminAccess.ts new file mode 100644 index 0000000..ec76a65 --- /dev/null +++ b/apps/web/src/services/useSystemAdminAccess.ts @@ -0,0 +1,23 @@ +import { useEffect, useState } from 'react'; +import { platformCatalogAdminApi } from './platformCatalogAdmin'; +import { useSession } from './session'; + +type AccessState = 'checking' | 'allowed' | 'denied'; + +/** 菜单可见性使用只读探测；后台 API 仍独立校验数据库授权。 */ +export function useSystemAdminAccess(): AccessState { + const { status } = useSession(); + const [access, setAccess] = useState('checking'); + useEffect(() => { + if (status !== 'authenticated') { + setAccess('checking'); + return; + } + let active = true; + void platformCatalogAdminApi.access() + .then((result) => { if (active) setAccess(result.is_system_admin ? 'allowed' : 'denied'); }) + .catch(() => { if (active) setAccess('denied'); }); + return () => { active = false; }; + }, [status]); + return access; +} diff --git a/apps/worker/src/main.ts b/apps/worker/src/main.ts index 13fe8ce..18a4796 100644 --- a/apps/worker/src/main.ts +++ b/apps/worker/src/main.ts @@ -19,17 +19,25 @@ import { type CatalogSyncScope, } from './ozon-catalog-sync.js'; import { scheduleStoreCategoryTreeSync } from './store-category-tree-scheduler.js'; +import { PlatformCatalogDispatcher, type PlatformCatalogJob } from './platform-catalog-dispatcher.js'; +import { PlatformCatalogScheduler } from './platform-catalog-scheduler.js'; +import { markPlatformCatalogUnavailable, syncPlatformCatalog } from './platform-catalog-sync.js'; const connection = new Redis(workerConfig.redisUrl, { maxRetriesPerRequest: null, }); const database = createApplicationDatabase(workerConfig.databaseUrl); const queue = new Queue('atlas-dispatch', { connection }); +const platformQueue = new Queue('atlas-dispatch', { connection }); const dispatcher = new OutboxDispatcher( database, queue, `worker_${randomUUID()}`, ); +const platformDispatcher = new PlatformCatalogDispatcher( + database, platformQueue, `platform_worker_${randomUUID()}`, +); +const platformScheduler = new PlatformCatalogScheduler(database); const objectStorage = new S3Client({ endpoint: workerConfig.objectStorageEndpoint, region: 'us-east-1', @@ -54,15 +62,17 @@ type CatalogSyncJob = OutboxJob & { }; }; -const worker = new Worker( +const worker = new Worker( 'atlas-dispatch', async (job) => { - if (job.name === 'store_credential_verification.requested') { + if (job.name === 'platform_catalog_sync.requested') { + await syncPlatformCatalog(database, job.data as PlatformCatalogJob); + } else if (job.name === 'store_credential_verification.requested') { await verifyStoreCredentials(database, job.data as OutboxJob & { payload: { store_id: string; operation_id: string; secret_id?: string } }); } else if (job.name === 'collection.cleanup.requested') { await cleanupCollection(database, job.data as OutboxJob & { payload: { operation_id: string; collection_item_ids: string[] } }); } else if (job.name === 'collection.assets.materialize.requested' || job.name === 'collection.assets.retry.requested') { - await materializeCollectionAssets(database, objectStorage, workerConfig.objectStorageBucket, job.data); + await materializeCollectionAssets(database, objectStorage, workerConfig.objectStorageBucket, job.data as OutboxJob); } else if ( job.name === 'store_category_tree_sync.requested' || job.name === 'store_category_attribute_sync.requested' || @@ -84,7 +94,9 @@ async function cleanupCollection(database: Database, job: OutboxJob & { payload: worker.on('failed', (job, error) => { if (!job || job.attemptsMade < (job.opts.attempts ?? 1)) return; - if (job.name === 'store_credential_verification.requested') { + if (job.name === 'platform_catalog_sync.requested') { + void markPlatformCatalogUnavailable(database, job.data as PlatformCatalogJob); + } else if (job.name === 'store_credential_verification.requested') { void markUnavailable(database, job.data as StoreVerificationJob, error); } else if ( job.name === 'store_category_tree_sync.requested' || @@ -285,20 +297,36 @@ async function markUnavailable( let dispatcherTimer: ReturnType | undefined; let mediaCleanupTimer: ReturnType | undefined; +let platformCatalogTimer: ReturnType | undefined; async function bootstrap() { await queue.waitUntilReady(); await worker.waitUntilReady(); await dispatcher.dispatchBatch(); + await platformDispatcher.dispatchBatch(); + await platformScheduler.run(); dispatcherTimer = setInterval( - () => + () => { void dispatcher.dispatchBatch().catch((error: unknown) => { console.error( 'outbox_dispatch_failed', error instanceof Error ? error.message : error, ); - }), + }); + void platformDispatcher.dispatchBatch().catch((error: unknown) => { + console.error( + 'platform_outbox_dispatch_failed', + error instanceof Error ? error.message : error, + ); + }); + }, 2_000, ); + platformCatalogTimer = setInterval( + () => void platformScheduler.run().catch((error: unknown) => { + console.error('platform_catalog_schedule_failed', error instanceof Error ? error.message : error); + }), + 60_000, + ); void mediaUploadCleanup.run().catch((error: unknown) => { console.error( 'media_upload_cleanup_startup_failed', @@ -329,8 +357,10 @@ void bootstrap().catch((error: unknown) => { async function shutdown() { if (dispatcherTimer) clearInterval(dispatcherTimer); if (mediaCleanupTimer) clearInterval(mediaCleanupTimer); + if (platformCatalogTimer) clearInterval(platformCatalogTimer); await worker.close(); await queue.close(); + await platformQueue.close(); objectStorage.destroy(); await database.close(); await connection.quit(); diff --git a/apps/worker/src/ozon-client.ts b/apps/worker/src/ozon-client.ts index a375107..7d0156d 100644 --- a/apps/worker/src/ozon-client.ts +++ b/apps/worker/src/ozon-client.ts @@ -87,18 +87,85 @@ export async function fetchOzonDictionaryValues( }, ) { const query = input.query?.trim() ?? ''; - const path = query - ? '/v1/description-category/attribute/values/search' - : '/v1/description-category/attribute/values'; - const body = await requestOzon(clientId, apiKey, path, { + const request = { attribute_id: numberOrText(input.attributeId), description_category_id: numberOrText(input.categoryId), type_id: numberOrText(input.typeId), language: 'ZH_HANS', - limit: query ? 100 : 1_000, - ...(query ? { value: query } : { last_value_id: 0 }), - }); - return readResultArray(body, '属性字典'); + }; + if (query) { + const body = await requestOzon( + clientId, apiKey, '/v1/description-category/attribute/values/search', + { ...request, limit: 100, value: query }, + ); + return readResultArray(body, '属性字典'); + } + const values: OzonDictionaryValue[] = []; + const seen = new Set(); + let lastValueId: number | string = 0; + // 大字典仅预取首批 1000 项；后续值由关键词搜索补充，重复游标不得造成无限循环。 + for (let pageIndex = 0; pageIndex < 20 && values.length < 1_000; pageIndex += 1) { + const body = await requestOzon( + clientId, apiKey, '/v1/description-category/attribute/values', + { ...request, limit: 1_000 - values.length, last_value_id: lastValueId }, + ); + const page = readResultArray(body, '属性字典'); + let added = 0; + for (const value of page) { + const id = String(value.id ?? ''); + if (!id || seen.has(id)) continue; + seen.add(id); + values.push(value); + added += 1; + } + const nextId = page.at(-1)?.id; + if ( + (body as { has_next?: unknown }).has_next !== true || !page.length || + !added || nextId == null || String(nextId) === String(lastValueId) + ) break; + lastValueId = typeof nextId === 'string' ? numberOrText(nextId) : nextId; + } + return values; +} + +/** 平台级字典按页获取，明确返回完整性；大字典不会伪装成已全量同步。 */ +export async function fetchOzonDictionaryBatch( + clientId: string, + apiKey: string, + input: { attributeId: string; categoryId: string; typeId: string }, +): Promise<{ values: OzonDictionaryValue[]; isComplete: boolean }> { + const values: OzonDictionaryValue[] = []; + const seen = new Set(); + let lastValueId: number | string = 0; + for (let pageIndex = 0; pageIndex < 5; pageIndex += 1) { + const body = await requestOzon( + clientId, apiKey, '/v1/description-category/attribute/values', + { + attribute_id: numberOrText(input.attributeId), + description_category_id: numberOrText(input.categoryId), + type_id: numberOrText(input.typeId), + language: 'ZH_HANS', + limit: 2000, + last_value_id: lastValueId, + }, + ); + const page = readResultArray(body, '属性字典'); + for (const value of page) { + const id = String(value.id ?? '').trim(); + if (id && !seen.has(id)) { + seen.add(id); + values.push(value); + } + } + const hasNext = (body as { has_next?: unknown }).has_next === true; + if (!hasNext) return { values, isComplete: true }; + const nextId = page.at(-1)?.id; + if (!page.length || nextId == null || String(nextId) === String(lastValueId)) { + throw new OzonRetryableError('Ozon 字典分页游标没有前进'); + } + lastValueId = nextId; + } + return { values, isComplete: false }; } async function requestOzon( diff --git a/apps/worker/src/platform-catalog-dispatcher.ts b/apps/worker/src/platform-catalog-dispatcher.ts new file mode 100644 index 0000000..06cd398 --- /dev/null +++ b/apps/worker/src/platform-catalog-dispatcher.ts @@ -0,0 +1,68 @@ +import type { Queue } from 'bullmq'; +import type { Database } from '@atlas/database'; + +export type PlatformCatalogJob = { + eventId: string; + runId: string; + platformId: string; +}; + +export class PlatformCatalogDispatcher { + public constructor( + private readonly database: Database, + private readonly queue: Queue, + private readonly workerId: string, + ) {} + + public async dispatchBatch() { + const events = await this.database.transaction((tx) => tx.query<{ + id: string; run_id: string; platform_id: string; + }>( + `WITH candidates AS ( + SELECT id FROM atlas.platform_catalog_outbox_events + WHERE (status = 'pending' AND next_attempt_at <= now()) + OR (status = 'dispatching' AND locked_until < now()) + ORDER BY created_at FOR UPDATE SKIP LOCKED LIMIT 20 + ) + UPDATE atlas.platform_catalog_outbox_events event + SET status = 'dispatching', locked_by = $1, + locked_until = now() + interval '2 minutes', updated_at = now() + FROM candidates WHERE event.id = candidates.id + RETURNING event.id, event.run_id, event.platform_id`, + [this.workerId], + )); + for (const event of events.rows) { + try { + await this.queue.add('platform_catalog_sync.requested', { + eventId: event.id, + runId: event.run_id, + platformId: event.platform_id, + }, { + jobId: event.id, + attempts: 5, + backoff: { type: 'exponential', delay: 5_000 }, + removeOnComplete: 1000, + removeOnFail: 1000, + }); + await this.database.query( + `UPDATE atlas.platform_catalog_outbox_events + SET status = 'dispatched', dispatched_at = now(), + locked_by = NULL, locked_until = NULL, updated_at = now() + WHERE id = $1 AND status = 'dispatching' AND locked_by = $2`, + [event.id, this.workerId], + ); + } catch (error) { + await this.database.query( + `UPDATE atlas.platform_catalog_outbox_events + SET status = 'pending', attempt_count = attempt_count + 1, + next_attempt_at = now() + interval '30 seconds', + locked_by = NULL, locked_until = NULL, + last_error_code = 'QUEUE_UNAVAILABLE', updated_at = now() + WHERE id = $1 AND status = 'dispatching' AND locked_by = $2`, + [event.id, this.workerId], + ); + throw error; + } + } + } +} diff --git a/apps/worker/src/platform-catalog-mappers.ts b/apps/worker/src/platform-catalog-mappers.ts new file mode 100644 index 0000000..a58f76c --- /dev/null +++ b/apps/worker/src/platform-catalog-mappers.ts @@ -0,0 +1,107 @@ +import type { OzonCategoryAttribute, OzonCategoryNode } from './ozon-client.js'; + +export type PlatformCategoryRecord = { + external_category_id: string; + external_type_id: string; + parent_key: string | null; + name: string; + path: string; + is_active: boolean; + source_payload: OzonCategoryNode; +}; + +/** Ozon 类型叶子可能省略类目 ID，需要继承最近的父类目。 */ +export function flattenPlatformCategories( + nodes: OzonCategoryNode[], + path: string[] = [], + parentKey: string | null = null, + inheritedCategory?: { id: string; name: string }, +): PlatformCategoryRecord[] { + const records: PlatformCategoryRecord[] = []; + for (const node of nodes) { + const explicitId = String(node.description_category_id ?? '').trim(); + const explicitName = node.category_name?.trim() ?? ''; + const categoryId = explicitId || inheritedCategory?.id || ''; + const categoryName = explicitName || inheritedCategory?.name || ''; + const typeId = String(node.type_id ?? 0); + const name = explicitName || node.type_name?.trim() || categoryName; + if (!categoryId || !name) continue; + const nextPath = [...path, name]; + const key = `${categoryId}:${typeId}`; + records.push({ + external_category_id: categoryId, + external_type_id: typeId, + parent_key: parentKey, + name, + path: nextPath.join(' › '), + is_active: node.disabled !== true && typeId !== '0', + source_payload: node, + }); + records.push(...flattenPlatformCategories( + node.children ?? [], + nextPath, + key, + explicitId && explicitName ? { id: explicitId, name: explicitName } : inheritedCategory, + )); + } + return records; +} + +export type PlatformAttributeRecord = { + platform_attribute_id: string; + complex_id: string; + name: string; + description: string | null; + group_id: string | null; + group_name: string | null; + value_type: 'text' | 'integer' | 'decimal' | 'boolean' | 'dictionary'; + is_required: boolean; + is_collection: boolean; + max_value_count: number; + dictionary_id: string | null; + is_aspect: boolean; + category_dependent: boolean; + source_payload: OzonCategoryAttribute; +}; + +export function mapPlatformAttributes(values: OzonCategoryAttribute[]): PlatformAttributeRecord[] { + const byKey = new Map(); + for (const value of values) { + const attributeId = String(value.id ?? '').trim(); + const name = value.name?.trim(); + if (!attributeId || !name) continue; + const complexId = String(value.attribute_complex_id ?? value.complex_id ?? 0); + const dictionaryId = String(value.dictionary_id ?? '').trim(); + const hasDictionary = !!dictionaryId && dictionaryId !== '0'; + const isCollection = value.is_collection === true; + const requestedMax = Number(value.max_value_count ?? (isCollection ? 100 : 1)); + const type = String(value.type ?? '').toLowerCase(); + const record: PlatformAttributeRecord = { + platform_attribute_id: attributeId, + complex_id: complexId, + name, + description: stringOrNull(value.description), + group_id: value.group_id == null ? null : String(value.group_id), + group_name: stringOrNull(value.group_name), + value_type: hasDictionary ? 'dictionary' + : type === 'integer' ? 'integer' + : type === 'decimal' || type === 'number' ? 'decimal' + : type === 'boolean' ? 'boolean' : 'text', + is_required: value.is_required === true, + is_collection: isCollection, + max_value_count: isCollection + ? Math.max(1, Math.min(100, Number.isFinite(requestedMax) ? requestedMax : 100)) + : 1, + dictionary_id: hasDictionary ? dictionaryId : null, + is_aspect: value.is_aspect === true, + category_dependent: value.category_dependent === true, + source_payload: value, + }; + byKey.set(`${attributeId}:${complexId}`, record); + } + return [...byKey.values()]; +} + +function stringOrNull(value: unknown): string | null { + return typeof value === 'string' && value.trim() ? value.trim() : null; +} diff --git a/apps/worker/src/platform-catalog-scheduler.ts b/apps/worker/src/platform-catalog-scheduler.ts new file mode 100644 index 0000000..ed3efa8 --- /dev/null +++ b/apps/worker/src/platform-catalog-scheduler.ts @@ -0,0 +1,103 @@ +import type { Database, DatabaseTransaction } from '@atlas/database'; + +type Candidate = { scope: 'tree' | 'attributes' | 'dictionary'; scope_key: string; + category_id: string | null; attribute_id: string | null }; + +/** 定时任务逐平台限量排队，避免启动时一次扫完全部类目和大字典。 */ +export class PlatformCatalogScheduler { + public constructor(private readonly database: Database) {} + + public async run() { + const sources = await this.database.query<{ platform_id: string }>( + `SELECT source.platform_id FROM atlas.platform_catalog_sources source + JOIN atlas.platforms platform ON platform.id = source.platform_id + WHERE platform.status = 'active' AND upper(platform.code) = 'OZON'`, + ); + for (const source of sources.rows) { + await this.schedulePlatform(source.platform_id); + } + } + + private async schedulePlatform(platformId: string) { + await this.database.transaction(async (tx) => { + const source = await tx.query<{ revision: number }>( + `SELECT revision FROM atlas.platform_catalog_sources + WHERE platform_id = $1 FOR UPDATE`, + [platformId], + ); + if (!source.rows[0]) return; + const pending = await tx.query<{ count: string }>( + `SELECT count(*)::text AS count FROM atlas.platform_catalog_sync_runs + WHERE platform_id = $1 AND status IN ('queued', 'running')`, + [platformId], + ); + if (Number(pending.rows[0]?.count ?? 0) >= 6) return; + const candidates = await tx.query( + `WITH possible AS ( + SELECT 'tree'::text AS scope, 'tree'::text AS scope_key, + NULL::uuid AS category_id, NULL::uuid AS attribute_id, + interval '24 hours' AS refresh_interval, 0 AS priority + UNION ALL + SELECT 'attributes', 'attributes:' || category.id, category.id, NULL::uuid, + interval '24 hours', 1 + FROM atlas.platform_product_categories category + WHERE category.platform_id = $1 AND category.is_active + AND category.external_type_id IS NOT NULL AND category.external_type_id <> '0' + UNION ALL + SELECT 'dictionary', 'dictionary:' || attribute.id, + attribute.platform_product_category_id, attribute.id, + interval '7 days', 2 + FROM atlas.platform_product_category_attributes attribute + JOIN atlas.platform_product_categories category + ON category.id = attribute.platform_product_category_id + WHERE attribute.platform_id = $1 AND attribute.is_active + AND attribute.dictionary_id IS NOT NULL AND category.is_active + ) + SELECT possible.scope, possible.scope_key, possible.category_id, possible.attribute_id + FROM possible + WHERE NOT EXISTS ( + SELECT 1 FROM atlas.platform_catalog_sync_runs run + WHERE run.platform_id = $1 AND run.scope_key = possible.scope_key + AND run.status = 'succeeded' + AND run.completed_at > now() - possible.refresh_interval + ) AND NOT EXISTS ( + SELECT 1 FROM atlas.platform_catalog_sync_runs run + WHERE run.platform_id = $1 AND run.scope_key = possible.scope_key + AND run.created_at > now() - interval '1 hour' + ) AND NOT EXISTS ( + SELECT 1 FROM atlas.platform_catalog_sync_runs run + WHERE run.platform_id = $1 AND run.scope_key = possible.scope_key + AND run.status IN ('queued', 'running') + ) + ORDER BY possible.priority, possible.scope_key LIMIT 6`, + [platformId], + ); + const capacity = 6 - Number(pending.rows[0]?.count ?? 0); + for (const candidate of candidates.rows.slice(0, capacity)) { + await enqueueScheduled(tx, platformId, source.rows[0].revision, candidate); + } + }); + } +} + +async function enqueueScheduled( + tx: DatabaseTransaction, + platformId: string, + sourceRevision: number, + candidate: Candidate, +) { + const run = await tx.query<{ id: string }>( + `INSERT INTO atlas.platform_catalog_sync_runs + (platform_id, scope, scope_key, category_id, attribute_id, + trigger_kind, source_revision) + VALUES ($1, $2, $3, $4, $5, 'scheduled', $6) + RETURNING id`, + [platformId, candidate.scope, candidate.scope_key, + candidate.category_id, candidate.attribute_id, sourceRevision], + ); + await tx.query( + `INSERT INTO atlas.platform_catalog_outbox_events (run_id, platform_id) + VALUES ($1, $2)`, + [run.rows[0].id, platformId], + ); +} diff --git a/apps/worker/src/platform-catalog-sync.ts b/apps/worker/src/platform-catalog-sync.ts new file mode 100644 index 0000000..af21891 --- /dev/null +++ b/apps/worker/src/platform-catalog-sync.ts @@ -0,0 +1,337 @@ +import type { Database, DatabaseTransaction } from '@atlas/database'; +import { + fetchOzonCategoryAttributes, fetchOzonCategoryTree, fetchOzonDictionaryBatch, + OzonCredentialError, OzonRequestError, type OzonCategoryNode, + type OzonDictionaryValue, +} from './ozon-client.js'; +import { flattenPlatformCategories, mapPlatformAttributes } from './platform-catalog-mappers.js'; +import type { PlatformCatalogJob } from './platform-catalog-dispatcher.js'; +import { decryptStoreSecret } from './store-secret.crypto.js'; +import { workerConfig } from './config.js'; + +type RunSource = { + id: string; platform_id: string; scope: 'tree' | 'attributes' | 'dictionary'; + category_id: string | null; attribute_id: string | null; + source_revision: number; platform_code: string; + client_id: string; secret_ciphertext: Buffer; secret_nonce: Buffer; + current_revision: number; + external_category_id: string | null; external_type_id: string | null; + platform_attribute_id: string | null; +}; + +type SyncPayload = + | { scope: 'tree'; nodes: OzonCategoryNode[] } + | { scope: 'attributes'; attributes: Awaited> } + | { scope: 'dictionary'; batch: Awaited> }; + +export async function syncPlatformCatalog(database: Database, job: PlatformCatalogJob) { + const source = await claimRun(database, job); + if (!source) return; + if (source.source_revision !== source.current_revision) { + await finishRun(database, job.runId, 'cancelled', 'CATALOG_SOURCE_REPLACED', '同步来源已更新'); + return; + } + if (source.platform_code.toUpperCase() !== 'OZON') { + await finishRun(database, job.runId, 'failed', 'PLATFORM_CATALOG_UNSUPPORTED', '该平台尚未接入目录同步'); + return; + } + const apiKey = decryptStoreSecret( + source.secret_ciphertext, source.secret_nonce, workerConfig.storeSecretEncryptionKey, + ); + try { + let payload: SyncPayload; + if (source.scope === 'tree') { + payload = { scope: 'tree', nodes: await fetchOzonCategoryTree(source.client_id, apiKey) }; + } else { + if (!source.external_category_id || !source.external_type_id || source.external_type_id === '0') { + await finishRun(database, job.runId, 'failed', 'CATEGORY_TYPE_UNAVAILABLE', '商品类型不存在或已停用'); + return; + } + if (source.scope === 'attributes') { + payload = { + scope: 'attributes', + attributes: await fetchOzonCategoryAttributes( + source.client_id, apiKey, + source.external_category_id, source.external_type_id, + ), + }; + } else { + if (!source.platform_attribute_id) { + await finishRun(database, job.runId, 'failed', 'ATTRIBUTE_NOT_FOUND', '字典属性已失效'); + return; + } + payload = { + scope: 'dictionary', + batch: await fetchOzonDictionaryBatch(source.client_id, apiKey, { + attributeId: source.platform_attribute_id, + categoryId: source.external_category_id, + typeId: source.external_type_id, + }), + }; + } + } + await persistAndComplete(database, source, payload); + } catch (error) { + if (error instanceof OzonCredentialError) { + await finishRun( + database, job.runId, 'failed', 'OZON_CATALOG_CREDENTIAL_INVALID', + error.status === 403 ? 'Ozon 拒绝读取目录，请检查密钥权限' : 'Ozon 未接受同步来源凭据', + ); + return; + } + if (error instanceof OzonRequestError) { + await finishRun( + database, job.runId, 'failed', 'OZON_CATALOG_REQUEST_REJECTED', + `Ozon 拒绝目录同步请求（HTTP ${error.status}）`, + ); + return; + } + throw error; + } +} + +export async function markPlatformCatalogUnavailable(database: Database, job: PlatformCatalogJob) { + await finishRun( + database, job.runId, 'failed', 'PLATFORM_CATALOG_SYNC_UNAVAILABLE', + '暂时无法同步平台目录，请稍后重试', + ); +} + +async function claimRun(database: Database, job: PlatformCatalogJob): Promise { + return database.transaction(async (tx) => { + const result = await tx.query( + `SELECT run.id, run.platform_id, run.scope, run.category_id, run.attribute_id, + run.source_revision, platform.code AS platform_code, + source.client_id, source.secret_ciphertext, source.secret_nonce, + source.revision AS current_revision, + category.external_category_id, category.external_type_id, + attribute.platform_attribute_id + FROM atlas.platform_catalog_sync_runs run + JOIN atlas.platforms platform ON platform.id = run.platform_id + JOIN atlas.platform_catalog_sources source ON source.platform_id = run.platform_id + LEFT JOIN atlas.platform_product_categories category + ON category.id = run.category_id AND category.platform_id = run.platform_id + LEFT JOIN atlas.platform_product_category_attributes attribute + ON attribute.id = run.attribute_id AND attribute.platform_id = run.platform_id + WHERE run.id = $1 AND run.platform_id = $2 + AND run.status IN ('queued', 'running') + FOR UPDATE OF run`, + [job.runId, job.platformId], + ); + const source = result.rows[0]; + if (!source) return null; + await tx.query( + `UPDATE atlas.platform_catalog_sync_runs + SET status = 'running', started_at = coalesce(started_at, now()), + attempt_count = attempt_count + 1 + WHERE id = $1`, + [job.runId], + ); + return source; + }); +} + +async function persistAndComplete(database: Database, source: RunSource, payload: SyncPayload) { + await database.transaction(async (tx) => { + // 凭据更新与结果发布共用来源行锁，旧任务不能覆盖新来源的目录。 + const revision = await tx.query<{ revision: number }>( + `SELECT revision FROM atlas.platform_catalog_sources + WHERE platform_id = $1 FOR UPDATE`, + [source.platform_id], + ); + const run = await tx.query<{ status: string }>( + `SELECT status FROM atlas.platform_catalog_sync_runs WHERE id = $1 FOR UPDATE`, + [source.id], + ); + if (run.rows[0]?.status !== 'running') return; + if (revision.rows[0]?.revision !== source.source_revision) { + await updateRun(tx, source.id, 'cancelled', null, 'CATALOG_SOURCE_REPLACED', '同步来源已更新'); + return; + } + let result: Record; + if (payload.scope === 'tree') { + result = await persistTree(tx, source.platform_id, payload.nodes); + } else if (payload.scope === 'attributes') { + result = await persistAttributes(tx, source.platform_id, source.category_id ?? '', payload.attributes); + } else { + result = await persistDictionary( + tx, source.platform_id, source.category_id ?? '', + source.attribute_id ?? '', payload.batch.values, payload.batch.isComplete, + ); + } + await updateRun(tx, source.id, 'succeeded', result); + }); +} + +async function persistTree(tx: DatabaseTransaction, platformId: string, nodes: OzonCategoryNode[]) { + const records = [...new Map(flattenPlatformCategories(nodes).map((node) => [ + `${node.external_category_id}:${node.external_type_id}`, node, + ])).values()]; + if (!records.length) throw new Error('Ozon 返回了空类目树'); + const syncTime = new Date(); + await tx.query( + `INSERT INTO atlas.platform_product_categories + (platform_id, external_category_id, external_type_id, name, path, + is_active, source_payload, synced_at) + SELECT $1, external_category_id, external_type_id, name, path, + is_active, source_payload, $3::timestamptz + FROM jsonb_to_recordset($2::jsonb) AS row( + external_category_id text, external_type_id text, parent_key text, + name text, path text, is_active boolean, source_payload jsonb) + ON CONFLICT (platform_id, external_category_id, external_type_id) DO UPDATE + SET name = EXCLUDED.name, path = EXCLUDED.path, is_active = EXCLUDED.is_active, + source_payload = EXCLUDED.source_payload, synced_at = EXCLUDED.synced_at, + updated_at = now()`, + [platformId, JSON.stringify(records), syncTime], + ); + await tx.query( + `WITH incoming AS ( + SELECT * FROM jsonb_to_recordset($2::jsonb) AS row( + external_category_id text, external_type_id text, parent_key text, + name text, path text, is_active boolean, source_payload jsonb) + ), resolved AS ( + SELECT child.id AS child_id, parent.id AS parent_id + FROM incoming + JOIN atlas.platform_product_categories child + ON child.platform_id = $1 + AND child.external_category_id = incoming.external_category_id + AND child.external_type_id = incoming.external_type_id + LEFT JOIN atlas.platform_product_categories parent + ON parent.platform_id = $1 + AND parent.external_category_id || ':' || parent.external_type_id = incoming.parent_key + ) + UPDATE atlas.platform_product_categories category + SET parent_id = resolved.parent_id, updated_at = now() + FROM resolved WHERE category.id = resolved.child_id`, + [platformId, JSON.stringify(records)], + ); + await tx.query( + `UPDATE atlas.platform_product_categories + SET is_active = false, updated_at = now() + WHERE platform_id = $1 AND synced_at IS DISTINCT FROM $2::timestamptz`, + [platformId, syncTime], + ); + return { category_count: records.length }; +} + +async function persistAttributes( + tx: DatabaseTransaction, platformId: string, categoryId: string, + attributes: Awaited>, +) { + const records = mapPlatformAttributes(attributes); + if (!records.length) throw new Error('Ozon 返回了空属性定义'); + const syncTime = new Date(); + await tx.query( + `INSERT INTO atlas.platform_product_category_attributes + (platform_id, platform_product_category_id, platform_attribute_id, complex_id, + name, description, group_id, group_name, value_type, is_required, + is_collection, max_value_count, dictionary_id, is_aspect, + category_dependent, is_active, source_payload, synced_at) + SELECT $1, $2, platform_attribute_id, complex_id, + name, description, group_id, group_name, value_type, is_required, + is_collection, max_value_count, dictionary_id, is_aspect, + category_dependent, true, source_payload, $4::timestamptz + FROM jsonb_to_recordset($3::jsonb) AS row( + platform_attribute_id text, complex_id text, name text, description text, + group_id text, group_name text, value_type text, is_required boolean, + is_collection boolean, max_value_count integer, dictionary_id text, + is_aspect boolean, category_dependent boolean, source_payload jsonb) + ON CONFLICT (platform_id, platform_product_category_id, platform_attribute_id, complex_id) + DO UPDATE SET name = EXCLUDED.name, description = EXCLUDED.description, + group_id = EXCLUDED.group_id, group_name = EXCLUDED.group_name, + value_type = EXCLUDED.value_type, is_required = EXCLUDED.is_required, + is_collection = EXCLUDED.is_collection, max_value_count = EXCLUDED.max_value_count, + dictionary_id = EXCLUDED.dictionary_id, is_aspect = EXCLUDED.is_aspect, + category_dependent = EXCLUDED.category_dependent, is_active = true, + source_payload = EXCLUDED.source_payload, synced_at = EXCLUDED.synced_at, + updated_at = now()`, + [platformId, categoryId, JSON.stringify(records), syncTime], + ); + await tx.query( + `UPDATE atlas.platform_product_category_attributes + SET is_active = false, updated_at = now() + WHERE platform_id = $1 AND platform_product_category_id = $2 + AND synced_at IS DISTINCT FROM $3::timestamptz`, + [platformId, categoryId, syncTime], + ); + return { attribute_count: records.length }; +} + +async function persistDictionary( + tx: DatabaseTransaction, platformId: string, categoryId: string, + attributeId: string, values: OzonDictionaryValue[], isComplete: boolean, +) { + const attribute = await tx.query<{ dictionary_id: string }>( + `SELECT dictionary_id FROM atlas.platform_product_category_attributes + WHERE id = $1 AND platform_id = $2 AND platform_product_category_id = $3 + AND is_active AND dictionary_id IS NOT NULL`, + [attributeId, platformId, categoryId], + ); + if (!attribute.rows[0]) throw new Error('字典属性已失效'); + const byId = new Map(); + for (const value of values) { + const id = String(value.id ?? '').trim(); + const label = value.value?.trim() ?? ''; + if (!id || !label) continue; + byId.set(id, { + external_value_id: id, + value: label, + info: typeof value.info === 'string' ? value.info : null, + picture: typeof value.picture === 'string' ? value.picture : null, + source_payload: value, + }); + } + const records = [...byId.values()]; + const syncTime = new Date(); + if (records.length) { + await tx.query( + `INSERT INTO atlas.platform_catalog_dictionary_values + (platform_id, platform_product_category_id, attribute_id, dictionary_id, + external_value_id, value, info, picture, source_payload, synced_at) + SELECT $1, $2, $3, $4, external_value_id, value, info, picture, + source_payload, $6::timestamptz + FROM jsonb_to_recordset($5::jsonb) AS row( + external_value_id text, value text, info text, picture text, source_payload jsonb) + ON CONFLICT (attribute_id, external_value_id) DO UPDATE + SET value = EXCLUDED.value, info = EXCLUDED.info, + picture = EXCLUDED.picture, source_payload = EXCLUDED.source_payload, + is_active = true, synced_at = EXCLUDED.synced_at, updated_at = now()`, + [platformId, categoryId, attributeId, attribute.rows[0].dictionary_id, + JSON.stringify(records), syncTime], + ); + } + if (isComplete) { + await tx.query( + `UPDATE atlas.platform_catalog_dictionary_values + SET is_active = false, updated_at = now() + WHERE attribute_id = $1 AND synced_at IS DISTINCT FROM $2::timestamptz`, + [attributeId, syncTime], + ); + } + return { dictionary_value_count: records.length, is_complete: isComplete }; +} + +async function finishRun( + database: Database, runId: string, + status: 'failed' | 'cancelled', code: string, message: string, +) { + await database.transaction((tx) => updateRun(tx, runId, status, null, code, message)); +} + +async function updateRun( + tx: DatabaseTransaction, runId: string, + status: 'succeeded' | 'failed' | 'cancelled', + result: Record | null, + code?: string, message?: string, +) { + await tx.query( + `UPDATE atlas.platform_catalog_sync_runs + SET status = $2::atlas.operation_status, completed_at = now(), + result = $3::jsonb, error_code = $4, error_message = $5 + WHERE id = $1 AND status IN ('queued', 'running')`, + [runId, status, JSON.stringify(result ?? {}), code ?? null, message ?? null], + ); +} diff --git a/apps/worker/test/ozon-client.test.mjs b/apps/worker/test/ozon-client.test.mjs new file mode 100644 index 0000000..cd6cacd --- /dev/null +++ b/apps/worker/test/ozon-client.test.mjs @@ -0,0 +1,95 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { fetchOzonDictionaryBatch, fetchOzonDictionaryValues } from '../src/ozon-client.ts'; + +const input = { + attributeId: '123', + categoryId: '456', + typeId: '789', +}; + +test('属性字典按 Ozon 游标读取多页', async () => { + const previousFetch = globalThis.fetch; + const requests = []; + globalThis.fetch = async (url, options) => { + requests.push({ url, body: JSON.parse(options.body) }); + const data = requests.length === 1 + ? { result: [{ id: 1, value: '中国' }], has_next: true } + : { result: [{ id: 2, value: '法国' }], has_next: false }; + return new Response(JSON.stringify(data), { status: 200 }); + }; + try { + const values = await fetchOzonDictionaryValues('client', 'key', input); + assert.deepEqual(values.map((value) => value.value), ['中国', '法国']); + assert.equal(requests.length, 2); + assert.equal(requests[0].body.last_value_id, 0); + assert.equal(requests[1].body.last_value_id, 1); + assert.ok(requests.every((request) => request.url.endsWith('/attribute/values'))); + } finally { + globalThis.fetch = previousFetch; + } +}); + +test('关键词使用 Ozon 字典搜索接口', async () => { + const previousFetch = globalThis.fetch; + const requests = []; + globalThis.fetch = async (url, options) => { + requests.push({ url, body: JSON.parse(options.body) }); + return new Response(JSON.stringify({ result: [{ id: 3, value: '儿童' }] }), { + status: 200, + }); + }; + try { + const values = await fetchOzonDictionaryValues('client', 'key', { + ...input, + query: '儿童', + }); + assert.equal(values.length, 1); + assert.equal(requests.length, 1); + assert.ok(requests[0].url.endsWith('/attribute/values/search')); + assert.equal(requests[0].body.value, '儿童'); + } finally { + globalThis.fetch = previousFetch; + } +}); + +test('Ozon 返回重复游标时停止翻页', async () => { + const previousFetch = globalThis.fetch; + let calls = 0; + globalThis.fetch = async () => { + calls += 1; + return new Response(JSON.stringify({ + result: [{ id: 1, value: '中国' }], + has_next: true, + }), { status: 200 }); + }; + try { + const values = await fetchOzonDictionaryValues('client', 'key', input); + assert.equal(values.length, 1); + assert.equal(calls, 2); + } finally { + globalThis.fetch = previousFetch; + } +}); + +test('平台字典批量同步会报告分页是否完整', async () => { + const previousFetch = globalThis.fetch; + const requests = []; + globalThis.fetch = async (_url, options) => { + requests.push(JSON.parse(options.body)); + const page = requests.length; + return new Response(JSON.stringify({ + result: [{ id: page, value: `候选值 ${page}` }], + has_next: page < 2, + }), { status: 200 }); + }; + try { + const batch = await fetchOzonDictionaryBatch('client', 'key', input); + assert.equal(batch.isComplete, true); + assert.deepEqual(batch.values.map((value) => value.id), [1, 2]); + assert.equal(requests[0].limit, 2000); + assert.equal(requests[1].last_value_id, 1); + } finally { + globalThis.fetch = previousFetch; + } +}); diff --git a/apps/worker/test/platform-catalog-mappers.test.mjs b/apps/worker/test/platform-catalog-mappers.test.mjs new file mode 100644 index 0000000..127ff61 --- /dev/null +++ b/apps/worker/test/platform-catalog-mappers.test.mjs @@ -0,0 +1,53 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { + flattenPlatformCategories, + mapPlatformAttributes, +} from '../src/platform-catalog-mappers.ts'; + +test('类目树叶子继承 description_category_id 并保留 type_id', () => { + const rows = flattenPlatformCategories([{ + description_category_id: 17027922, + category_name: '儿童玩具', + children: [{ type_id: 8229, type_name: '玩具类型' }], + }]); + + assert.equal(rows.length, 2); + assert.deepEqual(rows.map((row) => [row.external_category_id, row.external_type_id]), [ + ['17027922', '0'], + ['17027922', '8229'], + ]); + assert.equal(rows[1].parent_key, '17027922:0'); + assert.equal(rows[1].path, '儿童玩具 › 玩具类型'); + assert.equal(rows[1].is_active, true); +}); + +test('属性定义按 Ozon 属性 ID 和 complex ID 去重并保留约束', () => { + const rows = mapPlatformAttributes([{ + id: 85, + attribute_complex_id: 0, + name: '品牌', + type: 'String', + dictionary_id: 321, + is_required: true, + is_collection: true, + max_value_count: 1000, + category_dependent: false, + }, { + id: 85, + attribute_complex_id: 0, + name: '品牌（更新）', + type: 'String', + dictionary_id: 321, + is_required: true, + is_collection: true, + max_value_count: 2, + }]); + + assert.equal(rows.length, 1); + assert.equal(rows[0].platform_attribute_id, '85'); + assert.equal(rows[0].complex_id, '0'); + assert.equal(rows[0].value_type, 'dictionary'); + assert.equal(rows[0].max_value_count, 2); + assert.equal(rows[0].name, '品牌（更新）'); +}); diff --git a/docs/README.md b/docs/README.md index 82f94b1..2701f6d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,7 @@ | 产品需求 | [`requirements/`](./requirements/) | 页面、流程、字段和待确认事项 | | 基础架构 | [`architecture/`](./architecture/) | 多租户、平台、门店、水印、物流和定价的数据设计及 DDL | | 图片存储策略 | [`architecture/media-storage-strategy.md`](./architecture/media-storage-strategy.md) | 采集候选图片的按需物化、AI/水印处理与发布素材边界。 | +| 平台商品参考目录 | [`architecture/platform-product-reference-catalog.md`](./architecture/platform-product-reference-catalog.md) | 以平台为边界共享类目、属性和字典的架构与实施状态；门店差异层仅为未来预案。 | | 商品领域设计 | [`product/`](./product/) | 已有的多 SKU 商品编辑页、领域模型与 API 草案 | | 项目结构 | [`architecture/project-structure.md`](./architecture/project-structure.md) | pnpm monorepo 的目录、依赖关系与本地运行边界。 | | 外部平台资料 | [`integrations/`](./integrations/) | Ozon Seller API 的整理资料与适配依据 | diff --git a/docs/api/README.md b/docs/api/README.md index eb971fe..097b720 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -18,6 +18,7 @@ API 启动后会在 `/api-docs` 提供 Swagger UI，并在其 OpenAPI 文档中 | [`collection-and-extension.md`](./collection-and-extension.md) | 已设计 | 插件授权、采集写入、采集箱查询、素材转存与状态。 | | [`product-editor-and-publishing.md`](./product-editor-and-publishing.md) | M3.5 部分已实现 | 编辑上下文、完整 SKU 草稿、店铺切换、规格继承、AI 来源素材字段级合并，以及 Ozon 类目树、动态属性和关键词字典缓存同步；媒体、定价、AI 任务与首次上架仍待实现。 | | [`online-listings.md`](./online-listings.md) | 初版已设计 | 店铺独有的在线商品镜像、读取与异步同步；编辑/认领仍待讨论。 | +| [`platform-catalog-admin.md`](./platform-catalog-admin.md) | 已实现 | 全局系统管理员授权、平台参考源配置、类目/属性/字典读取、手动同步和任务状态。 | 旧的 [`../product/api.md`](../product/api.md) 是商品域的早期草案：已确认的产品规则可作为背景，但不能当作最终 HTTP 契约。后续商品模块会迁入本目录并替换其中的路径和细节。 @@ -34,7 +35,7 @@ API 启动后会在 `/api-docs` 提供 Swagger UI，并在其 OpenAPI 文档中 - 手机号、短信登录、邮箱验证、忘记密码、第三方登录、MFA 与设备管理； - 团队成员、工作空间切换和角色管理 UI； - Cookie 授权/保存； -- 平台、货币、字体、物流商、类目、佣金和汇率的后台维护接口。 +- 货币、字体、物流商、佣金和汇率的后台维护接口；平台类目维护已经使用独立系统管理员接口实现。 这些事项不会由首期客户端私自调用管理接口；运营数据由受控 seed、migration 或后台任务维护。 diff --git a/docs/api/platform-catalog-admin.md b/docs/api/platform-catalog-admin.md new file mode 100644 index 0000000..5125658 --- /dev/null +++ b/docs/api/platform-catalog-admin.md @@ -0,0 +1,56 @@ +# 平台类目与属性管理 API + +> 2026-09-18 新增契约。平台级目录供系统管理员维护；普通商品编辑器现有门店级 API 暂不改变。平台参考目录的归属见 [`platform-product-reference-catalog.md`](../architecture/platform-product-reference-catalog.md)。 + +## 权限与安全 + +- 本模块接口都要求有效登录会话。除 `GET /api/system/access` 外，必须具有数据库授予且未撤销的 `system_admin` 全局权限；工作空间 `owner/admin` 不等于系统管理员。未授权返回 `403 SYSTEM_ADMIN_REQUIRED`。 +- 系统管理员授权只能由受控数据库运维操作授予或撤销，不提供自助提权 HTTP 接口。权限变更在下一次请求时生效；前端菜单只是展示控制。 +- 目录、同步来源和任务均按 `platform_id` 分区，不使用客户工作空间的 `workspace_id` 承载平台任务。Ozon `Client-Id` / `Api-Key` 只经 TLS 提交至 API，Key 加密落库，不写日志、Outbox 或响应。 +- Wildberries 等其他平台可展示目录空状态；未实现适配器时发起同步返回 `422 PLATFORM_CATALOG_UNSUPPORTED`。 + +### 首位系统管理员初始化 + +系统管理员不能通过产品界面自助获得权限。目标用户先完成正常注册，再由数据库运维账号执行以下 SQL；应用运行账号 `atlas_app` 已被禁止修改该表： + +```sql +INSERT INTO atlas.system_admin_grants (user_id) +SELECT id FROM atlas.users WHERE lower(email) = lower('管理员邮箱') +ON CONFLICT (user_id) DO UPDATE SET revoked_at = NULL, granted_at = now(); +``` + +撤销权限时设置 `revoked_at = now()`，不要删除用户或改变其工作空间角色。授权和撤销均在下一次请求时生效。 + +## 接口 + +`GET /api/system/access` + +返回 `{ "data": { "is_system_admin": boolean } }`，供已登录 Web 决定是否展示系统管理入口；服务端权限判断仍以数据库授权为准。 + +`GET /api/system/platform-catalog/platforms` + +返回 `{ "data": [{ "id", "code", "name", "source": { "configured", "client_id_hint", "updated_at" }, "summary": { "category_count", "last_tree_sync_at", "last_error" } }] }`。`client_id_hint` 仅为脱敏末尾字符，不返回 API Key、密文或指纹。 + +`PUT /api/system/platform-catalog/platforms/{platform_id}/source` + +Body：`{ "client_id": "...", "api_key": "..." }`。仅 Ozon 适配器接受当前配置；重复提交同一凭据不产生新版本或重复任务。首次配置或更换凭据时返回脱敏来源状态，并为该平台排队一次类目树同步；更换后旧版本的未完成任务不得用新密钥执行。 + +`GET /api/system/platform-catalog/platforms/{platform_id}/categories` + +返回当前平台的全部树节点 `{ id, parent_id, external_category_id, external_type_id, name, path, is_active, synced_at }`；按父子关系在客户端构建树，目录节点可展开，仅可发布类型叶子用于查看属性。 + +`GET /api/system/platform-catalog/platforms/{platform_id}/categories/{category_id}/attributes` + +返回该类型的属性定义 `{ id, platform_attribute_id, complex_id, name, description, group_name, value_type, is_required, is_aspect, is_collection, max_value_count, dictionary_id, is_active, synced_at, dictionary_value_count }`。`category_id` 不属于所选平台时返回 404。 + +`GET /api/system/platform-catalog/platforms/{platform_id}/attributes/{attribute_id}/values?q={keyword}&page={number}` + +仅字典属性可查；`page` 从 1 开始、每页最多 100，返回 `{ "data": [{ "id", "external_value_id", "value", "info", "picture" }], "meta": { "page", "page_size", "total", "is_complete" } }`。搜索只查 Atlas 缓存；`is_complete=false` 表示已缓存部分候选值，不表示 Ozon 字典只有这些值。 + +`POST /api/system/platform-catalog/platforms/{platform_id}/syncs` + +Headers：`Idempotency-Key`（UUID）必填。Body：`{ "scope": "tree" | "attributes" | "dictionary", "category_id"?: "uuid", "attribute_id"?: "uuid" }`。树同步不带其他 ID；属性同步需要当前平台的可发布 `category_id`；字典同步需要该类型下带字典的 `attribute_id`。同作用域已有 queued/running 任务时返回已有任务，并将本次幂等键持久映射到该任务；同一用户重试不会在原任务完成后意外创建第二个任务。成功排队返回 `202` 与 `{ "data": { "id", "platform_id", "scope", "status", "trigger", "created_at" } }`。同步由 Worker 异步执行，失败保留上次成功缓存。 + +`GET /api/system/platform-catalog/platforms/{platform_id}/syncs?limit={number}` + +返回该平台最近的同步任务（最多 50 条），包括作用域、触发方式、状态、开始/完成时间、数量摘要及脱敏错误。系统管理员可据此查看手动和定时更新结果。 diff --git a/docs/api/product-editor-and-publishing.md b/docs/api/product-editor-and-publishing.md index 9a70890..3aa5fc5 100644 --- a/docs/api/product-editor-and-publishing.md +++ b/docs/api/product-editor-and-publishing.md @@ -1,9 +1,11 @@ # 商品编辑与首次上架 API -> M3.0 已实现第 1 节的 `POST /editor-contexts` 和 `GET /editor` 基础读模型，以及对应数据库归属约束。M3.1 已实现产品基础字段、当前平台文案、SKU 与 `offer_id` 的原子草稿保存及双版本并发控制。M3.2 已实现目标店铺候选与切换语义、父/子 SKU 的实物/包装规格继承、规格轴、SKU 复制和当前上架状态读模型。M3.3/M3.3.1 已实现 AI 来源素材的字段级合并、原子保存、复采变化提示与 AI 输入读模型。M3.4 已实现本地类目候选、动态属性 schema/字典、属性草稿与类目切换后的未映射保留。M3.5 在门店 Ozon 凭据验证成功后同步该门店的中文类目树，编辑器只读取当前目标门店缓存；属性和关键词字典仍按需同步。媒体选择、定价、AI 任务与发布仍是冻结契约，尚未实现。 +> M3.0 已实现第 1 节的 `POST /editor-contexts` 和 `GET /editor` 基础读模型，以及对应数据库归属约束。M3.1 已实现产品基础字段、当前平台文案、SKU 与 `offer_id` 的原子草稿保存及双版本并发控制。M3.2 已实现目标店铺候选与切换语义、父/子 SKU 的实物/包装规格继承、规格轴、SKU 复制和当前上架状态读模型。M3.3/M3.3.1 已实现 AI 来源素材的字段级合并、原子保存、复采变化提示与 AI 输入读模型。M3.4 已实现本地类目候选、动态属性 schema/字典、属性草稿与类目切换后的未映射保留。M3.5 在门店 Ozon 凭据验证成功后同步该门店的中文类目树，编辑器只读取当前目标门店缓存；属性和字典按需同步。媒体选择、定价、AI 任务与发布仍是冻结契约，尚未实现。 > 此处的商品始终是采集箱内的 Atlas 草稿。所有平台范围接口要求 `X-Atlas-Platform-Id`。商品通用资料可以跨平台复用；`product_platform_profile`、SKU 首次导入状态和在线商品不能跨平台/门店复用。 +> 架构迁移说明：2026-09-18 已决定将类目/商品类型树、属性定义和字典候选值迁至[平台级参考目录](../architecture/platform-product-reference-catalog.md)，同一平台所有门店共用，不维护门店差异层。本文件以下字段、UUID 和同步端点仍描述**当前已实现的门店级契约**；迁移前不得把它们解释为已经共享。未来调整须先修订本契约、共享类型和测试。 + ## 1. 进入编辑与读取编辑器 `POST /api/collection-items/{collection_item_id}/editor-contexts` @@ -130,15 +132,15 @@ Headers：`If-Match`、`Idempotency-Key` 必填。Body：`{ "target_store_id": " `GET /api/product-platform-profiles/{profile_id}/attribute-schema` -当前 profile 必须已有类目。返回本地同步的字段 schema：`platform_attribute_id`、`complex_id`、名称、`value_type`、`is_required`、`is_collection`、`max_value_count`、`dictionary_id` 与 `is_aspect`。可带 `?category_id={uuid}` 预览尚未保存的新类目 schema；该类目仍必须属于当前平台且为活动状态。类别未选返回 `422 CATEGORY_REQUIRED`。 +当前 profile 必须已有类目。返回本地同步的字段 schema：`platform_attribute_id`、`complex_id`、名称、`value_type`、`is_required`、`is_collection`、`max_value_count`、`dictionary_id`、`is_aspect` 与 `editor_field`。`editor_field` 只按 Ozon 属性 ID 计算，不允许按名称或翻译文本匹配：品牌 `85 → brand`、型号名称 `9048 → model`、类型 `8229 → category`、主题标签 `23171 → tags`、JSON 富内容 `11254 → rich_content`、简介/产品描述 `4191 → description`，其他 ID 返回 `null`。非空字段由编辑器已有控件承载，动态属性区不得重复展示或加载字典；服务端会兼容但忽略旧客户端重复提交的映射属性。可带 `?category_id={uuid}` 预览尚未保存的新类目 schema；该类目仍必须属于当前平台且为活动状态。类别未选返回 `422 CATEGORY_REQUIRED`。 `GET /api/product-platform-profiles/{profile_id}/attribute-dictionaries/{dictionary_id}?q={keyword}&cursor={opaque}` -返回本地同步的字典值 `{ items: [{ value_id, value }], next_cursor }`；可同样传 `category_id` 读取尚未保存的新类目。字典必须属于当前类目 schema，否则返回 `422 ATTRIBUTE_DICTIONARY_INVALID`。首期只读取缓存，不让前端直接持有 Ozon 密钥或直接调用 Ozon。 +返回本地同步的字典值 `{ items: [{ value_id, value }], next_cursor }`，每页最多 200 项；传入 `next_cursor` 可继续读取，`null` 表示本地缓存已读完。可同样传 `category_id` 读取尚未保存的新类目。字典必须属于当前类目 schema，否则返回 `422 ATTRIBUTE_DICTIONARY_INVALID`；无效游标返回 `400 VALIDATION_FAILED`。接口只读取缓存，不让前端直接持有 Ozon 密钥或直接调用 Ozon。 `GET /api/product-platform-profiles/{profile_id}/category-options?q={keyword}` -返回当前平台的缓存类目树节点，包含本地 UUID、父节点 UUID、平台外部类目/类型 ID、名称、路径和活动状态。选择类目本身不立即写库，随下一次 `editor-draft` 原子保存。缓存为空时客户端显示“准备中”，不提供同步按钮；Worker 仅使用显式配置的共享 Ozon 缓存源预热该树。 +返回当前目标门店的缓存类目树节点，包含本地 UUID、父节点 UUID、平台外部类目/类型 ID、名称、路径和活动状态。选择类目本身不立即写库，随下一次 `editor-draft` 原子保存。缓存为空时客户端显示“准备中”，编辑器不提供同步按钮；当前 Worker 在门店凭据验证成功后用该门店凭据同步树。平台级共享参考源属于待迁移目标，不是本接口的现有行为。 `POST /api/product-platform-profiles/{profile_id}/attribute-schema-syncs?category_id={uuid}` @@ -146,11 +148,48 @@ Headers：`If-Match`、`Idempotency-Key` 必填。Body：`{ "target_store_id": " `POST /api/product-platform-profiles/{profile_id}/attribute-dictionaries/{dictionary_id}/syncs?category_id={uuid}&q={keyword}` -按关键词（至少两个字符）创建 `store_attribute_dictionary_sync` operation，Worker 使用该门店的 Ozon 字典搜索接口并 upsert 命中的本地值。不会为打开一个字段而全量下载大字典；前端先读本地缓存，缺少结果时由用户明确选择“从 Ozon 搜索”。 +不传 `q` 时创建 `store_attribute_dictionary_sync` operation，Worker 从该门店的 Ozon 字典值接口按游标读取首批最多 1000 项并 upsert 本地缓存；打开字典控件时可按需触发，当前类目下同一字典只自动触发一次，切换类目后重新评估，不在加载类目时同时同步全部字典。传入 `q` 时至少两个字符，Worker 使用 Ozon 字典搜索接口 upsert 命中的值；前端输入关键词后延迟触发，以便从超过首批范围的大字典中继续查找。所有字典属性均由 schema 的 `dictionary_id` 驱动，不根据中文属性名维护固定选项。Ozon 密钥始终留在 Worker。 `GET /api/product-platform-profiles/{profile_id}/validation` -返回 profile 与每个未删除 SKU 的本地首次上架校验：商品型号、类目/属性、标题、目标店铺、用户填写的 offer ID、确认的包装规格、已确认定价快照、图片、格式/数量及平台特有规则。已导入 SKU 单独标记 `not_publishable_again`，而不是当作校验失败。 +返回 profile 与每个未删除 SKU 的本地首次上架校验：标题、型号、品牌、类目/属性、目标店铺、用户填写的 offer ID、确认的包装规格、已确认定价快照、图片、格式/数量及平台特有规则。已导入 SKU 单独标记 `not_publishable_again`，而不是当作校验失败。 + +响应 `data`： + +```json +{ + "ready": false, + "profile": { + "ready": false, + "issues": [ + { + "code": "OZON_ATTRIBUTE_REQUIRED", + "field": "attributes.10001.0", + "message": "请填写最小儿童年龄", + "platform_attribute_id": "10001" + } + ] + }, + "variants": [ + { + "variant_id": "uuid", + "display_name": "红色", + "status": "blocked", + "ready": false, + "issues": [ + { + "code": "OZON_ATTRIBUTE_REQUIRED", + "field": "variants.uuid.attributes.10096.0", + "message": "请填写颜色", + "platform_attribute_id": "10096" + } + ] + } + ] +} +``` + +`profile.issues` 包含商品级基础信息、类目 schema 和 `is_aspect=false` 的必填属性；每个 SKU 的 `issues` 包含货号、价格、有效包装规格、图片和 `is_aspect=true` 的必填属性。只有 `confirmation_status=confirmed` 且包含非空值的属性满足发布要求。`ready=true` 要求 profile 无问题、至少存在一个未上架 SKU，且全部未上架 SKU 均通过校验。 ## 4. SKU 定价确认 diff --git a/docs/api/stores-and-platforms.md b/docs/api/stores-and-platforms.md index 1390bed..38fd0e0 100644 --- a/docs/api/stores-and-platforms.md +++ b/docs/api/stores-and-platforms.md @@ -152,6 +152,8 @@ Headers：`Idempotency-Key` 必填。手动重试凭据校验，返回 `202` 与 Headers：`Idempotency-Key` 必填。同步请求 Ozon `POST /v1/description-category/tree` 并写入目标门店缓存；只有完整响应成功落库后才返回 `200` 与类目数量。必须是凭据已验证的 Ozon 门店，否则返回 `422 STORE_CREDENTIAL_UNAVAILABLE`。Ozon 请求或落库失败返回脱敏错误，旧缓存保持不变。此手动操作不经 Worker 或队列，API Key 仅在服务端请求期间短暂存在。 +> 此端点是现有门店级能力，不是未来系统管理员同步入口。迁移至[平台级参考目录](../architecture/platform-product-reference-catalog.md)时，须另行修订/废弃该同步语义；管理员操作应按平台排入统一后台任务，不复用本同步 HTTP 路径直接请求 Ozon。 + `POST /api/stores/{store_id}/warehouse-syncs` Headers：`Idempotency-Key` 必填。触发 Ozon `POST /v1/warehouse/list` 同步，返回 `202` 与 operation。凭据无效时不调用平台，返回 `422 STORE_CREDENTIAL_UNAVAILABLE`。 diff --git a/docs/architecture/platform-product-reference-catalog.md b/docs/architecture/platform-product-reference-catalog.md new file mode 100644 index 0000000..146bf2e --- /dev/null +++ b/docs/architecture/platform-product-reference-catalog.md @@ -0,0 +1,46 @@ +# 平台级商品参考目录的归属与维护决策 + +> 决策日期：2026-09-18。状态：平台参考目录、系统管理员维护 API/页面及定时同步链路已经实现；商品编辑器的门店级引用尚未迁移。当前商品编辑契约仍以 [`product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 为准。本决策取代 2026-09-10「每个门店完整保存一份类目、属性和字典」的目标设计，不抹去其实现历史。 + +## 1. 依据与边界 + +Ozon 的[类目树接口](https://docs.ozon.ru/api/seller/zh/#operation/DescriptionCategoryAPI_GetTree)请求体仅以 `language` 选择返回语言；[属性接口](https://docs.ozon.ru/api/seller/zh/#operation/DescriptionCategoryAPI_GetAttributes)以 `description_category_id + type_id + language` 查询属性；[字典值接口](https://docs.ozon.ru/api/seller/zh/#operation/DescriptionCategoryAPI_GetAttributeValues)还要求 `attribute_id`，并用 `last_value_id` 分页。属性响应的 `category_dependent` 指示字典值是否随类目变化。三个接口都需要卖家 `Client-Id + Api-Key`。 + +Atlas 本阶段明确采用**平台级参考数据**：同一 `platform_id` 下的所有门店共用一套类目/商品类型树、类型属性定义和字典候选值，不再按门店复制，也**不建立或维护门店差异层**。Ozon 文档未保证所有卖家账号返回完全一致；“同平台门店共用”是本阶段产品假设，而不是 Ozon 官方保证。若实际发现账号差异，再评审下文保留的扩展方案，不提前实现。 + +## 2. 数据归属 + +| 数据 | 目标归属与键 | 约束 | +|---|---|---| +| 类目/商品类型树 | `platform_id` 下的一份平台目录，名称按语言保存；Ozon 可发布叶子使用 `description_category_id + type_id` 标识 | 同平台门店读取相同的目录节点、父子关系与 `disabled`；不以名称或单独 `type_id` 判等，也不复制到各门店 | +| 类型属性定义 | `platform_id + 平台类目/类型键 + 属性键 + 语言/版本` | Ozon 的 `is_required`、`is_aspect`、`dictionary_id`、类型和数量限制属于其平台适配数据；其他平台由各自适配器定义外部标识和规则 | +| 字典候选值 | `platform_id + 平台类目/类型键 + 属性键 + 字典键 + 语言 + 值键`；记录完整/部分同步状态 | Ozon 的 `category_dependent=false` 可供后续去重，但不能仅以 `dictionary_id + value_id` 跨类目或跨平台合并 | +| 门店连接与商品/SKU 已填属性 | 原工作空间、门店、商品、profile、SKU | 凭据、上架结果、用户填报值、确认状态和发布快照仍是业务数据，按工作空间隔离；它们不是平台参考目录 | + +平台参考表以 `platform_id` 隔离 Ozon、未来的 Wildberries 等平台，只保存对应平台可复用的参考元数据；不存客户凭据、商品、价格或店铺专有数据，也不使用 `store_id` 作为目录分区键。所有门店连接和商品引用仍须满足 [`development-collaboration-contract.md`](../project/development-collaboration-contract.md) 的工作空间外键与 RLS 约束。读 API 依页头平台上下文过滤，不能跨平台混用 ID，也不能据此枚举其他店铺信息。 + +目标交互上，切换到**同一平台**的另一个门店不应清空已选类目和属性；切换平台则必须重新选择该平台的类目并按新平台 schema 校验。新门店凭据验证只处理该门店连接，不为其复制或重新同步整套平台目录；若平台目录尚未准备好，由平台级任务补齐。当前门店级外键尚未迁移前仍维持现有切换行为。 + +## 3. 同步方案：自动为主、人工为辅 + +统一的后台同步服务按 `platform_id` 负责定时任务、首次缺失时的补齐和管理员手动请求。三种触发方式都创建有权限校验、幂等去重的 `platform_catalog_sync_runs + platform_catalog_outbox_events`；这是不带 `workspace_id` 的全局任务事实，不能借用租户 `operations/outbox_events`。Worker 通过平台适配器读取服务端安全存储的参考源凭据并调用对应平台。浏览器、日志、run 和 outbox 载荷不包含 API Key。管理员手动同步不得在 HTTP 请求内直接访问平台或绕过同一套限流、审计与事务发布流程。 + +1. **同步来源**：每个平台分别配置 Atlas 专用的参考源凭据及适配器；Ozon 首期使用专用参考门店凭据作为技术采集身份，而非普通客户工作空间门店。设置最小授权、密钥轮换、失效告警与备用源，不能未经授权借用客户门店密钥。若暂无专用凭据，保持现有门店级链路，待来源配置完成后迁移。 +2. **基线调度**：当前实现为类目树和类型属性成功后 24 小时内不重复、字典成功后 7 天内不重复；调度器每 60 秒扫描，每个平台最多 6 个活动任务。BullMQ 最多尝试 5 次并从 5 秒开始指数退避。当前固定按树、属性、字典排序，在数千类型下会造成字典饥饿；后续必须改为属性/字典配额轮转，并增加近期访问优先级。具体间隔是 Atlas 运营参数，不是 Ozon 文档承诺的 TTL。 +3. **管理员页面**：按平台展示参考源状态、树、属性、字典候选值、最后成功时间、失败详情、排队任务和「同步类目树 / 指定类目属性 / 指定字典」操作。手动动作必须受系统管理员权限控制、记录操作者，并返回异步任务；页面不展示密钥明文。当前实现位于 `/system/platform-catalog`，全局系统管理员授权独立于工作空间角色。 +4. **读路径**：正常用户只读 Atlas 缓存。首次缺失时可排队补齐并显示准备中；已有数据过期时优先提供上次成功快照并后台更新。不能在每次打开编辑器或下拉框时同步请求 Ozon。大字典搜索按规范化关键词及上述字典作用域共享缓存，并去重并发补齐。 +5. **原子性与监控**：P0 按平台及树、类型属性、字典作用域在单事务内 upsert，提交前读取方继续看到旧数据；失败保留上次成功缓存。仅在确认完整分页完成后才处理消失的字典值，部分同步记录 `is_complete=false`。当前尚未实现不可变版本快照、内容哈希、`next_refresh_at`、连续失败告警和异常删减保护，这些属于上线前可靠性加固，不能在文档中误记为已完成。 + +Ozon 字典分页每次最多 2000 个值；[搜索接口](https://docs.ozon.ru/api/seller/zh/#operation/DescriptionCategoryAPI_SearchAttributeValues)要求至少两个字符、每次最多 100 个值。搜索命中只是局部候选，不能证明字典已完整同步。当前平台任务单次最多读取 5 页（10000 项）；超过上限会正确保留为部分缓存，但续传游标尚未实现。 + +## 4. 门店差异层的未来预案（本阶段不实施） + +本阶段按同平台所有门店使用相同目录、属性定义和候选值实施：**不创建门店差异表，不按门店同步参考目录，不在读取或发布校验时叠加门店覆盖规则**。门店凭据状态和某次发布的失败原因仍按门店记录，但不据此自动改写平台共享目录。 + +如果联调或线上证据表明确有账号专属的可售状态、属性或字典差异，再单独提出迁移：可按 `workspace_id + store_id` 建门店覆盖层，或按市场/卖家分组收窄共享范围，并制定差异检测与回退策略。该预案只保留扩展方向，不是当前开发任务或上线前置条件。 + +## 5. 从现有实现迁移 + +当前 `022_store_catalog_cache.sql` 的 `store_product_categories`、属性和字典表，以及 profile 的 `store_product_category_id` 外键都是已上线的门店级事实，**本次文档决策不改变它们**。旧 `001_foundation.sql` / `021_product_category_attribute_schema.sql` 虽已有平台级表，但原字典唯一键不足以表达按类目/类型变化的字典；不能直接当成最终系统目录复用。 + +迁移 `024_platform_catalog_management.sql` 已补齐以 `platform_id` 为作用域的参考来源、候选值和同步任务表，**没有建立门店差异表**；API、Worker 和管理页面已经按该作用域工作。下一步仍需以 Ozon 外部 ID 对照旧门店记录、回填平台目录。草稿/接口迁移应先提供兼容读写与可回滚映射，逐步改为平台目录引用，最后经校验和维护者批准再清理冗余门店缓存。现有商品编辑 HTTP 路径、UUID 含义和门店同步 operation 尚未改变；任何契约变更须先更新 `docs/api/`、共享类型和测试。Wildberries 等新平台应新增平台适配器及自己的外部 ID 映射，不复用 Ozon 的 `description_category_id + type_id` 语义。 diff --git a/docs/architecture/product-domain-data-model.md b/docs/architecture/product-domain-data-model.md index b8a34d2..4b4baaa 100644 --- a/docs/architecture/product-domain-data-model.md +++ b/docs/architecture/product-domain-data-model.md @@ -16,6 +16,8 @@ `products` / `product_variants` 只服务采集箱商品，保存来源、采购和跨平台可复用资料。`platform_listings` 则是目标平台、目标门店的实际商品镜像；它不能跨平台或跨门店复用，即使它关联了 Atlas SKU。`product_platform_profiles.market_code` 表示当前平台业务上下文，首期取平台默认 `RU`，不从门店派生。 +类目/商品类型、属性定义和字典候选值是待迁移的**平台级**参考数据：同一平台所有门店共用，不跨 Ozon、Wildberries 等平台混用，也不在本阶段维护门店差异层。门店连接与商品/SKU 已填值仍按工作空间隔离。现有 `022_store_catalog_cache.sql` 的门店级缓存和 profile 外键继续有效，目标模型及迁移边界见 [`platform-product-reference-catalog.md`](./platform-product-reference-catalog.md)。 + ## 2. 关键关系与状态 | 表 | 粒度 | 核心约束 | diff --git a/docs/integrations/ozon-seller-api/02-category-tree.md b/docs/integrations/ozon-seller-api/02-category-tree.md index 782961a..a30b8ea 100644 --- a/docs/integrations/ozon-seller-api/02-category-tree.md +++ b/docs/integrations/ozon-seller-api/02-category-tree.md @@ -29,7 +29,7 @@ | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| -| language | string | 可选 | 语言代码，可选值：`DEFAULT`（英文）、`RU`（俄文）、`EN`（英文）、`ZH_HANS`（简体中文）。默认 `DEFAULT` | +| language | string | 可选 | 语言代码：`DEFAULT`（默认俄文）、`RU`（俄文）、`EN`（英文）、`TR`（土耳其文）、`ZH_HANS`（简体中文） | --- @@ -105,13 +105,13 @@ ⑤ 选中后保存 description_category_id + type_id ``` -### 场景 2：服务端门店缓存 +### 场景 2：Atlas 平台级参考缓存（目标架构，未实施） ``` -① 门店 `Client-Id` + `Api-Key` 验证成功后拉取完整类目树（Atlas 使用 `ZH_HANS`） -② 递归保存每一层及其父子关系，按门店存入本地类目缓存；不与其他门店混用 -③ 同步失败由后台任务重试，已验证的门店凭据不因此改为无效 -④ 用户选类目时直接查当前目标门店缓存，不频繁调 API +① 按平台的定时任务用 Atlas 专用参考源凭据拉取完整类目树（Ozon 首期 `ZH_HANS`） +② 原子更新该平台共享目录；同平台门店读取同一份树，不建门店覆盖层 +③ 同步失败保留上次成功版本，由后台任务重试并告警 +④ 用户选类目时只查 Atlas 缓存，不频繁调 Ozon API ``` --- @@ -213,30 +213,7 @@ function toTreeData(nodes: CategoryNode[]): any[] { ## 缓存策略 -### 按门店缓存（Atlas 方案） - -```python -# 类目数据的读取凭证属于门店。即使结构通常相近，也必须按 store_id 隔离缓存。 -# 验证成功或缓存失效时，由 Worker 用该门店凭证拉取完整树并递归写库。 -# 前端只读取该门店的缓存，绝不携带或读取 Client-Id / Api-Key。 -async def get_store_category_tree(store_id: str): - cached = await load_store_category_cache(store_id) - if cached and cached.is_valid: - return cached.tree - - await enqueue_store_catalog_sync(store_id) - raise CatalogCachePreparingError(store_id) -``` - -### 按需更新 - -```python -# 用户在门店管理中手动刷新时，API 同步请求 Ozon 并在成功后原子替换目标门店缓存。 -# 请求或落库失败会保留旧缓存并向用户返回错误，不经 Worker 队列。 -async def refresh_store_category_tree(store_id: str): - tree = await fetch_category_tree_for_store(store_id) - return await replace_store_category_cache_atomically(store_id, tree) -``` +目标方案见 [`platform-product-reference-catalog.md`](../../architecture/platform-product-reference-catalog.md)：每个平台分别维护共享目录；定时自动同步与系统管理员手动触发共用异步任务、原子版本切换和失败保留旧版；前端只读 Atlas 缓存。当前运行中的门店级同步仍见下方「Atlas 当前集成」，不能把目标方案当作已经上线。 --- @@ -244,15 +221,15 @@ async def refresh_store_category_tree(store_id: str): ### Q1: 类目树很大吗？ -**A**: 约 **1-2 万个类目节点**，JSON 约 3-5MB。完整树在一次响应中以递归 `children` 返回，首次拉取需几秒，后续从门店缓存读取。 +**A**: 完整树在一次响应中以递归 `children` 返回；具体节点数和响应大小以实际同步记录为准，后续从 Atlas 缓存读取。 ### Q2: 多久更新一次？ -**A**: Ozon 不定期新增类目（月级别），建议 **24h TTL + 手动刷新入口**。 +**A**: Ozon 接口未规定 Atlas 的缓存 TTL。目标架构建议由后台每日检查树，并提供管理员手动排队同步入口；间隔可按运行量调整，见[架构决策](../../architecture/platform-product-reference-catalog.md)。 ### Q3: 不同语言的类目树结构一样吗？ -**A**: 通常 `description_category_id` / `type_id` 相同，仅 `category_name` / `type_name` 翻译不同。Atlas 统一由 Worker 为每个门店缓存 `ZH_HANS`，前端直接读取该门店缓存，不能为展示语言绕过缓存直接携带门店密钥请求 Ozon。 +**A**: 接口支持语言参数，不应未经验证就假定各语言的 ID 和翻译映射完全相同。当前 Worker 为每个门店缓存 `ZH_HANS`；目标是由 Ozon 平台参考源统一缓存该语言，同平台所有门店共用。前端不能携带门店密钥直连 Ozon。 ### Q4: `type_id=0` 是什么意思？ @@ -266,6 +243,7 @@ async def refresh_store_category_tree(store_id: str): - **API**：按当前目标门店返回缓存的扁平节点（包含 `parent_id`）；不会将 `Client-Id` 或 `Api-Key` 返回给浏览器。 - **前端**：根据 `parent_id` 重建任意深度的 Cascader；目录可展开，只有可发布的叶子能写入商品草稿。 - **调试**：若需要查看 Ozon 原始响应，应由受权限保护的服务端调试能力获取并脱敏展示；浏览器不得直接用门店密钥请求 Ozon。 +- **迁移目标**：平台级共享目录和统一异步管理同步尚未实现；本阶段不维护门店差异层，见[架构决策](../../architecture/platform-product-reference-catalog.md)。 --- diff --git a/docs/integrations/ozon-seller-api/03-category-attributes.md b/docs/integrations/ozon-seller-api/03-category-attributes.md index b487fe2..cbaa1a8 100644 --- a/docs/integrations/ozon-seller-api/03-category-attributes.md +++ b/docs/integrations/ozon-seller-api/03-category-attributes.md @@ -155,7 +155,7 @@ | description_category_id | integer | ✅ 是 | 类目 ID | | type_id | integer | ✅ 是 | 商品类型 ID | | language | string | 可选 | 语言代码 | -| limit | integer | 可选 | 每页数量，最大 **5000**，默认 1000 | +| limit | integer | ✅ 是 | 每页数量，范围 **1–2000**；Atlas 当前首批请求使用 1000 | | last_value_id | integer | 可选 | 分页游标（上一页最后一个值的 `id`），首页传 0 | --- @@ -209,7 +209,7 @@ async def fetch_all_values(attribute_id, category_id, type_id): "description_category_id": category_id, "type_id": type_id, "language": "RU", - "limit": 5000, + "limit": 2000, "last_value_id": last_id } ) @@ -431,48 +431,9 @@ if missing: ## 7. 缓存策略 -### 属性列表缓存 +Ozon 只定义查询参数和分页规则，不规定 Atlas 的 TTL。2026-09-18 的[架构决策](../../architecture/platform-product-reference-catalog.md)将属性定义和字典候选值设为平台级参考数据：同一平台所有门店共用，本阶段不维护门店差异层；此方案尚未实现。当前代码仍以门店、类目和类型为作用域按需同步，用户从 Atlas 本地缓存读取。 -```python -# 按 (category_id, type_id) 缓存 -# TTL 7 天（属性变化极少） - -from functools import lru_cache - -@lru_cache(maxsize=500) -async def get_attributes_cached(category_id: int, type_id: int): - # 先查数据库 - cached = await db.query(CategoryAttribute).filter_by( - description_category_id=category_id, - type_id=type_id - ).all() - - if cached: - return cached - - # 未缓存，调 API - attrs = await fetch_category_attributes(category_id, type_id) - - # 写入数据库 - await save_attributes_to_db(attrs) - - return attrs -``` - -### 字典值缓存（按需） - -```python -# 字典值可能很大（数万条），不全量缓存 -# 策略：用户映射到某属性时，才拉该属性的字典（且优先用 /search） - -async def get_attribute_values(attr_id, category_id, type_id, keyword=None): - if keyword: - # 有关键词 → 搜索接口（limit 100） - return await search_values(attr_id, category_id, type_id, keyword) - else: - # 无关键词 → 拉全量（分页，存数据库） - return await fetch_all_values(attr_id, category_id, type_id) -``` +目标同步方式：对活跃 `description_category_id + type_id` 的属性定义定期后台复核；字典候选值至少以类目、类型、属性、字典 ID 和语言限定作用域。`category_dependent=false` 可以作为进一步去重的依据，但在跨账号/跨类目验证前不能只以 `dictionary_id` 合并。小字典可完整分页并标记 `complete`；大字典先保存常用页与搜索命中，并明确标记 `partial`。搜索结果不是全集，不能据此清理未命中的旧值。定时和管理员手动同步必须共用异步任务链路，成功后原子切换版本，失败保留上次成功值。 --- diff --git a/docs/product/ozon-dynamic-attributes-and-sku-form-plan.md b/docs/product/ozon-dynamic-attributes-and-sku-form-plan.md index a594133..d281a7c 100644 --- a/docs/product/ozon-dynamic-attributes-and-sku-form-plan.md +++ b/docs/product/ozon-dynamic-attributes-and-sku-form-plan.md @@ -1,10 +1,10 @@ # Ozon 动态属性与 SKU 填报改造方案 -> 状态：待实施设计，记录于 2026-09-18。本文描述目标交互、数据归属和校验边界；在对应 API 契约、共享类型与实现完成更新前，不代表当前接口已经具备这些行为。 +> 状态：P0 已于 2026-09-18 实现，P1/P2 待实施。当前已完成必填展示、通用/变体属性分区、宽松草稿保存及服务端逐 SKU 校验；新 SKU 首次保存时关联属性、结构化字典值与发布闭环仍以后续阶段为准。 ## 1. 目标与原则 -Ozon 商品的必填属性由目标门店、`description_category_id` 与 `type_id` 对应的实时类目 schema 决定。编辑器不得为儿童玩具、服装、食品等类目分别硬编码字段，而应使用 Ozon 返回的 `is_required`、`is_aspect`、`dictionary_id`、`is_collection`、`max_value_count`、`type` 与复杂属性信息驱动展示、填报和发布校验。 +Ozon 商品的必填属性由 `description_category_id` 与 `type_id` 对应的类目 schema 决定；目标架构中，同一 Ozon 平台的所有门店共用该 schema。编辑器不得为儿童玩具、服装、食品等类目分别硬编码字段，而应使用 Ozon 返回的 `is_required`、`is_aspect`、`dictionary_id`、`is_collection`、`max_value_count`、`type` 与复杂属性信息驱动展示、填报和发布校验。目标参考数据归属见[架构决策](../architecture/platform-product-reference-catalog.md)；当前实现仍读门店级缓存。 页面继续以 Atlas 商品和 SKU 为编辑主体：主要信息保留稳定的商品级字段，Ozon 类目属性按通用属性和 SKU 变体属性拆分。保存草稿允许信息不完整；首次上架必须由服务端按当时有效的类目 schema 重新校验。 @@ -65,6 +65,8 @@ SKU 中的 Ozon 必填变体属性同样只在 Label 前显示红色 `*`。父 3. 同步成功后重新构建动态属性表单。 4. 页面显示类目路径、商品类型和最后同步时间，并提供失败后的重试入口。 +以上描述当前门店级 schema 的获取流程。迁移到平台级参考目录后，直接读取当前平台共享 schema，不叠加门店差异；缺失或过期时由统一后台任务补齐，普通用户不直接触发 Ozon 请求，管理员重试与定时任务共用同一队列。接口字段及草稿外键在 `docs/api/` 更新前不改变。 + 属性 schema 响应除现有字段外，计划补充： ```ts @@ -175,6 +177,10 @@ GET /api/product-platform-profiles/{profile_id}/validation - 保存草稿允许不完整，发布校验阻断缺失项。 - 服务端补齐通用和逐 SKU 必填属性检查。 +实现状态：已完成。编辑器会在选定类目后立即加载 schema，商品级必填属性始终显示在「产品属性」，SKU 级必填属性始终显示在对应 SKU 卡片；保存草稿不因缺少必填值失败，`validation` 接口按商品与 SKU 返回结构化缺失项。 + +类目 schema 中由编辑器已有控件承载的字段通过 `editor_field` 显式绑定，不在动态属性区重复展示，也不重复加载其字典。绑定只允许按 Ozon 属性 ID：品牌 `85`、型号名称 `9048`、类型 `8229`、主题标签 `23171`、JSON 富内容 `11254`、简介/产品描述 `4191`；禁止使用名称或翻译文本猜测。后续发布适配器必须据此生成 Ozon 所需字段，不能要求用户重复填写。 + ### P1：SKU 数据结构 - 属性草稿调整为 `common_attributes + variants[].attributes`。 @@ -185,7 +191,7 @@ GET /api/product-platform-profiles/{profile_id}/validation ### P2：发布闭环 -- 实现 validation 接口及发布接口复用。 +- 发布接口复用现有 validation 校验结果。 - 按 SKU 生成 `/v3/product/import` 的 `items[]`。 - 正确生成普通属性与复杂属性。 - 固化发布快照并将 Ozon 错误回填到 SKU/属性。 diff --git a/docs/product/product-ai-editor.md b/docs/product/product-ai-editor.md index b6fcb44..af12de3 100644 --- a/docs/product/product-ai-editor.md +++ b/docs/product/product-ai-editor.md @@ -29,7 +29,7 @@ 上架状态是“当前平台 + SKU”维度：`未上架`、`处理中`、`上架失败`、`已上架`。SPU 在当前平台的状态由未删除 SKU 汇总为 `未上架`、`已部分上架`、`已上架`。用户可勾选任意未上架 SKU 执行首次上架；已上架 SKU 不显示上架选择，也不发送更新请求。编辑已上架 SKU 时，保存按钮旁必须提示“仅保存 Atlas 草稿，不会更新 Ozon 商品”。 -前端根据当前目标门店、本地同步的商品类目 schema 渲染属性控件、必填提示、字典选择、多值限制及变体属性。门店 Ozon 凭据验证成功后，Worker 使用该门店凭据同步中文类目树；缓存为空时编辑器显示准备中状态，用户不能在编辑页发起树同步。选中类目但 schema 缺失时，仍可显式同步该类目属性。字典控件先搜索本地缓存，输入至少两个字符仍无结果时，可显式从 Ozon 搜索并缓存命中值。`is_aspect=true` 在编辑器中按 SKU 展示，其余属性按商品展示；保存仍由服务端复核 schema 与字典值。选择类目和属性与商品草稿同一次保存，`platform_type_id` 从服务端门店类目缓存取得。类目变更或 schema 下线后，失配属性保留为未映射草稿，不能自动进入发布请求。 +当前实现中，前端根据目标门店的本地类目 schema 渲染属性控件、必填提示、字典选择、多值限制及变体属性。门店 Ozon 凭据验证成功后，Worker 使用该门店凭据同步中文类目树；缓存为空时编辑器显示准备中状态，用户不能在编辑页发起树同步。选中类目但 schema 缺失时，仍可显式同步该类目属性。字典控件先搜索本地缓存，输入至少两个字符仍无结果时，可显式从 Ozon 搜索并缓存命中值。`is_aspect=true` 在编辑器中按 SKU 展示，其余属性按商品展示；保存仍由服务端复核 schema 与字典值。选择类目和属性与商品草稿同一次保存，`platform_type_id` 从服务端门店类目缓存取得。类目变更或 schema 下线后，失配属性保留为未映射草稿，不能自动进入发布请求。[待迁移目标](../architecture/platform-product-reference-catalog.md)是同平台门店共用参考目录，本阶段不维护门店差异层。 类目、标题、型号、品牌以及默认包装重量和默认包装尺寸固定放在「主要信息」区。SKU 默认继承父商品包装规格，仅在包装不同的情况下填写覆盖值。平台动态必填字段统一使用表单标准表现，在 Label 前显示红色 `*`；不追加「Ozon 必填」标签，也不在区块标题显示完成数量。更完整的目标交互、属性值表达、SKU 关联和发布校验改造见 [`ozon-dynamic-attributes-and-sku-form-plan.md`](./ozon-dynamic-attributes-and-sku-form-plan.md)。 diff --git a/docs/project/HANDOFF.md b/docs/project/HANDOFF.md index a0a501a..2aec866 100644 --- a/docs/project/HANDOFF.md +++ b/docs/project/HANDOFF.md @@ -215,7 +215,7 @@ ### 1.25 开发进度（2026-09-10）：M3.4 类目与动态属性 -- 旧迁移 `021_product_category_attribute_schema.sql` 建立了平台级 schema 缓存；最新设计由 `022_store_catalog_cache.sql` 另建门店级类目、schema 与字典缓存，发布草稿只引用门店级数据。 +- 旧迁移 `021_product_category_attribute_schema.sql` 建立了平台级 schema 缓存；当时采用 `022_store_catalog_cache.sql` 另建门店级类目、schema 与字典缓存，发布草稿只引用门店级数据。此处记录已实现历史，2026-09-18 的新目标见[平台级参考目录决策](../architecture/platform-product-reference-catalog.md)。 - 新增编辑器接口：类目候选、类目属性 schema 与属性字典值。类目 schema/字典接口支持传入未保存的 `category_id` 预览，因此用户选择新类目后不必先保存一次才能填写字段。 - 编辑器草稿可原子保存 `store_product_category_id`、类目来源与商品/SKU 属性；服务端派生 `platform_type_id`，复核类型、值数量、字典值与 SKU 归属。类目变更或 schema 下线的旧属性会转入 `product_unmapped_attributes`，不会默默丢失或进入新的发布 payload。 - Web 编辑页已提供类目选择、商品/SKU 维度动态字段、字典选择、未映射属性告警；上架店铺/主题标签保持标准 40px 控件高度，父商品包装重量与三项包装尺寸宽度分别为 150px / 120px。 @@ -224,17 +224,18 @@ - 已实现类目树、类目属性 schema、字典值缓存的数据表、Worker 同步逻辑、Transactional Outbox 和读 API；缓存属于门店级发布元数据，不属于某个商品草稿。浏览器、operation 响应与 outbox 事件都不含 API Key。 - 当前旧实现仍把“同步 Ozon 类目”暴露为商品编辑页操作；这已被最新产品决策否定，不能作为完成状态使用。属性 schema 仍是按类目读取/按需同步的现状，后续需单独确认是否也改为启动预热。 -- 字典不会全量拉取：字段先读取已有缓存；用户输入至少两个字符且本地无匹配时，现有实现可显式发起 Ozon `/attribute/values/search`，Worker 仅 upsert 返回的命中项。同步失败应保留旧缓存和可读错误状态。 +- 字典不会全量拉取：字段先读取已有缓存；首次打开某个字典属性时，按需从 Ozon `/attribute/values` 按游标同步首批最多 1000 项，当前类目下同一字典仅自动触发一次。输入至少两个字符后延迟调用 Ozon `/attribute/values/search`，补充首批以外的候选；本地缓存每页返回 200 项并支持下拉滚动续读。同步失败应保留旧缓存和可读错误状态。 ### 1.27 历史状态（2026-09-10）：平台级预热方案已废弃 -- 原交接要求的“Worker 启动时以指定门店预热一份平台共享类目树”已被产品决策替代：类目、属性和字典缓存按门店隔离，不能再恢复平台级共享缓存或环境变量指定的共享源。 +- 原交接要求的“Worker 启动时以指定门店预热一份平台共享类目树”当时被门店级方案替代。该时期要求类目、属性和字典按门店隔离，不恢复平台级共享缓存或以环境变量任意指定客户门店作为共享源。 - 保留的原则是：浏览器、日志、operation 和 outbox 事件均不携带 API Key；编辑器只读缓存，不提供类目树手动同步入口。 +- 本节只记录当时决策；2026-09-18 的[平台级参考目录决策](../architecture/platform-product-reference-catalog.md)已取代该目标。现有门店级实现未随文档决策自动迁移。 ### 1.28 开发进度（2026-09-10）：门店类目同步与来源回填 - Ozon 门店凭据验证成功后，在同一事务中创建门店类目同步 operation 与 outbox 事件；Worker 使用该门店 `Client-Id + Api-Key` 请求中文类目树，并写入 `store_product_categories`。失败只标记类目同步 operation，不会把已验证的凭据改为无效。 -- 已删除编辑器的手动类目树同步接口和客户端调用。属性 schema 与字典值仍按当前类目和关键词按需同步，使用原有 Outbox/Worker 链路。 +- 已删除编辑器的手动类目树同步接口和客户端调用。属性 schema 与字典值仍按当前类目按需同步；字典支持打开控件时同步首批值和按关键词搜索，均使用原有 Outbox/Worker 链路。 - Cascader 显示完整缓存树路径，但表单与草稿 API 始终保存末级类目 UUID，修复了路径数组不能直接提交到 `editor-draft` 的问题。 - 对 Ozon 来源商品，进入或读取编辑器时会将 `common.categories` 的规范化层级路径与活动缓存节点精确匹配；仅当 profile 未保存类目时写入匹配项并标记 `source_capture`。已有手工选择或此前保存的类目永远不被复采覆盖。API 集成测试覆盖回填和保护规则。 - 已新增 API 集成测试覆盖来源回填和保护规则；仍需在有效 Ozon 门店、真实 Ozon 样本与浏览器页面上执行最终回归。本地 Docker 基础设施未启动时，该集成测试无法实际执行。 @@ -275,6 +276,93 @@ M3.5 与 M3.6 均已收口。真实来源回归中若要提升 Ozon 自动类目 下一步：在真实采集来源中回归首次按需物化、Worker 下载失败重试与已选图片保存；然后实施定价确认。来源域限流、429/503 延迟重试和跨候选 URL 下载去重属于 Worker 下载器的后续可靠性加固，尚未在本 M3.6 变更中完成。 +### 1.32 开发进度（2026-09-18）：Ozon 动态属性与 SKU 表单 P0 + +- 编辑器选择类目后立即加载属性 schema。`is_required=true` 的商品级属性始终展示在「产品属性」，`is_aspect=true` 的必填属性始终展示在对应 SKU 卡片；必填状态仅使用 Label 前的红色 `*`，选填属性仍可折叠。 +- 动态属性控件已拆为独立组件，统一处理字典、布尔、数值、文本和多值字段；商品级与 SKU 级属性只负责各自的分区编排。主要信息继续保留类目、标题、型号、品牌和默认包装规格，SKU 展开区可覆盖包装及商品规格。 +- 草稿保存不会因 Ozon 必填属性或包装规格为空而失败；已提交的非空属性仍由 API 校验类型、数量、字典归属、类目归属及 `is_aspect` 对应的商品/SKU scope。 +- 新增 `GET /api/product-platform-profiles/{profile_id}/validation`，在独立校验模块中返回商品级问题和逐 SKU 问题。已导入 SKU 标为 `not_publishable_again`；必填通用属性和必填变体属性都以当前门店类目 schema 为准。 +- 类目 schema 新增 `editor_field` 语义绑定，严格按 Ozon 属性 ID 识别品牌 `85`、型号名称 `9048`、类型 `8229`、主题标签 `23171`、JSON 富内容 `11254` 和简介/产品描述 `4191`。这些字段由编辑器已有控件承载，动态属性区不再重复展示或预取字典；名称和翻译文本不参与判断。 +- Contracts、API 与 Web TypeScript 检查、Web production build 和 `git diff --check` 已通过。API 集成测试已补充通用/逐 SKU 必填缺失和 scope 伪造场景；本轮环境无法连接 PostgreSQL/Redis，因此未实际跑通该集成测试，且未按约定启动 API 或 Worker。 + +后续 P1/P2 仍包括：新 SKU 通过 `client_key` 在首次保存时关联动态属性、SKU 级条形码、结构化字典值，以及首次发布任务复用 validation 并回填 Ozon 错误。详见 [`ozon-dynamic-attributes-and-sku-form-plan.md`](../product/ozon-dynamic-attributes-and-sku-form-plan.md)。 + +### 1.33 开发进度与交接（2026-09-18）：平台级商品参考目录、系统后台与同步维护 + +#### 1.33.1 已冻结的数据归属 + +- 类目/商品类型树、类型属性定义和字典候选值归属 `platform_id`，同一平台的全部门店共用，不再按门店复制。Ozon 与未来 Wildberries 等平台分别使用自己的适配器和外部 ID 语义；本阶段**不创建、不读取门店差异层**。 +- 门店连接、卖家凭据、商品/SKU 已填属性、发布状态和错误仍是工作空间业务数据。平台参考目录不保存客户商品、价格、库存或发布事实。 +- 这项平台级能力已经独立落地，但商品编辑器仍使用 `022_store_catalog_cache.sql` 的门店级类目 UUID、属性和字典 API。不得直接删除旧表或把新旧 UUID 混用；编辑器迁移必须通过 Ozon 外部 ID 做双读/回填后再切换。 + +#### 1.33.2 类目树、属性和字典的标识规则 + +| 参考数据 | Atlas 表与唯一作用域 | Ozon 字段及处理规则 | +|---|---|---| +| 类目/类型树 | `platform_product_categories`；`platform_id + external_category_id + external_type_id` | `external_category_id = description_category_id`，`external_type_id = type_id`。类型节点可能不重复返回类目 ID，映射器会继承最近父类目的 `description_category_id`。纯目录节点使用 `type_id = 0`，只用于树结构，不允许作为建品类型；可发布类型必须同时使用 `description_category_id + type_id`，不能按名称或单独 ID 匹配。`parent_id` 和 `path` 由树同步统一重建，Ozon `disabled` 或本次全量树中消失的节点标为非活动，不物理删除。 | +| 类型属性定义 | `platform_product_category_attributes`；平台 + 类型节点 + `platform_attribute_id + complex_id` | 保存 Ozon 属性 `id`、`attribute_complex_id/complex_id`、名称、说明、分组、类型、`is_required`、`is_aspect`、`is_collection`、`max_value_count`、`dictionary_id` 和 `category_dependent`。属性同步是某一 `description_category_id + type_id` 的完整定义；成功后本次未返回的旧属性标为非活动。 | +| 字典候选值 | `platform_catalog_dictionary_values`；`attribute_id + external_value_id` | 调用字典接口时必须同时传 `attribute_id + description_category_id + type_id`。即使 Ozon 返回相同 `dictionary_id`，也不能只按字典 ID 跨类型合并。当前每页 2000 项，单任务最多读取 5 页；不足 5 页且 `has_next=false` 才记录 `is_complete=true`，只有完整同步才停用本次未返回的旧值。 | + +商品编辑器隐藏品牌 `85`、型号名称 `9048`、类型 `8229`、主题标签 `23171`、JSON 富内容 `11254`、简介/产品描述 `4191` 时，仍严格使用 Ozon 属性 ID；名称只用于展示。管理后台是参考数据检查工具，会展示完整属性定义，不应用编辑器的隐藏规则。 + +#### 1.33.3 数据库和安全边界 + +迁移 `024_platform_catalog_management.sql` 已新增或扩展以下对象： + +- `system_admin_grants`：独立的全局系统管理员授权。工作空间 `owner/admin` 不等于系统管理员；`atlas_app` 被撤销该表的写权限，不能通过普通 HTTP 接口自助提权。 +- `platform_catalog_sources`：每个平台一份专用参考源。Ozon `Api-Key` 使用现有 AES-256-GCM 边界加密，随机 nonce 与不可逆 HMAC fingerprint 分开保存；响应只返回脱敏 Client-Id，不回显密钥、密文或 fingerprint。 +- `platform_catalog_dictionary_values`：替代旧平台字典表不足以表达类目/属性作用域的问题；旧表暂不删除。 +- `platform_catalog_sync_runs`：平台级树、属性和字典任务事实，记录触发方式、状态、来源版本、尝试次数、结果数量和脱敏错误。 +- `platform_catalog_sync_requests`：把系统管理员的 `Idempotency-Key` 持久映射到任务；即使手动请求复用了一个已存在的定时任务，重试也不会在原任务完成后创建第二个任务。 +- `platform_catalog_outbox_events`：不带 `workspace_id` 的平台级 Transactional Outbox。平台任务不能借用租户 `operations/outbox_events`，避免伪造工作空间归属。 + +配置来源时，API 在同一事务更新密文和 `revision`，取消旧来源尚未完成的任务，并排队一次树同步。Worker 在领取和提交结果时都会比较 `source_revision`；来源已经更换的旧任务只能取消，不能用新凭据执行或覆盖新数据。API Key 只在 API 加密入口和 Worker 解密调用 Ozon 的短暂内存中出现，不进入浏览器回显、任务载荷或日志。 + +#### 1.33.4 系统管理员后台 + +- 独立后台路由为 `/system/platform-catalog`，布局不依赖工作台的门店选择器。普通登录用户可调用 `GET /api/system/access` 获取布尔值；所有管理读写 API 还会在服务端实时校验 `system_admin_grants`，前端隐藏菜单不是权限边界。 +- 页面名称为「平台类目与属性」。可选择平台、查看参考源状态和类目树最近成功时间；选择可发布类型后查看属性 ID、必填、SKU 变体、数据类型及已缓存候选值数量；字典在 Drawer 中分页搜索 Atlas 缓存并显示完整/部分状态。 +- 「配置同步来源」提交 Client-Id 与 Api-Key。首次配置或实际变更会自动排队树同步；重复提交同一凭据不增加来源版本或重复任务。 +- 「同步类目树」「同步当前类型属性」「同步此字典」都只向 API 排队，不在 HTTP 请求中直接访问 Ozon。最近任务表每 5 秒轮询一次；任务由 `queued → running → succeeded/failed/cancelled` 转换，完成后页面重新读取相应缓存。 +- 管理 API 契约、首位管理员初始化 SQL 和错误边界见 [`platform-catalog-admin.md`](../api/platform-catalog-admin.md)。目前数据库已经存在一名有效系统管理员授权；此前反馈过用户菜单没有显示入口，数据库授权已确认正确，但刷新/当前 Web 与 API 进程版本下的菜单展示仍需浏览器回归。 + +#### 1.33.5 手动同步与自动同步的共同链路 + +```text +系统管理员页面 / 定时调度器 + ↓ 同一事务创建 run + platform outbox +PlatformCatalogDispatcher（每 2 秒，批量最多 20 条） + ↓ 投递 atlas-dispatch / platform_catalog_sync.requested +BullMQ Worker（最多 5 次，5 秒起指数退避） + ↓ 使用平台参考源凭据调用 Ozon +事务内 upsert 参考数据并完成 run + ↓ +管理页面轮询任务并重新读取 Atlas 缓存 +``` + +- 手动接口要求 UUID `Idempotency-Key`。同一平台和 `scope_key` 只允许一个 `queued/running` 任务；已有活动任务时返回并映射到该任务。 +- Worker 启动时立即执行一次调度，之后每 60 秒扫描一次。每个平台最多保留 6 个活动任务，优先级依次为树、属性、字典；树和属性成功后 24 小时内不重复，字典成功后 7 天内不重复，任一作用域创建任务后 1 小时内不会被定时器重复排队。 +- Ozon 单次 HTTP 超时为 30 秒。401/403 转换为凭据错误；429、5xx、网络错误和响应结构异常交给 BullMQ 重试；其他确定性 4xx 直接记录请求被拒绝。最终失败只更新任务错误，不清空上次成功缓存。 +- 树、某类型的属性和某属性的字典分别在单个数据库事务中发布。读取方在事务提交前仍看到旧缓存；P0 尚未实现不可变版本快照、内容哈希和 `next_refresh_at`，当前依赖事务 upsert、`synced_at` 与任务历史保证一致性和可追踪性。 + +#### 1.33.6 当前实际进度快照 + +- `024_platform_catalog_management.sql` 已于 2026-09-18 实际应用，系统管理员授权已写入并回读验证。 +- Worker 曾因先于 `024` 迁移启动而无法初始化平台 Outbox Dispatcher；迁移后 Worker 已恢复。最新数据库事实显示 Outbox 已被分发、任务 `attempt_count=1`，证明平台 Dispatcher、BullMQ 消费和 Ozon 调用链路当前正在工作。 +- 两次 Ozon 类目树任务均已成功，每次映射结果为 7933 条；当前活动节点为 7365 条，差额主要是纯目录/禁用节点。定时属性预热已经开始：检查时 18 个属性任务成功，当前活动属性定义 436 条，单类型返回约 27～50 个属性。 +- 字典候选值当前仍为 0，尚未进入有效的初始预热阶段。现有调度固定优先全部属性，再处理字典；在数千个类型下可能导致字典长期排在属性之后，这是已知的 P0 调度公平性问题，不能把“属性同步已开始”误认为字典已经可供全部用户使用。 +- 已通过 API/Worker/Web TypeScript 检查、Web production build、3 项系统管理员/参数单元测试、6 项 Ozon 树/属性/字典映射与分页测试及 `git diff --check`。由于功能落地后才执行迁移，尚未新增并运行覆盖真实 PostgreSQL 的平台目录端到端测试；现有成功任务提供了真实 Ozon 链路验证，但不能替代自动化数据库回归。 + +#### 1.33.7 明确未完成项 + +1. 调整定时调度公平性：树之后不能等待全部类型属性完成才开始字典；应在属性和字典之间设置配额/轮转，并优先近期使用或管理员选中的类型。 +2. 为超过 10000 项的大字典实现可续传游标或分片同步周期。当前任务会正确标记 `is_complete=false`，但下一次仍从头读取，不能持续推进到第 10001 项以后。 +3. 将商品编辑器由门店级缓存迁移到平台级目录：按 `description_category_id + type_id` 和属性 ID 回填，先双读/兼容保存，再切换外键和 API，最后才讨论清理 `022` 表。 +4. 增加平台目录 PostgreSQL 集成测试，覆盖系统管理员隔离、凭据版本替换、手动幂等复用、定时去重、失败保留旧缓存、完整字典停用旧值及跨平台 ID 拒绝。 +5. 在浏览器完成管理员菜单、直达路由、凭据弹窗、任务轮询、类目/属性/字典展示的回归，并确认 API/Worker 进程都使用迁移后的当前代码。 + +完整架构边界见 [`platform-product-reference-catalog.md`](../architecture/platform-product-reference-catalog.md)，HTTP 契约见 [`platform-catalog-admin.md`](../api/platform-catalog-admin.md)。 + ## 2. 已确认产品决策 | 主题 | 决策 | @@ -293,6 +381,7 @@ M3.5 与 M3.6 均已收口。真实来源回归中若要提升 Ozon 自动类目 | 采集 SKU | 只有来源给出稳定 SKU/组合证据时创建多个 SKU；不能把规格轴做笛卡尔积。没有专属 SKU 图时，真实 SKU 继承父商品默认图而不复制资产。 | | 媒体 | 采集主图/详情图是商品候选池；来源明确给出 SKU、或可靠的规格轴值（如颜色）与图片关系时才自动绑定。其余素材由编辑页人工选择。 | | 发布与在线商品 | 商品采集、编辑、定价、AI 媒体和首次导入至 Ozon 后台是核心闭环。正式发布使用官方 Seller API，按一 SKU 一 import item/offer 执行并轮询结果；首期不传库存或仓库，用户在 Ozon 后台设置库存。已导入 SKU 不可再次上架，未上架 SKU 仍可首次上架；SPU 在当前平台汇总为未上架/已部分上架/已上架。在线商品由异步 Ozon API 同步，按 Ozon 商品 SKU 展示，亦包含非 Atlas 发布商品。 | +| 平台商品参考目录 | `platform_id` 下共享类目/类型树、属性定义和字典候选值；同平台门店共用，本阶段不维护门店差异层。定时同步、系统管理员页面和手动排队已实现；商品编辑器的门店级引用待迁移，见 [`platform-product-reference-catalog.md`](../architecture/platform-product-reference-catalog.md)。 | ## 3. Ozon 已核对结论 @@ -335,13 +424,13 @@ User → Workspace → Membership / Role 下一步建议按以下顺序推进： -> 注意：下面的历史清单仍保留用于追溯；当前执行优先级以 [`1.27 当前进行中`](#127-当前进行中2026-09-10类目树交互改造尚未验收) 和本段补充为准。先完成类目启动同步、树形选择与 Ozon 来源类目自动回填，再进入真实采集回归和后续发布能力。 +> 注意：下面的清单不能覆盖 2026-09-18 的 [Ozon 参考目录决策](../architecture/platform-product-reference-catalog.md)。平台目录、后台和同步基础链路已经实现；现有门店级商品编辑契约在完成兼容迁移前继续生效。 当前执行顺序： -1. 配置专用 Ozon 类目缓存源，在真实 Ozon 样本和 8100 页面完成类目预热、树形选择及来源回填回归。 -2. 完成候选媒体选择与按需物化，并把已选素材纳入 SKU 编辑草稿。 -3. 完成定价、AI 任务与候选结果、首次发布和在线商品同步的剩余纵向闭环。 +1. 完成平台目录首次预热并修正属性/字典调度公平性和大字典续传；补 PostgreSQL 集成测试与系统管理员浏览器回归。 +2. 按 Ozon 外部 ID 建立新旧目录映射和双读，迁移商品编辑器到平台级类目、属性和候选值；在验证前保留门店级缓存与外键。 +3. 在真实采集来源中继续回归候选媒体按需物化，然后完成定价、AI 任务、首次发布和在线商品同步的剩余纵向闭环。 ### 历史计划（仅供追溯） @@ -360,6 +449,7 @@ User → Workspace → Membership / Role - [API 统一约定](../api/conventions.md) - [基础模块数据模型与 DDL](../architecture/foundation-data-model.md) - [商品领域数据模型与 DDL](../architecture/product-domain-data-model.md) +- [平台级商品参考目录决策](../architecture/platform-product-reference-catalog.md) - [幂等与 Transactional Outbox](../architecture/transactional-outbox-and-idempotency.md) - [数据库角色与 RLS](../architecture/database-security.md) - [商品采集图片与存储策略](../architecture/media-storage-strategy.md) diff --git a/packages/contracts/src/product-editor.ts b/packages/contracts/src/product-editor.ts index bbfe695..16ec064 100644 --- a/packages/contracts/src/product-editor.ts +++ b/packages/contracts/src/product-editor.ts @@ -65,6 +65,14 @@ export type ProductAttributeSchema = { max_value_count: number; dictionary_id: string | null; is_aspect: boolean; + editor_field: + | 'category' + | 'brand' + | 'model' + | 'tags' + | 'rich_content' + | 'description' + | null; }; export type ProductAttributeDictionaryValue = { @@ -72,6 +80,28 @@ export type ProductAttributeDictionaryValue = { value: string; }; +export type ProductEditorValidationIssue = { + code: string; + field: string; + message: string; + platform_attribute_id?: string; +}; + +export type ProductEditorValidation = { + ready: boolean; + profile: { + ready: boolean; + issues: ProductEditorValidationIssue[]; + }; + variants: Array<{ + variant_id: string; + display_name: string | null; + status: 'ready' | 'blocked' | 'not_publishable_again'; + ready: boolean; + issues: ProductEditorValidationIssue[]; + }>; +}; + /** * M3.0 editor entry and read-model contracts. Draft mutation, pricing, and * publishing DTOs intentionally stay out of this first editor slice. diff --git a/packages/database/migrations/024_platform_catalog_management.sql b/packages/database/migrations/024_platform_catalog_management.sql new file mode 100644 index 0000000..6a4ebd1 --- /dev/null +++ b/packages/database/migrations/024_platform_catalog_management.sql @@ -0,0 +1,126 @@ +SET search_path TO atlas, public; + +-- 全局管理员授权独立于工作空间成员身份；日常应用角色只能读取授权。 +CREATE TABLE system_admin_grants ( + user_id UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE, + granted_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL, + granted_at TIMESTAMPTZ NOT NULL DEFAULT now(), + revoked_at TIMESTAMPTZ +); +REVOKE INSERT, UPDATE, DELETE ON system_admin_grants FROM atlas_app; + +-- 每个平台只配置一组受控参考源凭据，不挂载到客户门店。 +CREATE TABLE platform_catalog_sources ( + platform_id UUID PRIMARY KEY REFERENCES platforms(id) ON DELETE CASCADE, + client_id TEXT NOT NULL CHECK (length(trim(client_id)) BETWEEN 1 AND 128), + secret_ciphertext BYTEA NOT NULL, + secret_nonce BYTEA NOT NULL, + secret_fingerprint TEXT NOT NULL, + encryption_key_version TEXT NOT NULL, + revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0), + updated_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL, + updated_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +-- 复用既有平台类目和属性定义表；补齐管理页面及同步所需的属性元数据。 +ALTER TABLE platform_product_category_attributes + ADD COLUMN description TEXT, + ADD COLUMN group_id TEXT, + ADD COLUMN group_name TEXT, + ADD COLUMN category_dependent BOOLEAN NOT NULL DEFAULT false, + ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true, + ADD CONSTRAINT uq_platform_catalog_attribute_scope + UNIQUE (id, platform_id, platform_product_category_id); + +-- 旧字典表仅以 dictionary_id 唯一，无法表达类目相关候选值；新表明确归属属性。 +CREATE TABLE platform_catalog_dictionary_values ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + platform_id UUID NOT NULL, + platform_product_category_id UUID NOT NULL, + attribute_id UUID NOT NULL, + dictionary_id TEXT NOT NULL, + external_value_id TEXT NOT NULL, + value TEXT NOT NULL, + info TEXT, + picture TEXT, + is_active BOOLEAN NOT NULL DEFAULT true, + source_payload JSONB NOT NULL DEFAULT '{}'::jsonb, + synced_at TIMESTAMPTZ NOT NULL DEFAULT now(), + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), + FOREIGN KEY (attribute_id, platform_id, platform_product_category_id) + REFERENCES platform_product_category_attributes(id, platform_id, platform_product_category_id) + ON DELETE RESTRICT, + UNIQUE (attribute_id, external_value_id) +); +CREATE INDEX ix_platform_catalog_dictionary_values_lookup + ON platform_catalog_dictionary_values (attribute_id, is_active, value, external_value_id); + +-- 平台任务不能借用带 workspace_id 的租户 operation/outbox。 +CREATE TABLE platform_catalog_sync_runs ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + platform_id UUID NOT NULL REFERENCES platforms(id) ON DELETE CASCADE, + scope TEXT NOT NULL CHECK (scope IN ('tree', 'attributes', 'dictionary')), + scope_key TEXT NOT NULL, + category_id UUID REFERENCES platform_product_categories(id) ON DELETE RESTRICT, + attribute_id UUID REFERENCES platform_product_category_attributes(id) ON DELETE RESTRICT, + trigger_kind TEXT NOT NULL CHECK (trigger_kind IN ('manual', 'scheduled', 'source_configured')), + status operation_status NOT NULL DEFAULT 'queued', + source_revision INTEGER NOT NULL CHECK (source_revision > 0), + requested_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL, + idempotency_key UUID, + attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0), + result JSONB NOT NULL DEFAULT '{}'::jsonb, + error_code TEXT, + error_message TEXT, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + started_at TIMESTAMPTZ, + completed_at TIMESTAMPTZ, + CHECK ( + (scope = 'tree' AND category_id IS NULL AND attribute_id IS NULL) + OR (scope = 'attributes' AND category_id IS NOT NULL AND attribute_id IS NULL) + OR (scope = 'dictionary' AND category_id IS NOT NULL AND attribute_id IS NOT NULL) + ), + CHECK (idempotency_key IS NULL OR requested_by_user_id IS NOT NULL), + UNIQUE (requested_by_user_id, idempotency_key) +); +CREATE UNIQUE INDEX uq_platform_catalog_active_sync + ON platform_catalog_sync_runs (platform_id, scope_key) + WHERE status IN ('queued', 'running'); +CREATE INDEX ix_platform_catalog_sync_recent + ON platform_catalog_sync_runs (platform_id, scope, scope_key, created_at DESC); + +-- 一个手动请求可复用已有的定时任务；幂等键因此独立映射到任务，而不是只放在任务行。 +CREATE TABLE platform_catalog_sync_requests ( + requested_by_user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, + idempotency_key UUID NOT NULL, + platform_id UUID NOT NULL REFERENCES platforms(id) ON DELETE CASCADE, + scope_key TEXT NOT NULL, + run_id UUID NOT NULL REFERENCES platform_catalog_sync_runs(id) ON DELETE RESTRICT, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + PRIMARY KEY (requested_by_user_id, idempotency_key) +); +CREATE INDEX ix_platform_catalog_sync_requests_run + ON platform_catalog_sync_requests (run_id); + +CREATE TABLE platform_catalog_outbox_events ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + run_id UUID NOT NULL UNIQUE REFERENCES platform_catalog_sync_runs(id) ON DELETE CASCADE, + platform_id UUID NOT NULL REFERENCES platforms(id) ON DELETE CASCADE, + status outbox_event_status NOT NULL DEFAULT 'pending', + attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0), + next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT now(), + locked_by TEXT, + locked_until TIMESTAMPTZ, + dispatched_at TIMESTAMPTZ, + last_error_code TEXT, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), + CHECK ( + (status = 'dispatching' AND locked_by IS NOT NULL AND locked_until IS NOT NULL) + OR (status <> 'dispatching' AND locked_by IS NULL AND locked_until IS NULL) + ) +); +CREATE INDEX ix_platform_catalog_outbox_dispatch + ON platform_catalog_outbox_events (status, next_attempt_at, created_at) + WHERE status IN ('pending', 'dispatching');