crm.clientright.ru/CREATE_WEB_PROJECT_DOCS.md

# CreateWebProject - Документация

**Дата создания:** 01.11.2025  
**Автор:** Фёдор  
**Статус:** ✅ Работает и протестировано

---

## 📋 Назначение

Операция vTiger webservice для создания проекта из web-формы ERV.

**Логика работы:**
- Если проект с таким номером полиса **существует** → возвращает ID **БЕЗ обновления**
- Если проект **не существует** → создаёт новый

По аналогии с `CreateWebContact`.

---

## 🔧 Параметры

### Обязательные:
1. **policy_number** (String) - Номер полиса ERV (cf_1885)
   - Пример: `E1000-123456789`
   
2. **contact_id** (String) - ID контакта для привязки
   - Пример: `396625`
   - Получается из `CreateWebContact` на шаге 1

### Опциональные:
3. **period_start** (String) - Дата начала страхования (cf_1887)
   - Формат: `DD-MM-YYYY`
   - Пример: `01-01-2025`

4. **period_end** (String) - Дата окончания страхования (cf_1889)
   - Формат: `DD-MM-YYYY`
   - Пример: `31-12-2025`

---

## 📥 Пример запроса

```bash
curl -X POST "https://crm.clientright.ru/webservice.php" \
  -d "operation=CreateWebProject" \
  -d "sessionName={token от login}" \
  -d "policy_number=E1000-123456789" \
  -d "contact_id=396625" \
  -d "period_start=01-01-2025" \
  -d "period_end=31-12-2025"
```

---

## 📤 Пример ответа

### Новый проект (создан):
```json
{
  "success": true,
  "result": "{\"project_id\":\"396865\",\"is_new\":true}"
}
```

### Существующий проект (найден):
```json
{
  "success": true,
  "result": "{\"project_id\":\"396865\",\"is_new\":false}"
}
```

**Важно:** `result` - это JSON-строка, требует `JSON.parse()`!

---

## 🏗️ Создаваемые поля проекта

При создании нового проекта заполняются:

| Поле | Значение | Примечание |
|------|----------|------------|
| `projectname` | `ERV {полис} цифровой адвокат` | Например: "ERV E1000-123456789 цифровой адвокат" |
| `projectstatus` | `модерация` | Статус |
| `projecttype` | `ерв урегулирование` | Тип проекта |
| `linktoaccountscontacts` | `12x{contact_id}` | Привязка к контакту |
| `cf_1994` | `11x67458` | Заявитель (контрагент) |
| `cf_1885` | `{policy_number}` | Номер полиса ⭐ |
| `cf_1887` | `{period_start}` | Период начала (опционально) |
| `cf_1889` | `{period_end}` | Период конца (опционально) |
| `assigned_user_id` | Текущий API user | Ответственный |

---

## 🔍 Логика поиска

Проект ищется в БД по запросу:

```sql
SELECT p.projectid
FROM vtiger_project p
INNER JOIN vtiger_projectcf pcf ON p.projectid = pcf.projectid
LEFT JOIN vtiger_crmentity e ON e.crmid = p.projectid  
WHERE e.deleted = 0 AND pcf.cf_1885 = '{policy_number}'
LIMIT 1
```

**Поиск по:** `cf_1885` (номер полиса)

---

## 📁 Файлы

- **Handler:** `include/Webservices/CreateWebProject.php`
- **Handler Method:** `vtws_createwebproject`
- **Логи:** `logs/CreateWebProject.log`

---

## 🗄️ Регистрация в БД

### vtiger_ws_operation:
```
operationid: 51
name: CreateWebProject
handler_path: include/Webservices/CreateWebProject.php
handler_method: vtws_createwebproject
type: POST
prelogin: 0
```

### vtiger_ws_operation_parameters:
```
1. policy_number (String)
2. contact_id (String)
3. period_start (String)
4. period_end (String)
```

---

## ✅ Тестирование

### Тест 1: Создание нового проекта
```
Полис: E1000-TEST-1761990646
Contact: 396625
Результат: {"project_id":"396865","is_new":true}
Статус: ✅ Создан
```

### Тест 2: Повторный вызов с тем же полисом
```
Полис: E1000-TEST-1761990646
Contact: 396625
Результат: {"project_id":"396865","is_new":false}
Статус: ✅ Найден существующий (НЕ создан дубликат!)
```

---

## 🔗 Интеграция с n8n

### Workflow флоу (планируется):

```
1. Step1Phone → CreateWebContact
   ↓ contact_id
   
2. Step2Policy → Проверка полиса
   ↓ policy_number, period_start, period_end
   
3. n8n → CreateWebProject
   POST https://crm.clientright.ru/webservice.php
   {
     operation: CreateWebProject,
     sessionName: {token},
     policy_number: "E1000-123456789",
     contact_id: "396625",
     period_start: "01-01-2025",
     period_end: "31-12-2025"
   }
   ↓
   
4. Response → {"project_id": "396865", "is_new": false}
   ↓
   
5. Redis session update:
   claim:{claim_id} += {
     project_id: "396865",
     is_new_project: false
   }
```

---

## 📊 Связь с CreateWebContact

| Операция | Ищет по | Создаёт если | Возвращает |
|----------|---------|--------------|------------|
| `CreateWebContact` | `mobile` (телефон) | Не найден контакт | `{contact_id, is_new}` |
| `CreateWebProject` | `cf_1885` (полис) | Не найден проект | `{project_id, is_new}` |

**Флоу:** Телефон → Контакт → Полис → Проект → Тип события → Документы → Тикет

---

## 🐛 Troubleshooting

### Ошибка: "Unknown operation requested"
**Причина:** Операция не зарегистрирована в БД.  
**Решение:** Запустить `register_CreateWebProject_fixed.php` (уже выполнено).

### Ошибка: BOM символ в ответе
**Причина:** Файл CreateWebProject.php сохранён с UTF-8 BOM.  
**Решение:** `sed -i '1s/^\xEF\xBB\xBF//' include/Webservices/CreateWebProject.php` (уже выполнено).

### Проект создаётся дубликатом
**Причина:** Номер полиса отличается (пробелы, регистр).  
**Решение:** В коде есть `trim()`, но нет приведения к верхнему регистру. Если нужно - добавить.

---

## 📝 История изменений

**01.11.2025:**
- ✅ Создан файл CreateWebProject.php
- ✅ Зарегистрирован в БД (operationid: 51)
- ✅ Протестирован (создание + поиск)
- ✅ Закоммичен в master (af802149)

---

**Готово к использованию!** 🎉