first

CALLBACK-CONFIG.md

@@ -0,0 +1,110 @@
+# راهنمای تنظیمات Callback AGI
+
+تمام تنظیمات اجرای برنامه در فایل
+[`src/main/resources/application.properties`](src/main/resources/application.properties)
+قرار دارد. این AGI به هیچ پارامتر خط فرمانی نیاز ندارد.
+
+## تنظیمات اصلی برنامه
+
+| پارامتر | توضیح |
+|---|---|
+| `spring.application.name` | نام برنامه Spring است. |
+| `spring.main.web-application-type` | برنامه را در حالت غیر وب اجرا می‌کند، چون این پروژه یک AGI برای Asterisk است. |
+| `debug` | حالت debug مربوط به Spring Boot را فعال یا غیرفعال می‌کند. |
+
+## تنظیمات لاگ
+
+| پارامتر | توضیح |
+|---|---|
+| `logging.level.root` | سطح پیش‌فرض لاگ‌های برنامه. |
+| `logging.level.org.springframework` | سطح لاگ Spring Framework و Spring Boot. |
+| `logging.level.org.hibernate` | سطح لاگ Hibernate و JPA. |
+| `logging.level.com.zaxxer.hikari` | سطح لاگ connection pool مربوط به HikariCP. |
+
+## تنظیمات دیتابیس و JPA
+
+| پارامتر | توضیح |
+|---|---|
+| `spring.datasource.url` | آدرس اتصال JDBC به PostgreSQL. |
+| `spring.datasource.username` | نام کاربری PostgreSQL. |
+| `spring.datasource.password` | رمز عبور PostgreSQL. |
+| `spring.datasource.hikari.maximum-pool-size` | حداکثر تعداد connectionهای موجود در pool. |
+| `spring.datasource.hikari.connection-timeout` | حداکثر زمان انتظار برای گرفتن connection از pool، برحسب میلی‌ثانیه. |
+| `spring.jpa.hibernate.ddl-auto` | نحوه مدیریت schema دیتابیس. مقدار `none` مانع تغییر schema موجود توسط Hibernate می‌شود. |
+| `spring.jpa.open-in-view` | باز نگه داشتن EntityManager در لایه وب. برای این پروژه غیرفعال است، چون برنامه وب نیست. |
+| `spring.jpa.properties.hibernate.jdbc.time_zone` | منطقه زمانی مورد استفاده JDBC و Hibernate برای timestampها. |
+
+## تنظیمات Asterisk و IVR
+
+| پارامتر | توضیح |
+|---|---|
+| `callback.agi.dial-prefix` | پیشوند کانال برای تماس با داخلی کارمند؛ مانند `PJSIP/` یا `SIP/`. |
+| `callback.agi.dial-timeout-seconds` | مدت زمان زنگ خوردن داخلی برحسب ثانیه. |
+| `callback.agi.ivr-context` | نام context مربوط به IVR اصلی در dialplan. |
+| `callback.agi.ivr-extension` | extension مقصد در context مربوط به IVR. برای تماس ورودی معمولاً `s` است. |
+| `callback.agi.ivr-priority` | priorityای که اجرای IVR از آن شروع می‌شود. |
+
+در شرایط زیر تماس به IVR منتقل می‌شود:
+
+- قابلیت callback غیرفعال باشد.
+- callback مناسبی برای مشتری پیدا نشود.
+- داخلی پاسخ ندهد.
+- در جست‌وجو یا اتصال به دیتابیس خطایی رخ دهد.
+
+مقصد IVR از ترکیب سه مقدار زیر ساخته می‌شود:
+
+```text
+callback.agi.ivr-context,callback.agi.ivr-extension,callback.agi.ivr-priority
+```
+
+با تنظیمات فعلی، مقصد تماس این است:
+
+```text
+from-trunk,s,1
+```
+
+اگر context شما مثلاً `company-ivr` است، مقدار زیر را تغییر دهید:
+
+```properties
+callback.agi.ivr-context=company-ivr
+```
+
+## تنظیمات رفتار Callback
+
+| پارامتر | توضیح |
+|---|---|
+| `callback.agi.enabled` | فعال یا غیرفعال بودن callback. اگر `false` باشد، همه تماس‌ها مستقیماً به IVR می‌روند و جدول `tbl_cdr` بررسی یا تغییر داده نمی‌شود. |
+| `callback.agi.lookback-minutes` | بازه جست‌وجوی تماس‌های خروجی ناموفق برحسب دقیقه. مقدار `60` یعنی یک ساعت. |
+| `callback.agi.claim-value` | مقدار موقت ستون `tbl_cdr.target` هنگام شروع callback. این مقدار برای قفل هم‌زمانی استفاده می‌شود. |
+| `callback.agi.done-value` | مقدار نهایی ستون `tbl_cdr.target` بعد از پاسخ داخلی. پس از آن، تماس بعدی همان مشتری به IVR می‌رود. |
+
+## نمونه تنظیمات
+
+### فعال بودن Callback برای یک ساعت گذشته
+
+```properties
+callback.agi.enabled=true
+callback.agi.lookback-minutes=60
+```
+
+### غیرفعال کردن کامل Callback
+
+```properties
+callback.agi.enabled=false
+```
+
+در این حالت تمام تماس‌ها بدون جست‌وجوی callback به IVR می‌روند.
+
+### استفاده از IVR متفاوت
+
+```properties
+callback.agi.ivr-context=my-ivr
+callback.agi.ivr-extension=s
+callback.agi.ivr-priority=1
+```
+
+### تغییر بازه جست‌وجو به ۳۰ دقیقه
+
+```properties
+callback.agi.lookback-minutes=30
+```