feat: initial implementation
This commit is contained in:
commit
e29da874ee
39 files changed
+2309
No files matched your search
@@ -0,0 +1,28 @@
|
||||
# Architecture
|
||||
|
||||
## Runtime
|
||||
|
||||
Single FastAPI process with server-rendered HTML and a SQLite database volume. This keeps deployment suitable for a small VPS, NAS or home server.
|
||||
|
||||
## Layers
|
||||
|
||||
- `models.py`: persistence schema.
|
||||
- `scheduling.py`: deterministic month/rotation generation.
|
||||
- `web.py`: authentication, admin editing and change-request orchestration.
|
||||
- `notifications.py`: synchronous SMTP adapter + durable send log.
|
||||
- `cli.py`: maintenance commands that can be run manually or by cron.
|
||||
|
||||
## Data lifecycle
|
||||
|
||||
1. Visiting a month calls `ensure_month_assignments`.
|
||||
2. Missing Night rows are created unassigned.
|
||||
3. Missing lunch rows are created from each independent rotation.
|
||||
4. Admin assigns/overrides rows through the month editor.
|
||||
5. Member change requests operate on concrete assignment IDs.
|
||||
6. Email is attempted after the database action commits.
|
||||
|
||||
## Deployment
|
||||
|
||||
`docker-compose.yml` mounts `./data` at `/app/data`, so the SQLite DB persists across image rebuilds.
|
||||
|
||||
For larger installations, the SQLAlchemy configuration can point to PostgreSQL, but the project intentionally ships only the SQLite deployment path today.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Domain model
|
||||
|
||||
## Schedules vs assignments
|
||||
|
||||
A **schedule** describes when a duty exists and how its initial assignee is chosen. An **assignment** is the actual duty on a concrete date. Once an assignment exists, it is not recalculated from the schedule.
|
||||
|
||||
This distinction is intentional: editing a rotation must not retroactively change an already published month.
|
||||
|
||||
## Seeded schedules
|
||||
|
||||
### Night
|
||||
|
||||
- Exists every day (`Monday` through `Sunday`).
|
||||
- Type: `fixed`.
|
||||
- Generation creates an unassigned row for every date.
|
||||
- An administrator assigns a person for each date in **Manage month**.
|
||||
- Once assigned, it remains fixed until explicitly edited or transferred through an approved change request.
|
||||
|
||||
### Saturday Lunch
|
||||
|
||||
- Saturdays only.
|
||||
- Type: `rotation`.
|
||||
- Has its own ordered member list.
|
||||
- Uses an anchor date to continue the rotation across month boundaries.
|
||||
|
||||
### Sunday Lunch
|
||||
|
||||
- Sundays only.
|
||||
- Type: `rotation`.
|
||||
- Has its own ordered member list, independent of Saturday.
|
||||
|
||||
The data model supports a schedule matching multiple weekdays even though the seeded lunch schedules each use one day.
|
||||
|
||||
## Rotation generation
|
||||
|
||||
For a rotation schedule, the member is chosen from the ordered active rotation members using the number of matching schedule days from the anchor date to the target date modulo member count.
|
||||
|
||||
Only missing assignments are generated. Existing rows are never rewritten.
|
||||
|
||||
## Change request state machine
|
||||
|
||||
`open` → `pending_approval` → `approved`
|
||||
|
||||
Other terminal states: `rejected`, `cancelled`.
|
||||
|
||||
- A member can offer one of their future/current assignments to a specific active member or to anyone.
|
||||
- The requester cannot accept their own request.
|
||||
- A targeted request can only be accepted/rejected by that target.
|
||||
- An open request can be accepted by any other active member.
|
||||
- If the schedule requires manager approval, acceptance moves to `pending_approval`.
|
||||
- Approval transfers the assignment and sets its source to `swap`.
|
||||
- If the requester no longer owns the assignment, the request must not be applied.
|
||||
|
||||
## Notifications
|
||||
|
||||
Email is optional per user and per installation.
|
||||
|
||||
Events include:
|
||||
- assignment updated/removed by admin;
|
||||
- change requested;
|
||||
- change accepted;
|
||||
- manager approval required;
|
||||
- change approved/rejected;
|
||||
- shift reminder.
|
||||
|
||||
An email error is logged but must not undo a scheduling action.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Roadmap / intentionally deferred
|
||||
|
||||
Good next additions if the association needs them:
|
||||
|
||||
- Alembic migrations before production schema evolution.
|
||||
- Password self-service and forgot-password flow.
|
||||
- Phone notifications via an explicit SMS/WhatsApp provider.
|
||||
- iCalendar (`.ics`) export / personal calendar subscription.
|
||||
- Holiday/special-event exceptions.
|
||||
- Optional schedule eligibility groups.
|
||||
- Audit log for every admin assignment edit.
|
||||
- PostgreSQL deployment profile and automated backups.
|
||||
- Localization (Portuguese/English).
|
||||
|
||||
Not planned unless specifically requested: payroll, attendance/time clock, HR records, leave accrual, performance management.
|
||||
Reference in new issue
Block a user