# Расширенные настройки

Выражения PEXL, параметры ссылок, автозаполнение ответов и Redirects / HOOKs.

# PEXL

# Синтаксис PEXL

PEXL (Poll Expression Language) — язык выражений для доступа к данным интервью, сравнения значений, логических условий, работы с переменными, параметрами, тегами ответов, подсчётами и псевдослучайными значениями.

Документ описывает синтаксис, реально поддерживаемый грамматикой `pexl.g`, парсером `pexl.js` и тестами проекта.

---

## 1. Общая модель выражений

Выражение PEXL вычисляется в контексте объекта `interview` и возвращает одно значение:

- `true` / `false` для логических и сравнительных выражений;
- строку;
- число;
- `null`, если значение не найдено;
- иногда объект вопроса или ответа как внутреннее промежуточное значение, но в типовых пользовательских выражениях обычно используются строка, число или булево значение.

Примеры:

```pexl
Q1
Q1 == "Q one"
Q1.A3 == "A three"
Q5.A >= 22
PARAM("PARAM1") == "PAR1"
$X = RAND(1, 10)

```

---

## 2. Лексические элементы

### 2.1. Пробелы

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

Примеры:

```pexl
Q1.A3=="A three"
Q1.A3 == "A three"
Q1 . A3

```

Практически использовать стоит обычную читаемую запись без разрыва внутри ссылок вида `Q1.A3`.

### 2.2. Числа

Поддерживаются только целые числа:

```pexl
0
1
22
100500

```

Формально: последовательность цифр `\d+`.

Отрицательные, дробные и экспоненциальные числа синтаксисом не предусмотрены.

### 2.3. Строки

Поддерживаются строковые литералы в двойных кавычках:

```pexl
"Hello"
"A three"
"06bf20de-9658-4afd-9e7b-d712697ccdc7"

```

Также лексер распознаёт литералы в одинарных кавычках, но в грамматике языка они не используются как допустимые значения выражений. Поэтому в корректном PEXL следует использовать **двойные кавычки**.

### 2.4. Ключевые слова и служебные токены

Поддерживаются следующие ключевые слова и служебные конструкции:

- `AND`
- `OR`
- `NOT`
- `PARAM`
- `VAR`
- `QUUID`
- `ATUUID`
- `AQUUID`
- `TATUUID`
- `TAQUUID`
- `CQUUID`
- `CRUUID`
- `RAND`
- `COUNT`
- `Q`
- `R`
- `A`
- `T.<TAG_NAME>`

### 2.5. Операторы и знаки пунктуации

- `==`
- `!=`
- `<`
- `>`
- `<=`
- `>=`
- `=`
- `(`
- `)`
- `.`
- `,`

---

## 3. Базовая грамматика выражений

На верхнем уровне PEXL поддерживает два больших класса выражений:

1. **вычисление/сравнение значения**;
2. **присваивание переменной**.

Упрощённо:

```text
STMT ::= STMT == STMT
       | STMT != IVALUE
       | STMT <  IVALUE
       | STMT >  IVALUE
       | STMT <= IVALUE
       | STMT >= IVALUE
       | STMT AND STMT
       | STMT OR STMT
       | NOT STMT
       | ( STMT )
       | IVALUE
       | ASSIGN_VALUE

```

Где `IVALUE` — это обычное вычисляемое значение, а `ASSIGN_VALUE` — присваивание переменной.

---

## 4. Приоритет операторов

Согласно грамматике проекта, используются такие приоритеты:

1. `NOT` — самый высокий;
2. сравнения: `==`, `!=`, `<`, `<=`, `>`, `>=`;
3. `OR`;
4. `AND`;
5. `=` (присваивание).

> Важно: приоритеты в `pexl.g` заданы не совсем так, как в большинстве языков программирования. Для сложных выражений рекомендуется **всегда явно ставить скобки**.

Примеры безопасной записи:

```pexl
Q1.A3 AND (NOT Q2.A1)
(Q1.A3 == "A three") AND (Q2.A1 == "A one")
($X = RAND(1, 10)) AND ($X >= 1)

```

---

## 5. Допустимые виды значений (`IVALUE`)

`IVALUE` может быть одним из следующих типов:

- значение вопроса;
- значение ответа;
- текст ответа;
- значение тега ответа;
- количество ответов;
- значение параметра;
- значение переменной;
- доступ по UUID;
- результат `RAND`;
- числовой литерал;
- строковый литерал.

Подробно — ниже.

---

## 6. Ссылки на вопросы

### 6.1. Вопрос `Qx`

Форма:

```pexl
Q<number>

```

Примеры:

```pexl
Q1
Q2
Q10

```

Семантика:

- возвращает вопрос по `questionCode`;
- в сравнении используется `question.question` — текст вопроса;
- в булевом контексте истинно, если вопрос найден.

Примеры:

```pexl
Q1
Q1 == "Q one"
NOT Q123

```

### 6.2. Строка табличного вопроса `Qx.Ry`

Форма:

```pexl
Q<number>.R<number>

```

Примеры:

```pexl
Q3.R1
Q3.R2

```

Семантика:

