diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..0fa0939 --- /dev/null +++ b/README.md @@ -0,0 +1,118 @@ +# ShiftPlanner + +A single-file employee shift scheduling application for a small team +(a hotel/spa-style operation: the UI references "Therme"). It runs entirely in +the browser — no server, no build step, no install, no account. + +Version: **1.0.0** (see `VERSION`) +Canonical source: `src/index.html` (2,789 lines, 136,212 bytes, md5 `37207b2227899603f90c42e59ff1875a`) + +## What it does + +- **Staff register** — add, edit and delete workers, each with role and + contracted hours per week. +- **Shift templates** — define reusable shifts with name, start/end time, + colour and required headcount, then apply a template to a day. +- **Month calendar** — one month at a time, with per-day shift blocks, assigned + workers, headcount limits (min/max) and free-text day notes. +- **Absence tracking** — record vacation, sick days and days off per worker; + availability checks respect them. +- **Automatic plan generation** — a step-through generator that fills the month + for selected workers, honouring: + - fairness priority (equal number of shifts / equal total hours / equal + weekend shifts), + - maximum consecutive working days, + - minimum rest hours between shifts, + - maximum workers per shift. +- **Conflict detection** — flags double-booking, rest-period violations and + consecutive-day overruns, with a conflict badge, "Fix conflicts" and + "Clear Day" actions. +- **Exports** — CSV of the month's roster, and JSON backup of the whole plan. +- **Import** — restore a previously exported JSON backup. +- **Light/dark theme**. + +## What the buyer gets + +``` +shiftplanner/ +├── VERSION 1.0.0 +├── README.md this file +├── CHANGELOG.md +├── LICENSE +├── src/ +│ └── index.html the complete application (open this) +├── docs/ +│ ├── CANONICAL.md measurement record: why this file is canonical +│ └── USAGE.md non-technical, step-by-step instructions +└── archive/ four earlier/variant copies, kept for reference + ├── mindtech__shiftplanner.html + ├── mindtech__downloads__shiftplanner.html + ├── mindtech__shiftplanner_v1.3.html + └── agando__shiftplanner_v1.3.html +``` + +One file is the whole product. There is nothing to compile and nothing to +deploy beyond copying `src/index.html` somewhere and opening it. + +## How to run it offline + +1. Copy `src/index.html` to the machine that will use it — a laptop, a USB + stick, a shared folder, anything. +2. Double-click it, or drag it into any modern browser (Chrome, Edge, Firefox, + Safari). +3. That's it. The app is fully self-contained. + +Verified: the file contains **0** `<script src=…>` tags, **0** `<link>` tags and +**0** `url(…)` asset references. All CSS and JavaScript are inline. Nothing is +fetched from a CDN, so it works with the network cable unplugged and from a +`file://` path. + +The optional AI advisor is the only part that talks to anything, and it talks +only to a server you run yourself (see below). With no AI server running, the +panel shows "Not connected (start Ollama)" and every scheduling feature still +works. + +### Optional: the AI advisor + +The right-hand panel answers questions about the current schedule and can +suggest changes. It uses a local [Ollama](https://ollama.com) instance: + +- Default endpoint: `http://localhost:11434`, editable in Settings and stored + in `localStorage['sp_ai_endpoint']`. +- Calls `GET {endpoint}/api/tags` to check the connection and list models, and + `POST {endpoint}/api/generate` to answer a question. +- Default model `llama3.2`; the UI also offers `mistral`, `llama3.1`, `phi3`, + `gemma2` and `minimax-m3:cloud`. The choice is stored in + `localStorage['sp_ai_model']`. +- No cloud AI service is contacted — there is no OpenAI, Anthropic or Google + endpoint anywhere in the file. + +If you do not want AI at all, ignore the panel; it is inert without a server. + +## Where the data lives + +**In the browser's `localStorage`, on that machine and in that browser profile. +Nowhere else.** There is no backend, no sync and no telemetry. + +| Key | Contents | +|---|---| +| `shiftplanner_v2` | the full application state: workers, shifts, assignments, custom shifts, templates, settings | +| `sp_ai_endpoint` | the AI server URL | +| `sp_ai_model` | the selected AI model | + +Consequences worth knowing: + +- Clearing site data / "clear browsing history including site data" for this + file **erases the schedule**. Use **Export JSON** regularly. +- The data does not follow the user to another browser or another computer. + Move it with **Export JSON** → **Import JSON**. +- Opening the file from a different path or a different browser profile gives a + different, empty store. + +## Archive + +`archive/` holds four older or variant copies of the same app, preserved +unmodified for reference. They are **not** part of the product and are not +maintained. Two of them contain a real drag-and-drop scheduler and a +multi-provider AI layer that the canonical build does not have — see +`docs/CANONICAL.md` §3 if you want to port those features forward. |