Document platform architecture and Telegram proxy local setup.

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>
2026-08-15 22:57:07 +03:00
parent 5f8ed25759
commit 6dff3c1c3d
11 changed files with 1046 additions and 12 deletions
@@ -0,0 +1,91 @@
+# 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`.