- возвращает вопрос-строку таблицы;
- в сравнении используется текст вопроса этой строки.

Примеры:

```pexl
Q3.R1 == "Q three R one"
Q3.R2

```

---

## 7. Ссылки на ответы

### 7.1. Конкретный ответ `Qx.Ay`

Форма:

```pexl
Q<number>.A<number>

```

Пример:

```pexl
Q1.A3

```

Семантика:

- ищет ответ с кодом `Ay` у вопроса `Qx`;
- возвращает объект ответа;
- при сравнении используется `answerText`;
- если `answerText` выглядит как целое число, при некоторых сравнениях он будет приведён к числу.

Примеры:

```pexl
Q1.A3 == "A three"
Q7.A3 == 22

```

### 7.2. Конкретный ответ в строке таблицы `Qx.Ry.Az`

Форма:

```pexl
Q<number>.R<number>.A<number>

```

Пример:

```pexl
Q3.R1.A3

```

Примеры использования:

```pexl
Q3.R1.A3 == "A three"
Q3.R2.A1

```

---

## 8. Текст ответа

### 8.1. Первый/основной текст ответа вопроса `Qx.A`

Форма:

```pexl
Q<number>.A

```

Пример:

```pexl
Q5.A

```

Семантика:

- возвращает `answerText` первого подходящего ответа вопроса;
- если текст числовой, в ряде операций используется как число.

Примеры:

```pexl
Q1.A == "A three"
Q5.A == 22
Q5.A >= 22

```

### 8.2. Текст ответа строки таблицы `Qx.Ry.A`

Форма:

```pexl
Q<number>.R<number>.A

```

Пример:

```pexl
Q3.R2.A

```

Примеры:

```pexl
Q3.R2.A == "33"
Q3.R1.A == "A three"

```

---

## 9. Теги ответов

Тег кодируется как специальный токен вида:

```pexl
T.<TAG_NAME>

```

Допустимые символы имени тега: буквы, цифры, `_`, `-`.

Примеры:

```pexl
T.A_TAG_INT
T.A_TAG_STR
T.score-1

```

### 9.1. Тег конкретного ответа `Qx.Ay.T.TAG`

Форма:

```pexl
Q<number>.A<number>.T.<TAG>
Q<number>.R<number>.A<number>.T.<TAG>

```

Примеры:

```pexl
Q1.A3.T.A_TAG_INT
Q3.R1.A3.T.A_TAG_STR

```

Семантика:

- возвращает значение тега из `answerTags[tag]`;
- если значение тега числовое, оно приводится к числу;
- если тега нет, возвращается `null`.

Примеры:

```pexl
Q1.A3.T.A_TAG_INT == 55
Q1.A3.T.A_TAG_STR == "Tag value"

```

### 9.2. Тег первого/основного ответа вопроса `Qx.A.T.TAG`

Форма:

```pexl
Q<number>.A.T.<TAG>
Q<number>.R<number>.A.T.<TAG>

```

Примеры:

```pexl
Q1.A.T.A_TAG_INT
Q3.R1.A.T.A_TAG_STR

```

Семантика:

- перебирает ответы вопроса и возвращает первый найденный тег с таким именем;
- если тег нигде не найден, возвращает `null`.

Примеры:

```pexl
Q1.A.T.A_TAG_INT == 55
Q1.A.T.A_TAG_STR == "Tag value"

```

---

## 10. Подсчёт количества ответов

### 10.1. Количество ответов вопроса `Qx.COUNT`

Форма:

```pexl
Q<number>.COUNT

```

Пример:

```pexl
Q2.COUNT

```

Семантика:

- возвращает число ответов вопроса;
- в циклическом контексте результат зависит от `loopType`.

Примеры:

```pexl
Q2.COUNT == 4
Q6.COUNT == 6

```

### 10.2. Количество ответов строки таблицы `Qx.Ry.COUNT`

Форма:

```pexl
Q<number>.R<number>.COUNT

```

Пример:

```pexl
Q3.R1.COUNT

```

### 10.3. Количество заполненных строк таблицы `Qx.R.COUNT`

Форма:

```pexl
Q<number>.R.COUNT

```

Пример:

```pexl
Q3.R.COUNT == 3

```

Семантика:

- считает количество дочерних вопросов, чьи коды начинаются с `Qx.R`.

---

## 11. Доступ по UUID

### 11.1. Вопрос по UUID: `QUUID("...")`

Форма:

```pexl
QUUID("<question_uuid>")

```

Семантика:

- ищет вопрос по `questionId`;
- в сравнении используется текст вопроса.

Примеры:

```pexl
QUUID("06bf20de-9658-4afd-9e7b-d712697ccdc7")
QUUID("06bf20de-9658-4afd-9e7b-d712697ccdc7") == "Q one"

```

### 11.2. Конкретный ответ по UUID: `ATUUID("...")`

Форма:

```pexl
ATUUID("<answer_template_uuid>")

```

Семантика:

- ищет ответ по `templateAnswerId`;
- в сравнении используется `answerText`.

Примеры:

```pexl
ATUUID("a2101b08-b18e-4137-abb0-5eb2e44d751e")
ATUUID("a2101b08-b18e-4137-abb0-5eb2e44d751e") == "A three"

```

### 11.3. Текст ответа по UUID: `AQUUID("...")`

Форма:

```pexl
AQUUID("<question_uuid>")

```

Семантика:

- возвращает текст первого/основного ответа вопроса по UUID вопроса;
- для числовых строк поддерживаются числовые сравнения.

Примеры:

```pexl
AQUUID("06bf20de-9658-4afd-9e7b-d712697ccdc7") == "A three"
AQUUID("c82d8380-cae4-43c1-93be-3cf5a06449f3") >= 22

```

### 11.4. Тег конкретного ответа по UUID: `TATUUID("answerUuid", "TAG")`

Форма:

```pexl
TATUUID("<answer_template_uuid>", "<TAG>")

```

Примеры:

```pexl
TATUUID("a2101b08-b18e-4137-abb0-5eb2e44d751e", "A_TAG_INT") == 55
TATUUID("a2101b08-b18e-4137-abb0-5eb2e44d751e", "A_TAG_STR") == "Tag value"

```

### 11.5. Тег первого/основного ответа вопроса по UUID: `TAQUUID("questionUuid", "TAG")`

Форма:

```pexl
TAQUUID("<question_uuid>", "<TAG>")

```

Примеры:

```pexl
TAQUUID("06bf20de-9658-4afd-9e7b-d712697ccdc7", "A_TAG_INT") == 55
TAQUUID("06bf20de-9658-4afd-9e7b-d712697ccdc7", "A_TAG_STR") == "Tag value"

```

### 11.6. Количество ответов вопроса по UUID: `CQUUID("...")`

Форма:

```pexl
CQUUID("<question_uuid>")

```

Примеры:

```pexl
CQUUID("06bfcccc-9658-4afd-9e7b-d712697ccdc7") == 6

```

### 11.7. Количество строк таблицы по UUID: `CRUUID("...")`

Форма:

```pexl
CRUUID("<table_uuid>")

```

Примеры:

```pexl
CRUUID("7a33bdab-d53b-4958-a293-60e3fded8aa8") == 3

```

---

## 12. Параметры интервью

Форма:

```pexl
PARAM("<name>")

```

Примеры:

```pexl
PARAM("PARAM1")
PARAM("PARAM1") == "PAR1"
PARAM("PARAM1") == PARAM("param2")

```

Семантика:

- читает `interview.params[name]`;
- регистр имени зависит от того, как значения реально хранятся в объекте `params`.

---

## 13. Переменные

PEXL поддерживает две формы обращения к переменным.

### 13.1. Переменная вида `$NAME`

Форма:

```pexl
$<name>

```

Допустимые символы имени: буквы, цифры, `_`, `-`.

Примеры:

```pexl
$VAR1
$var2
$MY-VAR

```

Чтение:

```pexl
$VAR1 == "VAL1"

```

Присваивание:

```pexl
$VAR3 = "Test3"
$N = 22
$X = Q1
$Y = Q3.R1.A3
$R = RAND(1, 10)

```

### 13.2. Переменная вида `VAR("NAME")`

Форма:

```pexl
VAR("<name>")

```

Примеры:

```pexl
VAR("VAR1")
VAR("var2") == "val2"
VAR("VAR4") = "Test4"
VAR("VAR_QQ") = Q1

```

Семантика у `$NAME` и `VAR("NAME")` общая:

- чтение идёт из `interview.vars[name]`;
- запись идёт в `interview.vars[name]`.

### 13.3. Что можно присваивать переменной

Правая часть присваивания может быть:

- строкой;
- числом;
- вопросом `Q...` / `QUUID(...)` — в переменную попадёт текст вопроса;
- ответом `Q...A...` / `ATUUID(...)` — в переменную попадёт `answerText`;
- `COUNT`-значением;
- tag-значением;
- `Qx.A` / `Qx.Ry.A` / `AQUUID(...)`;
- другой переменной;
- `RAND(...)`.

Примеры:

```pexl
$VAR3 = "Test3"
$VAR_Q = Q1
$VAR_Q = Q3.R1.A3
$MY = $VAR3
VAR("VAR4") = "Test4"
VAR("VAR_QQ") = Q1

```

---

## 14. Псевдослучайные значения

### 14.1. Короткая форма `RAND(n)`

Форма:

```pexl
RAND(<max>)

```

Семантика:

- возвращает целое число в диапазоне от `1` до `n` включительно.

Пример:

```pexl
RAND(5)

```

### 14.2. Полная форма `RAND(min, max)`

Форма:

```pexl
RAND(<min>, <max>)

```

Семантика:

- возвращает целое число в диапазоне `[min, max]` включительно;
- если аргументы переданы в обратном порядке, фактически используются `Math.min` и `Math.max`.

Примеры:

```pexl
RAND(3, 7)
RAND(42, 42)
$X = RAND(1, 100)
RAND(10, 20) >= 10 AND RAND(10, 20) <= 20

```

Особенность реализации:

- генератор детерминированно инициализируется от `interview.id`;
- для одного и того же `interview.id` результат воспроизводим между запусками;
- если `interview.id` отсутствует, используется резервный seed.

Совместимость с конвертерами:

- `RAND(...)` корректно проходит через `convert2UUID` (выражение → UUID-форма для хранения в БД) и `convert2QA` (UUID-форма → читаемая форма для отображения);
- внутри `RAND(...)` нет ничего, что нужно конвертировать в UUID, поэтому литерал просто пробрасывается без изменений;
- допускается использование `RAND` в любых выражениях, которые сохраняются в poll-объекте: условиях ветвления, присваиваниях переменным и т.д.

---

## 15. Операторы сравнения

Поддерживаются:

- `==`
- `!=`
- `<`
- `>`
- `<=`
- `>=`

Примеры:

```pexl
Q1 == "Q one"
Q1.A3 == "A three"
Q5.A != 20
Q5.A < 123
Q5.A <= 22
Q5.A > 21
Q5.A >= 22

```

### 15.1. Правила сравнения

Реализация сравнения устроена так:

1. Левая часть должна быть truthy, иначе результат выражения будет ложным.
2. Если **и левое, и правое** значения распознаются как целые числа, сравнение выполняется как числовое.
3. Иначе сравнение выполняется как обычное JS-сравнение значений/строк.

Примеры числового сравнения:

```pexl
Q7.A3 == 22
Q7.A3 < Q7.A4
Q5.A >= 22

```

Примеры строкового сравнения:

```pexl
Q7.A1 == "AAAA"
Q7.A1 < Q7.A2

```

### 15.2. Сравнение значения слева и справа

С обеих сторон могут стоять не только литералы, но и выражения:

```pexl
Q7.A1 == Q7.A1
"BBBB" == Q7.A2
22 == Q7.A3
PARAM("PARAM1") == PARAM("param2")

```

---

## 16. Логические операторы

### 16.1. `AND`

Форма:

```pexl
<expr> AND <expr>

```

Примеры:

```pexl
Q1.A3 == "A three" AND Q2.A1 == "A one"
Q1 == "Q one" AND Q3.R1 == "Q three R one"

```

Семантика: логическое И.

### 16.2. `OR`

Форма:

```pexl
<expr> OR <expr>

```

Пример:

```pexl
Q1 == "Q one" OR Q1 == "Wrong Q"

```

### 16.3. `NOT`

Форма:

```pexl
NOT <expr>

```

Примеры:

```pexl
NOT Q1
NOT Q123
NOT Q1.A3 == "A three"
Q1.A3 AND NOT Q2222.A1 AND Q5555.A2

```

### 16.4. Скобки

Форма:

```pexl
( <expr> )

```

Примеры:

```pexl
Q1 AND (Q1 == "Q one" OR Q1 == "Wrong Q")
Q1.A3 AND (Q2.A1 == "A one" OR Q1111.A111 == "Wrong Q")
Q1.A3 AND (NOT Q2222.A1) AND Q5555.A2

```

---

## 17. Поведение при отсутствии данных

Если вопрос, ответ, тег или переменная не найдены, обычно возвращается `null`.

Типичные последствия:

- просто выражение `Q123` в булевом контексте считается ложным;
- `NOT Q123` даёт `true`;
- сравнение вида `Q111.A == "..."` не обязано возвращать строго `false`, потому что промежуточно может участвовать `null`.

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

---

## 18. Контекст циклов

Синтаксис выражения не меняется, но семантика поиска вопроса/ответа может зависеть от `options`, переданных в `execute(...)`.

Поддерживаются режимы:

- без цикла;
- `loopType: "DOWHILE"`;
- `loopType: "FOREACH"`;
- `loopType: "NONE"`.

### 18.1. `DOWHILE`

Требует:

```js
{ loopType: "DOWHILE", loopPass: <number> }

```

В этом режиме конструкции вроде:

- `Qx`
- `Qx.Ay`
- `Qx.A`
- `QUUID(...)`
- `ATUUID(...)`
- `AQUUID(...)`
- `CQUUID(...)`

ищут данные внутри соответствующей итерации `loopPass`, а при необходимости могут использовать значения вне цикла как fallback.

Примеры выражений:

```pexl
Q2 == "Q two 2"
Q2.A1 == "A one. LoopPass2"
Q2.A == "A one. LoopPass2"
QUUID("10264445-3949-41b3-8b87-4cc20bf6c5c0") == "Q two 2"
ATUUID("4a8e4bd6-7500-4195-a731-158780787d21") == "A two. LoopPass2"

```

### 18.2. `FOREACH`

Требует:

```js
{ loopType: "FOREACH", iterationTemplateAnswerId: "<uuid>" }

```

В этом режиме поиск значения выполняется в контексте конкретной итерации `iterationTemplateAnswerId`.

Примеры:

```pexl
Q6 == "Q Loop"
Q6.A1 == "A six one"
Q6.A == "A six one 2"
AQUUID("06bfcccc-9658-4afd-9e7b-d712697ccdc7") == "A six one 2"
Q6.COUNT == 3

```

### 18.3. Ошибки конфигурации цикла

