[Feature]: Procedure for Handling Unusable QR Codes (`surveyId`)

[ihsankahveci]

Pre-flight checklist

• I have searched the existing issues

Problem to solve

When a user starts a survey using a QR code (surveyId) but is immediately halted due to a user error (e.g., incorrectly answering an age-screening question), the initial surveyId becomes unusable. Currently, this would make it impossible to start another survey for the same participant without losing crucial information.

We need a defined procedure to allow the participant to restart the survey while maintaining two crucial constraints:

• Unique Data Integrity: Each participant should have only one unique surveyId.
• Referral Chain Integrity: The link to the original referrer must be preserved in the new record.

Proposed solution or API

I can think of two possible ways to tackle this issue.

Option 1: Overriding Soft Delete

This approach involves immediately correcting the bad entry to allow the same participant to use their original identifier.

Mechanism: The superuser performs a Hard Delete on the initial, unusable record (bypassing the standard soft-delete policy) and then a volunteer immediately re-enters the original QR code surveyId.

Permissions: This action must be restricted to the superuser role.

Challenge: This breaks the standard Soft Delete policy that is active during data collection, and makes backend implementation more complex.

Option 2: Generating a new surveyId with a given referredBySurveyId

This approach is generally cleaner as it maintains the existing Soft Delete policy and creates a new, distinct record.

Mechanism: A new, random surveyId is generated for the participant (similar to the "start without referral" workflow). Crucially, the new surveyId record must explicitly set its referredBySurveyID field to match the referredBySurveyID of the original, now-unusable surveyId.

Permissions: This action must be restricted to the superuser role.

Challenge: This approach requires a new UI design to implement the suggested workflow.

Alternatives considered

In the current version of the app, this problem is solved manually:

• The faulty entry is kept as is.
• The volunteer "starts a new survey without a referral" for the participant.
• The volunteer leaves a manual note on the app indicating that this new entry replaces the previous faulty surveyId.
• During the post-hoc analysis, the superuser manually updates the referredBySurveyID field of the new entry to meet data integrity requirements.

This manual process is prone to errors and requires significant manual intervention after data collection.

Additional context

No response

[anantmittal]

@ihsankahveci: Why not simply let superuser edit a survey, irrespective of whether it is completed or not?

[ihsankahveci]

Yeah, that should work for now. We just need to have a clear documentation for "error handling".