"""Генерирует contracts/ex-payload-v1.schema.json и contracts/examples/ex-payload-*.json (docs #208). Запуск из корня репозитория: .venv/bin/python -I scripts/kfo_contract/gen_ex_payload.py Руками схему и примеры не править: правка здесь → перегенерация → make check. Примеры — группа «Альфа / Бета / Гамма» сквозного примера §8 «КФО» (kfo_example.py, gen_kfo_openapi.py). """ import copy import json import sys from pathlib import Path HERE = Path(__file__).resolve().parent ROOT = HERE.parents[1] sys.path.insert(0, str(HERE)) import gen_kfo_openapi as kfo # noqa: E402 MONEY_RE = r"^-?\d{1,16}\.\d{2}$" M = {"type": "string", "pattern": MONEY_RE} MN = {"type": ["string", "null"], "pattern": MONEY_RE} PN = {"type": ["string", "null"], "pattern": r"^-?\d{1,5}\.\d{2}$"} UUID = {"type": "string", "format": "uuid"} UUIDN = {"type": ["string", "null"], "format": "uuid"} STR = {"type": "string"} STRN = {"type": ["string", "null"]} DATE = {"type": "string", "format": "date"} DT = {"type": "string", "format": "date-time"} def d(name): return {"$ref": f"#/$defs/{name}"} def arr(x): return {"type": "array", "items": x} def obj(props, required=None, closed=False, desc=None): o = {"type": "object", "properties": props, "required": list(props) if required is None else required, "additionalProperties": not closed} if desc: o["description"] = desc return o TYPES = { # item_type → (единица, $def данных) "summary_osv": ("rub", "SummaryOsvData"), "vgo_pairs": ("rub", "VgoPairsData"), "chess": ("rub", "ChessData"), "kfo_balance": ("thousand_rub", "KfoBalanceData"), "kfo_income": ("thousand_rub", "KfoIncomeData"), "goodwill": ("rub", "GoodwillData"), "corrections": ("rub", "CorrectionsData"), "other_report": ("thousand_rub", "OtherReportData"), "version_card": ("none", "VersionCardData"), } def kfo_defs(): """$defs КФО — из контракта КФО (gen_kfo_openapi.SCHEMAS), ссылки переведены на $defs, данные открыты.""" raw = json.loads(json.dumps(kfo.SCHEMAS).replace("#/components/schemas/", "#/$defs/")) out = {} for name, sch in raw.items(): if name in ("KfoAnnotationsIn", "KfoCommentIn", "ErrorDetail", "ErrorOut", "KfoResultOut"): continue sch = copy.deepcopy(sch) sch["additionalProperties"] = True out[name] = sch return out def defs(): out = kfo_defs() res = kfo.SCHEMAS["KfoResultOut"]["properties"] base = {k: json.loads(json.dumps(v).replace("#/components/schemas/", "#/$defs/")) for k, v in res.items() if k not in ("editable", "read_only_reason", "balance", "income")} out["KfoBalanceData"] = obj({**base, "balance": d("KfoStatementOut")}, desc="KfoResultOut без editable/read_only_reason, только отчёт ББ") out["KfoBalanceData"]["not"] = {"required": ["income"]} out["KfoIncomeData"] = obj({**base, "income": d("KfoStatementOut")}, desc="KfoResultOut без editable/read_only_reason, только отчёт ОФР") out["KfoIncomeData"]["not"] = {"required": ["balance"]} out["Ref"] = obj({"id": UUID, "name": STR}) out["UserRef"] = obj({"user_id": UUIDN, "full_name": STR}, desc="Пользователь с ФИО на дату верификации (user_id — справочно, app_user не удаляется)") # Сводная ОСВ — dev/api-contract-slice-4.md §3 out["ConsolidatedRowOut"] = obj({ "legal_entity_id": UUID, "legal_entity_name": STR, "legal_entity_inn": STRN, "account_code": STRN, "period": STR, "is_cumulative": {"type": "boolean"}, "counterparty_name": STRN, "counterparty_inn": STRN, "counterparty_id": UUIDN, "counterparty_entity_name": STRN, "counterparty_entity_inn": STRN, "counterparty_type": {"type": "string", "enum": ["GSK", "GK", "EXTERNAL"]}, "match_kind": STRN, "opening_debit": MN, "opening_credit": MN, "turnover_debit": MN, "turnover_credit": MN, "closing_debit": MN, "closing_credit": MN, }, desc="ConsolidatedRowOut (dev/api-contract-slice-4.md §3); entry_ids, warnings — справочно, необязательны") out["OsvGapOut"] = obj({"legal_entity_id": UUID, "legal_entity_name": STR, "account_code": STR, "missing_quarters": arr({"type": "integer", "minimum": 1, "maximum": 4})}) out["OsvSummaryOut"] = obj({"rows_total": {"type": "integer"}, "gaps": arr(d("OsvGapOut"))}) out["SummaryOsvData"] = obj({"rows": arr(d("ConsolidatedRowOut")), "summary": d("OsvSummaryOut")}) # Таблица корректировок — dev/api-contract-corrections.* out["CorrectionEntryOut"] = obj({"legal_entity_id": UUID, "counterparty_id": UUID, "account_code": STR, "side": {"type": "string", "enum": ["D", "K"]}, "amount": M, "decision": STR}, desc="строка ОСВ агрегата (нужна выгрузке таблицы корректировок)") out["AggregateSideOut"] = obj({"article_line": STRN, "accounts": arr(STR), "amount": M, "entries": arr(d("CorrectionEntryOut"))}) out["CorrectionLineOut"] = obj({"line_code": STR, "amount": M}) out["CorrectionOut"] = obj({"status": {"type": "string", "enum": ["APPLIED"]}, "version_no": {"type": "integer"}, "debit": arr(d("CorrectionLineOut")), "credit": arr(d("CorrectionLineOut")), "comment": STR, "updated_by": {}, "updated_at": DT}, desc="CorrectionOut; в срезе только APPLIED") out["CorrectionAggregateOut"] = obj({ "rule_no": {"type": "integer"}, "company_1": d("Ref"), "company_2": d("Ref"), "side_1": d("AggregateSideOut"), "side_2": d("AggregateSideOut"), "deviation_amount": M, "deviation_percent": PN, "exceeds_threshold": {"type": "boolean"}, "status": {"type": "string", "enum": ["AUTO", "DISCREPANCY", "ONE_SIDED", "MANUAL"]}, "eliminated_amount": M, "correction": {"anyOf": [d("CorrectionOut"), {"type": "null"}]}, }) out["UnallocatedEntryOut"] = obj({"owner": d("Ref"), "counterparty": d("Ref"), "account_code": STR, "side": {"type": "string", "enum": ["D", "K"]}, "amount": M, "reason": STR, "excluded": {"type": "boolean"}}) out["CorrectionTotalsOut"] = obj({"amount_1": M, "amount_2": M, "deviation_amount": M, "correction_debit": M, "correction_credit": M}) out["CorrectionTableData"] = obj({ "statement_type": {"type": "string", "enum": ["balance", "income"]}, "rules_version_no": {"type": "integer"}, "aggregates": arr(d("CorrectionAggregateOut")), "unallocated": arr(d("UnallocatedEntryOut")), "totals": d("CorrectionTotalsOut"), }, desc="CorrectionTableOut без editable/read_only_reason") out["VgoPairsData"] = obj({"balance": d("CorrectionTableData"), "income": {"anyOf": [d("CorrectionTableData"), {"type": "null"}]}}) out["CorrectionsData"] = obj({"items": arr(obj({ "statement_type": {"type": "string", "enum": ["balance", "income"]}, "rule_no": {"type": "integer"}, "company_1": d("Ref"), "company_2": d("Ref"), "correction": d("CorrectionOut")}))}) # Шахматка — dev/frontend-api-guide.md §5.7.1 out["MatrixCellOut"] = obj({"company_a_id": UUID, "company_b_id": UUID, "amount_a": M, "amount_b": M, "variance_amount": M, "variance_percent": PN, "exceeds_threshold": {"type": "boolean"}, "one_sided": {"type": "boolean"}}) out["IntercompanyMatrixOut"] = obj({"companies": arr(d("Ref")), "cells": arr(d("MatrixCellOut"))}, desc="IntercompanyMatrixOut; osv_entry_ids_* — справочно") out["ResultTableOut"] = obj({"companies": arr(d("Ref")), "articles": arr(obj({ "code": STR, "name": STR, "amounts": arr(obj({"company_id": UUID, "amount": M})), "group_total": M}))}) out["ChessData"] = obj({"matrix_all": d("IntercompanyMatrixOut"), "presets": arr(obj({"rule_no": {"type": "integer"}, "matrix": d("IntercompanyMatrixOut")})), "result_table": d("ResultTableOut")}) # Гудвилл — dev/api-contract-goodwill.* out["GoodwillTotalsOut"] = obj({"financial_investment_amount": MN, "charter_capital_amount": MN, "participation_amount": MN, "goodwill_amount": MN, "goodwill_in_kfo_amount": MN}) out["GoodwillRowOut"] = obj({ "head_legal_entity": d("Ref"), "subsidiary_legal_entity": d("Ref"), "ownership_share": PN, "financial_investment_amount": MN, "charter_capital_amount": MN, "additional_capital_amount": MN, "participation_amount": MN, "goodwill_amount": MN, "include_in_kfo": {"type": "boolean"}, "comment": STRN, "has_investments": {"type": "boolean"}}) out["GoodwillData"] = obj({"goodwill_enabled": {"const": True}, "rows": arr(d("GoodwillRowOut")), "groups": arr(obj({"head_legal_entity": d("Ref"), "totals": d("GoodwillTotalsOut")})), "totals": d("GoodwillTotalsOut")}, desc="GoodwillTableOut без editable/read_only_reason; пишется только при goodwill_enabled") out["OtherReportData"] = obj({"report_kind": {"const": "client_kfo_comparison"}, "lines": arr(obj({ "statement_type": {"type": "string", "enum": ["balance", "income"]}, "line_code": STR, "line_name": STR, "client_amount": MN, "client_vgo_amount": MN, "bank_amount": MN, "bank_vgo_amount": MN, "deviation_amount": MN, "deviation_percent": PN, "deviation_reason": STRN, "comment": STRN}))}) statuses = kfo.SCHEMAS["KfoRequisitesOut"]["properties"]["version_status"]["enum"] out["VersionCardData"] = obj({ "company_group": d("Ref"), "related_group": d("Ref"), "reporting_date": DATE, "year": {"type": "integer"}, "quarter": {"type": "integer", "minimum": 1, "maximum": 4}, "version_no": {"type": "integer"}, "scenario": {"type": "string", "enum": ["CREATE", "CONFIRM"]}, "approach": {"type": "string", "enum": ["BASIC", "EXTENDED"]}, "goodwill_enabled": {"type": "boolean"}, "initiator": d("UserRef"), "initiator_office": d("Ref"), "members": arr(obj({"legal_entity_id": UUID, "name": STR, "inn": STR, "is_head_entity": {"type": "boolean"}})), "history": arr(obj({"from_status": {"type": ["string", "null"], "enum": statuses + [None]}, "to_status": {"type": "string", "enum": statuses}, "changed_by": d("UserRef"), "changed_at": DT, "comment": STRN})), "verified_by": d("UserRef"), "verified_at": DT, "uob_decision_no": STRN, "uob_decision_date": {"type": ["string", "null"], "format": "date"}, "methodology_deviations": STRN, }, desc="Карточка версии на дату верификации (DOC-274687 доп. 4; новый item_type v5.26)") return out def schema(): branches = [] for t, (units, data_def) in TYPES.items(): branches.append({"if": {"properties": {"item_type": {"const": t}}}, "then": {"properties": {"units": {"const": units}, "data": d(data_def)}}}) return { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "ex-payload-v1.schema.json", "title": "Элемент среза ЕХ: ex_snapshot_item.payload, версия 1.0", "description": "Конверт замороженных данных элемента среза ЕХ (context/05-domain-rules.md §14). data — ответ API " "экрана рабочей версии на момент верификации без полей редактирования; у primary_document " "payload нет. Сгенерировано scripts/kfo_contract/gen_ex_payload.py — руками не править.", "type": "object", "additionalProperties": False, "required": ["schema_version", "item_type", "units", "generated_at", "source_version_no", "data"], "properties": { "schema_version": {"const": "1.0"}, "item_type": {"type": "string", "enum": list(TYPES)}, "units": {"type": "string", "enum": ["rub", "thousand_rub", "none"]}, "generated_at": DT, "source_version_no": {"type": "integer", "minimum": 1}, "data": {"type": "object"}, }, "allOf": branches, "$defs": defs(), } # ---------- примеры ---------- IDS = kfo.IDS REF = {c: {"id": IDS[c], "name": kfo.ex.NAMES[c]} for c in kfo.ex.COMPANIES} USER = {"user_id": "44444444-4444-4444-8444-444444444444", "full_name": "Петрова Мария Ивановна"} USER2 = {"user_id": "55555555-5555-4555-8555-555555555555", "full_name": "Соколов Игорь Петрович"} GEN = "2025-11-20T10:05:00Z" def env(t, data): return {"schema_version": "1.0", "item_type": t, "units": TYPES[t][0], "generated_at": GEN, "source_version_no": 1, "data": data} def examples(): res = kfo.result(True, frozen=True) for k in ("editable", "read_only_reason"): res.pop(k) kb = {k: v for k, v in res.items() if k != "income"} ki = {k: v for k, v in res.items() if k != "balance"} out = {"kfo_balance": env("kfo_balance", kb), "kfo_income": env("kfo_income", ki)} def entry(c, cp, acc, side, amt): return {"entry_ids": [], "legal_entity_id": IDS[c], "counterparty_id": IDS[cp], "account_code": acc, "side": side, "amount": amt, "decision": "AUTO", "candidate_rule_ids": []} corr_ba = {"status": "APPLIED", "version_no": 1, "debit": [{"line_code": "1230", "amount": "10000000.00"}], "credit": [{"line_code": "1520", "amount": "10000000.00"}], "comment": "Сверка Бета → Альфа: разница — аванс, исключаем подтверждённое", "reason_code": None, "updated_by": USER, "updated_at": "2025-11-12T14:30:00Z"} corr_ac = {"status": "APPLIED", "version_no": 2, "debit": [{"line_code": "1230", "amount": "20000000.00"}, {"line_code": "1170", "amount": "5000000.00"}], "credit": [{"line_code": "1520", "amount": "22500000.00"}], "comment": "Часть долга Гаммы переведена в займ — разнесено по статьям", "reason_code": None, "updated_by": USER, "updated_at": "2025-11-13T09:10:00Z"} aggs = [ {"rule_id": "66666666-6666-4666-8666-000000000006", "rule_no": 6, "company_1": REF["A"], "company_2": REF["B"], "side_1": {"article_line": "1230", "accounts": ["62.01"], "amount": "102000000.00", "entries": [entry("A", "B", "62.01", "D", "102000000.00")]}, "side_2": {"article_line": "1520", "accounts": ["60.01"], "amount": "100000400.50", "entries": [entry("B", "A", "60.01", "K", "100000400.50")]}, "deviation_amount": "1999599.50", "deviation_percent": "2.00", "exceeds_threshold": False, "status": "AUTO", "eliminated_amount": "100000400.50", "composition_changed": False, "correction": None}, {"rule_id": "66666666-6666-4666-8666-000000000006", "rule_no": 6, "company_1": REF["B"], "company_2": REF["A"], "side_1": {"article_line": "1230", "accounts": ["62.01"], "amount": "10000000.00", "entries": [entry("B", "A", "62.01", "D", "10000000.00")]}, "side_2": {"article_line": "1520", "accounts": ["60.01", "76.05"], "amount": "50000000.00", "entries": [entry("A", "B", "60.01", "K", "12000000.00"), entry("A", "B", "76.05", "K", "38000000.00")]}, "deviation_amount": "40000000.00", "deviation_percent": "400.00", "exceeds_threshold": True, "status": "DISCREPANCY", "eliminated_amount": "0.00", "composition_changed": False, "correction": corr_ba}, ] vgo = {"balance": {"version_id": kfo.VERSION, "statement_type": "balance", "rules_version_no": 1, "rules": [], "aggregates": aggs, "unallocated": [{"entry_ids": [], "owner": REF["C"], "counterparty": REF["A"], "account_code": "76.09", "line_code": None, "side": "D", "amount": "350000.00", "candidate_rule_ids": [], "reason": "MULTIPLE_RULES", "excluded": True}], "totals": {"amount_1": "112000000.00", "amount_2": "150000400.50", "deviation_amount": "41999599.50", "correction_debit": "10000000.00", "correction_credit": "10000000.00"}}, "income": None} out["vgo_pairs"] = env("vgo_pairs", vgo) out["corrections"] = env("corrections", {"items": [ {"statement_type": "balance", "rule_no": 6, "company_1": REF["B"], "company_2": REF["A"], "correction": corr_ba}, {"statement_type": "balance", "rule_no": 6, "company_1": REF["A"], "company_2": REF["C"], "correction": corr_ac}, ]}) def row(c, acc, cp, ctype, cd=None, cc=None): return {"entry_ids": [], "legal_entity_id": IDS[c], "legal_entity_name": kfo.ex.NAMES[c], "legal_entity_inn": kfo.ex.INN[c], "account_code": acc, "account_root": acc.split(".")[0], "period": "2025 Q3", "is_cumulative": False, "row_number": None, "counterparty_name": kfo.ex.NAMES.get(cp, cp), "counterparty_inn": kfo.ex.INN.get(cp), "counterparty_id": IDS.get(cp), "counterparty_entity_name": kfo.ex.NAMES.get(cp), "counterparty_entity_inn": kfo.ex.INN.get(cp), "counterparty_type": ctype, "match_kind": "INN" if cp in IDS else None, "match_stored": True, "opening_debit": None, "opening_credit": None, "turnover_debit": None, "turnover_credit": None, "closing_debit": cd, "closing_credit": cc, "warnings": []} ext = row("A", "60.01", "ООО «Поставщик»", "EXTERNAL", cc="5400000.00") ext.update({"counterparty_inn": "7702999999", "counterparty_id": None, "counterparty_entity_name": None, "counterparty_entity_inn": None}) out["summary_osv"] = env("summary_osv", { "rows": [row("A", "62.01", "B", "GSK", cd="102000000.00"), row("B", "60.01", "A", "GSK", cc="100000400.50"), ext], "summary": {"rows_total": 3, "unmapped_total": 0, "auto_matched_total": 0, "documents_total": 9, "gaps": [{"legal_entity_id": IDS["C"], "legal_entity_name": kfo.ex.NAMES["C"], "account_code": "76", "missing_quarters": [1]}], "counter_pairs": []}}) cell = {"company_a_id": IDS["A"], "company_b_id": IDS["B"], "amount_a": "102000000.00", "amount_b": "100000400.50", "variance_amount": "1999599.50", "variance_percent": "2.00", "exceeds_threshold": False, "one_sided": False, "skipped_osv_entry_count": 0} matrix = {"companies": [REF[c] for c in kfo.ex.COMPANIES], "cells": [cell]} out["chess"] = env("chess", {"matrix_all": matrix, "presets": [{"rule_no": 6, "matrix": matrix}], "result_table": {"companies": [REF[c] for c in kfo.ex.COMPANIES], "articles": [ {"code": "1230", "name": "Дебиторская задолженность", "group_total": "112000000.00", "amounts": [{"company_id": IDS["A"], "amount": "102000000.00"}, {"company_id": IDS["B"], "amount": "10000000.00"}]}]}}) gw_tot = {"financial_investment_amount": "50000000.00", "charter_capital_amount": "40000000.00", "participation_amount": "32000000.00", "goodwill_amount": "18000000.00", "goodwill_in_kfo_amount": "18000000.00"} out["goodwill"] = env("goodwill", { "version_id": kfo.VERSION, "goodwill_enabled": True, "rows": [{"head_legal_entity": REF["A"], "subsidiary_legal_entity": REF["B"], "ownership_share": "80.00", "financial_investment_amount": "50000000.00", "charter_capital_amount": "40000000.00", "additional_capital_amount": "0.00", "participation_amount": "32000000.00", "goodwill_amount": "18000000.00", "include_in_kfo": True, "comment": "Доля 80 % по выписке ЕГРЮЛ на 01.10.2025", "has_investments": True, "warnings": [], "updated_by": USER, "updated_at": "2025-11-12T11:00:00Z"}], "groups": [{"head_legal_entity": REF["A"], "totals": gw_tot}], "totals": gw_tot}) out["version_card"] = env("version_card", { "company_group": {"id": "77777777-7777-4777-8777-777777777777", "name": "ГК «Альфа»"}, "related_group": {"id": "88888888-8888-4888-8888-888888888888", "name": "ГСК «Альфа»"}, "reporting_date": "2025-10-01", "year": 2025, "quarter": 3, "version_no": 1, "scenario": "CREATE", "approach": "BASIC", "goodwill_enabled": True, "initiator": USER, "initiator_office": {"id": "99999999-0000-4000-8000-000000000001", "name": "Ростовский РФ"}, "members": [{"legal_entity_id": IDS[c], "name": kfo.ex.NAMES[c], "inn": kfo.ex.INN[c], "is_head_entity": c == "A"} for c in kfo.ex.COMPANIES], "history": [{"from_status": None, "to_status": "INITIATED", "changed_by": USER, "changed_at": "2025-11-05T09:00:00Z", "comment": None}, {"from_status": "VERIFICATION_GO", "to_status": "VERIFIED", "changed_by": USER2, "changed_at": "2025-11-20T10:00:00Z", "comment": "Решение УОБ-118"}], "verified_by": USER2, "verified_at": "2025-11-20T10:00:00Z", "uob_decision_no": "УОБ-118", "uob_decision_date": "2025-11-20", "methodology_deviations": "Отклонений от Методики нет"}) out["other_report"] = env("other_report", {"report_kind": "client_kfo_comparison", "lines": [ {"statement_type": "balance", "line_code": "1600", "line_name": "БАЛАНС", "client_amount": "590000.00", "client_vgo_amount": "180000.00", "bank_amount": "588500.00", "bank_vgo_amount": "179500.00", "deviation_amount": "1500.00", "deviation_percent": "0.25", "deviation_reason": "Гудвилл у клиента не выделен", "comment": None}]}) return out def main(): (ROOT / "contracts" / "ex-payload-v1.schema.json").write_text( json.dumps(schema(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8") for t, doc in examples().items(): (ROOT / "contracts" / "examples" / f"ex-payload-{t.replace('_', '-')}.json").write_text( json.dumps(doc, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") print("ok") if __name__ == "__main__": main()