crm.clientright.ru/erv_ticket/SYSTEM_DOCUMENTATION.md

# Документация системы ERV Ticket

## 📋 Общее описание

Это веб-приложение для приёма обращений за страховыми выплатами от клиентов ERV (Европейская страховая компания). Система собирает данные клиентов, проверяет полисы в базе данных, загружает документы и отправляет всё в CRM Vtiger.

---

## 🏗️ Архитектура системы

### Основные компоненты:

1. **Frontend (index.php)**
   - Многошаговая форма (3 шага)
   - SMS-верификация
   - Валидация данных
   - Загрузка файлов
   
2. **Backend**
   - `server.php` - обработка и отправка данных в CRM
   - `database.php` - проверка полисов в БД
   - `fileupload.php` - загрузка и обработка файлов
   - `sms-test.php` - отправка SMS кодов

3. **JavaScript (common.js)**
   - Логика работы формы
   - Валидация полей
   - Загрузка файлов
   - AJAX-запросы

---

## 📊 Процесс работы (Flow)

### Шаг 0: SMS-верификация
1. Пользователь вводит номер телефона
2. Система генерирует 6-значный код
3. Отправляет SMS через SigmaSMS API
4. Пользователь вводит код подтверждения
5. При совпадении открывается доступ к форме

### Шаг 1: Проверка полиса и персональные данные
1. **Проверка полиса в БД**:
   - Пользователь вводит номер полиса (формат: `A123-456789` или `E123-456789`)
   - AJAX запрос в `database.php`
   - Поиск в таблице `ci20465_erv.lexrpiority` по полю `voucher`
   - Если найден → автоподстановка дат страхования, скрытие поля загрузки полиса
   - Если не найден → требуется загрузить скан полиса

2. **Персональные данные**:
   - ФИО (фамилия, имя, отчество)
   - Дата рождения (с проверкой возраста для несовершеннолетних)
   - Банковские реквизиты (БИК, корр.счет, расчетный счет)
   - ФИО получателя
   - Документы законного представителя (если < 18 лет)

### Шаг 2: Описание события
1. **Тип события** (select):
   - Задержка авиарейса (> 3 часов)
   - Отмена авиарейса
   - Пропуск стыковочного рейса
   - Посадка на запасной аэродром
   - Задержка поезда
   - Отмена поезда
   - Задержка/отмена парома

2. **Динамические поля** (зависят от типа):
   - Для стыковочного рейса: дополнительно номер рейса отправления + дата
   - Для отмены рейса: подтверждение от авиакомпании

3. **Общие поля**:
   - Дата наступления страхового случая
   - Номер рейса/поезда/парома
   - Описание ситуации (textarea)
   - Подтверждающие документы (посадочный талон, билеты)

### Шаг 3: Документы и согласия
1. Адрес регистрации
2. ИНН (скрыт, заполняется автоматически значением `000000000000`)
3. Код документа (паспорт РФ, военный билет и т.д.)
4. Серия и номер документа
5. Страна события (выбор из списка)
6. Email
7. Скан документа, удостоверяющего личность
8. Согласие с политикой обработки персональных данных

### Финальная отправка
1. Все файлы загружаются на `https://form.clientright.ru/fileupload_v2.php`
2. Формируется JSON с данными форм (клиент, контрагент, проект, другие поля)
3. Отправка на `https://form.clientright.ru/server_webservice2.php`
4. Email-уведомление на `help@clientright.ru` и `ftpl@yandex.ru`
5. Редирект на `https://lexpriority.ru/ok`

---

## 🗄️ База данных

### Подключение:
```php
Host: localhost
Database: ci20465_erv
User: ci20465_erv
Password: c7vOXbmG
Table: lexrpiority
```

### Структура таблицы (предполагаемая):
```sql
lexrpiority:
  - voucher (номер полиса) - VARCHAR
  - insured_from (дата начала страхования) - DATE
  - insured_to (дата окончания страхования) - DATE
  - ... другие поля
```

---

## 📤 API интеграции

