PTSRaiAgent/docs/clinical/IMPLEMENTATION.md

# Реализация обновлённого опросника — PR #53

Спецификация: 19-страничный PDF, SHA-256
`b5e1cfd2b292526a8cec3bbb679294a90a446c4104a3615c0d8fcbf10e12fc0e`.
Состояние: техническая реализация для проверки; клиническое включение закрыто.

## Состав

- Первичный диалог: официальный русский C-SSRS Recent с условными переходами,
  PHQ-2 → PHQ-9 при сумме ≥2, фильтр травмы → TSQ → PCL-5 при TSQ ≥6,
  RUS-AUDIT-S 3/9/10 → полная форма по отдельно утверждаемому условию.
  Вопросы о недавности травмы, ЧМТ и психотропных препаратах сохраняются отдельно.
- TSQ: дословная инструкция и десять пунктов приложения Г1, с.129–130 PDF
  клинических рекомендаций 2023 года. Копия, источник и хеш —
  `tsq-guideline-2023.pdf`, `tsq-source.json`. Актуальность редакции не подтверждена.
- Полная алкогольная форма сохраняет ответы 3/9/10 без повторного суммирования;
  п.1=0 выводит только п.2=0. Конфликт с положительным п.3 передаётся на проверку.
  Отказ указать пол не подменяется выбором мужских или женских границ.
- PHQ/PCL взяты из новой версии PDF; обратный перевод и таблица согласования
  находятся в `revision-2026-10-03-v2/`. Тексты не считаются согласованными.
- Дневник: настроение, часы сна, восстановление после сна, приём лекарств и причина
  пропуска, переносимость, вещества, необязательный комментарий; модули ПТСР,
  депрессии, суицидальных мыслей. У группы с риском вопрос о мыслях задаётся первым.
  Общая сумма дневника не вычисляется.
- Повторы: 7/14/28 дней от начала/смены терапии, затем 28; после кризиса PHQ-9 — 7,
  PCL-5 — 14 с недельным периодом; специалист — 14/30; самопомощь — 28/28;
  RUS-AUDIT-S — 30. При пересечении выбирается ближайшая дата. ЧМТ и алкогольные
  направления сохраняются параллельно основному.
- Повторные PHQ/PCL сохраняют маршрут и изменение относительно последнего полного
  результата той же версии и периода. Рост ≥5/≥10 помечается для повторного триажа.
  Недельный PCL-5 не сравнивается с месячным. Переносимость уточняется при повторе
  на фоне зафиксированной терапии.

## Остановка и работа врача

Положительный PHQ-9/9, высокий сигнал C-SSRS, мысли о смерти в дневнике и кнопка
помощи немедленно останавливают обычные вопросы. Сохраняются частичные ответы,
причина, дополнительные флаги и обращение. Кризисный ответ содержит 112 и кнопку
плана безопасности. Средний риск C-SSRS требует оценки специалиста; низкий при
утверждённой политике `graded` показывает план безопасности и обращение врачу.
Альтернатива `stop_any` прекращает опрос при первом «Да». Выбор остаётся за врачом.

**Русский Since Last Contact не получен.** При повторном мониторинге создаётся
отдельное задание для оценки специалистом; Recent не переименовывается и не
выдаётся за повторную форму. Перед дневником/плановым мониторингом предусмотрено
одно такое задание на местный календарный день. Обычный сценарий ждёт решения
врача. Это явно обозначенный временный порядок, который также требует согласования.
Дневниковое «Да» не ждёт окончания дневника или этой плановой процедуры.

Новые служебные маршруты:

- `GET /api/v1/patients/{token}/questionnaires?doctor_id=...` — ответы, версия,
  периоды и результаты; чтение записывается в аудит.
- `POST /api/v1/patients/{token}/questionnaires/{record_id}/review` — поля
  `doctor_id`, `assessment_performed: true`, `decision: resume | keep_hold`,
  `reference` (идентификатор решения, без ФИО/свободного медицинского текста).
  Проверяются принадлежность пациента врачу, согласие и статус записи.
  Решение сохраняется с датой и аудитом. При открытом кризисе продолжение запрещено.
  Простое подтверждение получения уведомления не снимает этот запрет проверки.

Как и остальной API этой ветки, эти маршруты предназначены для синтетического
прототипа: `doctor_id` передаёт вызывающая сторона. Перед реальными данными нужна
аутентификация врача; существующая карточка дашборда остаётся отдельной заглушкой.

## Надёжность и данные

Три новые таблицы: `questionnaire_records`, `questionnaire_notices`,
`questionnaire_tasks`. Они создаются существующим `init_db`; прежние результаты
шкал не переименовываются и не мигрируют. Ответ, переход и обращение фиксируются
в одной транзакции. Неполные суммы — `null`, C-SSRS не получает суммарного балла.
Выведенный п.2 RUS-AUDIT отмечается в `derived`, отсутствуя среди исходных ответов.
Период привязан к началу конкретного заполнения; у каждого ответа есть время.

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

Обращения врачу повторяются после ошибки с ограниченной задержкой; в ошибках
сохраняется только класс исключения. `accepted_by_adapter` означает приём адаптером,
`test_sink` — сохранение демонстрационным адаптером. Доставка человеку не утверждается.
Исходящие плановые сообщения сохраняются в задании до попытки отправки. Протокол
канала не поддерживает ключ идемпотентности: после падения между отправкой и
фиксацией возможна повторная доставка; потеря очереди внутри MemoryOutbox после
перезапуска также не является подтверждённой доставкой. Для реального запуска
нужен постоянный адаптер с подтверждением доставки.

Планировщик использует часы приложения и Europe/Moscow. PostgreSQL блокирует
параллельные запуски планировщика advisory lock, ответы пациента — блокировкой
строки. В SQLite демонстрации используется один процесс. Пропущенные тики не
создают пачку исторических анкет. Перезапуск не создаёт новое открытое задание
того же типа. Изменение схемы лекарств должно иметь новую дату начала в источнике
назначений; изменение дозировки без даты не угадывается.

## Предложенные определения для согласования

В `config/intake_runtime.yaml`: семь полных календарных дней ДО трёх дней ухудшения
образуют базовый уровень; пропуски не заменяются нулями. Для каждой из трёх ночей
проверяется «сон <4 часов ИЛИ кошмары ≥3». Только явное «не принимал» три дня подряд
считается пропуском; частичный приём и побочные эффекты — отдельные флаги.
Два дня без завершённого дневника в группе риска создают обращение для контакта;
сам звонок этим кодом не выполняется. При двух модулях подробные вопросы ПТСР и депрессии чередуются по календарным
дням; вопросы о риске остаются ежедневно. Обещание заполнить за одну минуту не используется. Якоря положительных показателей
и разбиение вопроса о сне — кандидатные формулировки для врача.

## Включение и остающиеся внешние действия

По умолчанию `enabled: false`; все подписи пусты. Для включения нужны решение по
C-SSRS, порог расширения алкоголя (сумма ИЛИ зона), подпись политики и три подписи
той же версии runtime: маршрутизация/дневники/расписания, содержание, контакты.
Тестовые подписи создаются только во временных каталогах тестов. После изменения
конфигурации требуется перезапуск приложения.

До работы с пациентами остаются: врачебное согласование, независимая проверка
перевода, проверка актуальной редакции КР и условий использования TSQ, получение
русского Since Last Contact, операционная проверка линий и готовности дежурного.
Публикация PR не выполняет ни один из этих пунктов.