gitadmin/dzentra_bot

Fork 0

Files

Sergey 64a5bdd04c Build 060.30: finalize Market Data Acquisition documentation

2026-08-04 00:29:56 +03:00

14 KiB

Raw Blame History

Build 060.30 — Market Data Acquisition Final Documentation

Engineering Migration Report

Контроль документа

Свойство	Значение
Build	060.30
Статус	Completed
Подсистема	Market Data / Trades Feed (Time & Sales)
Компонент	Final Documentation and Production Safety
Дата завершения	2026-08-03
Версия	1.0

Связанные документы

Build 060.30 Architecture — границы, ADR и подробное evidence подэтапов 060.30.0–060.30.8;
Текущая архитектура Trades Feed — фактический dependency graph и lifecycle;
Эксплуатация Trade Stream Runtime — settings, startup, recovery, PostgreSQL и verification procedures;
Целевая архитектура Dzentra — место Market Data в целевой системе;
Master Roadmap — фактические статусы и следующий Build;
Build 060.29 Engineering Migration Report — Historical Access and Replay.

1. Назначение Build

Build 060.30 завершил документационный цикл Trades Feed Builds 060.20–060.30. Новое поведение Trade Runtime, Market Data SQL, Storage, Historical Access или Replay в Build не добавлялось.

Результат Build — согласованный набор источников истины:

production code + SQL migrations + tests + settings
        ↓
docs/architecture/trades_feed.md
        ↓
docs/operations/trades_feed_runtime.md
        ↓
overview + target architecture + master roadmap
        ↓
historические architecture и Build reports

Текущая архитектура и operations guide описывают фактическую систему. Исторические Build-документы сохраняют принятые на соответствующем этапе решения и test evidence без широкого переписывания задним числом.

2. Завершённые подэтапы

Подэтап	Название	Статус
060.30.0	Documentation Baseline	Accepted
060.30.1	As-Built Trades Feed Architecture	Accepted
060.30.2	Production Operations Guide	Accepted
060.30.3	Project Entry Documentation	Accepted
060.30.4	Target Architecture Alignment	Accepted
060.30.5	Navigation and Historical Normalization	Accepted
060.30.6	Documentation Integrity Gate	Accepted
060.30.7	Final Documentation Verification	Accepted
060.30.8	Closure	Accepted

Перед 060.30.3 отдельно реализован и принят corrective gate Docker Production Safety Hardening по ADR-060.30-008. Каждый основной подэтап и corrective gate проходили отдельный read-only review. Воспроизведённые findings исправлялись до принятия.

3. Зафиксированная архитектура Trades Feed

3.1. Production vertical slice

Production Runtime завершён только для Trades и поддерживает два режима включённого Trade Stream. При TRADE_STREAM_ENABLED=true и MARKET_DATA_STORAGE_ENABLED=true действует полная durable-цепочка:

Dzengi WebSocket / REST Recovery
        ↓
Trade validation + Consistency
        ↓
atomic PostgreSQL Trade + checkpoint
        ↓
in-memory state advance
        ↓
Runtime Event publication

Live и Recovery в обоих режимах используют один Consistency owner. В durable-режиме Canonical Trade и persistent checkpoint фиксируются одной транзакцией; in-memory state продвигается только после успешного commit.

При включённом Storage Startup выполняет Hydration до первого сетевого I/O, получает subscription ACK, держит Live gate закрытым во время Startup REST Recovery и разбирает buffered Live FIFO только после восстановления. Без Storage первоначальный startup подписывается без persistent Hydration, ожидания startup ACK и Startup REST Recovery; Live, in-memory Consistency и reconnect Recovery остаются доступными без restart persistence.

3.2. Storage, Checkpoint, Access и Replay

Границы подсистем разделены:

Storage владеет долговременной записью Canonical Market Data;
persistent checkpoint хранит подтверждённую позицию Trade Stream;
Historical Access только читает сохранённые данные;
Replay строит bounded immutable plan и запускается явным caller;
Retention и partition maintenance не запускаются автоматически.

Historical Access и Replay не являются частью automatic Bootstrap, не записывают воспроизводимые события обратно и не продвигают operational checkpoint.

3.3. Quotes и Candles

Quotes и Candle revisions имеют Canonical models, PostgreSQL repositories, Historical Access и Replay contracts. Они не подключены как Production Runtime consumers и не являются завершёнными production feeds.

4. Production Operations Guide

Создан единый runbook, который согласован с config.py, .env.example, Compose, Dockerfiles и test harness:

host и Compose startup;
feature flags и явные URL/symbols;
PostgreSQL pool, migrations и lifecycle;
startup recovery, reconnect и graceful shutdown;
file-backed secrets и запрет repository .env для production;
backup, restore и blocking migration 9;
Retention, Historical Access и Replay procedures;
unit, integration, stress и opt-in live verification;
диагностика типовых startup и database failures.

Migration 9 остаётся блокирующей. Перед применением к большой базе обязательны backup, benchmark на сопоставимом объёме и maintenance window. Online staged migration не реализована.

5. Docker Production Safety Hardening

ADR-060.30-008 устранил обнаруженный pre-production blocker: прежний Docker context мог включить app/.env в image layer.

Принятые меры:

