Raptor API Reference (MN)

Бүх модуль, класс, методуудын дэлгэрэнгүй тайлбар.

Агуулга

1. Dashboard\Controller
2. Dashboard\Application
3. Authentication
4. User
5. Organization
6. RBAC
7. Files
8. Content - News
9. Content - Comments
10. Content - Messages
11. Content - Pages
12. Content - References
13. Content - Settings
14. Localization
15. Log
16. Mail
17. Database Middleware
18. SpamProtectionTrait
19. CsrfMiddleware
20. HtmlValidationTrait
21. DashboardTrait
22. FileController
23. AIHelper
24. Badge систем
25. MenuModel
26. Dashboard Home
27. Dashboard Manual
28. Web Layer
29. Shop
30. Notification
31. Development
32. Migration
33. Cache
34. Seed болон анхдагч дата
35. Trash (Хогийн сав)
36. Event систем

Dashboard\Controller

Файл: application/dashboard/Controller.php Extends: codesaur\Http\Application\Controller Uses: codesaur\DataObject\PDOTrait

Бүх Controller-ийн суурь анги.

Properties

Methods

__construct(ServerRequestInterface $request)

Request-аас PDO instance-г авч $this->pdo-д оноох.

getUser(): ?User

Нэвтэрсэн хэрэглэгчийн User объект. Нэвтрээгүй бол null.

getUserId(): ?int

Нэвтэрсэн хэрэглэгчийн ID. Нэвтрээгүй бол null.

isUserAuthorized(): bool

Хэрэглэгч нэвтэрсэн эсэх.

isUser(string $role): bool

Хэрэглэгч тодорхой RBAC role-тэй эсэх.

isUserCan(string $permission): bool

Хэрэглэгч тодорхой RBAC permission-тэй эсэх.

getLanguageCode(): string

Идэвхтэй хэлний код ('mn', 'en' гэх мэт). Олдохгүй бол ''.

getLanguages(): array

Бүртгэлтэй бүх хэлний жагсаалт.

text(string $key, mixed $default = null): string

Орчуулгын текст авах. Олдохгүй бол $default эсвэл {key}.

template(string $template, array $vars = []): FileTemplate

Template үүсгэх. Автоматаар user, index, localization, request хувьсагчид нэмэгдэнэ. text болон link filter-ууд бүртгэгдэнэ.

respondJSON(array $response, int|string $code = 0): void

JSON хариулт хэвлэх. Content-Type: application/json header тохируулна. $code нь хүчинтэй HTTP статус (100-599) бол headerResponseCode()-оор онооно; эс бөгөөс хариу 200 хэвээр үлдэнэ.

redirectTo(string $routeName, array $params = []): void

Route нэрээр 302 redirect хийх. exit дуудна.

log(string $table, string $level, string $message, array $context = []): void

Мэдээллийн баазийн {$table}_log нэртэй хүснэгт рүү системийн лог бичих. Server request metadata болон хэрэглэгчийн мэдээлэл автоматаар нэмэгдэнэ.

dispatch(object $event): void

DI container-ийн EventDispatcher сервисээр PSR-14 event дамжуулах. Dispatcher байхгүй бол чимээгүй алгасна.

generateRouteLink(string $routeName, array $params = [], bool $is_absolute = false, string $default = '#'): string

Route нэрээр URL үүсгэх.

getContainer(): ?ContainerInterface

DI Container авах.

getService(string $id): mixed

Container-аас service авах.

invalidateCache(string ...$keys): void

Заасан cache key-үүдийг устгана. {code} placeholder ашиглавал бүх хэлээр давтана. Cache байхгүй бол алгасна.

$this->invalidateCache('pages_nav.{code}', 'featured_pages.{code}');
$this->invalidateCache('texts.{code}');
$this->invalidateCache('languages');

headerResponseCode(int|string $code): void

HTTP response code-ыг зөвхөн $code нь тоон утга бөгөөд стандарт HTTP мужид (RFC 9110: 100-599) багтах үед онооно. Тоон бус, мужаас гадуур, эсвэл 200 (default) бол алгасна - стандарт бус код хэзээ ч илгээгдэхгүй.

getScriptPath(): string

Script path буцаах (subdirectory дэмжлэг).

getDocumentRoot(): string

Document root зам буцаах.

Middleware-ийн аюулгүй байдлын дүрэм

handle()-г try/catch дотор хэзээ ч дуудаж болохгүй

Middleware runner нь дотоод array pointer (current()/next()) ашиглан queue-г дамждаг. $handler->handle() дуудагдах бүрт pointer нэг алхам ахина - буцаах боломжгүй.

Хэрвээ handle()-г try блок дотор дуудвал, гүнд exception уусаад буцаж ирэхэд catch блок барьж авна - гэхдээ pointer аль хэдийн ахисан байна. Тэгээд try-ийн гадна дахин handle() дуудвал pointer хэтэрч, current() нь false буцааж програм унана.

// Буруу - exception уусахад handle() давхар дуудагдана
public function process($request, $handler): ResponseInterface
{
    try {
        $data = $cache->get('key');
        if ($data !== null) {
            return $handler->handle($request->withAttribute('data', $data));
            //     ^^^^^^^^^^^^^^^ try дотор дуудагдсан - pointer ахина
            //     Гүнд exception уусвал catch барьж авна,
            //     тэгээд доорх handle() дахиад дуудагдана
        }
        $data = $this->loadFromDb();
    } catch (\Throwable $e) {
        \error_log($e->getMessage());
        // Exception чимээгүй баригдсан - гүйцэтгэл үргэлжилнэ
    }
    return $handler->handle($request->withAttribute('data', $data ?? []));
    //     ^^^^^^^^^^^^^^^ хоёр дахь дуудалт - pointer хэтэрсэн -> crash
}

// Зөв - handle()-г зөвхөн нэг удаа, try-ийн гадна дуудна
public function process($request, $handler): ResponseInterface
{
    $data = [];
    try {
        $cached = $cache->get('key');
        if ($cached !== null) {
            $data = $cached;          // Зөвхөн data бэлтгэх, handle() дуудахгүй
        } else {
            $data = $this->loadFromDb();
        }
    } catch (\Throwable $e) {
        \error_log($e->getMessage());
    }
    return $handler->handle($request->withAttribute('data', $data));
    //     ^^^^^^^^^^^^^^^ зөвхөн нэг удаа, try-ийн гадна дуудагдана
}

