initial commit

2026-04-28 16:18:07 +03:00
commit 6480f31e8f
7 changed files with 243 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,103 @@
+# MIEM Employees Server
+
+Сервис собирает сотрудников МИЭМ с сайта ВШЭ, хранит карточки и историю обновлений в Postgres, показывает минимальную админку и отдает read-only MCP endpoint для ИИ-агентов.
+
+## Архитектура
+
+- `api`: FastAPI, REST API, HTML-админка, healthcheck.
+- `worker`: weekly scheduler, который запускает парсинг по `CRAWL_CRON`.
+- `mcp`: HTTP MCP endpoint с bearer token.
+- `postgres`: основная БД.
+
+Парсер использует фиксированный источник сотрудников, по умолчанию `https://miem.hse.ru/persons`. Для каждой карточки сохраняются ФИО, должности, год начала работы, контакты, идентификаторы, вкладки профиля, секции, публикации, курсы, ВКР, JSON-снапшот и сжатый HTML-снапшот. Ссылки обходятся только из меню профиля самого сотрудника (`person-menu`), например `#sci`, `#teaching`, `#main`.
+
+## Переменные окружения
+
+Скопируйте `.env.example` в `.env` и поменяйте секреты:
+
+```bash
+cp .env.example .env
+```
+
+Основные настройки:
+
+- `DATABASE_URL`: строка подключения SQLAlchemy.
+- `SOURCE_URL`: список сотрудников МИЭМ.
+- `CRAWL_CRON`: расписание в формате crontab, по умолчанию `0 3 * * 1`.
+- `CRAWL_LIMIT`: опциональный лимит профилей для тестового запуска.
+- `ADMIN_USERNAME`, `ADMIN_PASSWORD`: логин и пароль админки.
+- `SESSION_SECRET`: секрет подписи cookie.
+- `MCP_TOKEN`: bearer token для `/mcp`.
+- `PARSER_USE_PLAYWRIGHT`: включение Playwright-рендера динамических вкладок.
+
+## Локальный запуск
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+```
+
+Админка: `http://localhost:8000/admin`.
+
+## Docker Compose
+
+```bash
+docker compose up --build
+```
+
+По умолчанию:
+
+- API и админка: `http://localhost:8000`
+- MCP: `http://localhost:8001/mcp`
+- Postgres: `localhost:5432`
+
+Таблицы создаются приложением при старте. SQL-миграция для ручного применения лежит в `migrations/001_init.sql`.
+
+## Парсинг
+
+Weekly worker запускается по `CRAWL_CRON`. Ручной запуск доступен в админке на странице `Runs` или через REST:
+
+```bash
+curl -X POST http://localhost:8000/api/crawl-runs --cookie "miem_admin_session=..."
+```
+
+Алгоритм обновления:
+
+- найденные сотрудники получают статус `active` и обновленный `last_seen_at`;
+- новые сотрудники добавляются в `employees`;
+- активные сотрудники, исчезнувшие из текущего списка источника, получают статус `dismissed` и `dismissed_at`;
+- каждый успешный разбор сохраняет запись в `employee_snapshots`.
+
+## MCP
+
+Endpoint: `POST /mcp`, авторизация `Authorization: Bearer <MCP_TOKEN>`.
+
+Поддерживаемые tools:
+
+- `search_employees(query, status?, limit?)`
+- `get_employee(profile_id_or_url)`
+- `list_employee_publications(profile_id_or_url)`
+- `list_employee_courses(profile_id_or_url)`
+- `get_crawl_status()`
+
+Пример:
+
+```bash
+curl http://localhost:8001/mcp \
+  -H "Authorization: Bearer change-me-mcp-token" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+## Обслуживание
+
+```bash
+docker compose logs -f api
+docker compose logs -f worker
+docker compose exec postgres pg_dump -U miem miem_workers > backup.sql
+docker compose down
+```
+
+Версия сервиса: `0.1.0`. Админка всегда показывает версии backend и frontend в footer.