Реализация `execute()` выбрасывает ошибку, если:

- указан `loopPass` или `iterationTemplateAnswerId`, но не указан `loopType`;
- `loopType: "FOREACH"` без `iterationTemplateAnswerId`;
- `loopType: "DOWHILE"` без `loopPass`;
- указан неизвестный `loopType`.

---

## 19. Полный каталог синтаксических форм

Ниже перечислены все поддерживаемые формы пользовательских выражений.

### 19.1. Литералы

```pexl
123
"text"

```

### 19.2. Вопросы и ответы

```pexl
Q1
Q3.R1
Q1.A3
Q3.R1.A3
Q1.A
Q3.R2.A

```

### 19.3. Теги

```pexl
Q1.A3.T.A_TAG_INT
Q3.R1.A3.T.A_TAG_STR
Q1.A.T.A_TAG_INT
Q3.R1.A.T.A_TAG_STR

```

### 19.4. Подсчёты

```pexl
Q2.COUNT
Q3.R1.COUNT
Q3.R.COUNT

```

### 19.5. UUID-функции

```pexl
QUUID("question-uuid")
ATUUID("answer-uuid")
AQUUID("question-uuid")
TATUUID("answer-uuid", "TAG")
TAQUUID("question-uuid", "TAG")
CQUUID("question-uuid")
CRUUID("table-uuid")

```

### 19.6. Параметры и переменные

```pexl
PARAM("PARAM1")
$VAR1
VAR("VAR1")

```

### 19.7. Присваивания

```pexl
$X = "abc"
$X = 10
$X = Q1
$X = Q1.A3
$X = Q1.A
$X = Q1.A3.T.A_TAG_INT
$X = Q2.COUNT
$X = AQUUID("question-uuid")
$X = TAQUUID("question-uuid", "TAG")
$X = RAND(1, 10)

VAR("X") = "abc"
VAR("X") = Q1
VAR("X") = Q1.A3

```

### 19.8. RAND

```pexl
RAND(5)
RAND(1, 10)

```

### 19.9. Логика и сравнения

```pexl
Q1 == "Q one"
Q1.A3 != "Wrong"
Q5.A < 100
Q5.A <= 22
Q5.A > 10
Q5.A >= 22
NOT Q123
Q1 AND Q2
Q1 OR Q2
(Q1 AND Q2) OR Q3

```

---

## 20. Практические рекомендации

1. Используйте **двойные кавычки** для строк.
2. Для сложной логики всегда ставьте **скобки**.
3. Если значение может отсутствовать, учитывайте возможность `null`.
4. Для числовых сравнений используйте числовые литералы:

```pexl
Q5.A >= 22

```

5. Для читаемости разделяйте длинные выражения пробелами:

```pexl
Q1.A3 == "A three" AND Q2.A1 == "A one"

```

---

## 21. Примеры полных выражений

### Простые проверки

```pexl
Q1
Q1.A3
NOT Q123

```

### Сравнение вопросов и ответов

```pexl
Q1 == "Q one"
Q1.A3 == "A three"
Q3.R1 == "Q three R one"
Q3.R1.A3 == "A three"

```

### Работа с числовыми ответами

```pexl
Q5.A == 22
Q5.A != 20
Q5.A < 123
Q5.A >= 22

```

### Теги

```pexl
Q1.A3.T.A_TAG_INT == 55
Q1.A.T.A_TAG_STR == "Tag value"
TATUUID("a2101b08-b18e-4137-abb0-5eb2e44d751e", "A_TAG_INT") == 55
TAQUUID("06bf20de-9658-4afd-9e7b-d712697ccdc7", "A_TAG_STR") == "Tag value"

```

### Параметры и переменные

```pexl
PARAM("PARAM1") == "PAR1"
$VAR1 == "VAL1"
VAR("VAR1") == "VAL1"
$TMP = Q1.A
VAR("N") = RAND(1, 100)

```

### Сложная логика

```pexl
Q1.A3 AND (Q2.A1 == "A one" OR Q1111.A111 == "Wrong Q")
Q1 AND (Q1 == "Q one" OR Q1 == "Wrong Q")
Q1.A3 AND NOT Q2222.A1 AND Q5555.A2

```

---

## 22. Краткая формальная сводка

```text
Вопрос:
  Qn
  Qn.Rm

Ответ:
  Qn.Am
  Qn.Rm.Ak

Текст ответа:
  Qn.A
  Qn.Rm.A

Теги:
  Qn.Am.T.TAG
  Qn.Rm.Ak.T.TAG
  Qn.A.T.TAG
  Qn.Rm.A.T.TAG

Подсчёты:
  Qn.COUNT
  Qn.Rm.COUNT
  Qn.R.COUNT

UUID:
  QUUID("uuid")
  ATUUID("uuid")
  AQUUID("uuid")
  TATUUID("uuid", "TAG")
  TAQUUID("uuid", "TAG")
  CQUUID("uuid")
  CRUUID("uuid")

Параметры:
  PARAM("name")

Переменные:
  $NAME
  VAR("NAME")

Присваивание:
  $NAME = <value>
  VAR("NAME") = <value>

RAND:
  RAND(n)
  RAND(min, max)

Логика:
  expr AND expr
  expr OR expr
  NOT expr
  (expr)

Сравнения:
  expr == expr
  expr != expr
  expr < expr
  expr > expr
  expr <= expr
  expr >= expr

```

