arm-ka-docs/openspec/changes/ex-payload-schema/plans/2026-11-06-ex-payload.md

Схема среза ЕХ ex-payload-v1 — план

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: схема contracts/ex-payload-v1.schema.json с примерами и проверкой, §15 правил и правки DBML v5.26 — к старту AURORA-1560 (12.11.2026).

Architecture: JSON Schema 2020-12: конверт + data по item_type через $defs; DTO-определения повторяют обязательные поля контрактов API (additionalProperties: true в data). Примеры — на числах scripts/kfo_contract/kfo_example.py (КФО) и ручных данных той же группы «Альфа/Бета/Гамма».

Tech Stack: JSON Schema 2020-12, scripts/validate_contracts.py (jsonschema), Markdown, DBML, OpenSpec.

Spec: openspec/changes/ex-payload-schema/design.md, proposal.md.

Пути — от корня worktree /Users/andrey.epifancev/projects/awp-ca/.wt/ex-payload/docs.

Global Constraints

• schema_version = "1.0"; $id — ex-payload-v1.schema.json; units ∈ {rub, thousand_rub, none}.
• item_type ∈ {summary_osv, vgo_pairs, chess, kfo_balance, kfo_income, goodwill, corrections, other_report, version_card}; у primary_document payload нет.
• Деньги — ^-?\d{1,16}\.\d{2}$; конверт — additionalProperties: false, data — true.
• audit_action.EX_SNAPSHOT_WRITE (раздел KFO); ex_snapshot_item.item_type + version_card; пояснение ex_snapshot.status.
• Новые OQ — с OQ-195.

Review Focus

1. Конверт с item_type, не совпадающим с data (например, kfo_balance с данными гудвилла) — схема отклоняет.
2. kfo_balance без requisites.corrections_balance — отклоняется (нужно форме 2.03.01.01с).
3. goodwill при выключенном гудвилле не пишется — правило в §15, не в схеме; пример — только включённый.
4. Деньги числом (1000.5) вместо строки — отклоняется.
5. Пример kfo_balance совпадает с примером goodwill_exceeded контракта КФО по строкам и сводке.

Пункты 1, 2, 4 — отрицательные примеры в тесте Task 1; 5 — генерацией примера из того же скрипта.

---

Task 1: Схема, примеры, проверка

Files: Create contracts/ex-payload-v1.schema.json, contracts/examples/ex-payload-*.json (минимум kfo_balance, version_card, corrections, summary_osv, vgo_pairs, chess, goodwill), scripts/kfo_contract/gen_ex_examples.py; Modify scripts/validate_contracts.py (+ схема ex-payload, шаблон ex-payload-), scripts/kfo_contract/ (тест отрицательных случаев).

• Step 1: тест scripts/kfo_contract/test_ex_payload.py — положительные примеры проходят; отрицательные (Review Focus 1, 2, 4) — нет. Run: .venv/bin/python -I scripts/kfo_contract/test_ex_payload.py — Expected: FAIL (схемы нет).
• Step 2: схема + генератор примеров (КФО — из kfo_example.py/gen_kfo_openapi.result()) + регистрация в validate_contracts.py.
• Step 3: Run тест и make validate-contracts — Expected: PASS, все ex-payload-* OK.
• Step 4: commit.

Task 2: §15, DBML, OQ

Files: Modify context/05-domain-rules.md (+ §15 после §13), model/data-model-v5.26.dbml, model/entities-v5.26.md, context/07-open-questions.md (OQ-195…), context/09-delivery-plan.md:287 (ссылка на §15).

• Step 1: Run grep -c "EX_SNAPSHOT_WRITE\|version_card" model/data-model-v5.26.dbml — Expected: 0 (RED).
• Step 2: §15 по design §4.3; DBML и entities по §4.4 (пункты changelog 6–8 v5.26); OQ: кто архивирует (ссылка на 1397), ключ ГК/ГСК, повтор при сбое, PDF.
• Step 3: Run тот же grep — Expected: ≥ 2; make check — зелёный.
• Step 4: commit.

Task 3: Spec delta, ревью, PR, Jira

• Step 1: specs/arm-core/spec.md (ADDED: «Срез ЕХ при верификации», «Payload элемента среза»), tasks.md; make validate-openspec CHANGE=ex-payload-schema — valid.
• Step 2: финальное ревью (opus); Critical/Important — исправить.
• Step 3: push, PR (base main, «сливать после #207»), вложения в AURORA-1560 (схема, 05-domain-rules.md, DBML), комментарий в 1560 и 2001.