diff --git a/%D0%A2%D0%95%D0%A5%D0%9D%D0%98%D0%A7%D0%95%D0%A1%D0%9A%D0%90%D0%AF-%D0%A1%D0%9F%D0%95%D0%A6%D0%98%D0%A4%D0%98%D0%9A%D0%90%D0%A6%D0%98%D0%AF-%28FRD%29.md b/%D0%A2%D0%95%D0%A5%D0%9D%D0%98%D0%A7%D0%95%D0%A1%D0%9A%D0%90%D0%AF-%D0%A1%D0%9F%D0%95%D0%A6%D0%98%D0%A4%D0%98%D0%9A%D0%90%D0%A6%D0%98%D0%AF-%28FRD%29.md new file mode 100644 index 0000000..2f18e7b --- /dev/null +++ b/%D0%A2%D0%95%D0%A5%D0%9D%D0%98%D0%A7%D0%95%D0%A1%D0%9A%D0%90%D0%AF-%D0%A1%D0%9F%D0%95%D0%A6%D0%98%D0%A4%D0%98%D0%9A%D0%90%D0%A6%D0%98%D0%AF-%28FRD%29.md @@ -0,0 +1,169 @@ +# ТЕХНИЧЕСКАЯ СПЕЦИФИКАЦИЯ (FRD) +**Проект:** Система управления юридическими процессами (Банкротство) +**Стек:** Node.js, Express, MongoDB (Mongoose), node-cron | Vue 3, PrimeVue (PrimeUI) + +--- + +## НАПРАВЛЕНИЕ 1. Ядро системы (Скелет, Сущности, RBAC) + +### 1.1. Модель данных (Mongoose Schemas) +В MongoDB мы используем вложенность там, где данные всегда читаются вместе, и ссылки (`ObjectId`), где данные имеют самостоятельную жизнь. + +* **User (Пользователи)** + * `email` (String, unique) + * `passwordHash` (String) + * `role` (Enum: 'admin', 'manager', 'lawyer') + * `permissions` (Array of Strings) - для гибкого RBAC. + * `settings` (Object) - настройки уведомлений, токены интеграций (Яндекс.Диск). +* **Debtor (Должник)** + * `fullName` / `companyName` (String) + * `inn`, `snils`, `passport` (String) + * `financialData` (Object) - гибкая структура для активов, счетов, доходов. + * `addresses` (Array of Objects) - ФИАС адреса. +* **Process (Процедура/Дело)** + * `debtorId` (ObjectId -> Debtor) + * `assignedLawyers` (Array of ObjectId -> User) + * `courtCaseNumber` (String, unique) - номер дела (А56-1529/2023). + * `status` (Enum: 'active', 'completed', 'archived') + * `currentStageId` (ObjectId -> Stage) + * `metadata` (Object) - специфичные поля (дата введения, номер в ЕФРСБ и т.д.). + +### 1.2. Архитектура и API (Backend) +* **Auth Middleware:** JWT-токены. Проверка ролей через кастомный middleware `checkRole(['admin', 'manager'])`. +* **API Endpoints:** + * `POST /api/auth/login`, `POST /api/auth/register` + * `CRUD /api/debtors` + * `CRUD /api/processes` +* **Data Isolation:** В Express middleware для ролей 'lawyer' принудительно добавляется фильтр `{ assignedLawyers: req.user.id }` ко всем запросам к `Process`. + +### 1.3. Frontend (Vue 3 + PrimeVue) +* **Layout:** `AppShell.vue` с боковым меню (`p-menu` или `p-sidebar`) и хедером с профилем. +* **Роутинг:** Vue Router с навигационными гардами (`beforeEach`) для проверки прав доступа. +* **Компоненты:** + * Таблицы сущностей: `p-datatable` с пагинацией, сортировкой и фильтрацией. + * Формы создания: `p-dialog` (модальные окна) с `p-form` и валидацией через `VeeValidate` + `Zod/Yup`. + +--- + +## НАПРАВЛЕНИЕ 2. Управление задачами и Автоматизация + +### 2.1. Модель данных +* **StageTemplate (Этап - шаблон для админа)** + * `name`, `order` (Number), `defaultDurationDays` (Number). +* **TaskTemplate (Тип задачи - шаблон)** + * `name`, `description`, `defaultDurationDays`, `stageTemplateId`. + * `triggers` (Array) - *см. пункт 2.2*. +* **Task (Инстанс задачи у юриста)** + * `processId`, `stageId`, `templateId`. + * `assigneeId` (ObjectId -> User). + * `status` (Enum: 'todo', 'in_progress', 'done', 'overdue'). + * `deadline` (Date). + * `report` (Object: { text, completedAt, completedBy, attachments }). + +### 2.2. Логика Автоматизации (Event-Driven) +Чтобы одна задача порождала другую, используем паттерн "Наблюдатель" или триггеры в БД. +* **Механика:** В `TaskTemplate` добавляется поле `onCompleteTriggers`: массив объектов `{ targetTaskTemplateId, delayDays }`. +* **Backend Logic:** При `PATCH /api/tasks/:id` (смена статуса на 'done'): + 1. Сохраняем отчет. + 2. Находим `TaskTemplate` текущей задачи. + 3. Если есть `onCompleteTriggers`, создаем новые инстансы `Task` с расчетом `deadline = now + delayDays`. +* **Cron (node-cron):** Задача `checkDeadlines` запускается раз в сутки (или раз в час). Ищет задачи со статусом `todo`/`in_progress`, где `deadline < now`, и меняет статус на `overdue`. Отправляет событие в шину уведомлений. + +### 2.3. Frontend (3 интерфейса) +1. **Проджект-менеджер (Внутри Процесса):** + * Используется `p-accordion` или `p-tree` для группировки задач по Этапам. + * Прогресс-бар этапа: `p-progressbar`. + * Чекбокс задачи: `p-checkbox`. При клике открывается `p-dialog` для ввода отчета. +2. **Таск-менеджер (Глобальный):** + * `p-datatable` с глобальным списком всех задач пользователя. + * Фильтры: `p-dropdown` (Статус, Тип), `p-calendar` (Дедлайн). +3. **Календарь:** + * Используется `p-calendar` (в режиме view="month" / "week") или кастомная интеграция с FullCalendar.js (если PrimeVue не даст нужного UX), но для MVP подойдет `p-schedule` (если есть в PrimeVue) или стандартный `p-dataview` с группировкой по датам. + +--- + +## НАПРАВЛЕНИЕ 3. Загрузка, хранение и парсинг документов + +### 3.1. Модель данных и Хранение +* **Document** + * `processId`, `type` (Enum: 'bank_statement', 'court_act', 'contract', 'other'). + * `fileName`, `mimeType`, `size`. + * `storagePath` (путь в локальной ФС или ключ в облаке). + * `parsedData` (Object) - результаты парсинга. +* **Storage Adapter Pattern:** На бэкенде создаем абстрактный класс `Storage`, и реализации `LocalStorage`, `YandexDiskStorage`. Выбор через конфиг. + +### 3.2. Парсинг и Триггеры (Background Jobs) +Загрузка файла не должна блокировать HTTP-запрос. +1. **API:** `POST /api/documents/upload`. Принимает `multipart/form-data`. Сохраняет метаданные в Mongo, файл на диск. Возвращает 202 Accepted. +2. **Worker (Cron/Queue):** Фоновый процесс забирает новые документы. + * *Если тип `bank_statement` (CSV):* Парсим CSV (библиотека `csv-parser`). Создаем записи в коллекции `FinancialTransaction`. Создаем задачу "Провести анализ подозрительных операций". + * *Если тип `court_act` (PDF):* (Для MVP) просто сохраняем. В будущем можно подключить OCR/NLP для извлечения даты и номера дела. + +### 3.3. Frontend +* **Загрузка:** `p-fileupload` (режим advanced). Drag-and-drop зона. +* **Метаданные:** Перед отправкой файла модальное окно с `p-dropdown` для выбора "Типа документа" и привязки к "Процессу" (если загрузка идет из общего раздела). +* **Просмотр:** `p-datatable` со списком документов. Кнопка "Скачать" генерирует presigned URL или стримит файл через Express. + +--- + +## НАПРАВЛЕНИЕ 4. Шаблонизатор создания документов + +### 4.1. Выбор инструмента (Backend) +Для генерации DOCX из шаблонов в Node.js идеальным решением является связка **`pizzip`** (для распаковки zip/docx) + **`docxtemplater`** (для замены тегов). +* *Альтернатива:* `docx` (создание с нуля), но она не подходит для шаблонов с версткой. + +### 4.2. Модель данных +* **DocumentTemplate** + * `name`, `category` (например, "Для суда", "Для должников"). + * `fileBuffer` (Binary) или путь к файлу. + * `variables` (Array of Strings) - список тегов, найденных в документе (например, `{{Должник.ФИО}}`, `{{Процесс.НомерДела}}`). + +### 4.3. Логика работы (Backend) +1. **Загрузка шаблона (Админ):** Админ загружает `.docx`. Бэкенд с помощью `docxtemplater` сканирует файл, находит все теги `{{...}}` и сохраняет их в массив `variables`. +2. **Генерация (Юрист):** + * Юрист выбирает шаблон. + * Бэкенд собирает контекст (Context Object): подтягивает данные из `Process`, `Debtor`, `User` и маппит их на теги шаблона. + * `docxtemplater` рендерит файл. + * Если выбрано несколько шаблонов, используется `archiver` (npm пакет) для создания ZIP-архива на лету. + * Файл отдается клиенту через `res.download()`. + +### 4.4. Frontend +* **Админ-панель:** + * `p-fileupload` для загрузки `.docx`. + * После загрузки отображается `p-chips` или `p-listbox` с найденными переменными, чтобы админ мог проверить, все ли теги распознаны. +* **Интерфейс юриста:** + * Список шаблонов: `p-dataview` с карточками или `p-datatable`. + * Чекбоксы для множественного выбора. + * Кнопка "Сгенерировать и скачать". Во время генерации показывается `p-progressbar` (indeterminate) или `p-blockui`. + +--- + +## Скрытые требования и Архитектурные решения (Non-Functional) + +1. **Уведомления (Email & Push):** + * *Backend:* Используем `nodemailer` для Email. Для Push (внутри PWA) используем `web-push` (VAPID keys). + * *Cron:* Задача `sendDailyDigest` раз в сутки собирает все непрочитанные уведомления и шлет дайджест на почту. +2. **Интеграции (КАД, ЕГРЮЛ, Яндекс.Диск):** + * Выносим в отдельный модуль `integrations/`. + * Обязательно используем паттерн **Retry with Exponential Backoff** (библиотека `axios-retry`), так как гос. API часто лежат или отдают 503. + * Кэширование ответов ЕГРЮЛ/ФИАС в Redis (если появится в стеке) или в коллекции MongoDB с TTL (Time To Live), чтобы не платить за лишние запросы к DaData. +3. **PWA (Progressive Web App):** + * На фронтенде используем `vite-plugin-pwa`. + * Настраиваем `manifest.json` и Service Worker для оффлайн-кэширования статики (но не API-запросов, так как данные должны быть свежими). + +--- + +## План передачи в разработку (Next Steps) + +1. **Для Backend-разработчика:** + * Инициализировать репозиторий. + * Написать миграции/сиды для Mongoose (создать базовые роли, этапы и типы задач). + * Реализовать модуль Auth и RBAC middleware. +2. **Для Frontend-разработчика:** + * Поднять Vue 3 + Vite + PrimeVue. + * Настроить Axios interceptor для обработки JWT и глобальных ошибок. + * Сверстать `AppShell` и базовые роуты. +3. **Совместно:** + * Согласовать Swagger/OpenAPI спецификацию (можно использовать `tsoa` или `swagger-jsdoc` в Express). + +*Данный документ является достаточным основанием для спринта №1 (Архитектура и Ядро) и содержит четкие векторы для спринтов №2, №3 и №4.* \ No newline at end of file