94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# 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)
|
|
- `visibility` (`public` or `private`)
|
|
- `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.
|
|
- Queries for public UI/ICS/sidebar must include private events with privacy redaction (time/date shown, non-time content masked).
|
|
|
|
## 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
|