263 lines
18 KiB
Markdown
263 lines
18 KiB
Markdown
# 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 و ارزیابی امنیتی کامل در دامنه این سند نیستند.
|