mirror of
https://github.com/Govor-team/Govor.git
synced 2026-11-18 05:15:06 +00:00
docs: split messaging and privileges guides
Organize reply/forward and friendship guidance into focused endpoint docs, add Govor+ privilege, profile-tag, and realtime guides, and document migrations and verification results.
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
# Привилегии и Govor+
|
||||
|
||||
Govor+ — назначаемый администратором специальный статус пользователя. Платёжная подписка пока не требуется. Права хранятся в БД и проверяются при каждой операции: выдача и отзыв работают во время работы API, без перезапуска и обновления JWT. Govor+ не выдаёт административных ролей.
|
||||
|
||||
## Набор прав
|
||||
|
||||
| Значение privileges | Права |
|
||||
| ------------------- | ------------------------------------------------------- |
|
||||
| 0 | Без специальных прав |
|
||||
| 1 | Govor+: официальный статус и настройка профильного тега |
|
||||
| 2 | Настройка профильного тега без статуса Govor+ |
|
||||
| 3 | Оба явно назначенных бита |
|
||||
|
||||
Это битовая маска: GovorPlus = 1, CustomProfileTag = 2. Неизвестные биты сервер отклоняет. Новые возможности добавляются отдельными битами с проверкой в соответствующем сервисе.
|
||||
|
||||
## Выдача и отзыв
|
||||
|
||||
`PUT /api/admin/users/{userId}/privileges` требует access JWT с ролью Admin. Запрос заменяет весь набор прав пользователя.
|
||||
|
||||
Выдать Govor+:
|
||||
|
||||
```json
|
||||
{ "privileges": 1 }
|
||||
```
|
||||
|
||||
Отозвать все специальные права:
|
||||
|
||||
```json
|
||||
{ "privileges": 0 }
|
||||
```
|
||||
|
||||
Успех — 200 с UserBenefitsView. Ошибки: 400 — неизвестные биты; 404 — пользователь не найден; 409 — конкурентное первое создание прав, перечитайте состояние и повторите запрос. Без JWT — 401, без роли Admin — 403.
|
||||
|
||||
## Чтение состояния
|
||||
|
||||
`GET /api/profile/{userId}/benefits` требует действующего access JWT. Тот же объект benefits входит в `GET /api/profile/download/me` и `GET /api/profile/download/{id}`.
|
||||
|
||||
| Поле | Назначение |
|
||||
| ---------------------- | ------------------------------------------------------- |
|
||||
| privileges | Явно назначенная битовая маска |
|
||||
| isGovorPlus | Наличие официального статуса Govor+ |
|
||||
| canCustomizeProfileTag | Право изменять оформление тега, включая право от Govor+ |
|
||||
| tag | Текущее доступное оформление или null |
|
||||
| revision | Монотонная ревизия состояния пользователя |
|
||||
|
||||
Официальный статус определяйте по isGovorPlus, а доступность редактора — по canCustomizeProfileTag. Текст тега произволен и не доказывает наличие статуса.
|
||||
|
||||
Обычный пользователь получает tag: null. У Govor+ без собственного оформления отображается стандартный тег. При отзыве всех прав настройки сохранённое оформление скрывается и перестаёт редактироваться; при повторной выдаче восстанавливается.
|
||||
|
||||
## Разделы
|
||||
|
||||
* [Профильные теги: HTTP-контракт и оформление](profile-tags.md).
|
||||
* [Обновления статуса и тега: SignalR и ревизии](realtime.md).
|
||||
|
||||
## Установка
|
||||
|
||||
Контракт реализован в дополнениях от 31.10.2026. Перед запуском версии примените миграции `MessagingAndUserBenefits` и `UserBenefitsRevision`; существующим пользователям права автоматически не назначаются. [Порядок обновления сервера](../operations.md).
|
||||
@@ -0,0 +1,54 @@
|
||||
# Профильные теги
|
||||
|
||||
У каждого пользователя один настраиваемый профильный тег. Изменение доступно при Govor+ или отдельном праве CustomProfileTag. [Назначение и проверка прав](README.md).
|
||||
|
||||
## Изменение и сброс
|
||||
|
||||
`PUT /api/profile/tag` заменяет оформление текущего пользователя. Текущий пользователь берётся из access JWT. Передайте непосредственно объект оформления:
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "Govor+",
|
||||
"textColor": "#FFFFFF",
|
||||
"textGradientEndColor": null,
|
||||
"backgroundColor": "#2455DD",
|
||||
"gradientEndColor": null,
|
||||
"gradientAngle": 90,
|
||||
"borderColor": "#6688FF",
|
||||
"borderGradientEndColor": null,
|
||||
"borderWidth": 1,
|
||||
"shadowColor": "#00000080",
|
||||
"shadowBlur": 4,
|
||||
"shadowOffsetX": 0,
|
||||
"shadowOffsetY": 1,
|
||||
"fontFamily": "Inter",
|
||||
"fontWeight": 600,
|
||||
"fontSize": 12
|
||||
}
|
||||
```
|
||||
|
||||
Пропущенные поля получают стандартные значения. `DELETE /api/profile/tag` сбрасывает оформление к стандартному. Оба endpoint возвращают 200 с актуальным UserBenefitsView. Без права настройки — 403; некорректное оформление — 400 без изменения сохранённого тега.
|
||||
|
||||
## Параметры оформления
|
||||
|
||||
| Параметр | Допустимое значение |
|
||||
| ------------------------------------------------ | --------------------------------------------------------------------------- |
|
||||
| `text` | 1–32 UTF-16 символа, не пробельная строка, без управляющих символов |
|
||||
| Цвета | `#RRGGBB` или `#RRGGBBAA` |
|
||||
| `gradientEndColor` | Конечный цвет градиента фона; `null` — сплошной фон |
|
||||
| `textGradientEndColor`, `borderGradientEndColor` | Конечные цвета градиентов текста и обводки; `null` — сплошной цвет |
|
||||
| `gradientAngle` | 0–360°, общий угол линейных градиентов |
|
||||
| `borderWidth` | 0–4 |
|
||||
| `shadowBlur` | 0–20 |
|
||||
| `shadowOffsetX`, `shadowOffsetY` | −10–10 |
|
||||
| `fontFamily` | `Inter`, `Roboto`, `Arial`, `Noto Sans`, `serif`, `sans-serif`, `monospace` |
|
||||
| `fontWeight` | 100–900 с шагом 100 |
|
||||
| `fontSize` | 10–24 |
|
||||
|
||||
Размеры заданы в логических пикселях. Угол соответствует CSS linear-gradient: 0° вверх, 90° вправо. Клиент обеспечивает наличие выбранного шрифта или безопасный fallback. Тег — структурированные данные: текст рендерится как plain text, а не HTML; URL шрифтов, произвольный CSS и внешние ресурсы не принимаются. Некорректное оформление даёт `400` и не изменяет сохранённый тег.
|
||||
|
||||
При отзыве прав сохранённое оформление остаётся в БД, но скрывается в API и не может редактироваться. При повторной выдаче права оформление восстанавливается.
|
||||
|
||||
## Отображение
|
||||
|
||||
Официальный статус определяйте по benefits.isGovorPlus, а не по тексту тега. Текущий стиль доступен в benefits.tag при чтении профиля или `GET /api/profile/{userId}/benefits`. После изменения или сброса сервер отправляет UserBenefitsUpdated в /hubs/profiles.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Обновления статуса и тега
|
||||
|
||||
Подключите каждый клиент к `/hubs/profiles` и слушайте `UserBenefitsUpdated`:
|
||||
|
||||
```javascript
|
||||
connection.on("UserBenefitsUpdated", ({ userId, benefits }) => {
|
||||
const old = profileBenefits.get(userId);
|
||||
if (!old || benefits.revision > old.revision) {
|
||||
profileBenefits.set(userId, benefits);
|
||||
refreshVisibleUserTags(userId);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
Событие содержит полный объект, включая `revision`, и отправляется **всем** подключённым авторизованным клиентам этого хаба, включая владельца, после фиксации выдачи/отзыва прав, изменения или сброса тега. Дружба или подписка на конкретный профиль не требуется. Статус и тег — публичные данные для авторизованных пользователей. Обновляйте общий кеш профилей и все места отображения пользователя: чат, список участников, друзей и открытый профиль. HTTP-ответ содержит тот же формат.
|
||||
|
||||
Ревизия монотонно увеличивается на пользователя; игнорируйте события и HTTP-снимки с меньшей или равной ревизией. Это защищает от изменения порядка доставки при конкурентных запросах. Сначала зарегистрируйте обработчик, подключитесь, затем загрузите HTTP-снимки, также сравнивая ревизии.
|
||||
|
||||
SignalR не хранит историю событий: после восстановления соединения перечитайте видимые профили/benefits через HTTP. При сбое доставки сохранённый HTTP-запрос остаётся успешным, ошибка пишется в серверный лог; снимок в БД является источником истины. Перезапуск API для выдачи статуса или изменения оформления не нужен. При запуске нескольких экземпляров API необходим общий SignalR backplane/service для доставки между экземплярами; текущая конфигурация использует стандартный in-process SignalR.
|
||||
|
||||
## Формат события
|
||||
|
||||
Имя события: `UserBenefitsUpdated`. Payload — `{ userId, benefits }`, где benefits содержит privileges, isGovorPlus, canCustomizeProfileTag, tag и revision. Например, отзыв всех прав:
|
||||
|
||||
```json
|
||||
{
|
||||
"userId": "<user-id>",
|
||||
"benefits": {
|
||||
"privileges": 0,
|
||||
"isGovorPlus": false,
|
||||
"canCustomizeProfileTag": false,
|
||||
"tag": null,
|
||||
"revision": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Операции записи выполняются через HTTP. Команд SetTag или SetPrivileges на ProfileHub нет. [Модель привилегий](README.md).
|
||||
Reference in New Issue
Block a user