Дүрмүүд:

• $handler->handle() нь middleware бүрт яг нэг удаа дуудагдах ёстой
• Тэр дуудалт нь try/catch блокийн гадна байх ёстой
• try/catch нь зөвхөн data бэлтгэх логикийг (DB query, cache read, validation) хамрах ёстой
• catch блок нь алдааг зохицуулаад (лог, default утга), гүйцэтгэлийг ганц handle() дуудалт руу урсгах ёстой

Dashboard\Application

Файл: application/dashboard/Application.php Extends: codesaur\Http\Application\Application

Dashboard Application. Middleware pipeline болон бүх Router-уудыг бүртгэнэ.

PDO холболт нь public_html/index.php дотор \Dashboard\DatabaseConnection::connect()-ээр нэг л удаа үүсэн request-ийн pdo attribute хэлбэрээр Application руу ирдэг.

Constructor Pipeline

1. ErrorHandler - Алдаа барих
2. MethodOverrideMiddleware - X-HTTP-Method-Override-аас PUT/PATCH/DELETE-г сэргээнэ (WAF verb-block-ийн шийдэл); Session/routing-аас өмнө ажиллаж жинхэнэ verb-ийг бүх давхаргад харагдуулна
3. BodyEncodingMiddleware - X-Body-Encoding-той ирсэн form талбаруудыг base64-аас decode хийнэ (WAF body-inspection-ийн шийдэл)
4. SessionMiddleware - Session удирдлага
5. JWTAuthMiddleware - JWT баталгаажуулалт
6. ContainerMiddleware - DI Container
7. LocalizationMiddleware - Олон хэл
8. SettingsMiddleware - Тохиргоо
9. LoginRouter, UsersRouter, OrganizationRouter, RBACRouter, LocalizationRouter, ContentsRouter, LogsRouter, MigrationRouter, TrashRouter, TemplateRouter, HomeRouter, ShopRouter (products + orders + reviews), ManualRouter, Development\DevelopmentRouter (хөгжүүлэлтийн хүсэлт application/dashboard/development/-д байрлана), File\FileRouter, Badge\BadgeRouter (sidebar badge систем application/dashboard/badge/-д байрлана)

CsrfMiddleware нь app-wide pipeline-д биш - router дээр mutating route бүрд per-route наагдана.

Authentication

JWTAuthMiddleware

Файл: application/dashboard/authentication/JWTAuthMiddleware.php Implements: MiddlewareInterface

generate(array $data): string

JWT токен үүсгэх. Payload дотор iat, exp, seconds + $data орно.

validate(string $jwt): array

JWT decode + validate хийх. Хугацаа дууссан бол RuntimeException. user_id, organization_id шаардлагатай.

process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

1. $_SESSION['RAPTOR_JWT'] уншина
2. JWT validate хийнэ
3. Хэрэглэгчийн profile DB-с татна
4. RBAC эрхүүдийг ачаална (rbac.{userId} cache) - байгууллагын шалгалтаас өмнө, coder эсэхийг мэдэхийн тулд
5. Байгууллагын хандалтыг шалгана: энгийн хэрэглэгчид organizations_users гишүүнчлэлийн мөр заавал; system_coder бол cross-tenant superuser тул зөвхөн байгууллага идэвхтэй байхад хангалттай (хандах эрх рольоос гарна - гишүүнчлэлийн мөр шаардахгүй, үүсгэхгүй)
6. User объект үүсгэж request attribute-д нэмнэ
7. Алдаа гарвал /dashboard/login руу redirect хийнэ. Хөтчийн хуудас нээлт (GET/HEAD + Accept: text/html, dashboard root/home-оос бусад) дээр анхны зам + query-г ?redirect=... параметрээр дамжуулна - LoginController үүнийг шүүж (зөвхөн dashboard mount доорх same-origin зам), амжилттай нэвтэрсний дараа login.html тэр хуудас руу шилжүүлнэ

SessionMiddleware

Файл: application/dashboard/SessionMiddleware.php Implements: MiddlewareInterface

Dashboard болон Web app хоёуланд ашиглагдах session middleware. Session эхлүүлж, read-only route дээр write-lock-ийг эрт суллана.

Raptor нь session cookie-ийн хугацааг кодоос 30 хоног болгодог (session_set_cookie_params(...)); server талын gc_maxlifetime / save_path нь PHP / host тохиргоогоор ажиллана. Host бүрд тааруулах (эсвэл тэр мөрийг устгаад php.ini-д даатгах) талаар SESSION-LIFETIME.md-аас үз.

Constructor-аар needsWrite closure авна:

• Dashboard: fn($path, $method) => str_contains($path, '/login')
• Web: fn($path, $method) => str_starts_with($path, '/language/') || ...

Closure null бол бүх route дээр session_write_close() дуудна.

LoginRouter

Файл: application/dashboard/authentication/LoginRouter.php

User (Value Object)

Файл: application/dashboard/authentication/User.php

User

UsersModel

Файл: application/dashboard/user/UsersModel.php Extends: codesaur\DataObject\Model

Хүснэгт: users

Organization

OrganizationModel

Файл: application/dashboard/organization/OrganizationModel.php Extends: codesaur\DataObject\Model

Хүснэгт: organizations

OrganizationUserModel

Файл: application/dashboard/organization/OrganizationUserModel.php Extends: codesaur\DataObject\Model

Хүснэгт: organizations_users

Хэрэглэгч-байгууллагын холбоос хүснэгт.

RBAC

RBAC

Файл: application/dashboard/rbac/RBAC.php

Хэрэглэгчийн бүх role болон permission-г ачаалж jsonSerialize() хэлбэрээр буцаадаг.

Roles

Файл: application/dashboard/rbac/Roles.php Extends: codesaur\DataObject\Model

Хүснэгт: rbac_roles

Permissions