---

## 23. Источник истины

Этот документ составлен по фактической реализации проекта:

- `pexl.g` — исходная грамматика основного парсера;
- `pexl.js` — сгенерированный парсер и лексер;
- `test_pexl.js` — набор тестов, фиксирующий поддерживаемое поведение основного парсера;
- `convert2UUID.g` / `convert2UUID.js` — грамматика и парсер преобразования выражений с алиасами (`Q1.A1`) в UUID-форму для хранения в БД;
- `convert2QA.g` / `convert2QA.js` — грамматика и парсер обратного преобразования (UUID-форма → читаемые алиасы) для отображения;
- `test_convert2UUID.js`, `test_convert2QA.js` — тесты конвертеров.

Грамматики `pexl.g`, `convert2UUID.g`, `convert2QA.g` должны держаться в синхроне по набору поддерживаемых токенов и продакшнов: если в одной из них появляется новый оператор (например, `RAND`), его обязательно нужно добавить и в две другие, иначе сохранение/отображение выражений ломается.

Если реализация и документ когда-либо разойдутся, источником истины следует считать код и тесты.

# Автозаполнение ответов из URL

# Автозаполнение ответов интервью из URL-параметров (userCode)

> **Статус:** реализовано· **Модуль:** web-интервью (CAWI) · **Дата:** 2026-07-16 **Аудитория:** методисты/администраторы опросов, интеграторы (формируют ссылки), разработчики.

## Коротко

При открытии web-интервью по ссылке с параметром вида `?sex=1` приложение **само выбирает** нужный вариант ответа: находит вопрос, у которого код `userCode == "sex"`, и отмечает в нём вариант, у которого `userCode == "1"`.

Это избавляет респондента от повторного ответа на вопросы, ответы на которые уже известны заранее (пол, возраст, регион и т. п. — например, переданы панелью или из CRM).

```
https://<адрес-приложения>/?poll_id=<uuid>&user_name=<имя>&sex=1
                                                          ▲
                                       код вопроса = sex, код варианта = 1 → выбран автоматически

```

---

## 1. Контракт

Правило ровно одно и симметричное:

<table id="bkmrk-%D0%A7%D0%B0%D1%81%D1%82%D1%8C-url-%D0%A7%D0%B5%D0%BC%D1%83-%D1%81%D0%BE%D0%BE%D1%82%D0%B2"><thead><tr><th>Часть URL</th><th>Чему соответствует</th></tr></thead><tbody><tr><td>**Имя** параметра (`sex`)</td><td>`userCode` **вопроса**</td></tr><tr><td>**Значение** параметра (`1`)</td><td>`userCode` **варианта ответа**</td></tr></tbody></table>

Сопоставление идёт **только по `userCode`**. Ни `answerCode`, ни порядковый номер, ни текст варианта в матчинге не участвуют.

---

## 2. Настройка опроса (методист / администратор)

Чтобы вопрос участвовал в автозаполнении, `userCode` нужно **включить и заполнить** в двух местах:

1. **На самом вопросе** — задать код (например `sex`) и включить флаг `userCode.enabled`.
2. **На каждом варианте ответа**, который должен быть выбираемым по ссылке, — задать код (например `1` для «МУЖ», `2` для «ЖЕН») и включить `userCode.enabled`.

**Пример (эталонный тестовый опрос «AUTOTEST-12»):**

<table id="bkmrk-%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA%D1%82-%D0%A2%D0%B5%D0%BA%D1%81%D1%82-usercod"><thead><tr><th>Объект</th><th>Текст</th><th>userCode</th></tr></thead><tbody><tr><td>Вопрос</td><td>«Пол»</td><td>`sex`</td></tr><tr><td>Вариант</td><td>МУЖ</td><td>`1`</td></tr><tr><td>Вариант</td><td>ЖЕН</td><td>`2`</td></tr></tbody></table>

Ссылка `...&sex=1` выберет «МУЖ», `...&sex=2` — «ЖЕН».

> **Важно:** вариант без включённого `userCode` по ссылке выбрать нельзя — он просто не будет найден. Отката на другие коды нет by design.

---

## 3. Формирование ссылки (интегратор)

Базовый формат web-ссылки на интервью:

```
https://<адрес-приложения>/?poll_id=<uuid-опроса>&user_name=<имя-респондента>&<код1>=<значение>&<код2>=<значение>

```

Параметры автозаполнения добавляются к обычной ссылке как дополнительные пары `код=значение`.

### Несколько вопросов сразу

Каждый вопрос — отдельный параметр:

```
...&sex=1&age=3&region=77

```

### Мультивыбор (вопросы с несколькими ответами)

Несколько вариантов одного вопроса — через **запятую в одном параметре**:

```
...&hobby=1,3,5

```

