# 1C Operational Coding Loop

Цель: сделать помощника по 1С, который работает в темпе реальной разработки, без постоянной полной выгрузки конфигурации в XML и без обязательного 1C:EDT на первом этапе.

## Problem

Полная выгрузка конфигурации в XML медленная. 1C:EDT требует отдельной установки, настройки проекта и дисциплины синхронизации. Для оперативной разработки помощнику нужны текущие данные почти сразу:

- структура базы и конфигурации;
- доступные объекты, реквизиты, табличные части, формы и команды;
- актуальные модули BSL;
- примеры реальных данных для read-only анализа;
- постановки задач из текста, Excel-файлов и скриншотов интерфейса.

## Decision

Используем двухконтурную схему.

Быстрый контур:

- read-only SQL для диагностики, выборок и проверки данных;
- легкий 1C agent внутри базы или рядом с ней для метаданных, модулей и управляемых операций;
- локальный кеш/snapshot с коротким TTL;
- RAG поверх актуального кеша;
- генерация патчей, внешних отчетов, обработок и расширений как артефактов.

Тяжелый контур:

- XML/EDT/хранилище конфигурации для периодической полной синхронизации;
- сборка, ревью, массовый рефакторинг и долгоживущие изменения;
- финальная проверка перед переносом в production.

## Live Sources

### SQL Read-Only

SQL удобен как быстрый источник данных, но не является главным источником метаданных 1С.

Разрешено:

- read-only запросы;
- выборки для отчетов и сверок;
- оценка объемов данных;
- поиск аномалий;
- проверка результата после изменения в тестовой базе.

Запрещено:

- DML/DDL;
- изменение таблиц платформы напрямую;
- запись в production;
- хранение строк подключения и паролей в репозитории.

## 1C Storage Layers (write/read boundary)

Принцип работы со слоями конфигурации:

- `Config` и `ConfigCAS` — **active** (уже применённое в системе состояние). Для них разрешены только read-операции.
- `ConfigSave` и `ConfigCASSave` — **saved, not yet applied** (сохранённое в конфигураторе состояние). Это целевые слои для формирования изменений через адаптер.
- Base-изменения пишутся в `ConfigSave`.
- Extension-изменения пишутся в `ConfigCASSave`.

Жёсткое правило:

- Коннектор/агент не пишет в `Config`/`ConfigCAS`.
- Изменения должны идти через saved-слои и проходить сравнение `ConfigSave↔Config`, `ConfigCASSave↔ConfigCAS` до ручного/внешнего apply в production.
- Если требуется production apply, это отдельный человеческий процесс контроля и проверки.

Мини-чеклист перед передачей на manual-apply:

1. Есть актуальный compare saved-vs-active.
2. Есть report с изменениями по объектам.
3. Есть отметка «не применено» в `ConfigSave`/`ConfigCASSave`.
4. Есть rollback-план и явное human approval.

### Working-State Read Policy

Для программирования и оперативного анализа помощник должен читать последнее
сохранённое состояние конфигуратора, а не только применённую конфигурацию.

По умолчанию:

- MCP-запросы к `extension.objects.find`, `modules.search`, `code.search` и
  `metadata.resolve_overrides` используют `source_state=working`;
- REST-запросы к тем же методам используют `state=working`;
- `working` означает: сначала `ConfigSave`/`ConfigCASSave`, затем active-слой
  как fallback;
- результаты помечаются `activation_state`: `saved_only`, `saved_override` или
  `active`.

Когда нужно сравнение:

- `source_state=applied` / `state=active` — показать только применённое;
- `source_state=all` / `state=both` — показать оба слоя и различия;
- `full_scan=true` включается только осознанно для глубокого поиска по active
  `ConfigCAS`, потому что такой поиск медленнее.

Если пользователь спрашивает естественным языком вроде «выдай список всех форм
в save только имена», агент должен трактовать это как working/save-first
срез, вернуть имена saved-форм и не отбрасывать объекты `saved_only`: они могут
быть ещё не активированы и всё равно являются текущим состоянием разработки.

### Code Write Policy

Для оперативного программирования агент не должен знать SQL-нюансы: таблицы,
имена файлов, stream indexes и brace paths являются внутренней реализацией
адаптера.

Стандартный write API для агента:

- `code.write` с `module_text`/`full_text`/`code` заменяет весь модуль;
- `code.write` с `routine_name` и `routine_text` заменяет только указанную
  процедуру или функцию;
