# Work In Progress — kwork-api

## 📊 Статус

| Параметр | Значение |
|----------|----------|
| **Проект** | kwork-api |
| **Начало** | 2026-03-23 |
| **Прогресс** | 100% |
| **Статус** | ✅ Готово к v1.0 |

---

## 📋 План

- [x] Структура проекта (pyproject.toml, UV)
- [x] Модели Pydantic (20+ моделей)
- [x] API клиент (45+ эндпоинтов)
- [x] Обработка ошибок (7 типов исключений)
- [x] Тесты unit (46 тестов, 92% coverage)
- [x] Документация (MkDocs + mkdocstrings)
- [x] CI/CD pipeline (Gitea Actions)
- [x] Semantic release (авто-версионирование)
- [ ] `/kworks` endpoint (требует исследования модели)
- [ ] Публикация на internal PyPI
- [ ] Интеграция с kwork-parser

---

## 🔨 Сейчас в работе

**Проект готов!** Ожидает настройки GITEA_TOKEN для автоматических релизов.

---

## 📝 Заметки

### 🏗️ Архитектура

**Стек:**
- Python 3.10+ (тесты на 3.12)
- UV (package manager)
- httpx[http2] (async client)
- pydantic v2 (модели)
- pytest + respx (тесты)
- ruff (lint + format)

**Структура:**
```
kwork-api/
├── src/kwork_api/
│   ├── __init__.py      # __version__
│   ├── client.py        # KworkClient (45+ методов)
│   ├── models.py        # 20+ Pydantic моделей
│   └── errors.py        # 7 типов исключений
├── tests/
│   ├── unit/            # Unit тесты (mock)
│   └── integration/     # Integration тесты (требуют credentials)
├── docs/                # Исходники документации
├── .gitea/workflows/    # CI/CD pipeline
└── pyproject.toml       # Конфигурация проекта
```

### 📚 Документация

**Инструмент:** MkDocs + mkdocstrings + Material theme

**Команды:**
```bash
# Локальная разработка
mkdocs serve

# Сборка HTML (для CI)
mkdocs build
```

**Деплой:** Автоматически через Gitea Actions на Gitea Pages

**Покрытие:** 100% docstrings (Russian language)

### 🧪 Тестирование

**Coverage:** 92% (порог 90% для PR)

**Запуск:**
```bash
# Все тесты
uv run pytest tests/unit/ -v

# С coverage
uv run pytest --cov=src/kwork_api --cov-report=html
```

**Артефакты:**
- HTML отчёт pytest (test-results/report.html)
- HTML отчёт coverage (coverage-html/index.html)

### 🚀 CI/CD (Gitea Actions)

**Workflow 1: PR Checks** (`pr-check.yml`)
- Триггер: `pull_request` в `main`
- Тесты с coverage (90% threshold)
- Linting (ruff)
- Formatter check
- Security scan (pip-audit)
- Артефакты: test results + coverage report

**Workflow 2: Release & Publish** (`release.yml`)
- Триггер: `push` в `main` ИЛИ теги `v*`
- **main:** Build (production deps only) → Deploy docs
- **tags:** Build → Publish to Gitea Packages

**Semantic Release:**
- Анализирует Conventional Commits
- Auto-bump версии (MAJOR/MINOR/PATCH)
- Auto-generate CHANGELOG
- Auto-create git tags
- Обновляет `pyproject.toml` и `__init__.py`

**Типы коммитов:**
- `feat:` → MINOR (0.1.0 → 0.2.0)
- `fix:` → PATCH (0.1.0 → 0.1.1)
- `feat: + BREAKING CHANGE` → MAJOR (0.1.0 → 1.0.0)
- `docs:`, `style:`, `refactor:`, `test:`, `chore:` → без изменений версии

### 📦 Публикация

**Gitea Packages:** PyPI-compatible registry
```bash
uv publish \
  --username <user> \
  --password <token> \
  https://git.much-data.ru/api/packages/much-data/pypi
```

**Установка:**
```bash
uv pip install kwork-api --index-url https://git.much-data.ru/api/packages/much-data/pypi
```

---

## 🎯 Endpoints

**Реализовано:** 33/33 (100%)

| Группа | Эндпоинты | Статус |
|--------|-----------|--------|
| CatalogAPI | `/catalogMainv2`, `/getKworkDetails` | ✅ |
| ProjectsAPI | `/projects`, `/getPayerOrders` | ✅ |
| UserAPI | `/getUserInfo`, `/getReviews` | ✅ |
| ReferenceAPI | `/cities`, `/countries`, `/categories` | ✅ |
| NotificationsAPI | `/notifications`, `/dialogs` | ✅ |
| OtherAPI | 25+ дополнительных | ✅ |
| ValidationAPI | `/api/validation/checktext` | ✅ |

**Не реализовано:**
- `/kworks` — требует исследования модели ответа
- Analytics эндпоинты — не нужны для библиотеки

---

## 🚧 Блокеры

Нет

---

## 📅 История

- **2026-03-29** — Репозиторий очищен от артефактов (site/, .coverage)
- **2026-03-29** — Настроен semantic-release для авто-версионирования
- **2026-03-29** — CI/CD pipeline готов (PR checks + release)
- **2026-03-29** — История переписана (1 чистый коммит)
- **2026-03-23** — Initial release (45+ endpoints, 92% coverage)

---

## 🔐 Секреты (Gitea)

**Требуется:** `GITEA_TOKEN` в repository secrets

**Права:**
- `write:repository` (push tags, create releases)
- `write:package` (publish to Gitea Packages)

**Где настроить:**
https://git.much-data.ru/much-data/kwork-api/settings/secrets