orchestrator/docs/work-items/ORCH-098/08-data-requirements.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-098	architecture	architect	proposed	2026-06-10	claude-opus-4-8

08 — Требования к данным: ORCH-098 — машинный журнал уроков lessons

Work Item: ORCH-098 · Repo: orchestrator · Стадия: architecture

When-applicable: задача добавляет одну таблицу на общую прод-БД. Схемы существующих таблиц — не затрагиваются.

Изменения схемы БД

Новая аддитивная таблица lessons + три индекса, создаются идемпотентно в db.init_db() (CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS), restart-safe (паттерн repo_freeze, coverage_baseline). На уже существующей таблице новые/будущие колонки добавляются через _ensure_column(conn, "lessons", "<col>", "<decl>") (src/db.py:341) — forward-safe, без миграции данных. DDL — см. ADR-001 D1.

Существующие таблицы (tasks/jobs/agent_runs/events/job_deps/repo_freeze/ coverage_baseline/tracker_messages) — байт-в-байт не тронуты (NFR-3, AC-8).

Новые/изменённые сущности

Сущность lesson — одна запись структурированного отклонения конвейера. Колонки:

Колонка	Тип	Null	Назначение
id	INTEGER PK AUTOINCREMENT	—	суррогатный ключ
created_at	TEXT DEFAULT datetime('now')	NOT NULL	момент записи
updated_at	TEXT	NULL	момент последнего update
lesson_type	TEXT	NOT NULL	slug-тип (gate_failure/merge_hold/transient_retry/deploy_degraded/…)
work_item_id	TEXT	NULL	контекст: задача (ORCH-NNN/ET-NNN)
task_id	INTEGER	NULL	контекст: внутренний id задачи
stage	TEXT	NULL	контекст: стадия конвейера
agent	TEXT	NULL	контекст: агент-роль
repo	TEXT	NULL	контекст: репозиторий, разрез выборки
root_cause	TEXT	NULL	анализ: корневая причина (если известна)
suggestion	TEXT	NULL	анализ: предложенное улучшение (если есть)
status	TEXT DEFAULT 'new'	NOT NULL	new/in_progress/closed/linked
related_task	TEXT	NULL	связанная заведённая задача
attribution	TEXT	NULL	АТРИБУЦИЯ: platform/project/both/unknown
target_repo	TEXT	NULL	АТРИБУЦИЯ: кого касается улучшение
target_domain	TEXT	NULL	АТРИБУЦИЯ: reliability/quality/economy/features/scale
source	TEXT	NULL	auto (детектор) / manual (оператор/Стрим)
detail	TEXT	NULL	свободный JSON/текст — payload детектора

Инварианты данных:

• Три колонки атрибуции (attribution/target_repo/target_domain) присутствуют в исходной схеме, нуллабельны (требование Славы 10.06, NFR-6, AC-2) — при автозаписи допустимо пусто/unknown; проставляются позже через update (AC-5).
• Без enum/CHECK-констрейнтов — значения lesson_type/attribution/target_domain суть конвенция строковых слагов (forward-compatible: новый тип не требует миграции).
• Индексы: idx_lessons_type_status (lesson_type, status) — выборка/snapshot; idx_lessons_repo (repo) — репо-разрез; idx_lessons_wi_type (work_item_id, lesson_type) — дедуп автозаписи (ADR-001 D4).

Совместимость данных / миграции

• Аддитивно / идемпотентно / restart-safe: только новая таблица + индексы; повторный init_db() не падает и не дублирует (NFR-4).
• Общая прод-БД (self-hosting): таблица создаётся на том же файле БД, что обслуживает orchestrator и enduro-trails. Уроки про любой репо хранятся в одной таблице; изоляция enduro — таблица аддитивна и не участвует в пайплайне enduro (NFR-3); репо-разрез — поле repo + фильтр выборки (ADR-001 D2).
• Объём строки — короткие текстовые поля; detail — компактный payload. Запись — один INSERT, чтение — простой параметризованный SELECT … ORDER BY id DESC LIMIT ? (NFR-5; общий хост впритык: RAM/диск).
• Ретенция / архивация — вне объёма v1; тренд роста и будущая стратегия — 10-tech-risks.md (TR-2).
• Миграция исторических уроков из memory/ — вне объёма (BRD §2).