klg-asutk-app/docs/КАК_ЗАПУСТИТЬ.md

# Как запустить программу

## Lawer R в своём окне (DMG или из исходников)

**Готовый образ для macOS:** `dist/Lawer R.dmg`. Перетащите «Lawer R» в «Программы» и запускайте. Своё окно, без Docker, Python, Node и других программ.

**Если .app не открывается** (macOS: «Разработчик не опознан»): нажмите по «Lawer R» правой кнопкой → **Открыть** (один раз).

### Сборка DMG (на машине сборки: Python 3, Node.js)

```bash
pip install -r requirements-standalone.txt
./build_dmg.sh
```

Результат: `dist/Lawer R.dmg`. Данные приложения: `~/Library/Application Support/LawerR/`.

### Запуск из исходников в одном окне (без сборки .app)

Если DMG не собран или .app не запускается — можно поднять Lawer R в одном окне из кода (нужны Python 3.11–3.13 и Node.js). **Из корня проекта** (папка `klg_asutk_app`):

```bash
cd ~/Downloads/klg_asutk_app   # или путь к папке проекта
chmod +x run-standalone-from-source.sh
./run-standalone-from-source.sh
```

Скрипт соберёт frontend (если ещё нет `frontend/dist`), поставит зависимости (в т.ч. pywebview) и запустит лаунчер. Вход: токен **`dev`**.

### Не запускается?

Откройте **`~/Library/Logs/LawerR/launcher.log`** — в нём причина и полный traceback при ошибках сервера или окна. Если порт **18473** занят, закройте другое приложение или пересоберите .app.

---

## Нет Docker?

