Интеграционная документация для фронтенда

Папка содержит документы, которые объясняют фронту, как реализовать конкретный экран/раздел без обращения к бэкендеру: какие эндпоинты дёргать, откуда брать значения для каждого селектора, как маппить поля UI на DTO, какие модалки открываются на каких жестах.

Документация не дублирует docs/business/ (бизнес-смысл) и docs/prd/ (продуктовые требования). Здесь — техническая интеграция: эндпоинты, поля, параметры, поведение модалок.

Структура

docs/frontend-integration/
  README.md                       — этот файл
  <module>/                       — модуль системы (accounting, staffing, inventory, ...)
    <screen-or-section>.md        — документ по одному экрану/разделу

Один раздел = один файл. Если внутри раздела несколько связанных модалок (как в «Приёме платежей» — таблица + «Приём оплаты» + «Новый счёт» + «Персональная карточка»), они описываются в одном документе с разными секциями.

Содержание документа раздела

Минимально каждый документ включает:

Назначение — что это за раздел и зачем он бухгалтеру/менеджеру/оператору.
Customer Journey Map (CJM) — основные пути пользователя в виде ASCII-схемы: какие модалки открываются на каких жестах, какие эндпоинты дёргаются.
Эндпоинты раздела — полный список вызовов с методом, маршрутом, краткой целью и ссылкой на контроллер.
Селекторы и справочники — для каждого dropdown’а: откуда брать значения, какие параметры передавать, как фильтровать.
Маппинг полей UI ↔ DTO — таблица соответствия для каждой формы/таблицы.
Семантика статусов, цветов, enum’ов — какие значения отображаются как и почему.
Известные расхождения и план доработок — что сейчас работает, что появится после конкретных задач Tracker.

Стиль

Русский язык.
Имена полей DTO и Prisma-сущностей — как в коде (paymentDate, Counterparty.isClient).
Ссылки на код через относительные пути от корня репозитория, для навигации в IDE и в GitHub: [payment.controller.ts:74](src/accounting/presentation/controllers/payment.controller.ts:74).
Ссылки на задачи Tracker полным URL: [LOCALIOFFICE-973](https://tracker.yandex.ru/LOCALIOFFICE-973).
Модель данных не дублировать — ссылаться на prisma/schema/*.prisma.
Помечать каждое расхождение с реальностью: «✅ есть сейчас», «⚠️ появится после задачи N», «❌ не поддерживается».

Кто и когда поддерживает

При создании нового раздела — копируется структура из существующего документа и заполняется.
При изменении API/UI в рамках задачи Tracker — задача в Tracker обязана обновить соответствующий документ. Если документа ещё нет — создаётся.
При появлении нового модуля на UI — заводится новая подпапка <module>/.

Существующие документы

accounting/payment-acceptance.md — Приём платежей (таблица + Приём оплаты + Новый счёт + Персональная карточка).
staffing/attendance-journal.md — Журнал явок: таблица сотрудников × дней + модалка «Окно явки» (редактирование, resolve PENDING, экспорт в xlsx).
staffing/timesheet-t13.md — Табель учёта рабочего времени (форма Т-13): модалка экспорта в журнале явок.
inventory/invoices.md — Накладные: список + форма (вкладки Товары / Услуги / Заготовки для приходной и расходной) + история + PDF + repost + lifecycle.
inventory/write-off-acts.md — Акты списания: список + форма (выбор склада, счёта списания, позиции с фасовкой и себестоимостью) + история + копирование + lifecycle.
inventory/sales-acts.md — Акты реализации: список + форма (выбор счёта выручки и расходного счёта, продажная цена в позиции) + история + копирование + экспорт + lifecycle.
inventory/stock-balances.md — Остатки на складах: матрица «номенклатура × склады» с meta-итогами в подвале + отдельный сценарий «остатки больше макс / меньше мин».
inventory/inventories.md — Инвентаризации: список + 3-шаговый мастер (блюда/заготовки → товары → счета излишков/недостач) + точечные операции с позициями + lifecycle.
menu-management/tech-card.md — Технологическая карта: вкладка в формах Блюда/Заготовки/Модификатора (составное чтение/сохранение через карточку номенклатуры, версии, расчётные поля, настройки по подразделениям, печать PDF).