wealth/docs/round-4-creator-money.md

544 lines
47 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 4 — Creator pricing & finance
> 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.
> Keep amounts in ink color; the sign carries meaning. Ruby only for negative balance and cancelled payouts.
## Deliver in this round
- قیمت‌گذاری اشتراک: first-time setup with suggestions, edit mode, validation errors, promotion section, cooldown-locked state, confirmation dialog
- مالی: schedule notice, balance summary (normal, in-transfer, negative, suspended), next-payout line states
- شبا: empty state, form with live grouping and bank name, errors, duplicate warning, read-back dialog, saved state
- گردش حساب ledger (همه / واریزها) and detail views for each entry type and payout status, receipt viewer, empty and error states
For every screen: mobile and desktop, RTL, real Farsi copy from below, and all listed states.
## Stories included
- **C7** — Creator: Subscription Pricing & Tier Configuration _(ClickUp status: ready for development)_
- **C19** — Payout Details _(ClickUp status: in design)_
- **C20** — Earnings & Payouts _(ClickUp status: in design)_
---
## C7 — Creator: Subscription Pricing & Tier Configuration
C7 — Creator: Subscription Pricing & Tier Configuration
Story:
As a creator, I want to set my own subscription price and available billing periods so that I have full control over my monetization model.
Scope note: This story owns everything the creator configures about subscription pricing — tier availability, standing prices, promotional discounts, and validation. The investor-facing checkout flow is owned by U9; renewal and reactivation pricing behaviour is owned by U3; revenue reporting is owned by C9.
⚠️ Forward dependency note: Subscription purchase requires ZarinPal integration (U9) and referral-code gating (Epic 5). A creator can fully configure pricing while Pending Verification, but no subscription can be purchased until they are Verified.
Acceptance Criteria:
1. Access & Entry Point
Happy Path:
Pricing configuration is accessed from the creator's داشبورد tab
Available to creators in Pending Verification and Verified states — a Pending creator can configure pricing while awaiting admin review, consistent with how C2/C3 allow profile completion while Pending
Configuration is a single scrolling form covering all tiers
Edge Cases:
A Pending creator can save pricing, but their channel cannot be subscribed to until Verified — an informational note explains this
A Rejected creator can still view and edit pricing — the block is on monetization, not configuration
A Suspended creator cannot access the app at all (A2), so this screen is unreachable in that state
Farsi copy:
Screen heading: قیمت‌گذاری اشتراک
Pending verification note: پس از تأیید احراز هویت، کاربران می‌توانند در کانال شما مشترک شوند.
2. Tier Availability
Happy Path:
Four fixed tiers: ماهانه (1 month), سه‌ماهه (3 months), شش‌ماهه (6 months), سالانه (12 months)
ماهانه is mandatory and always enabled — it cannot be toggled off. It is the baseline every creator must offer and the reference point all other tiers are validated against
The three longer tiers are individually toggleable and default to ON — combined with pre-filled suggestions (Section 4), a creator entering a single monthly price arrives at a complete, valid four-tier structure with no further input. Longer tiers create commitment and retention for both sides, so the default favours offering them
A creator may toggle any longer tier off; offering only ماهانه is a complete, valid configuration
Enabling a tier reveals its price field; disabling hides it and removes it from investor-facing checkout
Edge Cases:
Disabling a tier with active subscribers does not affect them — existing subscriptions run to natural expiry at the price paid. The tier simply stops being offered to new subscribers; a note informs the creator
Custom durations (e.g. 4 or 8 months) are not supported in Phase 0 — fixed tiers only
Phase 1 candidate: custom tier durations. Deliberately deferred — every surface displaying a tier label (U2 cards, U3 date previews, U4 transaction history, C9 dashboard) currently assumes four known labels, and no founding creator has yet indicated the fixed tiers are insufficient. Add to founding-creator interview questions to gather evidence before building.
Farsi copy:
Tier labels: ماهانه · سه‌ماهه · شش‌ماهه · سالانه
Monthly mandatory note: اشتراک ماهانه همیشه فعال است و قابل غیرفعال‌سازی نیست.
Disabling with active subscribers note: {n} مشترک فعال روی این دوره دارید. با غیرفعال کردن، اشتراک آن‌ها تا پایان دوره ادامه می‌یابد و فقط این دوره برای کاربران جدید نمایش داده نمی‌شود.
3. Standing Prices — Entry & Floors
Happy Path:
The creator enters a total price for each enabled tier (not a percentage, not a per-month figure) — the full amount an investor pays for that duration
Beneath each field, the system displays the computed per-month equivalent — how the creator sanity-checks their structure
Each tier has a minimum per-month standing price, declining with duration so long-tier discounting remains possible:
Tier Minimum standing price (per month)
ماهانه ۲۹۹,۰۰۰ تومان
سه‌ماهه ۲۶۵,۰۰۰ تومان
شش‌ماهه ۲۳۰,۰۰۰ تومان
سالانه ۱۹۹,۰۰۰ تومان
Floors are hardcoded in Phase 0; admin configurability is a Phase 1 item
There is no maximum price — premium positioning for a smaller, higher-value audience is a legitimate strategy the platform does not constrain
Edge Cases:
Prices entered in تومان, whole numbers only — no decimals
Per-month equivalent displayed rounded to the nearest تومان; the stored total price is exact
Typo protection comes from the confirmation dialog (Section 7), not from a price ceiling
Error States:
Price below the tier's floor → inline error naming that tier's specific minimum
Empty price on an enabled tier → inline error; the tier cannot be saved without a price
Non-numeric input → rejected at the input layer
Farsi copy:
Price field label: قیمت کل دوره
Per-month equivalent display: معادل {amount} تومان در ماه
Floor helper text (beneath each tier's field): حداقل قیمت این دوره {amount} تومان در ماه است.
Below-floor error: قیمت این دوره نمی‌تواند کمتر از {amount} تومان در ماه باشد.
Empty price error: وارد کردن قیمت برای دوره‌های فعال الزامی است.
4. Price Suggestions
Happy Path:
When the creator enters their monthly price, the system computes suggested prices for the three longer tiers using platform-standard discounts:
Tier Suggested discount off monthly × duration
سه‌ماهه 10%
شش‌ماهه 20%
سالانه 30%
Suggested prices are rounded down to the nearest ۱,۰۰۰ تومان, consistent with promotional rounding (Section 6)
First-time setup (no tier prices saved yet): suggestions are pre-filled directly into the price fields — fastest path for the common case, fully editable
Subsequent edits (tier prices already exist): suggestions appear as hint text beneath the field only — existing values are never overwritten, since a creator who deliberately set a price should not have it silently replaced
Worked example at ۴۰۰,۰۰۰ monthly:
Tier Full (monthly × duration) Suggested Per month
سه‌ماهه ۱,۲۰۰,۰۰۰ ۱,۰۸۰,۰۰۰ ۳۶۰,۰۰۰
شش‌ماهه ۲,۴۰۰,۰۰۰ ۱,۹۲۰,۰۰۰ ۳۲۰,۰۰۰
سالانه ۴,۸۰۰,۰۰۰ ۳,۳۶۰,۰۰۰ ۲۸۰,۰۰۰
Edge Cases:
Because the tier floors decline faster than the suggested discounts deepen, a suggested price can never fall below its tier floor at any monthly price. At the lowest legal monthly price (۲۹۹,۰۰۰): سه‌ماهه ۲۶۹,۰۰۰/mo (floor ۲۶۵,۰۰۰), شش‌ماهه ۲۳۹,۰۰۰/mo (floor ۲۳۰,۰۰۰), سالانه ۲۰۹,۰۰۰/mo (floor ۱۹۹,۰۰۰). No clamping logic is required
Changing the monthly price later does not overwrite existing longer-tier prices — it only re-computes hint text, and flags any tier that now violates validation (Section 5)
Suggestions are guidance only — a creator may ignore them entirely, provided validation passes
Farsi copy:
Suggestion hint text: پیشنهاد: {amount} تومان
5. Validation — Per-Month Cost Must Not Increase With Duration
Happy Path:
Core rule: a longer tier's per-month cost must be less than or equal to that of every shorter enabled tier, guaranteeing longer commitment never costs more per month
Validation runs live as the creator types and again on save
Edge Cases:
Validation compares against enabled tiers only — disabled tiers are ignored
Equal per-month cost is permitted (a longer tier at no discount — unusual, not invalid)
If the creator raises their monthly price such that an existing longer tier now costs more per month, that tier is flagged immediately
Violating prices cannot be saved — save is blocked until every enabled tier passes. There is no "save anyway" override
Error States:
Per-month cost higher than a shorter tier → inline error naming the conflict explicitly
Multiple violations → all flagged simultaneously, not one at a time
Farsi copy:
Validation error: قیمت ماهانه این دوره ({amount} تومان) نباید بیشتر از دوره {shorter_tier} ({amount} تومان) باشد.
Blocked save message: برای ذخیره، ابتدا خطاهای قیمت‌گذاری را برطرف کنید.
6. Promotional Discounts
Promotions are a separate mechanic from standing prices. A standing price is the creator's permanent, normal price; a promotion is a temporary reduction off it.
Happy Path:
A promotion can be applied to any enabled tier, including ماهانه
The creator enters a percentage (whole numbers, 1–99) — percentages are how discounts are conventionally communicated, and the تخفیف badge reads naturally from them
Each promotion has a start date and time and an end date and time (Shamsi calendar). The end may be set to indefinite — the promotion runs until the creator ends it
The system computes the effective price and rounds down to the nearest ۱,۰۰۰ تومان — rounding down ensures the investor always receives at least the advertised discount, never slightly less
Promotions are per-tier and independent — a creator may run 30% off سالانه while offering nothing on ماهانه; multiple tiers may run promotions simultaneously
Both the total promotional price and its per-month equivalent are displayed to the creator alongside the standing price and its per-month equivalent, so the full before/after comparison is visible while deciding
Promotion controls are always available, including during the standing-price cooldown (Section 8) — the cooldown governs permanent pricing only, never temporary offers
Worked example: standing price ۲۹۹,۰۰۰ with 30% off = ۲۰۹,۳۰۰ → displayed as ۲۰۹,۰۰۰
Promotional floor:
The effective promotional price may not fall below ۹۹,۰۰۰ تومان per month — a single flat floor across all tiers, regardless of duration
Deliberately far below the standing-price floors, allowing genuinely aggressive acquisition pricing while preventing fee-negative transactions
Scope of application — all purchase moments:
Purchase type Promotion applies?
New subscription ✅ Yes
Reactivation (expired subscription, buying again) ✅ Yes
Renewal (active subscription, extending early) ✅ Yes
A promotion applies at every moment an investor pays, with no exceptions
Rationale: a lapsed subscriber is someone the creator is re-acquiring — precisely who a win-back promotion targets. And for early renewal, a discount is the only thing that makes renewing early rational: the extension runs from the current expiry date either way (U3 Section 3), so without a promotion the investor gains nothing by paying sooner. Early renewal is a retention win — revenue arrives earlier, and the subscriber removes themselves from churn risk at the expiry moment
What a promotion never does: retroactively alter an already-purchased subscription. Someone who paid ۴۰۰,۰۰۰ last week receives no partial refund when a 30% promotion launches today — they receive the promotional price only if they choose to renew or reactivate during the promotional window
Ending a promotion:
A creator ends a promotion by toggling it off or deleting it, then saving — the change takes effect on save, not on toggle
Ending early affects only purchases made after that moment
Edge Cases:
The 7-day pricing cooldown (Section 8) does not apply to promotions — promos are inherently temporary and explicitly marked as such to investors; a Nowruz promo followed by an Eid promo two weeks later is normal behaviour, not thrash. A creator locked out of their main acquisition lever because they adjusted a standing price five days earlier would be a genuine handicap
A promotion ending mid-subscription has no effect on that subscriber — they paid the promotional price for a full term and keep it. At renewal they see whatever pricing is current at that moment
Promotions may be scheduled with a future start date and time
One active promotion per tier in Phase 0 — multiple scheduled promotions with different date ranges on the same tier is deferred to a later phase
No validation on discount depth beyond the floor — any percentage is permitted subject to the ۹۹,۰۰۰ minimum, with confirmation on save (Section 7)
Error States:
Effective price below ۹۹,۰۰۰/month → inline error showing the computed price and the floor
End date/time before or equal to start date/time → inline error
Percentage outside 1–99 → inline error
Farsi copy:
Section label: تخفیف دوره‌ای
Percentage field label: درصد تخفیف
Start/end labels: تاریخ و ساعت شروع / تاریخ و ساعت پایان
Indefinite end option: بدون تاریخ پایان
Computed price display: قیمت با تخفیف: {amount} تومان (معادل {amount} تومان در ماه)
Promotional floor error: قیمت با تخفیف ({amount} تومان در ماه) نمی‌تواند کمتر از ۹۹,۰۰۰ تومان در ماه باشد.
Invalid date range error: تاریخ و ساعت پایان باید بعد از شروع باشد.
Invalid percentage error: درصد تخفیف باید بین ۱ تا ۹۹ باشد.
Scope note: تخفیف برای خرید جدید، تمدید و خرید مجدد اعمال می‌شود، اما روی اشتراک‌های خریداری‌شده قبلی تأثیری ندارد.
7. Save & Confirmation Dialog
Happy Path:
On tapping save, a confirmation dialog summarises the full pricing structure before anything is committed
Every enabled tier is listed with its total price and per-month equivalent. Where a promotion is active, the dialog additionally shows the promotional price in both total and per-month terms, alongside the discount percentage and end date — the complete before/after picture in one view
The dialog also carries the cooldown warning and the safety-valve explanation (Section 8), so the creator understands the consequences of committing at the moment of committing
Confirming saves; cancelling returns to the form with all values intact
Example dialog content:
تأیید قیمت‌گذاری
ماهانه ۴۰۰,۰۰۰ تومان (۴۰۰,۰۰۰ در ماه)
سه‌ماهه ۱,۰۸۰,۰۰۰ تومان (۳۶۰,۰۰۰ در ماه)
سالانه ۳,۶۰۰,۰۰۰ تومان (۳۰۰,۰۰۰ در ماه)
تخفیف ۲۵٪ تا ۱۵ تیر ۱۴۰۴
معادل ۲,۷۰۰,۰۰۰ تومان (۲۲۵,۰۰۰ در ماه)
پس از اولین خرید با این قیمت‌ها، تا ۷ روز امکان تغییر قیمت وجود ندارد.
تا زمانی که خریدی انجام نشده، می‌توانید قیمت‌ها را آزادانه ویرایش کنید.
تنظیم تخفیف در هر زمان امکان‌پذیر است.
[تأیید و ذخیره] [انصراف]
Edge Cases:
The dialog appears on every save, not only the first — it is the platform's primary typo protection at any price level, replacing the need for a maximum price
If validation fails, the dialog does not appear — errors are surfaced inline first (Section 5)
Saving with no changes still shows the dialog; harmless, and keeps behaviour predictable
Error States:
Network failure on save: error banner, all entered values preserved, retry available
Farsi copy:
Dialog heading: تأیید قیمت‌گذاری
Per-month suffix: ({amount} در ماه)
Promotion lines: تخفیف {n}٪ تا {end_date} / معادل {amount} تومان ({amount} در ماه)
Indefinite promotion line: تخفیف {n}٪ (بدون تاریخ پایان)
Cooldown warning: پس از اولین خرید با این قیمت‌ها، تا ۷ روز امکان تغییر قیمت وجود ندارد.
Safety valve note: تا زمانی که خریدی انجام نشده، می‌توانید قیمت‌ها را آزادانه ویرایش کنید.
Promotion exemption note: تنظیم تخفیف در هر زمان امکان‌پذیر است.
Confirm CTA: تأیید و ذخیره
Cancel CTA: انصراف
Save success toast: قیمت‌گذاری با موفقیت ذخیره شد.
Network error banner: خطا در ذخیره‌سازی. اتصال اینترنت خود را بررسی کنید.
8. Changing Prices After Launch — Cooldown & Safety Valve
Happy Path:
A creator may change standing prices at any time, subject to a 7-day cooldown between changes
The cooldown does not begin at save — it begins at the first subscription purchased at the new price. Until someone actually buys, the creator can edit freely and as often as they like
Existing subscribers are unaffected by any price change — they keep the price they purchased at until expiry. At renewal they see the current standing price (or promotional price, if one is active), with U3's price-change note explaining any difference
The cooldown is per-creator, not per-tier — one change resets it for the entire standing-price configuration
Rationale for the safety valve: the scenario a cooldown must not punish is a creator saving a typo and discovering it minutes later. Tying the cooldown to first purchase rather than to save eliminates that entirely, without ever creating a subscriber who paid a price the creator immediately revoked. A fixed post-save edit window was considered and rejected: unlike editing a post (C4's 15-minute window), pricing is immediately purchasable, so a timed window would allow real money to change hands at a price still being edited.
Edge Cases:
The cooldown applies to standing prices and tier toggles only. Promotion controls — creating, editing, and ending — remain fully available at all times, including during cooldown (Section 6). The cooldown governs permanent pricing, never temporary offers
Toggling a tier on or off counts as a standing-price change and is subject to the same cooldown rules
During cooldown, only standing-price fields and tier toggles are read-only — the promotion section of each tier remains fully interactive
The cooldown notice is shown in two places: persistently on the form whenever it is locked (so the creator knows before typing, not after), and in the confirmation dialog at save time (so they know the clock is about to start). In both places the notice explicitly states that promotions remain editable, so a creator seeing a locked form doesn't assume promotions are locked too
Error States:
Attempting to edit standing prices during cooldown → those fields are not editable; notice shows when editing becomes available again
Phase 0 tuning note: 7 days is a starting value, not a fixed constraint. If founding creators report it as too restrictive during interviews, shortening it is a trivial configuration change — gather that evidence before adjusting.
Farsi copy:
Cooldown notice (on locked form): قیمت‌ها را هر ۷ روز یک‌بار می‌توانید تغییر دهید. امکان ویرایش بعدی: {date} — تنظیم تخفیف در هر زمان امکان‌پذیر است.
Pre-purchase editable note (on form, before first sale at current prices): هنوز خریدی با این قیمت‌ها انجام نشده — می‌توانید آزادانه ویرایش کنید.
Existing subscribers note (shown when editing prices): تغییر قیمت روی مشترکان فعلی تأثیری ندارد. قیمت جدید از زمان تمدید اشتراک آن‌ها اعمال می‌شود.
9. Investor-Facing Display (Reference)
How configured prices appear in checkout is owned by U9, but the display rules originate here:
When a longer tier's total is less than monthly × duration, checkout shows the higher figure struck through alongside the actual price — making the saving visible without the creator configuring anything
When a promotion is active, the strike-through shows the standing tier price (not the monthly-derived comparison), the live price shows the promotional price, and a تخفیف badge marks it. The monthly-derived comparison recedes in this state — one clear "before" figure, never two competing ones
Promotional time remaining is displayed as a plain date beyond 48 hours and switches to a live hourly countdown within 48 hours (U9 Section 3) — urgency appears only when it is real
Because promotions apply to renewals and reactivations as well as new subscriptions, these same display rules apply in U3's renewal and reactivation flows, not only in U9's first-purchase checkout
Disabled tiers do not appear in checkout at all
10. UI / UX
Layout is RTL throughout; Yekan Bakh is the typeface for all Farsi text, per the Stripi-inspired design system
All prices and per-month equivalents use font-feature-settings: "tnum" — non-negotiable per the design system's tabular-figures rule for monetary values
Each tier renders as a card-feature-light block containing its toggle, price field, per-month equivalent, floor helper text, and promotion controls
The mandatory ماهانه tier renders without a toggle — its permanence is visually evident, not an interaction the creator can attempt
Disabled tiers collapse to just their toggle row — price fields and promotion controls hidden, not merely greyed
Price input fields use text-input style with a تومان suffix; numeric keyboard on mobile
Per-month equivalent renders in {colors.ink-mute} (#64748d), {typography.caption} — supporting information, not the primary figure
Floor helper text renders in {colors.ink-mute}; on violation, the same line switches to {colors.ruby} (#ea2261) with the specific error
Suggestion hint text renders in {colors.ink-mute}, visually distinct from both entered values and error states
Promotion section within each tier sits on {colors.canvas-soft} (#f6f9fc) to distinguish it from standing-price configuration — and remains at full opacity during cooldown, while standing-price fields above it dim, making the distinction visually obvious
تخفیف badge uses {colors.ruby} (#ea2261) background with white text, pill-tag-soft style — the one place ruby is used affirmatively rather than as an error, since a discount badge is conventionally red in Iranian e-commerce
Save CTA uses button-primary-pill (#533afd); blocked state uses opacity: 0.4 with cursor: not-allowed
Cooldown read-only state renders standing-price fields and tier toggles at opacity: 0.5, with the cooldown notice prominently above the form
Confirmation dialog uses the standard modal pattern; confirm CTA button-primary-pill
Minimum touch target for all interactive elements: 44×44px
Form is mobile-first; desktop single column, max-width 560px
---
## C19 — Payout Details
C19 — Payout Details
Story: As a Creator, I want to register my bank payout details (شماره شبا), so that the platform can transfer the money I have earned.
Acceptance Criteria
Section 1 — Access & Entry Point
1.1 Payout details live under داشبورد → مالی. The section holds these blocks in order: the payout schedule notice, موجودی (C20), اطلاعات تسویه‌حساب (this story), تاریخچه واریز (C20).
Still a proposal until Epic 6 fixes the creator dashboard's sub-navigation.
1.2 Only the authenticated creator can see it, and only for their own account.
1.3 Gated on identity verification. While C1 verification is pending or rejected, the block shows locked:
پس از تأیید احراز هویت، می‌توانید اطلاعات تسویه‌حساب خود را ثبت کنید.
Section 2 — Payout Schedule Notice
2.1 A static notice sits at the top of the مالی section and is always visible:
واریز درآمد هر هفته، روزهای پنجشنبه انجام می‌شود. زمان نشستن مبلغ در حساب شما به چرخه‌های بانکی بستگی دارد. در صورت تعطیلی، واریز در اولین روز کاری بعد انجام خواهد شد.
2.2 The payout day is a config value ({payout_day}), not hard-coded copy, so changing the cadence doesn't need a release.
Section 3 — Empty State
3.1 With no شبا on file:
اطلاعات تسویه‌حساب
هنوز شماره شبای خود را ثبت نکرده‌اید. تا زمان ثبت آن، امکان واریز درآمد شما وجود ندارد.
3.2 CTA (button-primary-pill):
ثبت شماره شبا
3.3 If the creator has a balance above zero, a {colors.warning} note appears above the CTA:
درآمد شما در لومینا محفوظ است، اما تا ثبت شماره شبا قابل واریز نیست.
Section 4 — The Form
4.1 One field and one checkbox.
4.2 شماره شبا: text-input, dir="ltr", left-aligned, font-feature-settings: "tnum". IR is a fixed, non-editable prefix, and the 24 digits are grouped in fours as they're typed: IR## #### #### #### #### #### ##.
4.3 Helper text:
شماره شبای ۲۴ رقمی خود را وارد کنید. می‌توانید شبا را به‌صورت کامل کپی و اینجا جای‌گذاری کنید.
4.4 Normalization on type or paste, applied silently:
A leading IR / ir is stripped
Spaces, dashes and dots are stripped
Persian (۰–۹) and Arabic (٠–٩) digits are converted to Latin
4.5 Bank name, shown only once the bank code is present and recognised, in {colors.ink-mute} below the field:
بانک: بانک ملت
If the code isn't recognised, nothing is shown: no error, no placeholder.
4.6 Mandatory responsibility checkbox:
تأیید می‌کنم که این شماره شبا متعلق به من است. مسئولیت صحت آن، از جمله ثبت شبای متعلق به شخص یا نهاد دیگر، به‌طور کامل بر عهده من است و لومینا در قبال واریز به حساب اشتباه مسئولیتی ندارد.
4.7 Submit CTA, disabled until validation passes and the checkbox is ticked:
ثبت شماره شبا
Section 5 — Validation
5.1 Validation runs on blur and again on submit. Errors appear in {colors.ruby} below the field.
Condition Message
Empty شماره شبا را وارد کنید.
Not 24 digits after normalization شماره شبا باید ۲۴ رقم باشد.
Non-numeric characters شماره شبا فقط شامل عدد است.
Mod-97 checksum fails شماره شبای واردشده معتبر نیست. لطفاً آن را بررسی کنید.
Checkbox unticked برای ثبت، تأیید مسئولیت صحت اطلاعات الزامی است.
5.2 The checksum is the only real guard against typos. It catches every single-digit error and almost every transposition.
Section 6 — Duplicate شبا Warning
6.1 If the شبا already exists on another Lumina account, a {colors.warning} notice shows under the field. It's a warning, not a blocker:
این شماره شبا قبلاً در حساب کاربری دیگری در لومینا ثبت شده است. در صورت اطمینان از صحت آن، می‌توانید ادامه دهید.
6.2 The warning never says which account holds it.
6.3 Legitimate cases are an organisation running two channels, or a family sharing an account. That's why it doesn't block.
Token note: this uses {colors.warning} for a non-blocking caution rather than a time-sensitive one, which is wider than the scope we documented for that token. I think it's the right meaning for amber, but the token's description should be updated to say so.
Section 7 — Confirmation & Save
7.1 Submitting opens a read-back dialog:
ثبت شماره شبا
درآمد شما به این حساب واریز خواهد شد:
شماره شبا: IR62 0120 0000 0010 1234 5678 90
بانک: بانک ملت
لطفاً شماره را با اطلاعات بانک خود تطبیق دهید. واریز به حساب اشتباه قابل بازگشت نیست.
7.2 The بانک line is omitted if the code wasn't recognised. The شبا renders LTR, in groups of four, with tabular figures.
7.3 CTAs: ثبت نهایی (button-primary-pill) and ویرایش (button-secondary, which returns to the form with the value kept).
7.4 On success, the form collapses into the saved state and a toast confirms:
شماره شبا با موفقیت ثبت شد.
7.5 No admin approval. The شبا is used from the next payout onward.
Section 8 — Saved State & Editing
8.1 The saved card shows the full شبا (LTR, grouped), the bank name if recognised, and the last-updated date in Shamsi:
آخرین به‌روزرسانی: ۵ مهر ۱۴۰۵
8.2 An inline ویرایش action opens the same form, pre-filled, with the same validation, checkbox and read-back dialog. The checkbox must be ticked again on every edit.
8.3 An edit takes effect immediately, including for the next Thursday payout. There's no approval and no hold.
8.4 Every version is kept with a timestamp. Records are never overwritten, so the شبا used for any past payout can always be traced.
Section 9 — Change Notification
9.1 Each edit (not the first registration) triggers an SMS to the creator's registered mobile number:
شماره شبای حساب شما در لومینا تغییر کرد. اگر این تغییر توسط شما انجام نشده، فوراً با پشتیبانی تماس بگیرید.
lumina.ir/dashboard/finance
لومینا
9.2 An in-app notification mirrors the SMS.
9.3 With admin approval gone, this is what stops a hijacked account from silently redirecting a payout. It costs one SMS per edit.
Section 10 — Admin Visibility (hand-off to A15)
10.1 C19 has no admin approval step. The admin sees payout details in the A15 payout screen, next to each creator's balance:
Current شبا and bank name
Last-updated timestamp
Flag: شبای تکراری if it's shared with another account
Flag: تغییر در ۷ روز اخیر if it was edited within 7 days before the payout
10.2 The ownership check happens manually at transfer time. Before confirming a پایا or ساتنا, the admin compares the holder name shown by the bank against the creator's C1-verified name. The exact steps belong in A15.
Section 11 — Edge Cases
# Case Behavior
11.1 Creator suspended (A2) Block is read-only: حساب شما معلق است و امکان ویرایش شماره شبا وجود ندارد.
11.2 Edit saved on Thursday while the admin is paying The admin uses whichever شبا is shown at the moment of transfer, and A15 records it on the payout. The تغییر در ۷ روز اخیر flag makes the change visible
11.3 Balance exists but no شبا on payout day Creator is skipped and the balance carries over. The prompt in 3.3 stays visible
11.4 Browser autofill puts a 16-digit card number in the field Caught by length and checksum validation
11.5 Form abandoned mid-entry Nothing is saved. No drafts
11.6 Creator re-enters the same شبا already on file Saves normally, updates the timestamp, no SMS (nothing changed)
Section 12 — Error States
Condition Message
Save fails (network) ثبت انجام نشد. لطفاً دوباره تلاش کنید.
Save fails (server) خطایی رخ داد. لطفاً چند لحظه دیگر تلاش کنید.
Session expired جلسه شما منقضی شده است. لطفاً دوباره وارد شوید.
12.1 On any failure the typed شبا is kept, so the creator never has to re-type 24 digits.
Section 13 — Design Notes
Block: card-feature-light on {colors.canvas-soft}
Field: text-input, the only LTR element on an RTL page, with tabular figures
Primary CTA: button-primary-pill; secondary: button-secondary
Warnings: {colors.warning}; errors: {colors.ruby}; bank name and timestamp: {colors.ink-mute}
Touch targets ≥ 44×44px; Yekan Bakh throughout
---
## C20 — Earnings & Payouts
C20 — Earnings & Payouts
Story: As a Creator, I want to see my payable balance and a record of every earning and payout, so that I know exactly what I am owed and what has reached me.
Acceptance Criteria
Section 1 — Access & Layout
1.1 Location: داشبورد → مالی. Order, top to bottom:
Payout schedule notice (C19 §2)
Balance summary (§2)
Next payout line (§3)
اطلاعات تسویه‌حساب (C19)
گردش حساب (§4)
1.2 Only the authenticated creator can see it, and only for their own account.
1.3 Subscriber privacy, platform-wide: anywhere in this section, a subscriber is identified by username only. Their phone number and full name never appear in the UI, in notifications, in receipts, or in any creator-facing export or API response. The rule is enforced on the server: those fields never leave the backend in any creator-scoped response.
1.4 All amounts are whole تومان, Persian digits, ٬ separators, font-feature-settings: "tnum".
Section 2 — Balance Summary
2.1 Two figures:
Label Meaning Tooltip (ⓘ)
قابل واریز Confirmed earnings not yet paid out or in transfer این مبلغ در واریز بعدی به حساب شما منتقل می‌شود.
مجموع واریزشده Lifetime total of payouts with status انجام شده مجموع مبالغی که تاکنون به حساب شما واریز شده است.
2.2 Hierarchy: قابل واریز is the primary figure: larger, in {colors.brand-dark-900}. مجموع واریزشده sits beneath it as a secondary line.
2.3 In-transfer line, shown only when one or more payouts are در حال انجام, directly under the primary figure in {colors.ink-mute}:
در حال واریز: ۱٬۲۵۰٬۰۰۰ تومان
2.4 Negative balance. The label stays قابل واریز. The figure shows the negative amount in {colors.ruby}, with this explanation directly below:
قابل واریز: −۱۲۰٬۰۰۰ تومان
این مبلغ بابت بازگشت وجه به مشترکان است و از درآمدهای بعدی شما کسر می‌شود.
2.5 Rendering note (dev): every signed amount, whether in this figure or in ledger rows, is wrapped in an LTR isolate (<bdi dir="ltr"> or unicode-bidi: isolate; direction: ltr) so the sign stays attached to the left of the digits. The word تومان sits outside the isolate.
Section 3 — Next Payout Line
3.1 One line, depending on state:
State Copy
Available > 0 and a شبا on file واریز بعدی: پنجشنبه ۱۰ مهر ۱۴۰۵
Available > 0, no شبا برای دریافت واریز، ابتدا شماره شبای خود را ثبت کنید. (anchor link to the C19 block)
Available ≤ 0 and nothing in transfer در حال حاضر مبلغی برای واریز وجود ندارد.
Available ≤ 0, a payout in transfer Line hidden: the in-transfer line (§2.3) is enough
Account suspended See §9.1
3.2 The date comes from {payout_day} in Asia/Tehran time. Holidays aren't computed; C19 §2's copy covers them.
3.3 No minimum payout threshold in Phase 0. Any positive available amount is eligible.
Section 4 — The Ledger (گردش حساب)
4.1 One reverse-chronological list with two tabs: همه and واریزها.
4.2 Entry types:
Type Label Sign Created by
Subscription income درآمد اشتراک + U10 (successful payment) or A13 (reconciled payment)
Payout واریز به حساب − A15
Refund deduction کسر بازگشت وجه − A16, exceptional cases only
Correction اصلاحیه ± Admin, mandatory reason
4.3 Row anatomy:
Line 1: type label, with the signed amount on the opposite edge
Line 2 in {colors.ink-mute}: context, then the Shamsi date
Type Line 2 example
درآمد اشتراک @username · اشتراک ۳ ماهه · ۵ مهر ۱۴۰۵
واریز به حساب شبای …۵۶۷۸۹۰ · ۱۰ مهر ۱۴۰۵
کسر بازگشت وجه @username · بازگشت وجه اشتراک ۱۲ ماهه · ۸ مهر ۱۴۰۵
اصلاحیه {reason, one line} · ۱۱ مهر ۱۴۰۵
4.4 Payout status pills. Only non-final states are marked:
Status Pill Amount display
در حال انجام pill-tag-soft, {colors.ink-mute} Normal
انجام شده None, the default Normal
لغو شده pill-tag-soft, {colors.ruby} Struck through, {colors.ink-mute}
4.5 Amounts are in ink, and the sign carries the meaning. Red appears only on the negative balance and the لغو شده pill.
4.6 20 rows per page, with نمایش بیشتر. No filters, date ranges or search in Phase 0.
4.7 Each row opens a detail view: a bottom sheet on mobile, a side panel on desktop.
Section 5 — Entry Detail
5.1 درآمد اشتراک:
جزئیات درآمد
قیمت طرح: ۲۹۹٬۰۰۰ تومان
تخفیف: ۲۰٪ (only if a promotion applied)
مبلغ پرداختی مشترک: ۲۳۹٬۰۰۰ تومان
کارمزد لومینا ({commission_rate}٪): −۳۵٬۸۵۰ تومان
سهم شما: ۲۰۳٬۱۵۰ تومان
مشترک: @username
طرح: ۳ ماهه
تاریخ پرداخت: ۵ مهر ۱۴۰۵، ۱۴:۲۲
5.2 The rate shown is the rate stored with that payment, not the current one.
5.3 واریز به حساب:
جزئیات واریز
مبلغ: ۱٬۲۵۰٬۰۰۰ تومان
وضعیت: در حال انجام
تاریخ ثبت: ۱۰ مهر ۱۴۰۵، ۱۱:۰۵
شبای مقصد: IR62 •••• •••• •••• •••• 5678 90
[مشاهده رسید] [دانلود رسید]
5.4 While the status is در حال انجام, the detail view adds a note in {colors.ink-mute}:
بسته به چرخه‌های بانکی، مبلغ معمولاً طی ۱ تا ۲ روز کاری به حساب شما می‌نشیند.
5.5 Once the status is انجام شده, the view adds the completion date:
تاریخ انجام: ۱۳ مهر ۱۴۰۵
The creator is not told whether completion was automatic or manual. That distinction is visible to the admin only.
5.6 The destination شبا is the one recorded when the payout was created, not the creator's current شبا.
5.7 The receipt buttons are always present. A payout can't exist without a receipt, because A15 requires one at creation.
5.8 For لغو شده, the view adds:
تاریخ لغو: ۱۲ مهر ۱۴۰۵
دلیل: {reason}
این مبلغ به موجودی قابل واریز شما بازگشت داده شد.
5.9 کسر بازگشت وجه: the refunded subscription (plan, subscriber username, original payment date), the total refunded to the investor, and the creator's portion deducted.
5.10 اصلاحیه: the amount, the full reason, and the date. The admin's identity is never shown.
Section 6 — How Balances Move
6.1 Auditable history. Income, refund and correction entries are never edited or deleted. A payout's status can change, but every transition is logged with a timestamp, the actor (admin or system), and a reason where one is required. Balances are always derived from these records, never stored as editable numbers.
6.2 Income. Commission = {commission_rate} × amount actually paid (after any promotion), rounded down to a whole تومان. Creator share = amount paid − commission.
6.3 The rate is stored with each income entry at payment time. {commission_rate} is a single global config value that only the tech team changes. There is no admin UI and no per-creator rate in Phase 0.
6.4 Availability. Income is added to قابل واریز immediately on payment confirmation. For a payment resolved later through A13, it becomes available at the moment of resolution.
6.5 Payout lifecycle:
From To Triggered by Effect
— در حال انجام Admin records the payout with amount + receipt (A15) Amount leaves قابل واریز and appears in the in-transfer line (§2.3)
در حال انجام انجام شده Automatically, {auto_complete_hours} after creation, or earlier by an admin Amount moves from in-transfer to مجموع واریزشده. قابل واریز unchanged
در حال انجام لغو شده Admin, mandatory reason Amount returns to قابل واریز
انجام شده لغو شده Admin, mandatory reason (e.g. a bounced transfer) Amount leaves مجموع واریزشده and returns to قابل واریز
6.6 No other transitions exist, and لغو شده is final. The system never cancels on its own: every cancellation is a human decision with a reason.
6.7 {auto_complete_hours} defaults to 72. Payouts go out on Thursday, Friday is a holiday, and a Thursday transfer often lands on Saturday. 24 hours would mark payouts complete before the money arrives. 72 hours covers the normal weekend. Long holidays (نوروز and similar) are handled manually by the admin.
6.8 Automatic completion doesn't depend on any creator action. A creator who hasn't received a payout reports it through the creator support channel. If the report is confirmed, the admin cancels the payout from whichever state it's in.
6.9 The completion job is idempotent. If it runs late, the payout completes on the next run, and the recorded completion time is the actual transition time, not the scheduled time.
6.10 A payout amount can't exceed قابل واریز at the moment it's created. Enforced in A15.
6.11 A refund deduction comes out of قابل واریز and may take it below zero. New income offsets the negative balance first, and no payout can be created while قابل واریز ≤ 0.
Section 7 — Receipts
7.1 Receipts are uploaded by the admin when the payout is created (A15), as an image (JPG/PNG) or a PDF.
7.2 An image receipt opens in C4's full-screen lightbox (close with ✕ or the back gesture). A PDF opens in a new browser tab.
7.3 دانلود رسید saves the original file, uncompressed.
7.4 Receipts are private to their creator, served through signed, expiring URLs, so a copied link never becomes a public document.
Section 8 — Notifications
All mandatory, none can be turned off.
8.1 Payout created (در حال انجام), SMS plus in-app plus push. This is the creator's main payout notification:
مبلغ ۱٬۲۵۰٬۰۰۰ تومان بابت درآمد شما در لومینا به حساب با شبای …۵۶۷۸۹۰ ارسال شد و بسته به چرخه‌های بانکی، معمولاً طی ۱ تا ۲ روز کاری به حساب شما می‌نشیند. رسید واریز در بخش مالی داشبورد قابل مشاهده است.
lumina.ir/dashboard/finance
لومینا
8.2 Payout completed (انجام شده): no notification. Automatic completion comes from a timer, not a confirmation from the bank. Telling the creator «واریز شد» at that moment would be asserting something we haven't checked. The status change shows in the ledger only.
8.3 Payout cancelled (لغو شده), SMS plus in-app:
واریز مبلغ ۱٬۲۵۰٬۰۰۰ تومان به حساب شما لغو شد و این مبلغ به موجودی قابل واریز شما بازگشت. دلیل و جزئیات در بخش مالی داشبورد قابل مشاهده است.
lumina.ir/dashboard/finance
لومینا
The reason stays out of the SMS because it's free text from an admin.
8.4 Refund deduction, SMS plus in-app:
مبلغ ۶۰۰٬۰۰۰ تومان بابت بازگشت وجه اشتراک یکی از مشترکان، از موجودی شما در لومینا کسر شد. جزئیات در بخش مالی داشبورد قابل مشاهده است.
lumina.ir/dashboard/finance
لومینا
The SMS never names the subscriber.
8.5 Correction, in-app only:
یک اصلاحیه به مبلغ {amount} تومان در حساب مالی شما ثبت شد.
8.6 No notification for individual income entries. Whether creators get a "new subscriber" notification is an Epic 6 question.
Section 9 — Edge Cases
# Case Behavior
9.1 Creator suspended (A2) Figures stay visible. The next payout line becomes: به دلیل تعلیق حساب، موجودی شما تا زمان رسیدگی مسدود است و واریزی انجام نمی‌شود. Income from existing subscriptions still records; no new payout can be created. A payout already در حال انجام still auto-completes, because that money has already left
9.2 Payment stuck in در حال بررسی No entry until A13 resolves it. A payment that fails reconciliation never appears
9.3 Creator reports non-receipt while the payout is در حال انجام No in-app action. The admin investigates, and either cancels or lets automatic completion run
9.4 Transfer bounces after automatic completion Admin moves انجام شده → لغو شده with a reason; amount returns; SMS 8.3 corrects the earlier SMS 8.1
9.5 Admin marks a payout انجام شده before the timer Allowed; the timer is cancelled for that payout
9.6 Completion job runs late (outage, deploy) Completes on the next run (§6.9); no notification either way
9.7 Creator edits شبا while a payout is در حال انجام The payout keeps the شبا recorded at creation
9.8 Commission rate changes Past entries unchanged; new entries use the new rate
9.9 Subscriber deletes or loses their account Rows keep the username captured at payment time
9.10 Page open while a status changes No live update; the next load shows the new state
9.11 Two entries with the same timestamp Ordered by entry ID
Section 10 — Empty States
10.1 No entries at all:
هنوز درآمدی ثبت نشده است. پس از اولین اشتراک در کانال شما، جزئیات درآمد اینجا نمایش داده می‌شود.
Both figures show ۰ تومان, and the layout stays intact.
10.2 واریزها tab with no payouts:
هنوز واریزی به حساب شما انجام نشده است.
Section 11 — Error States
Condition Message
Section fails to load بارگذاری اطلاعات مالی انجام نشد. لطفاً دوباره تلاش کنید. (with a تلاش مجدد button)
More rows fail to load بارگذاری ادامه تراکنش‌ها انجام نشد. (inline, with retry)
Receipt fails to open نمایش رسید امکان‌پذیر نیست. لطفاً دوباره تلاش کنید.
Receipt link expired Regenerated silently on tap
11.1 The balance summary and the ledger fail independently, so one failure never blanks the whole section.
Section 12 — Design Notes
Summary: card-feature-light on {colors.canvas-soft}; primary figure in {colors.brand-dark-900}, labels in {colors.ink-mute}
Status pills: pill-tag-soft
{colors.ruby} only for the negative balance and لغو شده
{colors.hairline} dividers between rows
Signed amounts are LTR-isolated (§2.5); tabular figures everywhere; Yekan Bakh throughout
Touch targets ≥ 44×44px, including each full ledger row