arm-ka-docs/source/tz/АРМ КА.Техническое задание - 09_6. Справочник _Группы компаний и организации_.md

code, title

code	title
DOC-221280	6. Справочник "Группы компаний и организации"

6. Справочник "Группы компаний и организации"

Структура справочника:

ссылка на модель данных: 2. Модель данных (сущности)

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

4. Статусная модель

Ролевая модель справочника:

5. Ролевая модель

Визуальная форма справочника:

Экран открывается из бокового меню, раздел "Справочники", пункт "Справочник: ГК и организации". Заголовок страницы "Группы компаний и организаций", справа кнопка "Импорт из файла". Ниже - панель фильтров, под ней рабочая область из двух панелей:

• левая панель "Группы компаний" - список ГК;
• правая панель - состав выбранной ГК с вкладками "ЮЛ", "ГСК", "ГСЗ".

Фильтры:

• Фильтр "Базовый РФ" - выпадающий список филиалов (значение по умолчанию "Все РФ"), ограничивает список ГК группами выбранного филиала;
• Строка поиска "Поиск по наименованию или ID" - поиск по наименованию и CRM ID группы.

Левая панель "Группы компаний":

Панель отображает все Группы компаний по выбранным фильтрам, а также счетчик компаний и дает возможность создать ГК. Список ГК содержит - наименование ГК, ID ГК в CRM, счетчик организаций.

Правая панель "Состав ГК"

Показывает компании выбранной ГК. В панели существует несколько вкладок:

• ЮЛ - таблица организаций выбранной ГК. Отображаются активные записи, есть возможность активировать чек-бокс "Архив", который делает видимыми архивные компании. На вкладке есть возможность создать новую компанию в выбранном ГК.
• ГСК - таблица со всеми ГСК, входящих в выбранный ГК. На вкладке есть возможность создать новую ГСК в выбранном ГК.
• ГСЗ - таблица со всеми ГСЗ, входящих в выбранный ГК. На вкладке есть возможность создать новую ГСЗ в выбранном ГК.

Модальные окна справочника:

Создать / Изменить группу компаний

Поле	Системное наименование	Правила заполнения	Обязательность
Название ГК	name	ручной ввод	да
ID ГК в CRM	crm_id	ручной ввод при наличии ID из CRM	да, уникальное
Базовый РФ ГК	base_regional_office_id	выбор из regional_office	да

Создать / Изменить юридическое лицо

Поле	Системное наименование	Правила заполнения	Обязательность
ИНН	inn	ручной ввод	да, 10 знаков для ЮЛ и 12 для ИП
ID ЮЛ в CRM	crm_id	ручной ввод	уникальность
Тип	entity_type	выбор: ЮЛ / ИП	да
Наименование организации	name	ручной ввод	да
Альтернативные наименования	legal_entity_alias	ввод синонима (возможно несколько значений)	нет
Входит в ГСК	related_group_member (kind = gsk)	выбор одной ГСК из групп текущей ГК	нет
Входит в ГСЗ	related_group_member (kind = gsz)	выбор одной ГСЗ	нет

Перевести ЮЛ в другую ГК

Снимок прежнего состояния пишется в legal_entity_history , у записи меняется company_group_id.

Поле	Системное наименование	Правила заполнения	Обязательность
ЮЛ	legal_entity.name		нет
Текущая ГК	company_group.name		нет
Новая ГК	company_group_id	выбор из справочника ГК	да
?? Дата перевода	дата события	выбор даты	да

Вывести ЮЛ из состава ГК

Запись переходит в архив с выбранным событием, текущие версии нахождения в ГСК/ГСЗ закрываются.

Поле	Системное наименование	Правила заполнения	Обязательность
ЮЛ	legal_entity.name		-
Событие	тип события	выбор: "Закрытие" / "Переход в другую ГК"	да
Дата закрытия	close_date	выбор даты	да
Комментарий	комментарий события	текст	нет

Создать / Изменить ГСК и ГСЗ

Группа создается в рамках выбранной ГК. Состав участников ведется через поле "Входит в ГСК/ГСЗ" карточки ЮЛ.

Поле	Системное наименование	Правила заполнения	Обязательность
ID ГСК (ГСЗ) в CRM	related_group.code	ручной ввод	уникальность
Наименование	related_group.name	ручной ввод	да
Дата создания	related_group.created_date	выбор даты	да

Импорт групп компаний из файла

