Task Manager guide

Tiếng Việt: Hướng dẫn Quản lý công việc

This handbook covers the four Task Manager sections on the desktop workspace (/admin): Task Streams, Task History, Manual Templates, and Shift Templates.

Schedule & roster (today’s roster and the shift calendar) live on a separate left-rail hub at /schedule. Calendar placement is what drives automatic task assignment for daily and weekly playbooks.

Interactive demo: open task-manager-demo.html in a browser for a step-by-step animated walkthrough of the use case below (no login required).

---

Table of contents

1. Use case — lunch service at District 7
2. Open Task Manager
3. The four sections at a glance
4. Task Streams
5. Task History
6. Manual Templates
7. Manual Templates and Tasks — how they relate
8. Shift Templates
9. Auto-assign from the calendar
10. How the four sections work together
11. Troubleshooting

---

1. Use case — lunch service at District 7

Who: Linh, Restaurant Manager for District 7 (Quận 7 branch).

Goal: Every Server on the Lunch shift (10:00–16:00) should receive the same three-step opening checklist on their phone—without Linh tapping Assign every morning.

Week-one setup (one time)

Step	Where	What Linh does
1	Task Manager → Shift templates	Create “Lunch service 10:00–16:00” for District 7, position Server.
2	Task Manager → Manual Templates	Create “Lunch floor — open” (Daily, Server, District 7) with three steps: wipe stations (photo by 10:30), read tonight’s script (none by 10:45), confirm POS float (photo by 11:00). Under Schedule-based auto-assign, bind Shift time template = Lunch service.
3	Schedule & roster → Calendar (/schedule)	Place Minh, Lan, and Hùng on Lunch blocks for the coming week using the Lunch shift template.

What happens each service day

1. When Linh saves a Lunch block (or taps Run auto-assign on the calendar), Nexus matches the daily manual to blocks that use the Lunch shift template.
2. Each matched employee gets three task rows in Task Streams (one per manual step).
3. Minh, Lan, and Hùng see those lines on mobile Tasks after sync; push notifications fire if enabled.
4. Linh monitors progress in Task Streams (overdue banner, status filters).
5. After completion, rows move into Task History for audit.

One-off exception the same week

Health inspection on Tuesday: Linh needs only Lan to run six wipe-and-photo stations—once, not every day.

Step	Where	What
1	Manual Templates	Create “Inspection stations” with recurrence One-time, six steps.
2	Manual Templates → Assign	Choose To individual → Lan → confirm.
3	Task Streams	Six rows appear for Lan only; no calendar involvement.

Takeaway: Repeatable shift work → daily/weekly manuals + calendar. Ad-hoc or single-person bursts → one-time manual + Assign, or a single Quick task in Task Streams.

---

2. Open Task Manager

1. Sign in on a computer with a manager account.

2. In the left icon rail, click the people / Task Manager icon (first workforce icon). You land on /admin.

3. Use the text section switcher under the page title:

   Task Streams · Task history · Manual Templates · Shift templates

Your role must allow employees read access (Operations / admin shell). If you only see recruitment or other hubs, ask HQ to adjust Settings → Platform roles.

The header shows Task Manager online (live sync), limited access, or offline depending on connection state.

---

3. The four sections at a glance

Section	Question it answers	Typical user
Task Streams	Who owes what proof right now?	Floor lead during service
Task History	What did we complete in the past?	Manager, HR audit, coaching
Manual Templates	What playbook should run for which role/shift?	Supervisor authoring SOPs
Shift templates	What are our standard shift time windows?	Scheduler, ops lead

Staff on phones never open Task Manager—they use the mobile Tasks tab, which shows the same task rows assigned to them.

---

4. Task Streams

Subtitle: All tasks dispatched today across staff

What it’s for. The live mission-control feed of active checklist lines across the organisation (respecting filters you apply).

What you see

• Each row: assignee, branch, position, playbook source (manual name or ad-hoc), status (Sent, Doing, Done), deadline (HH:mm), evidence requirement (photo / video / none).
• Overdue styling and an Only overdue toggle.
• Footer: “N of M tasks” for the current filter scope.
• Live pill when SSE sync is connected.

Filters

Filter	Purpose
Duration	Today, last 3/7/30 days, or custom range
Branch	One branch or all you can access
Position	Job title (Server, Head Chef, …)
Individual	One employee
Manual	Rows spawned from a specific playbook
Status	Sent, Doing, Done
Only overdue	Late work only

Actions

Action	How
Filter	Combine dropdowns; Reset clears them.
New (Quick task)	One-off line: assignee, instruction, deadline, evidence—no manual required (Path A).
Update status	Sent → Doing → Done when someone completes work without their phone.
View evidence	Open photo/video lightbox when proof was submitted.
Task drawer	Timeline, manual source, assignment day.
Delete	Remove duplicate or mistaken rows (permanent for that row).

