169 lines
11 KiB
Markdown
169 lines
11 KiB
Markdown
# CLAUDE.md
|
||
|
||
Контекст проекта для Claude Code. Читается при старте каждой сессии.
|
||
|
||
## TL;DR
|
||
|
||
**Laude / Exercise Reminder** — Windows desktop приложение на Electron 33, которое напоминает делать упражнения и опционально парсит статистику матчей Dota 2 (через GSI) в количество повторений. Текущая версия — **0.5.4**. Один разработчик (AnRil), один remote — self-hosted Gitea.
|
||
|
||
## Стек
|
||
|
||
- **Runtime**: Electron 33 (main + preload + renderer)
|
||
- **Build**: electron-vite 2 + Vite 5 + electron-builder 25 (NSIS, x64 only)
|
||
- **UI**: React 18 + TypeScript 5 + Tailwind 3 + framer-motion + react-router (HashRouter) + zustand 5
|
||
- **Auto-update**: electron-updater 6, generic provider, фиксированный канал
|
||
- **Тесты**: Vitest 4 (53 теста, все зелёные)
|
||
- **Lint/format**: ESLint 8 (flat-ish .eslintrc.cjs) + Prettier 3 + EditorConfig
|
||
- **Иконки**: lucide-react (whitelisted lookup через `ICON_CHOICES`)
|
||
- **Шрифты**: Plus Jakarta Sans, Bricolage Grotesque, JetBrains Mono (Google Fonts CDN)
|
||
|
||
## Архитектура (важное)
|
||
|
||
### Процессы
|
||
- **main** (`src/main/`) — Node, scheduler, GSI HTTP-сервер, IPC, окна, tray, updater, persistence
|
||
- **preload** (`src/preload/index.ts`) — contextBridge → `window.api`, dev-only методы вырезаны на проде (`import.meta.env.MODE !== 'production'`)
|
||
- **renderer** (`src/renderer/src/`) — React, zustand-store, страницы Dashboard/Games/Settings/About, ReminderApp в отдельном окне
|
||
|
||
### Persistence
|
||
- Единственный JSON-файл: `%APPDATA%\Exercise Reminder\app-state.json`
|
||
- **Атомарная запись**: tmp + rename + retry на EBUSY/EPERM (антивирус, OneDrive)
|
||
- **Не теряет данные**: corrupt JSON → quarantine в `app-state.json.corrupt-<ts>`, не silent wipe
|
||
- **Schema migrations**: `__schemaVersion` поле + `MIGRATIONS: Record<number, (s)=>s>` map в `src/main/store.ts`
|
||
- **Debounced writes**: pendingWrite с `.unref()`
|
||
|
||
### IPC
|
||
- Типизированные каналы — `src/shared/ipc.ts`
|
||
- **Validation layer** — `src/main/validate.ts` (hand-rolled, без zod):
|
||
- `intervalMinutes ∈ [1, 1440]`, `reps ∈ [1, 9999]`, `multiplier ∈ [0, 1000]`
|
||
- string cap 200 chars, enum-валидация для theme/lang/notify-mode/stat
|
||
- HH:MM regex для quietHours, dedup days
|
||
- Strip `id` из updateExercise/updateChallenge patch
|
||
- **Dev-only**: `dev:simulateMatchEnd` gated на `!app.isPackaged`
|
||
|
||
### Auto-update (КРИТИЧНО)
|
||
- **Фиксированный URL канала**: `…/releases/download/update-channel/latest.yml` — никогда не меняется
|
||
- **НЕ** `…/releases/download/v${version}/…` (старая схема ломалась: установленная копия видела только свой релиз)
|
||
- Hourly silent auto-check (транзитные сетевые ошибки не показывают красный баннер; только ручной клик показывает ошибку)
|
||
- Boot-check: 3 ретрая с backoff 30s/2m/5m
|
||
- `lastCheckedAt` → UI «проверено N мин назад»
|
||
- Релиз через `scripts/release.ps1` публикует одной командой в:
|
||
1. `vX.Y.Z` (постоянный архивный тег)
|
||
2. `update-channel` (rolling — клиенты проверяют отсюда)
|
||
3. Опциональные `-BridgeTags` для миграции старых пользователей
|
||
|
||
### Безопасность
|
||
- **GSI server** (`src/main/games/gsi-server.ts`): per-install token verify через `timingSafeEqual`, reject Origin/Sec-Fetch-Site (CSRF), 256KB body cap, require `application/json`, generic 400
|
||
- **shell.openExternal allowlist**: только `http:`/`https:`/`mailto:` (`src/main/windows.ts`)
|
||
- **will-navigate** блокирует non-file:// и non-dev URL
|
||
- **Modal focus trap** + focus restore, aria-labelledby
|
||
|
||
### Quiet hours
|
||
- `isQuietAt(time, settings)` в `src/shared/types.ts`
|
||
- Wrap-around (22:00 → 07:00) корректно — при wrap-active проверяется день *начала* окна
|
||
- Тесты в `src/shared/quiet-hours.test.ts`
|
||
|
||
### История / стрики
|
||
- `src/renderer/src/lib/history.ts` — DST-safe через `shiftDays()` (calendar `setDate`, не ms-арифметика)
|
||
- Cap 10k записей, trim oldest 10% на overflow
|
||
- HistoryHeatmap: percentile-based bucketing (p25/p50/p85), а не flat ratio (защищает от outlier-дней)
|
||
|
||
### i18n
|
||
- Самописная микро-система: `src/renderer/src/i18n/dict.ts` (плоский словарь ~200 ключей × 2 языка)
|
||
- Хук `useT()`, плюрализация CLDR rules для RU (one/few/many)
|
||
- Интерполяция через split/join (не regex — защита от regex-инъекций в значениях var)
|
||
- Tray menu тоже локализован (`TRAY_STRINGS` в `src/main/tray.ts`)
|
||
|
||
## Команды
|
||
|
||
```bash
|
||
npm run dev # electron-vite dev
|
||
npm run typecheck # tsc по node + web
|
||
npm run test:run # vitest один раз
|
||
npm run lint # eslint --max-warnings 0
|
||
npm run format # prettier --write
|
||
npm run dist # сборка + NSIS installer → release/
|
||
|
||
# Релиз (всё в одном)
|
||
npm run release -- -Bump patch
|
||
# или -Bump minor / -Bump major / -Version 1.2.3
|
||
# опционально: -BridgeTags v0.4.0,v0.4.1
|
||
```
|
||
|
||
## Скрипты релиза
|
||
|
||
- `scripts/release.ps1` — bump → typecheck → test → build → tag → push → upload в Gitea (vX.Y.Z + update-channel + bridges)
|
||
- `scripts/upload-release-assets.ps1` — curl.exe с retry/backoff (15s/45s/2m/5m × 4) на 504/TLS, проверяет уже-залилось через list assets перед ретраем
|
||
- **PowerShell 5.1 gotchas**:
|
||
- Default reads CP1251 → файлы скриптов **ASCII-only**, без em-dash/кириллицы в коде
|
||
- `Set-Content -Encoding utf8` добавляет BOM → ломает PostCSS. Для UTF-8 без BOM использовать `[System.IO.File]::WriteAllText` + `new UTF8Encoding($false)`
|
||
- Никогда `-i` флаги (rebase -i, add -i) — нет interactive input
|
||
|
||
## Gitea remote
|
||
|
||
- URL: `https://xn--90adajar8af4h.xn--p1ai/git/AnRil/laude` (Punycode для `президент.рф`)
|
||
- User: `anril`
|
||
- Auth: см. `~/.claude/projects/.../memory/gitea_remote.md`
|
||
- **Actions выключены** (`has_actions: false`) — релизим через PowerShell, runners не настроены
|
||
- `.gitea/workflows/` пустая (раньше там лежали yml → queued runs копились)
|
||
|
||
## Файлы, которые часто правлю
|
||
|
||
| Файл | Что |
|
||
|---|---|
|
||
| `package.json` | version, publish.url, scripts, deps |
|
||
| `src/main/store.ts` | persistence, migrations, validation, atomic writes |
|
||
| `src/main/ipc.ts` | IPC handlers с валидацией |
|
||
| `src/main/scheduler.ts` | таймеры упражнений, powerMonitor |
|
||
| `src/main/games/dota2.ts` + `gsi-server.ts` | GSI приём матчей |
|
||
| `src/main/updater.ts` | auto-update logic, silent retries |
|
||
| `src/shared/types.ts` | shared типы, дефолты, isQuietAt |
|
||
| `src/shared/ipc.ts` | IPC channel types |
|
||
| `src/renderer/src/i18n/dict.ts` | словари |
|
||
| `src/renderer/src/pages/Dashboard.tsx` | главная |
|
||
| `src/renderer/src/ReminderApp.tsx` | окно напоминания |
|
||
|
||
## Тесты (53)
|
||
|
||
```
|
||
src/shared/types.test.ts (4)
|
||
src/shared/quiet-hours.test.ts (7)
|
||
src/renderer/src/lib/format.test.ts (8)
|
||
src/renderer/src/lib/history.test.ts (13)
|
||
src/main/games/vdf.test.ts (11)
|
||
src/renderer/src/i18n/i18n.test.ts (10)
|
||
```
|
||
|
||
Покрываются: helpers, история/стрики (DST), тихие часы (wrap+filter), VDF-парсер Steam, i18n с плюрализацией, дефолты.
|
||
|
||
## Технический долг (не для пользователя)
|
||
|
||
- `sandbox: true` на BrowserWindow — нужен smoke-тест preload в sandbox-режиме
|
||
- Self-host Google Fonts (сейчас внешняя CSP-зависимость)
|
||
- ReminderApp race: первое напоминание может прийти без озвучки до загрузки settings
|
||
- Мажорные апдейты (React 18→19, Electron 33→42, Tailwind 3→4) — каждый ломающий, отдельная итерация
|
||
- Code-signing NSIS — ~$300/год, уберёт SmartScreen warning
|
||
- Скриншоты в README (есть TODO в самом README)
|
||
|
||
## Стиль кода
|
||
|
||
- Prettier: semi:false, singleQuote, trailingComma:none, printWidth:80
|
||
- ESLint: eslint:recommended + ts + react + react-hooks (без style rules — это Prettier)
|
||
- TypeScript strict, никакого `any` в новом коде
|
||
- Комментарии на русском там, где объясняют **почему**, не **что**
|
||
- Коммиты на русском, формат `тип(scope): кратко` (feat/fix/docs/refactor/test/chore)
|
||
- Co-Authored-By футер в коммитах от Claude
|
||
|
||
## Управление контекстом
|
||
|
||
- **Ужимать контекст при достижении 250k токенов** — вызывать `/compact` (или эквивалент) когда суммарный контекст подходит к 250 000 токенов. Не дожидаться authentic переполнения и автоматического сжатия от рантайма — сделать это контролируемо, чтобы важный контекст (открытые правки, недокоммиченные решения, текущая ветка задачи) попал в summary, а не выпал.
|
||
|
||
## Чего НЕ делать
|
||
|
||
- Не пушить в `update-channel` руками — только через `release.ps1`
|
||
- Не добавлять `.gitea/workflows/*.yml` — has_actions выключен, runs зависнут
|
||
- Не использовать regex в i18n-интерполяции — только split/join
|
||
- Не silent wipe corrupt JSON — quarantine с timestamp
|
||
- Не возвращать ms-арифметику в history.ts — DST сломается
|
||
- Не убирать validation layer из IPC — compromised renderer может засунуть NaN/негативы
|
||
- Не амендить коммиты без явной просьбы пользователя
|