evening_detective_frontend/AGENTS.md

# AGENTS.md — Вечерний детектив (фронтенд)

Правила работы агента над этим репозиторием. Читай целиком перед началом любой задачи.
Онлайн-детективная игра: команды проходят «дело» — сценарий из точек, дверей, ключей и улик.

## 1. Стек и команды

- **Стек:** Vue 3.5 (`<script setup lang="ts">`), Vite 8, Pinia 3, Vue Router 5, Naive UI (тёмная тема), @vicons, axios.
- **API:** клиенты генерируются из `proto/main.proto` → `src/api/generated/`.

| Команда | Назначение |
|---|---|
| `npm run dev` | dev-сервер (Vite, `--host`) |
| `npm run type-check` | проверка типов (vue-tsc) |
| `npm run lint` | ESLint с автофиксами |
| `npm run lint:css` | Stylelint (алфавитный порядок свойств) |
| `npm run format` | Prettier (`src/`) |
| `npm run build` | type-check + сборка |
| `npm run proto:gen` | генерация API-клиентов из proto (после изменения proto) |

## 2. Структура и соглашения

- `src/views/*View.vue` — тонкие обёртки над страницами (только импорт и `<Page />`).
- `src/components/*Page.vue` — страницы (GamesPage, OfficePage, TeamStoryPage…).
- `src/components/*.vue` — переиспользуемые блоки (HeaderMenu, MessagePaper, PlaceBlock, IntroBlock…).
- `src/api/generated/**` — **сгенерированный код, руками не редактировать.** Обновляется только через `npm run proto:gen`.
- `src/stores/`, `src/composables/`, `src/utils/`, `src/types/` — по назначению.
- Алиас `@/` → `src/`. Импорты: `@/components/...` для общих блоков, относительные для соседних файлов.
- UI-тексты — на русском.

## 3. Правила выполнения задач

1. **Сначала изучи.** Прочитай `package.json`, `tsconfig.app.json`, релевантные компоненты и существующие паттерны. Следуй им; не вводи новый стек, механизмы и зависимости без согласования с пользователем.
2. **Код:** `defineProps` с типами (`Object as PropType<T>`), типизированные `emit`, производные значения через `computed`. Не дублируй логику — выноси в `composables/`/`utils/`.
3. **Импорты:** сортируй (simple-import-sort): сторонние → `@/` → относительные. Удаляй неиспользуемые (unused-imports). Точки с запятой не ставим, одинарные кавычки, ширина 100 (Prettier).
4. **API:** только через сгенерированные клиенты (`getAuthClient()` и т.п.). После вызова проверяй `res.error` и показывай `message.error(res.error!)`. Поля из proto необязательны — бери с `!` как в существующем коде.
5. **Ошибки и состояния:** используй `useMessage()` из naive-ui; загрузку — простым `ref` + асинхронная функция (существующий паттерн), поллинг — `useSimplePolling`.
6. **Стили:** `scoped`, свойства по алфавиту (stylelint). Не добавляй новые цвета хардкодом — только палитра из раздела 4.
7. **Адаптивность:** мобильная вёрстка по умолчанию, брейкпоинт `@media (width >= 1024px)` (существующий паттерн). Скрывай скроллбары как `.center-block-custom`.
8. **Проверки перед сдачей (всегда):** `npm run type-check` → `npm run lint` → `npm run lint:css`. При затрагивании сборки — `npm run build`. Сообщи в ответе, какие проверки прошли.
9. **Запрещено:** `git commit` и `git push` (глобальное правило). Не переписывай чужой код без необходимости — минимальные целевые изменения.

## 4. Правила дизайна (канон «бумажного детектива»)

Стилистика проекта — тёмный «кабинет сыщика»: тёмный фон, «бумажные листы дел» с текстурой и шрифтом печатной машинки, бронзовые/золотые акценты, зелёный акцент интерактива.

### 4.1 Палитра (использовать только эти значения)