Файл: application/dashboard/rbac/Permissions.php Extends: codesaur\DataObject\Model

Хүснэгт: rbac_permissions

RolePermissions

Файл: application/dashboard/rbac/RolePermissions.php

Role-Permission хамаарал.

UserRole

Файл: application/dashboard/rbac/UserRole.php

User-Role хамаарал.

Files

FilesModel

Файл: application/dashboard/file/FilesModel.php Extends: codesaur\DataObject\Model

Файлуудын мэдээлэл хадгалах. Хүснэгтийн нэр динамик (setTable()).

FilesController

Файл: application/dashboard/file/FilesController.php

FileRouter - Files маршрутууд

Protected файл (мөн FileRouter-т):

Dashboard\File\ProtectedFilesController (application/dashboard/file/) нь document root-оос гадуурх /protected хавтасны файлыг дамжуулна. Raptor-тай хамт ирдэг модулиуд protected storage ашигладаггүй тул энэ нь төсөлдөө тааруулж өөрчлөх reference implementation. Эрхийн шалгалт нь authorizeRead(string $relativePath): bool hook - default нь permissive (нэвтэрсэн хэрэглэгч бүр; system_coder үргэлж). Эмзэг файлын хандалтыг нарийсгах бол модулийнхаа index/view permission эсвэл tenant-ownership дүрмээр method-ийг шууд засварлана.

Content - News

NewsModel

Файл: application/dashboard/content/news/NewsModel.php Extends: codesaur\DataObject\Model

Хүснэгт: news

Тэмдэглэл: is_active багана news хүснэгтээс хасагдсан. Устгалтыг бүрмөсөн устгах + Хогийн сав аргаар хийнэ.

getRecentPublished(string $code, int $limit = 20): array

Сүүлийн нийтлэгдсэн мэдээнүүдийг буцаана. id, slug, title, description, photo, code, type, category, is_featured, comment, published_at, created_at, source талбаруудыг авна. read_count (dynamic) оруулаагүй тул cache-д тохиромжтой. HomeController-д recent_news.{code} cache key-ээр ашиглагдана.

generateSlug(string $title): string

SEO-friendly slug үүсгэх. Монгол кирилл транслитераци дэмждэг. Давхардвал дугаар залгана.

getBySlug(string $slug): array|null

Slug-аар мэдээ хайх.

getExcerpt(string $content, int $length = 200): string

HTML контентоос товч хураангуй гаргах.

ContentsRouter - News маршрутууд

Content - Comments

CommentsModel

Файл: application/dashboard/content/news/CommentsModel.php Extends: codesaur\DataObject\Model

Хүснэгт: news_comments

Тэмдэглэл: is_active багана хасагдсан. Устгалтыг бүрмөсөн устгах + Хогийн сав аргаар хийнэ.

CommentsController (Dashboard)

Файл: application/dashboard/content/news/CommentsController.php Extends: Dashboard\Controller

ContentsRouter - Comments маршрутууд

Content - Messages

MessagesModel

Файл: application/dashboard/content/messages/MessagesModel.php Extends: codesaur\DataObject\Model

Хүснэгт: messages

Тэмдэглэл: is_active багана хасагдсан. Устгалтыг бүрмөсөн устгах + Хогийн сав аргаар хийнэ.

MessagesController (Dashboard)

Файл: application/dashboard/content/messages/MessagesController.php Extends: Dashboard\Controller

ContentsRouter - Messages маршрутууд

Content - Pages

PagesModel

Файл: application/dashboard/content/page/PagesModel.php Extends: codesaur\DataObject\Model

Хүснэгт: pages

Тэмдэглэл: is_active багана pages хүснэгтээс хасагдсан. Устгалтыг бүрмөсөн устгах + Хогийн сав аргаар хийнэ.

generateSlug(string $title): string

SEO-friendly slug үүсгэх. Монгол кирилл транслитераци дэмждэг. Давхардвал дугаар залгана.

getBySlug(string $slug): array|null

Slug-аар хуудас хайх.

getNavigation(string $code): array

Нийтлэгдсэн *-menu төрлийн хуудсуудаас мод бүтэцтэй навигаци буцаана. position, id-р эрэмбэлнэ.

buildTree(array $pages, int $parentId = 0): array

Хуудсуудын жагсаалтаас parent -> children -> submenu рекурсив мод бүтэц үүсгэх.

getFeaturedLeafPages(string $code): array

Онцлох хуудсуудаас child-гүй (leaf) хуудсуудыг буцаана.

getExcerpt(string $content, int $length = 200): string

HTML контентоос товч хураангуй гаргах.

ContentsRouter - Pages маршрутууд

Content - References

ReferencesModel

Файл: application/dashboard/content/reference/ReferencesModel.php Extends: codesaur\DataObject\LocalizedModel

Динамик хүснэгтийн нэртэй лавлагааны хүснэгт.

ContentsRouter - References маршрутууд

Content - Settings

SettingsModel

Файл: application/dashboard/content/settings/SettingsModel.php Extends: codesaur\DataObject\LocalizedModel

Хүснэгт: raptor_settings

Үндсэн баганууд

Контент баганууд (хэл тус бүр)

retrieve(): array

Идэвхтэй (is_active=1) тохиргоог авах. Хоосон бол [].

SettingsMiddleware

Файл: application/dashboard/content/settings/SettingsMiddleware.php Implements: MiddlewareInterface

Settings-г DB-с уншиж settings нэрийн request attribute-д inject хийнэ.

ContentsRouter - Settings маршрутууд

SettingsController::updateEnv()

.env файлын утгыг шинэчлэх нэгдсэн endpoint. system_coder эрх шаардлагатай.

Request body: { "name": "ENV_VAR_NAME", "value": "...", "type": "bool|email|string" }

Зөвшөөрөгдсөн .env хувьсагчид:

Төрлийн ажиллагаа:

• bool - Одоогийн утгыг эсрэгээр солино (value талбар хэрэггүй). Хариуд value: true|false
• email - filter_var() ашиглан имэйл формат шалгана. Хоосон утга нь хаягийг арилгана
• string - Шалгалтгүй, шууд хадгална

