clqms-fe1/docs/COMPREHENSIVE_IMPLEMENTATION_PLAN.md

# Comprehensive Implementation Plan - CLQMS Frontend

**Goal:** Complete implementation of all use cases
**Estimated Time:** 6-8 weeks (after MVP)
**This document:** All features beyond MVP scope

---

## Phase 1: Authentication Enhancements (UC-01)
**Use Case:** UC-01 - Complete authentication flow
**Priority:** HIGH - Security & Multi-tenancy
**Dependencies:** Backend support for multi-site, password policies

### 1.1 Multi-Site Selection
**Current:** Login with single site
**Required:** Support for users with access to multiple sites

#### API Changes
```
POST /api/auth/login
Response changes:
{
  "token": "...",
  "user": { ... },
  "sites": [
    {"SiteID": "1", "SiteName": "Lab Jakarta", "SiteCode": "JK01"},
    {"SiteID": "2", "SiteName": "Lab Bandung", "SiteCode": "BD01"}
  ],
  "requiresSiteSelection": true
}
```

#### Frontend Implementation
**New Files:**
- `src/routes/login/SiteSelectionModal.svelte`
- `src/lib/stores/site.js` - Current site store

**Modify:**
- `src/routes/login/+page.svelte` - Add site selection step

**Features:**
- If personal email used: Show site selection dialog
- If site email used: Auto-select matching site
- Remember site selection in localStorage
- Site switcher in header/navigation
- Site context shown in UI (current site name)

### 1.2 Password Expiration
**Requirements:**
- Track password expiry date
- Force password change when expired
- Grace period warning (7 days before expiry)

#### API Changes
```
POST /api/auth/login
Response includes:
{
  "passwordStatus": "valid" | "expired" | "expiring",
  "passwordExpiryDate": "2025-03-01",
  "daysUntilExpiry": 5
}

POST /api/auth/change-password
```

#### Frontend Implementation
**New Files:**
- `src/routes/login/PasswordExpiredModal.svelte`
- `src/routes/login/ChangePasswordModal.svelte`

**Features:**
- Check password status on login
- If expired: Block access, show change password modal
- If expiring: Show warning banner with countdown
- Password strength requirements display
- Confirm password match validation

### 1.3 Account Lockout
**Requirements:**
- Count failed login attempts
- Lock account after X failed attempts (configurable)
- Lockout duration: X hours (configurable)
- Clear attempts on successful login

#### API Changes
```
POST /api/auth/login
Error responses:
{
  "error": "ACCOUNT_LOCKED",
  "message": "Please try again in 4 hours or contact system administrator",
  "lockoutEndsAt": "2025-02-14T18:00:00Z",
  "hoursRemaining": 4
}

POST /api/auth/login
On invalid password:
{
  "error": "INVALID_LOGIN",
  "attemptsRemaining": 2
}
```

#### Frontend Implementation
**Modify:**
- `src/routes/login/+page.svelte` - Handle lockout states

**Features:**
- Display attempts remaining
- Show lockout timer with countdown
- "Contact administrator" link/info
- Visual indicator of account status

### 1.4 Audit Logging Display
**Requirements:**
- View own login history
- Admin view: All user login history
- Filter by date, user, action

#### API Changes
```
GET /api/audit/login-logs?userId=&from=&to=&page=
Response:
{
  "logs": [
    {
      "AuditID": 1,
      "UserID": "admin",
      "Action": "LOGIN_SUCCESS",
      "Device": "Chrome 120.0 / Windows 10",
      "IPAddress": "192.168.1.1",
      "Timestamp": "2025-02-14T10:30:00Z"
    }
  ]
}
```

#### Frontend Implementation
**New Files:**
- `src/routes/(app)/admin/audit-logs/+page.svelte`
- `src/lib/api/audit.js`

**Features:**
- Paginated log table
- Filters: Date range, User, Action type
- Export to CSV
- Device/IP details

---

## Phase 2: Advanced Patient Management

### 2.1 Enhanced Patient Registration (UC-02a Enhancements)
**Missing Features:**
- Duplicate identifier detection with "Multiple IDs found" handling
- UC-02b link suggestion when duplicates detected

#### API Changes
```
POST /api/patient/check-duplicate
{
  "IdentifierType": "KTP",
  "Identifier": "1234567890"
}
Response:
{
  "hasDuplicates": true,
  "duplicates": [
    {"PID": "P001", "Name": "John Doe", "DOB": "1990-01-01"}
  ]
}
```

#### Frontend Implementation
**Modify:**
- `src/routes/(app)/patients/PatientFormModal.svelte`

**New Files:**
- `src/routes/(app)/patients/DuplicateWarningModal.svelte`

**Features:**
- Check for duplicates on identifier blur
- Show "Multiple IDs found" warning
- Options:
  1. Continue (create new, ignore duplicate)
  2. Link patients (redirect to UC-02b)
  3. Cancel
- Display duplicate patient details for comparison

