sdlc-hub/openspec/changes/archive/2026-10-25-sprints-backlog/specs/data-model/spec.md

MODIFIED Requirements

Requirement: Схема базы хаба

База хаба SHALL быть одним файлом SQLite (WAL) с таблицами issue, issue_link, issue_comment, issue_change, issue_attachment, attachment_file, issue_note, issue_sprint, jira_board, jira_sprint, batch, command, sync_run, agent_status, setting, project. Схема SHALL создаваться и мигрироваться самим хабом при старте по номеру версии в setting.schema_version (текущая — 9). Миграция существующей базы SHALL выполняться в одной транзакции с блокировкой записи; в той же транзакции, после повторной проверки версии, хаб SHALL скопировать файл базы в backups/<дата-время>-schema-v<старая>.sqlite рядом с базой — одна копия на миграцию, сколько бы соединений ни открывалось одновременно. Каталог данных хаба и backups/ SHALL иметь права 0700 (в базе токены): хаб выставляет их при создании и при каждом старте; если выставить не удалось — предупреждение в лог, работа продолжается. Денежных и дробных полей нет; даты — ISO-8601 строки в UTC, кроме duedate и плановых дат (даты без времени), строк времени Jira как есть (issue_comment.created/updated, issue_change.created, issue_attachment.created) и значений полей журнала.

Миграция v3 → v4 SHALL: создать project и колонку batch.project (у существующих пакетов NULL); разобрать прежнюю настройку base_jql вида … labels = <M> или … labels in (<M1>, …) и завести проекты с этими метками (название проекта AWPCA — «АРМ КА», остальных — метка; board_type = NULL); отдать прежний board_id проекту, если проект один, иначе никому, с предупреждением в лог; у строк sync_run с query, равной прежней base_jql, и у команд refresh в queued/claimed с params.jql, равной прежней base_jql, записать базовую JQL, вычисленную из проектов. Ключи base_jql и board_id в setting миграция MUST NOT удалять: базу может открыть процесс новой версии раньше, чем перезапущен хаб прежней версии, который их читает. Не разобранная base_jql — проектов нет, предупреждение в лог с прежним значением.

Миграция v4 → v5 SHALL: создать issue_change с индексами; добавить колонки issue_comment.created_at и sync_run.history_at; заполнить issue_comment.created_at у имеющихся комментариев приведением created к UTC (не разобралось — NULL). У имеющихся sync_run history_at = NULL.

Миграция v5 → v6 SHALL: создать пустые issue_attachment (с индексом по key) и attachment_file. Списки вложений появляются с первым refresh агента v14.

Миграция v7 → v8 SHALL: удалить колонку issue_note.fact_status (если она есть; значения удаляются безвозвратно, копия — в backups/ по общему правилу) и ключи status_labels и transitions_map из setting, если они есть, и поднять settings_version, если хотя бы один из ключей был удалён. Прочие поля заметок, задачи и настройки миграция MUST NOT менять.

Миграция v8 → v9 SHALL: добавить колонки issue.rank и issue.story_points (у имеющихся задач NULL); таблицы jira_board, jira_sprint, issue_sprint создаются схемой пустыми. Данные появляются с первым refresh агента v15.

Scenario: Первый запуск

• WHEN хаб стартует с несуществующим файлом базы
• THEN файл создаётся, таблицы и индексы на месте, setting.schema_version = текущая; каталог данных с правами 0700

Scenario: Миграция базы v1

• WHEN хаб стартует с базой schema_version = 1, в которой есть задачи, заметки и команда в claimed
• THEN в backups/ копия базы v1; добавлена command.deliveries (у claimed — 1, у остальных — 0); добавлена пустая issue_comment; данные на месте; schema_version = текущая

Scenario: Миграция базы v2

• WHEN хаб стартует с базой schema_version = 2, в которой есть задачи, связи и заметки
• THEN в backups/ копия базы v2; добавлена пустая issue_comment; данные на месте; schema_version = текущая

Scenario: Миграция базы v3

• WHEN хаб стартует с базой schema_version = 3, base_jql = "project = AURORA AND labels = AWPCA", board_id = 4216, в sync_run полный прогон с этой query
• THEN в backups/ копия базы v3; проект AWPCA «АРМ КА» с board_id = 4216, board_type = NULL; ключи base_jql и board_id в setting на месте; query того прогона — project = AURORA AND labels in ("AWPCA"); задачи, заметки, пакеты на месте; schema_version = текущая

Scenario: Миграция базы v4

• WHEN хаб стартует с базой schema_version = 4, у задачи X комментарий с created = "2026-10-22T13:05:11.000+0300", в sync_run полный прогон
• THEN в backups/ копия базы v4; есть пустая issue_change; у комментария created_at = "2026-10-22T10:05:11+00:00", created прежний; у прогона history_at = NULL; затем миграция v5 → v6; schema_version = текущая

Scenario: Миграция базы v5

• WHEN хаб стартует с базой schema_version = 5
• THEN в backups/ копия базы v5; есть пустые issue_attachment и attachment_file; прочие таблицы не тронуты; schema_version = текущая

Scenario: Миграция базы v7

• WHEN хаб стартует с базой schema_version = 7, у задачи X заметка fact_status = "В работе", work_kind = "Аналитика", в setting есть status_labels и transitions_map, settings_version = 12
• THEN в backups/ копия базы v7; в issue_note нет колонки fact_status, у X work_kind = "Аналитика", updated_at прежний; ключей status_labels и transitions_map в setting нет; settings_version = 13; schema_version = текущая

