Initial commit: проект документации YARU

2026-09-29 09:55:06 +00:00 · 2026-03-01 17:32:45 +03:00
commit 243b5caf7e
860 changed files with 13239 additions and 0 deletions
@@ -0,0 +1,130 @@
+# Backend документация
+
+## Стек технологий
+
+| Компонент | Технология | Примечание |
+|-----------|------------|------------|
+| Язык | Python 3.11+ | |
+| Фреймворк | FastAPI | Асинхронный, автодокументация |
+| База данных | PostgreSQL 15+ | Основная БД |
+| Кэш | PostgreSQL + pg_redis | Или Redis через extension |
+| Очереди | PostgreSQL + pgqueue | Или Celery + Redis |
+| ORM | SQLAlchemy 2.0 + Async | Асинхронная работа |
+
+---
+
+## Архитектура сервера
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      FastAPI App                        │
+├─────────────┬─────────────┬─────────────┬───────────────┤
+│   REST API  │ ActivityPub │   Auth API  │  Export API   │
+│  (лента,    │  (inbox,    │  (OAuth2,   │  (markdown,   │
+│  профили)   │  outbox)    │   JWT)      │   медиа)      │
+└─────────────┴─────────────┴─────────────┴───────────────┘
+                              │
+                    ┌─────────▼──────────┐
+                    │   PostgreSQL       │
+                    │  ───────────────── │
+                    │  • pg_redis (кэш)  │
+                    │  • pgqueue (очереди)│
+                    │  • pg_trgm (поиск)  │
+                    └────────────────────┘
+```
+
+---
+
+## Требования к бэкенду
+
+### 1. ActivityPub реализация
+
+- [ ] **Inbox** — приём активностей от других серверов
+- [ ] **Outbox** — отправка активностей подписчикам
+- [ ] **WebFinger** — обнаружение пользователей по @username@domain
+- [ ] **Actor** — профиль пользователя в формате ActivityPub
+- [ ] **Follow/Unfollow** — подписки между серверами
+- [ ] **Create/Update/Delete** — посты и их редактирование
+- [ ] **Like/Announce** — лайки и репосты
+- [ ] **Mastodon совместимость** — тестирование с mastodon.social
+
+### 2. REST API
+
+- [ ] `/api/v1/accounts` — управление профилем
+- [ ] `/api/v1/statuses` — создание/чтение постов
+- [ ] `/api/v1/timelines/home` — домашняя лента
+- [ ] `/api/v1/timelines/public` — публичная лента
+- [ ] `/api/v1/follows` — подписки
+- [ ] `/api/v1/karma` — карма пользователя
+
+### 3. База данных (PostgreSQL)
+
+#### Основные таблицы:
+- `users` — пользователи (id, username, domain, display_name, bio, karma)
+- `posts` — посты (id, user_id, content, content_type, created_at)
+- `follows` — подписки (follower_id, following_id, created_at)
+- `likes` — лайки (user_id, post_id, created_at)
+- `media` — медиафайлы (id, user_id, filename, mime_type, size)
+- `activities` — ActivityPub активности (id, type, actor, object, timestamp)
+
+#### PostgreSQL расширения:
+- `pg_trgm` — полнотекстовый поиск по постам
+- `pg_redis` — кэширование лент
+- `pgqueue` — фоновые задачи (отправка активностей)
+
+### 4. Экспорт контента
+
+**Требование**: Пользователь может экспортировать весь свой контент в виде:
+
+```
+export_username_2026-03-01/
+├── profile.md              # Информация о профиле
+├── posts/
+│   ├── 2026-03-01_post-123.md
+│   ├── 2026-03-02_post-124.md
+│   └── ...
+├── media/
+│   ├── image-001.png
+│   ├── image-002.jpg
+│   └── ...
+└── manifest.json           # Структура экспорта
+```
+
+- [ ] Формат постов — Markdown с frontmatter (дата, теги, карма)
+- [ ] Медиа — оригинальные файлы с переименованием
+- [ ] Manifest — JSON со списком всех файлов и метаданными
+- [ ] API endpoint: `GET /api/v1/export/@username`
+
+### 5. Аутентификация
+
+- [ ] OAuth2 + JWT токены
+- [ ] Поддержка Application Passwords для клиентов
+- [ ] Сессии с возможностью отзыва
+
+### 6. Карма
+
+- [ ] Механизм начисления/списания кармы
+- [ ] Защита от накрутки (лимиты, анти-спам)
+- [ ] История изменений кармы
+
+---
+
+## План разработки бэкенда
+
+1. [ ] Настройка проекта FastAPI + SQLAlchemy
+2. [ ] Модели базы данных (users, posts, follows, likes)
+3. [ ] REST API (CRUD для постов, профили)
+4. [ ] ActivityPub базовая реализация (Actor, Outbox)
+5. [ ] ActivityPub полная реализация (Inbox, Federation)
+6. [ ] Экспорт контента (Markdown + медиа)
+7. [ ] Система кармы
+8. [ ] Тестирование совместимости с Mastodon
+
+---
+
+## Вопросы для обсуждения
+
+- [ ] Нужно ли поддерживать совместимость с другими Fediverse-серверами (Pleroma, Pixelfed)?
+- [ ] Требуется ли rate limiting на API? Какие лимиты?
+- [ ] Как хранить медиа: локально, S3, или оба варианта?
+- [ ] Нужна ли модерация контента (админ-панель)?