Sync Conflicts - Quality Requirements

Version: 1.0
Last Updated: 2026-07-16

This document defines the quality standards and requirements for the Sync Conflicts feature.

Functional Requirements

FR-01: Conflict Detection

The system shall detect conflicts when:

A push request receives HTTP 409 from the data-service
Server data differs from client data after timestamp comparison

FR-02: Conflict Preservation

The system shall preserve both versions of conflicting data:

Server version stored in server_version JSONB field
Client version stored in client_version JSONB field
Both versions retained until explicit resolution

FR-03: Resolution Strategies

The system shall support the following resolution strategies:

server_wins: Accept server version, mark push record as failed
client_wins: Overwrite server with client version via PUT

FR-04: Tenant Isolation

All conflict operations shall be scoped to the current tenant via X-Tenant-ID header.

FR-05: Pagination

Conflict listing endpoints shall support pagination with skip and limit parameters.

Non-Functional Requirements

NFR-01: Performance

Conflict list retrieval shall complete within 2 seconds for datasets under 1000 records
Conflict resolution shall complete within 5 seconds for typical response sizes
Database indexes shall exist on tenant_id, response_id, and resolution

NFR-02: Availability

Conflict endpoints shall be available whenever sync-service is operational
Conflict resolution shall be idempotent (re-running same strategy has no additional effect)

NFR-03: Security

All endpoints require response:read permission
JWT tokens must be validated before processing
Tenant ID must be extracted from request state and cannot be overridden by client

NFR-04: Auditability

All conflicts shall be timestamped with created_at
All resolutions shall record resolved_at and resolved_by user
Conflict records shall not be deleted, only marked resolved

Validation Rules

V-01: Conflict Resolution

Cannot resolve an already-resolved conflict
Unknown strategies shall return HTTP 400
Missing conflict ID shall return HTTP 404

V-02: Data Integrity

response_id in conflict record must reference a valid response or push record
Both server_version and client_version must be valid JSON
Resolution field must be one of the defined strategies

Test Requirements

T-01: Unit Tests

The following scenarios shall have unit test coverage:

Conflict detection with timestamp comparison
Conflict detection with data comparison
Server wins resolution flow
Client wins resolution flow
Per-tenant conflict isolation

T-02: Integration Tests

End-to-end conflict creation during push
Conflict resolution via API
Permission enforcement verification
Multi-tenant isolation verification

T-03: Test Files

File	Purpose
`mobile/test/unit/conflict_resolution_test.dart`	Mobile conflict logic tests
`sync-service/tests/`	Backend conflict detection tests (to be created)

Operational Requirements

O-01: Monitoring

Conflict count metric should be available for dashboard display
Resolution attempts should be logged
Failed resolutions should emit warning-level logs

O-02: Backup

Conflict records are part of sync_db and follow standard backup procedures
Both versions in JSONB format are preserved in backups

O-03: Maintenance

Conflict records should be retained indefinitely for audit purposes
Push records with conflict status may be cleaned after resolution

Compliance Requirements

C-01: Data Protection

Conflicts contain response data subject to retention policies
Access to conflicts requires same permissions as response data
Deleted respondent data should cascade appropriately

Conflict records contain personal data from responses
Resolution does not create additional personal data exposure
Right to erasure applies to unresolved conflicts via respondent deletion