update

2026-06-25 08:31:36 +03:00
parent 71b270fcb3
commit 933f7fb9e1
22 changed files with 1871 additions and 620 deletions
--- a/apps/docs/Dockerfile
+++ b/apps/docs/Dockerfile
@@ -1,5 +1,3 @@
-# syntax=docker/dockerfile:1.4
-
 FROM node:24-alpine

 WORKDIR /app
--- a/apps/docs/lib/api-endpoints.ts
+++ b/apps/docs/lib/api-endpoints.ts
@@ -46,7 +46,26 @@ export const apiReference: ApiTagGroup[] = [
      { method: 'PATCH', path: '/profile/users/{userId}/avatar', summary: 'Обновить аватар', auth: true },
      { method: 'PATCH', path: '/profile/users/{userId}/contacts', summary: 'Обновить контакты', auth: true },
      { method: 'POST', path: '/profile/users/{userId}/password', summary: 'Установить пароль', auth: true },
-      { method: 'POST', path: '/profile/users/{userId}/self-delete', summary: 'Удалить свой профиль', auth: true }
+      {
+        method: 'POST',
+        path: '/profile/users/{userId}/self-delete',
+        summary: 'Запланировать удаление профиля',
+        description: 'Не удаляет аккаунт сразу. Запускает период ожидания ACCOUNT_DELETE_GRACE_DAYS (по умолчанию 30 дней).',
+        auth: true
+      },
+      {
+        method: 'POST',
+        path: '/profile/users/{userId}/self-delete/cancel',
+        summary: 'Отменить запланированное удаление профиля',
+        auth: true
+      },
+      {
+        method: 'GET',
+        path: '/profile/users/{userId}/self-delete/status',
+        summary: 'Статус запланированного удаления профиля',
+        description: 'Возвращает pending, deletionRequestedAt, effectiveAt и graceDays.',
+        auth: true
+      }
    ]
  },
  {
@@ -92,7 +111,28 @@ export const apiReference: ApiTagGroup[] = [
    endpoints: [
      { method: 'POST', path: '/family/groups', summary: 'Создать семейную группу', auth: true },
      { method: 'GET', path: '/family/users/{userId}/groups', summary: 'Список семей пользователя', auth: true },
-      { method: 'POST', path: '/family/groups/{groupId}/invites', summary: 'Пригласить участника', auth: true }
+      { method: 'GET', path: '/family/groups/{groupId}', summary: 'Получить семейную группу', auth: true },
+      { method: 'PATCH', path: '/family/groups/{groupId}', summary: 'Обновить семейную группу (название)', auth: true },
+      {
+        method: 'DELETE',
+        path: '/family/groups/{groupId}',
+        summary: 'Удалить семейную группу',
+        description: 'Только создатель семьи. Удаляет всех участников, приглашения, чаты, сообщения и медиа семьи.',
+        auth: true
+      },
+      { method: 'POST', path: '/family/groups/{groupId}/members', summary: 'Добавить участника', auth: true },
+      {
+        method: 'DELETE',
+        path: '/family/members/{memberId}',
+        summary: 'Исключить участника или выйти из семьи',
+        description: 'Создатель может удалить участника; участник может удалить себя («Выйти»). Владельца семьи удалить нельзя.',
+        auth: true
+      },
+      { method: 'POST', path: '/family/groups/{groupId}/invites', summary: 'Пригласить участника', auth: true },
+      { method: 'GET', path: '/family/groups/{groupId}/invite-search', summary: 'Поиск пользователей для приглашения', auth: true },
+      { method: 'GET', path: '/family/invites', summary: 'Входящие приглашения', auth: true },
+      { method: 'POST', path: '/family/invites/{inviteId}/respond', summary: 'Принять или отклонить приглашение', auth: true },
+      { method: 'GET', path: '/family/groups/{groupId}/presence', summary: 'Онлайн-статус участников семьи', auth: true }
    ]
  },
  {
--- a/apps/docs/lib/docs-pages.ts
+++ b/apps/docs/lib/docs-pages.ts
@@ -838,8 +838,8 @@ curl -X POST http://localhost:3000/auth/otp/verify \\
  },
  {
    slug: 'sessions',
-    title: 'Сессии и PIN',
-    description: 'Управление устройствами, PIN-блокировка и отзыв сессий.',
+    title: 'Сессии, PIN и удаление аккаунта',
+    description: 'Управление устройствами, PIN-блокировка, отзыв сессий и отложенное удаление профиля.',
    sections: [
      {
        id: 'totp',
@@ -866,6 +866,46 @@ curl -X POST http://localhost:3000/auth/otp/verify \\
          {
            type: 'paragraph',
            text: 'PIN хранится как bcrypt hash. Таймаут блокировки читается из SystemSetting PIN_LOCK_TIMEOUT_MINUTES — значение не захардкожено во frontend.'
+          },
+          {
+            type: 'list',
+            items: [
+              'PIN_DELETE_GRACE_MINUTES — задержка перед окончательным удалением PIN после запроса',
+              'PIN_REQUIRE_ON_DELETE — требовать текущий PIN при запросе удаления защиты'
+            ]
+          }
+        ]
+      },
+      {
+        id: 'account-deletion',
+        title: 'Удаление аккаунта',
+        blocks: [
+          {
+            type: 'paragraph',
+            text: 'Пользователь может запланировать удаление профиля в личном кабинете: раздел «Данные» (/data) → «Удалить профиль». Аккаунт не удаляется мгновенно — начинается период ожидания, настраиваемый администратором.'
+          },
+          {
+            type: 'table',
+            headers: ['Ключ SystemSetting', 'Описание', 'По умолчанию'],
+            rows: [
+              ['ACCOUNT_DELETE_GRACE_DAYS', 'Через сколько дней после запроса окончательно удалить аккаунт', '30']
+            ]
+          },
+          {
+            type: 'list',
+            items: [
+              'POST /profile/users/{userId}/self-delete — запланировать удаление (только свой профиль)',
+              'GET /profile/users/{userId}/self-delete/status — дата окончательного удаления и статус pending',
+              'POST /profile/users/{userId}/self-delete/cancel — отменить запрос до истечения срока',
+              'До истечения срока пользователь может входить и пользоваться сервисом как обычно',
+              'На странице /data отображается предупреждение с датой удаления и кнопкой отмены'
+            ]
+          },
+          {
+            type: 'callout',
+            variant: 'warning',
+            title: 'Что происходит при финализации',
+            text: 'Фоновый планировщик sso-core (каждые 5 минут) находит аккаунты с истёкшим сроком ожидания и выполняет soft-delete: анонимизация email/телефона/username, отзыв сессий, снятие ролей. Семьи, где пользователь — создатель, удаляются полностью (участники, чаты, медиа). Из остальных семей пользователь исключается.'
          }
        ]
      },
@@ -888,7 +928,7 @@ curl -X POST http://localhost:3000/auth/otp/verify \\
  {
    slug: 'family-chat',
    title: 'Семья и чат',
-    description: 'Семейные группы, приглашения, чат и realtime через WebSocket.',
+    description: 'Семейные группы, приглашения, чат, удаление семьи и realtime через WebSocket.',
    sections: [
      {
        id: 'family',
@@ -896,7 +936,61 @@ curl -X POST http://localhost:3000/auth/otp/verify \\
        blocks: [
          {
            type: 'paragraph',
-            text: 'Пользователь создаёт семью, приглашает участников по email/телефону/логину. Лимиты (max family members) берутся из SystemSetting.'
+            text: 'Пользователь создаёт семью, приглашает участников по email/телефону/логину или через поиск в интерфейсе. Лимит участников задаётся в SystemSetting MAX_FAMILY_MEMBERS (по умолчанию 6). При создании семьи автоматически создаётся общий чат «Общий чат».'
+          },
+          {
+            type: 'list',
+            items: [
+              'POST /family/groups — создать семью',
+              'GET /family/users/{userId}/groups — список семей пользователя',
+              'PATCH /family/groups/{groupId} — переименовать (только участники, название — создатель)',
+              'POST /family/groups/{groupId}/invites — отправить приглашение',
+              'GET /family/groups/{groupId}/invite-search?q=... — поиск пользователей для приглашения'
+            ]
+          }
+        ]
+      },
+      {
+        id: 'family-leave',
+        title: 'Выход и исключение участников',
+        blocks: [
+          {
+            type: 'paragraph',
+            text: 'Участник может выйти из семьи самостоятельно; создатель семьи может исключить любого участника, кроме себя. При выходе или исключении пользователь удаляется из всех чатов этой семьи.'
+          },
+          {
+            type: 'list',
+            items: [
+              'DELETE /family/members/{memberId} — выход (если memberId свой) или исключение (если запрос от создателя семьи)',
+              'Создателя семьи (role: owner) удалить через этот endpoint нельзя — только удалить всю семью целиком'
+            ]
+          }
+        ]
+      },
+      {
+        id: 'family-delete',
+        title: 'Удаление семьи',
+        blocks: [
+          {
+            type: 'paragraph',
+            text: 'Только создатель семьи может полностью удалить группу. В интерфейсе: страница семьи → «Участники семьи» → «Удалить семью». Действие необратимо.'
+          },
+          {
+            type: 'list',
+            items: [
+              'DELETE /family/groups/{groupId} — удалить семью (только ownerId === текущий пользователь)',
+              'Все участники исключаются из семьи',
+              'Все приглашения (FamilyInvite) удаляются',
+              'Все чаты семьи (ChatRoom), сообщения, опросы и голоса удаляются каскадом',
+              'Медиа в MinIO (аватар семьи, аватары чатов, вложения сообщений) удаляются best-effort',
+              'Остальным участникам отправляется уведомление family_group_deleted и событие WebSocket'
+            ]
+          },
+          {
+            type: 'callout',
+            variant: 'warning',
+            title: 'Без передачи владения',
+            text: 'Перед удалением семьи нельзя «передать» роль создателя другому участнику — только полное удаление группы или выход участников по отдельности.'
          }
        ]
      },
@@ -909,7 +1003,8 @@ curl -X POST http://localhost:3000/auth/otp/verify \\
            items: [
              'REST: /chat/groups/{groupId}/rooms, /chat/rooms/{roomId}/messages',
              'WebSocket: ws://localhost:8085/ws с JWT в query или заголовке',
-              'Медиа чата: presigned upload + защищённый stream с Authorization'
+              'Медиа чата: presigned upload + защищённый stream с Authorization',
+              'События realtime: chat_message, chat_message_updated, chat_message_deleted, family_group_deleted'
            ]
          }
        ]
--- a/apps/docs/lib/navigation.ts
+++ b/apps/docs/lib/navigation.ts
@@ -11,7 +11,7 @@ export const docNavigation: DocNavItem[] = [
  { slug: 'authentication', title: 'Аутентификация', group: 'Интеграция' },
  { slug: 'oauth', title: 'OAuth 2.0', group: 'Интеграция' },
  { slug: 'ldap', title: 'LDAP / LDAPS', group: 'Интеграция' },
-  { slug: 'sessions', title: 'Сессии и PIN', group: 'Безопасность' },
+  { slug: 'sessions', title: 'Сессии, PIN и удаление аккаунта', group: 'Безопасность' },
  { slug: 'family-chat', title: 'Семья и чат', group: 'Функции' },
  { slug: 'api-reference', title: 'Справочник API', group: 'Справочник' }
 ];