Маппинг: ИНН -> legal_entity.inn, Наименование -> legal_entity.name, Тип -> legal_entity.entity_type, Базовый РФ ГК -> regional_office (поиск по наименованию), ID ГК -> company_group.crm_id (поиск существующей ГК, при отсутствии - создание). Строка с ошибкой не импортируется: сообщение пишется в лог, обработка продолжается со следующей строки. Дубль ИНН обрабатывается по выбранной стратегии - пропуск или обновление записи.

Итоговая визуальная форма созданных записей:

ИНН	iD ГК	Базовый РФ ГК в CRM	Группа компаний	Организация	входит в ГСК	входит в ГСЗ	Тип
//поиск по полю	//поиск по полю	//поиск по полю	//поиск по полю	//поиск по полю	//поиск по полю	//поиск по полю	//поиск по полю
1626011106	1-5A6WW8Q	Татарстанский РФ	РМ Агро	ООО АПК "Продовольственная Программа"	да	да	ЮЛ
1626011089	1-5A6WW8Q	Татарстанский РФ	РМ Агро	ООО "РМ Агро"	да	да	ЮЛ
162600787296	1-5A6WW8Q	Татарстанский РФ	РМ Агро	ИП Мутигуллин Р.М.	да		ИП
3606007641	1-5APQRQT	Воронежский РФ	Молвест	ООО Мамоновские фермы	да	входит в ГСЗ	ЮЛ
3601011500	1-5APQRQT	Воронежский РФ	Молвест	ООО ЭкоКорм	да	входит в ГСЗ	ЮЛ
3662104342	1-5APQRQT	Воронежский РФ	Молвест	ООО Партнер – МК			ЮЛ
3612007495	1-5APQRQT	Воронежский РФ	Молвест	ООО Новомарковское			ЮЛ
3606000283	1-5APQRQT	Воронежский РФ	Молвест	ОАО Завод молочный Верхнемамонский			ЮЛ
3603004667	1-5APQRQT	Воронежский РФ	Молвест	ОАО Богучармолоко			ЮЛ
3601011404	1-5APQRQT	Воронежский РФ	Молвест	ЗАО Агрокомбинат Николаевский			ЮЛ
7743096552	1-5APQRQT	Воронежский РФ	Молвест	ООО РОСОМУ			ЮЛ
3612006533	1-5APQRQT	Воронежский РФ	Молвест	ООО Продвижение			ЮЛ
2321003134	1-5APQRQT	Воронежский РФ	Молвест	ЗАО Сыркомбинат Тихорецкий			ЮЛ
7303004208	1-5APQRQT	Воронежский РФ	Молвест	ОАО Молочный завод			ЮЛ
3606007673	1-5APQRQT	Воронежский РФ	Молвест	ООО Луч			ЮЛ

Пользовательские сценарии:

схема процесса

UC-01 Добавление нового РФ

UC-01: Добавление регионального филиала (Базовый РФ)

Общая информация

Параметр	Значение
ID	UC-01
Название	Добавление регионального филиала (Базовый РФ)
Основной актер	Администратор
Вторичные актеры	Система, Администратор
Предусловия	Пользователь авторизован, имеет роль Администратор или выше

Основной поток (Basic Flow)

1. Пользователь открывает справочник Состав групп компаний.
2. В тулбаре нажимает кнопку Добавить региональный филиал.
3. Система открывает модальное окно с формой:
   • region_code (varchar(20)) — ручной ввод, обязательно, проверка на уникальность
   • region_name (varchar(100)) — ручной ввод, обязательно
   • crm_system_id (varchar(50)) — ручной ввод, опционально
   • description (text) — опционально
4. Пользователь заполняет обязательные поля и нажимает Сохранить.
5. Система валидирует данные:
   • Проверка уникальности region_code
   • Проверка формата полей
6. При успешной валидации система создает запись в ref_crm_region со статусом active.
7. Система закрывает модальное окно, обновляет список, показывает уведомление Региональный филиал успешно добавлен.
8. Система записывает действие в аудит-лог.

Альтернативные потоки

A1: Ошибка валидации (дубликат region_code)

• На шаге 5 система обнаруживает, что region_code уже существует.
• Система показывает ошибку: Код региона уже существует.
• Пользователь исправляет значение или отменяет операцию.
• Возврат к шагу 4.

A2: Отмена создания

