NODEDC_1C/docs/ADDRESS/address_query/query_recipes_v1.md

Query Recipes V1 (Address Query)

Дата: 2026-03-29
Контур: Stage 4, отдельная ветка question_mode=address_query

1) Safe Access Contract

Цепочка должна быть строго управляемой:

intent -> filters -> recipe -> MCP -> factual result

Ограничения:

• LLM не генерирует произвольный SQL/1C-запрос.
• LLM выбирает только recipe_id из каталога и заполняет параметры.
• Любой нераспознанный или рискованный случай возвращается как LIMITED_WITH_REASON или уходит в deep-analysis.

2) Entity Catalog (P0 for address-query)

Базовые семейства для V1:

• ACCOUNTING_REGISTER (AccountingRegister_Хозрасчетный*)
• DOCUMENT (СписаниеСРасчетногоСчета, ПоступлениеНаРасчетныйСчет, АктСверкиВзаиморасчетов, документные линии)
• DOCUMENT_JOURNAL (ДокументыПоставщиков, ДокументыПокупателей, БанковскиеВыписки)
• NSI_CATALOG (ДоговорыКонтрагентов, плюс фильтровые справочники)
• CHART_OF_ACCOUNTS (Хозрасчетный)

3) Filter Catalog

filter	type	required_when	notes
period_from	date (YYYY-MM-DD)	turnover/list-by-period intents	начало периода
period_to	date (YYYY-MM-DD)	turnover/list-by-period intents	конец периода
as_of_date	date (YYYY-MM-DD)	balance/open-items intents	срез на дату
organization	string/guid	optional	если не задано, берется default company scope
counterparty	string/guid	required for by-counterparty intents	допускается name->id resolver
contract	string/guid	required for by-contract intents	допускается number/name->id resolver
account	string (60, 62.01, ...)	required for account intents	только validated account tokens
document_type	enum/string	required for list-by-type	белый список типов
document_ref	guid/string	required for document drilldown	точечный lookup
status	enum (open, closed, all)	optional	для open/closed срезов
limit	int (1..200)	optional	default 50
sort	enum (date_desc, amount_desc, name_asc)	optional	default recipe-specific

4) Query Recipe Catalog V1

recipe_id	purpose	required_params	optional_params	expected_output_schema	sort/limit rules	drilldown_targets
address.open_contracts.by_asof	Незакрытые договоры на дату	as_of_date	organization, counterparty, limit, sort	contract_ref, contract_name, counterparty_ref, debit, credit, saldo, as_of_date	default saldo_desc, limit=50	address.open_items.by_contract
address.payables.counterparty_totals	Кому должны мы	as_of_date	organization, account, limit	counterparty_ref, counterparty_name, payable_amount, doc_count, as_of_date	default payable_amount_desc, limit=50	address.open_items.by_counterparty
address.receivables.counterparty_totals	Кто должен нам	as_of_date	organization, account, limit	counterparty_ref, counterparty_name, receivable_amount, doc_count, as_of_date	default receivable_amount_desc, limit=50	address.open_items.by_counterparty
address.account.balance_snapshot	Остаток по счету на дату	account, as_of_date	organization, limit	account, debit_balance, credit_balance, net_balance, as_of_date	default account_asc, limit=20	address.balance.drilldown_documents
address.open_items.by_counterparty	Открытые позиции по контрагенту	counterparty, as_of_date	organization, contract, account, limit	document_ref, document_type, document_date, contract_ref, debit, credit, open_amount	default document_date_desc, limit=100	address.documents.by_contract
address.open_items.by_contract	Открытые позиции по договору	contract, as_of_date	organization, counterparty, account, limit	document_ref, document_type, document_date, counterparty_ref, debit, credit, open_amount	default document_date_desc, limit=100	address.documents.by_contract
address.documents.by_counterparty	Документы контрагента за период	counterparty, period_from, period_to	organization, document_type, limit, sort	document_ref, document_type, number, date, amount, posted	default date_desc, limit=100	address.documents.by_contract
address.bank_ops.by_counterparty	Банковские операции по контрагенту	counterparty	period_from, period_to, organization, limit, sort	document_ref, document_type, number, date, amount, posted, bank_account_hint	default date_desc, limit=100	address.documents.by_counterparty
address.documents.by_contract	Документы договора за период	contract, period_from, period_to	organization, document_type, limit, sort	document_ref, document_type, number, date, amount, posted	default date_desc, limit=100	address.balance.drilldown_documents
address.balance.drilldown_documents	Расшифровка остатка до документов	account, as_of_date	organization, counterparty, contract, limit	document_ref, document_type, number, date, debit, credit, delta	default date_desc, limit=150	address.documents.by_counterparty

5) Result Schema (Unified)

{
  "question_mode": "address_query",
  "intent": "list_payables_counterparties",
  "recipe_id": "address.payables.counterparty_totals",
  "filters": {
    "as_of_date": "2026-03-29",
    "organization": "<optional>",
    "limit": 50
  },
  "result_mode": "FACTUAL_SUMMARY",
  "summary": {
    "rows": 12,
    "total_amount": 1543200.50,
    "currency": "RUB"
  },
  "rows": [
    {
      "counterparty_name": "ООО Альфа",
      "payable_amount": 450000.00,
      "doc_count": 7
    }
  ],
  "limitations": []
}

6) Answer Contract

• FACTUAL_LIST: короткий вывод + список строк + totals.
• FACTUAL_SUMMARY: агрегат + top строки + предложение уточнить фильтр при большом объеме.
• LIMITED_WITH_REASON: честная причина ограничения (missing_required_filters, live_unavailable, no_matches_for_filters, unsupported_for_address_query_v1).

7) MCP Execution Notes

• Runtime вызывает MCP proxy (/api/execute_query) только с query-template из recipe и параметрами после валидации.
• Для V1 все recipe выполняются в read-only режиме.
• Ограничения на выборку (limit) и сортировки фиксируются recipe-контрактом, а не свободным текстом вопроса.

8) Account Scope Strategy (M2.3b)

• account_balance_snapshot and documents_forming_balance use strict account scope.
• counterparty-oriented recipes use preferred account scope with runtime fallback to raw rows when scope gives zero rows.
• this keeps account-intent precision while preventing blind row loss on party intents.