# Управляемые формы (Form)

Навыки группы `/form-*` позволяют анализировать, генерировать и валидировать управляемые формы 1С:Предприятия 8.3 из XML-исходников, не читая тысячи строк XML.

## Навыки

| Навык | Параметры | Описание |
|-------|-----------|----------|
| `/form-add` | `<ObjectPath> <FormName> [Purpose]` | Добавление формы к объекту конфигурации (Document, Catalog и др.) |
| `/form-info` | `<FormPath>` | Компактная сводка: дерево элементов, реквизиты, команды, события |
| `/form-compile` | `<JsonPath> <OutputPath>` | Генерация Form.xml из компактного JSON-определения |
| `/form-validate` | `<FormPath>` | Валидация: уникальность ID, companions, DataPath, команды |
| `/form-edit` | `<FormPath> <JsonPath>` | Добавление элементов, реквизитов, команд в существующую форму |
| `/form-patterns` | (без параметров) | Справочник паттернов: архетипы, конвенции именования, продвинутые приёмы |

## Сценарии использования

### Добавление новой формы к объекту конфигурации

`/form-add` создаёт каркас управляемой формы (metadata XML + Form.xml + Module.bsl) и регистрирует её в объекте конфигурации. Поддерживает Document, Catalog, DataProcessor, Report, InformationRegister и другие типы.

```
> Добавь форму документа к Documents/АвансовыйОтчет.xml
```

Claude вызовет `/form-add` с нужными параметрами. Назначение формы (Purpose) определяет структуру: Object — форма объекта с реквизитом «Объект», List/Choice — форма списка с DynamicList, Record — форма записи регистра.

Типичный workflow:

1. `/form-add` — создать каркас (metadata + Form.xml + Module.bsl)
2. `/form-compile` или `/form-edit` — наполнить Form.xml элементами
3. `/form-validate` — проверить корректность
4. `/form-info` — проанализировать результат

### Анализ формы перед модификацией

Файлы Form.xml содержат от сотен до десятков тысяч строк XML. 80% объёма — визуальный шум (цвета, шрифты, размеры, автогенерированные подсказки). `/form-info` извлекает суть.

```
> Покажи структуру формы документа РеализацияТоваровУслуг
```

Claude найдёт Form.xml и вызовет `/form-info`. Результат — компактная сводка (40–100 строк вместо тысяч):

```
=== Form: ФормаДокумента — "Реализация товаров и услуг" (Documents.РеализацияТоваровУслуг) ===

Properties: AutoTitle=false, CommandBarLocation=None

Events:
  OnCreateAtServer -> ПриСозданииНаСервере
  OnOpen -> ПриОткрытии

Elements:
  ├─ [Group:AH] ГруппаШапка
  │ ├─ [Input] Организация -> Объект.Организация {OnChange}
  │ └─ [Input] Контрагент -> Объект.Контрагент {OnChange, StartChoice}
  ├─ [Table] Товары -> Объект.Товары
  │ ├─ [Input] Номенклатура -> Объект.Товары.Номенклатура {OnChange}
  │ └─ [Input] Сумма -> Объект.Товары.Сумма [ro]
  └─ [Pages] Страницы
     ├─ [Page] Основное (5 items)
     └─ [Page] Печать (2 items)

Attributes:
  *Объект: DocumentObject.РеализацияТоваровУслуг (main)
  Валюта: CatalogRef.Валюты
  ...

Commands:
  Печать -> ПечатьДокумента [Ctrl+P]
```

### Добавление элементов в существующую форму

`/form-edit` добавляет элементы, реквизиты и команды в существующий Form.xml. Автоматически назначает ID, генерирует companion-элементы и обработчики событий.

```
> Добавь поле "Склад" в шапку формы после "Контрагент"
```

Claude вызовет `/form-info` для анализа структуры, создаст JSON и вызовет `/form-edit`:

```json
{
  "into": "ГруппаШапка",
  "after": "Контрагент",
  "elements": [
    { "input": "Склад", "path": "Объект.Склад", "on": ["OnChange"] }
  ],
  "attributes": [
    { "name": "Склад", "type": "CatalogRef.Склады" }
  ]
}
```

Позиционирование: `into` указывает группу-контейнер, `after` — элемент, после которого вставлять. Оба опциональны (по умолчанию — в конец корневого ChildItems).

Один вызов может содержать элементы, реквизиты и команды одновременно. Группы поддерживают `children` для вложенных элементов.

### Поиск обработчиков и привязок

Из сводки видно, какие события подключены к каким элементам:

```
> Какие обработчики срабатывают при изменении контрагента?
```

Claude вызовет `/form-info` и найдёт: `[Input] Контрагент -> Объект.Контрагент {OnChange, StartChoice}` — далее откроет модуль формы и найдёт процедуры по именам событий.

### Точечное погружение в детали

Сводка — это карта. Для деталей по конкретному элементу достаточно grep по имени из сводки:

```
> Покажи все свойства элемента ДоговорКонтрагента
```

Claude сделает grep по Form.xml и найдёт полный XML-блок с ChoiceParameters, ChoiceFoldersAndItems, стилями и прочими свойствами.

## Чтение вывода

### Дерево элементов

| Обозначение | Элемент |
|---|---|
| `[Group:V]` `[Group:H]` `[Group:AH]` `[Group:AV]` | Группа (Vertical / Horizontal / AlwaysHorizontal / AlwaysVertical) |
| `[Input]` | Поле ввода |
| `[Check]` | Флажок |
| `[Label]` | Декоративная надпись |
| `[LabelField]` | Поле надписи (привязанное к данным) |
| `[Table]` | Таблица |
| `[Pages]` / `[Page]` | Вкладки (страницы показывают количество элементов) |
| `[Button]` | Кнопка |
| `[CmdBar]` | Командная панель |
| `[Popup]` | Выпадающее меню |
| `[Picture]` | Декоративная картинка |
| `[PicField]` | Поле картинки |
| `[Calendar]` | Календарь |

