Files
canina/specs/002-seo-performance-tracking/spec.md
T

7.3 KiB

Feature specification: SEO performance tracking closed loop

Scope and status

Reviewed scope for research → approved digital action → measured outcome → CEO directive → revised action. This document describes required behavior, not completed or deployed capability. Independent acceptance is in acceptance-matrix.md; release findings are in release-investigation.md. Unit tests, synthetic adapter fixtures, a local commit, and HTTP 200 are not end-to-end proof. All department handoffs require observable artifacts; no Gate1/Gate2 terminology or automatic scheduler activation.

User stories and requirements

R1 — Durable research and actions

Research/SEO can store evidence URLs, observation date, title, hypothesis, intent, primary and secondary keywords, multiple measurable goals with units/windows/baselines, and multiple related actions/targets. A finding must support many actions, keywords and goals; a single optional blog relation is not the whole business model. Content, catalog, technical SEO, conversion, and UX actions may have different targets. Actions carry owning department, source finding, evidence, status, timestamps and immutable history. Preserve findings/history when targets disappear. Distinguish proposed recommendations from authorized executable actions and actual published artifacts.

R2 — Authenticated management

Authorized administrators can list/search/filter/sort findings with stable server pagination, truthful totals and bounded page sizes; normalized Persian/Arabic keyword search is tested. UI includes navigation, detail, goals, action/evidence history, source freshness, measurements, limitations and feedback. Unauthenticated requests receive 401; authenticated unauthorized users receive 403 for every read/write route. Validate payloads, UUIDs, numeric ranges, allowed sorting and periods; reject unknown fields. Never expose credentials or customer PII in UI/worker logs.

R3 — CEO feedback is optional to submit, mandatory to obey

Feedback persists atomically with timestamp, actor and monotonically changing directive/finding versions. Concurrent saves use expected version and return conflict rather than overwriting silently. Every downstream content/SEO action reads and binds the current directive version before work and rechecks at commit/publication/ingestion boundaries. A stale directive cannot authorize action or silently overwrite newer feedback. Merely displaying feedback or accepting a client-supplied version is insufficient: QA verifies the real execution consumer and conflict recovery. Human-readable rationale links each action to the directive it followed; ambiguous directives remain blocked for clarification.

R4 — Real measurements and honest missing data

Explicitly invoke a bounded worker to collect real GSC (sc-domain:canina.ir) and GA4 (properties/552453291) measurements for canonical target URLs and explicit closed date windows. Discover and validate actual permitted credentials/properties without printing secrets. Store provenance (source/property, request window, fetch time, canonical URL, source status, reason and units). Null/unavailable/error/unsupported/stale are not zero. A genuinely empty successful provider response may yield zero counts but not a fictional zero average rank. Partial source/metric availability remains visible; no fabricated fallback metrics or conclusions. Reconcile canonical/trailing slash/encoded URL variants and pagination/quotas; retries are bounded.

Clarity is explicitly in scope: discover approved export/API/report access, ingest meaningful behavior measurements with provenance, or display unsupported/unavailable with reason and responsible owner. Loading a Clarity script does not prove report integration. GA4 engagement time, bounce and scroll must use documented numerators/denominators; do not present the default scroll event (90% threshold) as arbitrary scroll-depth distribution. Include subscriptions/sign-ups, add-to-cart, checkout, article→product/shop/internal navigation, and completed purchase goals only where event collection and URL/window attribution are independently verified. Missing instrumentation is a tracked gap, not zero conversions.

R5 — Commerce attribution has explicit limits

Orders alone cannot establish that an article visitor purchased. Report attributable orders/revenue only with a documented lawful join/attribution mechanism, window/model, currency, paid/completed/refund treatment and deduplication. Separate total commerce from attributed commerce. Unknown joins, consent loss, cross-device loss, blockers or uninstrumented events produce unknown/unavailable and limitations; never assign all orders or zero orders to a finding by inference. Aggregate only necessary data and do not disclose customer identifiers.

R6 — Persistent history and recommendations

Append snapshots with a deterministic finding/target/window/source-contract ingestion identity, preserved across restart/retry. Same identity and payload returns the same snapshot; conflicting payload is rejected explicitly. Concurrent retries cannot duplicate records; historical windows remain retrievable through pagination rather than being lost behind a fixed latest-N response. Preserve source-specific and metric-specific partial availability and measurement semantics. Recommendations use actual comparable evidence and uncertainty, not arbitrary hard-coded thresholds. No automatic deletion, PRUNED transition, content pruning, or scaling based solely on thresholds. Any destructive/content change requires a separately authorized task and independent QA.

R7 — Department delivery and scheduler ownership

Research/SEO owns evidence and hypotheses; Content/Medical owns accurate editorial execution; Engineering/DBA owns contracts/schema/auth; Frontend/UX owns usable and measured interactions; Growth/Commerce owns attribution definitions; DevOps owns credentials/release/scheduler readiness; QA/PMO independently verifies receipts and routes defects. Provider/instrumentation/schema anomalies create or deliver actionable, deduplicated department alerts with finding/run/source/error context, bounded retry and durable delivery result. Telegram is a notification channel, not proof of department delivery. Test receipt and recovery, not just a mocked send call. Do not automatically publish content from the tracker.

Parsa manually configures each cron individually. Deliver an invocable worker, documented arguments, dry-run semantics and proposed schedule only; do not create, enable or alter cron jobs. Dry-run must have a tested explicit mutation boundary; real acceptance separately verifies authorized snapshot persistence.

Operational constraints

TDD requires saved RED and GREEN evidence before/after implementation. Real isolated database/HTTP integration, live provider readback and authenticated Stage browser acceptance are mandatory in addition to unit tests. Schema migration is a separate reviewed/authorized operation with backup/rollback and compatibility evidence; code CI must not run migrations/seeds. Use develop → exact-SHA CI → Stage behavior; promotion to main/Production requires separate authorization. No external writes, pushes, migrations, deployments or scheduler activation are authorized by this specification audit. Retain each unresolved acceptance row as blocked, not complete.