279 строк · 21 КиБ
docs/PROBLEM-REPORT-CONTRACT.md
| 1 | # Контракт отчёта о проблеме |
| 2 | |
| 3 | Что Chimera-Launcher отправляет, когда человек нажимает «Диагностика» → |
| 4 | «Отправить отчёт» (или запускает `chl report <вид> --send`), и на что |
| 5 | принимающая сторона имеет право рассчитывать. |
| 6 | |
| 7 | Документ адресован **тому, кто пишет серверную часть** — приём отчёта и |
| 8 | разбор его в работу OpenProject. Клиентская половина уже реализована |
| 9 | (`code/crates/chl-report`), серверной на момент написания **нет**: маршрут |
| 10 | `POST /problem-reports` ещё никем не обслуживается, и отправка сейчас |
| 11 | предсказуемо кончается ошибкой. Это ожидаемо и безопасно — см. |
| 12 | «Доставка» ниже. |
| 13 | |
| 14 | Реализация формата — `chl_report::Payload`. Расхождение между этим |
| 15 | документом и типом решается **в пользу типа**: он отправляется, документ |
| 16 | нет. |
| 17 | |
| 18 | --- |
| 19 | |
| 20 | ## Транспорт |
| 21 | |
| 22 | ``` |
| 23 | POST https://compat.project-chimera.ru/problem-reports/anonymous |
| 24 | Content-Type: application/json |
| 25 | ``` |
| 26 | |
| 27 | - Пользовательский токен не нужен. Токен OpenProject хранится только на |
| 28 | сервере. Запись публичных профилей совместимости остаётся защищённой |
| 29 | прежним токеном; анонимная отправка не меняет настройки других игроков. |
| 30 | - Путь **не** под `/games/<игра>/`, в отличие от отчётов |
| 31 | совместимости. Отчёт о проблеме бывает и не про игру вовсе (вид |
| 32 | `launcher`), а игра в нём — поле, а не часть адреса. |
| 33 | - Ответ: `201` и `{report_id, openproject_id, status: "created"}`, если |
| 34 | задача создана; `202` и `{report_id, openproject_id: null, status: "queued"}`, |
| 35 | если отчёт сохранён и сервер ждёт OpenProject. Клиент проверяет подтверждение. |
| 36 | - Клиент не отправляет отчёты автоматически. Отправка |
| 37 | происходит только по нажатию человека, и отправка без человека была бы |
| 38 | прямым нарушением того, что написано в `PRIVACY.md`. |
| 39 | - Сервер повторяет доставку уже принятого отчёта после сбоя. Повтор того |
| 40 | же JSON возвращает тот же номер; повторная доставка не создаёт второй |
| 41 | тикет. Старый `/problem-reports` с Bearer остаётся совместимым. |
| 42 | - Публичный приём ограничен 60 новыми отчётами в час и 300 в день, |
| 43 | тело HTTP — до 1 МиБ. Отказы `429`/`413` не удаляют локальный файл. |
| 44 | |
| 45 | ### Что уже гарантирует клиент |
| 46 | |
| 47 | - Текст разделов ограничен **512 КиБ** (`chl_report::MAX_PAYLOAD_BYTES`), одно |
| 48 | значение — не больше **32 КиБ** (`MAX_VALUE_BYTES`). Обрезанные значения |
| 49 | кончаются на `…[обрезано]`, и тогда `truncated: true`. Пользовательская |
| 50 | заметка ограничена 16 КиБ вместе с пометкой об обрезке; размер JSON включает |
| 51 | экранирование и метаданные. |
| 52 | - Кодировка UTF-8. Текст на русском, идентификаторы на ASCII. |
| 53 | - Отчёт **уже вычищен** (см. «Чистка»): полных домашних путей, логина, |
| 54 | имени машины и токенов в нём быть не должно. Это не повод не проверять |
| 55 | на своей стороне, но повод не строить очистку заново. |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ## Тело |
| 60 | |
| 61 | ```json |
| 62 | { |
| 63 | "schema": "chimera-launcher.problem-report", |
| 64 | "version": 1, |
| 65 | "launcher_version": "0.1.0", |
| 66 | "created_unix": 1788800000, |
| 67 | "kind": "black-screen", |
| 68 | "kind_title": "Чёрный экран, картинки нет", |
| 69 | "game": "AER Memories of Old", |
| 70 | "summary": ["абзац", "абзац"], |
| 71 | "note": "", |
| 72 | "sections": [ |
| 73 | { |
| 74 | "id": "wine", |
| 75 | "title": "Wine и префикс", |
| 76 | "why": "зачем этот раздел собран под этот симптом", |
| 77 | "items": [{ "label": "Сборка Wine", "value": "GE-Proton10-34" }] |
| 78 | } |
| 79 | ], |
| 80 | "redacted": [ |
| 81 | { "rule": "домашний каталог заменён на ~", "replacement": "~", "count": 12 } |
| 82 | ], |
| 83 | "truncated": false |
| 84 | } |
| 85 | ``` |
| 86 | |
| 87 | ### Поля верхнего уровня |
| 88 | |
| 89 | | Поле | Тип | Обязательно | Что это | |
| 90 | |---|---|---|---| |
| 91 | | `schema` | string | да | Всегда `chimera-launcher.problem-report`. Отличать отчёт от отчёта совместимости надо по этому полю, а не по маршруту. | |
| 92 | | `version` | integer | да | Версия формата, сейчас `1`. Правила совместимости ниже. | |
| 93 | | `launcher_version` | string | да | Версия лаунчера, собравшего отчёт (`CARGO_PKG_VERSION`). | |
| 94 | | `created_unix` | integer | да | Когда собран, секунды эпохи Unix, UTC. Не когда отправлен: отчёт мог сутки лежать файлом. | |
| 95 | | `kind` | string | да | Вид проблемы, ASCII, закрытый список — таблица ниже. | |
| 96 | | `kind_title` | string | да | Он же по-русски. Дублируется намеренно: принимающей стороне не нужно держать копию перевода, а формулировки на клиенте будут улучшаться. | |
| 97 | | `game` | string | **нет** | Название игры как в библиотеке. Отсутствует ровно у `kind: "launcher"`. | |
| 98 | | `summary` | array of string | да | Описание, **составленное лаунчером**, по абзацу на элемент. Это то, что читают первым. Никогда не пусто. | |
| 99 | | `note` | string | нет | Свободная заметка человека. Пусто — обычный случай, а не пропуск: описание пишет лаунчер, заметка добавляется поверх. | |
| 100 | | `sections` | array of Section | да | Доказательства. Порядок значимый: от главного к второстепенному. | |
| 101 | | `redacted` | array of Redacted | да | Что вычистила чистка. Пустой массив — законное значение («чистить было нечего»). | |
| 102 | | `truncated` | boolean | да | Пришлось ли обрезать отчёт по размеру. | |
| 103 | |
| 104 | ### Section |
| 105 | |
| 106 | | Поле | Тип | Обязательно | Что это | |
| 107 | |---|---|---|---| |
| 108 | | `id` | string | да | Стабильный ASCII-идентификатор раздела — по нему и раскладывать. Список ниже. | |
| 109 | | `title` | string | да | Заголовок по-русски. | |
| 110 | | `why` | string | нет | Зачем раздел собран **под этот симптом**. Пусто у разделов, собранных вне таблицы видов. | |
| 111 | | `items` | array of Item | да | Строки доказательства. | |
| 112 | |
| 113 | ### Item |
| 114 | |
| 115 | | Поле | Тип | Обязательно | |
| 116 | |---|---|---| |
| 117 | | `label` | string | да | |
| 118 | | `value` | string | да | |
| 119 | |
| 120 | `value` бывает многострочным (хвост лога, дамп переменных, список файлов) — |
| 121 | переводы строк внутри значения нормальны и значимы. Пустых значений нет: |
| 122 | «не нашлось» — это тоже текст, и он написан словами. |
| 123 | |
| 124 | Внимание: `items` — это **список пар, а не словарь**. `label` может |
| 125 | повторяться внутри раздела (несколько отчётов о сбое, несколько замечаний |
| 126 | об осмотре папки), и порядок значим. Складывать в map нельзя — потеряются |
| 127 | строки. |
| 128 | |
| 129 | ### Redacted |
| 130 | |
| 131 | | Поле | Тип | Что это | |
| 132 | |---|---|---| |
| 133 | | `rule` | string | Человеческое описание правила («имя машины скрыто»). | |
| 134 | | `replacement` | string | Чем заменяли (`~`, `<пользователь>`). | |
| 135 | | `count` | integer | Сколько замен сделано. | |
| 136 | |
| 137 | --- |
| 138 | |
| 139 | ## Виды проблемы (`kind`) |
| 140 | |
| 141 | Формулировки — симптомы, а не категории: человек, который не может |
| 142 | описать проблему, узнаёт «чёрный экран», но не «подсистема рендеринга». |
| 143 | |
| 144 | | `kind` | `kind_title` | Слаг в CLI | Игра нужна | |
| 145 | |---|---|---|---| |
| 146 | | `no-start` | Игра не запускается | `не-запускается` | да | |
| 147 | | `black-screen` | Чёрный экран, картинки нет | `чёрный-экран` | да | |
| 148 | | `crash` | Игра вылетает | `вылетает` | да | |
| 149 | | `slow` | Тормозит, низкий FPS | `тормозит` | да | |
| 150 | | `no-sound` | Нет звука | `нет-звука` | да | |
| 151 | | `gamepad` | Не работает геймпад | `геймпад` | да | |
| 152 | | `launcher` | Что-то не так в самом лаунчере | `лаунчер` | **нет** | |
| 153 | |
| 154 | Список закрытый в пределах мажорной версии формата. Новый вид — минорное, |
| 155 | совместимое изменение (см. «Совместимость»), поэтому принимающая сторона |
| 156 | **обязана** уметь получить неизвестный `kind`: класть в «разобрать |
| 157 | руками», а не отбрасывать. |
| 158 | |
| 159 | --- |
| 160 | |
| 161 | ## Разделы (`sections[].id`) |
| 162 | |
| 163 | | `id` | Заголовок | Что внутри | |
| 164 | |---|---|---| |
| 165 | | `launcher` | Лаунчер и система | Версия лаунчера, дистрибутив, ядро, тип сессии, разрешение, каталог установки, число игр. | |
| 166 | | `diagnostics` | Диагностика | Проверки `chl doctor`: итог плюс строки. У вида `launcher` — все, включая пройденные; у остальных — только отклонения (или только разделы «Графика»/«Системные лимиты»). | |
| 167 | | `game` | Игра | Запись в библиотеке (файл, есть ли он, источник, префикс, Steam appid) и история запусков. | |
| 168 | | `game_config` | Настройки игры | **Только изменённые** относительно умолчаний, с указанием происхождения значения. | |
| 169 | | `wine` | Wine и префикс | Сборка Wine и **почему выбрана именно она**, каталог, загрузчик, префикс и готов ли он, раскладка сборки, размеры DLL рендера в префиксе, настройки рендера. | |
| 170 | | `graphics` | Графика | Карты из `/sys/class/drm` (драйвер, PCI id, модель из `pci.ids`, VRAM, загрузка), ICD Vulkan с версией API, подключённые выходы с режимом. | |
| 171 | | `audio` | Звук | Сокет звукового сервера, `/proc/asound/cards`, звуковые драйверы сборки Wine. | |
| 172 | | `input` | Ввод и геймпад | Геймпады, прочие устройства, сколько устройств не читается по правам, переназначенные кнопки. | |
| 173 | | `last_run` | Прошлый запуск | Исход, время, сборка, префикс, запускавшийся файл, **хвост stderr** (до 200 строк / 64 КиБ, подряд идущие повторы свёрнуты в `[повторено × N]`), пути отчётов о сбоях. | |
| 174 | | `game_logs` | Лог игры | Пути найденных логов движка и их хвост (до 120 строк). Не нашлось — сказано, где искали и что это значит. | |
| 175 | | `crash_artifacts` | Отчёты о сбоях от игры | **Только пути и размеры.** Содержимое дампов не читается и не отправляется никогда: в дампе память процесса. | |
| 176 | | `game_folder` | Папка игры | Находки `chl_core::game_folder`: недоустановленный мод, ENB без обёртки, активатор репака и т.п. | |
| 177 | | `env` | Окружение запуска | Полный дамп собранного окружения (`chl env`), несколько десятков переменных. | |
| 178 | |
| 179 | Соответствие «вид → набор разделов» и обоснование каждой пары живут в |
| 180 | коде — `chl_report::Kind::evidence`. Обоснование оттуда приезжает в поле |
| 181 | `why` каждого раздела, так что **отчёт объясняет сам себя**, и жёстко |
| 182 | завязываться на набор разделов у вида не нужно. |
| 183 | |
| 184 | Разделы, которые человек снял в предпросмотре, в теле отсутствуют вовсе. |
| 185 | То есть **отсутствие раздела не означает «данных не было»** — оно означает |
| 186 | «не прислали». Различать эти два случая по телу нельзя, и требовать |
| 187 | раздел как обязательный нельзя ни для какого вида. |
| 188 | |
| 189 | --- |
| 190 | |
| 191 | ## Чистка |
| 192 | |
| 193 | Делается на клиенте, до предпросмотра, всегда (кроме `chl report --raw`, |
| 194 | который с `--send` запрещён — непочищенный отчёт отправить нельзя). |
| 195 | |
| 196 | | Что | Чем заменяется | |
| 197 | |---|---| |
| 198 | | Домашний каталог (`$HOME`) | `~` | |
| 199 | | Имя пользователя (`$USER`, `$LOGNAME`, имя каталога `$HOME`), от 3 символов | `<пользователь>` | |
| 200 | | Имя машины (`/etc/hostname`), от 3 символов | `<машина>` | |
| 201 | | Токен сервиса (`compat_api_token`) | `<токен скрыт>` | |
| 202 | | Любая шестнадцатеричная строка от 32 символов | `<похоже на ключ, скрыто>` | |
| 203 | |
| 204 | Правила применяются от самой длинной подстроки к самой короткой, поэтому |
| 205 | `/home/игрок/...` становится `~/...`, а не `/home/<пользователь>/...`. |
| 206 | Операция односторонняя: восстановить исходный текст из отчёта нельзя. |
| 207 | |
| 208 | Чего чистка **не** делает и на что рассчитывать не надо: она не ищет |
| 209 | персональные данные вообще (имена в текстах логов, адреса, номера) — такой |
| 210 | фильтр либо не находит ничего, либо калечит диагностику, и вдобавок создаёт |
| 211 | ложное чувство, что отчёт «проверен». Названия игр, модель железа и |
| 212 | структура путей внутри префикса остаются как есть: без них отчёт |
| 213 | диагностировать нельзя, и человек видит их в предпросмотре целиком. |
| 214 | |
| 215 | --- |
| 216 | |
| 217 | ## Доставка и почему сервер может не спешить |
| 218 | |
| 219 | Отчёт **всегда сначала ложится файлом**, и только потом (по отдельному |
| 220 | нажатию) уходит по сети: |
| 221 | |
| 222 | ``` |
| 223 | ~/.local/state/chimera-launcher/reports/<unix>-<вид>-<игра>.json |
| 224 | ~/.local/state/chimera-launcher/reports/<unix>-<вид>-<игра>.txt |
| 225 | ``` |
| 226 | |
| 227 | `.txt` — тот же отчёт человекочитаемым текстом, слово в слово то, что |
| 228 | человек видел в предпросмотре. Именно его и пересылают руками. |
| 229 | |
| 230 | Причина такого порядка не в аккуратности. `chimera-compat.chimera.local` |
| 231 | разрешается только в домашней сети владельца. Первый настоящий адресат |
| 232 | этой функции — друг со Steam Deck, и он **не достучится до сервера |
| 233 | никогда**. Значит для него «отправить» всегда кончится ошибкой, о которой |
| 234 | лаунчер скажет прямо, и работать он будет через файл. |
| 235 | |
| 236 | Отсюда два следствия для серверной стороны: |
| 237 | |
| 238 | 1. **Спешить необязательно.** Функция полезна уже сейчас, без сервера. |
| 239 | 2. **Публичная точка входа — отдельная задача, и она нужна.** Пока её нет, |
| 240 | `--send` имеет смысл только внутри LAN. Это работа на стороне кластера |
| 241 | (ingress наружу, свой токен на клиента, ограничение частоты), не |
| 242 | лаунчера. |
| 243 | |
| 244 | --- |
| 245 | |
| 246 | ## Совместимость |
| 247 | |
| 248 | `version` — мажорная. Меняется, только когда старый разбор ломается: |
| 249 | поле убрали, переименовали, сменили тип или смысл. |
| 250 | |
| 251 | **Совместимо** (версию не двигает, и принимающая сторона обязана это |
| 252 | переживать): |
| 253 | |
| 254 | - новый вид проблемы в `kind`; |
| 255 | - новый раздел в `sections`; |
| 256 | - новые `items` в существующем разделе, другой их порядок; |
| 257 | - новое необязательное поле верхнего уровня; |
| 258 | - любые изменения русских формулировок (`kind_title`, `title`, `why`, |
| 259 | `summary`, `label`, `value`) — они и должны улучшаться; |
| 260 | - новое правило чистки в `redacted`. |
| 261 | |
| 262 | Отсюда правила разбора: читать по `id` и `kind`, не по позиции; неизвестное |
| 263 | не отбрасывать, а сохранять как есть; на обязательность разделов не |
| 264 | опираться (человек мог снять любой). |
| 265 | |
| 266 | --- |
| 267 | |
| 268 | ## Что делать с отчётом дальше — не решено здесь |
| 269 | |
| 270 | Разбор отчёта в работу OpenProject (какой проект, какой тип, что в |
| 271 | описание, что в вики) сознательно **не описан**: это отдельный |
| 272 | workstream на стороне кластера. Со стороны лаунчера обязательство одно — |
| 273 | этот формат и его совместимость. |
| 274 | |
| 275 | Единственная просьба к тому разбору: `summary` — уже готовое описание |
| 276 | проблемы, написанное лаунчером за человека, который сформулировать не мог. |
| 277 | Его стоит взять как описание работы целиком, а не пересказывать: смысл |
| 278 | всей функции в том, что этот текст не надо составлять заново. |
| 279 |