Tips

• Task Streams answers: “Who owes what proof right now?”
• Changes appear on staff Tasks on mobile after sync (usually within seconds).
• Use Manual Templates → Assign when you need a full playbook, not a single line.

---

5. Task History

Subtitle: Past tasks across branches · filter, audit, export

What it’s for. A read-focused archive of completed and past tasks—audits, coaching, and “did we run the checklist last Tuesday?”

What you see

• Paginated list (50 rows per page, load more).
• KPI strip on the current page: total, on-time, overdue, evidence coverage.
• Same filter dimensions as Task Streams, plus search and has evidence filter.

Actions

Action	How
Research	Filter by branch, date range, manual, person, status.
Evidence review	Open proof from historical rows.
Export CSV	Downloads loaded rows on the current filter (not the full database).
Cross-check	Compare with Task Streams for the same day if something still shows open.

Tips

• Task History is not where you assign new work—use Task Streams or Manual Templates.
• Narrow date filters first; wide ranges take longer to load.

---

6. Manual Templates

Subtitle: Reusable playbooks · assign to position or individual

What it’s for. Authoring reusable playbooks: grouped checklist steps you assign manually or tie to roster automation.

What each manual contains

Field	Description
Name / description	Title staff see when tasks land.
Branch	One branch, or brand-wide scope where supported.
Position	Job title this playbook targets.
Repeat	One-time, Daily, or Weekly (+ weekday picker).
Steps	Instruction, deadline (HH:mm), evidence (photo/video/none), optional reference files.
Schedule-based auto-assign	Only for Daily / Weekly (see §9).

Recurrence behaviour

Repeat	Calendar auto-assign?	Typical use
One-time	No — use Assign or Quick task	Inspections, special projects
Daily	Yes — every scheduled matching day	Opening/closing every shift
Weekly	Yes — only on selected weekdays	Monday-only training

Copy in the editor: “One-time = assign from Operations when needed.”

Schedule-based auto-assign fields

Shown only for Daily / Weekly manuals:

Field	Effect
Shift time template	Manual runs only when the calendar block uses this shift template. When set, assign window below is ignored.
Assign window start / end	Local HH:mm on the calendar day; block must overlap this window.
Lead time (minutes)	Optional. Hourly cron only: tasks materialize when now ≥ shift start − lead minutes. Leave empty for immediate assign when managers save shifts or tap Run auto-assign.

Badges on the manual card show Auto · template … or Auto 10:00–16:00 when automation is configured.

Actions

Action	How
Create	New Manual → steps, scope, recurrence, evidence.
Edit	Open template, change steps or scope, Save Manual.
Delete	Removes template only; does not erase task history already created.
Assign	Assign Manual modal: To entire position or To individual. Shows “Will create N task(s) in Task Streams”. Confirm Push to Zalo if used.

Important: Assign twice creates two bundles (new random task IDs). Calendar auto-assign uses deterministic IDs and suppresses duplicates.

---

7. Manual Templates and Tasks — how they relate

Think of a Manual Template as the recipe and each Task row as one ingredient line on someone’s plate today.

Manual Template (playbook)
  name: "Lunch floor — open"
  recurrence: daily
  shift template: Lunch service 10:00–16:00
  steps:
    1. Wipe stations (photo, 10:30)
    2. Read tonight script (none, 10:45)
    3. Confirm POS float (photo, 11:00)
           │
           │  Path B: Manager clicks Assign
           │  Path C: Calendar auto-assign
           ▼
Task rows (live checklist lines)
  task A → Minh, step 1, status Sent, manualId → playbook
  task B → Minh, step 2, …
  task C → Minh, step 3, …
  task D → Lan, step 1, …
  … (one row per step × assignee)
           │
           ▼ staff completes on mobile
Task History (archive, searchable)

Data link

Concept	Stored as	Key link
Playbook	manuals + manual_steps	Template ID, steps, recurrence, shift binding
Live task	tasks	manualId, manualName, assignmentDayKey (yyyy-MM-dd for auto-assign)
Ad-hoc task	tasks	manualId empty — created from New in Task Streams

Three paths to create tasks

Path	Source	Creates
A — Just this once	Task Streams → New	One task row, no playbook
B — Push a playbook	Manual Templates → Assign	All steps × chosen people immediately
C — Let the roster do it	Calendar + daily/weekly manual	Steps × each employee on a matching shift block

Paths B and C both materialize the same step list; they differ in when and who triggers it.

---

8. Shift Templates

Subtitle: Reusable shift windows for the calendar and manual auto-assign.

What it’s for. Named time windows that mean the same thing everywhere—for example “Lunch service 10:00–16:00” for District 7 Servers.

What each template has

Field	Example
Template name	Lunch service
Branch	District 7
Position	Server (or Any position)
Start / End	10:00 – 16:00 (schedule timezone)