Использовать повторяющийся ключ (`hobby=1&hobby=3`) **нельзя** — при разборе URL остаётся только последнее значение, предыдущие теряются.

### ⚠️ Кодирование символов — критично

Значения параметров автозаполнения берутся из URL **как есть, без URL-декодирования**. Отсюда два правила:

- **Запятую-разделитель не кодировать.** `hobby=1,3` — правильно. `hobby=1%2C3` — приложение получит буквально строку `1%2C3`, не разобьёт её на `1` и `3`, и ни один вариант не совпадёт.
- **Не рассчитывать на раскодирование `%20` и подобного.** Пробелы и спецсимволы в кодах лучше не использовать вовсе. Пробелы по краям значения приложение обрежет само (`sex= 1 ` → `1`), но `%20` пробелом не станет.

---

## 4. Правила сопоставления (важные нюансы поведения)

<table id="bkmrk-%D0%A1%D0%B8%D1%82%D1%83%D0%B0%D1%86%D0%B8%D1%8F-%D0%9F%D0%BE%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5-%D0%97"><thead><tr><th>Ситуация</th><th>Поведение</th></tr></thead><tbody><tr><td>Значение совпало с `userCode` варианта</td><td>Вариант выбирается автоматически</td></tr><tr><td>**Строгое сравнение строк**</td><td>`01` ≠ `1`, `1.0` ≠ `1`. Код должен совпасть точно (пробелы по краям обрезаются)</td></tr><tr><td>Мультивыбор `q=1,3`</td><td>Выбираются оба варианта, **в порядке значений из URL**</td></tr><tr><td>В вопросе настроен **autoSelect** (условный автовыбор)</td><td>autoSelect **главнее** — автозаполнение по ссылке для такого вопроса не применяется</td></tr><tr><td>На вопрос **уже дан ответ** (респондент ответил / есть черновик)</td><td>Автозаполнение **не перезаписывает** ответ</td></tr><tr><td>**Чекбокс с лимитом** (максимум N ответов)</td><td>Если по ссылке пришло больше вариантов, чем разрешено, берутся первые N (в порядке URL), остальные отбрасываются</td></tr><tr><td>**Чекбокс с «эксклюзивным» вариантом** (напр. «Затрудняюсь ответить»)</td><td>Если среди пришедших есть эксклюзивный вариант — выбирается только он</td></tr><tr><td>Вариант **скрыт** условием видимости</td><td>Не выбирается (скрытые варианты в автозаполнении не участвуют)</td></tr><tr><td>Параметр есть, но **подходящего варианта нет** (`sex=99`)</td><td>Ничего не выбирается, приложение продолжает работу, в лог пишется предупреждение</td></tr><tr><td>Параметра для вопроса **нет в ссылке**</td><td>Вопрос остаётся пустым, респондент отвечает сам</td></tr></tbody></table>

Ключевой принцип: **автозаполнение либо помогает, либо молча уступает**. Оно никогда не ломает интервью, не перетирает уже данный ответ и не спорит с настроенным в опросе автовыбором.

---

## 5. Что НЕ поддерживается

Осознанно вне текущего объёма (планируется отдельно):

- **Диапазоны возраста** (например «19 лет» → группа «18–24»). Сейчас нужно точное совпадение кода.
- **Открытый ввод** — числовые и текстовые поля по ссылке не заполняются.
- **Табличные и шкальные вопросы.**

Для этих типов вопросов параметры в URL игнорируются без ошибок.

---

## 6. Диагностика

Фича не имеет видимой респонденту индикации — вся диагностика идёт в **технический лог интервью** (`saveLog`). Что искать при разборе:

<table id="bkmrk-%D0%97%D0%B0%D0%BF%D0%B8%D1%81%D1%8C-%D0%B2-%D0%BB%D0%BE%D0%B3%D0%B5-%D0%A7%D1%82%D0%BE-%D0%B7%D0%BD"><thead><tr><th>Запись в логе</th><th>Что значит</th></tr></thead><tbody><tr><td>`нет варианта под значение параметра <код>`</td><td>Параметр в ссылке есть, но вариант с таким `userCode` не найден (опечатка в коде варианта, вариант скрыт или `userCode` выключен)</td></tr><tr><td>`неоднозначное совпадение`</td><td>Несколько вариантов имеют одинаковый `userCode` (ошибка настройки опроса)</td></tr><tr><td>`userCode prefill пропущен (D6): ... есть autoSelect`</td><td>Автозаполнение не сработало, потому что в вопросе включён autoSelect (это ожидаемо)</td></tr><tr><td>`вариант(ов) сверх maxAnswers ... отброшено`</td><td>Для чекбокса по ссылке пришло больше вариантов, чем разрешает лимит</td></tr></tbody></table>

**Первый шаг при жалобе «ссылка не подставляет ответ»:** сверить код в URL с `userCode` варианта в настройках опроса (регистр, ведущие нули, пробелы) и убедиться, что `userCode.enabled` включён и на вопросе, и на варианте.

---

## 7. Для разработчиков

**Точка входа данных:** параметры URL разбираются в `src/main.vue` (`forWebApp()`), складываются в профиль (`SET_WEB_INFO`) и доступны как `getMap`. Значения не декодируются, повторный ключ перетирается — см. раздел 3.

