Уникальное поле идентификатора

Создайте автоматически сгенерированные уникальные идентификаторы с последовательной нумерацией и пользовательским форматированием

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

Простой пример

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

mutation CreateUniqueIdField {
  createCustomField(input: {
    name: "Ticket Number"
    type: UNIQUE_ID
    useSequenceUniqueId: true
  }) {
    id
    name
    type
    useSequenceUniqueId
  }
}

Расширенный пример

Создайте отформатированное поле уникального идентификатора с префиксом и нулями в начале:

mutation CreateFormattedUniqueIdField {
  createCustomField(input: {
    name: "Order ID"
    type: UNIQUE_ID
    description: "Auto-generated order identifier"
    useSequenceUniqueId: true
    prefix: "ORD-"
    sequenceDigits: 4
    sequenceStartingNumber: 1000
  }) {
    id
    name
    type
    description
    useSequenceUniqueId
    prefix
    sequenceDigits
    sequenceStartingNumber
  }
}

Входные параметры

CreateCustomFieldInput (UNIQUE_ID)

Параметр	Тип	Обязательный	Описание
`name`	String!	✅ Да	Отображаемое имя поля уникального идентификатора
`type`	CustomFieldType!	✅ Да	Должен быть `UNIQUE_ID`
`description`	String	Нет	Текст помощи, отображаемый пользователям
`useSequenceUniqueId`	Boolean	Нет	Включить автоматическую нумерацию (по умолчанию: ложь)
`prefix`	String	Нет	Текстовый префикс для сгенерированных идентификаторов (например, "ЗАДАЧА-")
`sequenceDigits`	Int	Нет	Количество цифр для нулей в начале
`sequenceStartingNumber`	Int	Нет	Начальное число для последовательности

Опции конфигурации

Автоматическая нумерация (`useSequenceUniqueId`)

true: Автоматически генерирует последовательные идентификаторы при создании записей
false или undefined: Требуется ручной ввод (работает как текстовое поле)

Префикс (`prefix`)

Необязательный текстовый префикс, добавляемый ко всем сгенерированным идентификаторам
Примеры: "ЗАДАЧА-", "ЗАКАЗ-", "БАГ-", "ЗАПРОС-"
Нет ограничения по длине, но оставьте разумным для отображения

Цифры последовательности (`sequenceDigits`)

Количество цифр для нулей в начале номера последовательности
Пример: sequenceDigits: 3 производит 001, 002, 003
Если не указано, дополнение не применяется

Начальное число (`sequenceStartingNumber`)

Первое число в последовательности
Пример: sequenceStartingNumber: 1000 начинается с 1000, 1001, 1002...
Если не указано, начинается с 1 (поведение по умолчанию)

Формат сгенерированного идентификатора

Финальный формат идентификатора объединяет все параметры конфигурации:

{prefix}{paddedSequenceNumber}

Примеры формата

Конфигурация	Сгенерированные идентификаторы
Без опций	`1`, `2`, `3`
`prefix: "TASK-"`	`TASK-1`, `TASK-2`, `TASK-3`
`sequenceDigits: 3`	`001`, `002`, `003`
`prefix: "ORD-", sequenceDigits: 4`	`ORD-0001`, `ORD-0002`, `ORD-0003`
`prefix: "BUG-", sequenceStartingNumber: 500`	`BUG-500`, `BUG-501`, `BUG-502`
All options combined	`TASK-1001`, `TASK-1002`, `TASK-1003`

Чтение значений уникального идентификатора

Запрос записей с уникальными идентификаторами

query GetRecordsWithUniqueIds {
  todos(filter: { projectIds: ["proj_123"] }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
        prefix
        sequenceDigits
      }
      sequenceId    # The generated sequence number
      text         # The text value for UNIQUE_ID fields
    }
  }
}

Формат ответа

{
  "data": {
    "todos": [
      {
        "id": "todo_123",
        "title": "Fix login issue",
        "customFields": [
          {
            "id": "field_value_456",
            "customField": {
              "name": "Ticket Number",
              "type": "UNIQUE_ID",
              "prefix": "TASK-",
              "sequenceDigits": 3
            },
            "sequenceId": 42,
            "text": "TASK-042"
          }
        ]
      }
    ]
  }
}

Автоматическая генерация идентификаторов

Когда идентификаторы генерируются

Создание записи: Идентификаторы автоматически назначаются при создании новых записей
Добавление поля: При добавлении поля UNIQUE_ID к существующим записям ставится в очередь фоновая задача (реализация рабочего процесса ожидается)
Фоновая обработка: Генерация идентификаторов для новых записей происходит синхронно через триггеры базы данных

Процесс генерации

Триггер: Создается новая запись или добавляется поле UNIQUE_ID
Поиск последовательности: Система находит следующий доступный номер последовательности
Назначение идентификатора: Номер последовательности назначается записи
Обновление счетчика: Счетчик последовательности увеличивается для будущих записей
Форматирование: Идентификатор форматируется с префиксом и дополнением при отображении

Гарантии уникальности

Ограничения базы данных: Уникальное ограничение на идентификаторы последовательности в каждом поле
Атомарные операции: Генерация последовательности использует блокировки базы данных для предотвращения дубликатов
Область проекта: Последовательности независимы для каждого проекта
Защита от условий гонки: Параллельные запросы обрабатываются безопасно

Ручной режим против автоматического

Автоматический режим (`useSequenceUniqueId: true`)

Идентификаторы автоматически генерируются через триггеры базы данных
Последовательная нумерация гарантирована
Атомарная генерация последовательности предотвращает дубликаты
Отформатированные идентификаторы объединяют префикс + дополненный номер последовательности

