مفاهیم دامنه

پرتو یک کتابخانه عمومی نیست. کامپوننت‌های آن دانش خاص دامنه سوشال لیسنینگ را کدگذاری می‌کنند. این صفحه این مفاهیم را توضیح می‌دهد.

دسته‌بندی اینفلوئنسرها

اینفلوئنسرها بر اساس تعداد دنبال‌کننده به پنج دسته تقسیم می‌شوند. کلید ستون اول همان مقداری است که در کد می‌نویسید (تایپ FollowerGroup):

هر دسته آستانه‌های نرخ تعامل مخصوص خودش را دارد — نرخ 3٪ برای یک حساب نانو «متوسط» است و برای یک حساب مگا «عالی». آستانه‌ها در ENGAGEMENT_RANGES تعریف شده‌اند (برچسب‌ها در GROUP_LABELS) و getFollowerGroup(followers) دسته را از تعداد دنبال‌کننده استخراج می‌کند.

این دسته‌بندی در EngagementRate به کار می‌رود: سطح نرخ تعامل هر حساب با آستانه‌های دستهٔ خودش سنجیده می‌شود.

نمونه بصری

هر دسته با بازهٔ دنبال‌کننده، نرخی که برایش «عالی» است، و یک حساب نمونه که getFollowerGroup دسته‌اش را تعیین می‌کند:

import { ENGAGEMENT_RANGES, GROUP_LABELS, getFollowerGroup } from '@partodata/ui'

getFollowerGroup(45_000) // 'micro'
GROUP_LABELS.fa.micro // 'میکرو'
ENGAGEMENT_RANGES.micro.excellent // 4 (درصد)

سطوح نرخ تعامل (Engagement Tiers)

نرخ تعامل (Engagement Rate) — نسبت تعاملات (لایک، کامنت، ذخیره) به دنبال‌کننده‌ها — به شش سطح رنگ‌کدشده تقسیم می‌شود:

نمونه بصری — نرخ تعامل

آستانه‌های متفاوت به دسته

هر دسته اینفلوئنسر آستانه‌های متفاوتی برای هر سطح دارد. نرخ تعامل 3٪ برای یک مگا اینفلوئنسر «عالی» است، اما برای یک نانو اینفلوئنسر «متوسط».

import { EngagementRate } from '@partodata/ui'

// نرخ 3٪ برای مگا → سطح "عالی"
<EngagementRate value={3.2} category="mega" />

// نرخ 3٪ برای نانو → سطح "متوسط"
<EngagementRate value={3.2} category="nano" />

تحلیل احساسات (Sentiment Analysis)

محتوای شبکه‌های اجتماعی به سه نوع احساس تقسیم می‌شود:

نمونه بصری

import { SentimentBadge, Distribution } from '@partodata/ui'

// نشان احساس یک آیتم
<SentimentBadge sentiment="positive" />
<SentimentBadge sentiment="neutral" />
<SentimentBadge sentiment="negative" />

// توزیع احساسات (درصدی)
<Distribution kind="sentiment"
  positive={65}
  neutral={25}
  negative={10}
/>

پلتفرم‌های اجتماعی

پلتفرم‌های متعددی با رنگ‌های برند اختصاصی پشتیبانی می‌شوند. پرکاربردترین شبکه‌های اجتماعی:

علاوه بر این‌ها، پلتفرم‌های دیگری مانند فیس‌بوک و رسانه‌های پخش (تلویزیون، رادیو، مطبوعات) نیز توکن رنگ برند اختصاصی دارند.

این نام‌های رشته‌ای همان source در PlatformMark هستند. قرارداد عمومی PostData از کد عددی search-content استفاده می‌کند: 1 اینستاگرام، 2 فیس‌بوک، 3 وب‌سایت و 4 تلگرام. هر عدد بزرگ‌تر از 4 معتبر است و به‌صورت پلتفرم N با icon عمومی نمایش داده می‌شود؛ پرتو آن را به یک شبکه‌ی شناخته‌شده تبدیل نمی‌کند.

نمونه بصری

import { PlatformMark } from '@partodata/ui/social'