### 1. SigmaSMS API
**Файл**: `sms-test.php`
```
Endpoint: https://online.sigmasms.ru/api/
Login: kfv.advokat@gmail.com
Password: s7NRIb
Token: 27f89492e00973263ff746a655663678fae7203bac8b62919700e489e33b3902
```

### 2. Vtiger CRM Webforms
**Endpoint**: `https://crm.clientright.ru/modules/Webforms/capture.php`

**Параметры**:
- `__vtrftk`: session token
- `publicid`: форма ID
- `name`: 'websiteticket'
- Поля клиента (lastname, firstname, email, phone и т.д.)
- Поля контрагента (inn, ogrn, accountname, address и т.д.)
- Кастомные поля (cf_XXXX)
- Файлы (вложения)

### 3. DaData API
**Используется для**: автозаполнения реквизитов организации
```
Endpoint: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/party
Token: f5d6928d7490cd44124ccae11a08c7fa5625d48c
```

---

## 📁 Загрузка файлов

### Процесс:
1. **Валидация на клиенте**:
   - Максимум 10 файлов
   - Форматы: `.pdf`, `.jpg`, `.png`, `.gif`, `.jpeg`
   - Размер: до 5 МБ каждый

2. **Загрузка** (`fileupload.php` или удаленный `fileupload_v2.php`):
   - Конвертация изображений в PDF (через ImageMagick `convert`)
   - Объединение всех PDF в один файл (через Ghostscript `gs`)
   - Формат имени: `{translit(docname)}_{дата}_{translit(lastname)}_{страниц}_CTP.pdf`

3. **Сохранение**:
   - Временно в папке `uploads/`
   - После отправки формы - очистка папки

### Защита:
- Запрещены исполняемые файлы (.php, .exe, .js и т.д.)
- Замена опасных символов в именах
- Проверка через `is_uploaded_file()`

---

## 🎨 Frontend технологии

### Библиотеки:
- **jQuery 3.6.3** - DOM манипуляции
- **InputMask** - маски ввода (телефон, ИНН, БИК, даты)
- **Datepicker** - календарь выбора дат
- **intlTelInput** - международные телефонные номера
- **Fancybox** - модальные окна (SMS подтверждение, успех)
- **heic2any** - конвертация HEIC изображений

### Маски ввода:
```javascript
Телефон:     999 999-99-99
ИНН:         999999999999 (12 цифр)
БИК:         999999999 (9 цифр)
Расч. счет:  99999999999999999999 (20 цифр)
Корр. счет:  99999999999999999999 (20 цифр)
Дата:        99-99-9999
SMS код:     999999 (6 цифр)
Полис:       A9{3,5}-*{6,10} (например: A123-456789)
```

---

## 🔐 Безопасность

### Проблемы текущей реализации:
⚠️ **КРИТИЧНЫЕ**:
1. Пароли и токены в открытом виде в коде
2. `shell_exec()` и `exec()` без экранирования
3. SQL-запросы без prepared statements
4. Отсутствие CSRF защиты
5. Email-адреса в открытом виде

⚠️ **ВАЖНЫЕ**:
1. Нет rate limiting на SMS
2. Отсутствует логирование действий
3. Нет проверки подлинности сессии
4. Файлы сохраняются в веб-доступной папке

---

## 📋 Маппинг полей в CRM

### Клиент (client):
- `lastname` - Фамилия
- `firstname` - Имя
- `secondname` - Отчество
- `birthday` - Дата рождения
- `mobile` - Телефон
- `email` - Email
- `mailingstreet` - Адрес регистрации
- `inn` - ИНН

### Контрагент (contractor):
- `accountname` - "Филиал ООО РСО ЕВРОИНС Туристическое"
- `inn` - 7714312079
- `ogrn` - 1037714037426
- `address` - Адрес офиса
- `email` - info@erv.ru
- `phone` - 84956265800
- `website` - https://www.erv.ru/

