portal/docs/superpowers/specs/2026-05-21-project-delete-dedup-errors-design.md

# Удаление проектов вместо архива + дедуп источника + человеческие ошибки

**Дата:** 2026-05-21
**Статус:** утверждён (заказчик «ок делай»)
**Ветка исполнения:** worktree от `feat/project-migration-redesign` (origin/main)

## Контекст и проблема

Заказчик при создании проекта получил сырой `SQLSTATE[23505] Unique violation ...
projects_tenant_id_name_key` в UI. Разбор вскрыл 4 связанных задачи:

1. **Архивация бессмысленна** — если клиенту проект не нужен, хранить его незачем.
   Сейчас «удаление» (`DELETE /api/projects/{id}`) = мягкая архивация
   (`ProjectService::archive` → `archived_at`, `is_active=false`). Нужно настоящее удаление.
2. **Шеринг между клиентами** — два разных клиента могут завести проекты с одинаковыми
   параметрами/источником. Это корректно (модель шеринга: один донор раздаётся ≤3 клиентам
   через `LeadRouter`). Менять не нужно — подтвердить.
3. **Дедуп источника внутри клиента отсутствует** — один клиент может завести 2 проекта на
   один источник (номер/домен/SMS-отправитель). Нужен запрет.
4. **Утечка SQL в UI** — `Project::create()` бьётся о DB-констрейнт без перехвата → сырой
   `SQLSTATE` рендерится пользователю. Нужны человеческие сообщения.

## Ключевые факты кодовой базы (разведка)

- `deals.project_id` — **без FK** (таблица партиционирована, partition-wise FK не
  поддерживается). Hard-delete проекта НЕ каскадит и НЕ блокируется сделками → они «повиснут».
  Поэтому удаление проекта со сделками опасно → блокируем (см. Решение 1).
- `ON DELETE CASCADE` на `projects(id)` имеют только служебные таблицы:
  `project_supplier_links`, `supplier_manual_sync_queue`, `project_suppliers`,
  `project_user_assignments`, `project_limit_adjustments`. Их каскад при удалении — норма.
- Уникальность `projects` на DB-уровне: `projects_tenant_id_name_key` = `(tenant_id, name)`.
  Дедупа по источнику на DB-уровне нет.
- Источник проекта: `signal_identifier` (call=телефон `7\d{10}`, site=домен) либо
  `sms_senders[]` (+ `sms_keyword`) для sms.
- Шеринг донора: `project_supplier_links` (M:N projects↔supplier_projects) связывает
  Лидерра-проекты РАЗНЫХ тенантов с одним `supplier_project` (донором). Outbound-синк
  (`SyncSupplierProjectsJob`) считает агрегатный лимит по всем клиентам источника
  (`computeOrder = max(max, ceil(Σ/3))`, cap=3).
- Архив-ссылки (под снос): backend — `ProjectController` (destroy/index/bulk),
  `ProjectService` (archive/bulk/update/resolveBulkScope), `Project` (scopeActive/scopeArchived,
  fillable+cast `archived_at`), `ProjectResource`, `DashboardController`,
  `SyncSupplierProjectsJob`, `BulkProjectActionRequest`. Frontend — `BulkActionsBar`,
  `ProjectCard`, `ProjectDetailsDrawer`, `ProjectsView`, `projectsStore`.

## Решения (утверждены заказчиком)

### Решение 1 — удаление вместо архива, с защитой по сделкам

- `DELETE /api/projects/{id}` → **hard delete** через новый `ProjectService::delete()`.
- **Guard:** если по проекту есть хоть одна `deals` (любой статус, включая `deleted_at`-soft)
  → удаление блокируется HTTP 422 (`{errors:{...}}`/`message`, формат фронта) с сообщением:
  *«Нельзя удалить проект: по нему есть сделки. Остановите приём (пауза), чтобы скрыть из
  работы».* Пустой проект (0 сделок) → удаляется насовсем.
- Архивация убирается **полностью**: код-пути `archive`, scope `archived`, фильтр «Архивные»,
  bulk-action `archive`. Колонка `archived_at` дропается миграцией (schema bump). Пауза
  (`is_active`) сохраняется — это отдельный механизм.
- Bulk: action `archive` → `delete` (с тем же guard'ом per-project; проекты со сделками
  попадают в `skipped` с причиной, не роняют весь батч).

### Решение 2 — удаление у поставщика с учётом шеринга

При удалении Лидерра-проекта P (тенант T) по источнику X (один или несколько доноров
B1/B2/B3 через `project_supplier_links`):

1. Удаляем P локально (его `project_supplier_links` уходят каскадом).
2. Для каждого затронутого `supplier_project` S (донора источника X):
   - Считаем оставшиеся `project_supplier_links` на S (проекты ДРУГИХ тенантов).
   - **Остались** → донор нужен другим клиентам → **пере-синк** S (агрегатный лимит/регионы/дни
     без T) через outbound-синк. У поставщика проект НЕ удаляем.
   - **Не осталось** (T был последним) → у поставщика **удаляем** донора
     (`SupplierPortalClient::deleteProject(external_id)`) + удаляем локальную запись
     `supplier_projects` S.
