Формы обходов

Возможности

• Список форм: название, «действует» или «выключена», где заполняется, число полей, номер версии и число заполнений.
• «Новая форма» и «Изменить» — конструктор: название, описание для диспетчера, «Раз на наряд» или «На каждом узле обхода», поля.
• Поля девяти типов: «Текст», «Целое число», «Число», «Выбор одного», «Выбор нескольких», «Дата», «Да / отметка», «Пояснение», «Фото». У поля — подпись, имя латиницей, «Обязательное», «Подсказка», варианты, границы «Не меньше» и «Не больше» для чисел, «Показывать по условию».
• Порядок полей — стрелками вверх и вниз; «Удалить поле».
• «Как увидит бригада» — живой предпросмотр с проверкой ответов; «Очистить» сбрасывает пробные ответы.
• «Загрузить XLSForm» — форма из файла ODK или Survey123 (.xlsx) с перечнем того, что не перенеслось.
• «Выключить» и «Включить» — форма перестаёт предлагаться в нарядах, заполнения остаются.
• Выгрузка заполнений формы в Excel (значок Excel появляется, когда заполнения есть, и только при праве «Выгрузки и отчёты»).

Как это работает

Где хранятся данные. Таблицы веба: tgid_form (форма), tgid_form_version (поля каждой версии), tgid_form_submission (заполнения). В наряде форма — поле form_id таблицы tgid_work_order. Десктоп ТГИД эти таблицы не читает.

Версии. Новая форма — версия 1. Если при «Сохранить» поля изменились (тип, подпись, варианты, условие, порядок), сервер создаёт следующую версию. Если поменяли только название, описание или «где заполняется» — версия та же. Каждое заполнение хранит номер своей версии и проверяется по ней. Поэтому правка формы не ломает уже присланные ответы: в карточке наряда они показываются с полями той версии, по которой их заполняли.

Где заполняется. «Раз на наряд» — одна форма на весь наряд. «На каждом узле обхода» — форма на каждом узле маршрута обхода; без узла сервер такое заполнение не примет.

Имя поля. Имя составляется из подписи транслитерацией, пока его не правили руками: «Состояние люка» → sostoyanie_lyuka. Имя — латиница, цифры и _, с буквы, до 40 символов. Имя — это колонка в выгрузке Excel и ключ ответа в API.

Варианты выбора. По одному на строку: «значение = подпись» или просто подпись (значение составится само). До 200 вариантов, значения не повторяются.

Условие показа. Условие ставится только по полю выше, кроме полей «Пояснение» и «Фото». Для «Выбор нескольких» — «выбрано», для остальных — «равно» или «не равно». Пока на поле-условие не ответили, зависимое поле скрыто при любом условии. Скрытое поле не проверяется и не сохраняется.

Проверка ответов одинакова в предпросмотре, на телефоне и на сервере: «обязательное поле», «отметьте», «нужно число», «нужно целое число», «не меньше N», «не больше N», «нет такого варианта», «фото — до 5».

Ограничения формы: от 1 до 100 полей, хотя бы одно поле для ответа (не только «Пояснение»), до 5 фото в поле «Фото», текст ответа — до 2000 знаков. Фото поля добавляет бригада с телефона; в конструкторе кнопка фото только показывает «Фото добавляет бригада с телефона».

XLSForm. Читаются листы survey, choices и settings (название из form_title), подпись — из колонки label или русской label::…. Переносятся типы text, integer, decimal, select_one, select_multiple, date, acknowledge, note, image; условия вида ${поле} = 'значение' и selected(${поле}, 'значение'); ограничения чисел вида . >= N and . <= M. Группы переносятся без группы, служебные поля (время, устройство) пропускаются. Всё, что не перенеслось, перечисляется над конструктором. Загрузка файла ничего не записывает: форма открывается в конструкторе, записывает её «Сохранить».

Выгрузка в Excel. Строка — заполнение, колонки — поля всех версий формы по порядку появления. Выбор показывается подписью варианта, отметка — «да», фото — «фото: N».

Что нужно для работы

• Пункт «Формы обходов» видят только пользователи с ролью «Администратор». Создание, правка, включение и выключение — тоже только администратор и при включённой записи (MUTATIONS_ENABLED=true). При выключенной записи в окне — «Запись выключена на сервере (MUTATIONS_ENABLED).», кнопок «Новая форма», «Выключить» и «Включить» нет, а в конструкторе «Сохранить» неактивна: форму можно открыть кнопкой «Изменить» и посмотреть, но не сохранить.
• Выгрузка в Excel — право «Выгрузки и отчёты»; без него значка Excel нет.
• Заполнять форму может бригада с правом «Журналы» в полевом приложении (/field), когда форма выбрана в наряде.
• Для «На каждом узле обхода» нужен наряд на обход по контуру осмотра.

