docs: update WIP.md with current state
- 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
This commit is contained in:
root
parent
455bbd166d
commit
7b8de4af2d
229
WIP.md
229
WIP.md
@ -5,121 +5,158 @@
|
|||||||
| Параметр | Значение |
|
| Параметр | Значение |
|
||||||
|----------|----------|
|
|----------|----------|
|
||||||
| **Проект** | kwork-api |
|
| **Проект** | kwork-api |
|
||||||
| **Начало** | 2026-03-23 02:16 UTC |
|
| **Начало** | 2026-03-23 |
|
||||||
| **Прогресс** | 100% |
|
| **Прогресс** | 100% |
|
||||||
| **Статус** | ✅ Готово |
|
| **Статус** | ✅ Готово к v1.0 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📋 План
|
## 📋 План
|
||||||
|
|
||||||
- [x] Структура проекта (pyproject.toml, зависимости)
|
- [x] Структура проекта (pyproject.toml, UV)
|
||||||
- [x] Модели Pydantic (20+ моделей для всех ответов API)
|
- [x] Модели Pydantic (20+ моделей)
|
||||||
- [x] API клиент (KworkClient с 45 эндпоинтами)
|
- [x] API клиент (45+ эндпоинтов)
|
||||||
- [x] Обработка ошибок (KworkAuthError, KworkApiError, etc.)
|
- [x] Обработка ошибок (7 типов исключений)
|
||||||
- [x] Тесты unit (49 тестов, 92% coverage)
|
- [x] Тесты unit (46 тестов, 92% coverage)
|
||||||
- [x] Документация (README + docs/)
|
- [x] Документация (MkDocs + mkdocstrings)
|
||||||
- [x] **Аудит эндпоинтов** — все 33 endpoint протестированы ✅
|
- [x] CI/CD pipeline (Gitea Actions)
|
||||||
- [x] **Автогенерация документации** — pydoc-markdown ✅
|
- [x] Semantic release (авто-версионирование)
|
||||||
- [x] **Docstrings** — 100% покрытие ✅
|
- [ ] `/kworks` endpoint (требует исследования модели)
|
||||||
- [x] **Добавить `/api/validation/checktext` (валидация текста)** ✅
|
|
||||||
- [ ] Добавить `/kworks` endpoint (альтернатива каталогу)
|
|
||||||
- [ ] Тесты integration (шаблон готов, нужны реальные credentials)
|
|
||||||
- [ ] CI/CD pipeline (Gitea Actions)
|
|
||||||
- [ ] Публикация на internal PyPI
|
- [ ] Публикация на internal PyPI
|
||||||
|
- [ ] Интеграция с kwork-parser
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔨 Сейчас в работе
|
## 🔨 Сейчас в работе
|
||||||
|
|
||||||
**Проект завершён!** ✅
|
**Проект готов!** Ожидает настройки GITEA_TOKEN для автоматических релизов.
|
||||||
|
|
||||||
**Что можно сделать потом:**
|
|
||||||
- Добавить `/kworks` endpoint (когда будет модель ответа)
|
|
||||||
- Настроить публикацию на internal PyPI
|
|
||||||
- Интеграция с kwork-parser
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📝 Заметки
|
## 📝 Заметки
|
||||||
|
|
||||||
### Автогенерация документации (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/
|
kwork-api/
|
||||||
├── index.md # Quick start guide
|
├── src/kwork_api/
|
||||||
├── api-reference.md # API overview
|
│ ├── __init__.py # __version__
|
||||||
├── api/
|
│ ├── client.py # KworkClient (45+ методов)
|
||||||
│ ├── client.md # KworkClient documentation
|
│ ├── models.py # 20+ Pydantic моделей
|
||||||
│ ├── models.md # Pydantic models
|
│ └── errors.py # 7 типов исключений
|
||||||
│ └── errors.md # Exception classes
|
├── tests/
|
||||||
└── examples.md # Usage examples
|
│ ├── unit/ # Unit тесты (mock)
|
||||||
|
│ └── integration/ # Integration тесты (требуют credentials)
|
||||||
site/ # Generated HTML (не коммитим)
|
├── docs/ # Исходники документации
|
||||||
├── index.html
|
├── .gitea/workflows/ # CI/CD pipeline
|
||||||
├── api-reference/
|
└── pyproject.toml # Конфигурация проекта
|
||||||
└── ...
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Конфигурация:**
|
### 📚 Документация
|
||||||
- `mkdocs.yml` — MkDocs конфигурация
|
|
||||||
- Pre-commit hook — автогенерация HTML при коммите
|
|
||||||
|
|
||||||
**Покрытие документацией:**
|
**Инструмент:** MkDocs + mkdocstrings + Material theme
|
||||||
- `KworkClient` — класс, аутентификация, все методы
|
|
||||||
- `CatalogAPI` — каталог кворков
|
|
||||||
- `ProjectsAPI` — биржа проектов
|
|
||||||
- `UserAPI` — пользовательские данные
|
|
||||||
- `ReferenceAPI` — справочники
|
|
||||||
- `NotificationsAPI` — уведомления
|
|
||||||
- `client.get_*()` — настройки и предпочтения (бывший OtherAPI)
|
|
||||||
- `models.py` — все модели
|
|
||||||
- `errors.py` — все исключения
|
|
||||||
|
|
||||||
**Команды:**
|
**Команды:**
|
||||||
```bash
|
```bash
|
||||||
# Сборка HTML документации
|
# Локальная разработка
|
||||||
mkdocs build
|
|
||||||
|
|
||||||
# Локальный просмотр
|
|
||||||
mkdocs serve
|
mkdocs serve
|
||||||
|
|
||||||
|
# Сборка HTML (для CI)
|
||||||
|
mkdocs build
|
||||||
```
|
```
|
||||||
|
|
||||||
### Аудит эндпоинтов (2026-03-23 03:08)
|
**Деплой:** Автоматически через Gitea Actions на Gitea Pages
|
||||||
|
|
||||||
**Из HAR дампа:** 44 эндпоинта
|
**Покрытие:** 100% docstrings (Russian language)
|
||||||
- **Пропущено (internal/analytics):** 9
|
|
||||||
- **Реализовано:** 33/33 (100%) ✅
|
|
||||||
- **Протестировано:** 33/33 (100%) ✅
|
|
||||||
|
|
||||||
**Пропущенные эндпоинты (анализ):**
|
### 🧪 Тестирование
|
||||||
|
|
||||||
| Эндпоинт | Размер | Описание | Решение |
|
**Coverage:** 92% (порог 90% для PR)
|
||||||
|----------|--------|----------|---------|
|
|
||||||
| `/signIn` | - | Авторизация | ✅ Реализовано в `login()` |
|
|
||||||
| `/getWebAuthToken` | - | Получение токена | ✅ Реализовано в `login()` |
|
|
||||||
| `/kworks` | 22KB | Список кворков | 🔴 Добавить |
|
|
||||||
| `/quick-faq/init` | 3.7MB | FAQ данные | ⏪ Опционально |
|
|
||||||
| `/api/validation/checktext` | - | Валидация текста | 🔴 Добавить |
|
|
||||||
| Остальные | - | Analytics/UI | ⏪ Пропустить |
|
|
||||||
|
|
||||||
**Тесты:**
|
**Запуск:**
|
||||||
- Unit тесты: 46 passed
|
```bash
|
||||||
- Покрытие: 92%
|
# Все тесты
|
||||||
- Файлы: `test_client.py` (13 тестов), `test_all_endpoints.py` (33 теста)
|
uv run pytest tests/unit/ -v
|
||||||
|
|
||||||
**Аутентификация:** cookies + web_auth_token (2 этапа)
|
# С coverage
|
||||||
**Стек:** UV + httpx(http2) + pydantic v2 + structlog + mkdocstrings
|
uv run pytest --cov=src/kwork_api --cov-report=html
|
||||||
**HAR дамп:** 45 эндпоинтов проанализировано
|
```
|
||||||
|
|
||||||
**Решения:**
|
**Артефакты:**
|
||||||
- Rate limiting на стороне пользователя (не в библиотеке)
|
- HTML отчёт pytest (test-results/report.html)
|
||||||
- Только библиотека (без CLI)
|
- HTML отчёт coverage (coverage-html/index.html)
|
||||||
- Pydantic модели для всех ответов
|
|
||||||
- Автогенерация документации через mkdocstrings+griffe
|
### 🚀 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 эндпоинты — не нужны для библиотеки
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -131,19 +168,21 @@ mkdocs serve
|
|||||||
|
|
||||||
## 📅 История
|
## 📅 История
|
||||||
|
|
||||||
- **23:24** — **v1.0 выпущен!** ✅ Все изменения запушены в Gitea
|
- **2026-03-29** — Репозиторий очищен от артефактов (site/, .coverage)
|
||||||
- **23:12** — Добавлен `/api/validation/checktext` endpoint ✅
|
- **2026-03-29** — Настроен semantic-release для авто-версионирования
|
||||||
- Модели: `ValidationResponse`, `ValidationIssue`
|
- **2026-03-29** — CI/CD pipeline готов (PR checks + release)
|
||||||
- Метод: `client.other.validate_text()`
|
- **2026-03-29** — История переписана (1 чистый коммит)
|
||||||
- Тесты: 3 новых теста (16 total)
|
- **2026-03-23** — Initial release (45+ endpoints, 92% coverage)
|
||||||
- **03:44** — mkdocstrings+griffe настроен, документация генерируется
|
|
||||||
- **03:38** — Выбран mkdocstrings+griffe вместо pydoc-markdown
|
---
|
||||||
- **03:26** — Автогенерация документации настроена (pre-commit hook)
|
|
||||||
- **03:20** — Создана docs/ структура
|
## 🔐 Секреты (Gitea)
|
||||||
- **03:17** — WIP.md восстановлен после rebase
|
|
||||||
- **03:14** — Анализ пропущенных эндпоинтов
|
**Требуется:** `GITEA_TOKEN` в repository secrets
|
||||||
- **03:08** — Аудит завершён: 33/33 endpoint протестированы (92% coverage)
|
|
||||||
- **02:48** — Все unit тесты пройдены (13/13)
|
**Права:**
|
||||||
- **02:35** — Завершён этап "API клиент"
|
- `write:repository` (push tags, create releases)
|
||||||
- **02:20** — Завершён этап "Структура проекта"
|
- `write:package` (publish to Gitea Packages)
|
||||||
- **02:16** — Начат проект
|
|
||||||
|
**Где настроить:**
|
||||||
|
https://git.much-data.ru/much-data/kwork-api/settings/secrets
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user