Добавить ТЕХНИЧЕСКАЯ СПЕЦИФИКАЦИЯ (FRD)
@@ -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.*
|
||||||
Reference in New Issue
Block a user