• На шаге 4 пользователь нажимает Отмена .
• Система закрывает модальное окно без сохранения.
• Возврат к шагу 1.

Постусловия

• Новая запись в ref_crm_region доступна для выбора при создании группы компаний.
• Запись отображается в справочнике с возможностью поиска.

UC-02 Добавление новой ГК

UC-02: Создание группы компаний

Общая информация

Параметр	Значение
ID	UC-02
Название	Создание группы компаний
Основной актер	Аналитик
Предусловия	Пользователь авторизован; существует хотя бы один региональный филиал в ref_crm_region

Основной поток

1. Пользователь открывает справочник нажимает Добавить группу компаний .
2. Система открывает модальное окно с формой:

Поле	Системное имя	Тип	Обязательность	Валидация
Идентификатор в справочнике	group_id	auto	да	автогенерация (UUID или последовательность)
ID Группы в CRM	crm_group_id	varchar(20)	нет	уникальность, формат ^1-[A-Z0-9]{7}$
Наименование группы	group_name	varchar(200)	да	—
Региональный филиал	region_code	FK ref_crm_region	да	выбор из справочника
Статус	status	enum	нет	по умолчанию active

1. Пользователь заполняет данные нажимает Сохранить.
2. Система валидирует:
   • Уникальность crm_group_id (если заполнен)
   • Наличие region_code в справочнике
3. Система показывает уведомление, обновляет список.

Альтернативные потоки

A1: CRM ID не соответствует формату

• Если crm_group_id не соответствует паттерну ^1-[A-Z0-9]{7}$, система показывает предупреждение: ID группы в CRM должен иметь формат 1-XXXXXXX.
• Пользователь может исправить или сохранить без CRM ID.

A2: Группа с таким наименованием уже существует

• Система проверяет уникальность group_name в пределах region_code.
• При дубликате: ошибка Группа с таким именем уже существует в выбранном регионе.

Постусловия

• Группа создан, готова к добавлению организаций.
• Запись доступна для редактирования и поиска.

UC-03 Добавление организации

UC-03: Добавление организации в группу

Общая информация

Параметр	Значение
ID	UC-03
Название	Добавление организации в группу
Основной актер	Аналитик
Предусловия	Существует активная группа в consolidation_group ; пользователь имеет роль Аналитик

Основной поток

1. Пользователь нажимает кнопку Добавить организацию в тулбаре.
2. Система открывает модальное окно с формой:

Поле	Системное имя	Тип	Обязательность	Примечание
Группа	group_id	FK	да	выбор из consolidation_group
Наименование организации	full_name	varchar(300)	да	—
ИНН	inn	varchar(12)	да	уникальность, 10/12 знаков по типу
Тип организации	org_type_code	FK ref_org_type	да	ЮЛ, ИП, ФЛ, нерез.
Базовый РФ ГК	region_code	FK ref_crm_region	да	автозаполнение из группы
Флаг ГСК	is_gsk	boolean	нет	по умолчанию false
Флаг ГСЗ	is_gsz	boolean	нет	по умолчанию false

1. Пользователь заполняет форму нажимает Сохранить.
2. Система валидирует:
   • Уникальность inn в пределах Organizations
   • Соответствие длины ИНН типу организации (10 для ЮЛ, 12 для ИП)
   • Наличие group_id в consolidation_group
3. При успехе система:
   • Создает запись в Organizations (если ИНН новый)
   • Создает запись в group_membership с membership_from = CURRENT_DATE
4. Система показывает уведомление, обновляет список.

Альтернативные потоки

A1: Организация с таким ИНН уже существует

• Система находит существующую организацию по inn.
• Предлагает пользователю: Организация с таким ИНН уже существует.

A2: Некорректный формат ИНН

• Если длина ИНН не соответствует типу (например, 11 знаков для ЮЛ), система показывает ошибку.
• Пользователь исправляет или меняет тип организации.

A3: Попытка добавить организацию в архивную группу

• Если consolidation_group.status = archived, система блокирует действие с сообщением: Нельзя добавить организацию в архивную группу.

Постусловия

• Организация привязана к группе через group_membership.
• Запись отображается в итоговой форме справочника.

UC-04 Редактирование текущей организации

UC-03: Редактирование карточки организации

Общая информация

Параметр	Значение
ID	UC-03
Название	Редактирование карточки организации
Основной актер	Аналитик
Предусловия	Существует активная группа в consolidation_group ; пользователь имеет роль Аналитик

