From 39f5b705c57ca4bf807210e8b887cb8bced7926b Mon Sep 17 00:00:00 2001 From: Canina Automation Date: Wed, 28 Oct 2026 06:44:45 +0000 Subject: [PATCH] feat(seo): add versioned findings and nullable snapshot provenance --- .../migration.sql | 89 +++++++++++++++++++ backend/prisma/schema.prisma | 31 +++++-- 2 files changed, 111 insertions(+), 9 deletions(-) create mode 100644 backend/prisma/migrations/20261028120000_add_seo_tracking_contract/migration.sql diff --git a/backend/prisma/migrations/20261028120000_add_seo_tracking_contract/migration.sql b/backend/prisma/migrations/20261028120000_add_seo_tracking_contract/migration.sql new file mode 100644 index 00000000..9fc1a55a --- /dev/null +++ b/backend/prisma/migrations/20261028120000_add_seo_tracking_contract/migration.sql @@ -0,0 +1,89 @@ +-- SEO models existed in schema.prisma without a tracked CREATE migration. +-- Create only missing SEO objects, then additively upgrade existing SEO tables. +-- This does not reconcile the repository's broader incomplete baseline: blogs +-- must already exist (see prisma/MIGRATION_BASELINE.md). No live SQL is run here. +DO $$ BEGIN + CREATE TYPE "ResearchFindingStatus" AS ENUM ('RESEARCHED', 'ACTIONED', 'EVALUATING', 'SCALED', 'PRUNED'); +EXCEPTION + WHEN duplicate_object THEN NULL; +END $$; + +CREATE TABLE IF NOT EXISTS "content_research_findings" ( + "id" UUID NOT NULL, + "title" VARCHAR(255) NOT NULL, + "hypothesis" TEXT NOT NULL, + "target_keywords" TEXT[], + "primary_keyword" VARCHAR(128) NOT NULL, + "expected_outcome" TEXT NOT NULL, + "status" "ResearchFindingStatus" NOT NULL DEFAULT 'RESEARCHED', + "blog_id" UUID, + "ceo_feedback" TEXT, + "feedback_submitted_at" TIMESTAMPTZ, + "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updated_at" TIMESTAMPTZ NOT NULL, + CONSTRAINT "content_research_findings_pkey" PRIMARY KEY ("id"), + CONSTRAINT "content_research_findings_blog_id_fkey" FOREIGN KEY ("blog_id") REFERENCES "blogs"("id") ON DELETE SET NULL ON UPDATE CASCADE +); + +ALTER TABLE "content_research_findings" + ADD COLUMN IF NOT EXISTS "version" INTEGER NOT NULL DEFAULT 0, + ADD COLUMN IF NOT EXISTS "feedback_version" INTEGER NOT NULL DEFAULT 0, + ADD COLUMN IF NOT EXISTS "search_text" TEXT NOT NULL DEFAULT '', + ADD COLUMN IF NOT EXISTS "goal_metric" TEXT, + ADD COLUMN IF NOT EXISTS "goal_target" DOUBLE PRECISION, + ADD COLUMN IF NOT EXISTS "action_id" TEXT; +-- action_id is a plain external reference, deliberately without a foreign key. +CREATE UNIQUE INDEX IF NOT EXISTS "content_research_findings_blog_id_key" ON "content_research_findings"("blog_id"); +CREATE INDEX IF NOT EXISTS "content_research_findings_status_idx" ON "content_research_findings"("status"); +CREATE INDEX IF NOT EXISTS "content_research_findings_primary_keyword_idx" ON "content_research_findings"("primary_keyword"); + +CREATE TABLE IF NOT EXISTS "content_performance_snapshots" ( + "id" UUID NOT NULL, + "finding_id" UUID NOT NULL, + "snapshot_date" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, + "gsc_impressions" INTEGER, + "gsc_clicks" INTEGER, + "gsc_position" DOUBLE PRECISION, + "ga4_active_users" INTEGER, + "ga4_avg_engagement_sec" DOUBLE PRECISION, + "ga4_bounce_rate" DOUBLE PRECISION, + "ga4_scroll_depth_rate" DOUBLE PRECISION, + "attributed_orders_count" INTEGER, + "attributed_sales_value" DECIMAL(15,2), + "action_recommendation" VARCHAR(64), + "analysis_notes" TEXT, + "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, + CONSTRAINT "content_performance_snapshots_pkey" PRIMARY KEY ("id"), + CONSTRAINT "content_performance_snapshots_finding_id_fkey" FOREIGN KEY ("finding_id") REFERENCES "content_research_findings"("id") ON DELETE CASCADE ON UPDATE CASCADE +); + +ALTER TABLE "content_performance_snapshots" + ADD COLUMN IF NOT EXISTS "period_start" TIMESTAMPTZ, + ADD COLUMN IF NOT EXISTS "period_end" TIMESTAMPTZ, + ADD COLUMN IF NOT EXISTS "source_metadata" JSONB, + ADD COLUMN IF NOT EXISTS "ingestion_key" TEXT, + ALTER COLUMN "gsc_impressions" DROP NOT NULL, + ALTER COLUMN "gsc_impressions" DROP DEFAULT, + ALTER COLUMN "gsc_clicks" DROP NOT NULL, + ALTER COLUMN "gsc_clicks" DROP DEFAULT, + ALTER COLUMN "gsc_position" DROP NOT NULL, + ALTER COLUMN "gsc_position" DROP DEFAULT, + ALTER COLUMN "ga4_active_users" DROP NOT NULL, + ALTER COLUMN "ga4_active_users" DROP DEFAULT, + ALTER COLUMN "ga4_avg_engagement_sec" DROP NOT NULL, + ALTER COLUMN "ga4_avg_engagement_sec" DROP DEFAULT, + ALTER COLUMN "ga4_bounce_rate" DROP NOT NULL, + ALTER COLUMN "ga4_bounce_rate" DROP DEFAULT, + ALTER COLUMN "ga4_scroll_depth_rate" DROP NOT NULL, + ALTER COLUMN "ga4_scroll_depth_rate" DROP DEFAULT, + ALTER COLUMN "attributed_orders_count" DROP NOT NULL, + ALTER COLUMN "attributed_orders_count" DROP DEFAULT, + ALTER COLUMN "attributed_sales_value" DROP NOT NULL, + ALTER COLUMN "attributed_sales_value" DROP DEFAULT; + +-- Do not rewrite historical metrics: old zeros remain zeros, not proven measures. +-- Newly added metadata/period/key columns remain SQL NULL for legacy snapshots; +-- no provenance, observation period, or idempotency key can be inferred safely. +CREATE INDEX IF NOT EXISTS "content_performance_snapshots_finding_id_snapshot_date_idx" ON "content_performance_snapshots"("finding_id", "snapshot_date"); +-- PostgreSQL permits multiple NULL keys, preserving all historical snapshots. +CREATE UNIQUE INDEX IF NOT EXISTS "content_performance_snapshots_finding_id_ingestion_key_key" ON "content_performance_snapshots"("finding_id", "ingestion_key"); diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prisma index b4aa27ce..094467b9 100644 --- a/backend/prisma/schema.prisma +++ b/backend/prisma/schema.prisma @@ -1040,6 +1040,13 @@ model ContentResearchFinding { primaryKeyword String @map("primary_keyword") @db.VarChar(128) expectedOutcome String @map("expected_outcome") @db.Text status ResearchFindingStatus @default(RESEARCHED) + version Int @default(0) + feedbackVersion Int @default(0) @map("feedback_version") + searchText String @default("") @map("search_text") @db.Text + goalMetric String? @map("goal_metric") + goalTarget Float? @map("goal_target") + // External action reference only; no orchestration relation or foreign key. + actionId String? @map("action_id") blogId String? @unique @map("blog_id") @db.Uuid blog Blog? @relation(fields: [blogId], references: [id], onDelete: SetNull) @@ -1064,17 +1071,22 @@ model ContentPerformanceSnapshot { snapshotDate DateTime @default(now()) @map("snapshot_date") @db.Timestamptz() - gscImpressions Int @default(0) @map("gsc_impressions") - gscClicks Int @default(0) @map("gsc_clicks") - gscPosition Float @default(0.0) @map("gsc_position") + periodStart DateTime? @map("period_start") @db.Timestamptz() + periodEnd DateTime? @map("period_end") @db.Timestamptz() + sourceMetadata Json? @map("source_metadata") + ingestionKey String? @map("ingestion_key") - ga4ActiveUsers Int @default(0) @map("ga4_active_users") - ga4AvgEngagementSec Float @default(0.0) @map("ga4_avg_engagement_sec") - ga4BounceRate Float @default(0.0) @map("ga4_bounce_rate") - ga4ScrollDepthRate Float @default(0.0) @map("ga4_scroll_depth_rate") + gscImpressions Int? @map("gsc_impressions") + gscClicks Int? @map("gsc_clicks") + gscPosition Float? @map("gsc_position") - attributedOrdersCount Int @default(0) @map("attributed_orders_count") - attributedSalesValue Decimal @default(0) @map("attributed_sales_value") @db.Decimal(15, 2) + ga4ActiveUsers Int? @map("ga4_active_users") + ga4AvgEngagementSec Float? @map("ga4_avg_engagement_sec") + ga4BounceRate Float? @map("ga4_bounce_rate") + ga4ScrollDepthRate Float? @map("ga4_scroll_depth_rate") + + attributedOrdersCount Int? @map("attributed_orders_count") + attributedSalesValue Decimal? @map("attributed_sales_value") @db.Decimal(15, 2) actionRecommendation String? @map("action_recommendation") @db.VarChar(64) analysisNotes String? @map("analysis_notes") @db.Text @@ -1082,6 +1094,7 @@ model ContentPerformanceSnapshot { createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz() @@index([findingId, snapshotDate]) + @@unique([findingId, ingestionKey]) @@map("content_performance_snapshots") }