gitrusprusandCursor
6dff3c1c3d
Add developer docs for CA/CP/PI flows and wire cp-workers to the host SOCKS proxy so local Telegram auth and parsing work reliably. Co-authored-by: Cursor <cursoragent@cursor.com>
92 lines
2.8 KiB
Markdown
92 lines
2.8 KiB
Markdown
# Distribution API (ПИ)
|
||
|
||
**ПИ** — не отдельный Docker-сервис, а внешний HTTP-срез поверх данных ЦА.
|
||
|
||
Общий контекст: [docs/architecture-overview.md](../../docs/architecture-overview.md).
|
||
|
||
---
|
||
|
||
## Общими чертами
|
||
|
||
1. В UI «ПИ» (`/consumers`) создаётся подписчик.
|
||
2. Ему выдаётся API-ключ (в БД хранится только SHA-256 hash).
|
||
3. Клиент читает события:
|
||
|
||
```http
|
||
GET /api/v1/events
|
||
Authorization: Bearer <api_key>
|
||
```
|
||
|
||
4. ЦА отдаёт события с учётом фильтров consumer (регионы, темы, дата).
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Client[External system]
|
||
V1[GET /api/v1/events]
|
||
Cons[Consumer + Filter]
|
||
Events[(events)]
|
||
|
||
Client -->|Bearer key| V1
|
||
V1 --> Cons
|
||
Cons --> Events
|
||
```
|
||
|
||
---
|
||
|
||
## Подробнее
|
||
|
||
### Код
|
||
|
||
| Часть | Путь |
|
||
|-------|------|
|
||
| Роут | `centers/analytics/api/app/routers/v1.py` |
|
||
| Модели | `Consumer`, `ConsumerFilter` в `models.py` |
|
||
| Фильтрация | `services/filtering.py` |
|
||
| Admin CRUD | `routers/admin.py` — `/admin/consumers`, `…/rotate-key` |
|
||
| UI | `frontend/src/views/ConsumersView.vue` |
|
||
| Seed | `seed.py` — consumer `test-pi` из `TEST_PI_API_KEY` |
|
||
|
||
### Аутентификация
|
||
|
||
- Заголовок: `Authorization: Bearer <plain_api_key>`.
|
||
- Сравнение с `consumers.api_key_hash` (SHA-256).
|
||
- Неактивный consumer → отказ.
|
||
|
||
### Фильтры подписчика
|
||
|
||
Типичные ограничения (через `ConsumerFilter`):
|
||
|
||
- список регионов;
|
||
- список тем;
|
||
- `date_from` (нижняя граница даты события).
|
||
|
||
Точный набор полей — в модели/схемах admin API; при изменении фильтров обновляйте UI consumers и `filtering.py`.
|
||
|
||
### Admin операции
|
||
|
||
| Метод | Путь | Действие |
|
||
|-------|------|----------|
|
||
| GET | `/admin/consumers` | Список |
|
||
| POST | `/admin/consumers` | Создать (+ ключ в ответе один раз) |
|
||
| PATCH | `/admin/consumers/{id}` | Обновить |
|
||
| POST | `/admin/consumers/{id}/rotate-key` | Новый ключ |
|
||
|
||
### Локальный тест
|
||
|
||
После `docker compose up` (если не меняли seed):
|
||
|
||
```bash
|
||
curl -s -H "Authorization: Bearer test-pi-api-key-change-me" \
|
||
"http://localhost:8080/api/v1/events" | head
|
||
```
|
||
|
||
В проде обязательно смените `TEST_PI_API_KEY` и ротируйте ключи.
|
||
|
||
### Что ПИ не делает
|
||
|
||
- не пишет в БД;
|
||
- не ставит parse jobs;
|
||
- не ходит в Redis / ЦП.
|
||
|
||
Только чтение уже ingest'нутых событий через контракт `/api/v1`.
|