kwork-api/WIP.md

Work In Progress — kwork-api

📊 Статус

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

---

📋 План

• Структура проекта (pyproject.toml, UV)
• Модели Pydantic (20+ моделей)
• API клиент (45+ эндпоинтов)
• Обработка ошибок (7 типов исключений)
• Тесты unit (46 тестов, 92% coverage)
• Документация (MkDocs + mkdocstrings)
• CI/CD pipeline (Gitea Actions)
• 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

Команды:

# Локальная разработка
mkdocs serve

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

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

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

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

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

Запуск:

# Все тесты
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

uv publish \
  --username <user> \
  --password <token> \
  https://git.much-data.ru/api/packages/much-data/pypi

Установка:

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