Care Plan Service — Sync Contract

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

Per-Aggregate Conflict Policy

Aggregate	Policy	Rationale
CarePlan	server_authoritative	Clinical artifact; version conflicts must be surfaced to the clinician. No silent merge of care plan metadata.
CarePlanGoal	server_authoritative	Goal targets and status are clinically significant; last-write-wins would create safety risk.
CarePlanActivity	server_authoritative	Activity status (especially completion) must not be silently overwritten.
CareTeamMember	server_authoritative	Team membership is replaced atomically via PUT /care-team; no partial merge.

Conflict Resolution Detail

• All mutating endpoints require the current version in the request body.
• If version does not match the database record, the server returns 409 VERSION_CONFLICT with the latest version and updatedAt so the client can refresh and retry.
• Offline clients (clinical workstations in low-connectivity environments) MUST read the latest version before submitting mutations.
• There is no automatic merge of concurrent edits. The second writer always loses and receives 409.

Offline Client Guidance

1. Cache the full care plan (including version) on load.
2. Apply local edits optimistically in UI.
3. On reconnect, attempt the mutation with the cached version.
4. If 409 is returned, present a diff to the clinician and require manual resolution.
5. Use Idempotency-Key header on all create operations to prevent duplicate resources on retry.

FHIR Read Surface (no conflict policy needed)

The FHIR R4 read surface is read-only for external consumers. No conflict policy applies to FHIR GET/search endpoints — they reflect the current authoritative state.