# Functional Specification — v3 (Markdown edition)

Task & Job Description Management · mirrors the client-facing `Task-Management-Spec-v3.docx` (3 Aug 2026, integrates client answers of 2 Aug).
Decided points are marked **[client — Qn]**. Open points are `A…G` → see `machine/open-points.tsv`.

## 1 · What this system does

Web application for ≈**400 employees** across ≈**45 departments**. Every employee logs in with a personal account and sees: what they have to do, what is waiting for them, and their job description. Managers create and assign tasks; finished work is checked (and sample-verified); management gets a live overview per department plus workload and KPI data.
Interface is **bilingual English / Thai**; the client adds English names for everyone in their data. **[client — Q7]**

## 2 · Core principle: positions, not people

Every task and job description attaches to a **position** (e.g. "HR Manager"), never to a person. People are the current **holders** of positions.

- Employee leaves → only the name is cleared; the position keeps job description, tasks, SOP links, history.
- New employee on the position inherits everything — the job description doubles as training material.
- Tasks can be **copied** between positions or **moved**, without losing history.
- **One person holds exactly one position.** Temporary cover = temporary task copy, never a second position. **[client — Q4]**

## 3 · Access levels

Six client levels collapse into three permission tiers (canonical: `machine/roles.json`):

| Tier | Members | Can create & assign for | Also |
|---|---|---|---|
| Admin | Roma · Narin · HR Manager | every position, every department | manages departments, positions, holders, logins; sees all KPI |
| Manager level | Manager · Assistant Manager · Supervisor · Line Leader | own department (exact who→whom matrix: **open point A**) | check/verify, team overview, overdue reminders |
| Staff | everyone else | themselves only (personal to-dos, below) | start, finish, report an issue |

- **Staff personal to-dos** **[client — Q2]**: a *recurring* self to-do is saved and **visible to the manager**; a *one-time* self to-do stays private, no check/verify. *(confirmation pending — open point G)*
- **Logins** **[client — Q10]**: the old employee code (e.g. `00002202`) is **not** the username — stored as a sync ID for the legacy database. Username format & password resets: **open point D**.

## 4 · What each user sees

- **Staff** — dashboard with exactly three tabs: Notifications · My Tasks (day/week/month; Start / Finish / Report issue; + own to-dos) · My Job Description (read-only).
- **Manager level** — same, plus: create & assign within department · check & verify · team overview · overdue reminders with note.
- **Admin** — everything, across all departments, plus admin-only tabs: departments & positions tables · people→position assignment · accounts & logins · KPI/evaluation.

## 5 · A task and its fields

Canonical list: `machine/task-fields.tsv`. Summary:

| Field | Notes |
|---|---|
| Description | what has to be done |
| Occurrence | `once / daily / weekly / monthly / quarterly / general` — **general** duties live in the job description only, never tracked; **once** added by client |
| Deadline | main date for one-time tasks; recurring cut-offs = **open point E** |
| Fixed day option | e.g. every 15th; auto-shifted off weekends/holidays (annual holiday calendar, Admin-maintained); proposal: shift to **next** working day |
| Checker | checks **every** task — normally the direct supervisor; approval **completes** the task **[client — Q1]** |
| Verifier | **random sample audit** on completed tasks; optional per task **[client — Q1]** *(confirmation pending — open point F)* |
| Report to deliver / Example of report / WI-SOP | free text + links |
| Time to do task | minutes; feeds workload |
| Customer tag | optional customer-DB ID for per-customer analytics *(client addition)* |
| Active / Not active | deactivate, never delete |
| Created by | recorded automatically (who + when) |

## 6 · The life of a task

```mermaid
stateDiagram-v2
    [*] --> todo : instance generated / task assigned
    todo --> started : staff starts
    started --> finished : staff marks done
    finished --> checked : Checker approves — task COMPLETE
    finished --> todo : Checker sends back (with note)
    checked --> verified : Verifier random sample (audit, optional)
    todo --> missed : recurring only — not done by cut-off (open points C & E)
    started --> missed : recurring only — not done by cut-off (open points C & E)
```

- `late` is **not a status**: any open task past its date shows a red *late* badge; manager can send a reminder with a note.
- `missed` is written only by the scheduled cut-off evaluation, only for recurring instances — behaviour next day (**stays vs removed**) = **open point C** (Narin).

### One-time tasks *(client addition)*

```mermaid
flowchart LR
    A[Creator makes task\none-time + deadline] --> B[Assigned to person]
    B --> C[Assignee marks Finished]
    C --> D[Creator notified\nin-app · ntfy]
    D --> E[Creator closes ✓]
```

Creator plays the Checker role by default. One-time tasks appear in My Tasks with their deadline and count in workload/reporting like any other task.

## 7 · Scheduling & recurrence

- **One-time**: single deadline, no recurrence.
- **Recurring** (daily/weekly/monthly/quarterly): instances generated automatically by the nightly job — idempotent via unique index on `recurring_id + due_date`.
- **Fixed-day** tasks shift off weekends/holidays to the **next working day** (proposal, client silent = accepted).
- **Work-day patterns**: Mon–Fri or Mon–Sat per employee; Saturday instances only for Mon–Sat people; shifting respects the pattern.
- **General** duties never generate instances.

## 8 · Notifications

Channels **[client — Q6, re-scoped]**: in-app + SSE (real time) and **ntfy** system notifications (LAN, offline-capable). There is **no Mattermost today** — chat-vs-notify is an open audit; if chat is wanted later it plugs in as one more driver (see `architecture.md` §4).
Events: task assigned · sent back · overdue reminder · one-time finished (→ creator) · deadline approaching *(proposal)*.

## 9 · Managing change

- Copy task sets between positions; permanent moves remove from source.
- Temporary cover: tasks **temporarily copied** into the covering person's own position, auto-removed at end. **[client — Q4]**
- Deactivate, never delete; every creation/change recorded (who, when).
- Employee leaves → name cleared; offboarding reassigns open instances & templates in one transaction; history stays attributed.
- Structure tables (departments, positions, holders) are Admin-only.

## 10 · Overview, workload & KPI

- Manager team summary (layout after "Bastien's Team-Dashboard example" — **open point B**): late, waiting for check/verify, workload per person.
- Workload = sum of time-to-do per person.
- KPI from completion history (on time / late / missed), visible to **Admin + each manager for their own department**. **[client — Q9]**
- Customer tag → per-customer analytics (tasks & total time per customer).

## 11 · Open points (A–G)

Canonical: `machine/open-points.tsv`. **C and E block the recurrence engine** — see `architecture.md` §12.

| ID | (Q) | Title | Blocks |
|---|---|---|---|
| A | Q3 | Assignment matrix (client table to come) | nothing — provisional default in place |
| B | Q5 | Team-Dashboard example | one screen's layout |
| C | Q8 | Missed behaviour next day (Narin) | **CORE — recurrence engine** |
| D | Q10 | Username format & resets | login screen only |
| E | Q11 | Cut-offs & timestamps | **CORE — recurrence engine & KPI truth** |
| F | Q1 | Confirm verifier = random sample | nothing — building stated reading |
| G | Q2 | Confirm one-time self to-dos private | nothing — building stated reading |