refactor(backend/api): extract AuditSession service layer (Step 4 worked example)

Phase 1 Step 4 of PHASE1_RUNBOOK.md, first worked example. Demonstrates
the router -> service delegation pattern for all 18 oversized route
files still above the 500 LOC hard cap.

compliance/api/audit_routes.py (637 LOC) is decomposed into:

  compliance/api/audit_routes.py              (198) — thin handlers
  compliance/services/audit_session_service.py (259) — session lifecycle
  compliance/services/audit_signoff_service.py (319) — checklist + sign-off
  compliance/api/_http_errors.py               ( 43) — reusable error translator

Handlers shrink to 3-6 lines each:

    @router.post("/sessions", response_model=AuditSessionResponse)
    async def create_audit_session(
        request: CreateAuditSessionRequest,
        service: AuditSessionService = Depends(get_audit_session_service),
    ):
        with translate_domain_errors():
            return service.create(request)

Services are HTTP-agnostic: they raise NotFoundError / ConflictError /
ValidationError from compliance.domain, and the route layer translates
those to HTTPException(404/409/400) via the translate_domain_errors()
context manager in compliance.api._http_errors. The error translator is
reusable by every future Step 4 refactor.

Services take a sqlalchemy Session in the constructor and are wired via
Depends factories (get_audit_session_service / get_audit_signoff_service).
No globals, no module-level state.

Behavior is byte-identical at the HTTP boundary:
  - Same paths, methods, status codes, response models
  - Same error messages (domain error __str__ preserved)
  - Same auto-start-on-first-signoff, same statistics calculation,
    same signature hash format, same PDF streaming response

Verified:
  - 173/173 pytest compliance/tests/ tests/contracts/ pass
  - OpenAPI 360 paths / 484 operations unchanged
  - audit_routes.py under soft 300 target
  - Both new service files under soft 300 / hard 500

Note: compliance/tests/test_audit_routes.py contains placeholder tests
that do not actually import or call the handler functions — they only
assert on request-data shape. Real behavioral coverage relies on the
contract test. A follow-up commit should add TestClient-based
integration tests for the audit endpoints. Flagged in PHASE1_RUNBOOK.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sharang Parnerkar
2026-04-07 18:16:50 +02:00
parent 482e8574ad
commit 4a91814bfc
5 changed files with 715 additions and 533 deletions

View File

@@ -20675,7 +20675,7 @@
},
"/api/compliance/audit/checklist/{session_id}": {
"get": {
"description": "Get the audit checklist for a session with pagination.\n\nReturns requirements with their current sign-off status.",
"description": "Get the paginated audit checklist for a session.",
"operationId": "get_audit_checklist_api_compliance_audit_checklist__session_id__get",
"parameters": [
{
@@ -20843,7 +20843,7 @@
},
"/api/compliance/audit/checklist/{session_id}/items/{requirement_id}/sign-off": {
"put": {
"description": "Sign off on a specific requirement in an audit session.\n\nIf sign=True, creates a digital signature (SHA-256 hash).",
"description": "Sign off on a specific requirement in an audit session.",
"operationId": "sign_off_item_api_compliance_audit_checklist__session_id__items__requirement_id__sign_off_put",
"parameters": [
{
@@ -20959,7 +20959,7 @@
]
},
"post": {
"description": "Create a new audit session for structured compliance reviews.\n\nAn audit session groups requirements for systematic review by an auditor.",
"description": "Create a new audit session for structured compliance reviews.",
"operationId": "create_audit_session_api_compliance_audit_sessions_post",
"requestBody": {
"content": {
@@ -21002,7 +21002,7 @@
},
"/api/compliance/audit/sessions/{session_id}": {
"delete": {
"description": "Delete an audit session and all its sign-offs.\n\nOnly draft sessions can be deleted.",
"description": "Delete a draft or archived audit session and all its sign-offs.",
"operationId": "delete_audit_session_api_compliance_audit_sessions__session_id__delete",
"parameters": [
{
@@ -21128,7 +21128,7 @@
},
"/api/compliance/audit/sessions/{session_id}/complete": {
"put": {
"description": "Complete an audit session (change status from in_progress to completed).",
"description": "Complete an audit session (in_progress -> completed).",
"operationId": "complete_audit_session_api_compliance_audit_sessions__session_id__complete_put",
"parameters": [
{
@@ -21170,7 +21170,7 @@
},
"/api/compliance/audit/sessions/{session_id}/report/pdf": {
"get": {
"description": "Generate a PDF report for an audit session.\n\nParameters:\n- session_id: The audit session ID\n- language: Output language ('de' or 'en'), default 'de'\n- include_signatures: Include digital signature verification section\n\nReturns:\n- PDF file as streaming response",
"description": "Generate a PDF report for an audit session.",
"operationId": "generate_audit_pdf_report_api_compliance_audit_sessions__session_id__report_pdf_get",
"parameters": [
{
@@ -21233,7 +21233,7 @@
},
"/api/compliance/audit/sessions/{session_id}/start": {
"put": {
"description": "Start an audit session (change status from draft to in_progress).",
"description": "Start an audit session (draft -> in_progress).",
"operationId": "start_audit_session_api_compliance_audit_sessions__session_id__start_put",
"parameters": [
{