کارت سلامت موجودیت (EntityHealthCard)

معرفی

EntityHealthCard کارت canonical برای نمایش وضعیت سلامت موجودیت‌های long-lived است — ورکرهای افکارسنجی/بوستر، پیج‌های تحت رصد، منابع فید، حساب‌های داده‌گیری. برخلاف JobCard که lifecycle کار async (queued→completed) را نشان می‌دهد، این کارت «چقدر سالم است؟»، «چرا؟»، و «الان چه کار کنیم؟» را پاسخ می‌دهد.

شش سطح شدت (ordered worst → best):

• banned — موجودیت مسدود شده (مثلاً پیج از سمت پلتفرم)
• at-risk — نیاز به مداخله فوری (شکست بررسی، نقض قوانین)
• warning — متریک‌ها در حال افت
• pending — هنوز ارزیابی نشده (جدید، setup، در حال warmup)
• growing — در حال بهبود ولی هنوز به ثبات نرسیده
• healthy — پایدار و سالم

چه زمانی استفاده کنیم:

• لیست ورکرهای بوستر با وضعیت ban/warmup/operational
• گرید پیج‌های تحت رصد با score و trend
• dashboard منابع فید با trust score و last-check
• هر entity که «سلامت» در domain‌ش concept اصلی است

چه زمانی استفاده نکنیم:

• نمایش lifecycle کار async (queued/running/completed) — از JobCard استفاده کنید
• متریک تک‌عدد با trend — از MetricCard استفاده کنید
• کارت پروفایل کاربر/پیج بدون بار سلامت — از ProfileCard استفاده کنید
• وضعیت operational کوتاه‌مدت (critical/warning/middle/low) — از StatusBadge استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده

'use client'
import {
  EntityHealthCard,
  EntityHealthCardHeader,
  EntityHealthCardHeaderText,
  EntityHealthCardHeaderEnd,
  EntityHealthCardTitle,
  EntityHealthCardSubtitle,
  EntityHealthCardSeverityBadge,
  EntityHealthCardScore,
  EntityHealthCardNarrative,
  EntityHealthCardTrust,
  EntityHealthCardPhase,
  EntityHealthCardMetrics,
  EntityHealthCardMetric,
  EntityHealthCardFooter,
  EntityHealthCardActions,
  EntityHealthCardMeta,
  Button,
} from '@parto-system-design/ui'

export function WorkerHealth({ worker }) {
  return (
    <EntityHealthCard severity={worker.severity} interactive onClick={() => openWorker(worker.id)}>
      <EntityHealthCardHeader>
        <EntityHealthCardHeaderText>
          <EntityHealthCardTitle>@{worker.username}</EntityHealthCardTitle>
          <EntityHealthCardSubtitle>ورکر اینستاگرام</EntityHealthCardSubtitle>
        </EntityHealthCardHeaderText>
        <EntityHealthCardHeaderEnd>
          <EntityHealthCardSeverityBadge />
        </EntityHealthCardHeaderEnd>
      </EntityHealthCardHeader>
      <EntityHealthCardScore value={worker.score} label="نمره سلامت" delta={worker.delta} />
      <EntityHealthCardNarrative>{worker.narrative}</EntityHealthCardNarrative>
      <EntityHealthCardTrust value={worker.trustScore} />
      <EntityHealthCardPhase phase="warmup" day={worker.day} total={worker.totalDays} />
      <EntityHealthCardMetrics>
        <EntityHealthCardMetric label="عملیات امروز" value={worker.actionsToday} />
        <EntityHealthCardMetric label="موفقیت" value={`${worker.successRate}٪`} trend="down" />
      </EntityHealthCardMetrics>
      <EntityHealthCardFooter>
        <EntityHealthCardMeta>آخرین بررسی ۵ دقیقه پیش</EntityHealthCardMeta>
        <EntityHealthCardActions>
          <Button size="sm">بررسی</Button>
        </EntityHealthCardActions>
      </EntityHealthCardFooter>
    </EntityHealthCard>
  )
}

