thatguygriff/walkies
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

Covert requirements to feature specs

Browse Source
This commit is contained in:
James Griffin-Allwood
2026-04-07 10:23:26 -03:00
parent 67335f0b45
commit b838c66bb1
8 changed files with 342 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/features/check-in.md Normal file
View File

@@ -0,0 +1,37 @@
# Feature: Check-In & Check-Out
**Source:** VSMS Functional Requirements v1.1, Section 7
---
## Kiosk (On-Site)
Check-in and check-out are performed via a **shared web-based kiosk** at the shelter, accessible only from a designated on-site device/URL. No individual volunteer login is required — volunteers tap their name from a list.
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-C01** | The kiosk displays only volunteers assigned to shifts occurring **today**. | |
| **FR-C02** | A volunteer taps their name to check in. They tap again to check out. | No individual login required on the kiosk. |
| **FR-C03** | A volunteer not on today's shift list can still check in as an **unscheduled walk-in**. Admin is notified of any unscheduled check-in. | |
| **FR-C04** | The kiosk cannot access any Admin features or other system views. | |
---
## Remote Check-In View (Dog Log Monitors)
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-C05** | Volunteers with the **Dog Log Monitor** operational role can access a **read-only live view** of today's check-in status from any device, including from home. | View-only — no check-in/check-out actions can be performed remotely. Authentication required. |
---
## Attendance Classification
The system automatically classifies each volunteer's attendance for every shift:
| Status | Condition | Visible To |
|--------|-----------|------------|
| On Time | Checked in within 15 minutes of shift start | Admin + volunteers on that shift |
| Late | Checked in more than 15 minutes after shift start | Admin + volunteers on that shift |
| No Show | Never checked in before shift end | Admin only |
| Completed | Checked in and checked out | Admin + volunteers on that shift |

73
docs/features/notifications.md Normal file
View File

@@ -0,0 +1,73 @@
# Feature: Notifications
**Source:** VSMS Functional Requirements v1.1, Section 5
---
## Delivery
- **Email is required** for all notifications in MVP.
- SMS is nice-to-have for a future release.
- All Admin notifications are email only.
---
## Monthly Schedule Publish
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-N01** | When Admin publishes a month's schedule, each assigned volunteer receives **a single email** listing all their shifts for that month. | One email per volunteer, not one per shift. |
| **FR-N02** | The monthly email includes a single **'I've seen my schedule'** acknowledgement button. Clicking it marks the volunteer as acknowledged for that entire month. The email instructs: if they cannot make any shift, they must log in and book time off. | Acknowledgement covers the whole month — not per-shift. |
| **FR-N03** | Admin can see acknowledged vs. unacknowledged status per volunteer on the schedule view. Unacknowledged volunteers are visually flagged. | |
> **✦ Nice to Have (post-MVP):** If a volunteer has not acknowledged within 3 days of the monthly publish email, the system automatically sends them a reminder.
---
## Open Decisions
- **Default acknowledgement state:** If a volunteer never responds to the monthly email, are their shifts treated as acknowledged or unacknowledged? *(⚠ Open Decision)*
- **Time-off link in monthly email:** Should the email include a direct link to the time-off page for volunteers who know they cannot attend a shift? *(⚠ Open Decision)*
---
## Shift Reminders
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-N04** | **24 hours** and **1 hour** before each shift, all assigned volunteers receive a reminder notification. | |
| **FR-N05** | The 24-hour reminder includes two actions: **'I'll be there'** and **'Cannot Attend'**. | |
| **FR-N06** | If a volunteer clicks 'Cannot Attend', they must select a mandatory reason before submitting. | Options: Sick, Emergency, Work conflict, Other (free text) |
| **FR-N07** | On 'Cannot Attend': the shift spot is marked open, the cancellation reason is recorded, and Admin is notified immediately. | |
---
## Other Volunteer Notifications
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-N08** | When a published shift is edited (assignments or capacity changed), all volunteers assigned to that shift are notified and their acknowledgement status is reset. | |
| **FR-N09** | When a volunteer is added to a shift mid-month (after publishing), they receive a notification about the newly added shift. | |
| **FR-N10** | When a published month is retracted (unpublished), all assigned volunteers are notified. | |
---
## Admin Notifications
Each Admin can configure which of the following they receive. All delivered by email, individually per event.
| FR ID | Event | Content |
|-------|-------|---------|
| **FR-N11** | Volunteer clicks 'Cannot Attend' | Volunteer name, shift details, reason provided |
| **FR-N12** | Volunteer submits time off | Volunteer name, dates, optional reason |
| **FR-N13** | Volunteer claims an open shift | — |
| **FR-N14** | Shift drops below minimum volunteer capacity | One alert per threshold breach |
| **FR-N15** | Trainee becomes eligible for promotion (2 shifts completed) | Informational only — promotion is always a manual action |
> **TBD:** Admin notification configurability — whether this is a simple toggle list or something more complex depends on implementation effort.
---
## Open Decisions
- **Understaffing alert timing:** How many days before a shift should Admin be alerted if it is still below minimum capacity? Admin-configurable — default value TBD. *(⚠ Open Decision)*

