7b8de4af2d
- Remove outdated pydoc-markdown references - Add CI/CD pipeline documentation - Add semantic-release workflow description - Add current architecture and stack - Add testing and coverage info - Add deployment instructions - Clean up history section
189 lines
5.4 KiB
Markdown
189 lines
5.4 KiB
Markdown
# 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
|