# Схема среза ЕХ 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.