wealth/docs/design-brief.md

427 lines
33 KiB
Markdown
Raw Normal View History

2026-10-02 13:57:42 +00:00
# Design Brief — Lumina (لومینا) · Verified Financial Creator Platform · MVP Phase 0
> Sources: PRD MVP Phase 0 v3.1 + ClickUp stories (23 tasks) + back-end codebase (`trading-platform` @ `3553719`).
> **Precedence:** ClickUp story > PRD for *behaviour*. The back end is used for *data shapes* and wherever a story is silent. Where a story and the back end conflict, **design to the story** and treat the conflict as an open decision (§9).
> Full acceptance criteria and exact Farsi copy for each story are in the `round-*.md` files. Attach the matching round file with this brief.
---
## 1. Product in one paragraph
Lumina is a platform for Iranian financial creators (analysts, signal providers) and the investors who follow them. Creators get a verified professional profile, a channel with free and premium posts, invite-only paid subscriptions, and **structured, immutable predictions** that the system tracks automatically. Investors can judge a creator by a **verifiable track record** before paying.
The core positioning is **performance proof over social proof**. The product must feel credible and professional, not like another Telegram channel. Because of this, follower counts are never shown publicly, and prediction outcomes are never hidden behind the paywall.
Phase 0 is a **closed beta**: 5–10 hand-picked creators and about 50 paying subscribers.
---
## 2. Platform and locale (confirmed)
| Topic | Decision |
|---|---|
| Stack | NX monorepo + Next.js, one responsive web app for **mobile and desktop** |
| Priority | **Mobile-first** for investor and creator surfaces; **desktop-first** for the admin panel (mobile = simplified card list) |
| Direction | **RTL** throughout. LTR exceptions: شبا field, URLs, usernames, tickers, signed amounts (§4.4) |
| Language | Persian. Persian digits (۰–۹) in UI, `٬` as thousands separator |
| Currency | تومان, whole numbers only |
| Dates | Shamsi (Jalali), e.g. `۱۵ خرداد ۱۴۰۴، ساعت ۱۴:۳۰`. Relative for recent items: همین الان · ۵ دقیقه پیش · ۲ ساعت پیش · دیروز. Timezone Asia/Tehran |
| Auth | Iranian mobile number (09XXXXXXXXX) + 5-digit SMS OTP. One entry screen for login and registration. Investor and creator accounts are separate (one number = one role) |
| Notifications | SMS + in-app only (push is deferred to Phase 1) |
| Payment | ZarinPal only |
| URLs | Channel `lumina.ir/@{username}`, post `lumina.ir/@{username}/posts/{post_id}`, finance `lumina.ir/dashboard/finance` |
---
## 3. Navigation and information architecture
### 3.1 Investor
- **Top bar:** notification bell with unread badge (99+). It opens a slide-in panel from the right on mobile.
- **Bottom nav:** خانه (feed + creator search) · داشبورد
- **داشبورد sub-sections:** اشتراک‌ها · تراکنش‌ها · دنبال‌شده‌ها
- **Reached from links:** creator channel, standalone post, checkout, track record page
- **Logged-out visitors** can browse channels and free posts via shared links. Every gated action leads to one CTA, **ورود/ثبت‌نام**, and the user returns to the same page after auth.
### 3.2 Creator
- **Top bar:** avatar opens **اطلاعات کاربری** (profile edit + verification status, C3). The notification bell is assumed to be shared with investors.
- **Bottom nav:** داشبورد · کانال, plus a center **FAB `+ انتشار`** that opens a mini menu with **پست جدید** and **پیشبینی جدید**.
- **داشبورد contents:** overview stats (C9, not yet specced) · **قیمت‌گذاری اشتراک** (C7) · **مالی** (C19 + C20).
- **First-run onboarding** (C1 then C2) is mandatory and can't be exited. There is no back button, and the Android back gesture is suppressed.
### 3.3 Admin (desktop)
- **Sidebar:** احراز هویت کریتورها (with a red pending-count badge) · مدیریت کریتورها · then the other sections from PRD Epic 3/11 (not yet specced).
---
## 4. Design system ("Stripe-inspired")
> Only the tokens referenced in the stories are listed here. **If you have the full design-system file, attach it.** It fills in the values marked "?".
### 4.1 Tokens
| Token | Value | Used for |
|---|---|---|
| `colors.primary` | `#533afd` | Primary CTA, verified, active, success, selected |
| `colors.primary-deep` | ? | Text on soft tags |
| `colors.primary-bg-subdued-hover` | `#b9b9f9` | Soft tag background, unread notification border |
| `colors.brand-dark-900` | `#1c1e54` | **پریمیوم** badge, primary financial figure |
| `colors.ink` | ? | Body text |
| `colors.ink-mute` | `#64748d` | Secondary text, pending, neutral and expired badges, icons |
| `colors.canvas` | `#ffffff` | Cards, sheets |
| `colors.canvas-soft` | `#f6f9fc` | Page backgrounds, locked placeholders, highlighted blocks |
| `colors.hairline` / `hairline-input` | ? | Borders, dividers, input borders |
| `colors.ruby` | `#ea2261` | Errors, critical/urgent, destructive, rejected, suspended, negative balance, **and the تخفیف badge** (its only affirmative use) |
| `colors.warning` | `#f59e0b` | Time-sensitive warnings, pending payment, non-blocking cautions, preview-mode banner |
| Typography | `heading-md`, `heading-sm`, `body-md`, `caption`, `micro` | Font **Yekan Bakh** for all Farsi |
| Radius | `rounded.md`, `rounded.lg`, `rounded.xl`, pill | |
| Shadow | Level 1 (cards), Level 2 (menus, popovers, sheets) | |
### 4.2 Components
`button-primary-pill` · `button-secondary` (outline, primary text; **ruby variant** for destructive admin actions) · `pill-tag-soft` · `card-feature-light` (canvas, hairline border, rounded.lg, Level 1) · `text-input` (focus border = primary) · `link-on-light` · snackbar/toast · modal · bottom sheet (mobile) / popover or side panel (desktop) · full-screen image lightbox (black background, swipe, pinch-zoom, `۱ / ۳` counter) · status badge · countdown.
### 4.3 Global rules
- **Tabular figures** (`font-feature-settings: "tnum"`) on every number: prices, dates, OTP, stats, reference numbers, countdowns. This is non-negotiable and part of the brand's financial look.
- **Frozen controls** stay visible at `opacity: 0.4` with `cursor: not-allowed`, and show an explanatory tooltip or message on tap. Controls are never hidden just because they're unavailable.
- **Dimmed or unavailable items** (for example a suspended creator) use `opacity: 0.5` with a lock icon. Any action that still works inside the item renders at full opacity.
- **Touch targets** are at least 44×44px.
- **Desktop column widths:** forms 560px · content and post pages 640px · checkout 480px.
- **Data safety:** on any network failure the entered data is kept. Errors appear inline under fields, and an error banner appears at the top for submit failures.
### 4.4 Numbers and RTL
- Signed amounts are wrapped in an LTR isolate, so the minus sign stays left of the digits: `−۱۲۰٬۰۰۰ تومان`. The word تومان sits outside the isolate.
- شبا renders LTR in groups of four: `IR62 0120 0000 0010 1234 5678 90`.
---
## 5. Cross-cutting patterns
### 5.1 Viewer states (channel, post page, feed)
| Viewer | Content | Follow | Subscribe |
|---|---|---|---|
| Logged-out | Free posts in full, premium as locked teasers | Shown; leads to auth | Shown; leads to auth |
| Logged in, not following | Same | دنبال کردن | اشتراک |
| Following, not subscribed | Same | دنبال نکردن | اشتراک |
| Waitlisted | Same | As applicable | **اشتراک stays live**, with a quiet note underneath and a لغو اطلاع‌رسانی link |
| Payment pending | Same | As applicable | Frozen indicator «پرداخت در حال بررسی» with a clock icon |
| Active subscriber | Everything unlocked, پریمیوم badge still shown | **Frozen** (can't unfollow while subscribed) | Replaced by the indicator «مشترک هستید ✓» |
| Creator (own channel) | Everything, plus share/edit/delete | Hidden | Hidden |
| Creator in "view as visitor" preview | Locked teaser, with an amber banner and «خروج از پیش‌نمایش» | n/a | n/a |
### 5.2 Locked premium post (one shared component everywhere: channel, post page, feed)
- The header row (avatar, username, timestamp, **پریمیوم** badge) is always visible.
- **Text:** only the first 2 lines are shown, fading into the canvas color with a centered lock icon. Two lines is a hard limit, so no analysis leaks.
- **Images:** never shown and never blurred. A generic lock placeholder on canvas-soft replaces them, with an optional «۳ تصویر» count badge.
- **Premium prediction:** asset, direction, entry, targets, stop loss and horizon are all hidden. Only the card frame, the پریمیوم badge and the status remain.
- **Data note:** the API sends `captionPreview` (first 140 characters) and `mediaPreview` with a `blurHash`. **Clamp the preview visually to 2 lines and never render the blurHash.** The rule against blurred images comes first.
- Below the locked content: one message and one CTA, depending on auth state. Logged-out users see «ورود/ثبت‌نام». Logged-in users see «اشتراک در کانال». The two are never shown together.
- There is no "you used to have access" variant after a subscription lapses.
### 5.3 Creator verification gating
- **States:** در انتظار احراز هویت (ink-mute, clock icon) · تأییدشده ✓ (primary, check icon) · رد شده (ruby, warning icon). Suspended is a separate admin state that can coexist with these.
- **For a creator who isn't yet Verified:**
- A persistent, non-dismissible banner sits on the کانال tab. It's informational when Pending. When Rejected, it shows the reason and is tappable to C3.
- A compact badge shows on داشبورد.
- The FAB and the channel share icon are frozen.
- Pricing and profile can still be edited.
- Payout details (شبا) are locked.
- **Identity fields** lock at first submission and reopen only on rejection. The username can never be changed. The national ID card image field is always empty when the form opens.
### 5.4 Time-based states
- **Post edit window:** 15 minutes after publishing. After that the edit icon is frozen and shows a tooltip. Edited posts show a «ویرایش‌شده» label in micro type. Posts can be deleted at any time; predictions can't (per the PRD).
- **Subscription remaining time:**
| Remaining | Label | Color | Warning under card |
|---|---|---|---|
| More than 7 days | {n} روز مانده | ink-mute | — |
| 4–7 days | {n} روز مانده | warning | — |
| 3 days or less | کمتر از {n} روز مانده | ruby | Yes |
- **Promotion countdown:** a plain date when more than 48 hours remain, a live «{n} ساعت باقی مانده» in warning color at 48 hours or less, and nothing at all for an indefinite promotion. There is no fake urgency.
- **OTP:** a 2-minute countdown that turns ruby in the last 30 seconds. Resend is available only after expiry. After 3 failed attempts the user is blocked for 10 minutes.
### 5.5 Status vocabulary
| Domain | States (Farsi label · color) |
|---|---|
| Subscription | فعال · primary — منقضی‌شده · ink-mute (neutral, not an error) — suspended creator: card dimmed + «درخواست بازگشت وجه» action — refund requested: «درخواست بازگشت وجه در حال بررسی» |
| Transaction | موفق · primary — ناموفق · ruby (ruby start border on row) — در حال بررسی · warning (warning start border, pinned to top) |
| Transaction type | اشتراک جدید · تمدید اشتراک · فعال‌سازی مجدد |
| Tier | ماهانه · سه‌ماهه · شش‌ماهه · سالانه |
| Payout | در حال انجام · ink-mute pill — انجام شده · no pill — لغو شده · ruby pill + struck-through amount |
| Ledger entry | درآمد اشتراک (+) · واریز به حساب (−) · کسر بازگشت وجه (−) · اصلاحیه (±). Amounts in ink color; the sign carries the meaning |
| Creator account (admin) | Active · primary + check — Suspended · ruby + ban icon, row tinted `rgba(234,34,97,0.05)` |
### 5.6 Prediction card (no ClickUp story yet; fields from the back end, rules from the PRD)
**Fields as the API returns them:**
| Field | Shape | Display |
|---|---|---|
| `symbol` | free text, uppercased (`XAUUSD`, `BTCUSDT`, `TEDPIX`) | LTR, prominent |
| `market` | one of the market keys (§10.2) | soft tag with its Farsi label |
| `direction` | `long` / `short` | Labels خرید / فروش (Long / Short) with an arrow icon. Never rely on color alone |
| `entryPrice` | number | tabular |
| `targetPrices[]` | **1 or more** numbers | Design for 1–3 targets (T1, T2, T3) |
| `stopLoss` | number, optional | Show when present; hide the row when absent |
| `horizon` | free label, for example `2w`, `45d` | Shown as a label. Show time remaining only when `expiresAt` exists |
| `caption` | text | Acts as the creator's note / rationale |
| `publishedAt` | system timestamp | **Prominent**; it is the trust signal |
| `status` | `open` / `closed` | |
| `outcome` | `win` / `loss` / **`breakeven`** | Three closed states |
| `closedPrice`, `closedAt` | on close | Show with the outcome |
| ROI | computed: (closed − entry) / entry, reversed for short | Signed percent, LTR-isolated |
- **States to design:** open · closed-win · closed-loss · closed-breakeven · premium-locked (§5.2) · owner view (with a «بستن پیشبینی» action that asks for the closing price, since closing is currently done by the creator).
- **Immutability:** prediction fields can't be edited after publishing. Show a lock cue and the timestamp. The PRD's 15-minute window and edit history don't exist yet (§9).
- **Variants:** compact (feed, channel) and expanded (post page). It also appears on the track record page, the creator dashboard and admin screens.
- **No market snapshot image for now:** a prediction post can't carry media in the API.
**Creator stats block** (U6, channel header):
- **Metrics:** نرخ موفقیت (`winRate`, already a percent such as `62.86` → `۶۲٫۹٪`) · کل پیشبینی‌ها · پیشبینی‌های فعال · بازدهی (`avgRoiPercent`) · روند دقت · and a CTA «مشاهده کارنامه کامل».
- **روند دقت is the last 10 outcomes** (`["win","loss","win",…]`). Design it as a row of 10 small outcome markers (win / loss / breakeven), not a line chart. A wins / losses / breakeven split is also available.
- **When the block shows:** the U6 rule is all or nothing. It's absent until the activation threshold is met or when the creator hides it. No zeros, no placeholder.
---
## 6. Screen inventory
Status key: ✅ fully specced in ClickUp · 📄 PRD only (design at lower fidelity, expect changes).
### 6.1 Auth and onboarding
| # | Screen | Story | Key states |
|---|---|---|---|
| 1 | ورود یا ثبت‌نام (mobile number) | U1, C1 | Invalid format · number belongs to the other role · network error |
| 2 | OTP | U1, C1 | Countdown · wrong code · expired · blocked 10 min (full screen) · resend |
| 3 | Investor تکمیل پروفایل (first and last name in Persian, username) | U1 | Live username check (available ✓, taken, invalid) · immutability note · step indicator without a total count |
| 4 | Login success modal / suspended-account screen | U1, A2 | |
| 5 | Creator KYC form (username, first and last name, national ID, ID card image) | C1 | Field validation · upload errors · no exit |
| 6 | Creator تکمیل پروفایل (bio, avatar crop, links, market tags, T&C) | C2 | Toast on load · 8-link limit (frozen add button) · drag reorder · quick-add (Telegram, Instagram, X, YouTube) · success screen «پروفایل ذخیره شد» |
| 7 | اطلاعات کاربری (creator profile edit) | C3 | Verified/Pending (identity locked) · Rejected (banner + editable identity + «ارسال مجدد اطلاعات هویتی») · two independent save actions · unsaved-changes dialog |
### 6.2 Investor
| # | Screen | Story | Key states |
|---|---|---|---|
| 8 | **Creator channel** `/@username` (header + post list) | U6, C4 §12, U8 | All viewer states (§5.1) · stats present or absent · empty channel · suspended channel |
| 9 | **Standalone post page** | C4b | Free · locked · subscriber · owner · visitor preview · deleted (404) · channel suspended · desktop share popover / mobile native share |
| 10 | خانه feed + creator search | 📄 Epic 7, U7 | Empty state «follow someone» + CTA · locked cards inline in chronological order |
| 11 | **Checkout** «خرید اشتراک» (one screen) | U9 | Tier cards with total, per-month and strike-through · promotion badge and countdown · referral code (valid ✓ / invalid) · frozen CTA · no code · price-changed modal · waitlist offer modal · already-waitlisted modal · pay CTA pinned to the bottom · link to «شرایط اشتراک» |
| 12 | Payment return | U10 | Non-dismissible «در حال تأیید پرداخت...» · success toast on the channel · pending · failure (back to checkout with selections kept) |
| 13 | شرایط اشتراک (terms page) | U9 comment | Static long-form text |
| 14 | داشبورد → اشتراک‌ها | U2, U3, A2 | Summary line «{n} اشتراک فعال» · active cards sorted by soonest expiry · expiry escalation · expired section · suspended-creator card with refund action · empty state |
| 15 | Renew / reactivate bottom sheet | U3 | Tier selector · date preview block (renew: from current expiry; reactivate: from today) · price-changed note · promotion · success checkmark animation · failure |
| 16 | داشبورد → تراکنش‌ها + detail sheet | U4 | Filter chips (همه · موفق · ناموفق · در حال بررسی) · pending rows pinned · tap-to-copy reference number · support CTA · pagination of 20 |
| 17 | داشبورد → دنبال‌شده‌ها | U8 | Unfollow with confirmation · frozen unfollow for subscribed creators · suspended row · empty state |
| 18 | Notification center | U5 | Unread (start border) / read · CTA chips · relative timestamps · empty state |
| 19 | Track record page | 📄 Epic 10 | Public · not yet available · hidden |
| 20 | Refund request + status | 📄 U21 (only the suspension case is specced, in A2 §6) | |
### 6.3 Creator
| # | Screen | Story | Key states |
|---|---|---|---|
| 21 | کانال tab (own channel) | C4, C5 | Verification banner · post cards with share/edit/delete (+ preview icon on premium posts) · empty state |
| 22 | FAB + mini menu | C4 | Frozen when not Verified, with a blocking message per state |
| 23 | Post composer (full-screen modal) | C4, C5 | Free/premium toggle · 2,000-character counter · up to 4 images (thumbnail strip, frozen add button) · empty error · discard dialog · publishing state · failed image |
| 24 | Prediction composer | 📄 C12–C15 | Structured form · free/premium · preview · warning that it locks after 15 min |
| 25 | Share channel | C6 | Mobile bottom sheet / desktop popover · editable caption (150 characters, default «من را در لومینا دنبال کن 👇») · copy link |
| 26 | داشبورد overview | 📄 C9–C11, C16 | Subscribers · revenue (label gross or net) · prediction summary · open predictions · compact verification badge |
| 27 | **قیمت‌گذاری اشتراک** | C7 | 4 tier cards (monthly always on) · per-month equivalent · floors · suggestions · validation that per-month cost can't increase with duration · promotion section per tier · cooldown lock (standing prices dimmed, promotions still live) · confirmation dialog |
| 28 | **مالی** — schedule notice · balance · next payout · شبا · ledger | C19, C20 | See §7 |
### 6.4 Admin (desktop-first)
| # | Screen | Story |
|---|---|---|
| 29 | Verification queue (tabs: در انتظار بررسی · تأییدشده · رد شده, search, sort, pagination of 20) | A1 |
| 30 | Verification detail (ID image lightbox and download, previous/next request, submission history, audit log, approve, reject with reason templates) | A1 |
| 31 | Creator management list and detail (suspend dialog showing subscriber impact, reinstate dialog showing extension summary, audit log) | A2 |
| 32 | Users · subscriptions · transactions · reconciliation · refunds · payout run (amount + receipt upload) · predictions moderation · feature flags | 📄 Epic 3/11 |
---
## 7. Creator finance model (from C19/C20, which replace the PRD's Epic 11 numbers)
- **Payouts are weekly on Thursday** (`{payout_day}` is configurable). A static notice explains bank cycles and holidays.
- **There is no minimum payout threshold, and income is available immediately** on payment confirmation. There is no 7-day pending state.
- **Balance summary:**
- **قابل واریز** is the primary figure in brand-dark-900.
- **مجموع واریزشده** is a secondary line.
- **در حال واریز** appears only while a transfer is in flight.
- A negative balance shows in ruby with an explanation underneath.
- **Next payout line** has several states: date · «register شبا first» · «nothing to pay» · suspended/frozen.
- **شبا:**
- The field is LTR with a fixed `IR` prefix, auto-grouped into fours, and normalizes Persian/Arabic digits.
- The bank name is detected and shown underneath.
- It's checked with a mod-97 checksum.
- A responsibility checkbox is mandatory.
- A read-back confirmation dialog appears before saving.
- A duplicate شبا shows an amber warning; it doesn't block.
- **No admin approval.** Every edit sends an SMS alert.
- Saved state shows the شبا, bank and last-updated date, with an edit action.
- **Ledger «گردش حساب»:**
- Tabs همه · واریزها, 20 rows plus «نمایش بیشتر».
- Two-line rows.
- A detail view opens as a bottom sheet on mobile and a side panel on desktop. Income detail shows price → discount → amount paid → commission → «سهم شما». Payout detail shows a masked شبا and the receipt (view/download).
- **Subscriber privacy:** creators only ever see `@username`. Phone numbers and real names are never shown.
---
## 8. Sample data (for realistic mockups)
Keys follow the real API (§10). Raw dates are ISO UTC and money is Toman where shown. Display everything per §2 (Shamsi, Persian digits, `٬`).
```json
{
"creator": {
"username": "ali_gold",
"displayName": "تحلیل‌گر طلا",
"bio": "تحلیل تکنیکال طلا و دلار، ۸ سال سابقه",
"markets": ["gold", "forex", "crypto"],
"socialLinks": [{ "label": "کانال تلگرام", "url": "https://t.me/ali_gold" }, { "label": "اینستاگرام", "url": "https://instagram.com/ali_gold" }],
"stats": { "totalPredictions": 42, "activePredictions": 7, "pastPredictions": 35, "wins": 22, "losses": 12, "breakeven": 1,
"winRate": 62.86, "avgRoiPercent": 8.7,
"accuracyTrend": ["win", "loss", "win", "win", "breakeven", "win", "loss", "win", "win", "win"] },
"tiers": [
{ "billingPeriod": "monthly", "priceToman": 490000, "perMonthToman": 490000 },
{ "billingPeriod": "quarterly", "priceToman": 1161000, "standingPriceToman": 1290000, "perMonthToman": 387000,
"promotion": { "percent": 10, "endsAt": "2026-10-12T20:30:00Z" } },
{ "billingPeriod": "semi_annual", "priceToman": 2352000, "perMonthToman": 392000 },
{ "billingPeriod": "yearly", "priceToman": 4116000, "perMonthToman": 343000 }
]
},
"posts": [
{ "type": "text", "accessLevel": "free", "publishedAt": "2026-10-01T11:00:00Z", "caption": "دلار در محدوده حمایتی؛ منتظر تأیید باشید." },
{ "type": "image", "accessLevel": "premium", "locked": true, "captionPreview": "تحلیل هفتگی انس جهانی و دلار آزاد؛ سطوح کلیدی…", "mediaCount": 3 },
{ "type": "prediction", "accessLevel": "free", "caption": "شکست مقاومت ۲۴۰۰ دلار",
"prediction": { "symbol": "XAUUSD", "market": "gold", "direction": "long", "entryPrice": 2310, "targetPrices": [2400, 2450],
"stopLoss": 2280, "horizon": "2w", "status": "closed", "outcome": "win", "closedPrice": 2402 } },
{ "type": "prediction", "accessLevel": "free",
"prediction": { "symbol": "BTCUSDT", "market": "crypto", "direction": "short", "entryPrice": 68000, "targetPrices": [61000],
"horizon": "45d", "status": "open" } },
{ "type": "prediction", "accessLevel": "premium", "locked": true, "prediction": { "status": "open" } }
],
"investorSubscriptions": [
{ "creator": "ali_gold", "tier": "quarterly", "status": "active", "daysRemaining": 2 },
{ "creator": "gold_signal", "tier": "monthly", "status": "active", "daysRemaining": 5 },
{ "creator": "crypto_mina", "tier": "monthly", "status": "active", "creatorSuspended": true },
{ "creator": "bourse_pro", "tier": "yearly", "status": "expired", "expiryDate": "2026-09-21T08:00:00Z" }
],
"transactions": [
{ "type": "subscribe", "tier": "quarterly", "toman": 1161000, "status": "pending", "reference": "201234567" },
{ "type": "renew", "tier": "monthly", "toman": 490000, "status": "successful", "reference": "201230011" },
{ "type": "subscribe", "tier": "yearly", "toman": 4116000, "status": "failed", "reference": null }
],
"creatorFinance (C20 target shape; no API yet)": {
"available": 3420000, "inTransfer": 1250000, "totalPaidOut": 14300000,
"nextPayout": "پنجشنبه ۱۶ مهر ۱۴۰۵",
"sheba": "IR620120000000101234567890", "bank": "بانک ملت",
"ledger": [
{ "type": "income", "amount": 203150, "subscriber": "@reza_inv", "tier": "quarterly", "date": "2026-09-27" },
{ "type": "payout", "amount": -1250000, "status": "in_progress", "date": "2026-10-01" },
{ "type": "refund_deduction", "amount": -600000, "date": "2026-09-30" },
{ "type": "payout", "amount": -900000, "status": "cancelled", "date": "2026-09-19" }
]
}
}
```
---
## 9. Decisions and open points
**Story decisions that override the PRD**
- Subscriptions are **invite-only**. A referral code from the creator is required, and capacity is limited. When capacity is full, users with a valid code can join a waitlist (a notification subscription with opt-out). Following stays free.
- Creator payouts are weekly, with no threshold, no clearing period and no شبا approval (see §7).
- There is no public follower count anywhere.
- Prediction stats show in full or not at all.
- Pricing uses 4 fixed tiers with per-month floors (ماهانه ۲۹۹٬۰۰۰ · سه‌ماهه ۲۶۵٬۰۰۰ · شش‌ماهه ۲۳۰٬۰۰۰ · سالانه ۱۹۹٬۰۰۰ per month), promotions, and a 7-day cooldown.
- Suspension is a full blackout. Subscribers choose between a pro-rated refund and extension by the paused time.
**Inconsistencies to resolve (design with the first option until told otherwise)**
1. **Brand name:** «لومینا / lumina.ir» appears in C4, C6, C19 and C20, while other stories use the placeholder `[نام پلتفرم]`. Use **Lumina**.
2. **Pending label:** C1 uses «در انتظار تأیید», while C3 and the PRD use «در انتظار احراز هویت». Use the latter.
3. **Thousands separator:** C7 examples use `,`, while C20 specifies `٬`. Use `٬`.
4. **Push notifications:** C20 §8.1 mentions push, but push is deferred to Phase 1. Design for SMS + in-app.
5. **Prediction outcome:** the back end has `win` / `loss` / `breakeven`, closed by the creator. Design those three states.
**Story vs back-end conflicts (design to the story; the team must decide)**
| # | Topic | Story | Back end today |
|---|---|---|---|
| 6 | OTP | 5 digits, 2-minute expiry | 6 digits, 10-minute expiry, 60 s resend cooldown |
| 7 | National ID images | Front only | Front **and back** required |
| 8 | Public name | `@username` only (no nickname in C2) | Also a required `displayName` (max 80) |
| 9 | Post edit window | 15 minutes, then frozen; «ویرایش‌شده» label | Caption/media/access editable forever; no edited flag; predictions frozen at publish |
| 10 | Drafts | None (local draft only) | Server drafts, soft delete, purge |
| 11 | Locked prediction teaser | Everything hidden | Leaks `symbol` + `direction` |
| 12 | Locked image teaser | Never blurred | Sends `blurHash` |
| 13 | Follower count | Never public | Public endpoint exists |
| 14 | Promotions | Apply to new, renew and reactivate | New subscriptions only |
| 15 | Pending payment | Stays «در حال بررسی» until resolved | Auto-expires after 30 min and shows as **failed** |
| 16 | Creator profile field | — | Extra `tradingStyle` (not in stories, don't design it) |
| 17 | Brand | Lumina | `OnlyT` in SMS and config |
---
## 10. Back-end data model (design-relevant summary)
> The full analysis is in `backend-context.md` (for engineering). This section only keeps what changes how a screen looks or what content it shows.
### 10.1 Formats
- **Money:** stored in Rial, but every response has a Toman field (`toman`, `priceToman`, `perMonthToman`). The UI always shows Toman.
- **Dates:** ISO UTC. Server-made Farsi labels look like `۱۴۰۵/۳/۶` (no zero padding, no time). Designs use the §2 format; the front end formats dates itself.
- **Percentages:** `winRate` and `avgRoiPercent` are already percentages (`62.86`), not fractions.
- **Server copy:** many subscription, pricing, checkout and notification responses carry ready Farsi strings (`*Fa`) and color hints that match the tokens in §4.1. They agree with the story copy, so the round files stay the copy source.
### 10.2 Enums (exact keys)
| Enum | Keys |
|---|---|
| Market | `crypto` کریپتو · `gold` طلا و سکه · `equities` بورس · `forex` فارکس · `funds` صندوق‌های سرمایه‌گذاری · `real_estate` مسکن · `automotive` خودرو · `USDT` تتر |
| Billing period | `monthly` · `quarterly` · `semi_annual` · `yearly` |
| Post | type `text` / `image` / `prediction` · access `free` / `premium` |
| Prediction | status `open` / `closed` · outcome `win` / `loss` / `breakeven` · direction `long` / `short` |
| Subscription | `active` / `expired`. "Expiring" is computed: amber at 4–7 days, ruby with warning at ≤3 days |
| Payment (UI) | `successful` / `pending` / `failed` · type `subscribe` / `renew` / `reactivate` |
| Checkout CTA | `subscribe` · `active` (مشترک هستید ✓) · `pending_review` (frozen) · `own` (hidden) |
| Payment return | `processing` → `granted` (land on channel) / `pending_review` / `failed` (back to checkout) |
| Verification | `pending` / `approved` / `rejected` (+ account `suspended`) |
### 10.3 Limits that affect layouts
- Bio 300 characters, max 3 line breaks.
- Links: max 8, label max 30 characters.
- Display name max 80 characters (if used, §9 #8).
- Avatar and ID images: JPG/PNG, max 5 MB.
- Post text: the story limit of 2,000 applies (the API accepts 5,000). Max 4 images per post (the API has no limit).
- Pagination: 20 per page for feed, posts and transactions. Notifications: latest 100, no paging.
### 10.4 Back-end support by screen
Designs still follow the stories for every screen. This list only shows what can be built against real data now.
| Supported | Not implemented yet |
|---|---|
| Auth, investor registration, creator registration + profile setup/edit | Verification approve/reject, resubmit, rejection reason (creators stay `pending`) |
| Channel, posts, post page, follow/unfollow (frozen while subscribed, auto-follow on subscribe) | Creator search · track record gate/history/hide · prediction auto-tracking (manual close only) |
| Pricing (floors, suggestions, promotions, cooldown, validation) | Earnings ledger, شبا, payouts, receipts, commission (C19/C20) |
| Checkout with invite code, waitlist, price-change guard, ZarinPal return | Refunds · reconciliation · subscription cancel |
| اشتراک‌ها, renew/reactivate, تراکنش‌ها, notification center | Whole admin panel · audit log · feature flags |
| Creator dashboard: active subscribers, gross revenue, recent payments | Net revenue (only gross exists, so label it «درآمد ناخالص») |
---
## 11. Design rounds
| Round | File | Goal |
|---|---|---|
| 1 | `round-1-channel-and-posts.md` | **Visual language.** Channel header, post card (free / locked / subscriber / owner), standalone post page, composer, share, follow, prediction card (from §5.6) |
| 2 | `round-2-auth-and-onboarding.md` | Entry, OTP, investor profile, creator KYC, profile setup, اطلاعات کاربری |
| 3 | `round-3-investor-subscriptions.md` | Checkout, payment return, waitlist, اشتراک‌ها, renew/reactivate, تراکنش‌ها, notifications |
| 4 | `round-4-creator-money.md` | Pricing, مالی (شبا + ledger) |
| 5 | `round-5-admin.md` | Verification queue and detail, suspend/reinstate |
| 6 | (PRD only) | Feed + search, track record, creator dashboard overview, prediction composer, other admin screens |
**For each round:** mobile (390px) and desktop, RTL, real Farsi copy from the stories, and every listed state (loading, empty, error, success, frozen, edge).