سند نیازمندی‌ها و یوزر استوری‌ها | مدیریت کلاس‌های ورزشی

خلاصه پروژه

این سند، تمام قابلیت‌های موردنیاز سامانه مدیریت کلاس‌های ورزشی را با تمرکز بر اجرای «سرورمحور» (Laravel) و کلاینت ساده (React Native) ارائه می‌کند: احراز هویت با OTP، مدیریت نقش‌ها، تعریف کلاس و جلسات، ثبت‌نام، فاکتور و پرداخت، حضور و غیاب، پیام‌رسانی، اعلان‌ها (Push/SMS)، لایو استریم، فروشگاه ویژه مربیان، پنل مدیریت، و در نهایت اشتراک ماهانه برای دوره‌های بلندمدت.

کانال‌های اعلان

Push + SMS

پرداخت

درگاه + Webhook

معماری

API-First، Queue، RBAC

نقشه راه

MVP

Auth OTP، پروفایل/مدارک، کلاس/جلسه، ثبت‌نام، فاکتور/پرداخت، حضور و غیاب، چت کلاسی، Push اصلی، پنل ادمین پایه.

V1

استریم زنده، فروشگاه مربیان، SMS رخدادهای کلیدی، گزارش‌گیری مالی/حضور، ارتقای Coach با مدارک نسخه‌دار.

V2

اشتراک ماهانه (صدور خودکار فاکتور، دِنینگ)، پرو-ریت، بازپخش جلسات، کوپن/تخفیف، آنالیتیکس.

Cursor Pagination Webhook-secured Server-issued Tokens Role-based Access

نمای کلی دامنه و مدل داده

هسته مدل داده شامل این موجودیت‌هاست: Users, Documents, Classes, Class Sessions, Enrollments, Attendance, Invoices, Payments, Threads, Messages, Products, Orders, Notifications, Subscriptions. روابط کلیدی بین این موجودیت‌ها، اجرای قوانین کسب‌وکار را ممکن می‌سازد (ظرفیت ثبت‌نام، پرداخت، حضور، چت، و اشتراک ماهانه).

Users & Roles Classes & Sessions Invoices & Payments Threads & Messages Subscriptions

Epic A

احراز هویت و آن‌بوردینگ

Story #1

ورود/ثبت‌نام با OTP (فقط موبایل)

کاربر بتواند با شماره موبایل و کد یکبارمصرف وارد شود.

Acceptance Criteria

Given موبایل معتبر؛ When درخواست OTP؛ Then کد ارسال و نرخ‌دهی محدود شود.
Given کد صحیح؛ When ارسال؛ Then توکن (Sanctum) صادر و ورود کامل شود.
Given کد ناصحیح؛ Then خطای 422 با پیام استاندارد برگردد.

Definition of Done

تست Feature OTP، مستند OpenAPI، لاگ تلاش‌ها و Rate Limit.

Story #2

اسلایدهای معرفی (Onboarding)

اسلایدهای معرفی یک‌بار پس از نصب نمایش داده شوند.

Acceptance Criteria

Given اولین اجرا؛ When ورود؛ Then اسلایدها یک‌بار نمایش داده شود.
Given کاربر رد کرد؛ Then فلگ 'onboarding_seen' ثبت شود.

Definition of Done

ذخیره فلگ در پروفایل؛ رندر سبک RN.

Story #3

نقش اولیه ورزشکار

تمام کاربران در شروع نقش Athlete داشته باشند؛ ارتقا به Coach بعداً.

Acceptance Criteria

Given ثبت‌نام جدید؛ Then نقش Athlete اختصاص یابد.
Given درخواست ارتقا؛ Then مسیر بررسی مدارک فعال شود.

Definition of Done

Policyهای نقش اعمال؛ تست دسترسی.

Epic B

پروفایل و مدارک

Story #4

ویرایش پروفایل

ویرایش نام، آواتار و تنظیمات پایه.

Acceptance Criteria