29
docs/features/open-shifts.md Normal file
View File

@@ -0,0 +1,29 @@
# Feature: Open Shifts
**Source:** VSMS Functional Requirements v1.1, Section 6
---
## Visibility
All Volunteers (with or without the Trainee flag) can see the full schedule including:
- All assigned volunteers and their operational roles
- Which specific roles are still needed on each shift (e.g. `1 Behaviour Team needed`)
Open spots show the **role gap**, not just a headcount.
---
## Claiming Open Shifts
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-O01** | Any Volunteer **without** the Trainee flag can claim an open shift. Claims are first-come first-served and confirmed automatically — no Admin approval required. | Trainees can see open shifts but cannot claim them. |
| **FR-O02** | A volunteer is blocked from claiming a shift if they have approved time off on that date. They are directed to remove their time off first. | |
| **FR-O03** | When a volunteer claims a shift, Admin is notified immediately. | |
---
## Floater Notifications *(Nice to Have — not in MVP)*
> **✦ Post-MVP:** When a shift spot opens, Floaters are notified first by email. After a set window (default: 1 week), volunteers who do not already have a shift that day are also notified. Floaters do not have an exclusive claim window — any eligible volunteer can claim at any time via the schedule view.

26
docs/features/reporting.md Normal file
View File

@@ -0,0 +1,26 @@
# Feature: Reporting
**Source:** VSMS Functional Requirements v1.1, Section 9
---
All reports are **Admin-only** and displayed on-screen. No data export is required for MVP.
---
## Per-Volunteer Reports
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-R01** | Admin can view a report per individual volunteer showing: total no-shows, total late arrivals, and full cancellation history with reasons. | Filterable by date range. |
| **FR-R02** | Admin can view total time off taken per individual volunteer. | Filterable by date range. |
| **FR-R03** | Admin can view an **aggregate summary** across all volunteers: total no-shows, late arrivals, and cancellations for a given period. | Filterable by date range. |
| **FR-R04** | The report displays volunteers as rows and dates as columns, showing each volunteer's cumulative count of on-time arrivals, absences, late cancellations, and no-shows. Allows admins to quickly assess and compare volunteer reliability at a glance. | Filterable by date range. |
---
## Per-Shift Reports
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-R05** | Admin can view a report per shift showing: open spots at shift time and which specific roles were unfilled. | Note: labelled FR-R04 in source doc (duplicate ID) — renumbered FR-R05 here. |

24
docs/features/schedule-view.md Normal file
View File

