teknav-bak/app/PHASE10.md

Phase 10 - SEO Growth, Trust, and Production Readiness

Status: Implemented — Linux production validation pending

Phase 10 turns the Phase 7-9 platform into a measurable Persian-first publication for https://www.teknav.ir. All features are implemented and the frontend build is clean. Schema migration, seed, and smoke testing must be run on Linux before declaring production-ready.

Default target: a 90-day SEO growth roadmap, followed by reader retention and monetization only after crawlability, measurement, and editorial quality are reliable.

Implemented in this pass

• Topic authority hubs at /topics/ai, /topics/security, /topics/software, /topics/hardware, /topics/startups, and /topics/data.
• Topic hub metadata in teknav-data.js: Persian SEO title/description, intro copy, keywords, and FAQ pairs.
• Frontend TopicHubPage with featured articles, latest articles, related series, related authors, and visible FAQ content.
• SEO manager support for topic hubs and series pages with CollectionPage, FAQPage, ItemList, and BreadcrumbList JSON-LD.
• Sitemap generation now includes topic hubs and public author profile URLs, and robots.txt blocks /ACCOUNTS.md.
• Production smoke script: npm run smoke:prod.
• Additive Prisma fields for editorial trust:
  • Article.factCheckedAt
  • Article.reviewedById
  • Article.sourceNotes
  • Article.contentFreshnessStatus
• Additive analytics model AnalyticsEvent with type, userId, articleId, topic, metadata, and createdAt.
• First-party event writes for article views, newsletter subscriptions, article saves, writer follows, topic follows, and share clicks.
• Topic follows via TopicFollow and /api/v1/topics/:slug/follow, with topic follow counts on authority hub pages.
• Public newsletter archive routes and API:
  • /newsletter
  • /newsletter/:slug
  • GET /api/v1/newsletter/archive
  • GET /api/v1/newsletter/archive/:slug
• Newsletter archive SEO metadata and sitemap inclusion for /newsletter.
• Article saves now create/use the default reading list بعداً بخوانم.
• Role-aware panel metrics API GET /api/v1/admin/panel-metrics covers admin, editor, writer, and reviewer dashboards with status, workflow, engagement, notification, SEO quality, and recent real event counts.
• Writer workspace /writer separates personal stats, writing, article management, and comments from the full admin panel. It uses GET /api/v1/admin/writer/dashboard for my views, followers, comments, and recent articles.
• Writer-created articles are forced into draft or review states from the panel; they cannot bypass approval into public publication, and a linked public author profile is created on first submission when a writer account does not already have one.
• Article writing now exposes an automatic table of contents from <h2> and <h3> headings before publish.
• Review approval now runs Phase 10 quality gates, completes missing metadata, publishes the article, refreshes counts/cache, and notifies writer/topic followers.
• Public tag pages and backend tag filtering are available through /tag/:tag and GET /api/v1/articles?tag=..., so approved content appears on category, topic, tag, author, article, sitemap, and feed surfaces.
• Topic and author RSS files are generated under /feeds/topic-*.xml and /feeds/author-*.xml in addition to /feed.xml.
• Weekly newsletter digest job npm run newsletter:digest and teknav-weekly-digest.timer send the latest weekly articles through the existing SMTP/newsletter stack.
• Glossary/dictionary term pages are available at /glossary/:slug with Persian metadata, DefinedTerm, FAQPage, and breadcrumb JSON-LD; scripts/generate-seo.mjs includes them in sitemap.xml.
• The article editor includes a structured "X vs Y" comparison template with responsive comparison-table styling for published articles.
• Topic pages continue to expose visible FAQ content and FAQPage schema for rich-result eligibility.
• Google Discover readiness is improved with local 1200x630 article hero images, fetchPriority="high" on the article hero image, max-image-preview:large, and OG image dimensions.
• Persian article SEO has been normalized around the ai-data-centric-2026 success pattern:
  • Older article pages automatically get a semantic .lead introduction block at render time when their stored content does not already provide one.
  • Runtime article JSON-LD includes enriched NewsArticle/TechArticle signals: alternativeHeadline, abstract, articleBody, wordCount, timeRequired, about, mentions, teaches, author knowsAbout, review metadata, and topic-hub linkage.
  • Static article pages generated under dist/article/{slug}/index.html receive the same enriched metadata before React hydration.
  • Future-dated articles are excluded from article sitemaps, feeds, and static article page generation until their dateEn is current.
  • Article image sitemap entries now use explicit ogImage values or generated /images/og/{slug}.jpg assets.
  • npm run check:seo audits current Persian indexable articles for canonical, meta, OG image, review date, heading structure, entity coverage, and body-depth warnings.
• OAuth login remains production-wired for Google and GitHub through /api/v1/auth/oauth/:provider and OAUTH_CALLBACK_BASE=https://www.teknav.ir.
• SMS-based 2FA is implemented through Kavenegar OTP: users can enable it from profile settings, login returns a 2FA ticket, and /api/v1/auth/2fa/verify completes session creation.
• Verified expert badges are supported on author records and rendered on author lists, author profiles, public user profiles, and article bylines.
• Published article corrections/errata are supported through ArticleCorrection, admin correction submission, public correction notices, and article dateModified updates.
• PWA support includes public/manifest.json, service-worker registration in index.html, offline cache handling for article pages/API responses, and an install prompt in teknav-ui.jsx.
• Personalized home feed uses the public article API with sort=personalized, followed topics, followed writers, and read history.
• Community retention now includes comment upvoting with best-comment sorting, expanded article reactions, reading streaks, continue-reading data, and article Q&A endpoints.
• Monetization foundations are in place:
  • /jobs with JobListing storage and company submission API.
  • /courses with course API and public course page.
  • /membership premium membership positioning page.
  • User.membershipTier, Article.premiumOnly, premium article labels, and content locking for non-premium readers.
  • Article.sponsored and public "Promoted Content" labels.
