98 lines
7.8 KiB
Markdown
98 lines
7.8 KiB
Markdown
# Functional Requirements Document (FRD)
|
|
## SOP Governance Tool — Stage 1
|
|
|
|
Each requirement has an ID, description, and acceptance criteria (AC). Build modules in order M1→M7 (see 07-development-plan.md).
|
|
|
|
---
|
|
|
|
## M1 — Authentication & Users
|
|
|
|
**FR-1.1 Login/logout** — Email + password via Supabase Auth.
|
|
AC: Wrong password shows a friendly error; session persists across refresh; logout clears session.
|
|
|
|
**FR-1.2 User management (Admin)** — Admin creates users (name, email, role, department, preferred_language), deactivates users, changes roles.
|
|
AC: Deactivated users cannot log in; a Staff user cannot open any admin page (redirected).
|
|
|
|
**FR-1.3 Departments (Admin)** — Create/rename departments; assign users to one department.
|
|
AC: Deleting a department with users is blocked with a clear message.
|
|
|
|
**FR-1.4 Role guard** — Every page and API route enforces the role matrix in the PRD §4.
|
|
AC: A Staff JWT calling an admin API receives 403; verified by test.
|
|
|
|
## M2 — SOP Repository & Editor
|
|
|
|
**FR-2.1 SOP record** — Fields: code (e.g. WH-PICK-001), title, department, category, owner (user), status, review_months (3/6/12/24).
|
|
AC: Code is unique; list view filters by department, status, category; search by title/code.
|
|
|
|
**FR-2.2 Structured editor** — Sections: Purpose, Scope, Roles & Responsibilities, Procedure (ordered steps, each step = text + optional photo), Exceptions, Safety Notes, Required Records. Purpose + Procedure mandatory.
|
|
AC: Cannot submit for approval with a mandatory section empty; steps can be added, reordered, deleted; photos upload to Supabase Storage and preview inline.
|
|
|
|
**FR-2.3 Autosave drafts** — Editor autosaves every 10s or on blur.
|
|
AC: Refresh mid-edit loses at most 10 seconds of typing.
|
|
|
|
## M3 — Governance: Workflow, Versions, Audit
|
|
|
|
**FR-3.1 Status flow** — draft → submitted → approved → published; rejection returns submitted → draft with a required comment. Published SOPs edited again create a NEW draft version; the published version stays live until the new one is published.
|
|
AC: Illegal transitions (e.g. draft → published) are impossible via UI and API.
|
|
|
|
**FR-3.2 Approval (1 level)** — Approver/Admin sees a queue of submitted SOPs; approves or rejects with comment.
|
|
AC: Approval records approver id, timestamp, decision, comment; Editor is notified in-app.
|
|
|
|
**FR-3.3 Versioning** — First publish = 1.0. Each subsequent publish increments: minor edit → 1.1, "major revision" checkbox → 2.0. Published version content is immutable (stored snapshot).
|
|
AC: Version history list shows every version with date, publisher, change note; opening an old version renders its frozen content.
|
|
|
|
**FR-3.4 Audit log** — Append-only records for: sop.created, sop.edited, sop.submitted, sop.approved, sop.rejected, sop.published, sop.assigned, ack.recorded, user.created, user.role_changed.
|
|
AC: Log entries store actor, action, entity, timestamp, and detail JSON; Admin can filter by SOP and export CSV. No update/delete path exists.
|
|
|
|
**FR-3.5 Review reminders** — Dashboard flags SOPs past `published_at + review_months`.
|
|
AC: An overdue SOP shows a red "Review overdue" badge on dashboard and list.
|
|
|
|
## M4 — Distribution & Acknowledgement
|
|
|
|
**FR-4.1 Assignment** — On publish (or later), Admin assigns the SOP to one or more departments; all active Staff in those departments become assignees. New staff added to a department inherit its assignments.
|
|
AC: Assignee list is visible per SOP; unassigning a department removes pending (not completed) acknowledgement expectations.
|
|
|
|
**FR-4.2 Staff "My SOPs" page (mobile-first)** — Staff log in and see assigned published SOPs: "Needs acknowledgement" on top, then "Acknowledged". Content renders in the staff member's preferred_language if a translation exists, else English, with a language switcher.
|
|
AC: Loads fast on a phone; steps render with large text and photos; language switch is one tap.
|
|
|
|
**FR-4.3 Acknowledgement** — Button: "I have read and agree / Saya faham & setuju / 我已阅读并同意". Tap records user, SOP, version, language viewed, timestamp, and a typed-name confirmation field (acts as the signature).
|
|
AC: One acknowledgement per user per published version; a NEW published version resets the requirement (re-ack needed); record is immutable.
|
|
|
|
**FR-4.4 Share link** — Each published SOP has a link Staff can open after login (paste into a WhatsApp group manually for now).
|
|
AC: Link deep-links to that SOP in the viewer for an authenticated assignee; unauthenticated users hit login first, then land on the SOP.
|
|
|
|
## M5 — Dashboard & Reports
|
|
|
|
**FR-5.1 Dashboard (Admin/Approver)** — Cards: total published SOPs, drafts, pending approvals, overdue reviews. Table: per-SOP acknowledgement % with progress bar; filter by department. Second table: per-department overall %.
|
|
AC: Numbers reconcile with raw data (verified by a seeded test dataset).
|
|
|
|
**FR-5.2 Acknowledgement export** — Per SOP: CSV of assignees with acknowledged version/date/language or "outstanding".
|
|
AC: Opens correctly in Excel; includes SOP code, title, version in the header rows.
|
|
|
|
## M6 — AI Assistance
|
|
|
|
**FR-6.1 AI Draft** — Editor enters a plain-language description (and optionally pastes messy notes); server calls Anthropic API and returns a structured draft filling the FR-2.2 sections; Editor reviews/edits before saving.
|
|
AC: AI output populates the editor fields (never publishes anything); a failed AI call shows a retry-able error without losing the input; prompt + response stored in ai_log for cost tracking.
|
|
|
|
**FR-6.2 AI Translate** — On an approved/published SOP, generate BM and/or ZH translations of all sections. Translations are stored per version and flagged `machine=true` until a human marks "reviewed".
|
|
AC: Publishing a new version marks old translations stale and prompts regeneration; safety-notes sections require the human "reviewed" flag before the translation is shown to Staff (English shown until then).
|
|
|
|
**FR-6.3 AI guardrails** — All AI routes: server-side only, role Editor+, rate-limited (e.g. 20 calls/user/day), inputs capped (~8k chars).
|
|
AC: Exceeding the limit returns a clear message; the Anthropic key never appears in client bundles (verified by build inspection).
|
|
|
|
## M7 — Operational Incident Log (minimal)
|
|
|
|
**FR-7.1 Report an incident (staff+, any role)** — From the staff SOP viewer ("Report a problem" link) or a standalone "Report incident" button on My SOPs. Fields: description (required), severity (low/medium/high), optional photo, optional linked SOP (pre-filled when opened from a viewer; records the SOP version too).
|
|
AC: Submitting takes < 60 seconds on a phone; photo uploads to Storage; reporter, timestamp, and department are recorded automatically; confirmation screen shown.
|
|
|
|
**FR-7.2 Incident list (approver/admin)** — Table of incidents: date, reporter, department, linked SOP, severity, status (open / reviewed / closed). Filter by status, severity, department, SOP. Detail view shows full description + photo.
|
|
AC: New incidents default to "open"; the dashboard shows an "Open incidents" count card (red if any high severity open).
|
|
|
|
**FR-7.3 Review & close (approver/admin)** — Status transitions open → reviewed → closed, with an optional resolution note. Closing prompts: "Does this incident require an SOP revision?" — if yes, a one-click jump to that SOP's edit page.
|
|
AC: Status changes and notes are audit-logged (`incident.reviewed`, `incident.closed`); a closed incident is read-only.
|
|
|
|
**FR-7.4 Incidents per SOP** — SOP detail page gains an "Incidents" tab listing incidents linked to that SOP across versions.
|
|
AC: An SOP with ≥3 incidents in 90 days shows a "Review suggested" hint on the dashboard.
|
|
|
|
**Deliberately excluded (do not build):** escalation chains, assignment/ownership of incidents, SLA timers, email/WhatsApp alerts, root-cause taxonomies, client-facing incident reports. The module is a capture-and-review loop feeding SOP revisions — nothing more in Stage 1.
|