# ТЗ: Модуль Документация

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

- [План реорганизации](plan.md)
- [Карта нового меню](menu.md)
- [Исходное ТЗ](source-tz.md)

## 1. Назначение

Модуль `Документация` предназначен для централизованного хранения общих документов платформы Manager 2.0.

Типовые документы:

- инструкции;
- прайсы;
- регламенты;
- шаблоны;
- технические файлы;
- прочая документация.

## 2. Статус

Статус модуля: **нужно реализовать**.

Модуль должен быть доступен из верхнего меню `Документация`.

## 3. Место в меню

Целевое меню:

```text
Документация
```

Требования:

- добавить верхний пункт `Документация`;
- пункт меню доступен всем авторизованным пользователям;
- выбранный год в CRM не влияет на отображение и документы модуля;
- внутри раздела отображается дерево папок и список документов выбранной папки.

## 4. Структура папок

Папки должны отображаться деревом.

Требования:

- поддерживается вложенность папок;
- корневые папки может создавать только администратор;
- подпапки может создавать пользователь, у которого есть право записи на родительскую папку;
- при создании подпапки права доступа наследуются от родительской папки;
- права подпапки можно изменить отдельно, если у пользователя есть право управления/записи для этой папки;
- папку можно переименовать при наличии права записи;
- папку можно удалить при наличии права записи;
- удаление папки должно учитывать вложенные папки, документы и версии документов.

## 5. Документы

Документ хранится внутри папки.

Функционал:

- загрузка документа;
- скачивание документа;
- переименование документа;
- удаление документа;
- загрузка новой версии документа;
- просмотр списка версий;
- скачивание любой доступной версии;
- полное удаление отдельной версии;
- полное удаление всех версий при удалении документа;
- отображение даты загрузки;
- отображение автора загрузки;
- поиск по названию документа.

Пользователь может создавать документы в папке, если у него есть право записи на эту папку.

## 6. Версионность

Для документов должна быть предусмотрена версионность.

Требования:

- первая загрузка файла создает версию `1`;
- загрузка новой версии увеличивает номер версии;
- у документа есть текущая активная версия;
- пользователь может скачать текущую версию;
- пользователь может открыть список предыдущих версий;
- пользователь с правом записи может загрузить новую версию;
- пользователь с правом записи может полностью удалить отдельную версию;
- при полном удалении версии удаляются и метаданные версии, и физический файл;
- если удаляется текущая версия, система должна назначить текущей последнюю оставшуюся версию;
- если удалены все версии документа, документ считается удаленным;
- при удалении документа удаляются все его версии.

## 7. Права доступа

Читать общедоступную документацию могут все авторизованные пользователи.

Управление доступом задается на уровне папки. Документы внутри папки наследуют права папки, если для документа не задано отдельное правило.

### 7.1 Администратор

Администратор:

- создает корневые папки;
- видит все папки и документы;
- может назначать права чтения и записи;
- может создавать, редактировать и удалять папки и документы;
- может удалять версии документов.

### 7.2 Права на папку

На папку назначаются права:

- чтение;
- запись.

Право чтения дает возможность:

- видеть папку в дереве;
- видеть документы внутри папки;
- скачивать доступные документы и версии.

Право записи дает возможность:

- создавать подпапки;
- создавать документы;
- загружать новые версии документов;
- переименовывать папки и документы;
- удалять папки, документы и версии;
- изменять права дочерних объектов, если это разрешено общей моделью управления.

### 7.3 Субъекты доступа

Права чтения и записи могут назначаться:

| Субъект | Описание |
|---|---|
| Все | Все авторизованные пользователи. |
| Роль | Все пользователи выбранной роли. |
| Пользователь | Конкретный пользователь. |

Пример: папку могут читать роль `Администратор` и пользователь `Иванов`.

### 7.4 Наследование

Требования:

- подпапка при создании наследует права родительской папки;
- документ при создании наследует права папки;
- если права на дочерний объект не переопределены, используются права родителя;
- если права переопределены, дочерний объект использует собственные настройки;
- пользователь с правом записи на папку может создавать подпапки и документы в этой папке.

## 8. Permission-модель

Целевые системные права:

- `documents.view` — вход в раздел документации;
- `documents.update` — административное управление документацией, включая создание корневых папок и настройку прав.

Администратор имеет все права по умолчанию.

Права чтения/записи на конкретные папки и документы хранятся отдельно от системных permissions.

## 9. Хранение

Требования:

- использовать текущий файловый механизм проекта;
- физические файлы хранить в стандартном storage проекта;
- хранить метаданные папок, документов, версий и правил доступа в БД;
- для версии хранить номер версии, имя файла, путь, размер, автора загрузки и дату загрузки;
- при полном удалении версии удалять физический файл и запись версии;
- при полном удалении документа удалять все версии и физические файлы.

## 10. Поиск и отображение

Функционал:

- дерево папок;
- список документов выбранной папки;
- поиск по названию документа;
- отображение текущей версии;
- отображение даты последнего обновления;
- отображение автора последнего обновления;
- отображение доступных действий согласно правам пользователя.

## 11. Критерии приемки

- Пункт `Документация` есть в верхнем меню.
- Раздел доступен всем авторизованным пользователям.
- Папки отображаются деревом.
- Корневые папки может создавать только администратор.
- Пользователь с правом записи на папку может создавать в ней подпапки и документы.
- Подпапки наследуют права родительской папки.
- Документы наследуют права папки.
- На папку можно назначить права чтения и записи для всех, ролей и отдельных пользователей.
- Документы поддерживают версии.
- Можно загрузить новую версию документа.
- Можно скачать предыдущую версию документа.
- Можно полностью удалить отдельную версию документа.
- При удалении документа удаляются все его версии.
- Файлы хранятся в текущем файловом механизме проекта.