feat(api): production security, cors hardening, latency optimizations, postman artifacts & frontend documentation

2026-08-31 13:48:54 +05:30
parent 4e21d617ce
commit e91cdbae6e
48 changed files with 3742 additions and 65 deletions
@@ -0,0 +1,194 @@
+# Text Onboarding & Document API Reference
+
+**Implementation Sources**: [`app/api/onboarding.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/api/onboarding.py), [`app/api/documents.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/api/documents.py)
+
+---
+
+## 1. POST `/v1/onboarding/start`
+
+Starts a new text-based clinical onboarding intake session.
+
+### Request Headers:
+```http
+Content-Type: application/json
+Authorization: Bearer test_token_PAT-10023
+```
+
+### Request Body (`StartOnboardingRequest`):
+```json
+{
+  "patient": {
+    "id": "PAT-10023",
+    "name": "Kavitha Ramesh",
+    "age": 35,
+    "gender": "female",
+    "phone": "+919876543210",
+    "abha_id": "91-1234-5678-9012",
+    "insurance_scheme": "PMJAY",
+    "dietary_habits": "Vegetarian"
+  },
+  "category": {
+    "type": "general",
+    "code": "general_medicine",
+    "name": "General Medicine"
+  },
+  "language": "en"
+}
+```
+
+### Field Descriptions:
+
+| Field | Type | Required | Validation Rules | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `patient.id` | string | **Yes** | Min length 1 | Unique patient identifier |
+| `patient.name` | string | No | Optional | Full name of patient |
+| `patient.age` | integer | No | $0 \le \text{age} \le 120$ | Patient age in years |
+| `patient.gender` | string | No | Optional | Gender identity ("male", "female", "other") |
+| `category.type` | string | **Yes** | `"general"` or `"speciality"` | Onboarding workflow type |
+| `category.code` | string | **Yes** | Min length 1 | Specialty classification code |
+| `category.name` | string | **Yes** | Min length 1 | Human-readable category display name |
+| `language` | string | No | Default `"en"` | Preferred intake language |
+
+### Successful Response (`200 OK` - `StartOnboardingResponse`):
+```json
+{
+  "success": true,
+  "session_id": "ONB-8F12A9C4",
+  "patient_id": "PAT-10023",
+  "category": {
+    "type": "general",
+    "code": "general_medicine",
+    "name": "General Medicine"
+  },
+  "language": "en",
+  "status": "in_progress",
+  "stage": "symptoms",
+  "message": "Hello Kavitha Ramesh! I am your clinical onboarding assistant. What symptoms are you experiencing today?"
+}
+```
+
+---
+
+## 2. POST `/v1/onboarding/{session_id}/message`
+
+Sends a patient chat response to the AI intake orchestrator.
+
+### Request Headers:
+```http
+Content-Type: application/json
+Authorization: Bearer test_token_PAT-10023
+```
+
+### Request Body (`SendMessageRequest`):
+```json
+{
+  "message": "I have had severe chest tightness and shortness of breath for 2 days."
+}
+```
+
+### Successful Response (`200 OK` - `SendMessageResponse`):
+```json
+{
+  "success": true,
+  "session_id": "ONB-8F12A9C4",
+  "stage": "medical_history",
+  "message": "Thank you for sharing. Does the chest tightness radiate to your arm or jaw, and do you have any history of high blood pressure?",
+  "status": "in_progress",
+  "response_time_ms": 1529.74,
+  "response_time_sec": 1.53
+}
+```
+
+---
+
+## 3. POST `/v1/documents/{session_id}/upload`
+
+Uploads a medical document (lab report, prescription, discharge summary) for vision extraction.
+
+### Request Headers:
+```http
+Content-Type: multipart/form-data
+Authorization: Bearer test_token_PAT-10023
+```
+
+### Form Data Parameters:
+- `file`: Binary file upload (**Allowed formats**: `image/jpeg`, `image/png`, `image/webp`, `application/pdf`). **Maximum size**: `10MB` (`10,485,760 bytes`).
+
+### Successful Response (`200 OK` - `DocumentExtractionResponse`):
+```json
+{
+  "success": true,
+  "session_id": "ONB-8F12A9C4",
+  "document_type": "lab_report",
+  "summary": "Report indicates elevated HbA1c (7.2%) and stage 1 hypertension (130/85 mmHg).",
+  "findings": [
+    {
+      "test": "HbA1c",
+      "value": "7.2",
+      "unit": "%",
+      "interpretation": "Elevated"
+    },
+    {
+      "test": "Blood Pressure",
+      "value": "130/85",
+      "unit": "mmHg",
+      "interpretation": "Stage 1"
+    }
+  ],
+  "medications_found": ["Metformin 500mg"],
+  "allergies_found": ["Penicillin"],
+  "message": "Medical document analyzed and integrated into onboarding session."
+}
+```
+
+---
+
+## 4. POST `/v1/onboarding/{session_id}/complete`
+
+Finalizes the intake session and outputs the structured clinical EHR payload.
+
+### Request Body (`CompleteOnboardingRequest`):
+```json
+{
+  "confirmed": true
+}
+```
+
+### Successful Response (`200 OK` - `CompleteOnboardingResponse`):
+```json
+{
+  "success": true,
+  "session_id": "ONB-8F12A9C4",
+  "status": "completed",
+  "result": {
+    "patient_id": "PAT-10023",
+    "abha_id": "91-1234-5678-9012",
+    "phone": "+919876543210",
+    "insurance_scheme": "PMJAY",
+    "category": {
+      "type": "general",
+      "code": "general_medicine",
+      "name": "General Medicine"
+    },
+    "chief_complaint": "Chest tightness and shortness of breath for 2 days",
+    "symptoms": [
+      {
+        "name": "Chest tightness",
+        "duration": "2 days",
+        "severity": "severe",
+        "description": "Triggered during exertion"
+      }
+    ],
+    "medical_history": ["Prehypertension"],
+    "medications": ["Metformin 500mg"],
+    "allergies": ["Penicillin"],
+    "dietary_habits": "Vegetarian",
+    "additional_information": "Patient confirmed details.",
+    "language": "en",
+    "onboarding_completed": true
+  },
+  "message": "Onboarding successfully completed and saved to patient record.",
+  "response_time_ms": 4075.41,
+  "response_time_sec": 4.08
+}
+```