NTK-10004 — NTK-10004: Solution Design — Guide Schedule Overwrite Bug¶

Affected Capabilities¶

Affected Services¶

• svc-scheduling-orchestrator

Architecture Decisions¶

• ADR-010
• ADR-011

Solution Contents¶

• Requirements
• Analysis
• Decisions
• Impact Assessments (0)
• Implementation Guidance
• Risk Assessment
• Capability Mapping

Related Solutions¶

Solutions that share services or capabilities with this design:

Metadata¶

1. Problem Statement¶

The svc-scheduling-orchestrator's nightly and on-demand optimization pipeline overwrites guide enrichment data (vacation blocks, medical restrictions, certification notes, group size overrides) stored in the daily_schedules table. The root cause is a full entity replacement via PUT semantics that discards fields not in the orchestrator's DTO. A secondary issue exists: no concurrency control prevents race conditions when multiple regions optimize simultaneously.

Impact: 15-20 incorrect guide removals per day during peak periods. Safety-critical medical restrictions silently removed. Guide HR complaints escalating.

2. Root Cause Summary¶

See: investigations.md for full evidence chain.

3. Solution Overview¶

Phased Approach¶

Architecture Decision Records¶

• ADR-NTK10004-001: Switch from PUT to PATCH semantics (PROPOSED)
• ADR-NTK10004-002: Add optimistic locking to DailySchedule (PROPOSED)

See: decisions.md

4. Affected Services¶

See: impacts.md

5. Data Ownership Model¶

The core architectural fix is establishing explicit field ownership:

┌─────────────────────────────────────────────────────────┐
│                    daily_schedules                       │
├─────────────────────────┬───────────────────────────────┤
│  ORCHESTRATOR-OWNED     │  GUIDE-MANAGEMENT-OWNED       │
│  ─────────────────────  │  ───────────────────────────  │
│  guideId                │  guideNotes                   │
│  tripId                 │  guidePreferences             │
│  startTime              │                               │
│  endTime                │                               │
│  participantCount       │                               │
│  maxCapacity            │                               │
│  status                 │                               │
│  locationId             │                               │
│  scheduleDate           │                               │
├─────────────────────────┴───────────────────────────────┤
│  SHARED / SYSTEM                                         │
│  ─────────────────────────────────────────────────────── │
│  id, version, generatedAt, lastModifiedAt, lastModifiedBy│
└─────────────────────────────────────────────────────────┘

The PatchScheduleDto enforces this boundary structurally: it contains only orchestrator-owned fields. Guide-management-owned fields cannot be accidentally modified because they do not exist in the DTO.

6. Key Design Decisions¶

1. PATCH over read-merge-write: PATCH semantics enforce ownership at the API boundary. Read-merge-write would add latency and rely on fragile merge logic.

2. @Version over ETag: JPA @Version is simpler and integrates with Hibernate's built-in conflict detection. ETag-based HTTP concurrency is deferred as a future enhancement for external API consumers.

3. Deprecate PUT, don't remove it immediately: A sunset period allows undiscovered callers to be identified and migrated. Logging + metrics track PUT usage during the transition.

4. Three-sprint phased rollout: Phase 1 (PATCH) provides immediate safety relief. Phase 2 (locking) addresses the less frequent concurrency issue. Phase 3 (monitoring/governance) prevents recurrence.

7. Risks¶

See: risks.md

8. Assumptions¶

See: assumptions.md

9. Implementation Guidance¶

Detailed implementation steps with code samples are provided in guidance.md, including: - PatchScheduleDto class definition - patchSchedule() service method - PATCH controller endpoint - PUT deprecation pattern - Database migration SQL - @Retryable configuration for optimistic lock conflicts - Testing checklist (9 test cases)

10. Success Criteria¶

1. Zero enrichment data loss after optimization — monitored via guide.enrichment.nullified.count metric (target: 0)
2. Concurrent write conflicts detected — schedule.patch.retry metric shows conflicts are caught, not silent
3. PUT usage drops to zero within 2 sprints of PATCH availability
4. No guide HR complaints related to lost schedule data post-deployment
5. 15-20 daily incorrect removals reduced to 0