docs: introduce project Bible and consolidate all architecture documentation

- Create docs/bible/ with 10 structured chapters (overview, architecture, API, data models, collectors, parsers, exporters, build, testing, decisions) - All documentation in English per ADL-007 - Record all existing architectural decisions in docs/bible/10-decisions.md - Slim README.md to user-facing quick start only - Replace CLAUDE.md with a single directive to read and follow the Bible - Remove absorbed files: REANIMATOR_EXPORT.md, docs/INTEGRATION_GUIDE.md, and all vendor parser README.md files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-20 14:15:35 +03:00
parent 82ee513835
commit fcd57c1ba9
21 changed files with 1289 additions and 2391 deletions
--- a/README.md
+++ b/README.md
@@ -4,102 +4,16 @@ LOGPile — standalone Go-приложение для анализа диагн

 Поддерживает два сценария:
 1. Загрузка архивов/снапшотов и оффлайн-анализ в веб-интерфейсе.
-2. Live-сбор через Redfish API с последующим экспортом и повторной загрузкой оффлайн.
-
-## Что умеет
-
- Standalone бинарник с embedded UI (без внешних статических файлов).
- Парсинг vendor-архивов (Supermicro, Inspur/Kaytus, NVIDIA, fallback generic).
- Live-сбор по Redfish (`/api/collect`) с прогрессом и журналом шагов.
- Расширенный Redfish snapshot:
-  - нормализованные данные (CPU/RAM/Storage/GPU/PSU/NIC/PCIe/Firmware),
-  - сырой `redfish_tree` для будущего анализа.
- Загрузка JSON snapshot обратно через `/api/upload` для оффлайн-работы.
- Экспорт в CSV / JSON.
-
-## Дополнительные источники данных (Inspur/Kaytus)
-
-Для архивов Inspur/Kaytus парсер использует не только `asset.json` и `component.log`,
-но и runtime-снимок `onekeylog/runningdata/redis-dump.rdb` (если файл присутствует).
-
-Что это даёт:
- обогащение GPU: `serial_number`, `firmware` (VBIOS/FW), часть runtime telemetry;
- обогащение NIC: firmware/serial/part-number (когда в текстовых логах поля пустые).
-
-## Внешний PCI IDs (без хардкода моделей)
-
-Источник PCI IDs в проекте: официальный репозиторий
-[`pciutils/pciids`](https://github.com/pciutils/pciids), подключён как git submodule:
-`third_party/pciids`.
-Локальная копия для встроенного lookup хранится в:
-`internal/parser/vendors/pciids/pci.ids`.
-
-Обновление локальной копии:
-
-```bash
-make update-pci-ids
-```
-
-Команда запускает `scripts/update-pci-ids.sh`, который скачивает актуальный
-`pci.ids` из submodule (`git submodule update --init --remote third_party/pciids`)
-и синхронизирует его в `internal/parser/vendors/pciids/pci.ids`.
-
-Автообновление при сборке:
- `make build` и `make build-all` запускают `scripts/update-pci-ids.sh --best-effort`;
- если submodule уже инициализирован, `pci.ids` синхронизируется перед сборкой;
- если submodule не инициализирован/недоступен, используется текущая копия файла,
-  сборка не прерывается.
-
-Отключить автообновление при сборке:
-
-```bash
-SKIP_PCI_IDS_UPDATE=1 make build
-```
-
-Если репозиторий клонирован без submodule:
-
-```bash
-git submodule update --init third_party/pciids
-```
-
-Парсер использует такой порядок lookup:
-1. встроенный в бинарник `internal/parser/vendors/pciids/pci.ids`;
-2. `./pci.ids`;
-3. `/usr/share/hwdata/pci.ids`;
-4. `/usr/share/misc/pci.ids`;
-5. `/opt/homebrew/share/pciids/pci.ids`;
-6. `LOGPILE_PCI_IDS_PATH` (можно передать несколько путей через `:`; имеет наивысший приоритет и переопределяет предыдущие значения).
-
-Пример запуска:
-
-```bash
-LOGPILE_PCI_IDS_PATH=/path/to/pci.ids ./bin/logpile
-```
-
-## Требования
-
- Go 1.22+
+2. Live-сбор через Redfish API с последующим экспортом.

 ## Сборка

 ```bash
-make build
+make build          # bin/logpile (текущая платформа)
+make build-all      # все платформы в bin/
 ```

-Бинарник будет в `bin/logpile`.
-
-Для кросс-сборки:
-
-```bash
-make build-all
-```
-
-Артефакты:
- `bin/logpile-linux-amd64`
- `bin/logpile-linux-arm64`
- `bin/logpile-darwin-amd64`
- `bin/logpile-darwin-arm64`
- `bin/logpile-windows-amd64.exe`
+Требования: Go 1.22+

 ## Запуск

@@ -110,14 +24,14 @@ make build-all
 ./bin/logpile --version
 ```

-Отладка падений (чтобы консоль не закрывалась):
+На Windows `--hold-on-crash` включён по умолчанию (консоль не закрывается при падении).
+
+## macOS: снятие карантина

 ```bash
-./bin/logpile --hold-on-crash
+xattr -d com.apple.quarantine /path/to/logpile-darwin-arm64
 ```

-> На Windows `--hold-on-crash` включён по умолчанию.
-
 ## Форматы загрузки

 `POST /api/upload` принимает:
@@ -126,15 +40,8 @@ make build-all

 ## Live Redfish

-Запуск live-сбора:
-
-```http
+```bash
 POST /api/collect
-```
-
-Пример body:
-
-```json
 {
  "host": "bmc01.example.local",
  "protocol": "redfish",
@@ -146,84 +53,15 @@ POST /api/collect
 }
 ```

-Жизненный цикл задачи:
-`queued -> running -> success|failed|canceled`
-
-Статус и прогресс:
- `GET /api/collect/{id}`
- `POST /api/collect/{id}/cancel`
-
 ## Экспорт

 - `GET /api/export/csv` — серийные номера
- `GET /api/export/json` — полный `AnalysisResult` (включая `raw_payloads`)
- `GET /api/export/reanimator` — экспорт для Reanimator
+- `GET /api/export/json` — полный AnalysisResult
+- `GET /api/export/reanimator` — формат Reanimator

-Имена экспортируемых файлов:
+## Архитектурная документация

-`YYYY-MM-DD (SERVER MODEL) - SERVER SN.<ext>`
-
-Пример:
-`2026-02-04 (SYS-421GE-TNHR2) - C8X123456789.json`
-
-## Canonical inventory (`hardware.devices`)
-
-В проекте используется единый реестр устройств сервера: `hardware.devices`.
-Это source of truth для UI и экспорта Reanimator.
-
-Основные правила:
- вкладки конфигурации читают данные устройств из `hardware.devices`;
- `Device Inventory` строится по типам `pcie`, `storage`, `gpu`, `network`;
- экспорт Reanimator использует тот же canonical-реестр;
- расхождение данных UI и Reanimator считается дефектом.
-
-Дедупликация в canonical-реестре:
-1. по usable `serial_number` (не пустой и не `N/A/NA/NONE/NULL/UNKNOWN/-`);
-2. если serial отсутствует — по `bdf`;
-3. если serial и bdf отсутствуют — записи не схлопываются.
-
-## API
-
-```text
-POST   /api/upload
-POST   /api/collect
-GET    /api/collect/{id}
-POST   /api/collect/{id}/cancel
-GET    /api/status
-GET    /api/parsers
-GET    /api/events
-GET    /api/sensors
-GET    /api/config
-GET    /api/serials
-GET    /api/firmware
-GET    /api/export/csv
-GET    /api/export/json
-GET    /api/export/reanimator
-DELETE /api/clear
-POST   /api/shutdown
-```
-
-Примечания:
- `GET /api/config` возвращает canonical inventory в `hardware.devices`.
- `GET /api/serials` и `GET /api/firmware` строятся из того же canonical inventory.
-
-`/api/status` и `/api/config` содержат метаданные источника:
- `source_type`: `archive` | `api`
- `protocol`: `redfish` | `ipmi` (для архивов может быть пустым)
- `target_host`
- `collected_at`
-
-## Структура
-
-```text
-cmd/logpile/main.go         # entrypoint
-internal/collector/         # live collectors (redfish, ipmi mock)
-internal/parser/            # archive parsers
-internal/server/            # HTTP handlers
-internal/exporter/          # CSV/JSON export
-internal/models/            # data contracts
-web/                        # embedded templates/static
-```
+→ [`docs/bible/`](docs/bible/README.md)

 ## Лицензия