314 lines
14 KiB
Markdown
314 lines
14 KiB
Markdown
# 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](build_060_30_architecture.md) — границы,
|
||
ADR и подробное evidence подэтапов 060.30.0–060.30.8;
|
||
- [Текущая архитектура Trades Feed](../architecture/trades_feed.md) —
|
||
фактический dependency graph и lifecycle;
|
||
- [Эксплуатация Trade Stream Runtime](../operations/trades_feed_runtime.md) —
|
||
settings, startup, recovery, PostgreSQL и verification procedures;
|
||
- [Целевая архитектура Dzentra](../architecture/dzentra_target_architecture.md) —
|
||
место Market Data в целевой системе;
|
||
- [Master Roadmap](../roadmap/master-roadmap.md) — фактические статусы и
|
||
следующий Build;
|
||
- [Build 060.29 Engineering Migration Report](build_060_29.md) —
|
||
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 — согласованный набор источников истины:
|
||
|
||
```text
|
||
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-цепочка:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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 подтвердили:
|
||
|
||
```text
|
||
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 границ.
|