<PlatformMark source="instagram" showLabel />
<PlatformMark source="telegram" showLabel />
<PlatformMark source="youtube" showLabel />

کامپوننت Post

هر پست، خبر یا بخش پخش با یک کامپوننت نمایش داده می‌شود: Post از @partodata/ui/social، با مدل SocialPost و یک محور کوچک layout (card که پیش‌فرض همه‌جاست؛ و به‌صراحت row، tile، summary، details). فهرست پست‌ها یک EntityCollection از Post است؛ نظرها Comment و حساب‌ها Account. هر 11 منبع (شبکه‌های اجتماعی، وب، مطبوعات، تلویزیون و رادیو) همین یک مدل را دارند.

دادهٔ تخت API سرویس search-content (PostData) را پیش از نمایش یک بار با fromPostData از @partodata/ui/social/adapters به مدل تبدیل کنید. در PostData، domain نام کاربری حساب است، نه hostname یا دامنه‌ی وب؛ رشته‌ی خالی نیز معتبر است و به هویت localized پلتفرم fallback می‌کند. profilePictureUrl آواتار، thumbnailUrl رسانه، body متن/caption، summary lead وب‌سایت و dateCreated epoch milliseconds است. engagementRate نسبت اعشاری است و هنگام نمایش یک بار درصد می‌شود (0.032 به‌صورت 3.2٪). فیلدهای language و platform عددی‌اند و نام زبان از روی کد حدس زده نمی‌شود.

'use client'

import type { PostData } from '@partodata/ui'
import { Post } from '@partodata/ui/social'
import { fromPostData } from '@partodata/ui/social/adapters'

const row: PostData = {
  domain: 'partodata',
  profilePictureUrl: 'https://cdn.example.com/avatar.jpg',
  platform: 1,
  title: 'گزارش رویداد فناوری',
  body: 'متن پست نمونه درباره رویداد فناوری',
  summary: '',
  thumbnailUrl: 'https://cdn.example.com/post.jpg',
  url: 'Dby-dorhHbF',
  hashtags: ['فناوری'],
  likeCount: 820,
  commentCount: 42,
  viewCount: 12500,
  videoPlayCount: 0,
  engagementRate: 0.032,
  followerCount: 45000,
  followingCount: 210,
  language: 1,
  categoryName: 'فناوری',
  domainRank: 68,
  dateCreated: Date.now() - 60_000 * 23,
}

// Once, before rendering: the model the social components take.
const post = fromPostData(row)

export function PostPreview() {
  return <Post post={post} layout="card" />
}

فیلدهای Parto مانند sentiment، content، quoted و platformMeta و metricهای تخت اختیاری (shares، reposts، quotes، saves، reach، audience، reads و domainAuthority) extensionهای جدا از 20 فیلد الزامی بالا هستند و fromPostData آن‌ها را به مدل می‌برد (رسانه‌ها، خبر و بخش پخش، سیگنال‌ها، پرچم‌ها). کد عددی ناشناخته‌ی پلتفرم و برچسب عمومی آن همیشه حفظ و نمایش داده می‌شود. مبدل صفرهای ساختگی API را نامعلوم می‌کند (بازدید، نرخ تعامل و آمار حساب با مقدار 0 «—» نمایش داده می‌شوند) و شمارنده‌ای را که منبع ندارد اصلاً نمایش نمی‌دهد. کد نسخهٔ 3 که هنوز PostCard دارد (در 5.0 حذف شد) به Post با fromPostData می‌رود.

توکن‌های رنگی دامنه

توکن‌های CSS اختصاصی دامنه در globals.css تعریف شده‌اند و در هر دو تم کار می‌کنند. نمونهٔ زندهٔ هر توکن در تم فعلی (برای دیدن تم دیگر، تم سایت را عوض کنید؛ روی هر ردیف بزنید تا نامش کپی شود):

/* سطوح تعامل */
--engagement-excellent
--engagement-very-good
--engagement-good
--engagement-average
--engagement-low
--engagement-poor

/* احساسات */
--sentiment-positive
--sentiment-neutral
--sentiment-negative

این توکن‌ها مانند سایر توکن‌های سیستم در تم‌های روشن و تاریک به درستی کار می‌کنند.