27 lines
5.7 KiB
Markdown
27 lines
5.7 KiB
Markdown
# 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.
|