70 lines
4.9 KiB
Markdown
70 lines
4.9 KiB
Markdown
# Схема среза ЕХ 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` с примерами и проверкой, §14 правил и правки 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` при выключенном гудвилле не пишется — правило в §14, не в схеме; пример — только включённый.
|
||
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: §14, DBML, OQ
|
||
|
||
**Files:** Modify `context/05-domain-rules.md` (+ §14 после §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` (ссылка на §14).
|
||
|
||
- [ ] Step 1: Run `grep -c "EX_SNAPSHOT_WRITE\|version_card" model/data-model-v5.26.dbml` — Expected: 0 (RED).
|
||
- [ ] Step 2: §14 по 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.
|