Messages, orders, comments, reviews жагсаалтын хуудасны дээд хэсэгт system_coder эрхтэй хэрэглэгчдэд харагддаг тохиргоо.

Localization

LanguageModel

Файл: application/dashboard/localization/language/LanguageModel.php Extends: codesaur\DataObject\Model

Хэлний бүртгэлийн хүснэгт.

TextModel

Файл: application/dashboard/localization/text/TextModel.php Extends: codesaur\DataObject\Model

Орчуулгын текстүүд (key -> value).

retrieve(array $languageCodes): array

Бүх орчуулгыг хэлний код -> key -> value бүтцээр буцаана.

LocalizationMiddleware

Файл: application/dashboard/localization/LocalizationMiddleware.php Implements: MiddlewareInterface

Dashboard болон Web app хоёуланд ашиглагдана. Constructor-аар session key авна:

• Dashboard: new LocalizationMiddleware() - default RAPTOR_LANGUAGE_CODE
• Web: new LocalizationMiddleware('WEB_LANGUAGE_CODE')

Request attribute-д localization массив inject хийнэ:

[
    'code'        => 'mn',                    // Идэвхтэй хэлний код
    'language'    => [...],                   // Бүх хэлний жагсаалт
    'text'        => ['key' => 'value', ...], // Орчуулгын текстүүд
    'session_key' => 'RAPTOR_LANGUAGE_CODE'   // Session-д хэл хадгалах key
]

Log

Logger

Файл: application/dashboard/log/Logger.php Extends: \Psr\Log\AbstractLogger

PSR-3 стандартын лог систем. Өгөгдлийн санд хадгална.

setTable(string $table): void

Лог хүснэгтийн нэр тохируулах.

log(mixed $level, string|\Stringable $message, array $context = []): void

Лог бичих.

LogsRouter маршрутууд

Mail

Mailer

Файл: application/dashboard/mail/Mailer.php

И-мэйл илгээх. send() нь RAPTOR_MAIL_TRANSPORT .env тохиргоогоор transport сонгоно: brevo (анхдагч), smtp, mail.

Database

DatabaseConnection

Файл: application/dashboard/DatabaseConnection.php

Бүх PDO холболтыг нэг газраас удирдах helper класс. HTTP entry point (public_html/index.php) болон тестүүд бүгд \Dashboard\DatabaseConnection::connect()-ийг дуудаж нэгэн ижил PDO авна.

• driver(): string - .env-ийн RAPTOR_DB_DRIVER уншина (mysql | pgsql). Зөвшөөрөгдсөн утгуудаас гадуур бол Exception шиднэ.
• connect(): \PDO - driver-ийн дагуу MySQL эсвэл PostgreSQL-д холбогдож PDO instance буцаана. Database нь аль хэдийн үүссэн байх ёстой (implicit auto-create байхгүй).

public_html/index.php дотор үүсгэсэн PDO нь $request->withAttribute('pdo', $pdo) хэлбэрээр Application руу дамждаг. Controller-ууд Dashboard\Controller::__construct() дотор $this->pdo болгон автоматаар авна.

ContainerMiddleware

Файл: application/dashboard/ContainerMiddleware.php

PSR-11 DI Container-г request-д inject хийнэ. cache, mailer, template_service, discord, events зэрэг service factory-уудыг бүртгэнэ. Эдгээр factory-ууд шаардлагатай бол PDO-г request-ийн pdo attribute-аас (entry point дээр суулгасан) уншиж ашиглана.

SpamProtectionTrait

Файл: application/dashboard/SpamProtectionTrait.php

Cloudflare Turnstile болон линк-д суурилсан эвристик ашиглан спам хамгаалалтын методууд хангана.

Methods

getTurnstileSiteKey(): string

ENV тохиргооноос Turnstile site key буцаана. Тохируулаагүй бол хоосон string.

validateSpamProtection(): bool

Request-аас Cloudflare Turnstile токен шалгана. Баталгаажуулалт амжилттай эсвэл Turnstile тохируулаагүй бол true буцаана.

checkLinkSpam(string $text): bool

Текстэд сэжигтэй линк загвар байгаа эсэх шалгана. Спам илэрвэл true буцаана.

Хэрэглэдэг газрууд

• Web\Service\ContactController - Холбоо барих форм илгээх
• Web\Content\NewsController - Мэдээний сэтгэгдэл илгээх
• Web\Shop\ShopController - Захиалга илгээх
• Dashboard\Authentication\LoginController - Бүртгүүлэх, нууц үг сэргээх

CsrfMiddleware

Файл: application/dashboard/CsrfMiddleware.php Implements: Psr\Http\Server\MiddlewareInterface

Dashboard-ийн mutating хүсэлтүүдэд CSRF token шалгах per-route middleware. Router дээр mutating route бүрд ->middleware([CsrfMiddleware::class])-аар наагдана (use Dashboard\CsrfMiddleware;).

Ажиллах зарчим

1. Middleware нь зөвхөн шалгана (token үүсгэх, attribute тавих зэрэг хийхгүй)
2. GET/HEAD/OPTIONS хүсэлтүүд шалгалтгүйгээр дамжина (GET_POST/GET_PUT compound route-ийн GET талыг хамгаална)
3. Бусад методууд (POST, PUT, PATCH, DELETE) $_SESSION['CSRF_TOKEN']-г X-CSRF-TOKEN header-тэй тулгана
4. Token таарахгүй эсвэл байхгүй бол 403 JSON хариу буцаана
5. Login routes exempt - тэнд middleware наахгүй (token login үед үүсдэг)

Token provisioning

• Token нь login үед үүсэж $_SESSION['CSRF_TOKEN'] дотор хадгалагдана
• Хуучин session-д fallback болгож Controller::template() (нэвтэрсэн хэрэглэгчид token байхгүй + session writable бол) үүсгэнэ

Frontend интеграци

• Token нь dashboard.html дахь <meta name="csrf-token"> tag-аар frontend-д хүрнэ
• dashboard.js дахь csrfFetch() wrapper нь X-CSRF-TOKEN header-г автоматаар нэмнэ
• Dashboard модулиудын бүх POST/PUT/PATCH/DELETE хүсэлтэд csrfFetch() ашиглана
• Standalone хуудсууд (жш: login) dashboard.js ачаалагдахгүй тул энгийн fetch() ашиглана

