# Data Requirements

## Purpose
Define requirements for calendar data storage in WordPress and for local testing data behavior.

## Scope
This document covers:

- Persistent plugin data in WordPress database
- Data model expectations for calendar entries and recurrence
- Data handling for local compatibility-harness testing

## Normative Boundaries
- This document defines high-level data requirements and test-data expectations.
- Concrete schema fields, constraints, and indexing are defined in `requirements/data_schema.md`.
- Recurrence exception semantics are defined in `requirements/recurrence_exceptions.md`.
- Runtime/code separation constraints are defined in `requirements/architecture.md`.

## Timezone Assumption
Unless explicitly overridden by a future requirement, all plugin dates and times are assumed to be in the `Europe/London` timezone.

## WordPress Database Storage
Plugin data must be stored using WordPress-compatible database access patterns.

Requirements:

- Plugin-owned tables use WordPress table prefix conventions (`$wpdb->prefix`).
- Schema creation/migration uses WordPress APIs (see lifecycle requirements).
- Data access uses WordPress database APIs (`$wpdb`) with prepared/safe queries.
- Stored records support full CRUD and recurrence features required by editor/web UI.

## Minimum Event Data Model
The stored model must support these fields (direct columns or normalized equivalents):

- Event identifier (internal primary key)
- `title`
- `location`
- `category`
- `all_day_event` flag
- `start_datetime`
- `end_datetime`
- `repeat_type` (`none`, `daily`, `weekly`, `monthly`, `yearly`, `custom`)
- Recurrence configuration (`interval`, `range_mode`, `count`, `until_date`, base unit)
- `description`
- Created/updated timestamps

## Data Integrity Requirements
- `title` and start time/date must be required.
- End must not be before start.
- Recurrence values must be internally consistent (e.g., positive interval/count).
- Deletes must not leave orphaned recurrence metadata or exception records.
- Migrations must preserve existing user data.

## Query and Retrieval Requirements
- Data model must support efficient retrieval by date range for day/week/month/year UI windows.
- Data model must support generation of recurrence occurrences for both web UI and ICS output.
- Queries for public UI must return only intended public event data.

## Local Testing Data Requirements
The local compatibility-harness test environment must support deterministic data setup and teardown.

Requirements:

- Provide seeded test data covering:
  - Single non-recurring events
  - All-day events
  - Each recurrence type
  - Custom recurrence with each range mode
  - Edge cases (month boundaries, leap year, DST transitions where relevant)
- Test runs must isolate state between cases (clean database state or controlled fixtures).
- Test data setup scripts/fixtures must be version-controlled under `tests/` and/or `compatibility-layer/`.

## Test Validation Data Requirements
Automated/local verification should include assertions for:

- CRUD persistence correctness
- Recurrence expansion correctness in 3-month preview windows
- Correct behavior of keep/remove data paths during uninstall
- Correct mapping readiness for ICS export fields

## Backup and Recovery (Server Data)
- Production/test server data changes should be recoverable via normal backup processes.
- Destructive operations (e.g., uninstall data removal) require explicit intent and must be test-covered.

## Documentation Requirements
Project docs must include:

- Current schema description
- Migration/versioning approach
- Local compatibility-harness usage
- Data retention behavior across install/upgrade/uninstall