Files
cti/docs/markdown/CTI-ARCHITECTURE-ANALYSIS.md
2026-10-14 23:05:02 +03:30

18 KiB
Raw Blame History

CTI Application Architecture Analysis

هدف سند: خط مبنای فنی برای تطبیق مستندات محصول با کد موجود. این متن وضعیت فعلی سورس را ثبت می‌کند و تصمیم طراحی یا مهاجرت نیست.

  • تاریخ تحلیل: 2026-09-16
  • نوع پروژه: Full-stack؛ پنل مدیریتی وب + سرویس مرکزی VoIP/CTI
  • ریشه‌های اصلی: cti-app/ (فرانت‌اند) و p-line/ (بک‌اند)
  • فایل محوری بررسی‌شده: PlineTools.tsx

1. خلاصه اجرایی

سامانه از یک SPA با React 18 و Vite تشکیل شده که از طریق Axios به APIهای Spring Boot متصل می‌شود. بک‌اند روی Java 17، Spring Boot، Spring MVC، Spring Data JPA و PostgreSQL اجرا می‌شود و علاوه بر APIهای مدیریتی، با Asterisk از طریق asterisk-java، فایل‌سیستم سیستم‌عامل، سرویس لایسنس خارجی و یک WebSocket در مسیر /ws ارتباط دارد.

مرزهای اصلی قابل مشاهده:

  1. پنل وب: ورود، داشبورد، تنظیمات، کاربران، SIP، مسیرهای تماس، صف/گروه زنگ، IVR، فکس، گزارش و مانیتورینگ.
  2. API و کنترل دسترسی: کنترلرهای REST در p-line/src/main/java/.../controllers با فیلتر JWT و کنترل مجوز منوی کاربر.
  3. دامنه تلفنی و زیرساخت: تولید فایل‌های Asterisk، مدیریت تماس، شبکه، ذخیره‌سازی، پشتیبان‌گیری، فکس و گزارش‌های CDR.
  4. داده پایدار: مدل‌های JPA با جدول‌های tbl_* و اتصال PostgreSQL.

2. شواهد و شمارش موجودی

مورد مقدار
فایل‌های TypeScript/TSX/JS در cti-app/src 227
فایل‌های Java در p-line/src/main/java 301
کنترلرهای بک‌اند 54 فایل / 53 کلاس دارای @RestController
مدل‌های دارای @Entity 57
Repositoryهای بک‌اند 58
اعلان‌های Mapping در کنترلرها 317 مورد
دامنه‌های سطح اول صفحات فرانت 12 دامنه

تعداد Mappingها شامل Mappingهای سطح کلاس و متد است؛ برای شمارش دقیق endpointهای نهایی باید Mapping سطح کلاس با Mapping سطح متد ترکیب شود.

3. ساختار فرانت‌اند

3.1 فناوری و ورودی اجرا

  • React ^18.3.1، TypeScript ^5.9.3، Vite ^7.2.7
  • مسیریابی با react-router-dom ^6.23.1
  • ارتباط HTTP با axios ^1.7.2
  • ترجمه با i18next و react-i18next
  • UI با React Bootstrap، React Select، اجزای reusable داخلی و Font Awesome
  • نمودارها با Chart.js و react-chartjs-2
  • composition اصلی: App.tsx
  • فهرست صفحات: AppRoutes.tsx

3.2 لایه‌بندی مشاهده‌شده

لایه مسیر نقش
Composition و routing cti-app/src/App.tsx, components/application-components/routes Providerها، Routeها، Footer و loading
Layout components/application-components/layout Header، Sidebar، منوها و Footer
Guard و هویت components/application-components/private-route, pages/login cookie، redirect و ورود/خروج
صفحات دامنه components/pages صفحات قابل دسترسی و فرم‌های CRUD
سرویس شبکه components/services/RequestService.ts, UpdateService.ts, PlineTools.tsx Axios، هدرها، مجوز و خطا
Context و وضعیت UI components/context, components/application-components/common زبان، تم، polling، app info و i18n
اجزای مشترک components/application-components/reuseables input، modal، grid و overlay

3.3 مسیرها و دامنه‌های UI

مسیرهای عمومی در App.tsx:

  • /login
  • /502
  • /notfound
  • مسیرهای ناشناخته به /notfound هدایت می‌شوند.

مسیرهای مدیریتی زیر PrivateRoute هستند. حوزه‌های موجود در AppRoutes.tsx:

حوزه نمونه مسیرها
داشبورد و مانیتورینگ /, /home, /call-monitoring/index, /registered-users/index, /call-reports/index
کاربران و دسترسی تغییر رمز، مجوزها و user management
SIP /sip-profiles/*, /sip-trunks/*, /sip-users/*, /sip-group-users/*
مسیر تماس /call-routes/inbounds/*, /call-routes/specific-outbounds/*
IVR و عملیات تماس /modules/ivr/*, /modules/queue/*, /modules/ring-group/*, /modules/follow-me/*
صدا و اعلان /modules/sounds/*, /modules/announcement/*, /modules/music-on-hold/*
فکس inbox/history، فرم، settings و monitoring
شبکه و سیستم interfaces، routes، VLAN، زمان سیستم، storage، power، certificate و HA
گزارش و CDR call recording، report، CDR setting و queue reports
لایسنس و به‌روزرسانی Licence، update history و Update CTI

4. رفتار و قرارداد PlineTools

PlineTools.tsx یک utility/service متمرکز است:

4.1 تعیین آدرس بک‌اند

  • در localhost یا 127.0.0.1: http://localhost:8080
  • در سایر میزبان‌ها: protocol://hostname[:port]/api
  • URL جداگانه به‌روزرسانی در updateUrl به‌صورت ثابت تعریف شده است.
  • Axios با timeout: 30000 ساخته می‌شود.

موضوع تطبیق: مستندات باید مشخص کنند آیا reverse proxy در production prefix /api را اضافه می‌کند؛ mappingهای کنترلرها در بک‌اند با /app، /users و مانند آن شروع می‌شوند.

4.2 احراز هویت سمت کاربر

  • داده‌های ورود در cookieهای username، token، uid و fullname ذخیره می‌شوند.
  • cookieها با SameSite=Lax و بدون مشاهده HttpOnly/Secure ساخته می‌شوند.
  • interceptor درخواست Axios، token را به‌عنوان Authorization: Bearer ... اضافه می‌کند.
  • mid/Mid برای access code منو استفاده می‌شود.
  • خروج با حذف cookieها و انتقال به #/login انجام می‌شود.

4.3 وضعیت مرورگر

کلیدهای localStorage: language, theme, dashboardLayout, powerTime, timeSet, additionDate, operation.

کلیدهای sessionStorage: confirm_link, version, name, theme, copyRight, website, serial.

موضوع تطبیق: مالک هر کلید، طول عمر، وابستگی به user و رفتار logout/refresh باید در مستندات روشن شود. theme در هر دو storage دیده می‌شود.

4.4 خطا و قطع بک‌اند

  • RequestService خطاهای Axios را به toast/رفتار UI تبدیل می‌کند.
  • backendFailureCount و سقف MAX_FAILURES = 15 وجود دارد.
  • interceptor پاسخ، مسیر /502 را برای شکست‌های متوالی/شبکه‌ای در نظر می‌گیرد.
  • PowerGlobal با polling روی /app/get-version وضعیت reboot/shutdown را بررسی می‌کند.

5. ساختار بک‌اند

5.1 فناوری و تنظیمات اجرا

  • Java 17
  • Spring Boot parent با نسخه ثبت‌شده 4.1.0
  • Spring MVC، Data JPA، JDBC، Data REST، Thymeleaf، Validation، WebSocket و Actuator
  • PostgreSQL driver 42.7.3
  • Asterisk Java 3.41.0
  • JWT با jjwt 0.12.5
  • پورت پیش‌فرض 8080
  • spring.jpa.hibernate.ddl-auto=none؛ schema خودکار از Entity ساخته نمی‌شود.
  • timezone دیتابیس UTC است و در PlineApplication نیز تنظیم می‌شود.

منابع: pom.xml، application.properties، PlineApplication.java

5.2 لایه‌های کد

لایه مسیر شواهد
Bootstrap/config PlineApplication, configuration, init Spring Boot، scheduling و filter
REST controller controllers بیش از 50 controller
Domain/data model models, enums Entity و DTO/response model
Persistence repositories Spring Data و queryهای تراکنشی
سرویس و منطق plineServer تنظیمات، لایسنس، شبکه، لاگ و file generator
عملیات تلفنی coreController تماس، AGI، fax و socket initialization
WebSocket webSocket handler متن روی /ws

5.3 خانواده‌های API

Prefixهای اصلی:

/users, /user-access, /app, /settings, /reports, /sip-profiles, /sip-profile-details, /sip-trunks, /sip-users, /sip-user-groups, /inbound-routes/*, /outbound-routes/*, /queues, /queue-members, /ring-groups, /ivrs, /ivr-keys, /sounds, /announces, /music-on-hold, /ringing-music-on-holds, /fax, /network, /storage, /system, /backup_schedules, /cdr-analysis, /cdr-setting, /call-record-spy, /crm/*, /download, /upload, /tmp.

نمونه‌ها:

6. مرزهای امنیت و دسترسی

فیلتر jwtAuthorizationCheck.java:

  1. OPTIONS و CORS را مدیریت می‌کند.
  2. مسیرهای عمومی شامل /users/login، /app/get-version، /error/*، /download/*، /crm/* و /tmp/* هستند.
  3. سایر درخواست‌ها به Authorization با prefix Bearer نیاز دارند.
  4. token با secret تنظیم‌شده در pline.jwt_secret parse می‌شود.
  5. user از repository پیدا شده و در HttpSession با کلید user قرار می‌گیرد.
  6. برای non-admin، هدر Mid با menu tokenها تطبیق داده می‌شود.
  7. شکست احراز هویت 401 و نبود مجوز منو 404 برمی‌گرداند.

مستندات باید تفاوت 401 و 404، endpointهای public، طول عمر JWT، نقش session و سیاست CORS را صریحاً ثبت کنند.

7. WebSocket و ارتباطات غیر HTTP

ارتباطات دیگر:

  • Asterisk از طریق asterisk-java
  • مسیرهای OS برای config، log، spool، sounds، fax و monitor
  • سرویس خارجی license از pline.license_url
  • PostgreSQL روی 127.0.0.1:5432/pline

8. مدل داده موجود

مدل‌های JPA عمدتاً با Tbl* و جدول‌های tbl_* تعریف شده‌اند. حوزه‌ها:

  • کاربر، دسترسی و log: TblPlineUser, TblUserAccess, TblUserLog
  • SIP: user، profile، profile details، trunk، group و globals
  • inbound/outbound route و pattern/trunk/user/action
  • queue، member، log، ring group و users
  • IVR، sound، announcement و music-on-hold
  • CDR، call record spy و گزارش‌های تحلیلی
  • network: IP address، route و VLAN
  • backup، storage، settings و license

روابط صریح شامل @OneToOne در SIP profile details و @ManyToOne در time condition timing است. چون ddl-auto=none است، schema واقعی باید با SQL و database deployment نیز تطبیق داده شود.

9. جریان‌های کلیدی

ورود

Login page → API login → username/token/uid/fullname → cookie → PrivateRoute → Home.

درخواست محافظت‌شده

صفحه دامنه → RequestService یا PlineTools.api → Authorization و در صورت نیاز Mid → JWT filter → user و menu authorization → controller → service/repository → ApiResult یا response اختصاصی.

بارگذاری و تولید فایل

UI فرم/آپلود → multipart endpoint → temp path یا generator → فایل Asterisk/فایل موقت → اعمال تنظیمات سیستم.

reboot/shutdown

تنظیم power در localStorage → PowerGlobal → polling /app/get-version → تغییر وضعیت → toast → logout.

10. نقاط ابهام برای تطبیق

  1. Prefix API: فرانت در non-localhost پایه /api می‌سازد، اما mappingهای کنترلر با /app، /users و مانند آن شروع می‌شوند؛ reverse proxy/context path باید مستند شود.
  2. نسخه Spring Boot: pom.xml نسخه 4.1.0 را ثبت کرده؛ مستندات build/runtime باید با artifact نهایی کنترل شوند.
  3. مسیریابی: بعضی routeها پارامتر پویا و بعضی literal مانند edit/id دارند؛ رفتار لینک‌ها باید بررسی شود.
  4. احراز هویت دوگانه: cookie/token در فرانت و HttpSession در بک‌اند هم‌زمان استفاده می‌شوند؛ مالک session و invalidate مشخص نیست.
  5. CORS و WebSocket: origin باز * ثبت شده؛ مستندات محیط مجاز باید با deployment واقعی تطبیق یابد.
  6. پایگاه داده: schema خودکار تولید نمی‌شود؛ SQL و DB واقعی منبع نهایی هستند.
  7. قرارداد خطا: بخشی ApiResult با hasError/messages/result و بخشی response مستقیم دارند؛ نباید یک shape واحد فرض شود.
  8. تنظیمات حساس: secret در properties وجود دارد اما در این سند بازتولید نشده؛ مستندات فقط نام کلید و روش مدیریت secret را ثبت کنند.

11. جدول تطبیق مستندات

موضوع مرجع کد وضعیت پرسش تطبیقی
معماری کلان cti-app/, p-line/ استخراج شد آیا دو runtime و مرز deployment همین است؟
فهرست صفحات AppRoutes.tsx استخراج شد آیا routeهای پنهان/غیرفعال نیز ثبت شده‌اند؟
احراز هویت PlineTools.tsx, PrivateRoute.tsx, jwtAuthorizationCheck.java استخراج شد token، session، Mid و statusها چگونه مستند شوند؟
API catalog controllers/ استخراج سطح prefix شد آیا مستندات همه mappingها را پوشش می‌دهد؟
مدل داده models/, SQL init/update نیازمند تطبیق SQL آیا table/column واقعی با Entity یکسان است؟
WebSocket webSocket/ استخراج شد آیا کلاینت واقعاً /ws را مصرف می‌کند؟
Asterisk coreController/, fileGeneratorTools/, properties استخراج شد مسیرها و مجوز OS کجا مستند شده‌اند؟
خطا/مانیتورینگ RequestService, /502, Actuator استخراج شد آستانه 15 failure و قرارداد خطا تأیید شود.

12. فایل‌های مرجع

13. محدودیت تحلیل

این سند static analysis است. رفتار وابسته به database واقعی، reverse proxy، Asterisk، license server، متغیرهای محیطی، فایل‌های خارج از repository یا deployment runtime باید با اجرای سیستم و مستندات عملیاتی تأیید شود. تست، build، deployment topology و ارزیابی امنیتی کامل در دامنه این سند نیستند.