HtmlValidationTrait

Файл: application/dashboard/content/HtmlValidationTrait.php

Серверийн талын HTML контент шалгалт. Pages, News, Products controller-ууд insert/update хийхэд ашиглана.

validateHtmlContent(string $html): void

Хаагдаагүй HTML comment (<!-- -->), эвдэрсэн tag шалгана. DOMDocument ашиглан текстийн урт харьцуулна. 20%-аас их алдагдалтай бол InvalidArgumentException шидэнэ.

Ашигладаг газрууд

• Dashboard\Content\NewsController - Мэдээ нэмэх/засах
• Dashboard\Content\PagesController - Хуудас нэмэх/засах
• Dashboard\Shop\ProductsController - Бүтээгдэхүүн нэмэх/засах

DashboardTrait

Файл: application/dashboard/template/DashboardTrait.php

Dashboard UI рендерлэлт, эрхийн мэдэгдэл, sidebar цэс үүсгэх, хэрэглэгчийн мэдээлэл авах.

Энэ trait-ийг ашигладаг controller нь trait-ийн public API-тай (dashboardTemplate, dashboardProhibited, modalProhibited, getUserMenu, getUserOrganizations) ижил нэртэй метод тодорхойлж болохгүй - class метод trait методыг чимээгүй дарж, trait-ийн дотоод дуудлагуудыг эвдэнэ.

dashboardTemplate(string $template, array $vars = []): FileTemplate

dashboard.html layout дотор контент рендерлэнэ. Sidebar цэс, topbar-ийн байгууллага солих жагсаалт (user_organizations), тохиргоо ачаална. Цэсийг cache-с уншина (menu.{code} key).

dashboardProhibited(?string $alert = null, int|string $code = 0): FileTemplate

Эрхийн хориглолын мэдэгдэл dashboard layout дотор харуулна.

modalProhibited(?string $alert = null, int|string $code = 0): FileTemplate

Эрхийн хориглолын modal (standalone, layout-гүй).

getUserMenu(): array

Хэрэглэгчийн эрх, байгууллагын alias, харагдах байдал, идэвхжилтээр шүүсэн sidebar цэс үүсгэнэ.

getUserOrganizations(): array

Topbar-ийн байгууллага солих dropdown-д зориулж идэвхтэй байгууллагуудын жагсаалтыг [['id' => ..., 'name' => ..., 'logo' => ...], ...] хэлбэрээр буцаана. system_coder-т бүх идэвхтэй байгууллага (cross-tenant роль), бусдад зөвхөн гишүүнчлэлийнх; одоо нэвтэрсэн байгууллага үргэлж багтана. id=1 (системийн үндсэн байгууллага) жагсаалтад байвал үргэлж хамгийн эхэнд, бусад нь нэрийн эрэмбээр. Жагсаалт 1-ээс олон бол dropdown харагдаж, 10-аас олон бол хайлтын шүүлтүүртэй болно.

retrieveUsersDetail(?int ...$ids): array

[user_id => "username - First Last (email)"] map буцаана. ID өгөөгүй бол бүх хэрэглэгчид.

FileController

Файл: application/dashboard/file/FileController.php Extends: Dashboard\Controller

Файл upload, шалгалт, хадгалалт, зураг optimize хийх суурь класс. FilesController, SettingsController, UsersController зэрэг файл upload хийдэг controller-ууд үүнийг extend хийнэ.

Гол методууд

AIHelper

Файл: application/dashboard/content/AIHelper.php Extends: Dashboard\Controller

moedit WYSIWYG editor-ийн OpenAI API интеграци. HTML контент сайжруулалт (Shine) болон зургаас текст таних (OCR/Vision).

moeditAI(): void

POST /dashboard/content/moedit/ai - Хоёр горимтой:

HTML горим (mode: 'html'): RAPTOR_OPENAI_MODEL (.env, default gpt-5-mini) ашиглан HTML контент сайжруулна. Body: {mode, html, prompt}.

Vision горим (mode: 'vision'): RAPTOR_OPENAI_VISION_MODEL (.env, default gpt-5.1) ашиглан зургаас текст таниулна. Body: {mode, images[], prompt}.

Хариу: {status: 'success', html: '...'} эсвэл {status: 'error', message: '...'}.

.env-д RAPTOR_OPENAI_API_KEY шаардлагатай. Нэвтэрсэн хэрэглэгч шаардлагатай.

Badge систем

BadgeController

Файл: application/dashboard/badge/BadgeController.php Extends: Dashboard\Controller

Dashboard sidebar-д модуль тус бүрийн уншаагүй үйлдлийн тоог badge-ээр харуулах систем. *_log хүснэгтүүдээс уншина.

list(): void

GET /dashboard/badges - Модуль бүрийн badge тоог JSON-оор буцаана. Өнгө: ногоон=create, цэнхэр=update, улаан=delete. Админы эрхээр шүүнэ. Өөрийн үйлдлийг тоолохгүй. Шинэ хэрэглэгчид 30 хоногийн lookback.

seen(): void

POST /dashboard/badges/seen - Модулийг уншсан гэж тэмдэглэнэ. checked_at timestamp шинэчилнэ.

Тогтмолууд

• BADGE_MAP - [log_table][action] -> [module_path, color] зурагчлал
• PERMISSION_MAP - Модуль бүрд шаардагдах эрх (null = аль ч админ, 'system_x' = эрх шалгах, 'role:system_coder' = role шалгах)

Хоёр map хоёулаа mount-naive зам (/news, /dashboard/news биш)-аар түлхүүрлэгдэнэ. /dashboard mount prefix-ийг runtime-д getMountPath()-аар нэмдэг тул index.php дахь mount цэгийг өөрчилсөн ч эдгээр map-д гар хүрэх шаардлагагүй.

BadgeRouter

Файл: application/dashboard/badge/BadgeRouter.php

AdminBadgeSeenModel

Файл: application/dashboard/badge/AdminBadgeSeenModel.php Extends: codesaur\DataObject\Model

