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:

// 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