clqms-fe1/openspec/changes/complete-backend-todos-and-core-pages/design.md

## Context

The CLQMS frontend currently has several incomplete features marked with TODO comments:

1. **Patient Delete**: The `deletePatient()` API exists but isn't wired up in the UI
2. **Order Detail**: Orders can only be viewed as a list item, with no detail modal
3. **Barcode Printing**: Referenced in UI but not implemented
4. **TestMap Delete**: Blocked by API limitation (missing TestMapID in list response)

Additionally, the sidebar links to two pages that don't exist:
- **Specimens**: Critical for complete lab workflow (patient → visit → order → specimen → results)
- **Users**: Essential for system administration

This change addresses all these gaps to provide a complete laboratory management experience.

## Goals / Non-Goals

**Goals:**
- Wire up patient delete functionality
- Create order detail view modal
- Implement specimen management page with full CRUD
- Implement user management page with full CRUD
- Prepare barcode printing infrastructure
- Document TestMap delete limitation

**Non-Goals:**
- Full barcode generation library integration (out of scope, preparing structure only)
- Backend API changes for TestMap (document limitation only)
- Role-based access control (reuse existing auth patterns)
- Advanced specimen tracking (batch, location) - basic CRUD only

## Backend API Requirements

### Specimen API (clqms01-be)
**Current Status:** CRU exists, missing DELETE

Required additions:
```php
// Add to app/Config/Routes.php
$routes->delete('(:num)', 'Specimen\SpecimenController::delete/$1');

// Add to SpecimenController
public function delete($id) {
    // Soft delete specimen
}
```

### User API (clqms01-be)
**Current Status:** Not implemented

Required new files:
```
app/
├── Controllers/
│   └── User/
│       └── UserController.php    # CRUD operations
├── Models/
│   └── User/
│       └── UserModel.php         # Database model
└── Config/Routes.php             # Add user routes
```

Required endpoints:
- `GET /api/users` - List with pagination
- `GET /api/users/(:num)` - Get single user
- `POST /api/users` - Create user
- `PATCH /api/users` - Update user  
- `DELETE /api/users/(:num)` - Delete user

## Decisions

### Decision: Use Existing Patterns
**Rationale**: Consistency with existing codebase reduces cognitive load and maintenance burden.

All new pages follow existing patterns:
- Search/filter pattern from Patients page
- Modal forms from Test Management
- API structure from existing `/lib/api/*.js` files
- DaisyUI + Tailwind styling consistent with current UI

### Decision: Barcode Printing - Stub First
**Rationale**: Barcode libraries (jsbarcode, qrcode) add dependencies. Better to prepare structure first, then integrate library in follow-up.

Current implementation:
- Print button triggers stub function
- Opens print dialog with formatted HTML
- Placeholder text indicates "coming soon"

Future enhancement:
- Add jsbarcode or similar library
- Generate actual barcodes
- Keep same print dialog structure

### Decision: Specimen Page Structure
**Rationale**: Specimens bridge orders and results - need to show relationships.

Page layout:
- Search/filter bar (specimen type, status, date)
- Data table with key columns
- Detail modal showing:
  - Specimen attributes
  - Related order info
  - Collection details
  - Container information

### Decision: User Page - Basic CRUD Only
**Rationale**: User management is admin function, not daily use. Complex features (permissions matrix, audit logs) can be added later.

Features:
- List users with search
- Create/edit user form
- Soft delete (disable) users
- Prevent self-deletion

Not included:
- Permission matrix UI
- User activity audit
- Password reset flow (use existing)

## Risks / Trade-offs

**[Risk] API endpoints may not exist for specimens/users**
→ **Status**: CONFIRMED - Specimen delete missing, User API not implemented
→ **Mitigation**: Coordinate with backend team to add endpoints before frontend delete features

**[Risk] TestMap delete limitation blocks feature**
→ **Mitigation**: Document limitation clearly, add informative error message, suggest backend improvement

**[Risk] Barcode printing may not work in all browsers**
→ **Mitigation**: Use standard window.print(), test in target environments, provide fallback

**[Risk] User delete without RBAC checks**
→ **Mitigation**: Add client-side check to prevent self-deletion, rely on backend for authorization

## Migration Plan

**Deployment**:
1. Deploy frontend changes
2. Verify new pages load correctly
3. Test patient delete on staging data
4. Verify sidebar navigation works

**Rollback**:
- Revert to previous commit
- No database changes required (frontend only)

## Open Questions

1. **What fields are available for specimens?**
   Need to review SpecimenModel for data structure

2. **Are there existing barcode requirements?**
   What format? Code128? QR codes? What data to encode?

3. **Should users have soft delete or hard delete?**
   Check if backend supports soft delete (status field)

## Backend Coordination Checklist

- [ ] Backend: Add Specimen delete endpoint
- [ ] Backend: Create UserController
- [ ] Backend: Create UserModel
- [ ] Backend: Add user routes to Routes.php
- [ ] Frontend: Implement specimen delete once API ready
- [ ] Frontend: Implement users page once API ready