Given تصویر معتبر؛ When آپلود؛ Then آواتار با URL امضا‌شده ذخیره شود.
Given کاربر خواست حذف آواتار؛ Then تصویر پیش‌فرض اعمال شود.

Definition of Done

ولیدیشن فایل، Signed URLs، تست ولیدیشن.

Story #5

بارگذاری مدارک با وضعیت

آپلود بیمه/مدرک مربی با وضعیت‌های pending/approved/rejected.

Acceptance Criteria

Given فایل آپلود؛ Then نسخه جدید مدرک ساخته و pending شود.
Given ادمین رد کرد؛ Then دلیل رد ثبت و اعلان ارسال شود.

Definition of Done

نسخه‌گذاری، پردازش صف (تولید پیش‌نمایش)، مستندسازی.

Story #6

درخواست ارتقا به مربی

ورزشکار بتواند با ارسال مدارک به Coach ارتقا یابد.

Acceptance Criteria

Given مدارک کامل؛ When ارسال؛ Then تسک بررسی برای ادمین ایجاد شود.
Given تایید ادمین؛ Then نقش Coach و اعلان برای کاربر.

Definition of Done

ایمیل/Push به ادمین، Audit log اقدام.

Epic C

کلاس‌ها و جلسات

Story #7

تعریف کلاس توسط مربی

مربی کلاس را با عنوان، توضیح، ظرفیت، شهریه و قوانین بسازد.

Acceptance Criteria

Given کلاس جدید؛ Then حالت draft ایجاد شود.
When انتشار؛ Then state=published و اعلان به دنبال‌کنندگان اختیاری.

Definition of Done

Policy Coach-only؛ تست ایجاد/ویرایش/انتشار.

Story #8

لیست و جست‌وجوی کلاس‌ها

ورزشکار بتواند کلاس‌ها را جست‌وجو و فیلتر کند.

Acceptance Criteria

Given پارامترها؛ Then صفحه‌بندی Cursor و فیلتر مربی/قیمت/ظرفیت کار کند.
Then پاسخ ≤200ms روی دیتای نمونه 10k رکورد.

Definition of Done

ایندکس‌های DB روی فیلدهای کلیدی، تست Performance محلی.

Story #9

ثبت‌نام در کلاس (Enrollment)

ورزشکار در کلاس ثبت‌نام کند.

Acceptance Criteria

Given ظرفیت و شرایط پرداخت؛ When درخواست؛ Then ایجاد Enrollment یکتا.
Then جلوگیری از ثبت‌نام تکراری، اعلان موفقیت.

Definition of Done

تراکنش اتمیک DB؛ رویداد EnrollmentCreated.

Story #10

مدیریت جلسات کلاس

مربی جلسات کلاس را بسازد و ویرایش کند.

Acceptance Criteria

Given بازه زمانی؛ Then جلوگیری از تداخل، ذخیره starts_at/ends_at.
When تغییر؛ Then اعلان به اعضای کلاس.

Definition of Done

ولیدیشن بازه‌ها، تست CRUD جلسات.

Story #11

حضور و غیاب دستی/QR

ثبت حضور/غیاب برای اعضا.

Acceptance Criteria

Then وضعیت present/absent/late ثبت شود.
Optional: QR برای تایید سریع حضور مربی.

Definition of Done

ثبت زمان/روش، گزارش حضور ساده.

Epic D

مالی و پرداخت

Story #12

ایجاد فاکتور (Invoice)

هنگام ثبت‌نام یا شهریه، فاکتور ساخته شود.

Acceptance Criteria

Then مبلغ، due_at، status=unpaid ثبت شود.
Given لغو؛ Then status=canceled.

Definition of Done

مدل Invoice مرتبط با Enrollment؛ تست‌ها.

Story #13

پرداخت آنلاین با Webhook

پرداخت امن و نهایی‌سازی از طریق Webhook.

Acceptance Criteria

