18 KiB
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 ارتباط دارد.
مرزهای اصلی قابل مشاهده:
- پنل وب: ورود، داشبورد، تنظیمات، کاربران، SIP، مسیرهای تماس، صف/گروه زنگ، IVR، فکس، گزارش و مانیتورینگ.
- API و کنترل دسترسی: کنترلرهای REST در
p-line/src/main/java/.../controllersبا فیلتر JWT و کنترل مجوز منوی کاربر. - دامنه تلفنی و زیرساخت: تولید فایلهای Asterisk، مدیریت تماس، شبکه، ذخیرهسازی، پشتیبانگیری، فکس و گزارشهای CDR.
- داده پایدار: مدلهای 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.
نمونهها:
AppControllers.java:/app/get-version,/app/info,/app/send-code,/app/mobile-verify,/app/registerReportsControllers.java: CDR، CPU، memory، disk، channel و hangupSipUsersControllers.java: CRUD، import/export و عملیات گروهیPlineController.java: upload باmultipart/form-data
6. مرزهای امنیت و دسترسی
فیلتر jwtAuthorizationCheck.java:
OPTIONSو CORS را مدیریت میکند.- مسیرهای عمومی شامل
/users/login،/app/get-version،/error/*،/download/*،/crm/*و/tmp/*هستند. - سایر درخواستها به
Authorizationبا prefixBearerنیاز دارند. - token با secret تنظیمشده در
pline.jwt_secretparse میشود. - user از repository پیدا شده و در
HttpSessionبا کلیدuserقرار میگیرد. - برای non-admin، هدر
Midبا menu tokenها تطبیق داده میشود. - شکست احراز هویت
401و نبود مجوز منو404برمیگرداند.
مستندات باید تفاوت 401 و 404، endpointهای public، طول عمر JWT، نقش session و سیاست CORS را صریحاً ثبت کنند.
7. WebSocket و ارتباطات غیر HTTP
- endpoint:
/ws - پیادهسازی:
WebSocketConfig.javaوPlineWebSocketHandler.java - origin مجاز
*است. - handler پیام متنی ورودی را با پیشوند
Server response:برمیگرداند.
ارتباطات دیگر:
- 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. نقاط ابهام برای تطبیق
- Prefix API: فرانت در non-localhost پایه
/apiمیسازد، اما mappingهای کنترلر با/app،/usersو مانند آن شروع میشوند؛ reverse proxy/context path باید مستند شود. - نسخه Spring Boot:
pom.xmlنسخه4.1.0را ثبت کرده؛ مستندات build/runtime باید با artifact نهایی کنترل شوند. - مسیریابی: بعضی routeها پارامتر پویا و بعضی literal مانند
edit/idدارند؛ رفتار لینکها باید بررسی شود. - احراز هویت دوگانه: cookie/token در فرانت و
HttpSessionدر بکاند همزمان استفاده میشوند؛ مالک session و invalidate مشخص نیست. - CORS و WebSocket: origin باز
*ثبت شده؛ مستندات محیط مجاز باید با deployment واقعی تطبیق یابد. - پایگاه داده: schema خودکار تولید نمیشود؛ SQL و DB واقعی منبع نهایی هستند.
- قرارداد خطا: بخشی
ApiResultباhasError/messages/resultو بخشی response مستقیم دارند؛ نباید یک shape واحد فرض شود. - تنظیمات حساس: 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. فایلهای مرجع
App.tsxAppRoutes.tsxPlineTools.tsxRequestService.tspackage.jsonpom.xmlPlineApplication.javajwtAuthorizationCheck.javaWebSocketConfig.javaPlineWebSocketHandler.javaapplication.properties
13. محدودیت تحلیل
این سند static analysis است. رفتار وابسته به database واقعی، reverse proxy، Asterisk، license server، متغیرهای محیطی، فایلهای خارج از repository یا deployment runtime باید با اجرای سیستم و مستندات عملیاتی تأیید شود. تست، build، deployment topology و ارزیابی امنیتی کامل در دامنه این سند نیستند.