fix(seo): validate ingress and fence directive and snapshot writes
This commit is contained in:
1 parent
39f5b705c5
commit
6102556eae
7 files changed
+566
-283
No files matched your search
@@ -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';
|
||||
|
||||
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<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()
|
||||
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;
|
||||
}
|
||||
@@ -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,
|
||||
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);
|
||||
|
||||
@@ -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>(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 });
|
||||
});
|
||||
});
|
||||
@@ -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<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()
|
||||
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<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;
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user