NODEDC_1C/docs/ADDRESS/address_query/query_recipes_v1.md

Query Recipes V1 (Address Query)

Дата: 2026-04-13
Контур: question_mode=address_query (live-first, whitelist only)

1) Safe Access Contract

Каноническая цепочка исполнения:

intent -> filters -> recipe -> MCP -> materialization -> factual/limited

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

• LLM не генерирует свободные SQL/1C-запросы.
• Runtime выбирает только recipe_id из статического каталога.
• Если фильтры/якоря невалидны или не подтверждены, возвращается LIMITED_WITH_REASON.

2) Entity Families (runtime focus)

• ACCOUNTING_REGISTER (РегистрБухгалтерии.Хозрасчетный)
• DOCUMENT (СписаниеСРасчетногоСчета, ПоступлениеНаРасчетныйСчет, документные строки)
• DOCUMENT_JOURNAL
• NSI_CATALOG (договоры, контрагенты)
• CHART_OF_ACCOUNTS

3) Filter Catalog (runtime)

filter	type	required_when (runtime)	notes
period_from	date (YYYY-MM-DD)	периодные выборки	начало окна
period_to	date (YYYY-MM-DD)	периодные выборки	конец окна
as_of_date	date (YYYY-MM-DD)	balance/drilldown/open-items	для account intents defaulted если не задан
organization	string	optional	passthrough-filter
counterparty	string	by-counterparty intents	допускается heuristic extraction
contract	string	by-contract intents	допускается heuristic extraction
account	string (60, 62.01, ...)	account intents	strict token normalization
document_type	string	optional (пока ограниченно используется)	runtime V1 не строит отдельный by-type intent
document_ref	string	optional	point lookup
status	string	optional	reserved
limit	int	optional	extractor default: 20
sort	enum	optional	period_desc / period_asc

4) Runtime Recipe Catalog (actual)

recipe_id	intent	purpose	required_filters	optional_filters	query_template	account_scope_mode
address_period_coverage_profile_v1	period_coverage_profile	профиль покрытия периодов + топ год/месяц активности	-	period_from, period_to, organization, limit	period_profile	preferred
address_document_type_and_account_section_profile_v1	document_type_and_account_section_profile	профиль типов документов + заполненность разделов учета	-	period_from, period_to, organization, limit	document_section_profile	preferred
address_movements_payables_v1	list_payables_counterparties	movement-срез по обязательствам	-	as_of_date, counterparty, contract, limit	movements	preferred
address_movements_receivables_v1	list_receivables_counterparties	movement-срез по требованиям	-	as_of_date, counterparty, contract, limit	movements	preferred
address_open_contracts_confirmed_as_of_date_v1	open_contracts_confirmed_as_of_date	подтвержденный срез открытых договоров на дату	as_of_date	period_from, period_to, organization, counterparty, contract, limit, sort	open_contracts_confirmed_as_of_balance_profile	strict
address_open_contracts_candidates_v1	list_open_contracts	диагностические кандидаты незакрытых договоров	-	as_of_date, organization, limit	movements	preferred
address_open_items_by_party_or_contract_v1	open_items_by_counterparty_or_contract	открытые позиции по party/contract	- (service guard: нужен counterparty OR contract)	as_of_date, counterparty, contract, limit	movements	preferred
address_documents_by_counterparty_v1	list_documents_by_counterparty	документы по контрагенту	counterparty	period_from, period_to, as_of_date, organization, limit, sort	bank_docs	preferred
address_bank_operations_by_counterparty_v1	bank_operations_by_counterparty	банковские операции по контрагенту	counterparty	period_from, period_to, as_of_date, organization, limit, sort	bank_docs	preferred
address_documents_by_contract_v1	list_documents_by_contract	документы по договору	contract	period_from, period_to, as_of_date, organization, counterparty, limit, sort	movements	preferred
address_bank_operations_by_contract_v1	bank_operations_by_contract	банковские операции по договору	contract	period_from, period_to, as_of_date, organization, counterparty, limit, sort	movements	preferred
address_documents_forming_balance_v1	documents_forming_balance	drilldown документов, формирующих остаток	account, as_of_date	organization, counterparty, contract, period_from, period_to, limit, sort	movements	strict
address_movements_account_snapshot_v1	account_balance_snapshot	snapshot движений по счету	account (as_of_date defaulted in extractor)	as_of_date, period_from, period_to, limit	movements	strict

5) Limit and Scope Policy (actual)

• Базовый max limit: 200.
• Расширенный max limit (1000) для:
  • period_coverage_profile;
  • document_type_and_account_section_profile;
  • documents/bank by counterparty|contract;
  • open_items_by_counterparty_or_contract;
  • list_open_contracts;
  • open_contracts_confirmed_as_of_date.
• Для all-time запросов documents/bank by * runtime поднимает limit до max.
• Для account intents при явном account limit поднимается до 200.

6) Stage Status Taxonomy (runtime)

• skipped
• error
• no_raw_rows
• raw_rows_received_but_not_materialized
• materialized_but_not_anchor_matched
• materialized_but_filtered_out_by_recipe
• matched_non_empty

Legacy совместимость:

• mcp_call_status_legacy=materialized_but_not_matched для двух split-статусов materialized-*.

7) Runtime Fallback Behaviors (actual)

• При list_documents_by_contract и пустом документном отборе, но с anchor rows:
  • fallback на банковские строки по договору или на anchor rows.
• Для documents/bank by * при пустом заданном периоде:
  • auto-broaden периода до доступных данных (period_window_auto_broadened_to_available_data).
• Для documents/bank by * при anchor mismatch:
  • factual fallback на ближайшие строки (anchor_not_matched_fallback_rows) вместо silent empty.
• Для open_contracts_confirmed_as_of_date:
  • exact недоступность должна заканчиваться LIMITED_WITH_REASON;
  • list_open_contracts допустим только как отдельный diagnostic capability, не как silent fallback.

8) Result Modes

• FACTUAL_LIST
• FACTUAL_SUMMARY
• LIMITED_WITH_REASON

Фактическая реализация composeStage сейчас отдает:

• FACTUAL_SUMMARY для account_balance_snapshot, period_coverage_profile, document_type_and_account_section_profile;
• для остальных factual intents — FACTUAL_LIST.

9) Guardrails

• whitelist recipes only
• read-only MCP
• no free-form query generation
• no silent source substitution