3. Внешние вызовы к поставщику — через job (resilience, retry), не inline в HTTP-запросе.

Граничные сценарии:

- P не привязан ни к одному донору (например, синк ещё не прошёл) → шаг 2 пропускается.
- Несколько доноров (B1/B2/B3) у одного источника → шаг 2 для каждого независимо.
- Падение удаления у поставщика → job ретраит; локальное удаление P уже выполнено
  (eventual consistency; «висячий» донор у поставщика подметёт следующий синк/ретрай).

### Решение 3 — дедуп источника внутри клиента

- При создании и при изменении источника: внутри `tenant_id` источник должен быть уникален
  среди проектов клиента.
- «Источник» (source key):
  - call/site → `signal_identifier`;
  - sms → нормализованный `sms_senders` (сортировка+lower) + `sms_keyword`.
- Enforcement: app-level проверка в `ProjectService::create()`/`update()` → 422 с сообщением
  *«У вас уже есть проект с этим источником: "<название>"»*. После сноса архива «существующие
  проекты» = все проекты клиента (soft-deleted проектов нет — мы их hard-delete'им).
- DB-уровень: partial unique index как защита-эшелон (опционально, в той же миграции);
  его нарушение перехватывается общим обработчиком (Решение 4) и не утекает.

### Решение 4 — человеческие ошибки вместо SQL

- App-level pre-checks (до DB): уникальность `name` в рамках клиента + уникальность источника
  (Решение 3) → 422 `{errors: {field: [msg]}}` (формат, который уже понимает фронт).
- Глобальный перехват `Illuminate\Database\QueryException` в `bootstrap/app.php`
  (`withExceptions`): в лог — полный текст; пользователю — generic
  *«Не удалось сохранить. Проверьте данные или попробуйте ещё раз»* (HTTP 422 для JSON-запросов).
  Никакой `SQLSTATE` в UI.
- Фронт `NewProjectDialog`/`projectsStore` — убедиться, что 422 `errors`/`message`
  показываются как есть (уже умеет; правок минимум).

## Затрагиваемые компоненты

**Backend**

- `ProjectService`: +`delete()` (guard сделок + оркестрация шеринга), −`archive()`,
  bulk `archive`→`delete`, чистка `archived_at`/`archived` из update/resolveBulkScope,
  +дедуп источника в create/update.
- `ProjectController`: `destroy()` → `delete()`, index `status=archived` убрать, bulk doc.
- `BulkProjectActionRequest`: `archive`→`delete`, status `archived` убрать.
- `Project` (модель): −scopeArchived, scopeActive упростить/убрать, −`archived_at` fillable+cast.
- `ProjectResource`: −`archived_at`.
- `DashboardController`, `SyncSupplierProjectsJob`: убрать `whereNull('archived_at')`.
- Новый job `DeleteSupplierProjectJob` (или расширение существующего) — удаление донора у
  поставщика, когда источник остался без потребителей.
- Миграция: `DROP COLUMN projects.archived_at` (+ опц. partial unique index источника) →
  schema bump v8.27 + `db/CHANGELOG_schema.md`.
- `bootstrap/app.php`: глобальный handler `QueryException`.

**Frontend**

- `BulkActionsBar`: «Архивировать»→«Удалить» (+подтверждение/иконка).
- `ProjectCard`, `ProjectDetailsDrawer`: «Архивировать»→«Удалить».
- `ProjectsView`: `@archive`→`@delete`, убрать фильтр «Архивные».
- `projectsStore`: `archive()`→`delete()`, bulk `archive`→`delete`, тип `archived_at` убрать.

## Тестирование (TDD)

- Backend (Pest): delete пустого проекта → 204 + строки нет; delete со сделками → 409/422,
  проект жив; шеринг — delete последнего потребителя → донор удалён у поставщика (mock client);
  delete при оставшихся потребителях → донор НЕ удалён, пере-синк; дедуп источника create/update
  → 422; имя-дубль → 422 (не SQL); глобальный QueryException handler → generic message.
- Frontend (Vitest): кнопки «Удалить» вместо «Архивировать»; нет фильтра «Архивные»;
  store.delete дёргает DELETE; ошибка сервера показывается человеческим текстом.
- Live («проверь на практике» по каждой задаче, затем чистка тестовых данных):
  1) удаление пустого проекта + блок на проекте со сделками;
  2) два тенанта с одинаковым источником — создание проходит;
  3) попытка дубля источника у одного тенанта — отказ с понятным текстом;
  4) создание дубля имени — человеческое сообщение, не SQL.

## Вне scope (YAGNI)

- Restore/корзина удалённых проектов (удаление окончательное по решению заказчика).
- Массовая авто-чистка уже-архивированных проектов dev-БД (разовая ручная операция).
- `StatusPill 'archived'` mapping не трогаем (используется и для статусов сделок).