### Флаги

Показываются только при отклонении от умолчания:
- `[visible:false]` — элемент скрыт (Visible=false)
- `[enabled:false]` — элемент недоступен (Enabled=false)
- `[ro]` — только чтение (ReadOnly=true)
- `,collapse` — сворачиваемая группа (Behavior=Collapsible)

### Привязки и события

- `-> Объект.Поле` — DataPath (привязка к данным)
- `-> Имя [cmd]` — привязка к команде формы
- `-> Close [std]` — привязка к стандартной команде
- `{OnChange, StartChoice}` — имена подключённых событий
- `[title:Текст]` — заголовок, если отличается от имени элемента

### Реквизиты

- `*Объект: DocumentObject.Реализация (main)` — основной реквизит формы
- `Таблица: ValueTable [Кол1: тип, Кол2: тип]` — таблица значений с колонками
- `Список: DynamicList -> Catalog.Пользователи` — динамический список с основной таблицей

## Генерация формы с нуля

`/form-compile` принимает компактное JSON-определение (20–50 строк) и генерирует полный Form.xml (100–500+ строк) с namespace-декларациями, companion-элементами и последовательными ID.

```
> Создай форму загрузки данных с полями Организация, Контрагент, таблицей Товары и кнопкой Загрузить
```

Claude создаст JSON-определение и вызовет `/form-compile`. Пример JSON:

```json
{
  "properties": { "autoTitle": false },
  "events": { "OnCreateAtServer": "ПриСозданииНаСервере" },
  "elements": [
    { "group": "horizontal", "name": "Шапка", "children": [
      { "input": "Организация", "path": "Объект.Организация", "on": ["OnChange"] },
      { "input": "Контрагент", "path": "Объект.Контрагент" }
    ]},
    { "table": "Товары", "path": "Объект.Товары", "columns": [
      { "input": "Номенклатура", "path": "Объект.Товары.Номенклатура" },
      { "input": "Сумма", "path": "Объект.Товары.Сумма", "readOnly": true }
    ]},
    { "button": "Загрузить", "command": "Загрузить" }
  ],
  "attributes": [
    { "name": "Объект", "type": "DataProcessorObject.ЗагрузкаДанных", "main": true }
  ],
  "commands": [
    { "name": "Загрузить", "action": "ЗагрузитьОбработка" }
  ]
}
```

### Верификация результата

После компиляции используйте `/form-validate` и `/form-info` для проверки:

```
> /form-validate src/МояОбработка/Forms/Форма/Ext/Form.xml
> /form-info src/МояОбработка/Forms/Форма/Ext/Form.xml
```

`/form-validate` проверит структурную корректность (ID, companions, ссылки), `/form-info` покажет результат в виде компактной сводки.

## Генерация из метаданных объекта

`/form-compile` умеет автоматически генерировать форму из метаданных объекта (XML-выгрузки). Скрипт читает реквизиты, табличные части, стандартные реквизиты и строит форму по стандарту ERP.

```
> Создай форму документа ЗаказКлиенту
```

Claude вызовет `/form-compile` с флагом `-FromObject`. Назначение формы (Purpose) автоматически определяется из имени формы (ФормаДокумента -> Item, ФормаСписка -> List, ФормаВыбора -> Choice).

Поддерживаемые типы: Document, Catalog, InformationRegister, AccumulationRegister, ChartOfCharacteristicTypes, ExchangePlan, ChartOfAccounts.

Не поддерживается: DataProcessor (реквизиты объекта пустые -- форма строится на реквизитах формы, используйте JSON DSL).

### Project-level пресеты

Раскладка формы управляется пресетом (по умолчанию `erp-standard`). Для настройки под проект создайте файл:

```
<project-root>/presets/skills/form/erp-standard.json
```

Файл накладывается поверх встроенного пресета через deep merge -- достаточно указать только переопределяемые ключи. Полная документация ключей: `.claude/skills/form-compile/presets/README.md`.

## Примеры слеш-команд

```
> /form-info upload/acc_8.3.24/Documents/РеализацияТоваровУслуг/Forms/ФормаДокумента/Ext/Form.xml
> /form-info src/МояОбработка/Forms/Форма/Ext/Form.xml
> /form-compile src/form.json src/МояОбработка/Forms/Форма/Ext/Form.xml
> /form-edit src/МояОбработка/Forms/Форма/Ext/Form.xml src/additions.json
> /form-validate src/МояОбработка/Forms/Форма/Ext/Form.xml
```

## Связь с EPF-навыками

Навыки `/form-*` работают с формами из любых источников — конфигурации и внешних обработок.

При работе с объектами конфигурации:

1. `/form-add` — создать форму (каркас + регистрация в объекте)
2. `/form-compile` или `/form-edit` — наполнить Form.xml элементами
3. `/form-validate` — проверить корректность
4. `/form-info` — проанализировать результат

При работе с внешними обработками:

1. `/form-add` — создать форму (каркас)
2. `/form-compile` — сгенерировать Form.xml из JSON-определения
3. `/form-edit` — добавить элементы/реквизиты/команды в существующую форму
4. `/form-validate` — проверить корректность
5. `/form-info` — проанализировать результат
6. `/epf-build` — собрать EPF

## Спецификации

- [Управляемая форма](1c-form-spec.md) — Form.xml, элементы, команды, реквизиты, система типов
- [Form DSL](form-dsl-spec.md) — JSON-формат описания формы для `/form-compile` и `/form-edit`
- [Паттерны компоновки](form-patterns.md) — типовые архетипы форм, конвенции именования, примеры DSL