Scenario: Миграция базы v8

• WHEN хаб стартует с базой schema_version = 8, в зеркале задача X со спринтом «Спринт 2»
• THEN в backups/ копия базы v8; у X rank и story_points — NULL, sprint прежний; таблицы jira_board, jira_sprint, issue_sprint пусты; schema_version = 9

Scenario: refresh в очереди при миграции

• WHEN в базе v3 стоит queued refresh {jql: "project = AURORA AND labels = AWPCA"}
• THEN после миграции его params.jql — project = AURORA AND labels in ("AWPCA"), и по завершении он считается полным прогоном

Scenario: Два соединения к базе v1

• WHEN к базе schema_version = 1 одновременно открываются два соединения
• THEN миграция выполнена один раз, в backups/ одна копия schema-v1

Scenario: Открытый каталог данных

• WHEN хаб стартует, каталог данных существует с правами 0755
• THEN права каталога и backups/ — 0700

Requirement: Зеркало задачи

Таблица issue SHALL хранить задачу Jira как есть: key (PK), id, issue_type, summary, description (wiki), status, priority, assignee, reporter, duedate, planned_start, planned_end, epic_key, labels (JSON-список), sprint, rank (ранг Jira строкой как есть или NULL), story_points (оценка, число или NULL), jira_updated, fetched_at, neighbor (0/1 — вне базовой JQL, дочитана по связи), created. Таблица issue_link SHALL хранить связи (source_key, target_key, link_type) с направлением по семантике Jira: source блокирует/ссылается на target (у source в GET это outwardIssue). Таблица issue_comment SHALL хранить комментарии задачи как есть: key, comment_id (PK вместе с key), author, created, updated, body (wiki). Таблица issue_attachment SHALL хранить список вложений задачи без содержимого: attachment_id (PK, id вложения Jira), key, filename, size (байт или NULL), mime_type, author, created (время Jira как есть), created_at (UTC, приведённое из created; не разобралось — NULL). Обновлять issue, issue_link, issue_comment и issue_attachment SHALL только загрузка состояния от агента; HTTP API интерфейсов и MCP MUST NOT писать в них. Присланные комментарии задачи SHALL заменять все её прежние комментарии; задача, присланная без поля comments, свои комментарии SHALL сохранять. Так же со вложениями: присланное поле attachments заменяет все прежние вложения задачи, задача без поля (агент до v14) свои вложения сохраняет. Полный прогон (refresh по базовой JQL), завершившийся done, SHALL помечать neighbor = 1 задачи, не обновлённые им, — только если прогон загрузил хотя бы одну задачу.

Scenario: Загрузка состояния заменяет связи

• WHEN агент прислал состояние задачи X с двумя связями
• THEN все строки issue_link с source_key = X заменены на присланные; строки с target_key = X, не присланные со стороны X, не трогаются до загрузки их источника

Scenario: Соседняя задача

• WHEN в issuelinks задачи из базовой JQL есть ключ Y вне JQL
• THEN Y сохраняется с neighbor = 1; при следующем полном refresh, если Y вошла в JQL, neighbor = 0

Scenario: Пустой полный прогон

• WHEN полный refresh завершился done, загрузив 0 задач
• THEN признак neighbor задач зеркала не меняется

Scenario: Комментарий удалён в Jira

• WHEN у X в зеркале комментарии 101 и 102, агент прислал X с comments = [{id: "102", …}]
• THEN у X в issue_comment только 102

Scenario: Состояние от агента до v10

• WHEN у X в зеркале три комментария, агент v9 прислал X без поля comments
• THEN поля X обновлены, три комментария на месте

Scenario: Вложения в состоянии

• WHEN у X в зеркале вложения #1 и #2, агент v14 прислал X с attachments = [{id: "2", …}, {id: "3", …}]
• THEN у X в issue_attachment #2 (поля из состояния) и #3; #1 удалено; attachment_file не тронута

Scenario: Состояние от агента до v14

• WHEN у X в зеркале два вложения, агент v13 прислал X без поля attachments
• THEN поля X обновлены, два вложения на месте

ADDED Requirements

Requirement: Доски, спринты и членство задач

Модуль jira SHALL хранить данные досок проектов, присланные агентом в refresh (см. hub-api, «Приём досок и спринтов»):

• jira_board: board_id (PK), type (scrum | kanban | NULL), columns (JSON-список [{name, statuses: [имя статуса]}] в порядке доски или NULL), kanban_backlog (1 / 0 / NULL — неизвестно), fetched_at (UTC);
• jira_sprint: sprint_id (PK, id спринта Jira), board_id, name, state (active | future | closed), start_date, end_date, complete_date (строки Jira как есть или NULL), goal;
• issue_sprint: key, sprint_id (PK — пара) — все спринты задачи любого состояния. Писать их SHALL только загрузка состояния от агента. Выполненной на доске SHALL считаться задача, чей status входит в statuses последней колонки доски; колонок нет (NULL) — выполненных нет.

Scenario: Задача прошла два спринта

• WHEN агент прислал задачу X с sprint_ids: [101, 102], спринт 101 закрыт, 102 активен
• THEN у X две строки issue_sprint; X в составе закрытого спринта 101 и активного 102

Scenario: Колонки доски

• WHEN у доски 4216 колонки «К выполнению» [Backlog, Ожидает анализа], «В работе» […], «Готово» [Готово, Протестировано, Снято]
• THEN задача в статусе Протестировано выполнена, в статусе Backlog — нет