# CTI Application Architecture Analysis > **هدف سند:** خط مبنای فنی برای تطبیق مستندات محصول با کد موجود. این متن وضعیت فعلی سورس را ثبت می‌کند و تصمیم طراحی یا مهاجرت نیست. - **تاریخ تحلیل:** 2026-09-16 - **نوع پروژه:** Full-stack؛ پنل مدیریتی وب + سرویس مرکزی VoIP/CTI - **ریشه‌های اصلی:** `cti-app/` (فرانت‌اند) و `p-line/` (بک‌اند) - **فایل محوری بررسی‌شده:** [`PlineTools.tsx`](cti-app/src/components/services/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`](cti-app/src/App.tsx) - فهرست صفحات: [`AppRoutes.tsx`](cti-app/src/components/application-components/routes/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`](cti-app/src/App.tsx): - `/login` - `/502` - `/notfound` - مسیرهای ناشناخته به `/notfound` هدایت می‌شوند. مسیرهای مدیریتی زیر `PrivateRoute` هستند. حوزه‌های موجود در [`AppRoutes.tsx`](cti-app/src/components/application-components/routes/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`](cti-app/src/components/services/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`](p-line/pom.xml)، [`application.properties`](p-line/src/main/resources/application.properties)، [`PlineApplication.java`](p-line/src/main/java/ir/peeco/pline/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`](p-line/src/main/java/ir/peeco/pline/controllers/AppControllers.java): `/app/get-version`, `/app/info`, `/app/send-code`, `/app/mobile-verify`, `/app/register` - [`ReportsControllers.java`](p-line/src/main/java/ir/peeco/pline/controllers/ReportsControllers.java): CDR، CPU، memory، disk، channel و hangup - [`SipUsersControllers.java`](p-line/src/main/java/ir/peeco/pline/controllers/SipUsersControllers.java): CRUD، import/export و عملیات گروهی - [`PlineController.java`](p-line/src/main/java/ir/peeco/pline/controllers/PlineController.java): upload با `multipart/form-data` ## 6. مرزهای امنیت و دسترسی فیلتر [`jwtAuthorizationCheck.java`](p-line/src/main/java/ir/peeco/pline/configuration/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 - endpoint: `/ws` - پیاده‌سازی: [`WebSocketConfig.java`](p-line/src/main/java/ir/peeco/pline/webSocket/WebSocketConfig.java) و [`PlineWebSocketHandler.java`](p-line/src/main/java/ir/peeco/pline/webSocket/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. نقاط ابهام برای تطبیق 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. فایل‌های مرجع - [`App.tsx`](cti-app/src/App.tsx) - [`AppRoutes.tsx`](cti-app/src/components/application-components/routes/AppRoutes.tsx) - [`PlineTools.tsx`](cti-app/src/components/services/PlineTools.tsx) - [`RequestService.ts`](cti-app/src/components/services/RequestService.ts) - [`package.json`](cti-app/package.json) - [`pom.xml`](p-line/pom.xml) - [`PlineApplication.java`](p-line/src/main/java/ir/peeco/pline/PlineApplication.java) - [`jwtAuthorizationCheck.java`](p-line/src/main/java/ir/peeco/pline/configuration/jwtAuthorizationCheck.java) - [`WebSocketConfig.java`](p-line/src/main/java/ir/peeco/pline/webSocket/WebSocketConfig.java) - [`PlineWebSocketHandler.java`](p-line/src/main/java/ir/peeco/pline/webSocket/PlineWebSocketHandler.java) - [`application.properties`](p-line/src/main/resources/application.properties) ## 13. محدودیت تحلیل این سند static analysis است. رفتار وابسته به database واقعی، reverse proxy، Asterisk، license server، متغیرهای محیطی، فایل‌های خارج از repository یا deployment runtime باید با اجرای سیستم و مستندات عملیاتی تأیید شود. تست، build، deployment topology و ارزیابی امنیتی کامل در دامنه این سند نیستند.