• Operations foundations now include global Fastify rate limiting, selected bulk comment moderation, first-party client error capture at /api/v1/errors, and backend/tests/phase10-smoke.test.mjs for auth/article/comment smoke coverage.
• Living docs that describe the current surface now stay aligned: DEPLOY.md, AGENTS.md, CLAUDE.md, SECURITY.md, and backend index docs.
• Admin API foundations:
  • GET /api/v1/admin/seo/audit
  • GET /api/v1/admin/analytics/content
  • GET /api/v1/admin/analytics/newsletter
  • GET /api/v1/admin/analytics/engagement

Linux Validation Checklist

Run only on Linux/staging or production-like infrastructure:

cd /opt/teknav/SERVER
cd backend && npm run prisma:generate
cd backend && npm run prisma:apply
cd backend && npm run seed
cd ..
npm run seo:sitemap
npm run check:seo
npm run og:images
npm run build
cd backend && npm run build
cd backend && npm test
cd ..
npm run smoke:prod

Production smoke checks expect:

• /api/v1/health returns 2xx with minimal { ok }; /api/v1/ready is the strict PostgreSQL/Redis readiness check.
• /sitemap.xml, /robots.txt, and /feed.xml return 2xx.
• /ACCOUNTS.md returns 403 or 404 through nginx.
• Selected article URLs return canonical URL evidence.

Override smoke targets when needed:

TEKNAV_SMOKE_URL=https://www.teknav.ir TEKNAV_SMOKE_ARTICLES=/article/agentic-ai-production,/article/ai-clean-data npm run smoke:prod

Writer Studio V5 — Close-out polish (implemented)

• HtmlEditor toolbar: grouped buttons (Formatting | Headings | Inline+Block | Lists | Media) with hover states, Bold/Italic label styling, and keyboard shortcuts Ctrl+B / Ctrl+I in the textarea and Ctrl+S globally to save draft.
• Live word count + character count footer on the editor textarea.
• WritingTipCard: manual prev/next navigation with 1/N counter; auto-advance timer resets on manual interaction.
• ArtifactStudio diagram library: gradient placeholder thumbnails replaced with live scaled DiagramRenderer compact mini-previews (CSS scale 0.33, overflow-hidden 56px container).
• ArtifactStudio code mode: relabelled "code preview" with empty-state guidance; was falsely labelled "live preview".
• WeeklyChart data pipeline fixed: was reading the non-existent weeklyViews field; now correctly reads viewsByDay.slice(-7).map(d => d.views) from the dashboard response.
• Analytics sparklines upgraded: full-width filled-area SVG with linearGradient, dot on latest point, "۳۰ روز پیش → امروز" axis labels.
• Analytics table: sparklines prefetched for all articles on mount (parallel requests); inline 80×20 mini-sparkline visible per row; totals footer row; column header corrected from "روند (۳۰ روز)" to "روند اخیر".
• Overview tab: amber needsRevision alert banner when reviewer has flagged articles; dynamic time-of-day greeting (صبح / ظهر / عصر / شب بخیر) with matching tagline.
• Article editor meta-panel: fields grouped into "اطلاعات پایه", "زمان‌بندی", and collapsible "سئو پیشرفته"; slug field added inside SEO section.
• Article editor preview mode: renders selected diagram via DiagramRenderer and subtitle above the article body.
• Article editor: dirty-state indicator (● ذخیره نشده · Ctrl+S) shown when form differs from last-saved snapshot; cleared on successful save.
• Article editor: amber "بازخورد ویراستار" banner when opening a نیازمند اصلاح article with a reviewer note.
• Articles list: hard cap of 15 replaced with "نمایش X مورد دیگر" show-more/less button; reviewer note shown inline for revision-flagged rows.
• Overview recent-articles: reviewer note shown inline for نیازمند اصلاح articles.
• Comments tab: article title chip added next to commenter name; cap note explains 8-recent limit and redirects to article for full thread.
• Backend: articleInclude now joins review { note, status }; publicArticle exposes reviewNote; flows through writer dashboard, articles list, and editor.

Remaining Work

• Linux validation (blocking for production):
  • cd backend && npm run prisma:generate
  • cd backend && npm run prisma:apply
  • cd backend && npm run seed
  • npm run seo:sitemap && npm run og:images && npm run build
  • npm run check:seo
  • cd backend && npm run build
  • npm run smoke:prod
• Verify all flows after schema apply: auth, comments/likes/flags, history, notifications/SSE, reading lists, topic/writer follows, tag pages, series, topic hubs, newsletter archive/campaigns, review workflow, analytics endpoints, panel metrics, first-party events.
• Rotate all seed/admin passwords after first production login.
• Remove resetPasswordOnSeed from writer-admin credentials after rotation.
• Confirm SMTP and Kavenegar credentials.
• Nice-to-have (not blocking): article save list picker UI; topic-targeted new-article notifications; Search Console/Bing Webmaster local verification files.

Editorial Rules

• Every published article should have one topic/category, two or more internal links, a canonical path, local OG image, source notes, and fact-check date.
• Articles older than 90 days should be marked needs_update unless reviewed.
• External analytics scripts remain out of scope for Phase 10 because of zero-CDN and privacy goals.