Add FIN (wristband) field — separate from participant ID

[loopback]

Context

The barcode scanner currently populates the participant ID field, but FIN (Financial Identification Number, from patient wristband) and the research participant ID are different identifiers. Research workflow needs both: a manually-entered participant ID (links to consent tracking, REDCap, audits) and a scanned FIN.

Design Decisions

FIN storage: New ParticipantFIN table in the existing recordings.db (not a separate database). Integer FK to participants.id with a unique constraint (one FIN per participant, upserted on conflict). Proper PHI access control is deferred to the DataJoint export layer (future scope, @ktshah04).

API contract: POST /api/v1/session extended with an optional fin query parameter. FIN is NOT echoed in the response.

Lazy participant creation: set_session() only writes to recordings.db when a FIN is provided — it calls _get_or_create_participant() then stores the FIN. The no-FIN flow remains a no-op against the DB (unchanged behavior).

FIN preserved across patient ID changes (app): If the operator scans a wristband then changes the typed participant ID, the FIN stays — it belongs to the wristband, not the typed ID.

FIN field allows manual entry (app): Editable text field. Barcode scanner auto-fills, manual typing as fallback.

DataJoint: Not implemented (owned by @ktshah04). Commented integration point in push_to_datajoint() references the new get_fin() helper in recording_db.py.

Server Changes (this PR)

Modified: multi_camera/backend/recording_db.py

• New ParticipantFIN model: id (PK), participant_id (Integer FK → participants.id, unique, not null), fin (String, not null), created_at, updated_at
• Participant gains a back-reference: fin_record = relationship("ParticipantFIN", uselist=False, back_populates="participant")
• New _get_or_create_participant(db, participant_name) helper (factored out from existing _get_or_create_session())
• store_fin(db, participant_name, fin) — upsert (creates participant if needed)
• get_fin(db, participant_name) → Optional[str]
• push_to_datajoint() TODO updated to reference get_fin() from this same module

Modified: multi_camera/backend/fastapi.py

• set_session() gains optional fin: Optional[str] = None query parameter
• Uses the existing db_dependency() (no separate PHI dependency)
• If fin is non-empty after session creation: calls store_fin(db, participant_name=subject_id, fin=fin.strip())
• FIN value is not logged. Only logs that a FIN was stored.
• Response model (Session) unchanged — FIN is not returned

Deleted: multi_camera/backend/phi_db.py

Replaced by the additions to recording_db.py.

App Changes (already on feature/fin-field in capture-app)

State model (patient_info_state.dart)

• New fin field (String, default '')
• New bool get hasFin => fin.trim().isNotEmpty
• FIN is optional — does not gate session creation

Controller (patient_info_controller.dart)

• updateFin(String value), clearFin()
• updatePatientId() does NOT clear FIN
• createSession() passes FIN to repository if non-empty

Repository (prepare_repository.dart)

• createPreparation() gains optional String? fin parameter
• Includes 'fin': fin in query parameters when non-null

Session creation screen (patient_info_screen.dart)

• Patient ID field: barcode scanner icon removed (manual-entry only)
• New FIN field below Patient ID in the same card; editable, with scanner + clear suffix buttons
• Card title: "Patient ID" → "Patient Identification"
• Scanner callback: controller.updatePatientId(value) → controller.updateFin(value)

Barcode scanner sheet (barcode_scanner_sheet.dart)

• Header: "Scan Patient ID Barcode" → "Scan Wristband Barcode"
• Instruction: "Align Aztec barcode within the frame" → "Align wristband barcode within the frame"

Edge Cases

Scenario	Behavior
FIN scanned before patient ID entered	FIN populates. User types ID. Both sent on session create.
FIN scanned after session created	FIN field disabled (locked with session).
Patient ID changed after FIN scanned	FIN preserved. Belongs to wristband, not typed ID.
No FIN provided	Session created without FIN. No DB write.
Same participant, different FIN	Upsert overwrites previous FIN for that participant.

Verification

1. Backend: POST /api/v1/session?subject_id=test01&fin=12345 → inspect data/recordings.db and confirm a participant_fin row links to participants.name = test01. Verify data/phi.db is not created. Repeat with same participant + different FIN → verify upsert. Call without fin for a fresh participant → verify no DB write.
2. App: Patient ID field has no scanner icon. FIN field shows scanner icon, is editable. Scanner populates FIN. Manual typing works. FIN sent in API call on session create. FIN locked after session creation.

[loopback]

Addressed review feedback: dropped the separate data/phi.db and consolidated FIN storage into the existing recordings.db.

• Deleted multi_camera/backend/phi_db.py
• Added ParticipantFIN model to recording_db.py with an integer FK to participants.id (matches the convention used by Session/Recording/Imported/Photo)
• Factored out _get_or_create_participant() so set_session() can lazily create the participant row when (and only when) a FIN is provided — the no-FIN flow still does not write to the DB
• set_session() now uses the existing db_dependency() instead of a separate PHI dependency
• Updated the DataJoint TODO in push_to_datajoint() to note that proper PHI access control belongs in the export layer

API contract is unchanged (POST /api/v1/session?subject_id=...&fin=...), so the app-side commits already on feature/fin-field in capture-app need no changes.

Pushed as 81f90f1. PR description updated to reflect the new design.