# ТЗ: базовая онтология 1С бухгалтерии + проверка полноты доступа и цепочек связей

**Версия:** 0.1  
**Дата:** 2026-03-22  
**Контур:** тестовая копия 1С, опубликованная по OData  
**База:** `X:\1C\База бухгалтерии`  
**Публикация:** `http://localhost/buh_test/odata/standard.odata/`

---

## 1. Цель этапа

Нужно решить две задачи одновременно:

1. Сформировать **базовую каноническую онтологию бухгалтерского контура 1С** для будущего ассистента, графа знаний и MCP-слоя.
2. Провести **жёсткую проверку полноты и связности текущего OData-доступа**, чтобы понять:
   - достаточно ли его для MVP и последующего роста;
   - или OData годится только как быстрый транспорт / discovery-слой;
   - или нужно переходить к более глубокому способу доступа к данным 1С.

Ключевой принцип этапа: нас интересует **не перечень сущностей сам по себе**, а возможность восстановить **операционный бухгалтерский смысл**:
- какой документ породил движение;
- какие проводки легли на какие счета;
- какие субконто, контрагенты, договоры, организации и банковские счета участвуют в цепочке;
- можно ли объяснять остатки, обороты, сальдо, расхождения и основания операций.

---

## 2. Что уже подтверждено на текущем шаге

### 2.1. Инфраструктура поднята

- 1С опубликована на IIS.
- Веб-клиент открывается.
- OData endpoint отвечает.
- `$metadata` отвечает и отдаёт модель сущностей.

### 2.2. По текущему инвентарю уже видны ключевые семейства объектов

Подтверждено наличие:
- `Document_*`
- `Catalog_*`
- `AccountingRegister_Хозрасчетный`
- `AccumulationRegister_*`
- `ChartOfAccounts_Хозрасчетный`
- `InformationRegister_*`

### 2.3. По снапшоту entity sets видно, что модель большая и не пустая

Сейчас опубликовано:
- всего сущностей: **1189**
- `Document`: **517**
- `Catalog`: **162**
- `InformationRegister`: **270**
- `AccumulationRegister`: **102**
- `AccountingRegister`: **2**
- `ChartOfAccounts`: **1**

### 2.4. Уже есть признаки связности

В `$metadata` видны `NavigationProperty`, а значит модель содержит не только плоские entity sets, но и формализованные связи между объектами.

---

## 3. Главный вывод по идеологии

### 3.1. Не строим “онтологию всей 1С” как прямую копию entity sets

Это плохой путь, потому что:
- в 1С слишком много технических и вторичных сущностей;
- прямое зеркало OData быстро превратится в шум;
- ассистенту нужна не свалка OData-объектов, а понятный слой бухгалтерского смысла.

### 3.2. Строим двухслойную модель

#### Слой А. Каноническая онтология бухгалтерии

Это **главный рабочий слой**, на котором потом живут:
- граф связей;
- семантика для ассистента;
- поиск отклонений;
- сверки;
- explainability;
- MCP-инструменты.

#### Слой B. Mapping / adapter layer к 1С OData

Это слой соответствий:
- какие OData entity sets соответствуют каноническим сущностям;
- какие поля и ключи заполняют каноническую модель;
- какие связи можно восстановить напрямую, а какие только вычислением;
- где OData достаточно, а где нужен более глубокий коннектор.

---

## 4. Базовая онтология v0.1

Ниже — минимальный, но уже полезный состав сущностей, который должен закрыть бухгалтерский MVP и диагностику связности.

### 4.1. Core facts

#### 1. `Posting`
Базовая атомарная бухгалтерская запись / движение.

Поля:
- `posting_id`
- `period`
- `organization_id`
- `document_id`
- `debit_account_id`
- `credit_account_id`
- `amount`
- `currency_id`
- `content`
- `subconto_1`
- `subconto_2`
- `subconto_3`
- `source_register`
- `is_active`

#### 2. `Document`
Первичный / операционный документ 1С.

Поля:
- `document_id`
- `document_type`
- `number`
- `date`
- `organization_id`
- `counterparty_id`
- `contract_id`
- `author_id`
- `posted_flag`
- `comment`
- `source_entity_set`

