50 lines
3.9 KiB
Markdown
50 lines
3.9 KiB
Markdown
---
|
||
work_item: ORCH-119
|
||
stage: architecture
|
||
author_agent: architect
|
||
status: proposed
|
||
created_at: 2026-06-17
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 08 — Требования к данным: ORCH-119 — durable-персист `description` задачи
|
||
|
||
Work Item: **ORCH-119** · Repo: **orchestrator** · Стадия: architecture
|
||
|
||
> When-applicable / информационный (гейтом не парсится). Применимо: фикс требует durable-хранения
|
||
> `description` в строке `tasks` для пути B (отложенный срез ветки, ORCH-088).
|
||
|
||
## Изменения схемы БД
|
||
- **Новая колонка `tasks.description TEXT`** — добавляется идемпотентным
|
||
`_ensure_column(conn, "tasks", "description", "TEXT")` (`src/db.py`, рядом с `tasks.title`,
|
||
`src/db.py:125`). Прецедент 1:1 — `tasks.title` / `tasks.track` / `tasks.cancelled_at`.
|
||
- Базовый `CREATE TABLE tasks` (`src/db.py:31–42`) **не трогается**.
|
||
- Индексы **не требуются** (колонка не участвует в выборках/JOIN; читается по PK `tasks.id`).
|
||
- `NULL` по умолчанию; для уже существующих задач остаётся `NULL` (ретро-генерация вне объёма).
|
||
|
||
## Новые/изменённые сущности
|
||
- **`tasks.description`** — plain-text описание запроса (предпочтительно `description_stripped`
|
||
Plane-issue), записывается **при создании задачи** внутри атомарного INSERT
|
||
`create_task_atomic` (`src/db.py:678–683`; список колонок/значений расширяется, параметр
|
||
`description` аддитивен с дефолтом). Читается на пути B в `_spawn`
|
||
(`SELECT ..., description FROM tasks`, `src/agents/launcher.py:561`) и передаётся в
|
||
`_materialize_deferred_branch` → `_create_initial_docs`.
|
||
- Инвариант данных: значение пишется **как есть**, без обрезки/искажения; многострочный текст и
|
||
markdown-спецсимволы сохраняются (`00-business-request.md` гейтом не парсится — спецсимволы
|
||
безопасны, NFR-2). Пустое/`NULL` → рендер деградирует на fallback-маркер (ADR-001 D3), не на
|
||
отказ.
|
||
|
||
## Совместимость данных / миграции
|
||
- **Аддитивность:** только `ADD COLUMN` через `_ensure_column`; существующая боевая ОБЩАЯ БД и
|
||
enduro-trails не затронуты (для них `description` тоже просто рендерится — улучшение, не регресс).
|
||
- **Идемпотентность:** `_ensure_column` — no-op при наличии колонки; повторный `init_db` безопасен
|
||
(TC-05). `_create_initial_docs` на Gitea-`422` — no-op (тело не перезаписывается, TC-06).
|
||
- **Restart-safe / атомарность:** запись `description` — в том же INSERT под `_CREATE_TASK_LOCK`
|
||
(ORCH-053), без окна «задача создана, описание отсутствует»; реклейм/материализация после
|
||
рестарта безопасны.
|
||
- **Down-миграция:** не требуется — revert PR оставляет колонку инертной (без обязательного DROP на
|
||
общей прод-БД).
|
||
- **Влияние на общую прод-БД (self-hosting):** одна аддитивная колонка, без рестарта прода в рамках
|
||
схемы (применяется на следующем `init_db`); без новых сетевых вызовов в горячем `claim_next_job`
|
||
(NFR-4).
|