Админ тус бүрийн модуль сүүлд хэзээ үзсэн мэдээллийг хадгална. Багана: admin_id, module, checked_at, last_seen_count. Unique index: (admin_id, module).

MenuModel

Файл: application/dashboard/template/MenuModel.php Extends: codesaur\DataObject\LocalizedModel

Dashboard sidebar цэсний олон хэлтэй, parent/child бүтэцтэй model.

Баганууд

Методууд

Dashboard Home

HomeRouter

Файл: application/dashboard/home/HomeRouter.php

Нэрлэгдсэн home route нь /dashboard/home дээр; /dashboard (root) нь нэргүй alias хэлбэрээр мөн HomeController::index рүү заасан хэвээр. Sidebar-ийн active-илрүүлэлт prefix-д суурилдаг тул root дээрх home link бүх хуудсанд active болно; харин public вэб layout {{ index }}/dashboard руу шууд линк хийдэг тул root өөрөө үлдэх ёстой.

SearchController

Файл: application/dashboard/home/SearchController.php Extends: Dashboard\Controller

search(): void

Dashboard ерөнхий хайлт - topbar хайлтын modal (Ctrl+K)-ийн endpoint. Мэдээ, хуудас, бүтээгдэхүүн, захиалга, хэрэглэгч, байгууллага, хөгжүүлэлтийн хүсэлт, мессеж, сэтгэгдэл, үнэлгээ хүснэгтүүдээс LIKE query ашиглан хайна. Блок бүр тухайн модулийн index хуудасны ижил permission (эсвэл мөрийн түвшний шүүлт)-ээр хамгаалагдана (news/pages/messages/comments -> system_content_index, products/orders/reviews -> system_product_index, users -> system_user_index, organizations -> system_organization_index, dev-requests -> system_development-гүй бол зөвхөн өөрийн/хуваарилагдсан). JSON буцаана.

WebLogStatsController

Файл: application/dashboard/home/WebLogStatsController.php Extends: Dashboard\Controller

stats(): void

Вэб зочилсон статистик JSON буцаана (өнөөдөр/долоо хоног/сар, график дата, шилдэг хуудас/мэдээ/бүтээгдэхүүн, IP хаяг).

logStats(): void

Системийн *_log хүснэгтүүдийн статистик JSON буцаана (өнөөдөр/долоо хоног/нийт тоо, сүүлийн шинэчлэлт).

WebLogStats

Файл: application/dashboard/home/WebLogStats.php

Вэб зочилсон статистик тооцоолох utility класс. web_log_cache хүснэгт ашиглан гүйцэтгэлийг хурдасгана. MySQL (JSON_EXTRACT) болон PostgreSQL (::jsonb) аль алийг дэмжинэ.

Dashboard Manual

ManualRouter

Файл: application/dashboard/manual/ManualRouter.php

ManualController

Файл: application/dashboard/manual/ManualController.php Extends: Dashboard\Controller

index(): void

application/dashboard/manual/ хавтасны бүх гарын авлагын HTML файлуудыг модулиар нь бүлэглэн жагсаана.

view(string $file): void

Тодорхой гарын авлагын файлыг харуулна. Хүссэн хэлний хувилбар байхгүй бол англи хэлний (-en.html) руу fallback хийнэ.

Web Layer

Web\Application

Файл: application/web/Application.php Extends: codesaur\Http\Application\Application

Public вэб сайтын Application. Middleware pipeline: ExceptionHandler -> Container -> Session -> Localization -> Settings -> WebRouter

WebRouter

Файл: application/web/WebRouter.php

HomeController

Файл: application/web/HomeController.php Extends: TemplateController

PageController

Файл: application/web/content/PageController.php Extends: TemplateController

ContactController

Файл: application/web/service/ContactController.php Extends: TemplateController

NewsController (Web)

Файл: application/web/content/NewsController.php Extends: TemplateController

ShopController

Файл: application/web/shop/ShopController.php Extends: TemplateController

SeoController

Файл: application/web/service/SeoController.php Extends: TemplateController

TemplateController

Файл: application/web/template/TemplateController.php Extends: Dashboard\Controller

ExceptionHandler

Файл: application/web/template/ExceptionHandler.php Implements: codesaur\Http\Application\ExceptionHandlerInterface

Вэб frontend-д хэрэглэгчид ээлтэй алдааны хуудас рендерлэнэ. page-404.html template ашиглана. CODESAUR_DEVELOPMENT горимд JSON stack trace нэмэгдэнэ.

Moedit AI

Маршрут: POST /dashboard/content/moedit/ai Нэр: moedit-ai

moedit editor-ийн AI товчинд зориулсан OpenAI API proxy.

ContentsRouter - Бүх маршрутууд

Файл: application/dashboard/content/ContentsRouter.php

Контент модулийн бүх маршрутыг нэг дор бүртгэнэ. Files, News, Pages, References, Settings, Moedit AI.

Shop

ProductsModel

Файл: application/dashboard/shop/ProductsModel.php Extends: codesaur\DataObject\Model

Хүснэгт: products

generateSlug(string $title): string

SEO-friendly slug үүсгэх. Монгол кирилл транслитераци дэмждэг.

getExcerpt(string $content, int $length = 150): string

HTML контентоос товч хураангуй гаргах.

ProductOrdersModel

Файл: application/dashboard/shop/ProductOrdersModel.php Extends: codesaur\DataObject\Model

Хүснэгт: products_orders

ShopRouter

Файл: application/dashboard/shop/ShopRouter.php

Дэлгүүр модулийн нэгдсэн dashboard router: бүтээгдэхүүн, үнэлгээ, захиалга.

Бүтээгдэхүүн:

Үнэлгээ:

Захиалга:

Notification

DiscordListener

Файл: application/dashboard/notification/DiscordListener.php

PSR-14 event listener - Discord webhook мэдэгдэл илгээнэ. Өмнөх DiscordNotifier шууд дуудлагын загварыг орлосон. ListenerProvider-ээр бүртгэгддэг.

__construct(string $webhookUrl)