#### 3. `RegisterMovement`
Универсальное представление движений по регистрам, если нужно отделить их от бухгалтерской проводки.

Поля:
- `movement_id`
- `register_type`
- `register_name`
- `period`
- `recorder_document_id`
- `organization_id`
- `dimensions`
- `resources`
- `is_active`

---

### 4.2. Main dimensions

#### 4. `Account`
Счёт бухгалтерского учёта.

Поля:
- `account_id`
- `code`
- `name`
- `parent_account_id`
- `is_off_balance`
- `kind`
- `subconto_profile`

#### 5. `SubcontoType`
Вид аналитики по счёту.

Поля:
- `subconto_type_id`
- `name`
- `code`
- `chart_reference`

#### 6. `Organization`
Организация.

#### 7. `Counterparty`
Контрагент.

#### 8. `Contract`
Договор контрагента.

#### 9. `BankAccount`
Банковский счёт.

#### 10. `Currency`
Валюта.

#### 11. `Item`
Номенклатура / товар / услуга.

#### 12. `Warehouse`
Склад, если нужен товарный / операционный контур.

#### 13. `Employee`
Сотрудник / физлицо / автор / ответственный.

#### 14. `Tax`
Налог / вид налогового обязательства.

#### 15. `CostItem`
Статья затрат / ДДС / аналитика затрат, если есть в базе.

---

## 5. Канонические связи

Это ядро графа, которое обязательно надо уметь строить.

### 5.1. Документно-проводочный слой

- `Document -> creates -> Posting`
- `Document -> creates -> RegisterMovement`
- `RegisterMovement -> derivedInto -> Posting` *(если между регистром и проводкой есть вычислимый мост)*
- `Posting -> basedOn -> Document`

### 5.2. Бухгалтерский слой

- `Posting -> debitAccount -> Account`
- `Posting -> creditAccount -> Account`
- `Posting -> hasCurrency -> Currency`
- `Posting -> belongsTo -> Organization`
- `Posting -> usesSubcontoType -> SubcontoType`
- `Posting -> referencesCounterparty -> Counterparty`
- `Posting -> referencesContract -> Contract`
- `Posting -> referencesBankAccount -> BankAccount`
- `Posting -> referencesItem -> Item`

### 5.3. Справочный слой

- `Counterparty -> hasContract -> Contract`
- `Organization -> ownsBankAccount -> BankAccount`
- `Account -> allowsSubcontoType -> SubcontoType`
- `Document -> referencesCounterparty -> Counterparty`
- `Document -> referencesContract -> Contract`
- `Document -> referencesOrganization -> Organization`
- `Document -> referencesWarehouse -> Warehouse`
- `Document -> referencesItem -> Item`

---

## 6. Mapping 1С OData -> каноническая онтология

Ниже — стартовый mapping, который нужно завести как отдельную таблицу / YAML / JSON-конфиг.

### 6.1. Сущности верхнего приоритета

| 1С OData entity | Каноническая сущность | Приоритет |
|---|---|---:|
| `AccountingRegister_Хозрасчетный` | `Posting` / `RegisterMovement` | высокий |
| `AccountingRegister_Хозрасчетный_RecordType` | `Posting` | высокий |
| `ChartOfAccounts_Хозрасчетный` | `Account` | высокий |
| `Catalog_Контрагенты` | `Counterparty` | высокий |
| `Catalog_ДоговорыКонтрагентов` | `Contract` | высокий |
| `Catalog_Организации` | `Organization` | высокий |
| `Catalog_БанковскиеСчета` | `BankAccount` | высокий |
| `Catalog_Валюты` | `Currency` | высокий |
| `Catalog_Номенклатура` | `Item` | высокий |
| `Document_ПоступлениеТоваровУслуг` | `Document(type=goods_receipt)` | высокий |
| `Document_РеализацияТоваровУслуг` | `Document(type=sales)` | высокий |
| `Document_СписаниеСРасчетногоСчета` | `Document(type=bank_out)` | высокий |
| `Document_ПоступлениеНаРасчетныйСчет` | `Document(type=bank_in)` | высокий |
| `Document_ОперацияБух` | `Document(type=manual_entry)` | высокий |

### 6.2. Табличные части документов