Шаги

1. Откройте «Инструменты» и наберите в поиске «Формы обходов» — пункт выделен рамкой.

   

2. Нажмите пункт — откроется окно.

   

3. «Новая форма» открывает конструктор: название формы и как её заполнять — раз на наряд или на каждом узле обхода. «Добавить поле» — тип поля: текст, целое число, число, выбор одного, выбор нескольких, дата, отметка «да», пояснение, фото. У поля — подпись, имя латиницей (составится само), обязательность и условие показа («показывать, если поле … равно …»). Для выбора варианты пишутся по одному на строку.

   

4. Справа — «Как увидит бригада»: так форма выглядит на телефоне, проверяйте её здесь. «Сохранить» создаёт форму (каждое изменение — новая версия), «Отмена» выходит без сохранения. Сохранённую форму выбирают в наряде в поле «Форма обхода».

   

Примеры

Форма из инструкции. Форма «Осмотр тепловой камеры»: поле «Выбор одного» с подписью «Состояние люка» получает имя sostoyanie_lyuka. Варианты «исправен», «повреждён», «отсутствует» без явных значений получают значения ispraven, povrezhden, otsutstvuet. Поле «Фото» с подписью «Фото камеры» получает имя foto_kamery. Если ниже добавить поле «Описание повреждения» с условием «Если поле — Состояние люка, равно — повреждён», в предпросмотре оно появится только после выбора «повреждён».

Версии. Форма сохранена — версия 1. К ней добавили поле — при «Сохранить» появится «Форма «Осмотр тепловой камеры» сохранена (версия 2)». Если потом поменять только название, сообщение снова покажет версию 2.

На копиях Алматы и Астаны форм пока нет: список показывает «Форм ещё нет.», а в окне «Наряды и заявки» поле «Форма обхода» не появляется.

Если не получается

• Нет пункта «Формы обходов» — у вас не роль «Администратор».
• «Сохранить» неактивна, внизу красный текст — в форме ошибка: «Добавьте хотя бы одно поле», «Поле «…»: нет подписи», ««…»: нет вариантов», ««…»: имя «…» уже есть», ««…»: имя поля — латиница, цифры и _, с буквы», ««…»: условие — по полю выше», ««…»: минимум больше максимума», «Нет ни одного поля для ответа».
• Условие показа не предлагается — выше нет поля, по которому его можно задать (первое поле, или выше только «Пояснение» и «Фото»). При перемещении поля выше его источника условие снимается.
• «Некорректные параметры запроса: Файл не похож на XLSForm (.xlsx)», «… В файле нет листа survey», «… В форме не найдено ни одного поддерживаемого поля» — файл не XLSForm или в нём нет поддерживаемых полей. «Файл больше 2 МБ» — уменьшите файл.
• Нет кнопки «Новая форма», «Сохранить» неактивна, под описанием окна — «Запись выключена на сервере (MUTATIONS_ENABLED).» — запись на сервере выключена; включает её администратор сервера.
• Нет значка Excel у формы с заполнениями — нет права «Выгрузки и отчёты».
• Форма не предлагается в наряде — она выключена; включите её кнопкой «Включить».

Для администратора

• Таблицы tgid_form, tgid_form_version, tgid_form_submission API создаёт в базе города сам.
• Запись форм: роль «Администратор» и MUTATIONS_ENABLED=true. Заполнения с телефона — право «Журналы»; повтор отправки с тем же ключом (client_id) не создаёт второе заполнение.
• Выключенную форму нельзя выбрать в новом наряде, но наряды, где она уже стоит, её сохраняют («Форма: … (выключена)»).

Для разработчика

• API (routers/forms.py, database/forms.py): GET /api/v1/forms (active=true — только действующие), GET /api/v1/forms/types, GET /api/v1/forms/{id}?version=, POST /api/v1/forms, PUT /api/v1/forms/{id}, PATCH /api/v1/forms/{id} (active), POST /api/v1/forms/import-xlsform, GET /api/v1/forms/{id}/export.xlsx, POST /api/v1/forms/submissions, GET /api/v1/work-orders/{id}/forms.
• Константы: MAX_FIELDS, MAX_CHOICES, MAX_TEXT, MAX_PHOTOS в database/forms.py. Правила проверки — в двух местах, держать одинаковыми: database/forms.py (validate_answers, is_relevant) и utils/forms.ts (validateAnswers, isRelevant, schemaProblems).
• Веб: components/FormsDialog.vue (ключ forms), components/forms/FormRenderer.vue (предпросмотр, телефон, карточка наряда), components/FieldFormDialog.vue (заполнение в /field). Описание — itwin-api/docs/inspection-forms.md.
• Тесты: API — tests/test_forms.py; веб — tests/utils/forms.spec.ts.