openspec/specs/document-review-ui/spec.md

@@ -200,3 +200,25 @@ SHALL быть отключена с подсказкой «Разберите
 - **WHEN** документ открыт прямой ссылкой в новой вкладке, аналитик выбрал в списке «Документ» другой документ и нажал
   «Назад» экрана
 - **THEN** открыт список групп компаний `/groups`
+
+### Requirement: Комментарии к документу
+Экран документа SHALL показывать в шапке кнопку «Комментарии (N)», где N — `comments_count` документа из
+`GET /documents/{id}`. Кнопка SHALL открывать боковую панель «Комментарии к документу» со списком
+`GET /documents/{id}/comments` (запрос при каждом открытии) по возрастанию времени: ФИО автора, дата и время по Москве
+(«dd.mm.yyyy hh:mm»), текст с переносами строк; без комментариев — «Комментариев нет»; ошибка запроса — «Не удалось
+загрузить комментарии». Под списком SHALL быть поле ввода (до 4000 символов) и кнопка «Добавить», неактивная при пустом
+тексте после обрезки пробелов; добавление — `POST /documents/{id}/comments {text}`. После успешного добавления поле
+SHALL очищаться, список — перечитываться, счётчик на кнопке — обновляться из `GET /documents/{id}`. При ошибке
+добавления SHALL показываться сообщение сервера, текст в поле сохраняется. Правки и удаления комментариев нет.
+
+#### Scenario: Добавленный комментарий виден после перезагрузки
+- **WHEN** аналитик открыл «Комментарии (0)», добавил «нет подписи руководителя» и перезагрузил страницу
+- **THEN** на кнопке «Комментарии (1)», в панели — комментарий с его ФИО, датой и временем
+
+#### Scenario: Причина замены документа
+- **WHEN** документ заменён из панели «Первичные документы» с причиной «новая редакция от клиента»
+- **THEN** в комментариях заменённого документа есть «Замена документа: новая редакция от клиента»
+
+#### Scenario: Ошибка добавления
+- **WHEN** сервер отклоняет добавление (403 или 422)
+- **THEN** показано сообщение сервера, введённый текст остаётся в поле, список не меняется

openspec/specs/primary-files-ui/spec.md

@@ -75,3 +75,18 @@ SHALL перечитывать этот список раз в 5 секунд и
 #### Scenario: Потерянный ОФР в карточке
 - **WHEN** у задания `job.warnings = [{code: "JSON_FAILED", severity: "error", message: "…", locator: "file:x_ofr.json"}]`
 - **THEN** карточка показывает предупреждение уровня «ошибка» с текстом и местом; экран не падает на объекте вместо строки
+
+### Requirement: Комментарии документа в панели
+В строке документа панели «Первичные документы» [39-01] SHALL быть кнопка с иконкой комментария и числом комментариев
+документа (`documents[].comments_count`; при нуле — только иконка). Клик по кнопке SHALL открывать поповер «Комментарии
+к документу <имя файла>» со списком `GET /documents/{id}/comments` (запрос при открытии; автор, дата и время по Москве,
+текст) только для чтения; без комментариев — «Комментарий отсутствует»; кнопка «Закрыть» закрывает поповер. Клик по
+кнопке и внутри поповера SHALL NOT открывать документ. У строки файла без документов кнопки нет.
+
+#### Scenario: Счётчик совпадает с числом комментариев
+- **WHEN** к документу добавлены два комментария и панель перечитана
+- **THEN** в строке документа у иконки число 2, в поповере — оба комментария по возрастанию времени
+
+#### Scenario: Документ без комментариев
+- **WHEN** аналитик нажимает иконку комментария у документа без комментариев
+- **THEN** в поповере «Комментарий отсутствует», экран документа не открывается