Given پرداخت موفق در درگاه؛ Then Webhook تایید نهایی را ثبت کند.
Given قطع مسیر بازگشت؛ Then همگام‌سازی با Webhook حفظ شود.

Definition of Done

امضای درخواست Webhook، لاگ تراکنش‌ها، تست سناریوها.

Story #14

داشبورد پرداخت برای مربی

نمایش وضعیت پرداخت‌های اعضای کلاس.

Acceptance Criteria

Then فیلتر براساس وضعیت/ماه؛ Export CSV.

Definition of Done

ایندکس‌ها و کوئری‌های بهینه.

Story #15

رزرو ظرفیت پیش از پرداخت

ظرفیت برای مدت کوتاه لاک شود تا اوربوک نشود.

Acceptance Criteria

Then lock 15 دقیقه‌ای با انقضای خودکار.
Then در انقضا، رزرو آزاد شود.

Definition of Done

Job زمان‌بندی‌شده برای release؛ idempotent.

Epic E

پیام‌رسانی و اعلان‌ها

Story #16

چت گروهی کلاس

تاپیک گفتگوی اعضای هر کلاس.

Acceptance Criteria

Then Thread per Class؛ تاریخچه پیام‌ها؛ Push پیام جدید.

Definition of Done

Rate limit ارسال، ریپورت/بلاک پایه.

Story #17

گفتگوی مستقیم مربی↔️ورزشکار

پیام خصوصی بین مربی و ورزشکار.

Acceptance Criteria

Then شروع گفتگو از پروفایل؛ بلاک کاربر؛ اعلان.

Definition of Done

Policy دسترسی، تست DM.

Story #18

اعلان‌های ادمین (Broadcast)

ادمین بتواند به نقش/کلاس/همه پیام بدهد.

Acceptance Criteria

Then هدف‌گیری Segment؛ صف ارسال Push.

Definition of Done

Audit log ارسال‌ها.

Story #19

Push برای رویدادهای کلیدی

اطلاع‌رسانی ثبت‌نام/پرداخت/جلسه.

Acceptance Criteria

Then T-15m برای شروع جلسه؛ پرداخت موفق؛ سررسید فاکتور.

Definition of Done

مدیریت ترجیحات کاربر، مستند قالب پیام‌ها.

Story #20

SMS برای رخدادهای حیاتی (OTP/بدهی)

ارسال پیامک برای OTP و بدهی مهم.

Acceptance Criteria

Then الگوهای پیام؛ محدودیت هزینه؛ fallback بعد از Push ناموفق.

Definition of Done

تنظیم کانال‌ها و درگاه SMS.

Epic F

لایو استریم جلسات

Story #21

شروع لایو توسط مربی

مربی جلسه را به‌صورت زنده پخش کند.

Acceptance Criteria

Then توکن دسترسی موقت (Server-issued) فقط برای اعضای کلاس.
Then پایان خودکار با اتمام جلسه.

Definition of Done

یکپارچه‌سازی LiveKit/Agora/Daily؛ تست توکن.

Story #22

مشاهده لایو توسط اعضا

اعضای کلاس لایو را تماشا کنند.

Acceptance Criteria

Then کنترل دسترسی؛ شمارنده بینندگان؛ ثبت اختیاری حضور.

Definition of Done

کیفیت سازگار با شبکه؛ fallback پیام خطا.

Epic G

فروشگاه مربیان

Story #23

مشاهده کاتالوگ (Coach-only)

مربی محصولات فروشگاه را ببیند.

Acceptance Criteria

Then فیلتر/جست‌وجو؛ نمایش موجودی/قیمت.

Definition of Done

Policy Coach-only؛ تست لیست.

Story #24

ثبت سفارش با تأیید ادمین

مربی سفارش ثبت کند و ادمین تایید/رد کند.

Acceptance Criteria

Then وضعیت pending/approved/rejected؛ اعلان طرفین.

Definition of Done

فاکتور فروشگاهی مستقل؛ Export سفارش‌ها.

Story #25