### 2.2 Patient Unlink (UC-02c)
**Requirements:**
- Reverse patient link operation
- Only Supervisor Lab, Manajer Lab
- Restore source PID to active status

#### API Changes
```
POST /api/patient/unlink
{
  "SourcePID": "P001",
  "DestinationPID": "P002"
}
Creates ADT: A37 (Unlink Patient Information)
```

#### Frontend Implementation
**New Files:**
- `src/routes/(app)/patients/unlink/+page.svelte`

**Features:**
- Search by PID to find linked patients
- Display destination with all linked sources
- Uncheck source PIDs to unlink
- Confirmation dialog
- Restore source PID edit/order capabilities

---

## Phase 3: Advanced Visit Management

### 3.1 Cancel Admission (UC-03b)
**Requirements:**
- Cancel patient admission
- Only Supervisor Lab, Manajer Lab
- Reason for cancellation
- ADT Code: A11 (Cancel Admit)

#### API Changes
```
POST /api/patvisit/:pvid/cancel-admission
{
  "Reason": "Insurance invalid",
  "Notes": "..."
}
Creates ADT: A11 (Cancel Admit)
```

#### Frontend Implementation
**New Files:**
- `src/routes/(app)/patients/CancelAdmissionModal.svelte`

**Features:**
- Available in visit actions (supervisor only)
- Reason dropdown + notes field
- Confirm cancellation
- Mark visit as cancelled
- Prevent new orders on cancelled visits

### 3.2 Change Attending Doctor (UC-03c)
**Requirements:**
- Change primary doctor (DPJP)
- ADT Code: A54 (Change Attending Doctor)
- Track doctor history

#### API Changes
```
POST /api/patvisit/:pvid/change-attending-doctor
{
  "NewAttendingDoctorID": "DOC001"
}
Creates ADT: A54
```

#### Frontend Implementation
**Modify:**
- `src/routes/(app)/patients/VisitFormModal.svelte`

**Features:**
- Doctor dropdown with search
- Show current attending doctor
- Change history in ADT log
- Validation: Doctor must exist in contacts

### 3.3 Change Consulting Doctor (UC-03d)
**Requirements:**
- Change consulting doctor (konsulen)
- ADT Code: A61 (Change Consulting Doctor)

#### API Changes
```
POST /api/patvisit/:pvid/change-consulting-doctor
{
  "NewConsultingDoctorID": "DOC002"
}
Creates ADT: A61
```

#### Frontend Implementation
**Modify:**
- `src/routes/(app)/patients/VisitFormModal.svelte`

**Features:**
- Similar to attending doctor change
- Separate field for consulting doctor
- History tracking

---

## Phase 4: Test Ordering Enhancements

### 4.1 Future Orders
**Requirements:**
- Schedule test order for future date
- Effective date validation

#### Frontend Implementation
**Modify:**
- `src/routes/(app)/orders/new/+page.svelte`

**Features:**
- "Effective Date" field (default: today)
- Future date validation (max 30 days?)
- Separate OID generation for future orders?
- View scheduled orders separately

### 4.2 Order from PID (Alternative Flow)
**Requirements:**
- Create order using PID instead of PVID
- Show list of active PVIDs for patient
- Select PVID then proceed

#### Frontend Implementation
**Modify:**
- `src/routes/(app)/orders/new/+page.svelte`

**Features:**
- Toggle: "Use PID instead of PVID"
- PID search
- Display patient's active visits (not discharged)
- Select PVID to proceed

### 4.3 Non-Patient Orders
**Requirements:**
- Orders without patient (QC, calibration, research)
- Different order type/flow

#### API Changes
```
POST /api/orders/non-patient
{
  "OrderType": "QC",
  "Description": "...",
  "Tests": [...]
}
```

#### Frontend Implementation
**New Files:**
- `src/routes/(app)/orders/non-patient/+page.svelte`

---

## Phase 5: Specimen Management

### 5.1 Specimen Tracking
**Requirements:**
- Full specimen lifecycle tracking
- Collection, receipt, rejection, disposal
- Barcode/label generation

#### API Changes
```
GET    /api/specimens/:sid/status-history
PATCH  /api/specimens/:sid/status
{
  "Status": "COLLECTED", // COLLECTED, RECEIVED, REJECTED, DISPOSED
  "Notes": "..."
}
```

#### Frontend Implementation
**New Files:**
- `src/routes/(app)/specimens/+page.svelte` - Specimen list
- `src/routes/(app)/specimens/[sid]/+page.svelte` - Specimen detail
- `src/lib/api/specimens.js` (extend)

**Features:**
- Specimen search (SID, OID, Patient)
- Status timeline/history
- Collection/receipt timestamps
- Rejection reason logging
- Label printing (integration with printer)

### 5.2 Label Printing Integration
**Requirements:**
- Print patient labels
- Print order labels
- Print specimen labels
- Support for label printers

#### Frontend Implementation
**New Files:**
- `src/lib/utils/labelPrinting.js`
- `src/routes/(app)/print/labels/+page.svelte`

