91 lines
6.9 KiB
Markdown
91 lines
6.9 KiB
Markdown
# Инструкции для агентов
|
||
|
||
## Контекст проекта
|
||
|
||
ProxyWarden - standalone Windows desktop client в корне репозитория. Это Tauri 2 + React/TypeScript UI + Rust backend для маршрутизации выбранных Windows-приложений через внешний SOCKS5-прокси или опциональный Local sing-box.
|
||
|
||
Не возвращать старую идею `APP_MODE=windows` и не подключать Windows-клиент к отдельному Node gateway/server. Текущий рабочий путь - `src`, `src-tauri`, `scripts` в корне репозитория.
|
||
|
||
## Основные инварианты
|
||
|
||
- Три компонента должны оставаться разделенными: Control App, ProxiFyre, Local sing-box.
|
||
- ProxiFyre - обязательный слой для per-app routing; Local sing-box - необязательный runtime.
|
||
- Внешний SOCKS5 flow должен работать без установленного Local sing-box.
|
||
- Profile apply не должен скрыто устанавливать, удалять, запускать или чинить компоненты. Install/start/stop/uninstall - только явные действия пользователя.
|
||
- Source of truth - JSON под `C:\ProgramData\ProxyWarden\config` и `state`.
|
||
- `C:\ProgramData\ProxyWarden\generated\proxifyre-app-config.json` и `sing-box-config.json` - derived artifacts, их можно пересоздать.
|
||
- Subscription URL и другие секреты нельзя показывать полностью в UI, diagnostics или логах.
|
||
- Summary panel должен оставаться read-only: без apply/install/start/stop/delete/input/subscription mutations.
|
||
|
||
## Структура
|
||
|
||
- `src/app/App.tsx` - основная React-оркестрация, вкладки `Сводка`, `ProxiFyre`, `VPN / Прокси`, вызовы Tauri-команд и transient UI state.
|
||
- `src/app/readiness.ts` - gating применимости маршрута. Не обходить его локальными проверками в JSX.
|
||
- `src/app/viewModel.ts` - маленькие display/view-model helpers.
|
||
- `src/ui/*` - общие presentational-компоненты. Для новых кнопок, вкладок, service rows, pills, полей и лог-дока сначала расширять эти компоненты.
|
||
- `src/api/tauriCommands.ts` - единственная TypeScript-обертка над `invoke(...)`; держать DTO в синхронизации с Rust.
|
||
- `src/domain/types.ts` - TypeScript-зеркало доменных DTO.
|
||
- `src-tauri/src/models.rs` - Rust-модели и default values.
|
||
- `src-tauri/src/validation.rs` - нормализация входов.
|
||
- `src-tauri/src/storage.rs` и `activity.rs` - JSON storage, backup/tmp writes, activity cap/sort.
|
||
- `src-tauri/src/adapters/proxy_router.rs` - adapter boundary для proxy-router.
|
||
- `src-tauri/src/adapters/proxifyre.rs` - первый adapter, генерирует ProxiFyre `app-config.json`.
|
||
- `src-tauri/src/adapters/singbox.rs` - генерация локального `sing-box` конфига из subscription cache и выбранного сервера.
|
||
- `src-tauri/src/component_detection.rs` - detection ProxiFyre/Proxifier/Local sing-box.
|
||
- `src-tauri/src/commands.rs` - Tauri command handlers, installer/service orchestration, structured errors.
|
||
- `src-tauri/src/main.rs` - реальная Tauri entrypoint-регистрация команд.
|
||
- `src-tauri/src/lib.rs` сейчас scaffold/stale; не считать его источником регистрации команд без отдельной cleanup-задачи.
|
||
- `scripts/*.ps1` - явные installer entrypoints. `-PlanOnly` должен возвращать structured JSON без side effects.
|
||
|
||
## Правила изменений
|
||
|
||
- Не создавать второй источник правды для профилей, targets, components, subscription или activity.
|
||
- Не писать generated config напрямую из React.
|
||
- Не парсить raw PowerShell/stdout в UI. Backend/helper boundary должен возвращать structured JSON/error DTO.
|
||
- Не привязывать UI напрямую к деталям ProxiFyre, если изменение относится к общему proxy-router поведению.
|
||
- Не делать Local sing-box обязательным для external target.
|
||
- Для service/install операций сохранять UAC/admin boundary и человекочитаемые ошибки.
|
||
- При удалении install folders сохранять safe-path checks; не ослаблять рекурсивное удаление.
|
||
- В UI держать стиль компактной Windows-утилиты, а не landing/dashboard. Использовать existing `Button`, `Tabs`, `ServiceControlRow`, `StatusPill`, `Field`, `ActionMenu`, `LogDock`.
|
||
- Всплывающие подсказки при наведении делать быстрыми, кастомными и читаемыми: темная compact-плашка с мягкой рамкой/тенью, появление ~120ms, без нативного browser `title` как основного UI. Для иконок расширять общий `IconButton`/tooltip-паттерн, а не дублировать JSX/CSS локально.
|
||
- Apply actions должны быть disabled с объяснением, когда нет приложений, ProxiFyre отсутствует, proxy input неверный или local route не готов.
|
||
|
||
## Проверка
|
||
|
||
Минимум для frontend/UI:
|
||
|
||
```powershell
|
||
npm run build
|
||
```
|
||
|
||
Rust/backend:
|
||
|
||
```powershell
|
||
cd D:\repos\ProxyWarden\src-tauri
|
||
cargo test
|
||
```
|
||
|
||
Tauri/toolchain:
|
||
|
||
```powershell
|
||
npm run tauri -- info
|
||
npm run tauri -- dev
|
||
npm run tauri -- build
|
||
```
|
||
|
||
Installer boundaries:
|
||
|
||
```powershell
|
||
& .\scripts\install-control-app.ps1 -PlanOnly
|
||
& .\scripts\install-proxyfier.ps1 -PlanOnly
|
||
& .\scripts\install-singbox.ps1 -PlanOnly
|
||
```
|
||
|
||
Для UI-изменений проверять browser-preview на desktop и narrow viewport. Browser-preview не доказывает native Tauri commands или elevated service lane.
|
||
|
||
## Известные риски
|
||
|
||
- Реальные elevated install/start/stop/uninstall операции для ProxiFyre и Local sing-box считаются `implemented but unproven`, пока они не проверены на Windows с UAC/admin confirmation.
|
||
- Исторические planning/evidence файлы лежат в ignored `docs`-папках и не должны попадать в коммиты.
|
||
- Старые документы могут ссылаться на `apps/windows-client`; текущая структура репозитория - standalone client в корне.
|