Все entity sets вида:
- `Document_*_Товары`
- `Document_*_Услуги`
- `Document_*_Оплата`
- `Document_*_Поставщики`
- `Document_*_Контрагенты`
- `Document_*_СчетаРасчетов`

рассматриваются как:
- либо `DocumentLine`
- либо специализированные дочерние узлы `DocumentItemLine`, `PaymentLine`, `SettlementLine`

### 6.3. Накопительные и информационные регистры

- `AccumulationRegister_*` -> `RegisterMovement`
- `InformationRegister_*` -> `ReferenceFact` / `OperationalAttribute` / `RegisterMovement` в зависимости от смысла

Важно: не пытаться все `InformationRegister_*` сразу тянуть в онтологию. Сначала только те, которые реально участвуют в бухгалтерских вопросах.

---

## 7. Формат хранения онтологии на MVP

На этом этапе онтология должна храниться **не в RDF первым делом**, а в практичном инженерном виде.

### 7.1. Рекомендуемый формат

#### Вариант A. YAML / JSON schema + mapping tables

Нужно завести:
- `ontology/entities.yaml`
- `ontology/relations.yaml`
- `ontology/mapping_1c_odata.yaml`
- `ontology/probe_matrix.yaml`

#### Вариант B. Таблицы в Postgres / SQLite

Минимально:
- `ontology_entities`
- `ontology_relations`
- `source_entity_mappings`
- `probe_results`
- `probe_relationships`

### 7.2. Что должно быть у каждой сущности

- `canonical_name`
- `description`
- `source_entity_sets`
- `required_fields`
- `optional_fields`
- `key_fields`
- `candidate_relationships`
- `probe_status`

### 7.3. Что должно быть у каждой связи

- `relation_name`
- `from_entity`
- `to_entity`
- `semantic_meaning`
- `source_evidence`
- `reconstruction_method`
- `confidence`
- `probe_status`

---

## 8. Главная задача этапа: проверка цепочек

Это ключевой блок. Именно он отвечает на вопрос: **достаточен ли OData в принципе**.

### 8.1. Цель probe-этапа

Нужно не просто прочитать объекты, а доказать, что через текущий доступ можно восстанавливать бухгалтерские зависимости.

### 8.2. Критически важные цепочки

#### Цепочка A. Документ реализации -> проводки -> счета -> субконто

Проверить:
- читается ли `Document_РеализацияТоваровУслуг`;
- есть ли у документа ключ / ссылка / recorder;
- можно ли выйти на `AccountingRegister_Хозрасчетный`;
- можно ли получить Дт/Кт;
- можно ли получить аналитику по контрагенту / договору / номенклатуре.

**Ожидаемый вывод:** можно ли объяснить, как документ реализации отразился в бухучёте.

#### Цепочка B. Документ поступления -> проводки -> счета расчётов / товаров / НДС

Проверить:
- `Document_ПоступлениеТоваровУслуг`
- табличные части товара / услуг
- связь с проводками
- связь со счетами расчётов и учёта

**Ожидаемый вывод:** можно ли строить контроль по закупкам и закрытию обязательств.

#### Цепочка C. Контрагент -> договор -> документы -> движения

Проверить:
- `Catalog_Контрагенты`
- `Catalog_ДоговорыКонтрагентов`
- документы по контрагенту
- движения по контрагенту
- расчёты / закрытие / сальдо

**Ожидаемый вывод:** можно ли строить “паспорт взаиморасчётов” по контрагенту.

#### Цепочка D. Банковский документ -> банк / счёт -> движения

Проверить:
- `Document_СписаниеСРасчетногоСчета`
- `Document_ПоступлениеНаРасчетныйСчет`
- `Catalog_БанковскиеСчета`
- проводки по 51/52 и связанные аналитики

**Ожидаемый вывод:** можно ли строить сценарии контроля денежных потоков.

#### Цепочка E. Manual entry -> хозрасчетный регистр -> explainability

Проверить:
- `Document_ОперацияБух`
- его табличные части / регистровые части
- связь с `AccountingRegister_Хозрасчетный`

**Ожидаемый вывод:** можно ли объяснить ручную бухгалтерскую операцию как граф.

#### Цепочка F. План счетов -> виды субконто -> проводки