@@ -0,0 +1,24 @@
# Feature: Schedule View
**Source:** VSMS Functional Requirements v1.1, Section 8
---
## Volunteer Weekly Calendar
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-V01** | All volunteers access the schedule via a **weekly calendar view**. This is the primary (and only required) schedule view in MVP. | A list/grid view is not required for MVP. |
| **FR-V02** | Each shift on the calendar displays: date, time, all assigned volunteers, each volunteer's operational role, and which specific roles still have open spots. | |
| **FR-V03** | The logged-in volunteer's own name is **visually highlighted** on the calendar. | |
| **FR-V04** | Volunteers cannot edit any shift assignments — their own or others'. | |
| **FR-V05** | Volunteers can subscribe to a **personal calendar feed (iCal/ICS)** that syncs their assigned shifts to their preferred calendar app (Google Calendar, Apple Calendar, Outlook, etc.). The feed updates automatically when their shifts change. | Note: labelled FR-405 in source doc — assumed typo for FR-V05. |
---
## Admin Coverage Dashboard
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-V06** | Admin has a **coverage dashboard** showing the health of the current and upcoming month's shifts at a glance — highlighting shifts that are understaffed (below minimum capacity) and volunteers who have not acknowledged the monthly schedule. | |
| **FR-V07** | Admin can drill into any shift to see full assignment details and acknowledgement statuses. | |

61
docs/features/scheduling.md Normal file
View File

@@ -0,0 +1,61 @@
# Feature: Scheduling & Publishing
**Source:** VSMS Functional Requirements v1.1, Section 3
---
## Shift Templates
Admins manage the recurring schedule through weekly shift templates. Each template defines the base structure for a shift that repeats each week.
**Template fields:**
- Name (e.g. `Morning Shift`)
- Day of week
- Start time and end time
- Minimum and maximum volunteer capacity (e.g. min 3, max 5)
- Role requirements per shift (e.g. 1 Behaviour Team, 3 Dog Shelter Volunteers, 1 Dog Log Monitor)
- Recurring volunteer assignments — volunteers assigned to a template automatically appear on every generated instance of that shift
### Template Requirements
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-S01** | Admin can create, edit, and delete shift templates. | Deleting a template does not affect already-generated shift instances. |
| **FR-S02** | Admin manually triggers shift generation for a given period (e.g. a month). The system generates instances from all active templates for that period. Duplicate generation is prevented. | Auto-rolling generation is out of scope for MVP. |
| **FR-S03** | Editing a shift template applies only to shift instances that have not yet been published. Published instances are protected from template changes. | Published instances can still be edited manually — see FR-S07/FR-S08. |
---
## Publishing
Generated shift instances are in **draft (unpublished)** state until Admin publishes them. Publishing makes the schedule visible to volunteers and triggers notifications.
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-S04** | Admin manually publishes a month's schedule. On publish, each assigned volunteer receives a single email listing all their shifts for that month. | See [notifications.md](notifications.md) for details. |
| **FR-S05** | Admin can unpublish a published month. All volunteers assigned to shifts in that month are notified that the schedule has been retracted. | Intended for accidental early-publish scenarios. |
| **FR-S06** | Admin can see unconfirmed volunteers (those who have not acknowledged the monthly schedule email) flagged on the schedule view. | |
---
## Editing Published Shifts
Admin can manually edit individual shift instances at any time, including after publishing. These edits do not affect the underlying template or other weeks.
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-S07** | Admin can adjust volunteer assignments on any individual shift instance (add or remove a specific volunteer for that occurrence only). | |
| **FR-S08** | Admin can adjust the min/max volunteer headcount on any individual shift instance. | |
| **FR-S09** | When Admin edits a published shift (assignments or capacity), all volunteers assigned to that shift have their confirmation status reset and must re-acknowledge. | Volunteers are notified of the change — see FR-N09. |
| **FR-S10** | When Admin adds a volunteer to a shift mid-month (after publishing), that volunteer receives a notification about the newly added shift. | See FR-N10. |
---
## State Model
```
Template → [generate] → Draft Instance → [publish] → Published Instance
↓
Admin can edit (FR-S07/S08)
Resets acknowledgement (FR-S09)
```

35
docs/features/time-off.md Normal file
View File

