Hugging Face's logo

Spaces:
rickescher
/
SailingMedAdvisor
Build error

App Files Community
SailingMedAdvisor / SPEC_Add_Crew_Functionality.md
Rick
Sync working tree changes
e171203
preview code
|
raw
history blame contribute delete
11.4 kB

Specification: Add Crew Member Functionality

Vessel & Crew Info Page

Document Version: 1.0
Date: January 22, 2026
System: SailingMedAdvisor v5.7

1. Overview

The Add Crew Member functionality allows users to register new crew members, passengers, or captain into the SailingMedAdvisor system. This feature is located on the Vessel & Crew Info tab within a collapsible "Add New Crew Member" section under "Crew Information".

2. User Interface Location

  • Primary Tab: Vessel & Crew (4th tab in main navigation)
  • Parent Section: Crew Information (collapsible)
  • Component: Add New Crew Member (nested collapsible form)
  • UI State: Initially collapsed (must be expanded to access)

3. Form Fields

3.1 Personal Information

Field Name Input Type Required Validation Notes
First Name Text Yes* Non-empty after trim Left column of 3-column grid
Middle Name(s) Text No None Center column of 3-column grid
Last Name Text Yes* Non-empty after trim Right column of 3-column grid
Sex Dropdown Yes* Must select value Options: Male, Female, Non-binary, Other, Prefer not to say
Birthdate Date Yes* Must have value Standard HTML date picker
Position Dropdown Yes* Must select value Options: Captain, Crew, Passenger

3.2 Travel Documents

Field Name Input Type Required Validation Notes
Citizenship Text + Datalist Yes* Non-empty after trim Autocomplete suggestions from predefined country list
Passport Number Text Yes* Non-empty after trim Unique identifier
Issue Date Date No None Passport issue date
Expiry Date Date No None Passport expiration date

Country Datalist: USA, Canada, UK, Australia, New Zealand, France, Germany, Spain, Italy, Netherlands, Singapore, Malaysia, Thailand, Philippines, Japan, China, India

3.3 Contact Information