Ручной режим (`useSequenceUniqueId: false` или `undefined`)

Работает как обычное текстовое поле
Пользователи могут вводить пользовательские значения через setTodoCustomField с параметром text
Нет автоматической генерации
Нет обеспечения уникальности, кроме ограничений базы данных

Установка ручных значений (только ручной режим)

Когда useSequenceUniqueId ложно, вы можете установить значения вручную:

mutation SetUniqueIdValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    text: "CUSTOM-ID-001"
  })
}

Поля ответа

Ответ TodoCustomField (UNIQUE_ID)

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор для значения поля
`customField`	CustomField!	Определение пользовательского поля
`sequenceId`	Int	Сгенерированный номер последовательности (заполняется для полей UNIQUE_ID)
`text`	String	Отформатированное текстовое значение (объединяет префикс + дополненная последовательность)
`todo`	Todo!	Запись, к которой принадлежит это значение
`createdAt`	DateTime!	Когда значение было создано
`updatedAt`	DateTime!	Когда значение было в последний раз обновлено

Ответ CustomField (UNIQUE_ID)

Поле	Тип	Описание
`useSequenceUniqueId`	Boolean	Включена ли автоматическая нумерация
`prefix`	String	Текстовый префикс для сгенерированных идентификаторов
`sequenceDigits`	Int	Количество цифр для нулей в начале
`sequenceStartingNumber`	Int	Начальное число для последовательности

Необходимые разрешения

Действие	Необходимое разрешение
Create unique ID field	`OWNER` or `ADMIN` role at project level
Update unique ID field	`OWNER` or `ADMIN` role at project level
Set manual value	Standard record edit permissions
View unique ID value	Standard record view permissions

Ошибки ответов

Ошибка конфигурации поля

{
  "errors": [{
    "message": "Invalid sequence configuration",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

Ошибка разрешения

{
  "errors": [{
    "message": "CustomField not found",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Важные заметки

Автоматически сгенерированные идентификаторы

Только для чтения: Автоматически сгенерированные идентификаторы не могут быть отредактированы вручную
Постоянные: После назначения идентификаторы последовательности не меняются
Хронологические: Идентификаторы отражают порядок создания
Область: Последовательности независимы для каждого проекта

Соображения по производительности

Генерация идентификаторов для новых записей происходит синхронно через триггеры базы данных
Генерация последовательности использует FOR UPDATE блокировки для атомарных операций
Система фоновых задач существует, но реализация рабочего процесса ожидается
Учитывайте начальные номера последовательности для проектов с высоким объемом

Миграция и обновления

Добавление автоматической нумерации к существующим записям ставит в очередь фоновую задачу (ожидается реализация рабочего процесса)
Изменение настроек последовательности влияет только на будущие записи
Существующие идентификаторы остаются неизменными при обновлении конфигурации
Счетчики последовательности продолжают с текущего максимума

Лучшие практики

Дизайн конфигурации

Выбирайте описательные префиксы, которые не будут конфликтовать с другими системами
Используйте соответствующее дополнение цифр для ожидаемого объема
Устанавливайте разумные начальные числа, чтобы избежать конфликтов
Тестируйте конфигурацию с образцами данных перед развертыванием

Планирование последовательности

Оцените объем ваших записей, чтобы выбрать соответствующее дополнение цифр
Учитывайте будущий рост при установке начальных чисел
Планируйте разные диапазоны последовательностей для разных типов записей
Документируйте ваши схемы идентификаторов для справки команды

Общие случаи использования

Системы поддержки
- Номера билетов: TICK-001, TICK-002
- Идентификаторы дел: CASE-2024-001
- Запросы на поддержку: SUP-001
Управление проектами
- Идентификаторы задач: TASK-001, TASK-002
- Элементы спринта: SPRINT-001
- Номера поставок: DEL-001
Бизнес-операции
- Номера заказов: ORD-2024-001
- Идентификаторы счетов: INV-001
- Заказы на покупку: PO-001
Управление качеством
- Отчеты об ошибках: BUG-001
- Идентификаторы тестовых случаев: TEST-001
- Номера обзоров: REV-001

Интеграционные функции

С автоматизацией

Запускайте действия, когда назначаются уникальные идентификаторы
Используйте шаблоны идентификаторов в правилах автоматизации
Ссылайтесь на идентификаторы в шаблонах электронной почты и уведомлениях

С поисками

Ссылайтесь на уникальные идентификаторы из других записей
Находите записи по уникальному идентификатору
Отображайте идентификаторы связанных записей

С отчетностью

Группируйте и фильтруйте по шаблонам идентификаторов
Отслеживайте тенденции назначения идентификаторов
Мониторьте использование последовательностей и пробелы

Ограничения

Только последовательные: Идентификаторы назначаются в хронологическом порядке
Без пробелов: Удаленные записи оставляют пробелы в последовательностях
Без повторного использования: Номера последовательностей никогда не повторяются
Область проекта: Нельзя делиться последовательностями между проектами
Ограничения формата: Ограниченные варианты форматирования
Без массовых обновлений: Нельзя массово обновлять существующие идентификаторы последовательностей
Без пользовательской логики: Нельзя реализовать пользовательские правила генерации идентификаторов

Связанные ресурсы

Текстовые поля - Для ручных текстовых идентификаторов
Числовые поля - Для числовых последовательностей
Обзор пользовательских полей - Общие концепции
Автоматизация - Для правил автоматизации на основе идентификаторов