| Роль | Значение |
|---|---|
| Фон страницы | `#111` |
| Панели / карточки / блоки | `#222` (border-radius: 10px) |
| Основной текст | `#eee` |
| Вторичный текст (подписи, служебное) | `#aaa`, `#777` |
| Акцент hover/active | `#63e2b7` |
| Бронза (заголовки на бумаге, PDF-ссылки) | `--second-color: rgb(97 74 22)` |
| Золото (ключи, «требуемые ключи») | `gold` |
| Кнопки-действия на бумаге | текст `#bfa07d`, фон — текстура `belt.png` |
| Подписи улик/приложений | `burlywood` |
| Текст на бумажном листе | `black` |

### 4.2 Типографика

- **UI (формы, панели, навигация):** системный стек из `base.css`, 15px.
- **Бумажные листы дел:** `font-family: 'font_old_typer'` (шрифт подключён в `main.css`, файл `src/assets/fonts/a_OldTyper.ttf`). Контент — 18px, заголовок вступления — 26px с `letter-spacing: 3px`.
- Никогда не используй `font_old_typer` для UI-элементов (кнопки, формы, меню).

### 4.3 Бумажный лист (компонент MessagePaper)

Контент дел (вступление, точки, приложения) оборачивается в `MessagePaper`:

- Фон — текстура `paper.jpg` (`background-size: cover`), тень `0 0 5px black`, слои-подложки с поворотами `rotate(-3deg)` / `rotate(2deg)`.
- Разделители — пунктирные `hr`: `border: dashed 1px` (на бумаге — `black`, в тёмных панелях — `#eee`).
- **«Фотографии»** (картинка точки, картинки-улики): подложка с текстурой `paper_white.jpg`, паддинг 7px, `transform: rotate(-3deg)`, тень `0 3px 15px rgb(98 98 98)`, `cursor: zoom-in`, клик — просмотр в `n-modal` + `n-card`.
- **Улики-картинки в потоке текста:** блок `float: right`, текст обтекает; контейнер — `display: flow-root` (BFC, чтобы не наезжало на двери).
- **Кнопки действий («двери»):** фон `belt.png` (`background-size: cover`), текст `#bfa07d`, `border-radius: 5px`, inline-block, паддинг `5px 12px`.
- **Сворачивание листа:** иконка `collapse.png` (45×28), развёрнутый лист — `rotate(-180deg)`.

### 4.4 Компоненты и иконки

- UI-контролы — только naive-ui (`n-*`): тёмная тема задана в `App.vue` (`NConfigProvider :theme="darkTheme"`). Не стилизуй нативные `<input>/<button>`.
- Иконки — `@vicons` через обёртку `<Icon>` из `@vicons/utils`, размер через `size` (например `<Icon size="28"><MenuOutlined /></Icon>`).
- Модальные окна просмотра — `n-modal` + `n-card`, ширина `min(94vw, 1200px)`, `role="dialog" aria-modal="true"`.

### 4.5 Раскладка страниц

- Фиксированный `HeaderMenu` сверху, высота 70px; контент — контейнер `.center-block-custom` (`margin-top: 70px`, высота `calc(100dvh - 70px)`, скрытый скроллбар).
- Ширина контента: `.width700` — бумажные листы/дела, `.width1200` — списки и таблицы.
- Карточки списков (игры, сценарии): фон `#222`, `border-radius: 10px`, hover — `color: #63e2b7` + `cursor: pointer`.
- Интерактивные блоки-«листы» в редакторе: `.place-block-hover` — hover-рамка `1px solid #63e2b7`.

### 4.6 Поведение и состояния

- Hover интерактивных элементов — только `#63e2b7` (не изобретай новые цвета).
- Заголовки и служебные подписи — вторичные цвета палитры (`#aaa`/`#777`), без ярких акцентов.
- Новые цвета/токены добавлять только через `src/assets/base.css` в `:root` (существующие: `--main-color`, `--second-color`, `--main-back-color`, `--main-back-item-color`) — и только если без них нельзя обойтись палитрой.

## 5. Чек-лист перед сдачей

1. ✅ Соблюдены соглашения структуры и импортов (разделы 2–3).
2. ✅ Использована только палитра и стилистика раздела 4.
3. ✅ Адаптивность и скролл-контейнеры как в существующих страницах.
4. ✅ `npm run type-check`, `npm run lint`, `npm run lint:css` — без ошибок (отчёт в ответе).
5. ✅ Сгенерированный код не тронут; git commit/push не выполнялись.