@@ -0,0 +1,35 @@
# Feature: Time Off Management
**Source:** VSMS Functional Requirements v1.1, Section 4
---
## Volunteer Time Off
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-T01** | Volunteers (including Trainees) can add time off for a single day or a date range. An optional reason can be provided. | |
| **FR-T02** | Volunteers can edit or delete their own **future** time off. | Past time off cannot be edited by volunteers. |
| **FR-T03** | If a volunteer submits time off that covers a day they are assigned to a shift, the system displays a clear warning before submission. On confirmation, the volunteer is automatically removed from those shift instances and Admin is notified. | |
| **FR-T04** | If Admin deletes a volunteer's time off, the volunteer is automatically re-added to any shift instances from which they were removed due to that time off. Admin is shown which shifts will be affected before confirming. | |
---
## Admin Time Off Controls
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-T05** | Admin can add, edit, and delete time off for any user. | |
| **FR-T06** | The system blocks Admin from assigning a volunteer to a shift if that volunteer has approved time off on that date. A clear warning is displayed. **The block cannot be overridden** — the time off must be removed first. | |
| **FR-T07** | If a volunteer attempts to claim an open shift that conflicts with their own time off, the system warns them to delete their time off first. They cannot claim the shift until the conflict is resolved. | |
---
## Conflict Rules Summary
| Scenario | Behaviour |
|----------|-----------|
| Volunteer submits time off overlapping an assigned shift | Warning shown → on confirm, removed from shift, Admin notified |
| Admin tries to assign volunteer with time off on that date | Hard block — must remove time off first |
| Volunteer tries to claim open shift with conflicting time off | Blocked with prompt to resolve time off first |
| Admin deletes volunteer's time off | Volunteer re-added to affected shifts; Admin sees impact preview first |

57
docs/features/user-accounts.md Normal file
View File

@@ -0,0 +1,57 @@
# Feature: User Accounts & Profiles
**Source:** VSMS Functional Requirements v1.1, Section 2
---
## Roles
There are two account types: **Admin** and **Volunteer**. Multiple Admin accounts are supported. Admins are not assigned to volunteer shifts.
**Trainee** is not a separate account type — it is a permission flag on a Volunteer account that blocks open shift claiming. All other Volunteer behaviour is identical.
### Operational Roles
Assigned by Admin. A volunteer may hold multiple simultaneously. Displayed on schedule and calendar views.
- Behaviour Team
- Dog Log Monitor
- Dog Shelter Volunteer
- Trainee *(mirrors the Trainee permission flag)*
- Floater *(covers open shifts; can also hold a recurring assigned shift)*
---
## Profile Data
| Field | Required | Notes |
|-------|----------|-------|
| Full name | Yes | Editable by volunteer |
| Email address | Yes | Used for login and notifications |
| Phone number | No | Stored for reference; not used for notifications in MVP |
| Operational role(s) | — | Set/edited by Admin only |
| Notification preference | — | Email only in MVP; email + SMS future |
| Internal Admin notes | — | Admin-only; not visible to volunteer |
| Last login date | — | Visible to Admin |
| Completed shift count | — | System-tracked; used to inform Trainee promotion |
Volunteers can edit: **name** and **phone number** only.
---
## Requirements
| FR ID | Requirement | Notes |
|-------|-------------|-------|
| **FR-U01** | Admin creates all accounts. No self-registration. Admin sets name, email, operational role(s), and Trainee flag at creation. | |
| **FR-U02** | On account creation, the system sends an invite email with an activation link. | Admin can resend if not yet activated. |
| **FR-U03** | Login uses invite-based flow. Google Auth (OAuth) preferred if feasible; email/password with invite activation is the fallback. | No self-signup regardless of method. **TBD: implementation team to decide.** |
| **FR-U04** | Admin can deactivate a volunteer at any time. Volunteer is locked out immediately. Past shift records are preserved; name displays as `Name (inactive)` on past shifts. Deactivated accounts are hidden from active schedule and user list views. | |
| **FR-U05** | Admin can promote a Trainee to full Volunteer (remove Trainee flag) at any time. Completed shift count is displayed on their profile to inform the decision. Conventional threshold is 2 shifts, but promotion is always a manual Admin action. Removing the flag immediately grants open shift claiming. | |
| **FR-U06** | Admin can add, edit, and delete internal notes on any user profile. Notes are not visible to the volunteer. | |
---
## Open Decisions
- **Authentication:** Google Auth vs. email/password — implementation team to advise and recommend. *(TBD)*