teknav-bak/app/PHASE11.md

Phase 11 - Production Launch + Platform Completeness

Status: Implemented (Linux production validation pending)

Goal

Ship https://www.teknav.ir by completing Linux production validation (Track 0), then close the 13 confirmed platform gaps across admin completeness, reader UX, monetization activation, and reliability without introducing new dependencies or architectural shifts.

---

Track 0 — Production Gate [BLOCKING]

All items in this track must be completed before any Phase 11 feature work begins.

0.1 Linux Validation Sequence

Run in order on the production or staging Linux host:

Step	Command
Generate Prisma client	cd backend && npm run prisma:generate
Apply schema	cd backend && npm run prisma:apply
Seed database	cd backend && npm run seed
Install frontend deps (if needed)	npm install
Generate SEO artifacts	npm run seo:sitemap
Generate OG images	npm run og:images
Build frontend	npm run build
Build backend	cd backend && npm run build
Run smoke tests	npm run smoke:prod

0.2 Functional Verification Checklist

After schema apply, manually verify each flow:

• Login by email and by @username
• Signup with display name, username, password, email/phone
• SMS 2FA enable from profile → login returns tek_2fa ticket → /api/v1/auth/2fa/verify completes session
• Google/GitHub OAuth callback and session creation
• Password reset via SMTP
• Email verification via SMTP
• Profile edit for reader, writer, editor, reviewer, admin roles
• Password change with current-password confirmation
• Avatar upload and WebP conversion
• Article create → review workflow → publish (writer → reviewer → editor/admin)
• Scheduled publish fires via teknav-publish-due.timer
• Comments, replies, likes, flags, upvotes
• Reading history tracked on article view
• Reading lists — save to default list, list management
• Notifications and SSE stream at /api/v1/auth/notifications/stream
• Admin SSE at /api/v1/admin/stream (visitor counter, activity)
• Writer/topic follows and follow counts
• Tag pages at /tag/:tag
• Topic hub pages at /topics/ai etc.
• Newsletter archive at /newsletter and /newsletter/:slug
• Series pages at /series/:slug
• Glossary pages at /glossary/:slug
• Reactions (heart/fire/thinking) on articles
• Reading streak increments on daily visits
• Continue-reading progress saved in ReadHistory.progress
• Q&A endpoints at /api/v1/articles/:slug/qa
• /jobs, /courses, /membership pages render
• Premium article content locking for non-premium readers
• Sponsored label visible on promoted articles
• Errata notices on corrected articles
• Admin analytics at /api/v1/admin/analytics/*
• Panel metrics at /api/v1/admin/panel-metrics
• SEO audit at /api/v1/admin/seo/audit
• First-party error capture at /api/v1/errors
• /ACCOUNTS.md returns 403/404 through nginx
• /sitemap.xml, /robots.txt, /feed.xml return 2xx

0.3 Credential Rotation and Hardening

• Rotate all seed/admin passwords after first production login
• Remove resetPasswordOnSeed flag from writer-admin credentials in backend/prisma/credentials.json
• Confirm SMTP credentials in /etc/teknav/backend.env
• Confirm Kavenegar API key in /etc/teknav/backend.env
• Confirm OAUTH_CALLBACK_BASE=https://www.teknav.ir in env
• Verify ACCOUNTS.md is gitignored and HTTP-blocked

---

Track 1 — Admin + Editor Completeness [Quick wins — backend fully built]

All 5 items in this track have complete backend support. Only frontend wiring is missing.

1.1 Sponsored / premiumOnly / featured Toggles in ArticleEditor [S] ✓ DONE

Gap: Article.sponsored, Article.premiumOnly, and Article.featured exist in the Prisma schema and are returned by the admin articles API, but the ArticleEditor form in teknav-admin.jsx has no UI controls for them. A field helper (fieldRow) exists and is used for other boolean fields; these three are simply not called.

Fix: Add three toggle rows in the ArticleEditor meta-panel under a new "نشانه‌گذاری" (Flags) collapsible group:

• premiumOnly — "فقط اعضای ویژه" with lock icon
• sponsored — "محتوای حمایت‌شده" with badge icon
• featured — "مقاله ویژه" with star icon

Files: teknav-admin.jsx → ArticleEditor meta-panel

---

1.2 Content Freshness Filter in ArticlesManagement [S] ✓ DONE

Gap: Article.contentFreshnessStatus (values: up_to_date, needs_update, outdated) was added in Phase 10 but the ArticlesManagement filter bar only filters by status (draft/review/published etc.), not by freshness.

Fix: Add a <select> freshness filter dropdown alongside the existing status filter. Values: همه | به‌روز | نیاز به بازنگری | قدیمی. Wire to the existing articles list query param.

Files: teknav-admin.jsx → ArticlesManagement

---

1.3 SEO Audit Dedicated Tab [S] ✓ DONE

Gap: The SEO audit data from GET /api/v1/admin/seo/audit is fetched and displayed inline inside the analytics panel with a hard .slice(0,8) cap, and there is no dedicated tab for it. Issues beyond 8 are silently hidden.

Fix: Add a seo-audit tab to the AdminPanel tab bar. Move the full audit table there: show all issues paginated, add severity badges (خطا / هشدار / پیشنهاد), an article link per row, and a summary count header ("X مشکل یافت شد").

Files: teknav-admin.jsx → AdminPanel tabs, remove inline audit from analytics panel

---

1.4 Engagement Analytics Dedicated Tab [S] ✓ DONE

Gap: GET /api/v1/admin/analytics/engagement returns event-type counts, but the admin analytics panel only shows them as static count pills with no time-series, no per-article breakdown, and no comparison window.

Fix: Add an engagement sub-tab inside the existing analytics panel. Show:

• 7-day event count bar chart (reuse WeeklyChart or the filled-area SVG sparkline pattern)
• Event-type breakdown table: type | count | percentage of total
• Top 5 articles by engagement event count

Files: teknav-admin.jsx → analytics panel, src/lib/admin-api.js if endpoint not already called

---

1.5 Bulk Comment Moderation UI [M] ✓ DONE

Gap: POST /api/v1/admin/comments/bulk with { ids: [], action: 'delete'|'approve'|'flag' } exists in the backend but the CommentsModeration panel has no checkboxes or bulk-action toolbar.

Fix:

• Add a checkbox column to each comment row (left side, RTL-aware)
• Show a floating bulk-action bar when ≥1 comment is checked: "X مورد انتخاب شده | حذف | تأیید | علامت‌گذاری | لغو انتخاب"
• Wire to bulkModerateComments(ids, action) in src/lib/admin-api.js (method already exists)
• Clear selection and refresh list after action completes

Files: teknav-admin.jsx → CommentsModeration, src/lib/admin-api.js

---

Track 2 — Reader Experience [API infrastructure ready]

2.1 Article Card Save List Picker [S] ✓ DONE

Gap: Saving an article from the article card (home feed, search results, topic pages) calls contentApi.saveArticle() directly, which saves to the default list "بعداً بخوانم" without giving the reader a choice. The ReadingListModal (list picker) exists in teknav-articles.jsx for the full article detail page but is not wired to cards.

Fix: Lift ReadingListModal (or extract it to a shared location) so it can be triggered from ArticleCard. On card save-icon click: open the list picker modal, show user's reading lists + "ایجاد لیست جدید", save to the selected list.

Files: teknav-home.jsx (or wherever ArticleCard lives), teknav-articles.jsx (source of ReadingListModal)

---

2.2 Scheduled-Publish Topic Notifications Bug Fix [S] ✓ DONE

Gap: backend/scripts/publish-due.mjs sends writer-follow notifications when a scheduled article is published, but it does NOT look up TopicFollow records and notify topic followers. The TopicFollow model and the notification-creation pattern are already in the codebase from Phase 10.

Fix: After publishing a scheduled article in publish-due.mjs, query TopicFollow for the article's topic slug, then insert Notification records for each topic follower (same pattern as writer-follow notifications already in the script).

Files: backend/scripts/publish-due.mjs

---

2.3 Continue-Reading Progress Overlay on Article Cards [S] ✓ DONE

Gap: ReadHistory.progress (0–100 integer) is stored per article per user, and the backend returns it in history API responses. Article cards do not show any reading progress indicator, so readers cannot see which articles they have partially read.

Fix: On authenticated article card render, check if the article slug appears in the user's recent read history (available from engagementApi.getHistory()). If progress is between 5 and 95, show a thin progress bar at the bottom of the card image and a "ادامه مطالعه" chip.

Files: teknav-home.jsx → ArticleCard, src/lib/engagement-api.js

---

2.4 Search Console / Bing Webmaster Verification [S, operational] [DONE]

Gap: Site verification files for Google Search Console and Bing Webmaster Tools are not in public/. These are static files the crawlers expect (e.g. google<token>.html and BingSiteAuth.xml).

Fix: Add placeholder files to public/ with documented variable names. Operator fills in the actual tokens after production DNS is live. Add them to sitemap.xml exclusion so they don't show up as content pages.

Files: public/google<token>.html (placeholder), public/BingSiteAuth.xml (placeholder), scripts/generate-seo.mjs

---

Track 3 — Monetization & Premium

3.1 Premium Paywall Gate Card UX Upgrade [S] ✓ DONE

Gap: Premium article content locking in teknav-articles.jsx shows a single bare CTA button with no value proposition, no feature list, and no visual differentiation from the article content above. This produces low conversion.

Fix: Replace the bare CTA with a styled "قفل ویژه" gate card:

• Blurred/faded article excerpt above the gate (CSS mask-image gradient)
• Crown/lock icon + "این مقاله برای اعضای ویژه" headline
• 3-bullet benefit list (دسترسی به همه مقالات ویژه / بدون تبلیغ / حمایت از تکناو)
• Primary CTA: "عضویت ویژه" → /membership
• Secondary: "ورود به حساب" if user is not authenticated

Files: teknav-articles.jsx → premium gate section

---

3.2 Zarinpal Membership Subscription Flow [L] ✓ DONE

Gap: The /membership page is a static positioning page with no payment wiring. User.membershipTier exists in the schema but there is no route that upgrades it.

Design decisions:

• Payment gateway: Zarinpal for IRR transactions; Stripe noted as fallback for USD
• Flow: /membership → POST /api/v1/membership/subscribe → redirect to Zarinpal → callback to /api/v1/membership/callback → set User.membershipTier = 'premium' → redirect to /membership/success

New backend routes in backend/src/routes/monetization.ts:

• POST /api/v1/membership/subscribe — create Zarinpal payment request, return redirect URL
• GET /api/v1/membership/callback — verify Zarinpal callback, upgrade tier, create Notification
• GET /api/v1/membership/status — return current tier for authenticated user

Frontend changes:

• /membership page: wire CTA to POST /api/v1/membership/subscribe
• /membership/success route: show confirmation and "بازگشت به خانه"
• Profile settings: show current membership tier badge

Files: backend/src/routes/monetization.ts, teknav-articles.jsx (membership page), backend/prisma/schema.prisma (add MembershipPayment model for audit trail)

---

3.3 Job Listing Admin Panel [M] ✓ DONE

Gap: JobListing has a status field (pending, approved, rejected) and the public /jobs endpoint filters for approved only. Company submissions go through POST /api/v1/jobs but there is no admin UI or admin API endpoint to review and approve/reject pending listings.

New backend endpoint:

• GET /api/v1/admin/jobs — list all job listings with status filter
• PATCH /api/v1/admin/jobs/:id — set status to approved or rejected, optionally set featuredUntil

Frontend: Add a "آگهی‌های شغلی" tab to AdminPanel. Show a table: company | title | location | status | submitted date | actions (تأیید / رد / ویژه). Wire to new admin API methods in src/lib/admin-api.js.

Files: backend/src/routes/monetization.ts, teknav-admin.jsx → AdminPanel tabs, src/lib/admin-api.js

---

3.4 Premium Enforcement Audit [S] ✓ DONE (confirmed, no changes needed)

Gap: Article.premiumOnly is stored and returned by the admin API, but a review of backend/src/routes/public.ts is needed to confirm that publicArticle() strips article body content for non-premium authenticated users and unauthenticated users.

Fix: Audit publicArticle() in public.ts. If body is not stripped, add a content-gate: if article.premiumOnly && (!user || user.membershipTier !== 'premium'), return body: null and premiumGated: true in the serialized response. Confirm the frontend gate card is triggered by premiumGated: true.

Files: backend/src/routes/public.ts, teknav-articles.jsx

---

Track 4 — Reliability & Scale

4.1 Automated Test Suite [L]

Gap: backend/tests/phase10-smoke.test.mjs has 3 tests (auth, article fetch, comment post). There are no tests for: auth edge cases, profile editing, reading lists, comment moderation, analytics endpoints, panel metrics, or the review workflow.

Plan:

• Expand backend/tests/ with test files per domain: auth.test.mjs, articles.test.mjs, engagement.test.mjs, admin.test.mjs
• Each file: happy path + one error case per endpoint
• Use Node test runner (already used in smoke file) — no new test framework
• Target: ~40 tests total; run via cd backend && npm test
• Tests run against a local test database (separate TEST_DATABASE_URL env var)

Files: backend/tests/, backend/package.json (test script already wired)

---

4.2 First-Party Error Aggregation Dashboard [M] ✓ DONE

Gap: POST /api/v1/errors (in backend/src/routes/errors.ts) logs client errors to Pino but does not persist them. There is no way for ops/admin to see frontend error counts, top error messages, or affected users.

Design decision: Enhance first-party /api/v1/errors — consistent with zero-CDN, privacy-first architecture. No self-hosted GlitchTip or external SaaS.

Backend changes:

• Add ClientError model to backend/prisma/schema.prisma: id, message, stack, url, userId (nullable), userAgent, createdAt
• POST /api/v1/errors persists to ClientError in addition to Pino log
• GET /api/v1/admin/errors — aggregated view: top 10 error messages by count, count by day (last 30 days), most recent 20 raw errors (admin only)

Frontend changes:

• Add "خطاهای کلاینت" tab to AdminPanel (admin-only visibility)
• Show: daily error count sparkline, top-errors table (message | count | last seen), recent raw errors list

Files: backend/prisma/schema.prisma, backend/src/routes/errors.ts, teknav-admin.jsx, src/lib/admin-api.js

---

4.3 S3 Object Storage Interface Design [M] ✓ DONE (LocalStorageAdapter active, S3 stub ready)

Gap: Uploads go to /var/lib/teknav/uploads on local disk. When upload volume outgrows disk, migration to S3-compatible storage (Liara Object Storage, ArvanCloud, or MinIO) will be needed. No interface layer exists; storage path is hardcoded.

Design (no production wiring in Phase 11):

• Extract a StorageAdapter interface in backend/src/lib/storage.ts: upload(file, key) → url, delete(key), url(key)
• Implement LocalStorageAdapter (current behavior, no change)
• Implement S3StorageAdapter stub (wired but inactive; activated by STORAGE_BACKEND=s3 env var)
• Switch upload route in backend/src/routes/admin.ts to use the adapter
• Document required env vars: STORAGE_BACKEND, S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY

Files: backend/src/lib/storage.ts (new), backend/src/routes/admin.ts (upload handler)

---

4.4 Meilisearch Evaluation [S]

Gap: Persian FTS is handled by PostgreSQL to_tsvector with a custom Persian configuration. As article volume grows, ranking quality and response time may degrade. Meilisearch supports Persian (no stemming required for most Persian queries) and has a clean REST API.

Plan:

• Stand up a Meilisearch instance on the staging server alongside PostgreSQL
• Index the current 23 published articles
• Run identical queries through both PostgreSQL FTS and Meilisearch
• Measure: result relevance (manual spot-check), P95 query latency, index rebuild time
• Write a short evaluation note (2–3 paragraphs) as a follow-up to this phase
• Production wiring deferred to Phase 12 only if evaluation warrants

Files: backend/src/routes/public.ts (search endpoint, read-only audit), evaluation note in docs/meilisearch-eval.md

---

Complexity Reference

ID	Task	Complexity	Track
1.1	Sponsored/premiumOnly/featured toggles	S	Admin
1.2	Content freshness filter	S	Admin
1.3	SEO audit dedicated tab	S	Admin
1.4	Engagement analytics dedicated tab	S	Admin
1.5	Bulk comment moderation UI	M	Admin
2.1	Article card save list picker	S	Reader
2.2	Scheduled-publish topic notifications fix	S	Reader
2.3	Continue-reading overlay on cards	S	Reader
2.4	Search Console/Bing verification files	S	Ops
3.1	Premium gate card UX upgrade	S	Monetization
3.2	Zarinpal membership subscription flow	L	Monetization
3.3	Job listing admin panel	M	Monetization
3.4	Premium enforcement audit	S	Monetization
4.1	Automated test suite	L	Reliability
4.2	First-party error aggregation dashboard	M	Reliability
4.3	S3 storage interface design	M	Reliability
4.4	Meilisearch evaluation	S	Reliability

S = hours | M = 1–2 days | L = 3–5 days

---

Implementation Order

All batches 1–4 are complete. Remaining:

Batch 5 — Deferred (Phase 12 candidates)

• 4.1 Automated test suite (~40 tests) — backend/tests/
• 4.4 Meilisearch evaluation on staging → docs/meilisearch-eval.md
• S3 storage wiring (when upload volume requires it)

---

Constraints (carry-forward from Phase 10)

• Zero CDN. No third-party hosted JS, CSS, fonts, or assets. Zarinpal redirect is a server-side redirect — no inline scripts.
• Persian/RTL first. All new UI labels in Persian; logical CSS properties; no left/right assumptions.
• No mock admin data. Every new admin panel or tab must use real API data and show a proper empty state.
• No Docker. Production remains native Linux/systemd. S3 storage interface may reference MinIO as a local-dev option only.
• ACCOUNTS.md stays protected. No new paths or rewrites that could expose it.
• Backend APIs for all persistence. Frontend never touches the DB or session store directly.