arsam
e9cd12dda6
Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
146 lines
12 KiB
Markdown
146 lines
12 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|