Andrey Epifancev adab949783 docs: доска связей хаба — README, ARCHITECTURE, CLAUDE.md (#17 )

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-14 18:13:20 +04:00

5.3 KiB

Raw Blame History

Архитектура

Хаб моста Jira: SQLite-зеркало задач AURORA/AWPCA, служебные заметки, очередь команд, HTTP API и MCP. Агент (jira-agent, виртуалка) опрашивает хаб, пишет в Jira и возвращает состояние; хаб Jira не вызывает.

Модули

Модуль	Ответственность	Зависит от
`paths`	каталог данных (`JIRA_HUB_HOME`), пути базы и `backups/`, права 0700 (`secure_dir`)	stdlib
`db`	схема SQLite, миграции по `schema_version` (копия базы перед миграцией), `connect`	`backup`, `paths`
`settings`	настройки (`setting`), токены, темп, перенос из `config.example.json`	`db`
`mirror`	зеркало задач и связей, `apply_state`, заметки, фильтры, снимок доски `board`	`db`
`commands`	контракт типов команд, валидация, временные ключи, оценка, подтверждение по состоянию	`mirror`
`queue`	пакеты, выдача (`claim`), отчёты, отмена, повтор, автообновление	`commands`, `mirror`, `settings`, `db`
`backup`	копии файла базы, ротация	`paths`
`api`	HTTP-сервер, маршруты, авторизация по токенам, фоновый `tick`; страница доски GET /, /links (файл web/links.html, без токена) и снимок GET /board	`queue`, `mirror`, `settings`, `backup`, `relay`
`relay`	реле общей папки (настройка `relay_dir`): поток в `serve`, файлы `req/` → свой HTTP (адрес `serve`, для `0.0.0.0` — `127.0.0.1`) → `resp/`; агент с `hub_url = folder:<путь>` ходит через него; HTTP-обработчики о нём не знают	`settings`
`client`	HTTP-клиент хаба	`db`, `paths`, `settings` (только для `from_home`)
`mcp_server`	инструменты MCP по stdio	`client`
`importer`	разовый импорт CSV-пакета в заметки, сверка с зеркалом	`mirror`, `settings`
`cli`	`init`, `serve`, `import`, `mcp`, `tokens`	`api`, `mcp_server`, `importer`, `settings`, `db`, `paths`

src/jira_hub/web/links.html — страница доски связей: один HTML без зависимостей, хаб отдаёт его как есть. Данные страница берёт из GET /board с клиентским токеном и переводит в модель доски сама (вид работы по меткам, имена эпиков, логические типы связей); mirror.board отдаёт зеркало без преобразований — тот же формат будет читать веб-приложение.

Цепочки: api → queue → commands/mirror/settings → db; db → backup → paths, db → paths; api → relay → settings; mcp_server → client → HTTP API; importer → mirror/settings.

Потоки данных

Запись в Jira: клиент (mcp_server/интерфейс) → POST /batches → queue → агент claim → Jira → POST /agent/commands/{id}/result.
Чтение Jira: команда refresh → агент → POST /agent/state → mirror.apply_state.
Агент за VPN: агент → файлы в общей папке (relay_dir) → relay → HTTP хаба → ответ файлом.
Токены: агентский — только /agent/*, клиентский — остальное; MCP берёт клиентский токен из базы через HubClient.from_home.

Границы

Зеркало пишет только mirror.apply_state по запросу агента (и заметки через PUT /issues/{key}/note); из очереди и API задач напрямую не правят.
Хаб не знает пароль Jira и не обращается к Jira; init не переносит auth, base_url, verify_ssl, ca_bundle.
queue не создаёт команд сам: повтор после failed — новый пакет. Выданная без отчёта команда довыдаётся при следующем claim (до 3 выдач, затем failed).
mcp_server не импортирует queue/mirror/db напрямую и ходит только через client.
commands, mirror, queue не знают про HTTP; HTTP живёт только в api, client и relay (реле — клиент своего же HTTP).

Открытые вопросы

Просмотрщик на живых данных и правки из UI — отдельные change'и (viewer-live, viewer-edit).
Автоподстройка темпа по фактам 429 не реализована: хаб только показывает их.
Незакрытые SQLite-соединения и сокеты в ряде тестов (ResourceWarning при -W error::ResourceWarning).