مدیریت محصولات در پنل ادمین

ادمین کاتالوگ را مدیریت کند.

Acceptance Criteria

Then CRUD محصول/تصویر/موجودی؛ فعال/غیرفعال‌سازی.

Definition of Done

گزارش فروش پایه؛ ولیدیشن داده‌ها.

Epic H

پنل مدیریت

Story #26

مدیریت کاربران و نقش‌ها

ادمین نقش/مجوزها را مدیریت کند.

Acceptance Criteria

Then تعیین نقش‌ها؛ تعلیق کاربر؛ مدیریت دسترسی.

Definition of Done

Spatie Permissions؛ Audit log.

Story #27

بررسی و تأیید مدارک

ادمین مدارک را تایید/رد کند.

Acceptance Criteria

Then درج دلیل رد؛ اعلان نتیجه به کاربر.

Definition of Done

نسخه‌برداری مدارک؛ تاریخچه اقدامات.

Story #28

گزارش‌های نظارتی

گزارش ثبت‌نام/حضور/پرداخت.

Acceptance Criteria

Then بازه زمانی؛ فیلتر؛ خروجی CSV/Excel.

Definition of Done

Queryهای بهینه؛ ایندکس مناسب.

Story #29

تنظیمات سیستم

پیکربندی درگاه، SMS، FCM و کلیدها.

Acceptance Criteria

Then تست اتصال؛ مدیریت Secrets؛ health-check.

Definition of Done

صفحه وضعیت سرویس‌ها.

Epic I

اشتراک/اقساط ماهانه

Story #30

پلن ماهانه برای دوره‌های بلندمدت

تعریف دوره با Billing ماهانه.

Acceptance Criteria

Then انتخاب نوع پرداخت ماهانه؛ ارتباط با کلاس/پلن.

Definition of Done

مدل subscriptions با periodها.

Story #31

تولید خودکار فاکتور ماهانه

هر ماه برای مشترکین فاکتور تولید شود.

Acceptance Criteria

Then Job زمان‌بندی؛ due_at؛ idempotency برای جلوگیری از تکرار.

Definition of Done

لاگ ساخت؛ اعلان به کاربر؛ تست شبیه‌سازی Cron.

Story #32

یادآوری و ریترای پرداخت (Dunning)

یادآوری‌های T-3/T0/T+3 و تعلیق در T+7.

Acceptance Criteria

Then past_due و نهایتاً suspended در عدم پرداخت.

Definition of Done

قابل‌پیکربندی در پنل؛ تمپلیت پیام‌ها.

Story #33

پرو-ریت دوره (اختیاری)

محاسبه مبلغ بر اساس روزهای باقی‌مانده.

Acceptance Criteria

Then محاسبه دقیق در شروع وسط‌ماه.

Definition of Done

تست واحد سناریوهای مختلف.

Story #34

لغو اشتراک

ورزشکار بتواند اشتراک را لغو کند.

Acceptance Criteria

Then توقف صدور فاکتورهای بعدی؛ تاریخ اثر.

Definition of Done

ثبت دلیل لغو؛ سیاست بازگشت وجه قابل تنظیم.

Epic J

سیاست‌ها و کیفیت سیستم

Story #35

ترجیحات اعلان

کاربر بتواند ترجیحات Push/SMS را مدیریت کند.

Acceptance Criteria

Then روشن/خاموش برای هر نوع رویداد.

Definition of Done

ذخیره در notification_settings؛ تست API.

Story #36

طرح خطای یکنواخت API

الگوی خطا واحد برای همه اندپوینت‌ها.

Acceptance Criteria

Then `{code,message,details}` در خطاها برگردد.

Definition of Done

OpenAPI examples؛ مپ خطاها.

Story #37

لاگ و مانیتورینگ

لاگ ساختاریافته و Health-check.

Acceptance Criteria

Then آلارم روی 5xx؛ صفحه وضعیت.

Definition of Done

Sentry/Log Channel؛ تست Health endpoint.