Field Name Input Type Required Validation Notes
Cell/WhatsApp Text No None Placeholder format: +1234567890
Passport Photo/PDF File No Image/* or PDF, <5MB Uploaded separately after crew creation
Passport Page Photo/PDF File No Image/* or PDF, <5MB Uploaded separately after crew creation

3.4 Emergency Contact Information

Field Name Input Type Required Validation Notes
Name Text No None Emergency contact's full name
Relationship Text No None Relationship to crew member
Phone Text No None Emergency contact phone number
Email Email No None Emergency contact email address
Emergency Contact Notes Text No None Additional emergency contact information

* = Required field validation enforced

4. Functional Behavior

4.1 Add Operation Workflow

  1. User Input Phase:

    • User expands "Crew Information" section (if collapsed)
    • User expands "Add New Crew Member" section (if collapsed)
    • User fills out form fields
    • User clicks "+ Add Crew Member" button

  2. Validation Phase:

    Required Field Checks (in order):
1. First Name - Alert: "Please enter first name and last name"
2. Last Name - Alert: "Please enter first name and last name"
3. Sex - Alert: "Please select sex"
4. Birthdate - Alert: "Please enter birthdate"
5. Position - Alert: "Please select position"
6. Citizenship - Alert: "Please enter citizenship"
7. Passport Number - Alert: "Please enter passport number"
    • If any validation fails, display alert and stop processing
    • User must correct the issue and re-submit

  3. Data Creation Phase:

    • Fetch existing crew data from /api/data/patients
    • Create new crew member object:
      {
  id: Date.now().toString(),  // Timestamp-based unique ID
  firstName: string,
  middleName: string,
  lastName: string,
  sex: string,
  birthdate: string (YYYY-MM-DD),
  position: string,
  citizenship: string,
  passportNumber: string,
  passportIssue: string (YYYY-MM-DD),
  passportExpiry: string (YYYY-MM-DD),
  emergencyContactName: string,
  emergencyContactRelation: string,
  emergencyContactPhone: string,
  emergencyContactEmail: string,
  emergencyContactNotes: string,
  phoneNumber: string,
  passportPhoto: '',  // Empty initially
  passportPage: '',   // Empty initially
  history: ''         // Empty initially
}

  4. Data Persistence Phase:

    • Append new crew member to existing array
    • POST updated array to /api/data/patients endpoint
    • Server persists data to JSON file

  5. UI Update Phase:

    • Clear all form fields (reset to empty/default state)
    • Call loadData() function to refresh UI
    • New crew member appears in:
      • Crew Information list (on current tab)
      • Crew Health & Log dropdown
      • Chat page crew member selector

5. Data Model

5.1 Storage Location

  • Endpoint: /api/data/patients
  • Method: GET (retrieve), POST (update)
  • Format: JSON array
  • File: data/patients.json

5.2 ID Generation

  • Algorithm: Date.now().toString()
  • Format: Unix timestamp as string (e.g., "1737522671234")
  • Uniqueness: Guaranteed by millisecond precision
  • Note: IDs are not sequential, time-based for traceability

6. Integration Points

6.1 Affected Components

  1. Crew Member Dropdown (Chat Page):

    • New crew member added to p-select dropdown
    • Available for triage queries immediately

  2. Crew Medical List:

    • New entry created with empty medical history
    • Accessible on "Crew Health & Log" tab

  3. Crew Information List:

    • New collapsible section created
    • Shows crew member details with edit capability

6.2 Related Functions

  • loadCrewData() - Refreshes all crew-dependent UI elements
  • getCrewDisplayName() - Formats name as "Last, First"
  • getCrewFullName() - Formats name as "First Last"
  • calculateAge() - Calculates age from birthdate

7. User Experience Features

7.1 Form Behavior

  • Auto-trim: All text fields automatically trimmed before save
  • Reset on Success: Form clears completely after successful add
  • Datalist Support: Citizenship field provides autocomplete suggestions
  • File Upload: Document uploads handled separately after crew creation

7.2 Validation Feedback

  • Real-time: No real-time validation (submit-time only)
  • Error Messages: Alert-based, blocking further action until resolved
  • Field Focus: No automatic focus on error field (manual user correction required)

8. Button Specification

8.1 Add Crew Member Button

  • Label: "+ Add Crew Member"
  • Style:
    • Background: var(--dark) (#2c3e50)
    • Text: White
    • Width: 100% of container
    • Class: btn btn-sm
  • Action: onclick="addCrew()"
  • Location: Bottom of Add New Crew Member form

9. Edge Cases and Error Handling

9.1 Duplicate Detection

  • Current Behavior: No duplicate detection
  • Allowed: Multiple crew members with identical names
  • Recommendation: Consider adding duplicate warning for same passport number

9.2 Network Failures

  • No Error Handling: Function assumes successful API calls
  • Risk: Silent failure if network or server issues occur
  • Recommendation: Add try-catch blocks and user feedback

9.3 Concurrent Modifications

  • Race Condition: Possible if multiple users add crew simultaneously
  • Mitigation: Last-write-wins (later POST overwrites earlier)
  • Recommendation: Implement server-side locking or conflict detection

10. Security Considerations

10.1 Input Sanitization

  • Client-side: Basic HTML escaping via escapeHtml() on display
  • Server-side: Assumed (not verified in frontend code)
  • File Uploads: Size limit enforced (5MB), type validation (image/PDF)

10.2 Authentication

  • Current: Uses credentials: 'same-origin' for API calls
  • Session-based: Assumes server-side session validation
  • Login: Crew-specific login credentials managed separately in Settings

11. Accessibility Notes

11.1 Current State

  • Labels: Present for all form fields
  • Required Indicators: Asterisk (*) in label text
  • Keyboard Navigation: Standard HTML form tab order
  • Screen Reader: Field labels associated with inputs

11.2 Improvements Needed

  • ARIA attributes: Not currently implemented
  • Error announcements: Alert dialogs are announced but could be improved
  • Focus management: No automatic focus on validation errors

12. Performance Characteristics

12.1 Scalability

  • Data Structure: Array-based, linear search for operations
  • Current Capacity: Suitable for small crews (< 100 members)
  • Load Time: O(n) where n = number of crew members
  • Recommendation: Consider indexing for larger datasets

12.2 Network Efficiency

  • Data Transfer: Full array sent on each POST (not incremental)
  • Bandwidth: Minimal for typical crew sizes
  • Optimization: Could implement PATCH for single crew updates

13. Testing Scenarios

13.1 Happy Path

  1. Fill all required fields with valid data
  2. Click "+ Add Crew Member"
  3. Verify form clears
  4. Verify crew appears in all relevant lists
  5. Verify crew is selectable in chat dropdown

13.2 Validation Testing

  1. Submit with each required field missing (one at a time)
  2. Verify correct error message displayed
  3. Verify form data retained after validation failure

13.3 Data Integrity

  1. Add crew member
  2. Refresh page
  3. Verify crew member persists
  4. Verify all fields saved correctly

13.4 Special Characters

  1. Enter names with special characters (e.g., O'Brien, José)
  2. Verify correct storage and display
  3. Check CSV export format

14. Related Documentation

  • Main Application: app.py - Backend API endpoints
  • Frontend Logic: static/js/crew.js - Crew management functions
  • UI Template: templates/index.html - Form structure
  • Data Schema: data/patients.json - Sample data structure

15. Version History

Version Date Changes Author
1.0 2026-01-22 Initial specification based on code analysis System

16. Future Enhancements

16.1 Potential Improvements

  1. Photo capture: Direct camera integration for passport photos
  2. Barcode scanning: Auto-fill from passport MRZ scan
  3. Duplicate detection: Warning for similar names/passport numbers
  4. Batch import: CSV import for multiple crew members
  5. Validation enhancement: Real-time field validation
  6. Data export: Individual crew member PDF dossier generation
  7. History tracking: Audit log of crew member additions/changes

16.2 Integration Opportunities

  1. External APIs: Passport validation services
  2. Compliance: International maritime crew list standards (IMO FAL forms)
  3. Sync: Cloud backup and multi-device synchronization