fix(seo): validate ingress and fence directive and snapshot writes

This commit is contained in:
Canina Automation committed 2026-10-28 06:58:22 +00:00
1 parent 39f5b705c5
commit 6102556eae
7 files changed
+566 -283

No files matched your search

+27
View File
@@ -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.
@@ -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'; import { ResearchFindingStatus } from '@prisma/client';
export class CreateFindingDto { export class CreateFindingDto {
@IsString() @IsString() @MinLength(1) @MaxLength(255) title: string;
title: string; @IsString() @MinLength(1) @MaxLength(20000) hypothesis: string;
@IsString()
hypothesis: string;
@IsArray() @IsArray()
@ArrayNotEmpty() @ArrayNotEmpty()
@ArrayMaxSize(50)
@IsString({ each: true }) @IsString({ each: true })
@MaxLength(128, { each: true })
targetKeywords: string[]; targetKeywords: string[];
@IsString() @MinLength(1) @MaxLength(128) primaryKeyword: string;
@IsString() @IsString() @MinLength(1) @MaxLength(20000) expectedOutcome: string;
primaryKeyword: string; @IsOptional() @IsEnum(ResearchFindingStatus) status?: ResearchFindingStatus;
@IsOptional() @IsUUID() blogId?: string;
@IsString() @IsOptional() @IsString() @MaxLength(128) actionId?: string;
expectedOutcome: string; @IsOptional() @IsString() @MaxLength(64) goalMetric?: string;
@IsOptional() @IsNumber() @Min(0) goalTarget?: number;
@IsOptional()
@IsEnum(ResearchFindingStatus)
status?: ResearchFindingStatus;
@IsOptional()
@IsUUID()
blogId?: string;
} }
export class UpdateCeoFeedbackDto { export class UpdateCeoFeedbackDto {
@IsString() @IsString() @MaxLength(20000) feedback: string;
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 { 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() @IsOptional()
page?: number; @IsIn(['createdAt', 'updatedAt', 'title', 'status'])
@IsOptional()
limit?: number;
@IsOptional()
@IsString()
search?: string;
@IsOptional()
@IsEnum(ResearchFindingStatus)
status?: ResearchFindingStatus;
@IsOptional()
@IsString()
sortBy?: string; sortBy?: string;
@IsOptional() @IsIn(['asc', 'desc']) sortOrder?: 'asc' | 'desc';
@IsOptional()
@IsString()
sortOrder?: 'asc' | 'desc';
} }
export class CreateSnapshotDto { export class CreateSnapshotDto {
@IsString() @MinLength(1) @MaxLength(128) ingestionKey: string;
@IsISO8601({ strict: true }) periodStart: string;
@IsISO8601({ strict: true }) periodEnd: string;
@IsObject() sourceMetadata: Record<string, any>;
@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() @IsOptional()
gscImpressions?: number; @IsIn(['SCALE', 'REFINE', 'HOLD', 'PRUNE'])
@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()
actionRecommendation?: string; actionRecommendation?: string;
@IsOptional() @IsString() @MaxLength(20000) analysisNotes?: string;
@IsOptional()
@IsString()
analysisNotes?: string;
} }
@@ -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);
},
);
});
@@ -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);
});
});
@@ -7,9 +7,13 @@ import {
Param, Param,
Query, Query,
UseGuards, UseGuards,
ParseUUIDPipe,
UsePipes,
ValidationPipe,
} from '@nestjs/common'; } from '@nestjs/common';
import { SeoTrackingService } from './seo-tracking.service'; import { SeoTrackingService } from './seo-tracking.service';
import { import {
ActionFindingDto,
CreateFindingDto, CreateFindingDto,
QueryFindingsDto, QueryFindingsDto,
UpdateCeoFeedbackDto, UpdateCeoFeedbackDto,
@@ -21,7 +25,14 @@ import { Roles } from '../common/decorators/roles.decorator';
@Controller('admin/seo-tracking') @Controller('admin/seo-tracking')
@UseGuards(JwtAuthGuard, RolesGuard) @UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN', 'SUPER_ADMIN') @Roles('admin', 'superadmin')
@UsePipes(
new ValidationPipe({
transform: true,
whitelist: true,
forbidNonWhitelisted: true,
}),
)
export class SeoTrackingController { export class SeoTrackingController {
constructor(private readonly seoTrackingService: SeoTrackingService) {} constructor(private readonly seoTrackingService: SeoTrackingService) {}
@@ -36,21 +47,29 @@ export class SeoTrackingController {
} }
@Get(':id') @Get(':id')
async findOne(@Param('id') id: string) { async findOne(@Param('id', new ParseUUIDPipe()) id: string) {
return this.seoTrackingService.findOne(id); return this.seoTrackingService.findOne(id);
} }
@Patch(':id/feedback') @Patch(':id/feedback')
async updateCeoFeedback( async updateCeoFeedback(
@Param('id') id: string, @Param('id', new ParseUUIDPipe()) id: string,
@Body() dto: UpdateCeoFeedbackDto, @Body() dto: UpdateCeoFeedbackDto,
) { ) {
return this.seoTrackingService.updateCeoFeedback(id, dto); 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') @Post(':id/snapshots')
async addSnapshot( async addSnapshot(
@Param('id') id: string, @Param('id', new ParseUUIDPipe()) id: string,
@Body() dto: CreateSnapshotDto, @Body() dto: CreateSnapshotDto,
) { ) {
return this.seoTrackingService.addSnapshot(id, dto); return this.seoTrackingService.addSnapshot(id, dto);
@@ -1,119 +1,120 @@
import { Test, TestingModule } from '@nestjs/testing'; import { PrismaClient } from '@prisma/client';
import { SeoTrackingService } from './seo-tracking.service'; import { SeoTrackingService } from './seo-tracking.service';
import { PrismaService } from '../prisma/prisma.service'; const testUrl = process.env.SEO_TEST_DATABASE_URL;
import { NotFoundException } from '@nestjs/common'; if (testUrl && !/^postgresql:\/\/seo_test@127\.0\.0\.1:55439\/postgres$/.test(testUrl)) {
throw new Error('Integration tests require the dedicated disposable local database');
describe('SeoTrackingService (TDD)', () => { }
let service: SeoTrackingService; const run = testUrl ? describe : describe.skip;
let prisma: any; run('SEO disposable PostgreSQL integration', () => {
const db = new PrismaClient({
const mockFinding = { datasources: {
id: 'f9d3b841-8f52-4412-bc78-8316c029e001', db: {
title: 'تغذیه گربه مبتلا به نارسایی کلیه', url:
hypothesis: 'تمرکز بر مکمل رنال و اسیدهای آمینه به دلیل خلا در نتایج فارسی', process.env.SEO_TEST_DATABASE_URL ||
targetKeywords: ['غذای کلیه گربه', 'مکمل رنال گربه'], 'postgresql://disabled@127.0.0.1:1/disabled',
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 }),
),
}, },
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>(SeoTrackingService);
}); });
const service = new SeoTrackingService(db as any);
it('should create a new research finding', async () => { let id: string;
const dto = { beforeAll(async () => {
title: 'تغذیه گربه مبتلا به نارسایی کلیه', const f = await service.createFinding({
hypothesis: 'تمرکز بر مکمل رنال', title: 'كليه ۱۲',
targetKeywords: ['غذای کلیه گربه'], hypothesis: 'integration fixture',
primaryKeyword: 'مکمل رنال گربه', primaryKeyword: 'كليه',
expectedOutcome: 'فروش بیشتر', targetKeywords: ['كليه'],
}; expectedOutcome: 'test',
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,
}); });
id = f.id;
}); });
afterAll(async () => {
it('should update CEO feedback atomically and record timestamp', async () => { await db.contentResearchFinding.deleteMany();
const feedback = 'تمرکز باید دقیقاً روی علائم زودرس کراتینین بالا باشد.'; await db.$disconnect();
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,
}),
}),
);
}); });
it('normalizes both stored text and search with filtered pagination', async () => {
it('should throw NotFoundException if finding does not exist for feedback', async () => { const result = await service.findAll({ search: 'کلیه 12', limit: 1 });
prisma.contentResearchFinding.findUnique.mockResolvedValueOnce(null); 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( await expect(
service.updateCeoFeedback('non-existing', { feedback: 'test' }), service.actionFinding(id, {
).rejects.toThrow(NotFoundException); expectedVersion: 1,
}); feedbackVersion: 0,
status: 'ACTIONED',
it('should add performance snapshot with GSC and Sales data', async () => { }),
const snap = await service.addSnapshot(mockFinding.id, { ).rejects.toMatchObject({ status: 409 });
gscImpressions: 1200, const row = await service.actionFinding(id, {
gscClicks: 85, expectedVersion: 1,
attributedOrdersCount: 4, feedbackVersion: 1,
attributedSalesValue: 2400000, status: 'ACTIONED',
}); });
expect(row.version).toBe(2);
expect(snap.attributedOrdersCount).toBe(4); });
expect(prisma.contentPerformanceSnapshot.create).toHaveBeenCalled(); 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 });
}); });
}); });
+222 -92
View File
@@ -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 { PrismaService } from '../prisma/prisma.service';
import { CreateFindingDto, QueryFindingsDto, UpdateCeoFeedbackDto, CreateSnapshotDto } from './dto/seo-tracking.dto'; import {
import { createPaginationMeta } from '../common/utils/search.utils'; CreateFindingDto,
QueryFindingsDto,
UpdateCeoFeedbackDto,
CreateSnapshotDto,
ActionFindingDto,
} from './dto/seo-tracking.dto';
import {
createPaginationMeta,
normalizeSearchText,
} from '../common/utils/search.utils';
import { Prisma } from '@prisma/client'; 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<T extends object>(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() @Injectable()
export class SeoTrackingService { export class SeoTrackingService {
constructor(private prisma: PrismaService) {} constructor(private prisma: PrismaService) {}
async createFinding(input: CreateFindingDto) {
async createFinding(dto: 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({ return this.prisma.contentResearchFinding.create({
data: { data: {
title: dto.title, ...dto,
hypothesis: dto.hypothesis, searchText: normalizeSearchText(
targetKeywords: dto.targetKeywords, [dto.title, dto.primaryKeyword, ...dto.targetKeywords].join(' '),
primaryKeyword: dto.primaryKeyword, ),
expectedOutcome: dto.expectedOutcome,
status: dto.status || 'RESEARCHED',
blogId: dto.blogId,
}, },
include: { include: {
blog: { blog: { select: { id: true, title: true, slug: true, status: true } },
select: { id: true, title: true, slug: true, status: true },
},
}, },
}); });
} }
async findAll(input: QueryFindingsDto) {
async findAll(query: QueryFindingsDto) { const {
const { page = 1, limit = 10, search, status, sortBy = 'createdAt', sortOrder = 'desc' } = query; page = 1,
const safePage = Math.max(1, Number(page) || 1); limit = 10,
const safeLimit = Math.max(1, Number(limit) || 10); search,
const skip = (safePage - 1) * safeLimit; status,
sortBy = 'createdAt',
sortOrder = 'desc',
} = checked(QueryFindingsDto, input);
const where: Prisma.ContentResearchFindingWhereInput = {}; const where: Prisma.ContentResearchFindingWhereInput = {};
if (status) { if (status) where.status = status;
where.status = status; const normalized = normalizeSearchText(search);
} if (normalized)
if (search) { where.searchText = { contains: normalized, mode: 'insensitive' };
where.OR = [ const [data, total] = await this.prisma.$transaction(
{ title: { contains: search, mode: 'insensitive' } }, [
{ primaryKeyword: { contains: search, mode: 'insensitive' } }, this.prisma.contentResearchFinding.findMany({
{ hypothesis: { contains: search, mode: 'insensitive' } }, where,
]; skip: (page - 1) * limit,
} take: limit,
orderBy: [{ [sortBy]: sortOrder }, { id: 'asc' }],
const [data, total] = await Promise.all([ include: {
this.prisma.contentResearchFinding.findMany({ blog: { select: { id: true, title: true, slug: true } },
where, snapshots: { orderBy: { snapshotDate: 'desc' }, take: 1 },
skip,
take: safeLimit,
orderBy: { [sortBy]: sortOrder },
include: {
blog: { select: { id: true, title: true, slug: true } },
snapshots: {
orderBy: { snapshotDate: 'desc' },
take: 1,
}, },
}, }),
}), this.prisma.contentResearchFinding.count({ where }),
this.prisma.contentResearchFinding.count({ where }), ],
]); { isolationLevel: Prisma.TransactionIsolationLevel.RepeatableRead },
);
return { return { data, meta: createPaginationMeta(total, page, limit) };
data,
meta: createPaginationMeta(total, safePage, safeLimit),
};
} }
async findOne(id: string) { async findOne(id: string) {
const finding = await this.prisma.contentResearchFinding.findUnique({ const finding = await this.prisma.contentResearchFinding.findUnique({
where: { id }, where: { id },
include: { include: {
blog: true, blog: true,
snapshots: { snapshots: { orderBy: { snapshotDate: 'desc' }, take: 30 },
orderBy: { snapshotDate: 'desc' },
take: 30,
},
}, },
}); });
if (!finding) throw new NotFoundException('Research finding not found');
if (!finding) {
throw new NotFoundException(`Research finding with ID ${id} not found`);
}
return finding; return finding;
} }
async updateCeoFeedback(id: string, input: UpdateCeoFeedbackDto) {
async updateCeoFeedback(id: string, dto: UpdateCeoFeedbackDto) { const dto = checked(UpdateCeoFeedbackDto, input);
await this.findOne(id); return this.prisma.$transaction(async (tx) => {
const claim = await tx.contentResearchFinding.updateMany({
return this.prisma.contentResearchFinding.update({ where: { id, version: dto.expectedVersion },
where: { id }, data: {
data: { ceoFeedback: dto.feedback,
ceoFeedback: dto.feedback, feedbackSubmittedAt: new Date(),
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 actionFinding(id: string, input: ActionFindingDto) {
async addSnapshot(findingId: string, dto: CreateSnapshotDto) { const { expectedVersion, feedbackVersion, ...data } = checked(
await this.findOne(findingId); ActionFindingDto,
input,
return this.prisma.contentPerformanceSnapshot.create({ );
data: { return this.prisma.$transaction(async (tx) => {
findingId, const claim = await tx.contentResearchFinding.updateMany({
gscImpressions: dto.gscImpressions || 0, where: { id, version: expectedVersion, feedbackVersion },
gscClicks: dto.gscClicks || 0, data: { ...data, version: { increment: 1 } },
gscPosition: dto.gscPosition || 0.0, });
ga4ActiveUsers: dto.ga4ActiveUsers || 0, if (!claim.count) {
ga4AvgEngagementSec: dto.ga4AvgEngagementSec || 0.0, if (!(await tx.contentResearchFinding.findUnique({ where: { id } })))
ga4BounceRate: dto.ga4BounceRate || 0.0, throw new NotFoundException();
ga4ScrollDepthRate: dto.ga4ScrollDepthRate || 0.0, throw new ConflictException('Finding/directive version changed');
attributedOrdersCount: dto.attributedOrdersCount || 0, }
attributedSalesValue: dto.attributedSalesValue || 0, return tx.contentResearchFinding.findUniqueOrThrow({ where: { id } });
actionRecommendation: dto.actionRecommendation, });
analysisNotes: dto.analysisNotes, }
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<string, number | null> = {};
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<string, number | null>)[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<string, any>,
)
: 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;
}
} }
} }