**Ядро фичи:**

- `src/assets/utils/userCodePrefill.js` — чистый резолвер `resolveUserCodePrefill(question, map)` и store-guard `isQuestionAnswered(answeredSlides, slideId)`. Без побочных эффектов, покрыт юнит-тестами.
- `src/assets/mixins/radioMixin.js` и `src/assets/mixins/checkBoxMixin.js` — метод `applyUserCodePrefill(...)`, встроенный в существующий механизм автовыбора (`checkAutoSelect` / `change`). Выбранные варианты проходят штатным путём, поэтому квоты, ветвление и отправка работают без изменений.

**Тесты:**

```bash
npm run test:usercode-prefill   # юнит-тесты резолвера (node), + фикстура реального опроса
npm run test:lifecycle          # lifecycle-тесты интеграции в mixin'ы (jsdom)

```

Оба набора включены в `npm run build` и `npm run build-web`.

**Проектная документация:** дизайн-спека и решения D1–D7 — `docs/superpowers/specs/2026-06-10-url-param-autofill-by-usercode-design.md`.

---

## 8. Проверенные сценарии (QA)

Живой прогон на опросе AUTOTEST-12 (`53fb0813`), вопрос «Пол»:

<table id="bkmrk-%D0%A1%D1%86%D0%B5%D0%BD%D0%B0%D1%80%D0%B8%D0%B9-%D0%A0%D0%B5%D0%B7%D1%83%D0%BB%D1%8C%D1%82%D0%B0%D1%82-%3F"><thead><tr><th>Сценарий</th><th>Результат</th></tr></thead><tbody><tr><td>`?sex=1` → выбран «МУЖ»</td><td>✅ Подтверждено (store + DOM)</td></tr><tr><td>`?sex=2` → выбран «ЖЕН»</td><td>✅ Подтверждено</td></tr><tr><td>`?sex=99` (несуществующий код)</td><td>✅ Ничего не выбрано, интервью работает, предупреждение в логе</td></tr><tr><td>Приоритет черновика (D1)</td><td>Покрыто lifecycle-тестами; в web-флоу каждая загрузка стартует новое интервью, поэтому вживую неприменимо</td></tr><tr><td>Чекбокс / autoSelect (D6/D7)</td><td>Покрыто lifecycle-тестами; в эталонном опросе таких вопросов нет — для live-проверки нужен опрос с чекбокс-вопросом и вопросом с autoSelect</td></tr></tbody></table>

# Redirects / HOOKs

# WEB интервью: Redirect/HK и входные параметры

## Для чего это нужно

В WEB интервью ссылка для перехода (Redirect) и ссылка для хука (HK/hooks) могут автоматически получать значения из входной ссылки интервью.

Это позволяет:

- передавать `visit_id`, `project_id`, `source` и другие параметры дальше;
- одинаково обрабатывать обычные завершения и случаи дублей;
- не прописывать руками отдельные URL под каждый запуск.

---

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

### 1) Входные параметры берутся из URL запуска интервью

Пример входной ссылки:

```text
https://app.example.com/?poll_id=1001&visit_id=abc123&project_id=prj55&source=telegram

```

Из неё система запоминает параметры (`poll_id`, `visit_id`, `project_id`, `source` и т.д.).

### 2) В Redirect/HK используются плейсхолдеры

В настройках URL можно писать параметры в виде:

```text
$имя_параметра$

```

При выполнении Redirect/HK эти плейсхолдеры заменяются фактическими значениями.

Пример шаблона:

```text
https://target.example.com/result/$project_id$?visit=$visit_id$&src=$source$

```

Результат:

```text
https://target.example.com/result/prj55?visit=abc123&src=telegram

```

---

## Важные правила

1. Подстановка работает для **всех** параметров, которые пришли во входной ссылке.
2. Подстановка работает и для: 
    - обычных Redirect/HK;
    - сценария дубля (**DOUBLE**).
3. Если параметр отсутствует, вместо него подставляется пустое значение.
4. Спецсимволы в значениях кодируются автоматически (безопасно для URL).

---

## Рекомендации по настройке

- Используйте понятные имена параметров: `visit_id`, `project_id`, `source`, `respondent_id`.
- В шаблоне проверяйте точное совпадение имён: `$visit_id$` и `$visitId$` — это разные ключи.
- Перед боевым запуском прогоните тестовую ссылку и проверьте конечный Redirect URL.

---

## Подробности — в служебных данных

Во вкладке «Служебные данные» параметры запуска доступны полностью, с переносами длинных строк. Это помогает сверить переданные значения без перехода к исходной ссылке.

Здесь же показываются настроенные адреса перенаправления и серверного уведомления — «redirectUrl» и «hookUrl». Они выбираются по статусу интервью из текущих настроек опроса и появляются, если соответствующая настройка включена и адрес задан. Адреса отражают текущие настройки опроса для этого статуса.

![](https://wiki.sociometer.ru/uploads/images/gallery/2026-11/embedded-image-cf5mgwcw.png)