Client Intake Files

1. What does this feature do? (High-Level Overview)

This feature provides the Files section for a client profile, focused on two operational blocks:

1. Intake status tracking fields (welcome, consent, eligibility, etc.).
2. Paperwork URL management (documentation links table with add/edit/delete flow).

It is integrated into the client profile tab workflow and uses a read-mode component plus an edit-mode component controlled by permission-based edit wrapper logic in the parent profile screen.

2. Who is this for? (Roles & Permissions)

• Users with update_clients can enter edit mode in the Files section.
• Users without update_clients can view read-only Files data but cannot switch to edit mode from the wrapper.
• In read mode, URL inline edit button is shown only when update_clients is available.
• Documentation link create/update/delete actions are triggered from this section and handled by parent orchestration.

Required permissions used by this feature path:

• update_clients: enables edit mode and modification flow for intake fields and documentation links.

3. Business Rules & Enforcements

• Rule 1: Files section is shown when option_selected === 3 in client profile tabs.
• Rule 2: Edit mode is gated by appEditWrapper with requiredPermission=update_clients.
• Rule 3: Read component displays intake values as stored on client profile.
• Rule 4: Intake interview read label is normalized from value map (yes/sent/not_required).
• Rule 5: URL table in read mode shows normalized clickable links and No links provided when empty.
• Rule 6: URL edit mode clones a backup snapshot before modifications.
• Rule 7: URL save validates form controls; invalid URLs block save and show toast feedback.
• Rule 8: URL validation requires explicit protocol (http:// or https://) in edit form pattern.
• Rule 9: New URL rows use temporary negative ids and are converted to create events when non-empty.
• Rule 10: Existing URL rows emit update only if description or url changed versus backup.
• Rule 11: Removing persisted links emits delete events; removing temp rows only affects local UI.
• Rule 12: Empty persisted rows (no description and no url) are treated as delete on save in read component logic.
• Rule 13: Parent handles documentation link CRUD via DocumentationLinksV2Service and refreshes list after each operation.
• Rule 14: Edit component saves intake status changes by emitting patient partial data to parent saveFilesChanges.
• Rule 15: Parent saveFilesChanges delegates to savePatientChanges and persists through updatePatientProfile.
• Rule 16: File upload/delete handlers exist in parent and child APIs, but current Files edit template is focused on intake statuses and does not render upload/delete controls.

4. UI Placement

• Main route context:

1. Medical > Clients list.
2. Open client profile.
3. Files tab.

• Read mode blocks:

1. Intake Information card.
2. Paperwork URLs client information card.

• Edit mode blocks:

1. Intakes Status form.
2. Save / Cancel actions.

Note:

• Documentation links editing is currently implemented in the read component as an inline edit sub-mode (isEditingLinks), while intake status editing is handled by the dedicated edit component.

5. How-To Guide (Step-by-Step)

Scenario A: Update client intake statuses

1. Open client profile and go to Files tab.
2. Enter edit mode.
3. Update intake dropdowns (Welcome, Consent, Eligibility, etc.) and Interview value.
4. Click Save Changes.
5. Parent persists data through profile update flow and shows feedback.

Scenario B: Add a new paperwork URL

1. In Files tab read mode, click pencil on Paperwork URLs card.
2. Click Add URL.
3. Fill description and a valid URL including protocol.
4. Save Changes.
5. Parent creates the link and reloads current links list.

Scenario C: Edit an existing paperwork URL

1. Enter URL edit mode.
2. Modify description and/or URL.
3. Save Changes.
4. Parent patches the link and refreshes list.

Scenario D: Delete a paperwork URL

1. Enter URL edit mode and remove the row, or clear persisted row content and save.
2. Confirm deletion when prompted by parent flow.
3. Parent deletes link and reloads list.

6. What happens if…? (Edge Cases / FAQ)

• Q: What if user does not have update_clients?

• A: Files content remains visible, but edit entry points are blocked/hidden.

• Q: What if URL input is invalid during save?

• A: Save is blocked, controls are marked touched, and invalid URL toast feedback is shown.

• Q: What if documentation links list is empty?

• A: Read table shows No links provided.

• Q: What if documentation link API call fails?

• A: Parent shows toast error and keeps previous visible state.

• Q: Is binary file upload active in current Files UI?

• A: Upload/delete events and parent handlers exist, but current edit template does not render upload/delete controls, so operational focus is intake statuses + documentation URLs.

• Q: How are client files loaded after upload in current service layer?

• A: getPatientFiles in PatientUseCasesV2Service currently returns an empty array placeholder, so file listing behavior depends on future V2 implementation.