Where shift templates are used

1. Schedule & roster → Calendar — when placing a block, pick a template to pre-fill times and store shiftTemplateId on the block.
2. Manual Templates → Schedule-based auto-assign — bind a daily/weekly manual to this shift flavour so only Lunch blocks receive that checklist.

Mental model

Shift template  =  WHAT KIND of shift (label + default hours)
Calendar block  =  WHO works WHEN (employee + actual UTC interval)
Manual template =  WHAT CHECKLIST runs for that kind of shift

Shift templates describe when a shift flavour runs; the calendar places who works those hours.

Actions

Action	How
Create	Add template — name, branch, position, start/end.
Filter	By branch in the panel header.
Delete	Trash icon — confirm no active calendar blocks or manual links depend on it.

Tips

• Times follow Asia/Ho_Chi_Minh (Hanoi, UTC+7) unless IT overrides SCHEDULE_TIMEZONE / VITE_SCHEDULE_TIMEZONE.
• After changing templates, review linked manuals and upcoming calendar blocks.

---

9. Auto-assign from the calendar

Automatic assignment is Path C: daily and weekly manuals become task rows when employees appear on matching calendar blocks.

Matching rules

For each daily/weekly manual and each scheduled shift block on a calendar day:

flowchart TD
  A[Scheduled shift block] --> B{Manual recurrence daily/weekly?}
  B -->|No once| Z[Skip auto-assign]
  B -->|Yes| C{Branch + position match manual?}
  C -->|No| Z
  C -->|Yes| D{Weekly: weekday in weeklyDays?}
  D -->|No| Z
  D -->|Yes| E{Manual has shift template?}
  E -->|Yes| F{Block uses same shift template?}
  F -->|No| Z
  F -->|Yes| G[Materialize tasks]
  E -->|No| H{Assign window set?}
  H -->|Yes| I{Block overlaps local window?}
  I -->|No| Z
  I -->|Yes| G
  H -->|No| G

Priority	Manual setting	Block must…
1	Shift time template selected	Use the same shiftTemplateId
2	Assign window start + end (HH:mm)	Overlap that local window on the day
3	Neither	Match any block for manual’s branch + position

Additional filters:

• Manual branch matches block branch (or manual is brand-wide).
• Manual position matches employee’s position (or manual targets all positions).
• Weekly manuals: day’s weekday must be in weeklyDays (defaults Mon–Fri if unset).

When auto-assign runs

Trigger	Lead time respected?
Create shift block (POST /schedule)	No — immediate
Update shift block (PATCH /schedule/{id})	No
Fill week from defaults	No
Calendar Run auto-assign button	Only if respectLeadTime: true
Hourly cron (production, :15 past each hour)	Yes — honours Lead time (minutes)

Idempotency

• Auto-assign uses deterministic task IDs (t-auto-{manual}-{employee}-{day}-s{step}) and skips duplicates—safe to run twice.
• Manual Assign uses random IDs—clicking Assign twice creates duplicate bundles.

Manager checklist

1. Manual is Daily or Weekly (not One-time).
2. Shift template or assign window aligns with how you draw blocks on the calendar.
3. Employee is on the calendar for that day with a matching block.
4. For cron-delayed drop: Lead time is set and the hourly job has run close enough to shift start.
5. If tasks did not appear after editing the calendar, tap Run auto-assign on the schedule page.

For calendar editing step-by-step, see Putting someone on the calendar in the manager guide.

---

10. How the four sections work together

Shift Templates  ──►  Calendar blocks (/schedule)  ──►  Auto-assign (Path C)
        │                                                    │
        └──────────────►  Manual Templates ◄─────────────────┘
                                    │
                                    ▼ Assign (Path B) / auto-assign
                              Task Streams (live)
                                    │
                                    ▼ staff mobile Tasks tab
                              Task History (archive)

You want to…	Start here
Define standard shift hours	Shift templates
Write a repeatable checklist	Manual Templates
See live progress today	Task Streams
Audit last week’s completions	Task History
Put people on shifts	Schedule & roster (/schedule)

---

11. Troubleshooting

Symptom	What to check
Auto-assign never fired	Manual must be Daily/Weekly; shift template or window must match calendar block.
Wrong people got tasks	Position on manual vs employee card; shift template on block vs manual binding.
Duplicate tasks	Double Assign click (Path B). Auto-assign should not duplicate.
Tasks empty in Streams	Date filter (Today vs custom); branch/position filters too narrow.
Staff phone empty	Same calendar day (assignmentDayKey); roster branch matches employee.
Cron delay	Lead time set—tasks appear only within N minutes of shift start on hourly cron.

For broader manager topics (yield, salinity, recruitment, settings), see the manager & staff guide.

For staff mobile task completion, see the floor employee guide.