guard/docs/README.md
loki5512344 280284667f
docs: per-task roadmap, architecture and changelog
- Split TODO into a thin status index plus docs/roadmap/ with one file per
  task (v0.4 reliability, v0.5 product, v0.6 research, icebox).
- Add docs/architecture.md (current processes, packet/data path, layers,
  storage, metrics) and docs/development.md (rules, gates, DoD).
- Add CHANGELOG.md reconstructed from history; move round details out of
  TODO.
- Align docs with the code: config defaults and missing [detect]/
  [protocol.http] sections, XDP metric names, ClickHouse table and TTL,
  Redis RDB restore, multiarch clang include, CLI binary name.
- Add scripts/check_docs_links.sh and run it in CI.
- release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB,
  http parser bench 314 ns -> 278 ns; panic=abort stays off for
  catch_unwind in the Redis subscriber.
- Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
2026-11-16 14:51:50 +01:00

90 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Документация Rampart
> Индекс всей документации проекта и правила её ведения.
> Точка входа — [README.md](../README.md); текущий статус — [TODO.md](../TODO.md);
> история — [CHANGELOG.md](../CHANGELOG.md).
---
## 1. С чего начать
| Документ | Когда читать |
|----------|--------------|
| [architecture.md](architecture.md) | Понять устройство: процессы, путь трафика, слои, хранилища, метрики |
| [deployment.md](deployment.md) | Первый деплой edge-ноды и manager'а |
| [configuration.md](configuration.md) | Все поля `config.toml` и переменные окружения Manager |
| [development.md](development.md) | Правила кода, тестов, гейты и Definition of Done |
## 2. Эксплуатация (how-to)
| Документ | О чём |
|----------|-------|
| [runbook.md](runbook.md) | Метрики, рестарты, снятие банов, аварийные процедуры |
| [troubleshooting.md](troubleshooting.md) | Диагностика типовых проблем |
| [disaster_recovery.md](disaster_recovery.md) | Восстановление после отказа Redis/ноды |
| [testing.md](testing.md) | Гейты, тесты, XDP-smoke на реальном ядре |
## 3. Справочник (reference)
| Документ | О чём |
|----------|-------|
| [configuration.md](configuration.md) | Все поля конфига, границы и значения по умолчанию |
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты, лимиты |
| [vds_compatibility.md](vds_compatibility.md) | Ограничения окружений и ядер |
## 4. Планы и процесс
| Документ | О чём |
|----------|-------|
| [roadmap/README.md](roadmap/README.md) | Индекс задач по версиям, статусы, правила ведения |
| [roadmap/](roadmap/) | По одному файлу на задачу (v0.4, v0.5, v0.6, icebox) |
| [development.md](development.md) | KISS/DRY/SOLID, лимиты файлов, гейты, anti-patterns |
| [../TODO.md](../TODO.md) | Только текущий статус и ссылки на планы |
| [../CHANGELOG.md](../CHANGELOG.md) | Что и когда изменилось |
## 5. Протоколы
| Документ | О чём |
|----------|-------|
| [minecraft-java.md](minecraft-java.md) | Minecraft-edge: Paper, PROXY protocol, закрытый backend |
## 6. Теория и исследования
| Раздел | О чём |
|--------|-------|
| [kb/](kb/README.md) | База знаний: анатомия атак, уровни защиты, практика (двуязычная) |
| [research/](research/README.md) | Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты |
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на
вопрос «какое решение выбрать и почему». Статус проекта не живёт ни там, ни там —
только в [TODO.md](../TODO.md) и [roadmap/](roadmap/README.md).
---
## 7. Как вести документацию
1. **Язык.** `docs/` — русский. Исключение: [docs/kb/](kb/README.md), где статьи
двуязычные (`## English` / `## Русский`). Комментарии в коде — английский
([development.md](development.md) §5).
2. **Один документ = одна задача.** How-to начинается с цели («что получится в
конце»), содержит копируемые команды и заканчивается проверкой результата.
3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг
CLI или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение =
баг.
4. **Планы не растут в TODO.** Новая задача — новый файл в
[roadmap/](roadmap/README.md); в `TODO.md` добавляется только строка-ссылка.
5. **Новый документ** кладётся в подходящую категорию (1–6) и сразу добавляется в
эту таблицу; если он является точкой входа — ссылка добавляется и в корневой
README.
6. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна
только для серии документов (`kb/`, `research/`, `roadmap/`).
7. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри
документа.
8. **Никаких битых ссылок.** Перед коммитом: `bash scripts/check_docs_links.sh`
(этот же скрипт работает в CI).
9. **Не дублируй архитектуру.** Схемы и описания слоёв живут в
[architecture.md](architecture.md); остальные документы ссылаются на него.
---
*Версия: 3.0 | Ноябрь 2026*