Sub-componentها از context برای severity / size / locale استفاده می‌کنند — رنگ، آیکون، label، و قالب عدد خودکار هماهنگ می‌شوند.

شش سطح شدت

همه شش سطح از طریق prop severity روی root تعریف می‌شوند. رنگ border-accent (سمت start منطقی)، رنگ badge و آیکون progress خودکار از طریق token ها نگاشته می‌شود.

• banned / at-risk — مپ می‌شوند به --destructive-default. آیکون متمایز (Ban vs AlertTriangle) و pulse روی badge برای جلب توجه.
• warning — --warning-default (کهربایی).
• pending — --sentiment-neutral (خاکستری — «هنوز ارزیابی نشده»).
• growing — --brand-default (آبی — «در حال بهبود»).
• healthy — --sentiment-positive (سبز — «سالم»).

کمک‌تابع isCriticalEntityHealth(severity) برای flag کردن مواردی که نیاز به مداخله فوری دارند (banned + at-risk)، و entityHealthPriority برای sort «worst first» صادر می‌شوند.

حالت برای صفحه رصد (Page Evaluation)

کارت با score۰-۱۰۰ (formula: ۰٫۶ × engagement + ۰٫۴ × growth) و metric grid برای نمایش breakdown — همان الگوی پنل ارزیابی اما با قدرت DS.

حالت compact برای گرید/لیست

با size="sm" و حذف بخش‌های اختیاری (narrative / trust / phase)، کارت به یک ردیف فشرده تبدیل می‌شود که در گرید ۳ یا ۴ ستونه کاربرد دارد.

ترکیب با badge-only برای inbox

در حالت‌های بسیار فشرده (نوتیفیکیشن inbox، سلسله ردیف‌ها)، می‌توان فقط title + severity badge را نشان داد. iconOnly روی badge + حذف همه بخش‌های محتوایی.

حالت interactive

با interactive یا onClick، کل کارت کلیک‌پذیر می‌شود، role="button" + tabIndex=0 می‌گیرد، و keyboard (Enter/Space) پشتیبانی می‌شود. کلیک‌های داخل EntityHealthCardActions به root bubble نمی‌کنند تا دکمه‌های عمل جداگانه کار کنند.

راهنمای استفاده

Props

EntityHealthCard

EntityHealthCardSeverityBadge

EntityHealthCardScore

EntityHealthCardTrust

EntityHealthCardPhase

EntityHealthCardMetric

EntityHealthCardMetrics

دسترسی‌پذیری

• EntityHealthCard به‌صورت پیش‌فرض role="region" می‌گیرد تا screen reader آن را یک landmark بشناسد. با interactive به role="button" + tabIndex=0 + keyboard handler تبدیل می‌شود.
• EntityHealthCardSeverityBadge در حالت iconOnly هنوز aria-label localized دارد.
• EntityHealthCardTrust و EntityHealthCardPhase از role="progressbar" با aria-valuenow/min/max استفاده می‌کنند.
• EntityHealthCardScore.delta با arrow بصری، aria-label متنی (مثل «تغییر منفی») برای screen reader اضافه می‌کند.
• pulse روی badge برای banned و at-risk با motion-safe:animate-pulse ست شده — در prefers-reduced-motion: reduce ساکن می‌ماند.
• همه تون‌های متنی formal Farsi هستند؛ trilingual (fa/ar/en) پشتیبانی می‌شود.

کامپوننت‌های مرتبط

• JobCard — برای async work با lifecycle تعریف‌شده (queued→completed). اگر entity شما «task» است نه «entity سلامت‌دار»، JobCard را انتخاب کنید
• MetricCard — برای متریک تک‌عدد؛ وقتی «سلامت» concept اصلی نیست
• ProfileCard — کارت پروفایل بدون بار سلامت؛ برای influencer/author
• StatusBadge — badge وضعیت operational (critical/warning/middle/low) کوتاه‌مدت؛ این کارت روایت طولانی‌تر می‌دهد
• SeverityBadge — badge اولویت (urgent/high/medium/low)؛ مستقل از سلامت entity
• StatusFlow — وقتی نیاز به نمایش pipeline چندمرحله‌ای lifecycle دارید