корневой .dockerignore ограничивает build context;
Dockerfile копирует только production requirements и app/src;
production dependencies закреплены hash-lock;
bot работает как non-root с read-only root filesystem;
capabilities удалены, включён no-new-privileges;
secrets передаются через явные file-backed contracts;
Compose требует явный project namespace и закрывает PostgreSQL port;
PostgreSQL bootstrap-admin отделён от application-role;
healthcheck отклоняет privileged или неправильно настроенную role;
shutdown использует явные budgets и ожидает blocking lifecycle work.

Images, собранные до появления проверенного .dockerignore, считаются потенциально скомпрометированными и не должны публиковаться. Удаление старых images и rotation реальных credentials требуют отдельного операционного разрешения.

6. PostgreSQL version policy

Единственный поддерживаемый production deployment baseline:

PostgreSQL 16.14 hardened image, закреплённый tag + digest

Изолированная verification matrix подтвердила application compatibility с PostgreSQL 17.10 для migrations 1–9, repositories, checkpoint, Historical Access, Replay, Trade Runtime integration и restart.

Этот результат не принимает hardened PostgreSQL 17 image, Compose cutover или upgrade существующего volume. Production-переход на PostgreSQL 17 требует отдельного infrastructure gate. Major version нельзя переключать на существующем data volume без проверенной процедуры pg_dump/restore либо pg_upgrade.

7. Documentation Integrity Gate

Добавлен локальный offline gate:

scripts/check_documentation_integrity.py
app/tests/static/test_documentation_integrity_gate.py

Gate проверяет обязательные документы, относительные Markdown-ссылки, выход path за repository root, URI safety и переносимость path rules. Он не обращается к сети и входит в default offline regression и Pyright scope.

Историческая навигация нормализована без изменения старых test counts и принятых решений. Stage roadmaps явно обозначены как архивные и больше не определяют следующий Build.

8. Финальная verification matrix

060.30.7 и Closure подтвердили:

Documentation integrity gate:              366 documents, 259 links, 0 issues
Полный static-набор:                        332 passed
Pyright:                                    0 errors, 0 warnings
Dependency integrity:                       pip check clean
Compileall во временном cache:              618 files, clean
Полная offline-регрессия:                   3054 passed, 95 deselected
Target config/Docker tests:                 73 passed
Compose base + exchange-auth config:        clean
Shell syntax затронутых scripts:            clean
PostgreSQL application compatibility:       17.10 / 170010
PostgreSQL official image digest:            sha256:8189a1f6e40904781fc9e2612687877791d21679866db58b1de996b31fc312e4
Application-role dangerous flags:           5/5 disabled
Полный PostgreSQL 17 integration:            90 passed
Критические PG17 race/restart repeats:       10 x 6 = 60 passed
Durable restart probe:                       preserved
Test-only PostgreSQL 17 resources:           removed
PostgreSQL 16.14 deployment baseline:        unchanged
Git diff --check:                            clean
Text hygiene tracked/untracked:              61 Build files, clean
Staging candidates:                          61 paths, .gitignore excluded
Git index:                                   empty
Три независимых финальных review:            clean

Test-only PG17 container, network, volume, derived image и временные password-файлы удалены. Существующие Docker resources не изменялись. Stress/soak и Dzengi live в 060.30.7 повторно не запускались: Runtime behavior Build 060.30 не менял, а соответствующее acceptance evidence зафиксировано в Build 060.26.

9. Границы завершённого Build

Build 060.30 не реализует:

новую Market Data feed;
Production Runtime consumers для Quotes или Candles;
initial historical backfill и completeness metadata;
automatic Retention Scheduler;
Replay Bootstrap или automatic startup;
Backtesting, Analytics API или exchange simulator;
online replacement migration 9;
PostgreSQL 17 production deployment;
Production deployment, backup automation или monitoring program.

Доступная история начинается с наиболее ранней Canonical записи, которая фактически находится в PostgreSQL. Обычно это момент успешного включения Storage, но история может включать ранее импортированные durable rows. Нижняя граница сдвигается только после явно применённой Retention Policy. Документация не обещает полную биржевую историю за более ранний период.

Пользовательское изменение .gitignore не относится к Build 060.30 и не должно входить в staging.

10. Git и выпуск

Closure подготавливает точный список файлов Build без .gitignore, но не выполняет git add, commit или push.

Локальный main до фиксации 060.30 опережает remote на 58 commits. После отдельного commit Build 060.30 требуется отдельный read-only аудит этих 58 прежних commits и нового commit, затем согласованное исправление истории Build 045/046 и повторная проверка итоговой цепочки. Push разрешается только отдельным поручением после этого аудита.

11. Итог

Build 060.30 завершён и принят.

Trades Feed получил согласованную текущую архитектуру, единый production runbook, безопасный Docker baseline, offline documentation gate и финальное verification evidence. Документационный цикл Builds 060.20–060.30 закрыт без скрытого изменения Market Data Runtime или SQL.

Следующий Build — 061.00 Validation and Canonicalization Boundary Refactoring. Он начинается с отдельного read-only анализа фактического ownership validation, parsing, normalization, mapping, consistency и data-quality границ.

14 KiB Raw Blame History Unescape Escape