Проверить:
- `ChartOfAccounts_Хозрасчетный`
- `ChartOfCharacteristicTypes_ВидыСубконтоХозрасчетные`
- соответствие аналитик конкретным счетам

**Ожидаемый вывод:** можно ли восстанавливать бухгалтерскую логику, а не просто номера счетов.

---

## 9. Как проверять цепочки технически

### 9.1. Шаг 1. Скачать и распарсить `$metadata`

Codex / интеграционный слой должен:
- распарсить `EntityType`;
- распарсить `NavigationProperty`;
- выделить ключи;
- собрать список кандидатов на связи;
- пометить, какие связи подтверждены схемой, а какие только по названию.

### 9.2. Шаг 2. Построить реестр приоритетных сущностей

Сформировать shortlist из 30–60 сущностей верхнего приоритета, а не пытаться сразу охватить все 1189.

### 9.3. Шаг 3. Выполнить пробные GET-запросы

Для каждой ключевой сущности сделать:
- `$top=5`
- `$select=` для ключевых полей
- `$filter=` по периоду / номеру / организации
- по возможности `$expand=` для навигационных свойств

### 9.4. Шаг 4. Для каждой цепочки собрать “relationship evidence”

У каждой связи должны быть доказательства:
- подтверждена метаданными;
- подтверждена по реальным данным;
- восстановлена косвенно по ключам;
- не восстанавливается текущим методом.

### 9.5. Шаг 5. Завести матрицу полноты

Для каждой канонической связи нужно выставить статус:
- `direct` — есть прямая навигация или поле-ссылка;
- `derivable` — можно восстановить вычислением / join;
- `opaque` — связь предполагается, но текущим OData не извлекается надёжно;
- `missing` — данных недостаточно.

---

## 10. Критерии принятия решения: OData достаточно или нет

### 10.1. OData остаётся основным методом, если

Подтверждается следующее:
- можно пройти минимум 4 из 6 ключевых цепочек;
- можно reliably получить документ, связанные движения, счета и аналитику;
- `ChartOfAccounts` и субконто доступны в форме, пригодной для восстановления логики;
- write не нужен для MVP;
- explainability можно собирать поверх OData + канонической модели.

### 10.2. OData остаётся только discovery / transport-слоем, если

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

В этом случае:
- OData используется для discovery, metadata и части чтения;
- рядом проектируется более глубокий коннектор.

### 10.3. Нужно сразу идти к более жирному методу, если

Подтверждается хотя бы одно:
- document -> posting не восстанавливается надёжно;
- posting -> debit/credit/subconto недоступны в пригодном виде;
- регистры отдают неполную картину;
- часть нужной бухгалтерской логики вообще не видна через OData;
- восстановление связей превращается в гадание по именам полей.

---

## 11. Что считать “более жирным методом”

Это не raw SQL первым делом, а набор вариантов по возрастанию глубины.

### Вариант 1. OData + внутренние HTTP/OData helper endpoints

Когда OData в целом нормален, но не хватает готовых агрегатов.

Что делаем:
- оставляем OData как базу;
- добавляем внутренние сервисы / обработку, которые возвращают уже собранные цепочки;
- ассистент работает поверх канонического слоя.

### Вариант 2. Агент / расширение внутри 1С

Когда OData не даёт достаточно связности или глубины.

Что даёт:
- доступ к объектной модели 1С;
- возможность отдавать наружу уже осмысленные выборки;
- меньше потерь смысла, чем в OData-only.

### Вариант 3. Глубокий коннектор к базе / внутренним механизмам 1С

Используется только если предыдущие уровни не закрывают задачу.

Важно:
- raw SQL по 1С не должен быть первым выбором для бизнес-семантики;
- но может понадобиться как дополнительный диагностический путь, если нужно убедиться, что OData реально скрывает часть данных.

### Вариант 4. Комбинированный режим

Наиболее вероятный реалистичный итог:
- OData — для discovery, metadata, части чтения;
- внутренний адаптер / сервис 1С — для критичных бухгалтерских цепочек и explainability;
- канонический слой — единый контракт для ассистента и MCP.

---

## 12. Deliverables этого этапа

### 12.1. Документы

Нужно получить:

1. `ontology_v0_1.md`
   - список сущностей;
   - список связей;
   - смысл каждой сущности и связи.

