diff --git a/WIP.md b/WIP.md index a3329ec..d86bfcb 100644 --- a/WIP.md +++ b/WIP.md @@ -5,121 +5,158 @@ | Параметр | Значение | |----------|----------| | **Проект** | kwork-api | -| **Начало** | 2026-03-23 02:16 UTC | +| **Начало** | 2026-03-23 | | **Прогресс** | 100% | -| **Статус** | ✅ Готово | +| **Статус** | ✅ Готово к v1.0 | --- ## 📋 План -- [x] Структура проекта (pyproject.toml, зависимости) -- [x] Модели Pydantic (20+ моделей для всех ответов API) -- [x] API клиент (KworkClient с 45 эндпоинтами) -- [x] Обработка ошибок (KworkAuthError, KworkApiError, etc.) -- [x] Тесты unit (49 тестов, 92% coverage) -- [x] Документация (README + docs/) -- [x] **Аудит эндпоинтов** — все 33 endpoint протестированы ✅ -- [x] **Автогенерация документации** — pydoc-markdown ✅ -- [x] **Docstrings** — 100% покрытие ✅ -- [x] **Добавить `/api/validation/checktext` (валидация текста)** ✅ -- [ ] Добавить `/kworks` endpoint (альтернатива каталогу) -- [ ] Тесты integration (шаблон готов, нужны реальные credentials) -- [ ] CI/CD pipeline (Gitea Actions) +- [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 --- ## 🔨 Сейчас в работе -**Проект завершён!** ✅ - -**Что можно сделать потом:** -- Добавить `/kworks` endpoint (когда будет модель ответа) -- Настроить публикацию на internal PyPI -- Интеграция с kwork-parser +**Проект готов!** Ожидает настройки GITEA_TOKEN для автоматических релизов. --- ## 📝 Заметки -### Автогенерация документации (2026-03-23 04:35) +### 🏗️ Архитектура -**Инструмент:** MkDocs + mkdocstrings + Material theme +**Стек:** +- Python 3.10+ (тесты на 3.12) +- UV (package manager) +- httpx[http2] (async client) +- pydantic v2 (модели) +- pytest + respx (тесты) +- ruff (lint + format) **Структура:** ``` -docs/ -├── index.md # Quick start guide -├── api-reference.md # API overview -├── api/ -│ ├── client.md # KworkClient documentation -│ ├── models.md # Pydantic models -│ └── errors.md # Exception classes -└── examples.md # Usage examples - -site/ # Generated HTML (не коммитим) -├── index.html -├── api-reference/ -└── ... +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.yml` — MkDocs конфигурация -- Pre-commit hook — автогенерация HTML при коммите +### 📚 Документация -**Покрытие документацией:** -- `KworkClient` — класс, аутентификация, все методы -- `CatalogAPI` — каталог кворков -- `ProjectsAPI` — биржа проектов -- `UserAPI` — пользовательские данные -- `ReferenceAPI` — справочники -- `NotificationsAPI` — уведомления -- `client.get_*()` — настройки и предпочтения (бывший OtherAPI) -- `models.py` — все модели -- `errors.py` — все исключения +**Инструмент:** MkDocs + mkdocstrings + Material theme **Команды:** ```bash -# Сборка HTML документации -mkdocs build - -# Локальный просмотр +# Локальная разработка mkdocs serve + +# Сборка HTML (для CI) +mkdocs build ``` -### Аудит эндпоинтов (2026-03-23 03:08) +**Деплой:** Автоматически через Gitea Actions на Gitea Pages -**Из HAR дампа:** 44 эндпоинта -- **Пропущено (internal/analytics):** 9 -- **Реализовано:** 33/33 (100%) ✅ -- **Протестировано:** 33/33 (100%) ✅ +**Покрытие:** 100% docstrings (Russian language) -**Пропущенные эндпоинты (анализ):** +### 🧪 Тестирование -| Эндпоинт | Размер | Описание | Решение | -|----------|--------|----------|---------| -| `/signIn` | - | Авторизация | ✅ Реализовано в `login()` | -| `/getWebAuthToken` | - | Получение токена | ✅ Реализовано в `login()` | -| `/kworks` | 22KB | Список кворков | 🔴 Добавить | -| `/quick-faq/init` | 3.7MB | FAQ данные | ⏪ Опционально | -| `/api/validation/checktext` | - | Валидация текста | 🔴 Добавить | -| Остальные | - | Analytics/UI | ⏪ Пропустить | +**Coverage:** 92% (порог 90% для PR) -**Тесты:** -- Unit тесты: 46 passed -- Покрытие: 92% -- Файлы: `test_client.py` (13 тестов), `test_all_endpoints.py` (33 теста) +**Запуск:** +```bash +# Все тесты +uv run pytest tests/unit/ -v -**Аутентификация:** cookies + web_auth_token (2 этапа) -**Стек:** UV + httpx(http2) + pydantic v2 + structlog + mkdocstrings -**HAR дамп:** 45 эндпоинтов проанализировано +# С coverage +uv run pytest --cov=src/kwork_api --cov-report=html +``` -**Решения:** -- Rate limiting на стороне пользователя (не в библиотеке) -- Только библиотека (без CLI) -- Pydantic модели для всех ответов -- Автогенерация документации через mkdocstrings+griffe +**Артефакты:** +- 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 \ + --password \ + 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 эндпоинты — не нужны для библиотеки --- @@ -131,19 +168,21 @@ mkdocs serve ## 📅 История -- **23:24** — **v1.0 выпущен!** ✅ Все изменения запушены в Gitea -- **23:12** — Добавлен `/api/validation/checktext` endpoint ✅ - - Модели: `ValidationResponse`, `ValidationIssue` - - Метод: `client.other.validate_text()` - - Тесты: 3 новых теста (16 total) -- **03:44** — mkdocstrings+griffe настроен, документация генерируется -- **03:38** — Выбран mkdocstrings+griffe вместо pydoc-markdown -- **03:26** — Автогенерация документации настроена (pre-commit hook) -- **03:20** — Создана docs/ структура -- **03:17** — WIP.md восстановлен после rebase -- **03:14** — Анализ пропущенных эндпоинтов -- **03:08** — Аудит завершён: 33/33 endpoint протестированы (92% coverage) -- **02:48** — Все unit тесты пройдены (13/13) -- **02:35** — Завершён этап "API клиент" -- **02:20** — Завершён этап "Структура проекта" -- **02:16** — Начат проект +- **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