77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
# Recurrence Exception Requirements
|
|
|
|
## Purpose
|
|
Define normative behavior for recurring-event exception operations across admin UI, API, CalDAV, and ICS.
|
|
|
|
## Scope
|
|
This document covers:
|
|
|
|
- Single-occurrence delete and edit semantics
|
|
- Exception storage model
|
|
- Merge/precedence rules for recurrence expansion
|
|
- Cross-surface consistency requirements
|
|
|
|
## Core Principle
|
|
- A recurring event is one logical series keyed by stable series identity (`event_id`/`UID`).
|
|
- Exception operations modify occurrence behavior within that series.
|
|
- Exception operations must not split one series into multiple independent series unless explicitly invoked by a future "split series" feature.
|
|
|
|
## Exception Types
|
|
- `deleted_occurrence`: one generated occurrence is suppressed.
|
|
- `override_occurrence`: one generated occurrence is replaced with modified instance values.
|
|
|
|
## Delete-One-Occurrence Semantics
|
|
When a user deletes one occurrence of a recurring series:
|
|
|
|
- Add `deleted_occurrence` exception for the target occurrence key.
|
|
- Keep original series RRULE/repeat definition unchanged.
|
|
- Do not create a second series record.
|
|
- Future edits to series must still consider existing exceptions.
|
|
|
|
## Edit-One-Occurrence Semantics
|
|
When a user edits one occurrence in a recurring series:
|
|
|
|
- Add/update `override_occurrence` exception for the target occurrence key.
|
|
- Override payload contains changed fields for that occurrence.
|
|
- Parent series remains the source for non-overridden fields.
|
|
|
|
## Expansion Precedence Rules
|
|
Occurrence generation order:
|
|
|
|
1. Generate base occurrences from series rule.
|
|
2. Remove occurrences matching `deleted_occurrence`.
|
|
3. Apply `override_occurrence` records to matching occurrence keys.
|
|
4. Return sorted final set for window/query.
|
|
|
|
If both delete and override exist for the same occurrence key, the system must reject the conflicting write and require explicit conflict resolution.
|
|
|
|
## Validation Rules
|
|
- Exception target must correspond to a valid generated occurrence in series context.
|
|
- Duplicate exception entries for same occurrence key are not allowed.
|
|
- Exception operations on non-recurring events are rejected.
|
|
|
|
## CalDAV Representation
|
|
- Series remains same `UID`.
|
|
- Deleted occurrence represented with `EXDATE` and/or standards-compliant override pattern.
|
|
- Overridden occurrence represented with `RECURRENCE-ID` VEVENT override.
|
|
- Do not emit split UID sequences for single-occurrence deletes.
|
|
|
|
## ICS Representation
|
|
- Export includes base RRULE for series.
|
|
- Deleted occurrences exported as exceptions.
|
|
- Overridden occurrences exported as recurrence-id overrides.
|
|
- Consumer synchronization should observe missing/changed occurrence without series duplication.
|
|
|
|
## UI/API Behavior
|
|
- UI and API must expose "this occurrence only" actions distinctly from "entire series" actions.
|
|
- Confirmation messaging must clearly indicate operation scope.
|
|
- Audit records must capture actor, series, target occurrence key, and operation type.
|
|
|
|
## Verification Requirements
|
|
Acceptance should verify:
|
|
|
|
- Delete-one-occurrence removes only target occurrence.
|
|
- Series remains unified in storage and output.
|
|
- Override-one-occurrence updates only target occurrence.
|
|
- CalDAV/ICS outputs reflect same exception semantics as admin/API views.
|