wealth/docs/round-5-admin.md

348 lines
27 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Round 5 — Admin panel
> Attach together with `design-brief.md`. The brief defines the design system, shared patterns and status vocabulary; this file holds the full acceptance criteria and exact Farsi copy.
> Desktop-first with full tables; mobile is a simplified card list. Reuse the status badges from earlier rounds.
## Deliver in this round
- Admin shell: sidebar with pending-count badge
- Verification queue: tabs, search, sort, pagination, empty state
- Verification detail: ID image lightbox, previous/next, submission history, audit log, approve dialog (normal and suspended), reject panel with templates
- Creator management list (suspended row tint) and detail: suspend dialog (subscriber impact), reinstate dialog (extension summary)
For every screen: mobile and desktop, RTL, real Farsi copy from below, and all listed states.
## Stories included
- **A1** — Admin: Creator Verification Review _(ClickUp status: backlog)_
- **A2** — Admin: Creator Account Suspension & Reinstatement _(ClickUp status: backlog)_
---
## A1 — Admin: Creator Verification Review
A1 — Admin: Creator Verification Review
Story:
As an admin, I want to view and manually approve or reject creator verification requests so that I can ensure platform quality and manage onboarding.
Acceptance Criteria:
1. Access & Entry Point
Happy Path:
Admin accesses the verification requests section from the main Admin Panel navigation
The section displays a list of all Pending Verification requests sorted by submission date — oldest first
A badge on the navigation item shows the count of pending requests at all times
Edge Cases:
If there are no pending requests, an empty state is shown with a clear message
Admin can also access Verified and Rejected creator lists as separate filtered views within the same section
Farsi copy:
Navigation item label: احراز هویت کریتورها
Pending badge tooltip: {n} درخواست در انتظار بررسی
Empty state: هیچ درخواست جدیدی برای بررسی وجود ندارد.
Filter tabs: در انتظار بررسی · تأییدشده · رد شده
2. Verification Request List
Happy Path:
Each row in the list shows the following summary information:
Name — first name and last name displayed together as a single combined string (e.g., رضا احمدی), even though the underlying data is stored as two separate fields (per C1 Sections 3.2–3.3)
Username
Phone number
Submission date and time
Current status (Pending / Verified / Rejected)
Admin can click any row to open the full verification detail view
Edge Cases:
List is paginated — maximum 20 rows per page
Admin can search by name (matches either first name, last name, or the combined string), username, or phone number
Admin can sort by submission date (ascending / descending)
Error States:
If the list fails to load due to a network error, an error message is shown with a retry option
Farsi copy:
Table column headers: نام و نام خانوادگی · نام کاربری · شماره موبایل · تاریخ ارسال · وضعیت
Search placeholder: جستجو بر اساس نام، نام کاربری یا شماره موبایل
Load error: خطا در بارگذاری لیست. دوباره تلاش کنید.
3. Verification Detail View
Happy Path:
Clicking a request row opens a detail view showing all of the following:
Name — first name and last name shown together as a single combined label (same display rule as Section 2), though stored and independently editable as two separate fields — this matters specifically during a Rejected resubmission, where a creator may correct only one of the two (per C3 Section 3)
Username
Phone number
Submission date and time
Uploaded national ID card image — displayed at a readable size, with a zoom/full-screen option and a download option
Two action buttons are shown: Approve and Reject
Admin can navigate to the previous or next pending request without returning to the list
Edge Cases:
If the creator has resubmitted after a previous rejection, the detail view shows the full history of all past submissions for that creator — each with its date, the admin action taken, and the rejection reason if applicable
The national ID card image opens in a lightbox/full-screen viewer for clarity — the admin must be able to read the card details clearly
If the creator's account has been suspended (via A2) between submission and admin review, a warning banner is shown in the detail view — the admin can still approve or reject; approval on a suspended account does not automatically reinstate it (A2 suspension must be lifted separately)
Error States:
If the national ID card image fails to load, a retry option is shown — the admin cannot take an action without being able to view the image
If the national ID card image fails to download, an error message is shown with a retry option
If the detail view fails to load, an error message with a retry option is shown
Farsi copy:
Detail view heading: بررسی درخواست احراز هویت
Name label: نام و نام خانوادگی
Username label: نام کاربری
Phone label: شماره موبایل
Submission date label: تاریخ ارسال
ID image label: تصویر کارت ملی
Image zoom CTA: مشاهده تصویر کامل
Image download CTA: دانلود تصویر
Image load error: بارگذاری تصویر ناموفق بود. دوباره تلاش کنید.
Image download error: دانلود تصویر ناموفق بود. دوباره تلاش کنید.
Previous request CTA: درخواست قبلی
Next request CTA: درخواست بعدی
Submission history heading: تاریخچه ارسال‌های قبلی
Suspended account warning: این حساب در حال حاضر توسط ادمین تعلیق شده است. تأیید هویت، تعلیق را لغو نمی‌کند.
4. Approve Action
Happy Path:
Admin clicks the Approve CTA
A confirmation dialog appears asking the admin to confirm the approval
Admin confirms — creator status is set to Verified immediately
The request is removed from the Pending list and moved to the Verified list
Creator receives an in-app notification and SMS (as defined in C1 Section 6)
The approval action is logged with a timestamp and the admin's account ID
Edge Cases:
If the creator's account is currently suspended, approval sets the verification status to Verified but does not lift the suspension — the account remains suspended until an admin explicitly reinstates it via A2. A note in the confirmation dialog informs the admin of this.
Error States:
If the approval action fails due to a network error, an error message is shown and the creator's status remains Pending — the admin can retry
Farsi copy:
Approve CTA: تأیید
Confirmation dialog heading: تأیید درخواست
Confirmation dialog body (normal): آیا از تأیید هویت این کریتور اطمینان دارید؟
Confirmation dialog body (suspended account): این حساب در حال حاضر تعلیق شده است. تأیید هویت، تعلیق را لغو نمی‌کند و حساب تا رفع تعلیق غیرفعال می‌ماند. آیا ادامه می‌دهید؟
Confirm CTA: بله، تأیید کن
Cancel CTA: انصراف
Success message: حساب کریتور با موفقیت تأیید شد.
Network error: خطا در انجام عملیات. دوباره تلاش کنید.
5. Reject Action
Happy Path:
Admin clicks the Reject CTA
A rejection panel/dialog opens with a mandatory free-text field for the rejection reason
Admin enters the rejection reason and confirms
Creator status is set to Rejected
The request is removed from the Pending list and moved to the Rejected list
Creator receives an in-app notification and SMS with the rejection reason (as defined in C1 Section 6)
The rejection action is logged with a timestamp, the admin's account ID, and the rejection reason
The creator resubmits exclusively through C3 (اطلاعات کاربری) — first name, last name, and national ID unlock there (pre-filled with prior values), the ID card image field is always empty and requires a fresh selection, and username remains permanently locked. There is no separate resubmission form or admin-side re-entry mechanism; the resubmitted request appears back in this same Pending queue, indistinguishable in structure from a first-time submission
Edge Cases:
Rejection reason field is mandatory — the reject confirmation button is disabled until text is entered
Admin can use predefined reason templates (see below) to speed up the process — selecting a template pre-fills the field, which the admin can then edit
Rejection reason is visible to the creator in their profile area and in the SMS notification
Predefined Rejection Reason Templates:
Template label (Farsi) Pre-filled text (Farsi)
عدم تطابق اطلاعات اطلاعات وارد‌شده با مدارک ارسالی مطابقت ندارد.
تصویر ناخوانا تصویر کارت ملی ارسال‌شده واضح نیست. لطفاً تصویر با کیفیت بالاتر ارسال کنید.
مدرک ناقص مدارک ارسالی ناقص است. لطفاً اطلاعات را تکمیل و مجدداً ارسال کنید.
سایر — (admin writes manually)
Error States:
If rejection reason is empty and admin attempts to confirm, the confirm button remains disabled
If the rejection action fails due to a network error, an error message is shown and the creator's status remains Pending — admin can retry
Farsi copy:
Reject CTA: رد کردن
Rejection panel heading: رد درخواست احراز هویت
Rejection reason field label: دلیل رد درخواست
Rejection reason placeholder: دلیل رد را بنویسید یا از پیش‌فرض‌های زیر انتخاب کنید...
Template selector label: انتخاب دلیل پیش‌فرض
Confirm reject CTA (disabled until reason entered): رد کردن و اطلاع‌رسانی
Cancel CTA: انصراف
Success message: درخواست رد شد و کریتور مطلع گردید.
Network error: خطا در انجام عملیات. دوباره تلاش کنید.
6. Audit Log
Every admin action (approval or rejection) is permanently logged with:
Admin account ID and name
Action taken (Approved / Rejected)
Timestamp (date and time)
Rejection reason (if applicable)
The audit log is viewable within the creator's detail view under a collapsible "تاریخچه اقدامات" section
Audit log entries are immutable — no admin can edit or delete them
Farsi copy:
Audit log section heading: تاریخچه اقدامات
Log entry format: {admin_name} — {action} — {date} — {reason if rejected}
Approved action label: تأیید شد
Rejected action label: رد شد
7. Notifications Triggered by Admin Actions
Admin Action Creator Notification
Approve In-app + SMS — account approved
Reject In-app + SMS — account rejected with reason
Notifications are sent automatically by the system upon admin confirmation — no manual step required from the admin
8. UI / UX
Admin Panel layout is RTL throughout; Yekan Bakh is the typeface for all Farsi text
Pending status badge on navigation item uses {colors.ruby} (#ea2261) background with white text
Status labels use consistent color coding: Pending — {colors.ink-mute} (#64748d) with clock icon; Verified — {colors.primary} (#533afd) with checkmark icon; Rejected — {colors.ruby} (#ea2261) with warning icon
Approve button uses button-primary-pill style (#533afd)
Reject button uses button-secondary style, overridden to {colors.ruby} text and border instead of the component's default {colors.primary} — a deliberate semantic deviation (danger action), not an error
Confirm reject button is visually disabled (opacity: 0.4, cursor: not-allowed) until rejection reason is entered
National ID card image viewer is a full-screen lightbox with zoom and download support — minimum display size 600px on desktop
Predefined rejection reason templates displayed as pill-tag-soft chips
Admin Panel is desktop-first — optimized for desktop use with full table layout; mobile view is a simplified card list
---
## A2 — Admin: Creator Account Suspension & Reinstatement
A2 — Admin: Creator Account Suspension & Reinstatement
Story:
As an admin, I want to suspend or reinstate a creator account so that I can respond to policy violations or errors quickly.
Product decision (Option A adopted): Suspension is a full blackout — the creator's profile and all content are hidden from everyone; existing subscribers lose access for the duration of the suspension.
⚠️ Forward dependency note: Sections 4–6 introduce subscriber notification, a suspension pause clock, and a refund/extension choice. The refund mechanism itself (pro-rated calculation, ZarinPal card return, admin execution) is owned by Epic 11 — Financial Operations. The investor-facing action surface lives on the U2 subscription card and must be added there.
Acceptance Criteria:
1. Access & Entry Point
Happy Path:
Admin can suspend/reinstate from two entry points: the creator list (context menu or action button per row) and the creator detail view (action button in the header)
Available at all times for any creator regardless of verification state
The suspend action appears only for Active creators; reinstate only for Suspended creators — never both simultaneously
Farsi copy:
Navigation item label: مدیریت کریتورها
Suspend CTA (list row): تعلیق حساب
Reinstate CTA (list row): رفع تعلیق
2. Suspension Action
Happy Path:
The suspension dialog requires a free-text reason, with optional predefined templates
On confirm: status set to Suspended immediately; action logged (timestamp + admin ID); creator notified in-app + SMS
All active subscribers are notified simultaneously (Section 4)
The suspension pause clock starts for every active subscription (Section 5)
Edge Cases:
A Pending Verification creator can be suspended — the states coexist (Pending AND Suspended)
A Rejected creator can also be suspended
An already-suspended account cannot be suspended again — the CTA is hidden in that state
The dialog shows the number of active subscribers who will be affected, so the admin understands the blast radius before confirming
Predefined Suspension Reason Templates:
Template label (Farsi) Pre-filled text (Farsi)
نقض قوانین پلتفرم حساب شما به دلیل نقض قوانین پلتفرم تعلیق شده است.
محتوای نامناسب حساب شما به دلیل انتشار محتوای نامناسب یا غیرمجاز تعلیق شده است.
گزارش تخلف حساب شما به دلیل دریافت گزارش تخلف در حال بررسی است.
خطای اداری این تعلیق به دلیل خطای اداری بوده و به زودی رفع خواهد شد.
سایر — (admin writes manually)
Farsi copy:
Suspension dialog heading: تعلیق حساب کریتور
Affected subscribers note: این کریتور در حال حاضر {n} مشترک فعال دارد. با تعلیق حساب، دسترسی آن‌ها قطع می‌شود و امکان درخواست بازگشت وجه یا تمدید اشتراک به آن‌ها اطلاع داده خواهد شد.
Reason field label: دلیل تعلیق
Reason placeholder: دلیل تعلیق را بنویسید یا از پیش‌فرض‌های زیر انتخاب کنید...
Confirm CTA: تعلیق و اطلاع‌رسانی
Cancel CTA: انصراف
Success message: حساب کریتور تعلیق شد و {n} مشترک فعال مطلع شدند.
Network error: خطا در انجام عملیات. دوباره تلاش کنید.
3. Effects of Suspension
Take effect immediately:
Area Effect
Creator login Cannot log in — shown suspended message
Creator profile Hidden from all public-facing surfaces
Creator content All posts, predictions, channel content hidden
New subscriptions Blocked — channel undiscoverable and unsubscribable
Active subscriber access Revoked for the suspension duration
Payments No new payments; no renewals or reactivations processed
Creator dashboard Inaccessible
Subscription pause clock Starts for every active subscription (Section 5)
Waitlist notifications Suppressed for this creator until reinstatement; entries preserved (U9 Section 6)
Follow relationships Preserved — posts simply disappear from followers' feeds (U8 Section 3)
Content that was free and public before suspension is also hidden — full blackout applies
A subscription expiring during suspension still expires on schedule, but the subscriber retains their refund right with no deadline (Section 6)
Farsi copy (creator login attempt while suspended):
Heading: حساب شما تعلیق شده است.
Body: دلیل: {suspension_reason} — برای اطلاعات بیشتر با پشتیبانی تماس بگیرید.
Support contact CTA: تماس با پشتیبانی
4. Subscriber Notification (New)
This section fulfils the commitment made in the platform's Subscription Terms, Section 3. Without it, an investor who paid for a year would lose access in month two with no explanation and no recourse — which the platform has explicitly undertaken not to do.
Happy Path:
At the moment of suspension, every investor with an active subscription to that creator is notified via in-app notification and SMS
The notification states plainly that access has paused, and presents the two options:
Request a pro-rated refund for the unused period
Wait — if the creator returns, the paused duration is added to their subscription
Taking no action defaults to option 2 (extension) — the option that preserves the relationship
The notification links to the investor's اشتراک‌ها section, where the affected subscription card carries the refund-request action
Edge Cases:
The reason for suspension is not disclosed to subscribers — only that access has paused. The reason is between the platform and the creator; sharing it would expose a creator to reputational damage before any appeal or reinstatement
Investors whose subscription to that creator has already expired are not notified — they have nothing paused
Investors merely following (not subscribed) are not notified — they lost no paid access
SMS follows the same retry policy as other transactional messages (up to 3 attempts, 10-minute intervals, per U5 Section 3)
Farsi copy:
In-app notification title: دسترسی به کانال {creator_username} موقتاً متوقف شد
In-app notification body: دسترسی شما به محتوای این کانال موقتاً متوقف شده است. می‌توانید مبلغ دوره استفاده‌نشده را به‌صورت نسبی درخواست کنید، یا منتظر بمانید تا در صورت بازگشت کانال، مدت توقف به اشتراک شما اضافه شود.
In-app notification CTA: مشاهده اشتراک
SMS: دسترسی شما به کانال {creator_username} در [نام پلتفرم] موقتاً متوقف شد. برای مشاهده گزینه‌های خود (بازگشت وجه یا تمدید اشتراک): [لینک به بخش اشتراک‌ها]
5. Suspension Pause Clock (New)
Happy Path:
On suspension, a pause clock starts for every active subscription to that creator, recording the exact suspension timestamp
On reinstatement, the clock stops and the elapsed suspended duration is computed
For every subscriber who did not request a refund, that duration is added to their expiry date automatically
Each affected subscriber is notified of their new expiry date (Section 7)
Edge Cases:
The pause clock is tracked per subscription, not per creator — subscriptions purchased at different times all pause and resume together, but each carries its own adjusted expiry
Duration is measured to the minute, not the day — a 3-day-4-hour suspension extends by exactly that
If a creator is suspended and reinstated multiple times, each pause accumulates onto the same subscription
A subscriber who requested a refund during suspension is excluded from extension entirely — the two are mutually exclusive (Section 6)
If a subscription expired during suspension and no refund was requested, it remains expired on reinstatement. Extension applies only to subscriptions still within their term. The refund right persists regardless (Section 6)
6. Refund Requests During Suspension (New)
⚠️ The refund mechanism — pro-rated calculation, admin execution, ZarinPal card return — is owned by Epic 11 — Financial Operations. This section specifies only the trigger and its consequences within A2.
Happy Path:
While a creator is suspended, each affected subscriber sees a refund-request action on that creator's subscription card in اشتراک‌ها
Requesting a refund marks the subscription for admin review; the admin processes it per Epic 11
On refund completion, the subscription terminates — the subscriber forfeits any extension
Edge Cases:
Refund and extension are mutually exclusive — requesting one forfeits the other, and this is stated clearly at the point of request
There is no deadline for requesting a refund in Phase 0, including after a subscription would have expired naturally. A creator never reinstated leaves subscribers with an indefinite refund right
If a refund is requested and the creator is reinstated before it is processed, the request stands unless the investor cancels it — the platform does not silently void a request because circumstances changed
Requesting a refund does not unfollow the creator (U8) — those are independent
Forward dependency — U2 amendment required: the suspended-creator subscription card (U2 Section 2) currently dims and disables interaction entirely. It must gain a functional refund-request action while retaining the dimmed, non-navigable treatment for the rest of the card. This mirrors the precedent set in U8 Section 5, where a suspended creator's row stays dimmed but its unfollow action remains fully functional.
Farsi copy:
Refund action on subscription card: درخواست بازگشت وجه
Confirmation dialog heading: درخواست بازگشت وجه
Confirmation dialog body: مبلغ دوره استفاده‌نشده به‌صورت نسبی محاسبه و به کارت شما بازگردانده می‌شود. با ثبت این درخواست، اشتراک شما پایان می‌یابد و در صورت بازگشت کانال، تمدید نخواهد شد.
Confirm CTA: ثبت درخواست
Cancel CTA: انصراف
Request submitted toast: درخواست شما ثبت شد و به‌زودی بررسی می‌شود.
Card state after request: درخواست بازگشت وجه در حال بررسی
7. Reinstatement Action
Happy Path:
Admin taps رفع تعلیق; a confirmation dialog appears — no reason required
On confirm: status set to Active immediately; all suspended access restored (profile visible, content accessible, login enabled); action logged; creator notified in-app + SMS
The pause clock stops and extensions are applied automatically to every eligible subscription (Section 5)
Every extended subscriber is notified of their new expiry date
Edge Cases:
Reinstatement restores account access only — it does not affect verification state. A creator Pending before suspension remains Pending after
Subscribers who requested a refund are not extended and are not notified of any new expiry
Subscriptions that expired during suspension are not revived — they appear in اشتراک‌های منقضی‌شده (U3 Section 2) and can be reactivated normally
Waitlist notifications for this creator resume on reinstatement
The confirmation dialog shows how many subscriptions will be extended and by how long, so the admin sees the consequence before confirming
Farsi copy:
Reinstate CTA: رفع تعلیق
Confirmation dialog heading: رفع تعلیق حساب
Confirmation dialog body: با رفع تعلیق، دسترسی کریتور و مشترکان بازیابی می‌شود. {n} اشتراک فعال به مدت {duration} تمدید خواهد شد.
Confirm CTA: بله، رفع تعلیق
Cancel CTA: انصراف
Success message: تعلیق رفع شد و {n} اشتراک تمدید گردید.
Subscriber extension in-app notification: دسترسی شما به کانال {creator_username} بازیابی شد. اشتراک شما به مدت {duration} تمدید شد — تاریخ انقضای جدید: {new_expiry_date}
Subscriber extension SMS: دسترسی شما به کانال {creator_username} در [نام پلتفرم] بازیابی شد. اشتراک شما تا {new_expiry_date} تمدید شد.
8. Notifications Summary
Event Creator Active Subscribers
Suspension In-app + SMS, with reason In-app + SMS, without reason, with refund/extension choice
Reinstatement In-app + SMS In-app + SMS with new expiry date (extended subscribers only)
All notifications are sent automatically by the system on admin confirmation — no manual step required
Farsi copy:
Suspension SMS (creator): حساب کریتور شما در [نام پلتفرم] تعلیق شده است. دلیل: {suspension_reason} — برای اطلاعات بیشتر با پشتیبانی تماس بگیرید.
Suspension in-app (creator): حساب شما تعلیق شده است. دلیل: {suspension_reason}
Reinstatement SMS (creator): تعلیق حساب کریتور شما در [نام پلتفرم] رفع شد. اکنون می‌توانید وارد حساب خود شوید.
Reinstatement in-app (creator): تعلیق حساب شما رفع شد. خوش آمدید.
9. Audit Log
Every suspension and reinstatement is logged permanently with: admin ID and name, action, timestamp, suspension reason (suspensions only), number of subscribers affected, and total extension duration applied (reinstatements only)
Viewable in the creator's detail view under "تاریخچه اقدامات" — the shared log introduced in A1
Entries are immutable; full history shown chronologically across multiple suspension cycles
Farsi copy:
Suspended action label: تعلیق شد
Reinstated action label: رفع تعلیق شد
Log entry format: {admin_name} — {action} — {date} — {reason if suspended} — {n} مشترک متأثر
10. UI / UX
Admin Panel is RTL throughout; Yekan Bakh typeface
Status colours: Active — {colors.primary} (#533afd) with checkmark; Suspended — {colors.ruby} (#ea2261) with a ban icon
Suspend button uses button-secondary with {colors.ruby} text and border — a deliberate semantic deviation for a destructive action
Reinstate button uses button-primary-pill (#533afd)
Confirm-suspend button disabled (opacity: 0.4, cursor: not-allowed) until a reason is entered
Suspension reason templates render as pill-tag-soft chips
The affected-subscribers note in the suspension dialog and the extension summary in the reinstatement dialog both use {colors.ruby} — these are the consequence lines the admin most needs to register before confirming
Suspended creator rows in the list use a soft red tint (rgba(234, 34, 97, 0.05)) with a ban icon beside the status label
Admin Panel is desktop-first; mobile renders as a simplified card list
All prices, durations, and subscriber counts use font-feature-settings: "tnum"