From 6102556eae23325013789d610396a77b0f0136a7 Mon Sep 17 00:00:00 2001 From: Canina Automation Date: Wed, 28 Oct 2026 06:58:22 +0000 Subject: [PATCH] fix(seo): validate ingress and fence directive and snapshot writes --- backend/src/seo-tracking/VERIFICATION.md | 27 ++ .../src/seo-tracking/dto/seo-tracking.dto.ts | 138 ++++---- .../seo-tracking.contract.spec.ts | 38 +++ .../seo-tracking.controller.spec.ts | 86 +++++ .../seo-tracking/seo-tracking.controller.ts | 27 +- .../seo-tracking/seo-tracking.service.spec.ts | 219 ++++++------ .../src/seo-tracking/seo-tracking.service.ts | 314 +++++++++++++----- 7 files changed, 566 insertions(+), 283 deletions(-) create mode 100644 backend/src/seo-tracking/VERIFICATION.md create mode 100644 backend/src/seo-tracking/seo-tracking.contract.spec.ts create mode 100644 backend/src/seo-tracking/seo-tracking.controller.spec.ts diff --git a/backend/src/seo-tracking/VERIFICATION.md b/backend/src/seo-tracking/VERIFICATION.md new file mode 100644 index 00000000..b609def7 --- /dev/null +++ b/backend/src/seo-tracking/VERIFICATION.md @@ -0,0 +1,27 @@ +# SEO tracking backend local acceptance + +Base: develop 13f4fdc58dff96f192c612a8d38f33d314f70fad. Original unrelated .specify/ and evidence/ untracked. Concurrent frontend changes excluded. + +Spec intent: `/opt/data/engineering/canina-spec-baseline/specs/002-seo-performance-tracking/{spec,plan,tasks}.md`; constitution v1.1.0. Contract refinement: `/opt/data/analytics-engine/contract.md`. Pagination/validation/auth, nullable provenance-aware snapshots, retry integrity, atomic directive versions are local acceptance scope. Worker scheduling and publisher integration are separate acceptance gates. + +Graphify query: `seo tracking authentication snapshots models impact`, 4304 nodes, truncated 1800-token traversal. Graph SHA256 `6a73473cee9e207543fdeeb668bea544f766200a1b16b8a3a9ce18d4e42e51af`; graph build/source binding unknown, discovery only. Directly inspected controller, DTO, service, Prisma models, JwtAuthGuard, JwtStrategy, RolesGuard, search utility. Query modified only graph cache timestamp; excluded from commit. + +## Receipts (local /opt/data/analytics-engine/) +- backend-red.log: 9 validation assertions failed against naive implementation (exit 1). +- backend-green.log: 3 suites / 15 tests passed: validation, real HTTP Passport JWT/role pipeline, disposable PostgreSQL persistence/concurrent feedback fencing, stale action fencing, concurrent snapshot deduplication, changed-payload conflicts, null unavailable versus actual zero. +- backend-build.log: `npm run build`, exit 0. +- backend-db-setup.log: `prisma db push --skip-generate` only on fresh local PostgreSQL 16.2 port 55439, exit 0. +- backend-migration.log: actual additive migration SQL executed successfully against that disposable database after schema push. This verifies upgrade/idempotence against current schema, NOT full repository migrations-from-empty or historical migration baseline. +- backend-full-suite.log: 94 suites pass, 1 fails, 3 skip; 815 tests pass, 1 fails, 7 skip. Integration intentionally skipped without SEO_TEST_DATABASE_URL. +- backend-base-full-suite.log: equivalent clean base SHA, same node_modules: 93 suites pass, 1 fails, 2 skip; 809 tests pass, 1 fails, 3 skip. Both fail the same unrelated WikiService pagination test. + +Docker daemon unavailable and no system postgres binaries; downloaded Zonky PostgreSQL 16.2 binary archive from Maven Central into scratch and initialized a new unprivileged local cluster. No existing server/database used. HTTP tests use an isolated local JWT strategy and real shared guards, not production user lookup/Redis or real API-key credentials. + +## Remaining gates / limitations +- No push, CI, Stage, deployment, production SQL, real analytics ingestion or autonomous run claimed. +- Existing blog/content writers must call the action endpoint with current finding version and feedbackVersion. This endpoint fences both atomically, but cannot enforce arbitrary free-text directive semantics or protect writers bypassing it. No end-to-end publisher integration claimed. +- New findings have normalized title/keyword searchText; old rows default empty and need an authorized API backfill (not silently invented in SQL). Search excludes long hypothesis text. +- actionId is an external reference, not a validated task FK. Goals are stored as optional metric/target and not an automatic business-decision engine. +- Snapshot freshness is recorded by source fetchedAt with future-date sanity check; no business freshness SLA was invented. Source proof remains producer-supplied; actual commerce attribution requires instrumentation and is not inferred from aggregate sales. +- Historical metric zeros retained with null provenance; consumers must treat these as unverified legacy values. +- Wider repository migration baseline incomplete; migration assumes blogs exists. Validate release migration against a representative authorized Stage clone before release. diff --git a/backend/src/seo-tracking/dto/seo-tracking.dto.ts b/backend/src/seo-tracking/dto/seo-tracking.dto.ts index 605f00ea..7a2f89fe 100644 --- a/backend/src/seo-tracking/dto/seo-tracking.dto.ts +++ b/backend/src/seo-tracking/dto/seo-tracking.dto.ts @@ -1,95 +1,77 @@ -import { IsString, IsArray, IsOptional, IsEnum, IsUUID, ArrayNotEmpty } from 'class-validator'; +import { Type, Transform } from 'class-transformer'; +import { + IsString, + IsArray, + IsOptional, + IsEnum, + IsUUID, + ArrayNotEmpty, + ArrayMaxSize, + MaxLength, + MinLength, + IsInt, + Min, + Max, + IsIn, + IsNumber, + IsISO8601, + IsObject, +} from 'class-validator'; import { ResearchFindingStatus } from '@prisma/client'; - export class CreateFindingDto { - @IsString() - title: string; - - @IsString() - hypothesis: string; - + @IsString() @MinLength(1) @MaxLength(255) title: string; + @IsString() @MinLength(1) @MaxLength(20000) hypothesis: string; @IsArray() @ArrayNotEmpty() + @ArrayMaxSize(50) @IsString({ each: true }) + @MaxLength(128, { each: true }) targetKeywords: string[]; - - @IsString() - primaryKeyword: string; - - @IsString() - expectedOutcome: string; - - @IsOptional() - @IsEnum(ResearchFindingStatus) - status?: ResearchFindingStatus; - - @IsOptional() - @IsUUID() - blogId?: string; + @IsString() @MinLength(1) @MaxLength(128) primaryKeyword: string; + @IsString() @MinLength(1) @MaxLength(20000) expectedOutcome: string; + @IsOptional() @IsEnum(ResearchFindingStatus) status?: ResearchFindingStatus; + @IsOptional() @IsUUID() blogId?: string; + @IsOptional() @IsString() @MaxLength(128) actionId?: string; + @IsOptional() @IsString() @MaxLength(64) goalMetric?: string; + @IsOptional() @IsNumber() @Min(0) goalTarget?: number; } - export class UpdateCeoFeedbackDto { - @IsString() - feedback: string; + @IsString() @MaxLength(20000) feedback: string; + @IsInt() @Min(0) expectedVersion: number; +} +export class ActionFindingDto { + @IsInt() @Min(0) expectedVersion: number; + @IsInt() @Min(0) feedbackVersion: number; + @IsOptional() @IsUUID() blogId?: string; + @IsOptional() @IsString() @MaxLength(128) actionId?: string; + @IsOptional() @IsEnum(ResearchFindingStatus) status?: ResearchFindingStatus; } - export class QueryFindingsDto { + @IsOptional() @Type(() => Number) @IsInt() @Min(1) @Max(100000) page?: number; + @IsOptional() @Type(() => Number) @IsInt() @Min(1) @Max(100) limit?: number; + @IsOptional() @IsString() @MaxLength(255) search?: string; + @IsOptional() @IsEnum(ResearchFindingStatus) status?: ResearchFindingStatus; @IsOptional() - page?: number; - - @IsOptional() - limit?: number; - - @IsOptional() - @IsString() - search?: string; - - @IsOptional() - @IsEnum(ResearchFindingStatus) - status?: ResearchFindingStatus; - - @IsOptional() - @IsString() + @IsIn(['createdAt', 'updatedAt', 'title', 'status']) sortBy?: string; - - @IsOptional() - @IsString() - sortOrder?: 'asc' | 'desc'; + @IsOptional() @IsIn(['asc', 'desc']) sortOrder?: 'asc' | 'desc'; } - export class CreateSnapshotDto { + @IsString() @MinLength(1) @MaxLength(128) ingestionKey: string; + @IsISO8601({ strict: true }) periodStart: string; + @IsISO8601({ strict: true }) periodEnd: string; + @IsObject() sourceMetadata: Record; + @IsOptional() @IsInt() @Min(0) gscImpressions?: number | null; + @IsOptional() @IsInt() @Min(0) gscClicks?: number | null; + @IsOptional() @IsNumber() @Min(0) gscPosition?: number | null; + @IsOptional() @IsInt() @Min(0) ga4ActiveUsers?: number | null; + @IsOptional() @IsNumber() @Min(0) ga4AvgEngagementSec?: number | null; + @IsOptional() @IsNumber() @Min(0) @Max(1) ga4BounceRate?: number | null; + @IsOptional() @IsNumber() @Min(0) @Max(1) ga4ScrollDepthRate?: number | null; + @IsOptional() @IsInt() @Min(0) attributedOrdersCount?: number | null; + @IsOptional() @IsNumber() @Min(0) attributedSalesValue?: number | null; @IsOptional() - gscImpressions?: number; - - @IsOptional() - gscClicks?: number; - - @IsOptional() - gscPosition?: number; - - @IsOptional() - ga4ActiveUsers?: number; - - @IsOptional() - ga4AvgEngagementSec?: number; - - @IsOptional() - ga4BounceRate?: number; - - @IsOptional() - ga4ScrollDepthRate?: number; - - @IsOptional() - attributedOrdersCount?: number; - - @IsOptional() - attributedSalesValue?: number; - - @IsOptional() - @IsString() + @IsIn(['SCALE', 'REFINE', 'HOLD', 'PRUNE']) actionRecommendation?: string; - - @IsOptional() - @IsString() - analysisNotes?: string; + @IsOptional() @IsString() @MaxLength(20000) analysisNotes?: string; } diff --git a/backend/src/seo-tracking/seo-tracking.contract.spec.ts b/backend/src/seo-tracking/seo-tracking.contract.spec.ts new file mode 100644 index 00000000..6c858e9d --- /dev/null +++ b/backend/src/seo-tracking/seo-tracking.contract.spec.ts @@ -0,0 +1,38 @@ +import 'reflect-metadata'; +import { plainToInstance } from 'class-transformer'; +import { validate } from 'class-validator'; +import { + QueryFindingsDto, + CreateSnapshotDto, + UpdateCeoFeedbackDto, +} from './dto/seo-tracking.dto'; +describe('SEO ingress contract', () => { + it.each([ + { page: '1.5' }, + { page: '0' }, + { limit: '101' }, + { sortBy: 'hypothesis' }, + { sortOrder: 'wrong' }, + ])('rejects unsafe query %j', async (value) => { + expect( + (await validate(plainToInstance(QueryFindingsDto, value))).length, + ).toBeGreaterThan(0); + }); + it('requires optimistic version', async () => { + expect( + ( + await validate( + plainToInstance(UpdateCeoFeedbackDto, { feedback: 'new' }), + ) + ).length, + ).toBeGreaterThan(0); + }); + it.each([{ gscClicks: -1 }, { ga4BounceRate: 2 }, { gscClicks: 1.5 }])( + 'rejects invalid metrics %j', + async (value) => { + expect( + (await validate(plainToInstance(CreateSnapshotDto, value))).length, + ).toBeGreaterThan(0); + }, + ); +}); diff --git a/backend/src/seo-tracking/seo-tracking.controller.spec.ts b/backend/src/seo-tracking/seo-tracking.controller.spec.ts new file mode 100644 index 00000000..934fac35 --- /dev/null +++ b/backend/src/seo-tracking/seo-tracking.controller.spec.ts @@ -0,0 +1,86 @@ +import 'reflect-metadata'; +import { Test } from '@nestjs/testing'; +import { INestApplication } from '@nestjs/common'; +import request from 'supertest'; +import { PassportModule, PassportStrategy } from '@nestjs/passport'; +import { Strategy, ExtractJwt } from 'passport-jwt'; +import { JwtService } from '@nestjs/jwt'; +import { SeoTrackingController } from './seo-tracking.controller'; +import { SeoTrackingService } from './seo-tracking.service'; +import { JwtAuthGuard } from '../auth/jwt-auth.guard'; +import { RolesGuard } from '../common/guards/roles.guard'; +class LocalStrategy extends PassportStrategy(Strategy) { + constructor() { + super({ + jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(), + secretOrKey: 'local-disposable-test-secret', + ignoreExpiration: false, + }); + } + validate(payload: any) { + return payload; + } +} +describe('SEO HTTP security and validation', () => { + let app: INestApplication; + const jwt = new JwtService({ secret: 'local-disposable-test-secret' }); + const service = { + findAll: jest.fn().mockResolvedValue({ data: [], meta: { total: 0 } }), + findOne: jest.fn(), + }; + beforeAll(async () => { + const mod = await Test.createTestingModule({ + imports: [PassportModule], + controllers: [SeoTrackingController], + providers: [ + LocalStrategy, + JwtAuthGuard, + RolesGuard, + { provide: SeoTrackingService, useValue: service }, + ], + }).compile(); + app = mod.createNestApplication(); + app.setGlobalPrefix('api'); + await app.init(); + }); + afterAll(async () => { + await app.close(); + }); + it('rejects missing, invalid, expired credentials and nonadmins', async () => { + const route = '/api/admin/seo-tracking'; + await request(app.getHttpServer()).get(route).expect(401); + await request(app.getHttpServer()) + .get(route) + .set('Authorization', 'Bearer invalid') + .expect(401); + await request(app.getHttpServer()) + .get(route) + .set( + 'Authorization', + 'Bearer ' + jwt.sign({ role: 'admin' }, { expiresIn: -1 }), + ) + .expect(401); + await request(app.getHttpServer()) + .get(route) + .set('Authorization', 'Bearer ' + jwt.sign({ role: 'customer' })) + .expect(403); + }); + it('accepts lowercase admin and rejects query injection / malformed UUID', async () => { + const token = 'Bearer ' + jwt.sign({ role: 'admin' }); + await request(app.getHttpServer()) + .get('/api/admin/seo-tracking?page=2&limit=3') + .set('Authorization', token) + .expect(200); + expect(service.findAll).toHaveBeenCalledWith( + expect.objectContaining({ page: 2, limit: 3 }), + ); + await request(app.getHttpServer()) + .get('/api/admin/seo-tracking?sortBy=ceoFeedback') + .set('Authorization', token) + .expect(400); + await request(app.getHttpServer()) + .get('/api/admin/seo-tracking/not-a-uuid') + .set('Authorization', token) + .expect(400); + }); +}); diff --git a/backend/src/seo-tracking/seo-tracking.controller.ts b/backend/src/seo-tracking/seo-tracking.controller.ts index f6d149a6..8c1be6bb 100644 --- a/backend/src/seo-tracking/seo-tracking.controller.ts +++ b/backend/src/seo-tracking/seo-tracking.controller.ts @@ -7,9 +7,13 @@ import { Param, Query, UseGuards, + ParseUUIDPipe, + UsePipes, + ValidationPipe, } from '@nestjs/common'; import { SeoTrackingService } from './seo-tracking.service'; import { + ActionFindingDto, CreateFindingDto, QueryFindingsDto, UpdateCeoFeedbackDto, @@ -21,7 +25,14 @@ import { Roles } from '../common/decorators/roles.decorator'; @Controller('admin/seo-tracking') @UseGuards(JwtAuthGuard, RolesGuard) -@Roles('ADMIN', 'SUPER_ADMIN') +@Roles('admin', 'superadmin') +@UsePipes( + new ValidationPipe({ + transform: true, + whitelist: true, + forbidNonWhitelisted: true, + }), +) export class SeoTrackingController { constructor(private readonly seoTrackingService: SeoTrackingService) {} @@ -36,21 +47,29 @@ export class SeoTrackingController { } @Get(':id') - async findOne(@Param('id') id: string) { + async findOne(@Param('id', new ParseUUIDPipe()) id: string) { return this.seoTrackingService.findOne(id); } @Patch(':id/feedback') async updateCeoFeedback( - @Param('id') id: string, + @Param('id', new ParseUUIDPipe()) id: string, @Body() dto: UpdateCeoFeedbackDto, ) { return this.seoTrackingService.updateCeoFeedback(id, dto); } + @Patch(':id/action') + async actionFinding( + @Param('id', new ParseUUIDPipe()) id: string, + @Body() dto: ActionFindingDto, + ) { + return this.seoTrackingService.actionFinding(id, dto); + } + @Post(':id/snapshots') async addSnapshot( - @Param('id') id: string, + @Param('id', new ParseUUIDPipe()) id: string, @Body() dto: CreateSnapshotDto, ) { return this.seoTrackingService.addSnapshot(id, dto); diff --git a/backend/src/seo-tracking/seo-tracking.service.spec.ts b/backend/src/seo-tracking/seo-tracking.service.spec.ts index 5ad54fd1..39743e50 100644 --- a/backend/src/seo-tracking/seo-tracking.service.spec.ts +++ b/backend/src/seo-tracking/seo-tracking.service.spec.ts @@ -1,119 +1,120 @@ -import { Test, TestingModule } from '@nestjs/testing'; +import { PrismaClient } from '@prisma/client'; import { SeoTrackingService } from './seo-tracking.service'; -import { PrismaService } from '../prisma/prisma.service'; -import { NotFoundException } from '@nestjs/common'; - -describe('SeoTrackingService (TDD)', () => { - let service: SeoTrackingService; - let prisma: any; - - const mockFinding = { - id: 'f9d3b841-8f52-4412-bc78-8316c029e001', - title: 'تغذیه گربه مبتلا به نارسایی کلیه', - hypothesis: 'تمرکز بر مکمل رنال و اسیدهای آمینه به دلیل خلا در نتایج فارسی', - targetKeywords: ['غذای کلیه گربه', 'مکمل رنال گربه'], - primaryKeyword: 'مکمل رنال گربه', - expectedOutcome: 'افزایش بازدید ارگانیک و رشد فروش مکمل‌های کلیه', - status: 'RESEARCHED', - blogId: null, - ceoFeedback: null, - feedbackSubmittedAt: null, - createdAt: new Date(), - updatedAt: new Date(), - }; - - beforeEach(async () => { - prisma = { - contentResearchFinding: { - create: jest.fn().mockResolvedValue(mockFinding), - findMany: jest.fn().mockResolvedValue([mockFinding]), - count: jest.fn().mockResolvedValue(1), - findUnique: jest.fn().mockResolvedValue(mockFinding), - update: jest.fn().mockImplementation(({ data }) => - Promise.resolve({ ...mockFinding, ...data }), - ), +const testUrl = process.env.SEO_TEST_DATABASE_URL; +if (testUrl && !/^postgresql:\/\/seo_test@127\.0\.0\.1:55439\/postgres$/.test(testUrl)) { + throw new Error('Integration tests require the dedicated disposable local database'); +} +const run = testUrl ? describe : describe.skip; +run('SEO disposable PostgreSQL integration', () => { + const db = new PrismaClient({ + datasources: { + db: { + url: + process.env.SEO_TEST_DATABASE_URL || + 'postgresql://disabled@127.0.0.1:1/disabled', }, - contentPerformanceSnapshot: { - create: jest.fn().mockResolvedValue({ - id: 'snap-1', - findingId: mockFinding.id, - gscImpressions: 1200, - gscClicks: 85, - attributedOrdersCount: 4, - attributedSalesValue: 2400000, - }), - }, - }; - - const module: TestingModule = await Test.createTestingModule({ - providers: [ - SeoTrackingService, - { provide: PrismaService, useValue: prisma }, - ], - }).compile(); - - service = module.get(SeoTrackingService); + }, }); - - it('should create a new research finding', async () => { - const dto = { - title: 'تغذیه گربه مبتلا به نارسایی کلیه', - hypothesis: 'تمرکز بر مکمل رنال', - targetKeywords: ['غذای کلیه گربه'], - primaryKeyword: 'مکمل رنال گربه', - expectedOutcome: 'فروش بیشتر', - }; - - const result = await service.createFinding(dto as any); - expect(result).toBeDefined(); - expect(result.title).toBe(dto.title); - expect(prisma.contentResearchFinding.create).toHaveBeenCalled(); - }); - - it('should return paginated findings with standard metadata', async () => { - const res = await service.findAll({ page: 1, limit: 10 }); - expect(res.data).toHaveLength(1); - expect(res.meta).toEqual({ - total: 1, - page: 1, - limit: 10, - totalPages: 1, - lastPage: 1, - hasNextPage: false, - hasPrevPage: false, + const service = new SeoTrackingService(db as any); + let id: string; + beforeAll(async () => { + const f = await service.createFinding({ + title: 'كليه ۱۲', + hypothesis: 'integration fixture', + primaryKeyword: 'كليه', + targetKeywords: ['كليه'], + expectedOutcome: 'test', }); + id = f.id; }); - - it('should update CEO feedback atomically and record timestamp', async () => { - const feedback = 'تمرکز باید دقیقاً روی علائم زودرس کراتینین بالا باشد.'; - const updated = await service.updateCeoFeedback(mockFinding.id, { feedback }); - expect(updated.ceoFeedback).toBe(feedback); - expect(prisma.contentResearchFinding.update).toHaveBeenCalledWith( - expect.objectContaining({ - where: { id: mockFinding.id }, - data: expect.objectContaining({ - ceoFeedback: feedback, - }), - }), - ); + afterAll(async () => { + await db.contentResearchFinding.deleteMany(); + await db.$disconnect(); }); - - it('should throw NotFoundException if finding does not exist for feedback', async () => { - prisma.contentResearchFinding.findUnique.mockResolvedValueOnce(null); + it('normalizes both stored text and search with filtered pagination', async () => { + const result = await service.findAll({ search: 'کلیه 12', limit: 1 }); + expect(result.meta.total).toBe(1); + expect(result.data[0].id).toBe(id); + }); + it('permits only one competing version writer and fences stale actions', async () => { + const writes = await Promise.allSettled([ + service.updateCeoFeedback(id, { feedback: 'A', expectedVersion: 0 }), + service.updateCeoFeedback(id, { feedback: 'B', expectedVersion: 0 }), + ]); + expect(writes.filter((w) => w.status === 'fulfilled')).toHaveLength(1); await expect( - service.updateCeoFeedback('non-existing', { feedback: 'test' }), - ).rejects.toThrow(NotFoundException); - }); - - it('should add performance snapshot with GSC and Sales data', async () => { - const snap = await service.addSnapshot(mockFinding.id, { - gscImpressions: 1200, - gscClicks: 85, - attributedOrdersCount: 4, - attributedSalesValue: 2400000, + service.actionFinding(id, { + expectedVersion: 1, + feedbackVersion: 0, + status: 'ACTIONED', + }), + ).rejects.toMatchObject({ status: 409 }); + const row = await service.actionFinding(id, { + expectedVersion: 1, + feedbackVersion: 1, + status: 'ACTIONED', }); - - expect(snap.attributedOrdersCount).toBe(4); - expect(prisma.contentPerformanceSnapshot.create).toHaveBeenCalled(); + expect(row.version).toBe(2); + }); + const metadata = Object.fromEntries( + ['gsc', 'ga4', 'commerce'].map((k) => [ + k, + { + status: 'unavailable', + source: 'integration fixture', + fetchedAt: '2026-01-03T00:00:00Z', + }, + ]), + ); + const snapshot = { + ingestionKey: 'fixture-window', + periodStart: '2026-01-01T00:00:00Z', + periodEnd: '2026-01-02T00:00:00Z', + sourceMetadata: metadata, + }; + it('preserves null unavailable, idempotent concurrent retries, and conflicts', async () => { + const [a, b] = await Promise.all([ + service.addSnapshot(id, snapshot), + service.addSnapshot(id, snapshot), + ]); + expect(a.id).toBe(b.id); + expect(a.gscClicks).toBeNull(); + expect(a.attributedSalesValue).toBeNull(); + expect( + await db.contentPerformanceSnapshot.count({ where: { findingId: id } }), + ).toBe(1); + await expect( + service.addSnapshot(id, { ...snapshot, analysisNotes: 'different' }), + ).rejects.toMatchObject({ status: 409 }); + }); + it('retains genuine zero and rejects forged partial metrics', async () => { + const sourceMetadata = { + ...metadata, + gsc: { ...metadata.gsc, status: 'available' }, + }; + const row = await service.addSnapshot(id, { + ...snapshot, + ingestionKey: 'zero', + sourceMetadata, + gscImpressions: 0, + gscClicks: 0, + gscPosition: 0, + }); + expect(row.gscClicks).toBe(0); + expect(row.ga4ActiveUsers).toBeNull(); + await expect( + service.addSnapshot(id, { + ...snapshot, + ingestionKey: 'bad', + gscClicks: 0, + }), + ).rejects.toMatchObject({ status: 400 }); + await expect( + service.addSnapshot(id, { + ...snapshot, + ingestionKey: 'bad', + actionRecommendation: 'SCALE', + }), + ).rejects.toMatchObject({ status: 400 }); }); }); diff --git a/backend/src/seo-tracking/seo-tracking.service.ts b/backend/src/seo-tracking/seo-tracking.service.ts index a00a9f88..5a746846 100644 --- a/backend/src/seo-tracking/seo-tracking.service.ts +++ b/backend/src/seo-tracking/seo-tracking.service.ts @@ -1,122 +1,252 @@ -import { Injectable, NotFoundException } from '@nestjs/common'; +import { + Injectable, + NotFoundException, + BadRequestException, + ConflictException, +} from '@nestjs/common'; import { PrismaService } from '../prisma/prisma.service'; -import { CreateFindingDto, QueryFindingsDto, UpdateCeoFeedbackDto, CreateSnapshotDto } from './dto/seo-tracking.dto'; -import { createPaginationMeta } from '../common/utils/search.utils'; +import { + CreateFindingDto, + QueryFindingsDto, + UpdateCeoFeedbackDto, + CreateSnapshotDto, + ActionFindingDto, +} from './dto/seo-tracking.dto'; +import { + createPaginationMeta, + normalizeSearchText, +} from '../common/utils/search.utils'; import { Prisma } from '@prisma/client'; - +import { validateSync } from 'class-validator'; +import { plainToInstance } from 'class-transformer'; +const groups = { + gsc: ['gscImpressions', 'gscClicks', 'gscPosition'], + ga4: [ + 'ga4ActiveUsers', + 'ga4AvgEngagementSec', + 'ga4BounceRate', + 'ga4ScrollDepthRate', + ], + commerce: ['attributedOrdersCount', 'attributedSalesValue'], +}; +function checked(type: new () => T, value: T): T { + const dto = plainToInstance(type, value); + if (validateSync(dto, { whitelist: true, forbidNonWhitelisted: true }).length) + throw new BadRequestException('Invalid SEO tracking input'); + return dto; +} @Injectable() export class SeoTrackingService { constructor(private prisma: PrismaService) {} - - async createFinding(dto: CreateFindingDto) { + async createFinding(input: CreateFindingDto) { + const dto = checked(CreateFindingDto, input); + if ( + ![ + dto.title, + dto.primaryKeyword, + dto.hypothesis, + dto.expectedOutcome, + ...dto.targetKeywords, + ].every((v) => v.trim()) + ) + throw new BadRequestException('Blank text'); return this.prisma.contentResearchFinding.create({ data: { - title: dto.title, - hypothesis: dto.hypothesis, - targetKeywords: dto.targetKeywords, - primaryKeyword: dto.primaryKeyword, - expectedOutcome: dto.expectedOutcome, - status: dto.status || 'RESEARCHED', - blogId: dto.blogId, + ...dto, + searchText: normalizeSearchText( + [dto.title, dto.primaryKeyword, ...dto.targetKeywords].join(' '), + ), }, include: { - blog: { - select: { id: true, title: true, slug: true, status: true }, - }, + blog: { select: { id: true, title: true, slug: true, status: true } }, }, }); } - - async findAll(query: QueryFindingsDto) { - const { page = 1, limit = 10, search, status, sortBy = 'createdAt', sortOrder = 'desc' } = query; - const safePage = Math.max(1, Number(page) || 1); - const safeLimit = Math.max(1, Number(limit) || 10); - const skip = (safePage - 1) * safeLimit; - + async findAll(input: QueryFindingsDto) { + const { + page = 1, + limit = 10, + search, + status, + sortBy = 'createdAt', + sortOrder = 'desc', + } = checked(QueryFindingsDto, input); const where: Prisma.ContentResearchFindingWhereInput = {}; - if (status) { - where.status = status; - } - if (search) { - where.OR = [ - { title: { contains: search, mode: 'insensitive' } }, - { primaryKeyword: { contains: search, mode: 'insensitive' } }, - { hypothesis: { contains: search, mode: 'insensitive' } }, - ]; - } - - const [data, total] = await Promise.all([ - this.prisma.contentResearchFinding.findMany({ - where, - skip, - take: safeLimit, - orderBy: { [sortBy]: sortOrder }, - include: { - blog: { select: { id: true, title: true, slug: true } }, - snapshots: { - orderBy: { snapshotDate: 'desc' }, - take: 1, + if (status) where.status = status; + const normalized = normalizeSearchText(search); + if (normalized) + where.searchText = { contains: normalized, mode: 'insensitive' }; + const [data, total] = await this.prisma.$transaction( + [ + this.prisma.contentResearchFinding.findMany({ + where, + skip: (page - 1) * limit, + take: limit, + orderBy: [{ [sortBy]: sortOrder }, { id: 'asc' }], + include: { + blog: { select: { id: true, title: true, slug: true } }, + snapshots: { orderBy: { snapshotDate: 'desc' }, take: 1 }, }, - }, - }), - this.prisma.contentResearchFinding.count({ where }), - ]); - - return { - data, - meta: createPaginationMeta(total, safePage, safeLimit), - }; + }), + this.prisma.contentResearchFinding.count({ where }), + ], + { isolationLevel: Prisma.TransactionIsolationLevel.RepeatableRead }, + ); + return { data, meta: createPaginationMeta(total, page, limit) }; } - async findOne(id: string) { const finding = await this.prisma.contentResearchFinding.findUnique({ where: { id }, include: { blog: true, - snapshots: { - orderBy: { snapshotDate: 'desc' }, - take: 30, - }, + snapshots: { orderBy: { snapshotDate: 'desc' }, take: 30 }, }, }); - - if (!finding) { - throw new NotFoundException(`Research finding with ID ${id} not found`); - } - + if (!finding) throw new NotFoundException('Research finding not found'); return finding; } - - async updateCeoFeedback(id: string, dto: UpdateCeoFeedbackDto) { - await this.findOne(id); - - return this.prisma.contentResearchFinding.update({ - where: { id }, - data: { - ceoFeedback: dto.feedback, - feedbackSubmittedAt: new Date(), - }, + async updateCeoFeedback(id: string, input: UpdateCeoFeedbackDto) { + const dto = checked(UpdateCeoFeedbackDto, input); + return this.prisma.$transaction(async (tx) => { + const claim = await tx.contentResearchFinding.updateMany({ + where: { id, version: dto.expectedVersion }, + data: { + ceoFeedback: dto.feedback, + feedbackSubmittedAt: new Date(), + version: { increment: 1 }, + feedbackVersion: { increment: 1 }, + }, + }); + if (!claim.count) { + if (!(await tx.contentResearchFinding.findUnique({ where: { id } }))) + throw new NotFoundException(); + throw new ConflictException('Finding version changed'); + } + return tx.contentResearchFinding.findUniqueOrThrow({ where: { id } }); }); } - - async addSnapshot(findingId: string, dto: CreateSnapshotDto) { - await this.findOne(findingId); - - return this.prisma.contentPerformanceSnapshot.create({ - data: { - findingId, - gscImpressions: dto.gscImpressions || 0, - gscClicks: dto.gscClicks || 0, - gscPosition: dto.gscPosition || 0.0, - ga4ActiveUsers: dto.ga4ActiveUsers || 0, - ga4AvgEngagementSec: dto.ga4AvgEngagementSec || 0.0, - ga4BounceRate: dto.ga4BounceRate || 0.0, - ga4ScrollDepthRate: dto.ga4ScrollDepthRate || 0.0, - attributedOrdersCount: dto.attributedOrdersCount || 0, - attributedSalesValue: dto.attributedSalesValue || 0, - actionRecommendation: dto.actionRecommendation, - analysisNotes: dto.analysisNotes, + async actionFinding(id: string, input: ActionFindingDto) { + const { expectedVersion, feedbackVersion, ...data } = checked( + ActionFindingDto, + input, + ); + return this.prisma.$transaction(async (tx) => { + const claim = await tx.contentResearchFinding.updateMany({ + where: { id, version: expectedVersion, feedbackVersion }, + data: { ...data, version: { increment: 1 } }, + }); + if (!claim.count) { + if (!(await tx.contentResearchFinding.findUnique({ where: { id } }))) + throw new NotFoundException(); + throw new ConflictException('Finding/directive version changed'); + } + return tx.contentResearchFinding.findUniqueOrThrow({ where: { id } }); + }); + } + async addSnapshot(findingId: string, input: CreateSnapshotDto) { + const dto = checked(CreateSnapshotDto, input); + const periodStart = new Date(dto.periodStart), + periodEnd = new Date(dto.periodEnd); + if (periodStart >= periodEnd || periodEnd > new Date()) + throw new BadRequestException('Invalid measurement period'); + const metrics: Record = {}; + for (const [source, fields] of Object.entries(groups)) { + const meta = dto.sourceMetadata[source]; + if ( + !meta || + !['available', 'unavailable', 'error'].includes(meta.status) || + typeof meta.source !== 'string' || + !meta.source.trim() || + typeof meta.fetchedAt !== 'string' || + !Number.isFinite(Date.parse(meta.fetchedAt)) || + Date.parse(meta.fetchedAt) > Date.now() + 60000 + ) + throw new BadRequestException('Missing source provenance'); + for (const field of fields) { + const value = + (dto as unknown as Record)[field] ?? null; + if (meta.status !== 'available' && value !== null) + throw new BadRequestException('Unavailable metrics must be null'); + if ( + meta.status === 'available' && + value === null && + field !== 'ga4ScrollDepthRate' + ) + throw new BadRequestException('Available source missing metrics'); + metrics[field] = value; + } + } + if ( + dto.actionRecommendation && + Object.keys(groups).some( + (k) => dto.sourceMetadata[k].status !== 'available', + ) + ) + throw new BadRequestException( + 'Incomplete evidence cannot recommend actions', + ); + const data = { + findingId, + ingestionKey: dto.ingestionKey, + periodStart, + periodEnd, + sourceMetadata: dto.sourceMetadata as Prisma.InputJsonObject, + ...metrics, + actionRecommendation: dto.actionRecommendation ?? null, + analysisNotes: dto.analysisNotes ?? null, + }; + const existing = await this.prisma.contentPerformanceSnapshot.findUnique({ + where: { + findingId_ingestionKey: { findingId, ingestionKey: dto.ingestionKey }, }, }); + const same = (row: any) => { + const canonical = (v: any): string => + JSON.stringify( + v && typeof v === 'object' && !(v instanceof Date) + ? Object.keys(v) + .sort() + .reduce( + (o, k) => ((o[k] = JSON.parse(canonical(v[k]))), o), + {} as Record, + ) + : v, + ); + return Object.entries(data).every(([k, v]) => + k === 'sourceMetadata' + ? canonical(row[k]) === canonical(v) + : k === 'periodStart' || k === 'periodEnd' + ? new Date(row[k]).getTime() === (v as Date).getTime() + : k === 'attributedSalesValue' + ? row[k] === null + ? v === null + : Number(row[k]) === Number(v) + : row[k] === v, + ); + }; + if (existing) { + if (!same(existing)) + throw new ConflictException('Ingestion key reused with different data'); + return existing; + } + await this.findOne(findingId); + try { + return await this.prisma.contentPerformanceSnapshot.create({ data }); + } catch (error) { + if ((error as any).code === 'P2002') { + const row = + await this.prisma.contentPerformanceSnapshot.findUniqueOrThrow({ + where: { + findingId_ingestionKey: { + findingId, + ingestionKey: dto.ingestionKey, + }, + }, + }); + if (same(row)) return row; + throw new ConflictException('Ingestion key reused with different data'); + } + throw error; + } } }