Fix API regressions and refresh project docs

app/models/api_key.py

@@ -1,6 +1,7 @@
+import hashlib
 import secrets
 from datetime import datetime
-from sqlalchemy import String, Boolean, DateTime
+from sqlalchemy import Boolean, String
 from sqlalchemy.orm import Mapped, mapped_column
 from app.core.database import Base
 
@@ -24,3 +25,20 @@ class ApiKeyModel(Base):
     def generate_key() -> str:
         """Генерация безопасного случайного токена."""
         return secrets.token_urlsafe(32)
+
+    @staticmethod
+    def public_id_for(key: str) -> str:
+        """
+        Возвращает безопасный публичный идентификатор ключа.
+        Его можно отдавать клиенту и использовать в операциях revoke/activate
+        вместо самого секрета.
+        """
+        return hashlib.sha256(key.encode("utf-8")).hexdigest()[:16]
+
+    @property
+    def public_id(self) -> str:
+        return self.public_id_for(self.key)
+
+    @property
+    def preview(self) -> str:
+        return f"{self.key[:6]}...{self.key[-4:]}"