22. Модуль обращений и корреспонденции

Date: 2026-02-25

Status

Proposed

Context

В Narmak отсутствует модуль учёта входящей и исходящей корреспонденции. Требуется система для:

• Регистрации обращений (входящих/исходящих) с различными источниками (email, почта, порталы, ФНС и др.)
• Контроля сроков ответа: 5 дней — обычные, 3 дня — срочные
• Отслеживания движения обращений по отделам
• Связи с контрагентами и юридическим досье (legal_dossier)

Существующие модули: legal_dossier, company_structure (Department), tasks, counterparty.

Decision

1. Отдельное Django-приложение appeals

Создать новое приложение вместо расширения существующих моделей. Обоснование: независимый жизненный цикл, отдельные права доступа, масштабируемость.

2. Конфигурируемая схема по типам обращений

Типы обращений — справочник (AppealType). Каждый тип имеет свой набор полей через AppealTypeField. Значения специфичных полей хранятся в Appeal.extra_data (JSONField).

Структура:

AppealType (справочник типов)
├── AppealTypeField (поля типа: key, field_type, label, is_required, choices, ...)
└── Appeal.extra_data — JSON со значениями

Альтернатива (отвергнута): Один formlyJsonschema на AppealType без AppealTypeField — хуже для валидации на бэкенде и отчётов по полям.

3. Справочники

• AppealSource — источник (email, post, portal_gosuslugi, portal_fns, personal_visit, phone, internal, other), флаг is_fns для аналитики
• AppealPriority — приоритет (regular 5 дн., urgent 3 дн.), response_deadline_days
• AppealFieldType — типы полей (string, text, number, date, select, counterparty, contract, user, department, file_ref)
• AppealType — типы обращений (Запрос ФНС, Жалоба, Претензия и т.д.), default_priority, опционально response_deadline_days

4. Основная модель Appeal

Ключевые поля: number (ВХ-00001/ИСХ-00001), direction, registration_date, source, appeal_type, priority, subject, description, counter_party, contract, legal_conclusion, response_deadline, status, registered_by, current_department, executor, parent_appeal (связь вх.↔исх.), extra_data, files (GenericRelation).

Статусы: registered → in_department → in_progress → response_ready → completed; overdue — вычисляемый при просрочке.

5. Журнал движения AppealWorkflowLog

Запись каждого действия: received, assigned, transferred, completed. Поля: appeal, from_department, to_department, from_user, to_user, action, comment, created_at.

6. API

• GET /api/appeals/types/{id}/form-schema/ — схема формы по типу (для динамической формы)
• CRUD обращений с валидацией extra_data по AppealTypeField
• Фильтры: источник, отдел, статус, приоритет, ФНС, контрагент, тип
• Action transfer — передача по отделам

7. Интеграция с legal_dossier

Поле legal_conclusion в Appeal. В карточке LegalConclusion — блок «Связанные обращения». Использование существующего LegalConclusionPDFService при необходимости.

8. Дополнительные фичи (приоритизированы)

Этап 2: Шаблоны ответов, эскалация при просрочке, дашборд, экспорт Excel, журнал событий.

Этап 3: Связь с задачами (tasks), цепочка переписки, сохранённые фильтры, массовые операции, передоверие.

Этап 4: Проверка дубликатов, версионирование (AppealVersion), бизнес-календарь, KPI-отчёты.

Альтернативы

Вариант	Решение
Расширить legal_dossier	Отвергнуто — обращения шире, чем проверка контрагентов
JSONField для всех полей без AppealTypeField	Отвергнуто — нужна валидация и отчёты по полям
Отдельный микросервис	Отвергнуто — избыточно для MVP, проще в монолите

Consequences

• (+) Гибкая конфигурация типов обращений без миграций
• (+) Валидация extra_data на бэкенде
• (+) Полный аудит движения по AppealWorkflowLog
• (+) Связь с legal_dossier и tasks
• (-) Дополнительное приложение, новые таблицы
• (-) Необходимость периодической задачи для статуса overdue

Связанные документы

• План: .cursor/plans/модуль_обращений_и_корреспонденции_e7782a9e.plan.md
• Аналогичный паттерн: app/manufacture/models/workactivity.py (WorkActivityType + ExtraJsonField)
• Legal dossier ADR: 0006–0015