Spaces:
Build error
Build error
| # 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:** | |
| ```javascript | |
| 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: | |
| ```javascript | |
| { | |
| 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 | |