- `code.write` с `old` и `new` заменяет фрагмент только если `old` найден
  ровно один раз в выбранной области. Если передан `routine_name` или
  canonical path до процедуры, областью является эта процедура/функция; иначе
  весь текущий saved-модуль.

По умолчанию `code.write` делает `mode=apply`, но это apply в saved-state
слой (`ConfigSave`/`ConfigCASSave`), а не применение конфигурации в runtime.
Адаптер сам выставляет save-first gates и сам выбирает физический маршрут.
Физические детали возвращаются только при `include_storage=true` для
диагностики. Ответ `code.write` всегда содержит `write_mode`: target
`saved_state`, activation_state `not_activated`, production_apply `false`.
Ответы `code.read` и `code.search` для saved-кода содержат `current_state`:
source `saved_state`, activation_state `not_activated`.
Для `code.read`: `state=working` означает save-first с fallback в active,
`state=save` читает только saved layer, `state=active` пропускает saved layer.
`state=both` читает saved и active отдельно, возвращает `layers` для обоих
слоев и `comparison.both_present` / `comparison.differs`. При `include_text=true`
верхнеуровневый `text` берется из saved-state, если он есть, иначе из active;
`text_source` показывает выбранный слой.
Для `code.search state=both` saved-совпадения идут первыми, active-слой
добирается отдельным проходом, а `counts.saved_matches` и
`counts.active_matches` показывают покрытие по слоям.

Если фрагмент повторяется, агент должен передать более узкий контекст
(`routine_name`) или заменить процедуру целиком. Адаптер в такой ситуации
возвращает `ambiguous_fragment`, `scope` и `counts.occurrences`, и не
записывает.

### 1C Agent

Для актуальной структуры и кода нужен небольшой агент на стороне 1С. Он может быть реализован как внешняя обработка, расширение или опубликованный HTTP-сервис.

Минимальные функции:

- вернуть список объектов метаданных;
- вернуть описание объекта: реквизиты, табличные части, формы, команды, модули;
- искать по BSL-модулям;
- читать текст выбранного модуля;
- выполнять read-only запрос языка запросов 1С с лимитами;
- отдавать версию/дату изменения конфигурации для инвалидации кеша;
- принимать change proposal, но не применять его автоматически в production.

Если публикация HTTP-сервиса невозможна, первым вариантом может быть ручной запуск внешней обработки, которая выгружает JSON snapshot в общую папку.

## Freshness Model

Модель не должна считать кеш вечным.

- SQL read-only данные читаются по запросу.
- Metadata snapshot имеет TTL и номер версии конфигурации.
- BSL-модули кешируются с checksum.
- Перед генерацией кода под конкретный объект помощник проверяет свежесть metadata snapshot.
- Если snapshot устарел или отсутствует, помощник запрашивает обновление через agent.

## Task Intake

Задачи приходят разными форматами:

- обычный текст;
- Excel-файл с требованиями, примером отчета или справочником полей;
- скриншот формы, нарисованный макет интерфейса или ошибка;
- фрагмент BSL;
- SQL/запрос 1С;
- описание бизнес-процесса.

Обработка:

- текст идет напрямую в модель;
- Excel парсится структурно: листы, заголовки, таблицы, примечания;
- скриншоты идут через vision/OCR и превращаются в описание интерфейса, полей, команд и ошибок;
- все извлеченные требования связываются с metadata snapshot и BSL search.

## Coding Outputs

Помощник должен уметь выдавать:

- BSL-фрагмент;
- полный модуль формы/объекта/общего модуля;
- текст запроса 1С;
- схему внешнего отчета или обработки;
- proposal для расширения;
- список изменений по формам и командам;
- чеклист проверки;
- тестовые сценарии;
- rollback plan.

Для production изменения не применяются напрямую. Нормальный поток:

1. Получить актуальные метаданные и модули.
2. Сформировать change proposal.
3. Проверить синтаксис и зависимости в тестовой базе.
4. Сформировать артефакт: внешняя обработка, отчет, расширение или патч.
5. Провести ревью.
6. Перенести через согласованный 1С-процесс.

## Practical Priority

Первый рабочий MVP:

1. SQL read-only connector с валидацией политики.
2. 1C metadata snapshot через внешнюю обработку в JSON.
3. BSL module snapshot и поиск по модулям.
4. Загрузка постановки из Excel.
5. Загрузка скриншота формы/ошибки в vision-модель.
6. Генерация внешнего отчета/обработки по актуальному snapshot.
7. Smoke eval: модель не выдумывает реквизиты и просит обновить snapshot, если он устарел.