Update README and CLAUDE docs for current Redfish workflow
This commit is contained in:
Mikhail Chusavitin
199
CLAUDE.md
199
CLAUDE.md
@@ -1,130 +1,95 @@
|
||||
# LOGPile - Инструкции для Claude Code
|
||||
# LOGPile - Engineering Notes (for Claude/Codex)
|
||||
|
||||
## Что это за проект
|
||||
## Project summary
|
||||
|
||||
LOGPile - standalone Go-приложение для анализа BMC/IPMI диагностических архивов с веб-интерфейсом.
|
||||
Приложение запускает локальный HTTP-сервер, парсит архив, автоматически выбирает подходящий parser по vendor и показывает результат в UI + экспортирует данные.
|
||||
LOGPile is a standalone Go app for BMC diagnostics analysis with embedded web UI.
|
||||
|
||||
## Актуальная архитектура
|
||||
Current product modes:
|
||||
1. Upload and parse vendor archives / JSON snapshots.
|
||||
2. Collect live data via Redfish and analyze/export it.
|
||||
|
||||
- Язык: Go 1.22+
|
||||
- HTTP: стандартный `net/http` + `http.ServeMux`
|
||||
- UI: embedded (`//go:embed`) HTML/CSS/Vanilla JS
|
||||
- Бинарник: один executable, без внешних зависимостей на runtime
|
||||
- Порт по умолчанию: `8082` (а не 8080)
|
||||
## Runtime architecture
|
||||
|
||||
## Реальная структура репозитория
|
||||
- Go + `net/http` (`http.ServeMux`)
|
||||
- Embedded UI (`web/embed.go`, `//go:embed templates static`)
|
||||
- In-memory state (`Server.result`, `Server.detectedVendor`)
|
||||
- Job manager for live collect status/logs
|
||||
|
||||
```
|
||||
logpile/
|
||||
├── cmd/logpile/main.go
|
||||
├── internal/
|
||||
│ ├── analyzer/
|
||||
│ ├── exporter/
|
||||
│ ├── models/
|
||||
│ ├── parser/
|
||||
│ │ └── vendors/
|
||||
│ │ ├── generic/
|
||||
│ │ ├── inspur/
|
||||
│ │ ├── nvidia/
|
||||
│ │ ├── nvidia_bug_report/
|
||||
│ │ └── supermicro/
|
||||
│ └── server/
|
||||
├── web/
|
||||
│ ├── static/
|
||||
│ └── templates/
|
||||
├── Makefile
|
||||
└── go.mod
|
||||
```
|
||||
Default port: `8082`.
|
||||
|
||||
## CLI и запуск (актуально)
|
||||
## Key flows
|
||||
|
||||
### Upload flow (`POST /api/upload`)
|
||||
- Accepts multipart file field `archive`.
|
||||
- If file looks like JSON, parsed as `models.AnalysisResult` snapshot.
|
||||
- Otherwise passed to archive parser (`parser.NewBMCParser().ParseFromReader(...)`).
|
||||
- Result stored in memory and exposed by API/UI.
|
||||
|
||||
### Live flow (`POST /api/collect`)
|
||||
- Validates request (`host/protocol/port/username/auth_type/tls_mode`).
|
||||
- Runs collector asynchronously with progress callback.
|
||||
- On success:
|
||||
- source metadata set (`source_type=api`, protocol/host/date),
|
||||
- result becomes current in-memory dataset.
|
||||
- On failed/canceled previous dataset stays unchanged.
|
||||
|
||||
## Collectors
|
||||
|
||||
Registry: `internal/collector/registry.go`
|
||||
|
||||
- `redfish` (real collector):
|
||||
- dynamic discovery of Systems/Chassis/Managers,
|
||||
- CPU/RAM/Storage/GPU/PSU/NIC/PCIe/Firmware mapping,
|
||||
- raw Redfish snapshot (`result.RawPayloads["redfish_tree"]`) for offline future analysis,
|
||||
- progress logs include active collection stage and snapshot progress.
|
||||
- `ipmi` is currently a mock collector scaffold.
|
||||
|
||||
## Export behavior
|
||||
|
||||
Endpoints:
|
||||
- `/api/export/csv`
|
||||
- `/api/export/json`
|
||||
- `/api/export/txt`
|
||||
|
||||
Filename pattern for all exports:
|
||||
`YYYY-MM-DD (SERVER MODEL) - SERVER SN.<ext>`
|
||||
|
||||
Notes:
|
||||
- JSON export contains full `AnalysisResult`, including `raw_payloads`.
|
||||
- TXT export is tabular and mirrors UI sections (no raw JSON section).
|
||||
|
||||
## CLI flags (`cmd/logpile/main.go`)
|
||||
|
||||
- `--port`
|
||||
- `--file` (reserved/preload, not active workflow)
|
||||
- `--version`
|
||||
- `--no-browser`
|
||||
- `--hold-on-crash` (default true on Windows) — keeps console open on fatal crash for debugging.
|
||||
|
||||
## Build / release
|
||||
|
||||
- `make build` -> single local binary (`CGO_ENABLED=0`).
|
||||
- `make build-all` -> cross-platform binaries.
|
||||
- Tags/releases are published with `tea`.
|
||||
- Release notes live in `docs/releases/<tag>.md`.
|
||||
|
||||
## Testing expectations
|
||||
|
||||
Before merge:
|
||||
|
||||
```bash
|
||||
# Сборка
|
||||
make build
|
||||
|
||||
# Запуск (авто-открытие браузера включено)
|
||||
./bin/logpile
|
||||
|
||||
# Явный порт
|
||||
./bin/logpile --port 8082
|
||||
|
||||
# Не открывать браузер автоматически
|
||||
./bin/logpile --no-browser
|
||||
|
||||
# Версия
|
||||
./bin/logpile --version
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Важно: сейчас **нет** subcommand `serve`, запуск идёт напрямую через флаги.
|
||||
If touching collectors/handlers, prefer adding or updating tests in:
|
||||
- `internal/collector/*_test.go`
|
||||
- `internal/server/*_test.go`
|
||||
|
||||
## Основной runtime-flow
|
||||
## Practical coding guidance
|
||||
|
||||
1. `main.go` регистрирует embedded web FS и запускает сервер.
|
||||
2. `POST /api/upload` принимает архив и передаёт его в `parser.BMCParser`.
|
||||
3. `DetectFormat()` выбирает parser с максимальным confidence.
|
||||
4. Результат сохраняется в памяти (`Server.result`) и отдаётся через API.
|
||||
5. `POST /api/collect` запускает in-memory mock lifecycle live-сбора (`queued -> running -> success|failed`, поддерживается `cancel`).
|
||||
6. Для live-flow `AnalysisResult` обновляется только на `success` (при `failed/canceled` остаётся предыдущий результат).
|
||||
7. UI строит вкладки: конфигурация, прошивки, сенсоры, серийники, события.
|
||||
|
||||
## Поддерживаемые parser modules
|
||||
|
||||
- `supermicro` - Supermicro parser
|
||||
- `inspur` - Inspur/Kaytus parser
|
||||
- `nvidia` - NVIDIA Field Diagnostics parser
|
||||
- `nvidia_bug_report` - parser для `nvidia-bug-report.sh`
|
||||
- `generic` - fallback parser
|
||||
|
||||
Реестр parser-ов: `internal/parser/registry.go`, подключение модулей: `internal/parser/vendors/vendors.go`.
|
||||
|
||||
## API (фактически в коде)
|
||||
|
||||
```
|
||||
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/txt
|
||||
DELETE /api/clear
|
||||
POST /api/shutdown
|
||||
```
|
||||
|
||||
## Форматы данных и экспорт
|
||||
|
||||
- `AnalysisResult` агрегирует: events, sensors, FRU, hardware.
|
||||
- Экспорт реализован в `internal/exporter/exporter.go`:
|
||||
- CSV: серийные номера компонентов
|
||||
- JSON: полный `AnalysisResult`
|
||||
- TXT: человекочитаемый отчёт
|
||||
|
||||
## Важные текущие ограничения (чтобы не ошибаться в задачах)
|
||||
|
||||
- Upload через `/api/upload` использует `ParseFromReader()`, где сейчас поддержаны `.tar`, `.tar.gz`, `.tgz`.
|
||||
- Код распаковки `.zip` есть, но в текущем upload-пути `zip` не обрабатывается.
|
||||
- Флаг `--file` присутствует в CLI-конфиге, но preload в `Server.Run()` сейчас не выполняется.
|
||||
- Данные хранятся только в памяти процесса; перезапуск очищает состояние.
|
||||
- Live-сбор пока mock-only (реальные Redfish/IPMI коннекторы ещё не подключены).
|
||||
|
||||
## Практические рекомендации для доработок
|
||||
|
||||
- Если меняется parser-логика, обновляй `Version()` соответствующего parser-модуля.
|
||||
- Новые vendor-парсеры регистрируй через import в `internal/parser/vendors/vendors.go`.
|
||||
- Для API/контрактов проверяй согласованность `handlers.go` и `web/static/js/app.js`.
|
||||
- Для UI-изменений не забывай, что ассеты embedded через `web/embed.go`.
|
||||
|
||||
## Приоритетные следующие шаги
|
||||
|
||||
1. Довести поддержку `zip` в upload path (`ParseFromReader`).
|
||||
2. Реализовать preload из `--file`.
|
||||
3. Добавить/актуализировать автотесты для parser и HTTP handlers.
|
||||
4. Расширить vendor coverage (Dell/HPE/Lenovo) по реальным дампам.
|
||||
- Keep API contracts stable with frontend (`web/static/js/app.js`).
|
||||
- When adding Redfish mappings, prefer tolerant/fallback parsing:
|
||||
- alternate collection paths,
|
||||
- `@odata.id` references and embedded members,
|
||||
- deduping by serial/BDF/slot+model.
|
||||
- Avoid breaking snapshot backward compatibility (`AnalysisResult` JSON shape).
|
||||
|
||||
Reference in New Issue
Block a user