Config Modification

---
name: config-modification
description: "Используй, когда задача касается прямого изменения типового кода вендора, выбора точки перехвата, устойчивой к обновлению вендором, маркеров COMMENT_*, расширений конфигурации и директив &Перед, &После, &Вместо, &ИзменениеИКонтроль, #Вставка, #Удаление, ПродолжитьВызов, перехвата обработчика события формы или её элемента в расширении, заимствованных объектов, назначения расширения или документирования экспортных методов. Это скилл о том, как оформить доработку; перенос уже существующей доработки из типового объекта в расширение ведёт extract-to-extension."
---

# Паттерны доработки типовой конфигурации

> Нормы кода — в `.claude/rules/1c-rules.md` (единственный источник правил).
> Здесь — развёрнутые паттерны и примеры «как именно».
> Приоритет способа доработки (подписки > расширения > изменение типового кода) — норма в 1c-rules.md.

## Имена в расширении: префикс основной конфигурации ≠ префикс расширения

> Где префикс обязателен и где не нужен — норма в `.claude/rules/1c-rules.md` (### Именование метаданных).

Не путать два механизма именования:
- **Префикс основной конфигурации** — из строки `src\cf` таблицы каталогов исходников в `CLAUDE.md`.
- **Префикс расширения** — из строки этого расширения в той же таблице; задаётся в свойствах расширения (`Расш1_`, `МоеРасш_`).

При работе в существующем расширении используй его префикс. Например, расширение с префиксом `Расш1_` может добавить реквизит `Расш1_Признак` типовому объекту и определить перехватчик `Расш1_ПриЗаписи` в том же модуле — при заимствовании процедуры конфигуратор подставляет этот префикс сам. Внутри собственного общего модуля расширения методы префикса не требуют: имя модуля уже префиксовано. Префикс, как и всё в коде, — без буквы «ё».

## Паттерн: выбор точки встраивания

> Приоритет способа доработки — норма в `.claude/rules/1c-rules.md` (### Архитектура).
> Здесь — как найти точку и чем платят за каждую.

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

| Точка | Цена при обновлении |
|---|---|
| Обёртка над методом, пустым в поставке (переопределяемый метод конфигурации или БСП) | тело не копируется, и перекрывать в пустом методе нечего |
| Обёртка над типовым методом (`&Перед`/`&После`, `&Вместо` + `ПродолжитьВызов()`) | тело не копируется, но вендор может изменить логику вокруг молча |
| Копия тела (`&ИзменениеИКонтроль`) | правку вендора платформа покажет ошибкой применения, перехватчик пересобирается руками |

**Точку ищут, а не вспоминают.** Два хода, оба дешёвые:

1. **Посмотри вызывающий метод.** Вставка в середину частного метода часто оказывается вставкой
   в конец вызывающего — а это уже обёртка вместо копии тела.
2. **Поищи рядом переопределяемый метод.** В типовых конфигурациях и на БСП это общий модуль
   с постфиксом `Переопределяемый` и процедура, пустая в поставке. Ценно то, что вендор вызывает
   её из той же середины, где лежит правка: позиция в потоке сохраняется, а копия тела не нужна.
   Соглашение принадлежит конфигурациям, а не платформе — в самописной базе искать нечего.
   Убедись, что в нужной ветке метод действительно вызывается: перехватчик полезен, только если
   доказано, что цепочка до него доходит.

Добавление реквизита типовому объекту сверь с механизмом дополнительных реквизитов и сведений,
если конфигурация его несёт: реквизит расширения меняет структуру данных, дополнительное
свойство — нет.

**Другая точка — другой момент исполнения.** Меняются доступные данные, состояние объекта,
границы транзакции, порядок относительно другого кода. Эквивалентность поведения доказывается
разбором этих четырёх вещей, а не предполагается. Не смог показать, что поведение сохраняется, —
встраивайся там же, где правка лежала, и скажи, какой вариант отверг.

**Где остановиться.** Если устойчивая точка требует новых объектов метаданных или
переделки механизма, это уже не оформление доработки, а новая разработка. Скажи об этом
и не начинай её молча.

## Паттерн: директивы расширения (по выбору механизма)

Что выбирать — норма в `1c-rules.md` (### Архитектура): задача решается обёрткой — бери обёртку;
копия типового тела через `&ИзменениеИКонтроль` берётся только тогда, когда правка идёт в середину
метода. Здесь примеры каждого варианта.

> Директива — не единственный способ перехвата. У обработчиков событий формы и её элементов
> есть свой механизм, и в формах он основной — см. «Паттерн: перехват события формы».

**Чем платят за перехват.** Главная цена — копия типового кода в расширении: она живёт своей жизнью
и требует пересборки, когда вендор трогает метод. Обёртки (`&Перед`, `&После`, `&Вместо`
с `ПродолжитьВызов()`) не копируют ничего и обновление переживают. `&ИзменениеИКонтроль` копирует
метод целиком — и получает взамен контроль платформы, который громко сообщит о расхождении.
`&Вместо` без `ПродолжитьВызов()` не копирует, но и типовой код не выполняет — о расхождении
не сообщит никто.

**Сколько перехватчиков заводить.** Один перехватываемый метод — один перехватчик на тип вызова
(норма в `.claude/rules/1c-rules.md`, ### Архитектура). Несколько доработок одного метода живут
внутри одного перехватчика, каждая со своими маркерами, а не в нескольких `&После` подряд. Разные
задачи и разные даты доработок поводом развести перехватчики не являются — это история правок,
а не архитектура. Разные типы вызова (`&Перед` и `&После` на один метод) допустимы, когда этого
требует логика.

Что делать, если перехватчик над этим методом уже есть в другом расширении, — «Паттерн: несколько
расширений над одним методом».

### 1. &Перед / &После — обёртка без копии, только процедуры

Дополняют типовой метод, не заменяя его. `ПродолжитьВызов()` вызывать НЕ нужно — типовой метод отрабатывает сам.

Перехватчики соседних расширений не подавляют, поэтому среди обёрток это первый выбор. Только для процедур — норма и источник в `1c-rules.md` (### Архитектура). Обёртка функции — `&Вместо` ниже.

```bsl
&НаСервере
&Перед("ПриЗаписи")
Процедура Расш1_ПриЗаписи()
    // Выполнится ДО типового ПриЗаписи
КонецПроцедуры

&НаСервере
&После("ПриЗаписи")
Процедура Расш1_ПослеЗаписи()
    // Выполнится ПОСЛЕ типового ПриЗаписи
КонецПроцедуры
```

### 2. &Вместо + ПродолжитьВызов() — обёртка для функции

Тело типового метода в расширение не копируется: оно вызывается через `ПродолжитьВызов()`. Это единственная обёртка, доступная функции: можно поправить параметры на входе, результат на выходе или условно не вызывать оригинал вовсе. Обновление вендора такой перехватчик переживает — он не знает тела метода.

Цена — `&Вместо` молча подавляет перехватчики расширений, лежащих ниже по порядку применения («Паттерн: несколько расширений над одним методом»). Поэтому там, где процедуре хватает `&Перед`/`&После`, берут их.

Вторая цена — обратная сторона дешевизны: платформа типовое тело не контролирует, и когда вендор изменит его смысл, обёртка продолжит работать на прежних допущениях молча. При обновлении такие перехватчики перепроверяют глазами.

```bsl
&НаСервере
&Вместо("РассчитатьСумму")
Функция Расш1_РассчитатьСумму(Параметры)
    // Своя логика ДО
    Результат = ПродолжитьВызов(Параметры); // без него типовой метод не выполнится
    // Своя логика ПОСЛЕ
    Возврат Результат;
КонецФункции
```

### 3. &ИзменениеИКонтроль — правка внутри тела (с 8.3.15)

Когда обёртка задачу не выражает и вмешаться надо в середину: вставить между типовыми операторами, заменить или убрать фрагмент. Тело перехватчика содержит КОПИЮ оригинального кода; правки вносишь директивами `#Удаление` (исключить фрагмент оригинала) и `#Вставка` (добавить своё). `ПродолжитьВызов()` НЕ используется — оригинал уже в теле метода. Такой перехватчик допустим только один на метод во всей конфигурации.

**Что именно контролирует платформа.** Она берёт текст метода за вычетом блоков `#Вставка` — должен получиться исходный текст типового метода — и сверяет его с конфигурацией. Отсюда два следствия, которые и определяют оформление:

- внутри `#Удаление` типовые строки лежат **дословно и не закомментированными**: закомментируешь или удалишь — контролируемый текст перестанет совпадать, и метод попадёт в список ошибок применения расширения;
- в контролируемой части не должно быть ничего своего, **включая пояснительные комментарии**: добавленный комментарий тоже участвует в сверке. Всё своё — код, комментарии, маркеры доработок — только внутри `#Вставка` (норма о маркерах — в разделе «Маркеры доработок» `1c-rules.md`, если они в проекте применяются).

Если вендор изменит метод при обновлении, контроль сработает: Конфигуратор предложит восстановить соответствие, а вставки нужно перепроверить.

```bsl
&НаСервере
&ИзменениеИКонтроль("ОбработкаЗаполнения")
Процедура Расш1_ОбработкаЗаполнения(ДанныеЗаполнения, СтандартнаяОбработка)
    ЗаполнитьЗначенияСвойств(ЭтотОбъект, ДанныеЗаполнения);
    #Удаление
    ТиповаяИнициализация();
    #КонецУдаления
    #Вставка
    ДополнительнаяИнициализация(ДанныеЗаполнения);
    #КонецВставки
КонецПроцедуры
```

❌ Так контроль сломается — типовая строка закомментирована, а в контролируемой части появился чужой комментарий:

```bsl
Процедура Расш1_ОбработкаЗаполнения(ДанныеЗаполнения, СтандартнаяОбработка)
    // Оригинальный код типовой процедуры
    ЗаполнитьЗначенияСвойств(ЭтотОбъект, ДанныеЗаполнения);
    #Удаление
    // ТиповаяИнициализация();
    #КонецУдаления
```

### 4. &Вместо без ПродолжитьВызов() — полное замещение (крайний случай)

Типовой метод не выполняется вовсе. Допустимо, только когда он намеренно не должен работать; обоснуй решение и перепроверяй его после обновления конфигурации.

Если же ты копируешь тело метода в перехватчик и правишь копию — это не замещение, а правка внутри тела, и её место в `&ИзменениеИКонтроль`. Ровно этого требует официальная диагностика [`v8cs:change-and-validate-instead-of-around`](https://v8std.ru/diagnostics/v8-code-style/change-and-validate-instead-of-around/): «можно использовать аннотацию &ИзменениеИКонтроль вместо аннотации &Вместо в тех случаях, когда внутри метода отсутствует вызов ПродолжитьВызов». Разница практическая: `&ИзменениеИКонтроль` сверит копию с вендорской и сообщит о расхождении, `&Вместо` — нет.

❌ Так диагностика сработает — типовой код закомментирован и подменён своим:

```bsl
&Вместо("МояФункция")
Функция Расш1_МояФункция()
	//Возврат 1;
	Возврат 2;
КонецФункции
```

✅ То же самое, выраженное как правка тела:

```bsl
&ИзменениеИКонтроль("МояФункция")
Функция Расш1_МояФункция()
	#Удаление
	Возврат 1;
	#КонецУдаления
	#Вставка
	Возврат 2;
	#КонецВставки
КонецФункции
```

## Паттерн: перехват события формы

Обработчики событий формы и её элементов перехватываются **не директивой, а привязкой к событию**
в палитре свойств. Причина: у таких обработчиков нет фиксированных имён, они назначаемые, и
директиве `&После("Имя")` не за что зацепиться. Официально — [1С:Зазеркалье, «Расширение
модулей»](https://wonderland.v8.1c.ru/blog/rasshirenie-moduley/): «При перехвате обработчиков
событий в форме, вам нужно использовать не аннотации, а палитру свойств».

Выбор механизма — норма в 1c-rules.md (### Архитектура). Коротко: в форме берёшь событие;
директиву — только когда метод не является обработчиком события или нужно вмешаться в середину
типового обработчика (тогда `&ИзменениеИКонтроль`).

В модуле расширения это обычная процедура **без директивы расширения** — только с директивой
компиляции:

```bsl
&НаКлиенте
Процедура Расш1_СуммаДокументаПриИзмененииВместо(Элемент)

	ПродолжитьВызов();   // типовой обработчик; без него не выполнится

КонецПроцедуры
```

Весь перехват описан в `Form.xml` расширения:

```xml
<Events>
	<Event name="OnChange" callType="Override">Расш1_СуммаДокументаПриИзмененииВместо</Event>
</Events>
```

Что важно знать про эту запись:

| В выгрузке | В палитре свойств |
|---|---|
| `callType="Before"` | «Перед» |
| `callType="After"` | «После» |
| `callType="Override"` | «Вместо» |
| `callType` отсутствует | не перехват, а обычная привязка обработчика собственной формы расширения |

- Секция `<Events>` бывает и у формы (обработчики формы), и внутри элемента (обработчики элемента).
- На одно событие можно повесить два перехватчика разом — например «Перед» и «После».
- Работает и когда типового обработчика нет вовсе: тогда обработается событие, которое типовая
  конфигурация не обрабатывает.
- Имя обработчика Конфигуратор формирует сам — префикс расширения плюс суффикс типа вызова.
- **Это правка XML расширения**, а не только модуля. Значит на неё распространяется строка
  «XML: метаданные объектов расширений» таблицы полномочий `CLAUDE.md`. Режим не `изменять` —
  выдавай инструкцию для Конфигуратора, а код обработчика прикладывай готовым.
- Поиском по `&Перед`/`&После` такой перехват **не находится**: в модуле директивы нет. Искать
  надо в `Form.xml` расширений.

## Паттерн: конфигурация переназначает действия элементов формы

Отдельные конфигурации сами меняют действия элементов формы на свои диспетчеры. Любое переопределение действия — привязкой к событию, платформенным `УстановитьДействие()`, программным построителем форм — конкурирует с таким механизмом за одно и то же свойство элемента. Оба работают молча, побеждает отработавший вторым: либо элемент выпадает из механизма конфигурации, либо не вызывается наш обработчик.

Проявление в УТ (проверено по исходникам УТ 11.5.19.68) — «контроль несогласованных изменений»:

- `ОбщегоНазначенияУТ.УстановитьПодпискуНаСобытияИзмененияЭлементовФормы(Форма, ИменаЭлементов, Установить)` подменяет действия перечисленных элементов на `Подключаемый_<Событие>_УстановитьДоступностьЭлементовПоСтатусуСервер`. Событий шесть: `ПриИзменении`, `Нажатие`, `Команда`, `ПередНачаломИзменения`, `ПередНачаломДобавления`, `ПередУдалением`.
- Признак в модуле формы: процедура, заполняющая `МассивЭлементов` именами элементов и вызывающая этот метод; вызывается из `ПриЧтенииСозданииНаСервере`.
- Работает только для записанного объекта: при пустой `Объект.Ссылка` метод выходит по первой строке. Для нового объекта подмены нет.
- Охват в УТ 11.5.19 — 19 форм: формы документов продаж и закупок и формы элементов соглашений и договоров. Механизм есть не во всех формах, проверяй конкретную.

**Обертка вокруг типового обработчика здесь не спасает.** Диспетчер не читает сохраненное действие: `КонтрольНеСогласованныхИзмененийОбработатьСобытие*` в модуле формы — это лестница `Если Элемент.Имя = "..." Тогда ТиповойОбработчик(Элемент)`, а `СтруктураДействийКонтрольНеСогласованныхИзменений` служит лишь признаком участия элемента. Ветка `Иначе` бросает исключение «Внутренняя ошибка подсистемы контроля несогласованных изменений».

Что делать: на элементе, попавшем в такой механизм, действие не переопределять — врезаться в типовой обработчик через `&ИзменениеИКонтроль` по общей норме выбора механизма — правка идёт в середину обработчика, обёрткой она не выражается.

## Паттерн: ПродолжитьВызов()

- `&Перед` — типовой метод вызывается автоматически после перехватчика; **вручную не вызывать**.
- `&После` — типовой уже выполнился; `ПродолжитьВызов()` не используется.
- `&ИзменениеИКонтроль` — **не используется**: тело перехватчика уже содержит копию оригинала (правки через `#Вставка`/`#Удаление`).
- `&Вместо` — **обязателен**, если нужно сохранить типовую логику (тело оригинала не копируется, вызывается через `ПродолжитьВызов()`). Его отсутствие — сигнал проверить задачу: чаще всего это правка внутри тела, и её место в `&ИзменениеИКонтроль`.
- Перехват события формы с типом «Вместо» — так же, как `&Вместо`: `ПродолжитьВызов()` доступен и выполняет типовой обработчик. Проверено на живой базе (демо-конфигурация, один прогон): типовой обработчик записал значение в реквизит формы, перехватчик после `ПродолжитьВызов()` его прочитал.

## Паттерн: размещение добавляемого метода

Область выбирается по роли метода — норма `std#455` в `.claude/rules/1c-rules.md`. Именно по роли, а не по наличию: то, что какая-то область в модуле уже есть, не делает её подходящей.

Для перехватчика роль задаёт заимствованный метод. Посмотри, в какой области он лежит в типовом модуле, и положи перехватчик в такую же: перехват обработчика события — в `ОбработчикиСобытий`, перехват служебного метода — в `СлужебныеПроцедурыИФункции`. Собственные служебные методы расширения — в `СлужебныеПроцедурыИФункции`.

Нужной области в модуле расширения нет — заведи её на своём месте в стандартном порядке. Класть метод в чужую область, лишь бы не создавать новую, неверно: это ловят АПК:1340 и АПК:1341.

Не перестраивай модуль и не перемещай существующий код, если это не входит в задачу. Типовой код вендора не перемещай и не переоформляй.

## Паттерн: маркеры доработок

Обязательные нормы применения маркеров — в разделе «Маркеры доработок»
файла `.claude/rules/1c-rules.md`. Область их действия задаёт настройка
«Маркеры доработок» в `CLAUDE.md`: маркеры бывают выключены целиком или
оставлены только для правок типового кода в `src\cf`.

Если по этой настройке правимое место маркируется и задача требует
поставить, изменить или проверить `COMMENT_OPEN`/`COMMENT_CLOSE` —
перед правкой прочитай `references/markers.md`. Если не маркируется —
этот паттерн и `references/markers.md` пропусти целиком.

## Паттерн: заимствованные (adopted) объекты

Заимствованный объект (`Заимствованный`) — не копия, а ссылка на объект основной конфигурации, внесённый в область видимости расширения; при обновлении вендора переприменяется автоматически. Ограничения:

- Нельзя удалять типовые реквизиты и табличные части — они принадлежат основной конфигурации.
- Можно добавлять свои реквизиты и ТЧ (с префиксом расширения).
- Модули заимствованных объектов — только перехватчики (`&Перед`/`&После`/`&ИзменениеИКонтроль`), без прямых правок тела типовой процедуры.
- Формы заимствованных объектов — элементы можно добавлять, существующие удалять нельзя.

## Паттерн: несколько расширений над одним методом

Расширения ложатся на конфигурацию слоями — типовая в основании, расширения сверху. Исполнение
идёт **сверху вниз** этого «пирога», порядок слоёв задаёт свойство «Назначение»: Исправление →
Адаптация → Дополнение ([ИТС](https://its.1c.ru/db/pubextensions/content/11/hdoc),
[Зазеркалье](https://wonderland.v8.1c.ru/blog/rasshirenie-moduley/)).

**`&Перед` и `&После` конфликта не создают** — выполняются все, вложенно:

```
&Перед верхнего расширения
  &Перед нижнего расширения
    типовой метод
  &После нижнего расширения
&После верхнего расширения
```

**`&Вместо` подавляет соседей молча.** Дословно: «перекрывается не только вызов основного метода,
но также и перехватчиков, находящихся ниже в пироге». Ошибки не будет — доработки нижних
расширений просто перестанут выполняться, и заметят это не сразу. Это главная причина, по которой
обёртка через `&Вместо` требует проверки соседних расширений, а `&Перед`/`&После` — нет.

**`&ИзменениеИКонтроль` — один на метод во всей конфигурации.** Не в расширении, а вообще:
«с одним расширяемым методом конфигурации может быть связан только один метод, имеющий аннотацию
&ИзменениеИКонтроль», остальные «будут признаны ошибочными и будут показаны в списке ошибок
применения расширения» ([Зазеркалье](https://wonderland.v8.1c.ru/blog/razvitie-mekhanizma-rasshireniy-konfiguratsii-15/)).
То есть второе такое расширение не заработает, и узнаешь ты об этом при применении.

Отсюда практическое следствие: **проверять другие расширения нужно до выбора директивы, а не после**.
Норма — в `.claude/rules/1c-rules.md` (### Архитектура). Разбор темы на ИТС —
[«Взаимодействие нескольких расширений»](https://its.1c.ru/db/pubextensions/content/57/hdoc).

## Паттерн: назначение расширения

Свойство «Назначение» задаёт порядок применения расширений (Исправление → Адаптация → Дополнение,
см. предыдущий паттерн) и влияет на переприменение при обновлении:

| Назначение | Когда |
|---|---|
| Исправление (Patch) | Минимальные изменения, только перехватчики |
| Адаптация (Customization) | Реквизиты, формы, модули |
| Дополнение (AddOn) | Полностью новый функционал |

## Паттерн: документирование экспортных методов

Объём документации — по норме 1c-rules. Метод программного интерфейса (публичный API) — полная шапка: описание с глагола, параметры с типами, возвращаемое значение.

```bsl
// Возвращает данные заказа по идентификатору.
//
// Параметры:
//   ИдентификаторЗаказа - УникальныйИдентификатор - UUID заказа
//   ВключатьСтроки - Булево - загружать табличную часть (по умолчанию Истина)
//
// Возвращаемое значение:
//   Структура - данные заказа:
//     * Номер - Строка - номер заказа
//     * Дата - Дата - дата заказа
//   Неопределено - если заказ не найден
//
Функция ПрефиксПолучитьДанныеЗаказа(ИдентификаторЗаказа, ВключатьСтроки = Истина) Экспорт
```

Служебный экспортный метод, логика которого очевидна из имени: описание НЕ пишем (иначе дублируем имя — норма `std#453` в `1c-rules.md`, ### Документирование), но типы параметров указываем — из имени тип не виден.

```bsl
// Параметры:
//   Заказ - ДокументСсылка.ЗаказКлиента
//
Функция ПрефиксМожноОтменитьЗаказ(Заказ) Экспорт
```

Неэкспортный метод — секции описания нет, если назначение и порядок работы видны из имени метода и имён параметров (норма в 1c-rules). Описание появляется только там, где нужно пояснить особенность работы или неочевидную причину невыполнения действия. Шапка из одних секций «Параметры:»/«Возвращаемое значение:» с типами допустима и здесь — она даёт типизацию в EDT. Ловушка этой задачи: типовой код рядом документирует всё подряд, и это не образец.

```bsl
// НЕВЕРНО: комментарий не добавляет ничего к имени
// Обработчик события "ПриОткрытии" формы
//
&НаКлиенте
Процедура ПриОткрытии(Отказ)

// ВЕРНО: шапки нет
&НаКлиенте
Процедура ПриОткрытии(Отказ)

// ВЕРНО: описания нет, типы для EDT есть
// Параметры:
//   ТаблицаПродаж - ТаблицаЗначений
//
Процедура ЗаполнитьСуммыПродаж(ТаблицаПродаж)

// ВЕРНО: шапка объясняет неочевидное ограничение
// Пропускает строки с закрытыми заказами: их суммы уже вошли в закрывающий документ,
// повторный учет задваивает выручку.
Процедура ПрефиксЗаполнитьСуммыПродаж(ТаблицаПродаж)
```