From a40e3df6ffa0342fd0b1e68499989952192dbf5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vitor=20Hugo=20Belorio=20Sim=C3=A3o?= Date: Mon, 6 Apr 2026 14:42:55 -0300 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(admin):=20documentar=20resp?= =?UTF-8?q?onsabilidades=20da=20camada=20api=20interna?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adiciona comentarios curtos em arquivos da camada administrativa para deixar mais explicitas as responsabilidades de sessoes, roteamento, autenticacao, auditoria, configuracao e gestao de colaboradores. O objetivo deste commit e melhorar a leitura do codigo e o onboarding sem alterar comportamento funcional do sistema. --- admin_app/api/dependencies.py | 2 ++ admin_app/api/panel_session.py | 3 +++ admin_app/api/router.py | 2 ++ admin_app/api/routes/audit.py | 2 ++ admin_app/api/routes/collaborators.py | 2 ++ admin_app/api/routes/panel_auth.py | 2 ++ admin_app/api/routes/system.py | 2 ++ 7 files changed, 15 insertions(+) diff --git a/admin_app/api/dependencies.py b/admin_app/api/dependencies.py index da58704..b2ef418 100644 --- a/admin_app/api/dependencies.py +++ b/admin_app/api/dependencies.py @@ -32,6 +32,8 @@ from admin_app.services import ( ) from shared.contracts import AdminPermission, StaffRole, permissions_for_role, role_has_permission, role_includes +# Injeta services, repositórios e settings. + bearer_scheme = HTTPBearer(auto_error=False) _tool_generation_worker_lock = threading.Lock() diff --git a/admin_app/api/panel_session.py b/admin_app/api/panel_session.py index 32ab4f1..bb1469e 100644 --- a/admin_app/api/panel_session.py +++ b/admin_app/api/panel_session.py @@ -6,6 +6,9 @@ PANEL_ACCESS_COOKIE_NAME = "orquestrador_admin_panel_access" PANEL_REFRESH_COOKIE_NAME = "orquestrador_admin_panel_refresh" PANEL_COOKIE_SAMESITE = "lax" +# Sessão web do painel. Realiza a ponte entre o AuthService (que realiza a autenticação e geração do token) e o navegador usando cookies HTTP. + +# É o adaptador entre a autenticação administrativa orientada a tokens e o modo como o painel web mantém sessão no navegador. def get_panel_access_cookie(request: Request) -> str | None: return request.cookies.get(PANEL_ACCESS_COOKIE_NAME) diff --git a/admin_app/api/router.py b/admin_app/api/router.py index 5b6d0a7..52e77ed 100644 --- a/admin_app/api/router.py +++ b/admin_app/api/router.py @@ -11,6 +11,8 @@ from admin_app.api.routes.reports import router as reports_router from admin_app.api.routes.system import router as system_router from admin_app.api.routes.tools import router as tools_router +# Agrega as rotas administrativas. + api_router = APIRouter() api_router.include_router(auth_router) api_router.include_router(panel_auth_router) diff --git a/admin_app/api/routes/audit.py b/admin_app/api/routes/audit.py index 53fd4fb..3f9e80f 100644 --- a/admin_app/api/routes/audit.py +++ b/admin_app/api/routes/audit.py @@ -6,6 +6,8 @@ from admin_app.core import AuthenticatedStaffPrincipal from admin_app.services import AuditService from shared.contracts import AdminPermission +# login/logout da API admin. + router = APIRouter(prefix="/audit", tags=["audit"]) diff --git a/admin_app/api/routes/collaborators.py b/admin_app/api/routes/collaborators.py index 1eda0bf..606b2b8 100644 --- a/admin_app/api/routes/collaborators.py +++ b/admin_app/api/routes/collaborators.py @@ -16,6 +16,8 @@ from admin_app.core import AuthenticatedStaffPrincipal from admin_app.services import CollaboratorManagementService from shared.contracts import AdminPermission +# Camada HTTP de gestão de colaboradores administrativos + router = APIRouter(prefix="/colaboradores", tags=["colaboradores"]) diff --git a/admin_app/api/routes/panel_auth.py b/admin_app/api/routes/panel_auth.py index e597f87..8b9443d 100644 --- a/admin_app/api/routes/panel_auth.py +++ b/admin_app/api/routes/panel_auth.py @@ -20,6 +20,8 @@ from admin_app.api.schemas import ( from admin_app.core import AdminAuthenticatedSession, AdminSettings, AuthenticatedStaffContext from admin_app.services import AuthService +# Autenticação do painel web. + router = APIRouter(prefix="/panel/auth", tags=["panel-auth"]) diff --git a/admin_app/api/routes/system.py b/admin_app/api/routes/system.py index 6215459..838cde8 100644 --- a/admin_app/api/routes/system.py +++ b/admin_app/api/routes/system.py @@ -33,6 +33,8 @@ from admin_app.core.settings import AdminSettings from admin_app.services.system_service import SystemService from shared.contracts import AdminPermission +# governança e configuração do sistema. + router = APIRouter(tags=["system"])