127e5927bc
Рефакторинг: - OtherAPI упразднён — все методы перемещены в KworkClient - Методы client.get_wants(), get_kworks_status() и др. теперь напрямую в клиенте - Удалён property client.other Документация: - MkDocs + mkdocstrings + Material theme для HTML сайта - Навигация, поиск, форматирование кода - docs/index.md — quick start guide - docs/api/*.md — API reference с автогенерацией из docstrings - Pre-commit hook для автогенерации HTML Зависимости: - Добавлены: mkdocs, mkdocs-material, mkdocstrings, mkdocstrings-python - Убран pydoc-markdown (не нужен) Команды: - mkdocs build — сборка HTML - mkdocs serve — локальный просмотр
145 lines
5.5 KiB
Markdown
145 lines
5.5 KiB
Markdown
# Work In Progress — kwork-api
|
||
|
||
## 📊 Статус
|
||
|
||
| Параметр | Значение |
|
||
|----------|----------|
|
||
| **Проект** | kwork-api |
|
||
| **Начало** | 2026-03-23 02:16 UTC |
|
||
| **Прогресс** | 98% |
|
||
| **Статус** | 🟢 В работе |
|
||
|
||
---
|
||
|
||
## 📋 План
|
||
|
||
- [x] Структура проекта (pyproject.toml, зависимости)
|
||
- [x] Модели Pydantic (20+ моделей для всех ответов API)
|
||
- [x] API клиент (KworkClient с 45 эндпоинтами)
|
||
- [x] Обработка ошибок (KworkAuthError, KworkApiError, etc.)
|
||
- [x] Тесты unit (46 тестов, 92% coverage)
|
||
- [x] Документация (README + docs/)
|
||
- [x] **Аудит эндпоинтов** — все 33 endpoint протестированы ✅
|
||
- [x] **Автогенерация документации** — pydoc-markdown ✅
|
||
- [x] **Docstrings** — 100% покрытие ✅
|
||
- [ ] Добавить `/kworks` endpoint (альтернатива каталогу)
|
||
- [ ] Добавить `/api/validation/checktext` (валидация текста)
|
||
- [ ] Тесты integration (шаблон готов, нужны реальные credentials)
|
||
- [ ] CI/CD pipeline (Gitea Actions)
|
||
- [ ] Публикация на internal PyPI
|
||
|
||
---
|
||
|
||
## 🔨 Сейчас в работе
|
||
|
||
**Текущая задача:** Добавление endpoint `/kworks` и `/api/validation/checktext`
|
||
|
||
**Следующий шаг:**
|
||
1. Реализовать `/kworks` endpoint
|
||
2. Реализовать `/api/validation/checktext` endpoint
|
||
3. CI/CD pipeline (Gitea Actions)
|
||
|
||
---
|
||
|
||
## 📝 Заметки
|
||
|
||
### Автогенерация документации (2026-03-23 04:35)
|
||
|
||
**Инструмент:** MkDocs + mkdocstrings + Material theme
|
||
|
||
**Структура:**
|
||
```
|
||
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/
|
||
└── ...
|
||
```
|
||
|
||
**Конфигурация:**
|
||
- `mkdocs.yml` — MkDocs конфигурация
|
||
- Pre-commit hook — автогенерация HTML при коммите
|
||
|
||
**Покрытие документацией:**
|
||
- `KworkClient` — класс, аутентификация, все методы
|
||
- `CatalogAPI` — каталог кворков
|
||
- `ProjectsAPI` — биржа проектов
|
||
- `UserAPI` — пользовательские данные
|
||
- `ReferenceAPI` — справочники
|
||
- `NotificationsAPI` — уведомления
|
||
- `client.get_*()` — настройки и предпочтения (бывший OtherAPI)
|
||
- `models.py` — все модели
|
||
- `errors.py` — все исключения
|
||
|
||
**Команды:**
|
||
```bash
|
||
# Сборка HTML документации
|
||
mkdocs build
|
||
|
||
# Локальный просмотр
|
||
mkdocs serve
|
||
```
|
||
|
||
### Аудит эндпоинтов (2026-03-23 03:08)
|
||
|
||
**Из HAR дампа:** 44 эндпоинта
|
||
- **Пропущено (internal/analytics):** 9
|
||
- **Реализовано:** 33/33 (100%) ✅
|
||
- **Протестировано:** 33/33 (100%) ✅
|
||
|
||
**Пропущенные эндпоинты (анализ):**
|
||
|
||
| Эндпоинт | Размер | Описание | Решение |
|
||
|----------|--------|----------|---------|
|
||
| `/signIn` | - | Авторизация | ✅ Реализовано в `login()` |
|
||
| `/getWebAuthToken` | - | Получение токена | ✅ Реализовано в `login()` |
|
||
| `/kworks` | 22KB | Список кворков | 🔴 Добавить |
|
||
| `/quick-faq/init` | 3.7MB | FAQ данные | ⏪ Опционально |
|
||
| `/api/validation/checktext` | - | Валидация текста | 🔴 Добавить |
|
||
| Остальные | - | Analytics/UI | ⏪ Пропустить |
|
||
|
||
**Тесты:**
|
||
- Unit тесты: 46 passed
|
||
- Покрытие: 92%
|
||
- Файлы: `test_client.py` (13 тестов), `test_all_endpoints.py` (33 теста)
|
||
|
||
**Аутентификация:** cookies + web_auth_token (2 этапа)
|
||
**Стек:** UV + httpx(http2) + pydantic v2 + structlog + mkdocstrings
|
||
**HAR дамп:** 45 эндпоинтов проанализировано
|
||
|
||
**Решения:**
|
||
- Rate limiting на стороне пользователя (не в библиотеке)
|
||
- Только библиотека (без CLI)
|
||
- Pydantic модели для всех ответов
|
||
- Автогенерация документации через mkdocstrings+griffe
|
||
|
||
---
|
||
|
||
## 🚧 Блокеры
|
||
|
||
Нет
|
||
|
||
---
|
||
|
||
## 📅 История
|
||
|
||
- **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** — Начат проект
|