Motoshub · REST API v1 · Bridge Framework · branch: moto-next
پلاگین ow_plugins/api یک لایهی REST تمیز (سبک Laravel روی فریمورک Bridge) با JWT و RBAC
و Swagger زنده است — اما تا امروز فقط ۵ دامنه به آن منتقل شده. این سند دقیقاً میگوید چه چیزی هست، چه چیزی
باید ساخته شود، و با چه تمپلیتی.
استخراج مستقیم از spec زندهی motonext.shub.ir/api/v1/docs/json — ۲۴ عملیات، ۵ دامنه.
| دامنه | عملیات | Endpointها | وضعیت |
|---|---|---|---|
| Auth | 3 | POST /v1/auth/login · GET /v1/auth/me · GET /v1/auth/permissions | کامل |
| Blogs | 5 | GET · POST · GET/{id} · PATCH/{id} · DELETE/{id} | CRUD |
| News | 5 | GET · POST · GET/{id} · PATCH/{id} · DELETE/{id} | CRUD |
| Photos | 5 | GET · POST · GET/{id} · PATCH/{id} · DELETE/{id} | CRUD |
| Albums | 6 | CRUD + GET /v1/albums/{id}/photos | CRUD+ |
iismobilesupport (همان ۱۶۸ عملیاتِ
mobile/services/…) فرق دارد. آنجا منطق کسبوکار همهی فیچرهای اجتماعی از قبل نوشته شده
(در سرویسهای BOL اکسوال). پس مهاجرت یعنی «بستهبندی همان منطق موجود در تمپلیت تمیز v1» — نه نوشتن از صفر.
هر فیچر دقیقاً از این پنج قطعه ساخته میشود (نمونه: Blog).
و خروجی از Resource عبور میکند؛ دسترسی با Policy کنترل میشود.
// ow_plugins/blogs/src/Http/Controllers/API/V1/BlogController.php #[Policy(BlogPolicy::class)] class BlogController extends ApiController { public function __construct(private BlogServiceInterface $blogService){ parent::__construct(); } #[OA\Get(path:'/v1/blogs', tags:["Blogs"], ...)] // داکس Swagger زنده #[RouteGet('api/v1/blogs', middleware:['auth.jwt'])] // روت + JWT #[RoutePermissions(['blogs.view','blogs.list'])] // RBAC public function index(BlogListRequest $request){ $blogs = $this->blogService->fetchBlogs(true, $request->validated()); return Response::json(BlogResource::collection($blogs)); } // show() / store() / update() / destroy() به همین شکل … }
Controller نازک است: فقط orchestration. کارِ واقعی در Service، اعتبارسنجی در Request، شکل خروجی در Resource.
| قطعه | مسیر | مسئولیت |
|---|---|---|
| Controller | src/Http/Controllers/API/V1/ | روتها (attribute)، داکس OA، فراخوانی سرویس |
| Requests (List/Store/Update) | src/Http/Requests/ | پراپرتی تایپدار + #[Required]/#[Sanitize]/#[StripTags] + schema |
| Resource | src/Http/Resources/ | تبدیل خروجی به JSON یکدست + respondCreated/Updated/Deleted |
| Service (+Interface) | src/Services/ + Contracts/Services/ | منطق؛ به BOL اکسوال وصل میشود |
| Policy | src/Policies/ | مجوز دسترسی به عملیات |
| ثبت | SwaggerController scanDirs + auto-route | افزودن پوشهی پلاگین به اسکنر داکس |
new Generator()->generate()) — یعنی نیازمند PHP 8+ است، برخلاف هستهی اکسوال که روی PHP 7.4 است.
این واگرایی نسخه را باید در استقرار مدیریت کرد.سه سطل: منتقلشده ، منطق آماده برای بستهبندی ، و نبودِ کامل بکاند 🆕.
| دامنه | op قدیمی | منبع منطق | تخمین |
|---|---|---|---|
| Users / Profile | 42 | iismobilesupport + BOL_UserService | ۵–۸ روز |
| Groups (+ فایل/پوشه) | 28 | groups + iisgroupsplus | ۴–۶ روز |
| Messaging / Chat | 13 | mailbox | ۴–۵ روز |
| Events | 12 | event + iiseventplus | ۳–۴ روز |
| Forum | 12 | forum + iisforumplus | ۳–۴ روز |
| Newsfeed | 9 | newsfeed + iisnewsfeedplus | ۳–۴ روز |
| Notifications | 6 | notifications | ۲ روز |
| Comments | 5 | BOL_CommentService | ۲ روز |
| Questions / Polls | 5 | iisquestions | ۲ روز |
| Video | 4 | video (الگوی photo آماده) | ۱–۲ روز |
| Friends | 4 | friends | ۲ روز |
| Search / Mention / Privacy / Flag / Contact | ~6 | پلاگینهای مربوطه | ۲–۳ روز |
| iispors (پرسمانساز/کوییز) | ~82 | iispors + iispors_judgement | ۱۰–۱۵ روز |
| Landing builder | ~10 | iislandingcreator | ۳ روز |
| ماژول سازمانی | وضعیت | مسیر پیشنهادی |
|---|---|---|
| Projects / Contracts / Funds / Research / Reports | نه بکاند، نه API | ساخت جدید — ترجیحاً روی Django (به سند معماری کلی)، یا پلاگین جدید اکسوال با همین تمپلیت |
برای هر دامنهی ، این چرخه تکرار میشود. مثال: افزودن Video.
ow_plugins/video) پوشههای src/Http/Controllers/API/V1، Requests، Resources، Services، Contracts/Services، Policies را بساز.VideoServiceInterface + VideoService که داخلش همان متدهای منطقیِ موجود در web_service_video.php / BOL را صدا میزند (منطق را کپی نکن، فراخوانی کن).VideoListRequest/StoreRequest/UpdateRequest با پراپرتیهای تایپدار و اعتبارسنجی.VideoResource برای شکل خروجی یکدست.index/show/store/update/destroy با attributeهای #[OA\...]، #[Route...('api/v1/videos', middleware:['auth.jwt'])] و #[RoutePermissions(...)].scanDirs در SwaggerController اضافه کن تا در داکس زنده ظاهر شود./api/v1/docs/index) عملیات جدید را try-it-out کن.بهترتیب ارزش برای فرانت و وابستگیها. تخمین برای یک بکاند سینیور.
Users/Profile (۴۲ op)، Friends، Notifications. بدون اینها هیچ صفحهی واقعیای در فرانت زنده نمیشود. ~۹–۱۲ روز.
Groups (+files)، Newsfeed، Comments، Messaging. قلب تعامل اجتماعی. ~۱۳–۱۷ روز.
Events، Forum، Video، Questions، Search/Privacy/Flag. ~۱۱–۱۵ روز. (Blog/News/Photo از قبل )
iispors + judgement (بزرگ، ~۸۲ op) و Landing builder. ~۱۳–۱۸ روز.
Projects/Contracts/Funds/Research/Reports — ساخت از صفر (Django یا پلاگین جدید). مستقل از A–D پیش میرود.
دربارهی داکسِ فرانت که در جلسهی قبل شروع شده بود.
قبل از اینکه بفهمیم api/v1 منبع اصلی است، قرار بود openapi.json گیتوی موبایل (۱۶۸ op) را بازتولید و
روی گیتهاب پروتوتایپ (docs.shub.ir/docs) پوش کنم. حالا دو منبع داکس داریم:
iismobilesupport, ۱۶۸ op) — کامل و کارآمد، ولی سبک قدیمی mobile/services/:type.ow_plugins/api, ۲۴ op) — تمیز و RESTful و آیندهی محصول، ولی هنوز کوچک.پیشنهاد: فرانتاند بر روی api/v1 هدفگذاری شود و مهاجرت مطابق فازهای فوق پیش برود؛
تا وقتی یک دامنه هنوز روی v1 نیامده، فرانت موقتاً از گیتوی موبایل همان دامنه استفاده کند. بههمیندلیل داکسِ گیتوی موبایل را
پوش نکردم و منتظر تصمیم تو ماندم. اگر بخواهی، همان را هم بهعنوان «مرجع موقت» منتشر میکنم.
Motoshub API v1 · تهیهشده پس از خواندن پلاگین api و اسپک زندهی motonext.shub.ir · branch moto-next