# Story 2.3: Election-Cycle Key Dates

Status: ready-for-dev

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## 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