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

5.7 KiB

Technical plan: SEO performance tracking

Evidence boundary

Baseline inspected: local 13f4fdc58dff96f192c612a8d38f33d314f70fad; concurrent implementation advanced to 39f5b705c57ca4bf807210e8b887cb8bced7926b during audit. Bind final acceptance to the later integrated clean SHA, not these intermediate observations. Files in this directory are human-authored reviewed artifacts; specify 1.2.3 and installed prerequisite checks were exercised, not a claim of automatic slash-command generation or registered Hermes integration. See release investigation and acceptance matrix for actual observations.

Architecture and contract requirements

  • Backend backend/src/seo-tracking: guarded NestJS controller/service, DTO validation, bounded stable list pagination; return repository-compatible meta contract and document exact field names rather than inventing a conflicting totalPages requirement. Discover current client route in frontend/admin-panel/src/routes/adminRoutes.tsx; sidebar and actual mounted route must agree.
  • Data model must represent finding→many actions/targets, many keywords/goals and directive/action history. Existing single blogId uniqueness is not sufficient. Review normalized child records or explicit validated structured storage; document queryability, identifiers, indexes and retention. Do not claim a migration is done just because schema text exists.
  • Versioned feedback transaction and downstream execution contract: expected finding/directive version, read-before-execute and recheck-before-finalize; stale conflicts stop effects. Verify actual editorial/SEO callers, not only the controller. Preserve feedback author/time/history and per-action compliance evidence.
  • Snapshot contract: explicit period, canonical URL/target, deterministic idempotency identity, per-source and per-metric availability/provenance, null unknown values, units/currency, provider schema semantics and history retrieval. Database uniqueness protects concurrency; duplicate identical requests succeed and changed payload conflicts. No default-zero model for absent sources.
  • Extend API/client/UI together for Clarity, goals, event metrics, attribution limitations and history. Mark supported vs missing contract fields explicitly. Do not hide business scope behind generic sourceMetadata when the UI cannot render or validate it.
  • Worker scripts/seo_performance_tracker.py: authenticated API integration, real bounded GSC/GA4 requests, discovered approved Clarity input, attribution adapter only if join evidence exists; unknown otherwise. Canonicalize URLs, define timezone/date windows and pagination, bound retries/timeouts/rate limits; use no secret defaults. Persist/restore deterministic run identity so retries after process restart are idempotent.
  • Alerts: durable deduplication plus routed department task/notification and delivery status/readback. Department routing must use verified existing contracts; raw Telegram alone does not fulfill assignment/delivery. Reporter does not fabricate completed QA or publish/prune content.
  • Admin UI: actual SeoTrackingPage.tsx and services/seoTrackingApi.ts paths currently exist (the earlier planned SeoTracking.tsx/api/seoTracking.ts paths were inaccurate). Display nullable metrics without || 0, explicit source status/time/limitations, action/goal/directive and persistent history. Handle version conflict with reload/review, no silent resubmit over new feedback.

Validation and release

  1. Save focused RED then GREEN runs; unit fixtures/adapters prove branches only. Run full backend tests/build (npm test, npm run build) and admin tests/typecheck/build (npm test, npm run typecheck, npm run build) in actual installed dependency environment. Record commands, exit codes and SHA.
  2. Isolated PostgreSQL + real Nest HTTP auth/role/validation tests verify committed migrations/schema, restart persistence, concurrent feedback and snapshot ingestion. No live production mutation and no forged live JWT. Exercise real downstream action consumer and department delivery separately.
  3. Live provider read-only acceptance records sanitized property/URL/window/results/provenance and reconciles with provider response. Missing credentials/report/event join remain explicit blocked rows. Do not replace this with synthetic HTTP responses.
  4. Any required schema change is separately authorized and applied before compatible code rollout, with reviewed DDL and rollback; the official Stage release is code-only and will not migrate automatically.
  5. Secure Git transport and exact remote ancestry must be established before non-force develop push. Official workflow executes SHA-pinned deploy.sh → release-cache-stage.sh; it builds/recreates backend/frontend and probes public readiness, but does not run application test suites. Therefore passing CI is not equivalent to complete feature QA.
  6. Match Actions run SHA and completed logs, source manifest, both image/container SHA labels, then authenticated Stage feature behavior and real metrics. Operational checkout is intentionally untouched; never reset/clean it. See release-investigation.md for observed dirty checkout and secure transport blocker.
  7. Parsa owns individual manual cron activation. Supply documentation only; no create/enable action. Production/main remains separate authorized release.

Open acceptance dependencies

Full many-action/goal representation, Clarity report authorization, trustworthy event instrumentation, commerce join/window/refund policy, actual directive execution consumers, alert delivery receipts and schema operation approval must be verified by owning departments. They cannot be declared implemented from this plan or a small unit suite. acceptance-matrix.md remains the closure checklist.