Campaign_Tracker/_bmad-output/implementation-artifacts/2-3-election-cycle-key-dates.md

Story 2.3: Election-Cycle Key Dates

Status: ready-for-dev

Story

As a client services staff member, I want to define election-cycle key dates for data files, proofing, pickups, deliveries, and mail activities, so that the election timeline is established and visible to all operational teams.

Acceptance Criteria

1. Given an election-cycle job exists When a client services user opens the key dates section Then they can enter dates for: data file receipt, proofing, customer envelope pickup, customer envelope delivery, purple envelope pickup, purple envelope delivery, blue envelope pickup, blue envelope delivery, sort dates, mail dates, and tray delivery
2. Given a key date is entered and saved When the job is reloaded Then all entered dates persist and are visible in the job's date summary view
3. Given a key date entry would create a logical conflict (e.g., mail date before sort date) When the conflicting date is entered Then an inline warning identifies the conflict with specific field names — the save is not blocked but the warning is persistent until resolved
4. Given a key date is updated When saved Then the change is recorded in the audit log with actor identity and timestamp
5. Given a user enters dates via keyboard When using the date picker controls Then dates are enterable via keyboard without requiring mouse interaction (UX-DR9)

Tasks / Subtasks

• Backend: persist election-cycle key dates (AC: #1, #2, #4)
  • Extend the election-cycle job extension model with the full key date set: data file receipt, proofing, customer/purple/blue envelope pickup and delivery, sort date(s), mail date(s), tray delivery
  • Add GET and PUT/PATCH endpoints for key dates scoped to a cycle job, authorized for client services
  • Emit audit events on each saved date change including before/after values, actor, and timestamp via the shared audit logger
• Backend: conflict detection (AC: #3)
  • Implement a non-blocking validator that returns structured conflict warnings naming each conflicting field pair (e.g., mail before sort)
  • Persist warnings as derived state — saves succeed regardless; warnings remain visible until the underlying values are fixed
• Frontend: key dates editor (AC: #1, #2, #3, #5)
  • Add the key dates section to the cycle job detail view with one date control per field, grouped logically (intake → production → mail → delivery)
  • Render persistent inline warnings for each conflict returned by the backend, identifying both fields by name
  • Use Ant Design DatePicker (or equivalent) configured for keyboard entry per UX-DR9
  • Provide a date summary view that reads back all persisted values
• Tests & evidence (AC: #1–#5)
  • Backend tests for persistence, conflict detection rules, audit emission, RBAC
  • Frontend tests for save round-trip, conflict warning rendering, keyboard date entry
  • Document changed files and any config notes

Dev Notes

• Conflict detection is a warning, not a block. Resist the urge to gate saves — the rule is explicit: persistent warning until resolved.
• Use the existing audit logger from Story 1.5; do not introduce a parallel audit channel for date changes.
• Date storage must remain in extension tables — no writes to legacy Access. Surface dates to downstream stories (2.4 prior-cycle defaults, 2.5 readiness) via the cycle job read model.
• UX-DR9 keyboard support is a hard requirement — verify with a keyboard-only test path.
• Keep changes scoped to this story; readiness/publish behavior is Story 2.5.

Project Structure Notes

• Backend: Campaign_Tracker.Server/ — extend the election-cycle feature folder added in Story 2.2
• Frontend: campaign-tracker-client/ — extend the cycle job detail view with the key dates editor
• Story artifacts: _bmad-output/implementation-artifacts/

References

• Story source: _bmad-output/planning-artifacts/epics.md (Epic 2 / Story 2.3)
• Architecture constraints: _bmad-output/planning-artifacts/architecture.md
• UX patterns: _bmad-output/planning-artifacts/ux-design-specification.md (UX-DR9 keyboard accessibility)
• Prior stories: Story 2.2 — election-cycle job model; Story 1.5 — shared audit logging

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

• Story generated from epic source and architecture/UX planning artifacts.

Completion Notes List

• Story context created and marked ready-for-dev.

File List

Change Log