**Features:**
- Label templates (patient, order, specimen)
- Print dialog with printer selection
- Preview before print
- Batch printing
- Integration with browser print API or direct printer communication

---

## Phase 6: Reporting & Analytics

### 6.1 Cumulative Patient Reports
**Requirements:**
- View all test results across visits for linked patients
- Chronological view
- Filter by test type, date range

#### API Changes
```
GET /api/reports/patient-cumulative/:pid?from=&to=&tests=
Response:
{
  "patient": {...},
  "visits": [...],
  "results": [
    {
      "Date": "...",
      "Test": "Glucose",
      "Result": "120",
      "Unit": "mg/dL",
      "ReferenceRange": "70-100"
    }
  ]
}
```

#### Frontend Implementation
**New Files:**
- `src/routes/(app)/reports/patient-cumulative/+page.svelte`

**Features:**
- Patient search
- Date range filter
- Test type filter
- Table view with trend indicators
- Export to PDF/Excel

### 6.2 Workload Statistics
**Requirements:**
- Orders by time period
- Tests performed
- Turnaround time analysis

#### Frontend Implementation
**New Files:**
- `src/routes/(app)/reports/workload/+page.svelte`

---

## Phase 7: Administration Features

### 7.1 User Management
**Requirements:**
- Create/edit users
- Role assignment
- Site access management
- Password reset

#### Frontend Implementation
**New Files:**
- `src/routes/(app)/admin/users/+page.svelte`
- `src/routes/(app)/admin/users/UserFormModal.svelte`

### 7.2 Role & Permission Management
**Requirements:**
- Define roles
- Configure menu access per role
- Action-level permissions

### 7.3 System Configuration
**Requirements:**
- Global settings
- ADT code configuration
- Password policy settings
- Lockout configuration

---

## Phase 8: Integration Features

### 8.1 HL7/ADT Message Integration
**Requirements:**
- Receive ADT messages from HIS
- Send order updates to HIS
- Message queue management

### 8.2 Instrument Integration
**Requirements:**
- Bidirectional communication with lab instruments
- Auto-result entry
- QC data import

---

## Implementation Priority Matrix

### Critical (Month 1-2)
1. Authentication: Multi-site selection
2. Patient: Enhanced duplicate detection
3. Visit: Cancel admission, doctor changes
4. Orders: Future orders, PID-based ordering

### High (Month 2-3)
1. Authentication: Password expiration
2. Authentication: Account lockout
3. Patient: Unlink functionality
4. Specimens: Full tracking
5. Reports: Cumulative patient view

### Medium (Month 3-4)
1. Authentication: Audit logs
2. Specimens: Label printing integration
3. Administration: User management
4. Administration: Role management

### Low (Month 4+)
1. Non-patient orders
2. Workload statistics
3. System configuration UI
4. Instrument integration

---

## Technical Considerations

### Performance
- Implement pagination for all list endpoints
- Use virtual scrolling for large tables
- Cache patient/order data appropriately
- Lazy load audit logs

### Security
- All admin actions require elevated permissions
- Audit all sensitive operations
- Encrypt sensitive data at rest
- Secure password storage (backend)

### Scalability
- Support for multiple sites/locations
- Concurrent user handling
- Large dataset performance (100k+ patients)

---

## Dependencies

### Backend Must Support:
- [ ] Multi-site user management
- [ ] Password expiration tracking
- [ ] Failed login attempt tracking
- [ ] All ADT codes (A11, A54, A61, A24, A37)
- [ ] Advanced patient search (duplicate detection)
- [ ] Specimen status workflow
- [ ] Audit logging for all operations
- [ ] Role-based access control (RBAC)
- [ ] Label generation endpoints

### Infrastructure:
- [ ] Label printer setup
- [ ] Barcode scanner integration
- [ ] HIS/HL7 integration (if needed)
- [ ] Backup and disaster recovery

---

## Success Criteria

### Phase 1 Complete:
- [ ] Users can select site on login
- [ ] Password expiration enforced
- [ ] Account lockout working
- [ ] Multi-site data isolation

### Phase 2 Complete:
- [ ] Duplicate detection on registration
- [ ] Patient link/unlink functional
- [ ] Link validation (no multi-level)

### Phase 3 Complete:
- [ ] All visit operations functional
- [ ] Complete ADT history for all actions
- [ ] Doctor change tracking

### Phase 4 Complete:
- [ ] Future order scheduling
- [ ] PID-based ordering
- [ ] Non-patient order support

### Phase 5 Complete:
- [ ] Full specimen lifecycle tracking
- [ ] Label printing operational
- [ ] Specimen status history

### Phase 6 Complete:
- [ ] Cumulative reports for linked patients
- [ ] Workload statistics
- [ ] Export functionality

### Phase 7 Complete:
- [ ] User management UI
- [ ] Role configuration
- [ ] System settings

### Phase 8 Complete:
- [ ] HIS integration
- [ ] Instrument integration
- [ ] Message queue management