Project Chimera
Меню

Исходники

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```
23POST https://compat.project-chimera.ru/problem-reports/anonymous
24Content-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
2381. **Спешить необязательно.** Функция полезна уже сейчас, без сервера.
2392. **Публичная точка входа — отдельная задача, и она нужна.** Пока её нет,
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описание, что в вики) сознательно **не описан**: это отдельный
272workstream на стороне кластера. Со стороны лаунчера обязательство одно —
273этот формат и его совместимость.
274
275Единственная просьба к тому разбору: `summary` — уже готовое описание
276проблемы, написанное лаунчером за человека, который сформулировать не мог.
277Его стоит взять как описание работы целиком, а не пересказывать: смысл
278всей функции в том, что этот текст не надо составлять заново.
279