📝 docs(admin): documentar responsabilidades da camada api interna

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

@@ -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()

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)

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)

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"])
 
 

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"])
 
 

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"])
 
 

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"])