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

263 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 و ارزیابی امنیتی کامل در دامنه این سند نیستند.