### Кастомные поля:
- `cf_1885` - Номер полиса
- `cf_1887` - Дата начала страхования
- `cf_1889` - Дата окончания страхования
- `cf_1899` - Код документа
- `cf_1802` - Серия документа
- `cf_1804` - Номер документа
- `cf_1909` - Страна события
- `cf_1945` - ФИО получателя
- `cf_1265` - Банк
- `cf_1267` - БИК
- `cf_1271` - Корр. счет
- `cf_1269` - Расчетный счет
- `cf_1273` - Иные реквизиты
- `cf_1726` - Тип события
- `cf_2566` - Дата наступления страхового случая
- `cf_2568` - Номер транспорта
- `cf_2206` - SMS код
- `cf_2446` - Флаг проверки полиса в БД (1/0)
- `cf_2502` - Согласие с политикой

---

## 🔄 Логика валидации

### JavaScript валидация (common.js):

1. **Обязательные поля**:
   - Все `input[type="text"]`, `input[type="email"]`, `textarea` без класса `.notvalidate`
   - Исключаются поля с классом `.disabled`

2. **Email**:
   - Регулярное выражение RFC-совместимое

3. **Даты**:
   - Максимальная дата = сегодня (нельзя выбрать будущее)
   - Для дат рождения - расчет возраста

4. **Файлы**:
   - Форматы через расширение
   - Размер через `file.size`

5. **Динамическая логика**:
   - Возраст < 18 → показать поля законного представителя
   - Тип события = стыковочный рейс → показать доп. поля
   - Тип события = отмена рейса → показать поле подтверждения от АК

---

## 🚀 Точки входа и выхода

### Точки входа:
1. `index.php` - главная страница формы
2. `database.php?action=user_verify` - AJAX проверка полиса
3. `sms-test.php` - AJAX отправка SMS
4. `fileupload.php` или внешний `fileupload_v2.php` - загрузка файлов

### Точки выхода:
1. `https://form.clientright.ru/server_webservice2.php` - отправка данных
2. `https://lexpriority.ru/ok` - редирект после успеха
3. Email-уведомления на `help@clientright.ru` и `ftpl@yandex.ru`

---

## 🐛 Известные баги и особенности

1. **Двойная загрузка jQuery** (строки 17 и 18 в index.php)
2. **Жестко закодированные значения**:
   - ИНН = "000000000000" (скрытое поле)
   - Направление = "ЕРВ Средства размещения"
   - Данные контрагента

3. **Закомментированный код**:
   - Гражданство (огромный select с кодами стран)
   - Серия документа (отдельное поле)
   - Описание проблемы на шаге 3

4. **Таймауты в редиректе**:
   - 30ms - слишком быстро, пользователь не увидит модалку успеха

5. **Отладочный режим**:
   - `?demodata=1` - автозаполнение формы тестовыми данными

---

## 📞 Контакты и доступы

### Email:
- Получатели уведомлений: `help@clientright.ru`, `ftpl@yandex.ru`
- SMTP отправитель: `ask@fvkorobkov.ru` (пароль: G59UQwYaSl)

### SMS:
- Провайдер: SigmaSMS
- Sender: "Clientright"

### База данных:
- Host: localhost (141.8.194.131 - закомментирован)
- База: ci20465_erv
- Пользователь: ci20465_erv
- Пароль: c7vOXbmG

---

## 📝 Заметки для разработчика

### Что можно улучшить:
1. ✅ Вынести все credentials в `.env`
2. ✅ Использовать prepared statements для SQL
3. ✅ Добавить CSRF токены
4. ✅ Логирование всех операций
5. ✅ Rate limiting на SMS
6. ✅ Хранить файлы вне webroot
7. ✅ Версионирование API запросов
8. ✅ Улучшить обработку ошибок
9. ✅ Добавить unit-тесты
10. ✅ Документировать API endpoints

### Зависимости (composer):
```json
{
  "phpmailer/phpmailer": "для отправки email",
  "setasign/*": "работа с PDF",
  "clegginabox/*": "неизвестная библиотека"
}
```

---

Документация обновлена: **23.10.2025**