Build 060.30: finalize Market Data Acquisition documentation
This commit is contained in:
313
docs/migrations/build_060_30.md
Normal file
313
docs/migrations/build_060_30.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# 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 границ.
|
||||
Reference in New Issue
Block a user