Основной поток

1. Пользователь выбирает в списочной форме запись с нужной организацией (поиск по ИНН, наименованию организации, наименованию текущей привязанной ГК и так далее) и двойным кликом по записи открывает запись
2. Система открывает модальное окно с формой:

Поле	Системное имя	Тип	Обязательность	Примечание
Группа	group_id	FK	да	выбор из consolidation_group
Наименование организации	full_name	varchar(300)	да	—
ИНН	inn	varchar(12)	да	уникальность, 10/12 знаков по типу
Тип организации	org_type_code	FK ref_org_type	да	ЮЛ, ИП, ФЛ, нерез.
Базовый РФ ГК	region_code	FK ref_crm_region	да	автозаполнение из группы
Флаг ГСК	is_gsk	boolean	нет	по умолчанию false
Флаг ГСЗ	is_gsz	boolean	нет	по умолчанию false

1. Пользователь редактирует форму (указывает иную ГК, меняет тип ЮЛ, редактирует ИНН, проставляет чекбоксы ГСК и ГСЗ) нажимает Сохранить.
2. Система валидирует:
   • Уникальность inn в пределах Organizations
   • Соответствие длины ИНН типу организации (10 для ЮЛ, 12 для ИП)
   • Наличие group_id в consolidation_group
3. При успехе система:
   • Создает запись в Organizations (если ИНН новый)
4. Система показывает уведомление, обновляет список.

Альтернативные потоки

A1: Организация с таким ИНН уже существует

• Система находит существующую организацию по inn.
• Предлагает пользователю: Организация с таким ИНН уже существует.

A2: Некорректный формат ИНН

• Если длина ИНН не соответствует типу (например, 11 знаков для ЮЛ), система показывает ошибку.
• Пользователь исправляет или меняет тип организации.

A3: Попытка добавить организацию в архивную группу

• Если consolidation_group.status = archived, система блокирует действие с сообщением: Нельзя добавить организацию в архивную группу.

Постусловия

• Организация привязана к группе через group_membership.
• Запись отображается в итоговой форме справочника.

UC-05 Импорт записей справочника из внешней CRM

UC-04: Импорт данных из Excel-файла

Общая информация

Параметр	Значение
ID	UC-04
Название	Импорт данных из Excel-файла
Основной актер	Администратор
Предусловия	Файл подготовлен в формате .xls/.xlsx ; структура соответствует маппингу

Основной поток

1. Пользователь нажимает кнопку Импорт  в тулбаре.
2. Система открывает модальное окно выбора файла.
3. Пользователь выбирает файл нажимает Загрузить .
4. Система читает файл, отображает предпросмотр с маппингом колонок:

Колонка Excel	Целевое поле	Обязательность
ИНН	organization.inn	да
iD ГК	consolidation_group.group_id	да
Базовый РФ ГК в CRM	consolidation_group.region_code	да
Группа компаний	consolidation_group.group_name	да
Организация	organization.full_name	да
ГСК	group_membership.is_gsk	нет
ГСЗ	group_membership.is_gsz	нет
Тип	organization.org_type_code	да

1. Пользователь подтверждает импорт система начинает обработку.

2. Для каждой строки файла:

   • Валидация обязательных полей
   • Проверка уникальности inn и group_id
   • Создание/обновление записей в consolidation_group , organization , group_membership
   • При ошибке: запись в лог, переход к следующей строке

3. По завершении система показывает отчет:

   1
   2
   3

4. Пользователь может скачать детальный лог импорта.

Альтернативные потоки

A1: Файл не соответствует формату

• Если файл не .xls/.xlsx или структура не соответствует маппингу, система возвращает ошибку на шаге 4.
• Предложение: Скачать шаблон файла для импорта.

A2: Критическая ошибка валидации

• Если 20% строк содержат ошибки, система останавливает импорт и запрашивает подтверждение: Продолжить импорт с пропуском ошибочных строк?

A3: Конфликт данных (дубль ИНН)

• При обнаружении дубликата inn система:
  • Не создает новую организацию
  • Создает запись в group_membership для существующей организации (если группа другая)
  • Записывает предупреждение в лог

Постусловия

• Успешные строки отражены в справочнике.
• Ошибочные строки зафиксированы в логе для ручной обработки.
• Все изменения записаны в аудит.

Бизнес-правила

• Пустые значения в необязательных полях ( is_gsk , is_gsz ) интерпретируются как false .