RAPTOR_DISCORD_WEBHOOK_URL орчны хувьсагчаас Discord webhook URL авна.

onContentEvent(ContentEvent $event): void

Контентийн үйлдлүүдийг боловсруулна (нэмэх, засах, устгах, нийтлэх) - Мэдээ, Хуудас, Бүтээгдэхүүн гэх мэт.

onUserEvent(UserEvent $event): void

Хэрэглэгчтэй холбоотой event-үүдийг боловсруулна (бүртгүүлэх, зөвшөөрөх).

onOrderEvent(OrderEvent $event): void

Захиалгын event-үүдийг боловсруулна (шинэ захиалга, статус өөрчлөлт, үнэлгээ).

onDevRequestEvent(DevRequestEvent $event): void

Хөгжүүлэлтийн хүсэлтийн event-үүдийг боловсруулна (шинэ хүсэлт, шинэ хариулт).

Өнгөний тогтмолууд

Development

DevelopmentRouter

Файл: application/dashboard/development/DevelopmentRouter.php

Хандалтын дүрэм: бүх маршрут нэвтэрсэн хэрэглэгчийг шаардана. Нэвтэрсэн хэн ч хүсэлт үүсгэж, зөвхөн өөрийн үүсгэсэн болон өөрт хуваарилагдсан (created_by/assigned_to) хүсэлтийг харах, хариулах, устгах боломжтой. system_development эрхтэй хэрэглэгч (permission бичлэг: alias=system, name=development) бүх хүсэлтийг харах, хариулах, устгах бүрэн эрхтэй.

Migration

File-based, forward-only SQL migration систем. State нь disk дээрх directory layout-аар тодорхойлогддог (tracking хүснэгт байхгүй). Per-user folder: database/migrations/{userId}-{username}/ дотор pending файл, {userId}-{username}/ran/ дотор амжилттай ажилласан файл. database/migrations/ нь git-ignored.

MigrationRunner

Файл: application/dashboard/migration/MigrationRunner.php

MigrationController

Файл: application/dashboard/migration/MigrationController.php Extends: Dashboard\Controller

Зөвхөн system_coder role-той хэрэглэгч хандана. Бүх POST үйлдэл CSRF middleware-аар хамгаалагдсан.

MigrationRouter

Файл: application/dashboard/migration/MigrationRouter.php

MigrationSecurityScanner

Файл: application/dashboard/migration/MigrationSecurityScanner.php

Static SQL scanner - apply хийхээс өмнө sensitive хүснэгтэд хандсан pattern илрүүлнэ.

Sensitive хүснэгтүүд (SENSITIVE_TABLES const): users, rbac_roles, rbac_permissions, rbac_user_role, rbac_role_permission, organizations, organizations_users, localization_language, raptor_menu. Нэмж GRANT/REVOKE, CREATE/DROP/ALTER USER pattern-уудыг бас тэмдэглэнэ. SQL comment, string literal-аас үүдсэн false-positive-ийг мэдэрч таслана.

Cache

CacheService

Файл: application/dashboard/CacheService.php Namespace: Dashboard

Custom file-based DB cache (PSR-16 SimpleCache). Гадаад dependency-гүй, зөвхөн psr/simple-cache interface ашиглана. Document root-оос гадуурх, дээд түвшний cache/ хавтаст (logs/-тэй ижил түвшинд) хадгалагдана. ContainerMiddleware-д cache service бүртгэгдсэн. TTL: 12 цаг (нөөц хамгаалалт). Cache байхгүй бол систем DB-ээс шууд уншина.

Cache-лэгдсэн өгөгдөл

Middleware-д ашиглах

// Cache унших (LocalizationMiddleware, SettingsMiddleware)
$cache = $request->getAttribute('container')?->get('cache');
$data = $cache?->get('my_key');
if ($data === null) {
    $data = $model->retrieve();
    $cache?->set('my_key', $data);
}

Controller-д ашиглах

// Cache унших
$cache = $this->hasService('cache') ? $this->getService('cache') : null;
$data = $cache?->get("pages_nav.$code");
if ($data === null) {
    $data = $model->getNavigation($code);
    $cache?->set("pages_nav.$code", $data);
}

// Cache устгах (амжилттай DB бичлэгийн дараа, respondJSON-ийн өмнө)
$this->invalidateCache('pages_nav.{code}', 'featured_pages.{code}');

// RBAC өөрчлөлт (бүх хэрэглэгчид нөлөөлнө)
if ($this->hasService('cache')) {
    $this->getService('cache')->clear();
}

Seed болон анхдагч дата

Seed болон Initial классууд шинэ суулгалт хийхэд өгөгдлийн санг дүүргэнэ. Model-ийн __initial() методоос автоматаар дуудагдана.

PermissionsSeed

Файл: application/dashboard/rbac/PermissionsSeed.php

system_ угтвартай 18+ системийн эрх: logger, rbac, user_* (5), organization_* (4), content_* (6), product_* (5), localization_* (4), templates_index, development.

RolePermissionSeed

Файл: application/dashboard/rbac/RolePermissionSeed.php

Анхдагч role-ууд үүсгэж эрх оноох:

MenuSeed

Файл: application/dashboard/template/MenuSeed.php

Dashboard sidebar цэсний бүтэц 3 хэсэгтэй (MN/EN):

• Contents - Мессеж, Хуудас, Мэдээ, Файл, Хэл, Лавлагаа, Тохиргоо
• Shop - Бүтээгдэхүүн, Захиалга
• System - Хэрэглэгч, Байгууллага, Протокол, Хөгжүүлэлт, Гарын авлага, Migration, Цэс удирдлага

Цэс бүр permission хамгаалалт, position дэс дараалалтай.

TextInitial

Файл: application/dashboard/localization/text/TextInitial.php

100+ системийн орчуулгын keyword MN/EN хос хэлбэрээр (жш: accept, cancel, delete, dashboard, error, success). Цагаан толгойн дарааллаар, sys-defined төрөлтэй.

ReferenceInitial

Файл: application/dashboard/content/reference/ReferenceInitial.php

reference_templates хүснэгтэд и-мэйл загвар, хууль эрхзүйн контент:

