wealth/docs/round-2-auth-and-onboarding.md

681 lines
53 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 2 — Auth & onboarding
> 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.
> Reuse round-1 components. Mobile-first forms; desktop single column, 560px max (C3: 640px).
## Deliver in this round
- Entry screen (shared login/registration), OTP with countdown, blocked state, login success modal, suspended-account screen
- Investor تکمیل پروفایل with live username check and step indicator
- Creator KYC form (no exit), ID card upload
- Creator تکمیل پروفایل: bio, avatar crop, links (quick-add, reorder, 8-link limit), market tags, T&C, success screen
- اطلاعات کاربری (C3) in Verified, Pending and Rejected states, with the unsaved-changes dialog
For every screen: mobile and desktop, RTL, real Farsi copy from below, and all listed states.
## Stories included
- **U1** — Investor Registration & Login _(ClickUp status: in review)_
- **C1** — Creator Registration & Identity Verification _(ClickUp status: in review)_
- **C2** — Creator Profile Setup _(ClickUp status: in review)_
- **C3** — Creator Profile Edit _(ClickUp status: in review)_
---
## U1 — Investor Registration & Login
Story:
As an investor, I want to register and log in with my mobile number so that I can access the platform securely.
Acceptance Criteria:
1. Entry Screen — Mobile Number Input
Happy Path:
A single entry screen handles both registration and login — the user does not need to explicitly choose between the two
The screen accepts Iranian mobile numbers only (format: 09XXXXXXXXX — 11 digits starting with 09)
Input field triggers numeric keyboard on mobile
On submission, the system checks whether the number is already registered:
Number not registered → moves to OTP step → then profile setup → then redirect (context-aware, see Section 5)
Number already registered as investor → moves to OTP step → then redirect (context-aware, see Section 5)
Number already registered as creator → inline error, no redirect
Edge Cases:
The user does not know whether they are registering or logging in — the system handles this silently after number submission
A creator cannot register as an investor using the same mobile number in Phase 0
Error States:
Invalid format: inline error shown, no OTP sent
Number belongs to a creator account: specific inline error shown
Farsi copy:
Screen heading: ورود یا ثبت‌نام
Field label: شماره موبایل
Placeholder: ۰۹۱۲ ۳۴۵ ۶۷۸۹
Invalid format error: شماره موبایل وارد‌شده معتبر نیست.
Creator account error: این شماره به یک حساب کریتور تعلق دارد و امکان ثبت‌نام به عنوان سرمایه‌گذار را ندارد.
CTA button: ادامه
2. OTP Verification
Happy Path:
A 5-digit OTP is sent via SMS immediately after a valid number is submitted
OTP expires after 2 minutes
A visible countdown timer shows remaining time
On correct OTP entry:
New user → proceeds to profile setup (Section 3)
Returning user → login success modal shown → redirected based on context (Section 5)
Edge Cases:
User can request a resend only after the countdown expires — not before
After 3 consecutive failed OTP attempts, the session is blocked for 10 minutes
If the user navigates back to change their mobile number, the current OTP is invalidated — a new one is sent after re-submission
Error States:
Wrong OTP: inline error shown, remaining attempts decremented
Expired OTP: inline error with resend prompt
Blocked session: full-screen message with countdown to unblock
Network error on OTP send: inline error with retry option
Farsi copy:
Screen heading: کد تأیید را وارد کنید
Screen subheading: کد ۵ رقمی ارسال‌شده به {mobile_number} را وارد کنید.
SMS body: کد تأیید شما: ۴۵۲۱۸ — این کد تا ۲ دقیقه معتبر است.
Countdown label: انقضای کد: {mm:ss}
Wrong OTP error: کد وارد‌شده اشتباه است. لطفاً دوباره تلاش کنید.
Expired OTP error: کد منقضی شده. یک کد جدید دریافت کنید.
Resend CTA: ارسال مجدد کد
Blocked state: تعداد تلاش‌های مجاز به پایان رسید. ۱۰ دقیقه دیگر تلاش کنید.
Network error: ارسال کد تأیید ناموفق بود. دوباره تلاش کنید.
Returning user login success modal: شما وارد حساب کاربری خود شدید.
3. Registration — Profile Setup
This step is shown to new users only, immediately after OTP verification. It is mandatory and cannot be skipped — the user cannot access the platform without completing it.
3.1 Full Name
Happy Path:
Two separate fields: first name (نام) and last name (نام خانوادگی)
Persian characters only — Latin characters are not accepted
Both fields are mandatory
Full name is stored for payment reconciliation with ZarinPal — not publicly displayed in Phase 0
Full name can be edited later from the user's profile settings
Edge Cases:
Full name does not need to be unique across the platform
Error States:
Empty first name field: inline error shown
Empty last name field: inline error shown
Latin characters entered: inline error shown on that specific field
Farsi copy:
First name field label: نام
First name placeholder: مثال: علی
Last name field label: نام خانوادگی
Last name placeholder: مثال: رضایی
Empty error: این فیلد الزامی است.
Latin characters error: لطفاً نام را به فارسی وارد کنید.
3.2 Username
Happy Path:
User chooses a unique username that serves as their public identifier on the platform
Username rules:
3–30 characters
Allowed characters: Latin letters (a–z, A–Z), digits (0–9), and underscores (_)
No spaces, no special characters other than underscore
Case-insensitive — Ali and ali are treated as the same username
Must be unique across both investor and creator accounts
Real-time availability check fires after the user stops typing for 500ms (debounced)
Username is immutable after submission — a clear note is shown before submission
Edge Cases:
A user cannot take a username already held by a creator, and vice versa
Real-time availability check is debounced to avoid excessive API calls
Error States:
Taken username: inline error with availability indicator turning red
Invalid characters: inline error shown
Too short: inline error shown
Too long: input stops accepting characters at 30
Empty field on submission: inline error shown
Farsi copy:
Field label: نام کاربری
Field hint: نام کاربری شناسه عمومی شما در پلتفرم است و پس از ثبت قابل تغییر نیست.
Placeholder: مثال: ali_investor
Taken error: این نام کاربری قبلاً انتخاب شده. نام دیگری امتحان کنید.
Invalid characters error: نام کاربری فقط می‌تواند شامل حروف انگلیسی، اعداد و آندرلاین باشد.
Too short error: نام کاربری باید حداقل ۳ کاراکتر باشد.
Available confirmation: این نام کاربری در دسترس است. ✓
Immutability note: نام کاربری پس از ثبت قابل تغییر نیست.
Empty error: وارد کردن نام کاربری الزامی است.
3.3 Form Submission
Happy Path:
All fields are valid and filled
User taps the submit CTA
Account is fully created
User is redirected based on context (Section 5)
Edge Cases:
If the network fails on submission, an error banner appears at the top and all entered data is preserved — not lost
Error States:
Any invalid or empty mandatory field is highlighted with an inline error on submission attempt
Network error: error banner at top of screen with retry option
Farsi copy:
Screen heading: تکمیل پروفایل
Screen subheading: برای ورود به پلتفرم، اطلاعات زیر را تکمیل کنید.
Submit CTA: ورود به پلتفرم
Network error banner: خطا در ثبت اطلاعات. اتصال اینترنت خود را بررسی کنید.
4. Login — Returning User
Happy Path:
Returning investor enters their registered mobile number on the entry screen
System silently detects the number is registered and sends an OTP
On correct OTP entry, login success modal is shown and user is redirected based on context (Section 5)
Edge Cases:
If a returning user's account has been suspended, they are shown a suspended account screen after OTP verification — no redirect occurs
The entry screen is identical for new and returning users — no distinction is made until after number submission
Error States:
Same OTP error states as Section 2 apply
Suspended account: full-screen suspended message shown after OTP verification
Farsi copy:
Login success modal: شما وارد حساب کاربری خود شدید.
Suspended account screen heading: حساب شما تعلیق شده است.
Suspended account screen body: برای اطلاعات بیشتر با پشتیبانی تماس بگیرید.
Support CTA: تماس با پشتیبانی
5. Post-Authentication Redirect (Context-Aware)
⚠️ Forward dependency note: Full implementation of context-aware redirect — including creator profile URL structure, deep link handling, and locked content rendering — is fully specified in Epic 4 (Creator Channel: C4, C4b, C5). The principle is stated here so the authentication flow is built with this behaviour in mind from day one.
Principle:
After successful registration or login, the redirect destination is context-aware:
If the user entered the auth flow from a creator's public channel or a specific post → redirect back to that exact page after completing registration or login
If the user entered the auth flow directly (no creator channel context) → redirect to خانه tab
The originating context must be preserved throughout all registration steps so it is available at the moment of redirect
Farsi copy:
Welcome message for new users: به [نام پلتفرم] خوش آمدید.
6. Logged-Out User Access
⚠️ Forward dependency note: Full specification of the locked content teaser rendering (what is shown vs. hidden, exact layout) is defined in C4, C4b, and C5. This section states only the authentication-related principle: what happens when a logged-out user attempts to act on locked content.
Principle:
Unauthenticated users can browse creator public channels and view free content via a shared link or direct visit — no registration required
Premium content is shown to logged-out users as a locked teaser (full rendering specified in C5)
Any action requiring authentication — subscribing, following, interacting — shows a single unified prompt directing the user to the entry screen (Section 1)
There is only one CTA shown to logged-out users in any locked-content context — the platform never shows separate "Register" and "Login" buttons, since the entry screen itself silently determines which flow applies
After completing registration or login, the user is redirected back to the exact page they were on — as defined in Section 5
Farsi copy:
Locked content prompt (logged-out, shown across all locked-content contexts): برای دسترسی به این محتوا، ابتدا وارد شوید یا ثبت‌نام کنید.
Unified auth CTA: ورود/ثبت‌نام
7. Subscription Access & Waitlist
⚠️ Forward dependency note: Full specification of referral code validation, subscription access control, waitlist entry, and waitlist notification mechanics are deferred to Epic 5 (Paid Access Infrastructure). The following principles are stated here for awareness only.
Principles:
Subscription access to a creator's premium content is controlled via a referral code tied to that creator
Each referral code has a configurable maximum number of uses — set and adjusted manually by the admin in the database
If a referral code has reached its maximum use limit at the time an investor attempts to subscribe, the investor is placed on a waitlist for that creator's channel
When the admin increases the max_uses of a referral code, all waitlisted users for that creator are notified simultaneously via in-app notification and SMS — first to act gets the available slot
Existing subscribers can renew their subscriptions freely regardless of referral code capacity — capacity limits apply to new subscriptions only
8. UI / UX
Layout is RTL throughout; Yekan Bakh is the typeface for all Farsi text
Numeric fields (mobile number, OTP) use font-feature-settings: "tnum" per design system
Primary CTA buttons use button-primary-pill style (#533afd, pill radius)
Error messages render in {colors.ruby} (#ea2261)
Username availability confirmation renders in {colors.primary} (#533afd) with a checkmark
OTP countdown timer renders in {colors.ink-mute} (#64748d), switching to {colors.ruby} in the last 30 seconds
Progress through registration steps is communicated via a simple step indicator at the top — current step highlighted, no total step count shown to avoid overwhelming new users
Minimum touch target for all interactive elements: 44×44px
All registration and login screens are mobile-first
---
## C1 — Creator Registration & Identity Verification
C1 — Creator Registration & Identity Verification
Story: As a creator, I want to register with my mobile number and complete identity verification so that I have a verified, credible identity on the platform.
Acceptance Criteria:
1. Mobile Number Entry
The registration screen accepts Iranian mobile numbers only (format: 09XXXXXXXXX — 11 digits starting with 09)
Input field triggers numeric keyboard on mobile
If the number is already registered, the system shows an error and directs the user to the login flow
If the format is invalid, an inline error appears before the OTP is sent
On correct OTP entry:
New user → proceeds directly to profile & KYC step (no modal)
Returning user (login flow) → a confirmation modal appears before redirecting to the داشبورد tab
Farsi copy:
Field label: شماره موبایل
Placeholder: ۰۹۱۲ ۳۴۵ ۶۷۸۹
Invalid format error: شماره موبایل وارد‌شده معتبر نیست.
Already registered error: این شماره قبلاً ثبت شده. وارد شوید.
CTA button: ارسال کد تأیید
Login success modal: شما وارد حساب کاربری خود شدید.
2. OTP Verification
A 5-digit OTP is sent via SMS immediately after the creator submits their number
OTP expires after 2 minutes
A visible countdown timer shows remaining time
Creator can request a resend only after the countdown expires
After 3 consecutive failed OTP attempts, the session is blocked for 10 minutes
On correct OTP entry, behaviour follows Section 1 (new vs. returning user)
On expired OTP entry, system rejects it and prompts a resend
Farsi copy:
SMS body: کد تأیید شما: ۴۵۲۱۸ — این کد تا ۲ دقیقه معتبر است.
Countdown label: انقضای کد: {mm:ss}
Wrong OTP error: کد وارد‌شده اشتباه است. لطفاً دوباره تلاش کنید.
Expired OTP error: کد منقضی شده. یک کد جدید دریافت کنید.
Resend CTA: ارسال مجدد کد
Blocked state: تعداد تلاش‌های مجاز به پایان رسید. ۱۰ دقیقه دیگر تلاش کنید.
3. Profile Setup & KYC Submission
After OTP is verified, the creator fills in a single form with the following fields before submitting for admin review.
3.1 Username
Creator must choose a unique username serving as their public identifier (channel, profile URL, all public-facing surfaces)
Rules: 3–30 characters, Latin letters/digits/underscore only, case-insensitive, unique across the platform (checked against both investor and creator accounts), checked in real time (debounced)
Locked immediately upon first submission — this is permanent. Once a creator submits their KYC form for the first time, the username is reserved and can never be changed again through any later edit or resubmission flow, including after a rejection
Farsi copy:
Field label: نام کاربری
Field hint: نام کاربری شناسه عمومی شما در پلتفرم است و پس از ثبت اولیه قابل تغییر نیست.
Placeholder: مثال: ali_trader
Taken error: این نام کاربری قبلاً انتخاب شده. نام دیگری امتحان کنید.
Invalid characters error: نام کاربری فقط می‌تواند شامل حروف انگلیسی، اعداد و آندرلاین باشد.
Too short error: نام کاربری باید حداقل ۳ کاراکتر باشد.
Available confirmation: این نام کاربری در دسترس است. ✓
3.2 First Name
Persian characters only — matches the format of the national ID card
Mandatory
Locked immediately upon first submission — through both Pending and Verified states. Reopens for editing only if the submission is Rejected (see Section 8)
Farsi copy:
Field label: نام
Placeholder: مثال: علی
Empty error: این فیلد الزامی است.
Latin characters error: لطفاً نام را به فارسی وارد کنید.
3.3 Last Name
Persian characters only — matches the format of the national ID card
Mandatory
Locked immediately upon first submission — through both Pending and Verified states. Reopens for editing only if the submission is Rejected (see Section 8)
Farsi copy:
Field label: نام خانوادگی
Placeholder: مثال: رضایی
Empty error: این فیلد الزامی است.
Latin characters error: لطفاً نام خانوادگی را به فارسی وارد کنید.
3.4 National ID Number
Exactly 10 digits, numeric only — used by admin for verification, never publicly displayed
Locked immediately upon first submission — through both Pending and Verified states. Reopens for editing only if the submission is Rejected (see Section 8)
Farsi copy:
Field label: کد ملی
Invalid format error: کد ملی باید ۱۰ رقم باشد.
3.5 National ID Card Image Upload
Clear photo of the front side of the national ID card — stored securely, visible only to admins, never displayed publicly
Format: JPG, PNG, or PDF; max 5 MB; mandatory
This field always starts empty and requires a fresh selection every time the creator reaches it — on first submission, after any interrupted/resumed session, and on any resubmission following rejection. No previously selected or submitted image is ever pre-filled or restored, under any circumstance (see Section 8 for full rationale)
Farsi copy:
Upload field label: تصویر کارت ملی (رو)
Upload hint: یک تصویر واضح از روی کارت ملی خود آپلود کنید.
Upload error – wrong format: فقط فایل‌های JPG، PNG یا PDF مجاز هستند.
Upload error – too large: حجم فایل نباید بیشتر از ۵ مگابایت باشد.
3.6 Form Submission & Transition to Channel Setup
All fields mandatory
Creator taps ادامه
On successful submission, creator status is set to Pending Verification; username and all identity fields (first name, last name, national ID) are now locked
The creator is moved directly and seamlessly into channel/profile setup (C2 — تکمیل پروفایل) — no intermediate screen, no wizard, no separate confirmation page
A toast message confirming receipt is shown overlaid on top of the تکمیل پروفایل screen as it loads
Creator cannot publish content, set up payments, or be discovered while Pending — but can complete their channel/profile info immediately, since C2 explicitly allows this in Pending state
Farsi copy:
Submit CTA: ادامه
Toast (shown on the تکمیل پروفایل screen): اطلاعات شما دریافت شد. پس از تأیید، حساب شما فعال می‌شود.
4. Admin Review
Admin receives a new verification request notification in the Admin Panel
For each pending request, admin can view: first name, last name, username, phone number, uploaded national ID card image (full-size, zoomable) — first and last name displayed together as a single combined field in the Admin Panel UI, even though stored as two separate fields
Admin can Approve (→ Verified, notified) or Reject (→ must provide written reason → Rejected, notified with reason)
All admin actions timestamped and logged with admin's account ID
Farsi copy (Admin Panel):
Pending requests section heading: درخواست‌های احراز هویت
Approve CTA: تأیید
Reject CTA: رد کردن
Rejection reason field label: دلیل رد درخواست
Rejection reason placeholder: دلیل رد را بنویسید...
Rejection reason empty error: وارد کردن دلیل رد الزامی است.
5. Verification States
State Trigger Creator Access Identity Fields (name, national ID, username)
Pending Verification KYC form submitted; awaiting admin review Can complete/edit channel & profile via C3 (اطلاعات کاربری); cannot publish or monetize; can browse platform Fully locked — no self-service edits
Verified Admin approved Full creator access unlocked Fully locked, permanently
Rejected Admin rejected Can view rejection reason and resubmit — resubmission happens via the same C3 screen, not a separate form First name, last name, national ID reopen for editing; username remains permanently locked
Account state is visible to the creator across three surfaces (see Section 7)
On rejection, the admin-provided reason is shown both in-app and via SMS
Creator can resubmit — resubmission creates a new pending request in the Admin Panel
There is intentionally no self-service way to correct identity fields while Pending (e.g., a typo the creator spots before admin reviews it) — this is an accepted tradeoff for Phase 0, handled operationally via direct creator contact through the founding-creator support channel, with admin rejecting-with-reason to reopen the fields if needed
Farsi copy:
Pending label: در انتظار تأیید
Verified label: تأییدشده ✓
Rejected label: رد شده
Rejected message: احراز هویت شما تأیید نشد. دلیل: {admin_reason} — اطلاعات را اصلاح و مجدداً ارسال کنید.
Resubmit CTA: ارسال مجدد
6. Notifications
OTP sent: SMS with OTP code
KYC submitted: In-app notification confirming receipt
Admin approved: In-app notification + SMS
Admin rejected: In-app notification + SMS with rejection reason
Farsi copy:
KYC submitted in-app: اطلاعات شما دریافت شد. پس از بررسی، نتیجه به شما اطلاع داده می‌شود.
Approval SMS: حساب کریتور شما در [نام پلتفرم] تأیید شد. اکنون می‌توانید کانال خود را راه‌اندازی کنید.
Rejection SMS: احراز هویت شما در [نام پلتفرم] تأیید نشد. دلیل: {admin_reason} — برای اصلاح و ارسال مجدد وارد حساب خود شوید.
7. Persistent Verification Status Visibility & Resubmission Access (Principle)
⚠️ Forward dependency note: This section states the principle only. Full specification of placement, layout, copy, and interaction is owned by the following stories. C3 (اطلاعات کاربری) is the single, canonical, ongoing surface for viewing verification status, editing profile/channel info, and resubmitting KYC after rejection — کانال and داشبورد only ever navigate to C3, they never host a duplicate form themselves. C2's تکمیل پروفایل screen is a one-time, first-run screen only and is never a recurring destination.
Surface Treatment Tap Destination Full Spec Owned By
کانال tab Full banner with contextual message Navigates to C3, landing target per state below C4
اطلاعات کاربری (C3) Status badge under name/username — تأییدشده ✓ / در انتظار احراز هویت / رد شده (this is the destination itself) C3
داشبورد tab Compact status badge, visually consistent with the C3 badge Navigates to C3, landing target per state below C9 (Epic 6 — Creator Dashboard, not yet written)
Landing target within C3, by state:
Creator State Lands At Why
Rejected Top of screen — اطلاعات هویتی (identity block) Text identity fields (first name, last name, national ID) pre-fill with previously submitted values — creator only fixes what's wrong. The ID card image field always starts empty (Section 8)
Pending (Not applicable — under the mandatory onboarding sequence in Section 8, a Pending creator's profile is always complete) —
Pending, informational only Not tappable Nothing actionable left for the creator to do but wait
Principle (applies to all three surfaces):
The signal is persistent and non-dismissible for any creator not yet Verified
Once Verified, all three signals disappear entirely and do not reappear
This signal does not appear on the standalone post page (C4b)
C2 is a one-time, first-run screen only — reached exactly once via Section 3.6. It is not a recurring destination from کانال or داشبورد; C3 is
8. Onboarding Completeness & Draft Persistence (Cross-Story Principle)
⚠️ Forward dependency note: This principle applies to C1 (this story), C2 (channel/profile setup), and C3 (Rejected resubmission editing). It is documented once here as the shared source of truth.
Mandatory, uninterruptible first-run sequence:
KYC (C1) and channel/profile setup (C2) together form a single mandatory onboarding sequence for first-time creators — there is no in-app exit or back-navigation available until C2 is submitted
This means a Pending creator's profile is always complete by definition — the "incomplete profile" state does not exist for first-run onboarding
Fields that are optional within C2 (bio, avatar, social links) remain optional as content, but the screen itself cannot be abandoned mid-flow
Resumption after OS-level interruption (app killed, backgrounded, call received, etc.) — this is outside our control and must be handled regardless of the "no exit" rule above:
After submission (server-committed state): if KYC has been successfully submitted, re-authenticating (even on a different device) always routes the creator to the correct next step — C2 if channel setup is still pending, or C3 if Verified/Rejected
Before submission (client-side draft only): all text field values (username, first name, last name, national ID digits) are persisted locally as the creator types (e.g., on field blur) and restored if the app is reopened on the same device
Different device, pre-submission: no draft carries over; the form starts blank — acceptable, since nothing has been submitted yet
Resumption is step-level, not field-position-level — the creator returns to the top of whichever screen (C1 or C2) they were on, with text fields pre-filled; no attempt is made to restore exact scroll position or cursor location
No special "welcome back" screen or messaging — resumption happens silently, as if the creator had simply navigated away and returned
National ID card image — never persisted, under any circumstance:
The ID card image field always starts empty and requires a fresh selection, in every scenario without exception: first submission, a resumed draft after interruption, or a Rejected resubmission via C3
This is a deliberate policy, not just a technical limitation: since the image itself is a common source of rejection, silently carrying forward a previously selected (possibly flawed) file risks a creator unknowingly resubmitting the same bad image. Requiring a fresh, conscious selection every time closes that gap entirely
This also removes the need for any fragile "best-effort" file-handle restoration logic across app kills
Rejected resubmission via C3, specifically:
On a fresh (non-interrupted) visit, text identity fields (first name, last name, national ID) pre-fill with the creator's previously submitted values — they edit only what needs correcting
Username is not editable at this stage — it was permanently reserved at first submission (Section 3.1)
The ID card image field is empty and requires fresh selection (see above)
Once resubmitted, the flow is functionally identical to the original C1 submission: status flips to Pending, a new entry appears in the Admin Panel review queue, and all identity fields lock again immediately
9. UI / UX
Layout is RTL throughout; Yekan Bakh is the typeface for all Farsi text, per the Stripi-inspired design system
Numeric fields (OTP, national ID, phone) use font-feature-settings: "tnum" per design system
Primary CTA buttons use button-primary-pill style (#533afd, pill radius)
Error messages render in {colors.ruby} (#ea2261)
Verified badge/state uses {colors.primary} (#533afd) with a checkmark icon
Pending badge/state uses {colors.ink-mute} (#64748d) with a clock/hourglass icon
Rejected badge/state uses {colors.ruby} (#ea2261) with a warning icon
Toast on the تکمیل پروفایل screen uses the standard snackbar component style, auto-dismissing after a few seconds
Minimum touch target for all interactive elements: 44×44px
All screens in this story are mobile-first
Design note for Figma handoff: the existing locked-field captions in the C3 mockups currently read این اطلاعات پس از تأیید هویت قابل تغییر نیست ("cannot be changed after verification"). Per the rule above, fields actually lock at submission, not verification, and reopen only on rejection. Recommend updating the caption to: این اطلاعات پس از ثبت اولیه قابل تغییر نیست، مگر در صورت رد درخواست.
---
## C2 — Creator Profile Setup
C2 — Creator Profile Setup
Story:
As a creator, I want to set up my channel's public profile — bio, avatar, social links, and market specializations — as part of onboarding, so that investors can evaluate my expertise before subscribing.
Acceptance Criteria:
1. Screen Context & Onboarding Flow
Happy Path:
This screen (تکمیل پروفایل) is reached directly and automatically immediately after KYC submission in C1 Section 3.6 — there is no separate navigation step
This is a one-time, first-run screen only. Once submitted, the creator will never see this exact screen again — all future edits to this same data (bio, avatar, links, specializations) happen exclusively through C3 (اطلاعات کاربری)
On load, a toast is shown (triggered by the KYC submission in C1, not owned by this screen): اطلاعات شما دریافت شد. پس از تأیید، حساب شما فعال می‌شود.
All fields are presented as a single continuous scrolling form — not paginated, not a multi-step wizard
The creator's account status is Pending Verification throughout this screen — admin has not yet reviewed their KYC submission
This screen is part of the mandatory onboarding sequence established in C1 Section 8: there is no back button, no in-app exit, and no way to skip or defer this screen
Edge Cases:
If the app is interrupted (backgrounded, killed, call received) while filling this screen, resumption is governed entirely by C1 Section 8 — text field values restore on the same device; a different device starts the screen blank; no special "welcome back" messaging is shown
If the network fails on final submission, an error banner appears and all entered data is preserved — the creator can retry (see Section 6)
Farsi copy:
Screen heading: تکمیل پروفایل
Toast on load (inherited from C1 Section 3.6): اطلاعات شما دریافت شد. پس از تأیید، حساب شما فعال می‌شود.
2. Bio
Happy Path:
Creator enters a free-text bio of up to 300 characters
Persian, English, or mixed text accepted
Bio is displayed on the creator's public profile page below their username
A live character counter is shown as the creator types
Edge Cases:
Bio is optional — creator can submit the form without a bio
Line breaks are allowed (max 3 line breaks to prevent abuse)
URLs typed into the bio are displayed as plain text — not hyperlinked in Phase 0
Error States:
If the character count exceeds 300, the input stops accepting new characters, the counter turns red, and an inline message appears
Farsi copy:
Field label: بیو
Field hint: خود و حوزه تخصصی‌تان را معرفی کنید.
Placeholder: تحلیلگر بازار کریپتو و طلا با ۵ سال سابقه...
Character counter: {n}/۳۰۰
Max length indicator: به حداکثر تعداد کاراکتر رسیدید.
3. Avatar
Happy Path:
Creator uploads a square profile image
Accepted formats: JPG, PNG; maximum size: 5 MB
After upload, a circular crop preview is shown before the form is submitted
Avatar is displayed on the profile page, channel header, post cards, feed, and search results
Edge Cases:
Avatar is optional — if no avatar is uploaded, a default placeholder is shown (initials of the username on a {colors.primary} background)
Non-square images are accepted but the system applies a centered circular crop — a preview is shown so the creator can re-upload if unhappy
Creator can remove an uploaded avatar and revert to the default placeholder at any time
Error States:
Wrong format: inline error shown, upload rejected
File too large: inline error shown, upload rejected
Upload fails due to network error: inline error shown with a retry option
Farsi copy:
Field label: تصویر پروفایل
Field hint: تصویر مربعی با کیفیت بالا توصیه می‌شود.
Upload CTA: انتخاب تصویر
Remove CTA: حذف تصویر
Wrong format error: فقط فایل‌های JPG و PNG مجاز هستند.
Too large error: حجم فایل نباید بیشتر از ۵ مگابایت باشد.
Network error: آپلود ناموفق بود. دوباره تلاش کنید.
4. Social & Web Links
Happy Path:
Creator adds links using a dynamic list — each entry has two fields:
Label — free text, max 30 characters (e.g., کانال تلگرام, لینک‌تری, وب‌سایت شخصی)
URL — the full link
Four quick-add shortcut buttons are shown at the top of this section for the most common platforms: Telegram, Instagram, X, YouTube — tapping one adds a new entry with the label pre-filled, cursor lands on the URL field
For any other platform or link type (Linktree, personal website, etc.), creator taps "افزودن لینک" and fills both fields manually
Links are displayed on the public profile page in the order the creator added them
Creator can reorder links via drag-and-drop
Links go live on the public profile immediately upon saving — no moderation step
If no protocol is entered (i.e., the URL does not start with http:// or https://), the system automatically prepends https:// before saving and displaying the link
Constraints:
Maximum 8 links total
URL must contain at least a domain and a top-level domain (e.g., t.me/ali, linktr.ee/ali) — plain text with no dot is rejected
Label is mandatory for each entry — a link cannot be saved without a label
URL is mandatory for each entry — a label cannot be saved without a URL
T&C Agreement:
A one-time T&C checkbox is shown at the bottom of this form (Section 6) — since this is the creator's first-ever encounter with this data, the checkbox is always shown here, unconditionally
The checkbox must be ticked before the form can be submitted
The T&C text explicitly states that the creator is solely responsible for any links they add — including compliance with Iranian law and platform content policy
Edge Cases:
All link fields are optional — creator can submit the form with no links added
Quick-add shortcuts can be used multiple times (e.g., a creator could add two Telegram links)
If a creator deletes all entries, the section shows an empty state with the shortcut buttons and the add button visible
Creator can delete any individual link entry at any time via a remove icon on that entry
If the creator enters a URL without a protocol (e.g., t.me/ali_trader), https:// is silently prepended on save — no notification needed
Error States:
If a URL field contains plain text with no dot (e.g., alitrader), an inline error appears beneath that entry on submission
If a label is filled but URL is empty (or vice versa), an inline error appears on that entry on submission
Once 8 links are added, the add button is frozen/disabled — it remains visible but non-interactive, with a message shown beneath it
If the network fails on save, the error banner from Section 6 applies — no link data is lost
Farsi copy:
Section label: لینک‌ها
Section hint: لینک کانال‌ها، صفحات یا وب‌سایت خود را اضافه کنید.
Quick-add buttons: تلگرام · اینستاگرام · ایکس · یوتیوب
Label field placeholder: نام لینک (مثال: کانال تلگرام)
URL field placeholder: آدرس لینک (مثال: t.me/alitrader)
Add link CTA: + افزودن لینک
Remove link icon tooltip: حذف لینک
Max links reached (shown beneath frozen button): امکان افزودن بیش از ۸ لینک وجود ندارد!
Invalid URL error: آدرس وارد‌شده معتبر نیست.
Missing label error: وارد کردن نام برای این لینک الزامی است.
Missing URL error: وارد کردن آدرس لینک الزامی است.
T&C checkbox label: مسئولیت تمامی لینک‌های افزوده‌شده، از جمله انطباق آن‌ها با قوانین جمهوری اسلامی ایران و قوانین پلتفرم، به‌عهده من است.
T&C not checked error: برای ادامه، باید شرایط فوق را بپذیرید.
5. Market Specializations
Happy Path:
Creator selects one or more market specialization tags from a predefined list
Available tags in Phase 0:
Tag (Farsi) Tag (English key)
کریپتو crypto
طلا و سکه gold
بورس equities
فارکس forex
صندوق‌های سرمایه‌گذاری funds
مسکن real_estate
خودرو automotive
تتر (دلار و ارز) USDT
Selected tags are displayed as pill-tag-soft chips on the public profile
At least 1 tag must be selected — this is the only mandatory field in this form
Creator can select all tags if applicable (e.g., an institute covering all markets)
Edge Cases:
There is no maximum tag selection limit — creator can select all available tags
Tags are displayed in the same order as selected by the creator
Tags are stored and used internally in Phase 1+ for discovery and filtering — not exposed in Phase 0 discovery UI but must be stored correctly from day one
Error States:
If no tag is selected and the creator attempts to submit, an inline error appears beneath the section
Farsi copy:
Section label: تخصص بازارها
Section hint: بازارهایی که در آن‌ها تحلیل ارائه می‌دهید را انتخاب کنید.
Empty selection error: انتخاب حداقل یک تخصص الزامی است.
6. Form Submission & Transition to Channel
Happy Path:
At least 1 market specialization tag is selected and the T&C checkbox is ticked — these are the only two hard requirements to submit
Creator taps the submit CTA
On successful submission:
A success confirmation is shown: heading پروفایل ذخیره شد with a primary CTA رفتن به کانال
Tapping رفتن به کانال navigates the creator to the کانال tab
Since the creator is still Pending Verification at this moment (admin has not yet reviewed their KYC), the persistent verification banner (fully specified in C4) is visible on the کانال tab — this screen does not duplicate that messaging
This is the only forward path out of this screen — there is no discard, skip, or "complete later" option
Edge Cases:
Bio, avatar, and links remain optional as content — the creator can submit with all three left empty — but the screen itself cannot be abandoned without submitting
If the creator is already Verified by the time they reach this point (extremely unlikely given admin review timing, but technically possible), the same success flow applies — no special-casing needed
Error States:
If the mandatory market specialization field is empty on submission, it is highlighted with an inline error
If the T&C checkbox is not ticked, an inline error appears beneath it
If the network fails on submission, an error banner appears at the top of the form and all entered data is preserved — not lost, and no partial submission occurs
Farsi copy:
Submit CTA: ذخیره و تکمیل
Success screen heading: پروفایل ذخیره شد
Success screen CTA: رفتن به کانال
Network error banner: خطا در ذخیره‌سازی. اتصال اینترنت خود را بررسی کنید.
7. UI / UX
Layout is RTL throughout; Yekan Bakh is the typeface for all Farsi text, per the Stripi-inspired design system
No back arrow or close icon is shown in the top bar on this screen — since no legitimate exit exists, a visible-but-non-functional control would be confusing. The Android hardware back gesture is intercepted and suppressed for the same reason
Market specialization tags use pill-tag-soft style ({colors.primary-bg-subdued-hover} background, {colors.primary-deep} text) when unselected
Selected tags use {colors.primary} fill with white text
Primary CTA uses button-primary-pill style (#533afd, pill radius)
Error messages render in {colors.ruby} (#ea2261)
Character counter for bio uses {colors.ink-mute} and switches to {colors.ruby} when limit is reached
Avatar upload area is a circular dashed-border zone — tappable on mobile
Platform quick-add shortcut buttons use button-secondary style with their respective platform icon
Frozen add link button renders at reduced opacity (0.4) with cursor: not-allowed
Success screen (Section 6) uses a calm, celebratory layout — checkmark or similar affirming visual, generous whitespace, consistent with card-feature-light styling
Minimum touch target for all interactive elements: 44×44px
Form is mobile-first; on desktop, fields are in a single column with a max-width of 560px
---
## C3 — Creator Profile Edit
C3 — Creator Profile Edit (اطلاعات کاربری)
Story:
As a creator, I want to edit my profile information and, if rejected, resubmit my identity verification, so that my profile stays current and I can correct issues that blocked my approval.
Acceptance Criteria:
1. Access & Entry Point
Happy Path:
Accessed by tapping the avatar icon from the top bar — available on both داشبورد and کانال tabs, for any creator regardless of verification state
The screen's top-bar title is اطلاعات کاربری — this is the screen-level label, distinct from the section-level heading introduced in Section 5 below
The screen renders as a single continuous scroll, structured in two independently functioning blocks: اطلاعات هویتی (identity — top) and اطلاعات پروفایل (profile info — below it)
Landing scroll position on entry depends on verification state, per C1 Section 7: Rejected creators land at the top of اطلاعات هویتی; Verified/Pending creators land at the top of the screen normally (no forced scroll)
Edge Cases:
Unlike C2, this screen is exitable — a standard back button is shown, since this is an ongoing edit surface, not mandatory onboarding
If the creator has unsaved changes in either block and attempts to exit, a confirmation dialog appears (Section 8)
2. Verification Status Badge
Happy Path:
Displayed directly beneath the creator's name and username, at the top of the screen
Three states:
State Label Tappable?
Verified تأییدشده ✓ No
Pending در انتظار احراز هویت No — informational only
Rejected رد شده No — the rejection reason and resubmission action are already visible inline in اطلاعات هویتی below; no separate tap action needed since the creator is already on this screen
Edge Cases:
Since C3 is itself the canonical destination referenced by کانال/داشبورد banners (per C1 Section 7), the badge here doesn't need its own navigation — it's a status display, not a link
Farsi copy:
Verified: تأییدشده ✓
Pending: در انتظار احراز هویت
Rejected: رد شده
3. اطلاعات هویتی (Identity Block) — Display by State
Verified state:
Username, first name, last name, national ID — all shown read-only, each with a lock icon and the caption: این اطلاعات پس از ثبت اولیه قابل تغییر نیست، مگر در صورت رد درخواست
No action button — nothing to do here
Pending state:
Identical read-only rendering to Verified — locked, same caption
No action button — per C1 Section 5, there is intentionally no self-service edit while Pending
Rejected state:
A rejection banner is shown at the top of this block: احراز هویت شما تأیید نشد. دلیل: {admin_reason}
First name, last name, national ID unlock and become editable — pre-filled with the creator's previously submitted values (per C1 Section 8) so they only correct what's wrong
National ID card image field is shown empty — always requires a fresh selection, never pre-filled, regardless of prior submissions (per C1 Section 8)
Username remains permanently locked and read-only, even here — it was reserved at first submission and never reopens
A dedicated CTA appears directly beneath this block: ارسال مجدد اطلاعات هویتی
A helper caption sits beneath that CTA: این عملیات فقط اطلاعات هویتی شما را برای بررسی مجدد ارسال می‌کند.
Edge Cases:
The resubmit CTA is disabled until all four identity fields (first name, last name, national ID, ID card image) are validly filled — same validation rules as C1 Sections 3.2–3.5
If the creator edits identity fields but does not tap ارسال مجدد اطلاعات هویتی, and instead only interacts with اطلاعات پروفایل below, the identity edits are not saved — they remain as unsaved local state until that specific CTA is tapped, and trigger the exit-confirmation dialog if the creator tries to leave
Error States:
Same field-level validation errors as C1 Sections 3.2–3.5 (empty fields, Latin characters, invalid national ID format, wrong image format/size)
If resubmission fails due to network error: error banner shown, all entered data preserved, creator can retry
Farsi copy:
Rejection banner: احراز هویت شما تأیید نشد. دلیل: {admin_reason}
Resubmit CTA: ارسال مجدد اطلاعات هویتی
Helper caption: این عملیات فقط اطلاعات هویتی شما را برای بررسی مجدد ارسال می‌کند.
Locked field caption (Verified/Pending): این اطلاعات پس از ثبت اولیه قابل تغییر نیست، مگر در صورت رد درخواست
Username locked caption (all states): نام کاربری پس از ثبت اولیه قابل تغییر نیست.
4. اطلاعات هویتی — Resubmission Success
Happy Path:
On successful resubmission, the creator stays on C3 — no navigation away
A success toast appears: اطلاعات شما مجدداً ارسال شد. پس از بررسی، نتیجه به شما اطلاع داده می‌شود.
The identity block immediately re-locks (read-only again) and the badge flips to در انتظار احراز هویت
This creates a new Pending entry in the Admin Panel review queue, identical in structure to the original C1 submission (per C1 Section 8)
Standard notifications apply per C1 Section 6 (in-app confirmation; later, SMS + in-app on the next admin decision)
Farsi copy:
Resubmission success toast: اطلاعات شما مجدداً ارسال شد. پس از بررسی، نتیجه به شما اطلاع داده می‌شود.
5. اطلاعات پروفایل (Profile Info Block) — Always Editable
This block is functionally identical to C2 Sections 2–5 (Bio, Avatar, Social & Web Links, Market Specializations) — same fields, same validation rules, same limits. It is fully independent of verification state: editable and savable whether the creator is Pending, Verified, or Rejected.
Key difference from C2: the T&C checkbox does not appear here. Since C2's mandatory onboarding sequence already requires T&C agreement before a creator can ever reach C3 for the first time, re-showing it on every edit would be redundant. The creator's original agreement, given once in C2, covers all future edits made through this screen.
Happy Path:
Existing values (bio, avatar, links, specialization tags) are pre-populated from what was saved in C2 or any prior C3 edit
Creator edits any combination of fields and taps the dedicated CTA: ذخیره اطلاعات پروفایل
On success: toast confirmation, values update immediately, and — if the creator is Verified — the public profile reflects changes instantly
Edge Cases:
If the creator is Pending or Rejected, changes save normally but remain not publicly visible until the account reaches Verified status
All field-level rules (bio 300-char limit, avatar format/size, max 8 links, market specialization minimum 1 tag) carry over unchanged from C2
Error States:
Same as C2 Sections 2, 3, 4, 5 respectively (bio overflow, avatar format/size errors, link validation errors, empty specialization error)
Network failure on save: error banner, entered data preserved, retry available
Farsi copy:
Section header: اطلاعات پروفایل
Section CTA: ذخیره اطلاعات پروفایل
Success toast: اطلاعات پروفایل با موفقیت ذخیره شد.
All field-level copy: identical to C2 Sections 2–5 (bio, avatar, links, specializations)
6. Two Independent Save Actions — Rationale & Behavior
اطلاعات هویتی and اطلاعات پروفایل are deliberately decoupled, each with its own CTA, its own validation, and its own success/error handling
The top-bar **ذخیره** button present in the original design is removed entirely — it created ambiguity about scope once the screen had two genuinely independent save actions; removing it avoids that ambiguity rather than trying to define what a combined "save everything" would even mean
A creator can save either block without needing to touch or complete the other
This decoupling is reinforced by distinct CTA language (ارسال مجدد اطلاعات هویتی vs. ذخیره اطلاعات پروفایل) specifically to prevent a Rejected creator from mistakenly believing an edit to their identity fields was saved by tapping the profile-info button, or vice versa
7. Field Editability Summary
Field Verified Pending Rejected
Username Locked Locked Locked
First name Locked Locked Editable (pre-filled)
Last name Locked Locked Editable (pre-filled)
National ID Locked Locked Editable (pre-filled)
National ID card image Locked (n/a — no re-upload) Locked (n/a) Editable (always empty)
Bio Editable Editable Editable
Avatar Editable Editable Editable
Social & web links Editable Editable Editable
Market specializations Editable Editable Editable
8. Exit & Unsaved Changes
Happy Path:
If the creator has no unsaved changes in either block and taps back, they exit immediately — no dialog
If the creator has unsaved changes in either block (identity edits not yet resubmitted, or profile info edits not yet saved), a confirmation dialog appears on exit attempt
Edge Cases:
The dialog checks both blocks independently — if only one block has unsaved changes, the dialog still appears, since any unsaved data would be lost
Dialog options: save-and-exit (triggers whichever block(s) have pending changes) or discard-and-exit
Farsi copy:
Exit confirmation dialog: تغییرات ذخیره‌نشده دارید. آیا می‌خواهید خارج شوید؟
Save-and-exit CTA: ذخیره و خروج
Discard-and-exit CTA: خروج بدون ذخیره
9. UI / UX
Layout is RTL throughout; Yekan Bakh is the typeface for all Farsi text, per the Stripi-inspired design system
Screen top-bar title: اطلاعات کاربری — do not confuse with the اطلاعات پروفایل section header within the page; the two operate at different scopes (screen-level vs. section-level)
Locked fields use {colors.ink-mute} (#64748d) text with a lock icon, background tinted {colors.canvas-soft} to visually read as non-interactive
Verification badge colors: Verified — {colors.primary} (#533afd) with checkmark; Pending — {colors.ink-mute} (#64748d) with clock icon; Rejected — {colors.ruby} (#ea2261) with warning icon
Rejection banner uses {colors.ruby} (#ea2261) background tint, positioned directly above the now-unlocked identity fields to draw immediate attention
Resubmit CTA (ارسال مجدد اطلاعات هویتی) uses button-primary-pill style (#533afd, pill radius) — visually distinct from the profile-info save CTA through label alone, not color, to avoid implying one action is "more correct" than the other
Profile info save CTA (ذخیره اطلاعات پروفایل) also uses button-primary-pill style, positioned at the bottom of that block, separated from the identity block by a clear divider/section break
Helper caption beneath the resubmit CTA uses {colors.ink-mute} (#64748d), smaller type size, non-bold
Minimum touch target for all interactive elements: 44×44px
Screen is mobile-first; on desktop, content is centered in a single column with max-width of 640px