2. `mapping_1c_odata_v0_1.md`
   - соответствие OData entity sets к каноническим сущностям.

3. `probe_matrix.md`
   - перечень проверяемых цепочек;
   - статус прохождения;
   - direct / derivable / opaque / missing.

4. `decision_report_oddata_vs_deeper_access.md`
   - вердикт по OData;
   - список ограничений;
   - список причин, по которым нужен или не нужен более глубокий метод.

### 12.2. Технические артефакты

1. Скрипт парсинга `$metadata`
2. Список приоритетных entity sets
3. Набор probe-запросов к OData
4. JSON / YAML со схемой сущностей и связей
5. Отчёт с примерами реальных цепочек

---

## 13. Этапы работ

### Этап 1. Discovery и нормализация модели

Задачи:
- скачать `$metadata`;
- распарсить EntityType, keys, NavigationProperty;
- сформировать shortlist priority entity sets;
- собрать первый mapping.

Результат:
- черновик онтологии;
- черновик карты связей.

### Этап 2. Формирование базовой онтологии

Задачи:
- утвердить канонические сущности;
- утвердить канонические связи;
- выделить ядро бухгалтерской модели;
- зафиксировать обязательные поля.

Результат:
- `ontology_v0_1.md`
- `mapping_1c_odata_v0_1.md`

### Этап 3. Probe-проверка цепочек

Задачи:
- прогнать ключевые document/posting/account/subconto цепочки;
- проверить контрагентов, договоры, расчёты, банк;
- собрать evidence по каждой связи.

Результат:
- `probe_matrix.md`
- `relationship_evidence.json`

### Этап 4. Вердикт по OData

Задачи:
- определить, хватает ли OData для MVP;
- определить, нужен ли гибридный слой;
- определить, надо ли идти глубже в 1С.

Результат:
- `decision_report_oddata_vs_deeper_access.md`

### Этап 5. Подготовка к MCP / assistant layer

Задачи:
- на базе подтверждённой онтологии описать инструменты MCP;
- выделить сценарии запросов;
- построить explainable ответы поверх канонической модели.

Результат:
- спецификация инструментов MCP;
- список первых assistant-сценариев.

---

## 14. Что должен сделать Codex на этом этапе

### 14.1. Обязательные задачи

1. Скачать и распарсить `$metadata`.
2. Собрать shortlist сущностей высокого приоритета.
3. Построить базовую онтологию v0.1.
4. Построить mapping `1C OData -> ontology`.
5. Выполнить probe-цепочки.
6. Для каждой связи выдать статус:
   - `direct`
   - `derivable`
   - `opaque`
   - `missing`
7. Сформировать инженерный вывод:
   - OData достаточно;
   - OData частично достаточно;
   - OData недостаточно и нужен deeper access.

### 14.2. Что нельзя делать

- Нельзя объявлять OData “достаточным” только потому, что читаются entity sets.
- Нельзя считать перечень сущностей онтологией.
- Нельзя делать вывод о полноте без проверки document/posting/account/subconto цепочек.
- Нельзя уходить в raw SQL как в основной semantic-layer без проверки объектной модели 1С.

---

## 15. Критерий успеха этапа

Этап считается успешным, если по его итогу есть:

1. Формализованная базовая онтология бухгалтерского ядра.
2. Подтверждённый mapping из 1С OData в канонический слой.
3. Матрица связей с evidence по каждой критичной цепочке.
4. Честный вердикт:
   - хватает ли OData;
   - где OData заканчивается;
   - нужен ли следующий, более глубокий способ доступа.

Главный смысл этапа: **не доказать любой ценой, что OData подходит**, а быстро и жёстко определить его реальный потолок.

---

## 16. Рекомендация по следующему шагу

Следующим практическим шагом нужно запускать именно **Этап 1 + Этап 2 + первые probe-запросы** в одном спринте:

1. распарсить `$metadata`;
2. собрать `ontology_v0_1`;
3. выбрать 6 ключевых цепочек;
4. прогнать их;
5. выдать вердикт по полноте OData.

И только после этого принимать решение:
- остаёмся на OData,
- идём в гибрид,
- или сразу проектируем более глубокий коннектор внутрь 1С.