- **Установить Docker:** [Docker Desktop для Mac](https://www.docker.com/products/docker-desktop/) — раздел 1.
- **Без Docker (проще всего):** только **Python 3.11+** и **Node.js** — один скрипт, **PostgreSQL и Homebrew не нужны**. См. **раздел 4 (вариант А)**.
- **Без Docker с PostgreSQL:** раздел 4, вариант Б (пункты 4.1–4.3).

---

## 1. Запуск через Docker Compose (рекомендуется)

Из корня проекта:

```bash
cd klg_asutk_app
docker compose up --build
```

После старта:

| Сервис   | URL |
|----------|-----|
| **Frontend** | http://localhost:8080 |
| **API**      | http://localhost:8000 |
| **Документация API (Swagger)** | http://localhost:8000/docs |
| **Health**   | http://localhost:8000/api/v1/health |

### Пересборка после изменений

```bash
docker compose up --build
```

### Остановка

```bash
docker compose down
```

---

## 2. Авторизация (dev)

В dev используется заголовок:

```
Authorization: Bearer dev
```

или JWT с claim'ами: `sub`, `name`, `email`, `role`, `org_id`.

Роли: `admin`, `operator_manager`, `authority_inspector` и др.

---

## 3. Модуль юридических документов

### Юрисдикции (справочник)

После первого запуска заполните юрисдикции. **Команда выполняется только при запущенном backend** (если контейнеры остановлены — сначала `docker compose up -d` или `docker compose up --build`):

```bash
# 1) Убедитесь, что сервисы запущены (в одном терминале: docker compose up --build или в фоне: docker compose up -d)
# 2) Затем:
docker compose exec backend python -m app.db.seed_legal
```

Если видите ошибку `service "backend" is not running` — поднимите сервисы: `docker compose up -d`.

### ИИ-агенты (опционально)

Для работы классификации, проверки норм, перекрёстных ссылок и т.п. задайте в `docker-compose.yml` для сервиса `backend`:

```yaml
environment:
  OPENAI_API_KEY: "sk-..."
  # OPENAI_BASE_URL: "https://..."   # для локальных моделей
  # LEGAL_LLM_MODEL: "gpt-4o-mini"   # модель по умолчанию
```

и перезапустите:

```bash
docker compose up --build -d
```

### Эндпоинты модуля legal

- `GET  /api/v1/legal/jurisdictions` — список юрисдикций
- `GET  /api/v1/legal/documents` — список документов
- `POST /api/v1/legal/analyze` — запуск ИИ-анализа (тело: `jurisdiction_id`, `title`, `content` и др.)
- и другие — см. http://localhost:8000/docs#/legal

---

## 4. Запуск без Docker

### Вариант А: один скрипт (без PostgreSQL и Homebrew)

Нужны только **Python 3.11+** и **Node.js** ([nodejs.org](https://nodejs.org/)).

```bash
chmod +x run-without-docker.sh   # один раз, если «Permission denied»
./run-without-docker.sh
```

Скрипт: SQLite (`backend/klg.db`), каталог загрузок `backend/data/files`, зависимости из `backend/requirements-sqlite.txt` (без PostgreSQL), backend + frontend.  
После запуска: **http://localhost:3000**, токен **`dev`**. Остановка: **Ctrl+C**.

---

### Вариант Б: вручную с PostgreSQL

Требуются: PostgreSQL, Python 3.11+, Node.js. Если нет Homebrew: [Docker Desktop](https://www.docker.com/products/docker-desktop/) (раздел 1) или [Homebrew](https://brew.sh) и [Postgres.app](https://postgresapp.com/).

#### 4.1. PostgreSQL

**macOS (Homebrew):** если Homebrew уже есть и PostgreSQL ещё не установлен:

```bash
brew install postgresql@16
brew services start postgresql@16
# при необходимости: export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
```

Создайте пользователя `klg` с паролем `klg` и БД `klg`:

```bash
# один раз: пользователь klg, пароль klg, БД klg
createuser -s klg 2>/dev/null || true
psql -d postgres -c "ALTER USER klg WITH PASSWORD 'klg';" 2>/dev/null || true
createdb -O klg klg 2>/dev/null || true
```

Если `createuser` или `psql` выдают «role klg already exists» / «database klg already exists» — это нормально.

Если `psql` или `createuser` не в PATH (Apple Silicon / Homebrew):

```bash
export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
# или: /usr/local/opt/postgresql@16/bin — для Intel Mac
```

Либо создайте БД под своим пользователем и укажите в `DATABASE_URL`, например:

```text
postgresql+psycopg2://ВАШ_ПОЛЬЗОВАТЕЛЬ@localhost:5432/klg
```

### 4.2. Backend

```bash
cd backend

# виртуальное окружение (по желанию)
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# зависимости
pip install -r requirements.txt

# переменные (или .env в backend/)
export DATABASE_URL="postgresql+psycopg2://klg:klg@localhost:5432/klg"
export OPENAI_API_KEY="sk-..."   # по желанию

# создание таблиц и запуск
python -m app.db.init_db
python -m app.db.seed_legal     # юрисдикции для legal
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

API: http://localhost:8000, docs: http://localhost:8000/docs

### 4.3. Frontend

```bash
cd frontend
npm install
npm run dev
```

Фронт: http://localhost:3000. Прокси `/api` → `http://localhost:8000` (в `vite.config.ts`).

---

## 5. Проверка работы

1. **Health:**  
   `curl http://localhost:8000/api/v1/health`

2. **Список юрисдикций (с авторизацией):**  
   `curl -H "Authorization: Bearer dev" http://localhost:8000/api/v1/legal/jurisdictions`

3. **Swagger:**  
   Откройте http://localhost:8000/docs, нажмите «Authorize», введите `dev` в качестве Bearer-токена.

---

## 6. Приложение не загружается — что проверить

### Страница белая или «не загружается»

1. **Docker (если через `docker compose`):**
   - Убедитесь, что Docker запущен.
   - Выполните `docker compose up --build` и дождитесь сообщений о готовности frontend и backend.
   - Откройте http://localhost:8080 (не 3000: снаружи порт 8080).

2. **Вход в систему:**
   - Если видите форму входа — введите токен `dev` и нажмите «Войти». Без токена дальше приложение не откроется.

3. **Бэкенд не отвечает:**
   - Проверьте: `curl http://localhost:8000/api/v1/health`
   - Если ошибка — поднимите backend (Docker или вручную `uvicorn app.main:app --host 0.0.0.0 --port 8000`).
   - При ручном запуске фронта: backend должен быть на `http://localhost:8000`, иначе запросы `/api` будут падать.

4. **Запуск вручную (без Docker):**
   - Сначала backend на порту 8000, затем `cd frontend && npm run dev`. Фронт: http://localhost:3000.
   - В `vite.config.ts` по умолчанию прокси `/api` идёт на `http://localhost:8000`.

5. **Консоль браузера (F12 → Console):**  
   Посмотрите ошибки (сеть, CORS, 404 по `/api`). Если много 404 на `/api/*` — backend не запущен или прокси указан неверно.