• И-мэйл загварууд: forgotten-password-reset, request-new-user, approve-new-user, dev-request-new, dev-request-response, contact-message-notify, order-status-update, order-confirmation, order-notify, comment-notify, review-notify
• Хууль: tos (Үйлчилгээний нөхцөл), pp (Нууцлалын бодлого)

Жишиг дата классууд

Жишиг дата зөвхөн суурь модулиудад байдаг. Шинэ суулгалтад ажиллаж, dashboard-ийн "Reset" товчоор устгаж болно.

Trash (Хогийн сав)

TrashModel

Файл: application/dashboard/trash/TrashModel.php Extends: codesaur\DataObject\Model

Хүснэгт: trash

Бүрмөсөн устгасны дараа бичлэгүүдийг JSON хэлбэрээр хадгална. deleteById() амжилттай дууссан тохиолдолд л trash-д хадгална.

Index: trash_idx_table нь table_name-д, trash_idx_deleted нь deleted_at DESC-д.

store(string $logTable, string $tableName, int $originalId, array $recordData, int $deletedBy): array

Устгасан бичлэгийн хуулбарыг хадгална. Эхний параметр $logTable нь controller-ийн $this->log()-руу дамжуулдаг log channel-ийн нэр - restore() энэ утгыг ашиглаж аудит мөр бичнэ. Controller-ууд deleteById() амжилттай дууссаны дараа дуудна. Sidebar badge-д зориулан trash_log-д action='store' бүхий лог мөн бичигдэнэ.

getById(int $id): array|null

ID-р нэг trash бичлэг авна.

deleteById(int $id): bool

Trash бичлэгийг бүрмөсөн устгана.

TrashController

Файл: application/dashboard/trash/TrashController.php Extends: Dashboard\Controller

Log channel resolution - Controller-ууд TrashModel::store()-д log channel-ийн нэрийг эхний параметр болгож дамжуулдаг; restore() нь log_table баганаас уншиж $this->log()-руу дамжуулна. Codebase даяар ашигладаг стандарт утга:

Restore алгоритм

1. UNIQUE pre-flight - schema-аас (MySQL: information_schema.STATISTICS, PostgreSQL: pg_index) UNIQUE баганаудыг олж тус бүрд live хүснэгтэд давхцал байгаа эсэхийг шалгана. Давхцалтай бол алдаа буцаах (slug, keyword, code, sku гэх мэт талбарыг тодруулж).
2. Original ID-аар оролдох - FK холбоосыг (comments.news_id гэх мэт) хадгалахын тулд эхлээд анхны ID-аар insert хийнэ.
3. Auto-increment fallback - SQLSTATE 23000 (PRIMARY KEY conflict - UNIQUE-ийг pre-flight-аар үнэлсэн тул зөвхөн ID conflict ирнэ) гарвал ID-г хасч, DB-д шинэ ID олгуулна. Хүүхэд бичлэгүүдийн (comments гэх мэт) FK-г гар аргаар шинэчлэх шаардлагатай гэдгийг хариунд анхааруулга бичнэ.
4. LocalizedModel content - snapshot-д localized массив байвал {primary}_content хүснэгтэд шинэ parent_id-аар тус хэлийн мөр бүрийг insert хийнэ.
5. Хоёр давхар аудит лог - trash_log-д (action='trash-restore', restored_by, restored_at, original_id, new_id, used_original_id) ба log_table баганаас уншсан channel-д (action='restore', record_id=<new_id>) бичнэ. Энэ нь сэргээгдсэн бичлэгийн харах/засах хуудсан дээр Logger Protocol-аар "restored" мөр харагдахын тулд.

TrashRouter

Файл: application/dashboard/trash/TrashRouter.php

Устгах стратеги

Контент модулиуд soft delete-ийн оронд бүрмөсөн устгах + Хогийн сав ашиглана:

deactivate() -> delete() болж өөрчлөгдсөн Controller-ууд:

• NewsController (маршрут: /dashboard/news/delete)
• PagesController (маршрут: /dashboard/pages/delete)
• ProductsController (маршрут: /dashboard/products/delete)
• OrdersController (маршрут: /dashboard/orders/delete)
• ReviewsController (маршрут: /dashboard/products/reviews/delete)
• CommentsController (маршрут: /dashboard/news/comments/delete)
• MessagesController (маршрут: /dashboard/messages/delete)
• FilesController (маршрут: /dashboard/files/{table}/delete)
• ReferencesController (маршрут: /dashboard/references/delete)
• DevRequestController (маршрут: /dashboard/dev-requests/delete)

Event систем

EventDispatcher

Файл: application/dashboard/notification/EventDispatcher.php Implements: Psr\EventDispatcher\EventDispatcherInterface

PSR-14 стандартын event dispatcher. ListenerProvider-аас listener-үүдийг авч event объектоор дуудна.

__construct(ListenerProvider $provider)

ListenerProvider instance авна.

dispatch(object $event): object

Event-г бүртгэгдсэн бүх listener-үүдэд дамжуулна.

ListenerProvider

Файл: application/dashboard/notification/ListenerProvider.php Implements: Psr\EventDispatcher\ListenerProviderInterface

Event төрөл бүрд listener бүртгэж хангана.

addListener(string $eventClass, callable $listener): void

Тодорхой event класст listener бүртгэнэ.

getListenersForEvent(object $event): iterable

Өгөгдсөн event-ийн классад бүртгэгдсэн бүх listener-үүдийг буцаана.

ContentEvent

Файл: application/dashboard/notification/ContentEvent.php

Контентийн үйлдлүүдэд дамжуулагддаг event.

UserEvent

Файл: application/dashboard/notification/UserEvent.php

Хэрэглэгчтэй холбоотой event.

OrderEvent

Файл: application/dashboard/notification/OrderEvent.php

Захиалгатай холбоотой event.

DevRequestEvent

Файл: application/dashboard/notification/DevRequestEvent.php

Хөгжүүлэлтийн хүсэлтийн event.

Controller дотор хэрэглэх

// Мэдээ нэмсний дараа content event дамжуулах
$this->dispatch(new ContentEvent(
    'insert', 'news', $record['title'], $id
));