# Bug tracker for QA and developers: plan

Status: **approved 16 Nov 2026** (decisions below are the owner's answers).
**BT1 to BT4 built 16 Nov 2026 and committed** (backend `8f3810b`, web
`d7a5cfc`). **BT5 (releases and the board) and BT6 (test checklists, GitHub
links) built 16 Nov 2026**, not committed yet. Every planned sprint is built.
See "Progress" at the end.

## Goal

QA tests HostelCare (web app, mobile app, API, website) and reports bugs in one
place; developers pick them up, fix them and hand them back; QA verifies the
fix and closes the bug. The super admin creates the QA and developer accounts
and sees everything: every bug, who is working on what, and how the team is
doing.

Web only, inside the existing web app at `/bugs`. No mobile app. (Bugs *about*
the mobile app are reported here like any other.)

## Why build it into HostelCare

Decided (D1): build. For the record: GitHub Issues (free, the team is already on GitHub) or Jira (free up to 10
people) would cover basic tracking today with no build. Building our own is
worth it for: one sign-in the super admin controls, fields that fit this
product (hostel type, the role affected, app build), screenshots of production
data kept in our own private storage, the super admin's dashboard, and no
per-seat cost as the team grows. Most of the plumbing already exists from the
CRM and the blog (below), so the core is three sprints.

## What already exists and is reused

| Need | Reused from |
|---|---|
| Team accounts with no hostel, invited by email, switched off at once | CRM users / blog writers: `Role` values fenced in `authenticate.ts`, `alwaysTwoStep()`, `AccountInvite`, the shared `CrmUsersPanel` (`TeamAdapter`) and `InvitePage` (`InviteSource`) |
| Private files (screenshots) | Blog images: `platform/…` prefix in S3, short-lived links, type read from the bytes |
| A separate workspace, loaded only when opened | `/blog` (`BlogApp`, lazy chunk, hash routes) |
| Paged lists, search, forms, validation messages | `usePaginatedList`, `Pagination`, `Field`/`Input`, `useFormErrors`, `validation.ts` |
| Markdown writing and preview | The blog's TipTap editor and `react-markdown` preview |
| Emails | `lib/email.ts` and the templates' `wrap()` |
| Charts and exports | `lib/charts.ts`, `lib/spreadsheet.ts`, `lib/download.ts` |
| Tests | Throwaway-schema service tests, `audit:permissions`, `smoke` |

No new packages are expected.

## Who can do what

| | QA | Developer | Super admin |
|---|---|---|---|
| Report a bug, comment, attach files | ✓ | ✓ | ✓ |
| Edit a bug's details | own reports, or any while it is open | any | ✓ |
| Assign to a developer | ✓ | to themselves, or pass to another developer | ✓ |
| Start work, mark **Fixed**, ask for more information | – | ✓ | ✓ |
| Suggest "not a bug", "duplicate", "can't reproduce" | – | ✓ (QA confirms) | ✓ |
| **Verify and close**, or **reopen** | ✓ | – (a developer never closes their own fix) | ✓ |
| Modules, releases | read | read; add a release | ✓ manage |
| Team accounts, dashboard, export | – | – | ✓ |

Every tracker account is fenced to `/api/bug-tracker` and `/api/auth`: it can
reach no hostel, CRM or blog data, and no hostel, CRM or blog account can reach
the tracker. One account has one role; someone who is both a blog writer and a
tester needs two email addresses.

## A bug

- **Key:** `BUG-1`, `BUG-2`, … (never reused).
- **What happened:** title; steps to reproduce; expected result; actual result
  (three boxes, so no report arrives without them); Markdown allowed.
- **Where:** app (Web app, Android app, iOS app, API, Website — a fixed list;
  the tracker is for HostelCare only, D4) and module (Rooms, Students, Billing,
  Mess, Gate, CRM, Blog …), a list the super admin edits; environment
  (Production, Staging, Local); app version or build; browser and device
  (pre-filled from the reporter's browser when it is a web bug); page address.
- **Product context, specific to HostelCare:** tenant type affected (Hostel, PG,
  Dormitory, Enterprise, All) and the role that hits it (Hostel admin, Warden,
  Mess admin, Resident, Guard, Guardian, Super admin, CRM user, Blog writer).
- **How bad:** severity, set by the reporter (Critical: data loss, money wrong
  or nobody can work · Major: a feature is broken · Minor: works with a
  workaround · Trivial: cosmetic). Priority (P1 fix now … P4 someday), set by
  whoever triages; the history shows who.
- **Type:** Bug, or Suggestion (an improvement, tracked the same way).
- **Files:** screenshots (paste from the clipboard, drag in, or choose), PDFs and
  log/text files; see D6 for videos.
- **People:** reporter, assignee, watchers (get the emails).
- **Fix:** the developer's note on what was wrong, a commit or pull-request
  link, and the release it is fixed in.
- **Links:** "duplicate of BUG-n", "related to BUG-n".
- **History:** every change, by whom and when; comments with @mentions.

## Life of a bug

```
            report
              │
            OPEN ──────────────► NEEDS INFO (developer asks) ──► back to OPEN
              │ developer starts                                    when QA answers
         IN PROGRESS
              │ developer: fixed (+ note, link, release)
            FIXED ── waiting for QA ──┐
              │ QA: works             │ QA: still broken (+ why)
           CLOSED (verified)       REOPENED ──► IN PROGRESS …   (reopen count kept)

 Developer suggests Not a bug / Duplicate / Can't reproduce / Won't fix
   → waits for QA → QA agrees: CLOSED with that reason · QA disagrees: REOPENED
```

Statuses: Open, In progress, Needs info, Fixed, Reopened, Closed. A closed bug
carries its reason: Verified fixed, Duplicate, Not a bug, Can't reproduce,
Won't fix. A closed bug can be reopened by QA or the super admin.

## Decisions (owner, 16 Nov 2026)

| # | Question | Decision |
|---|---|---|
| D1 | Build it into HostelCare, or use GitHub Issues / Jira? | **Build it into HostelCare.** |
| D2 | Accounts | Two new roles, **`QA`** and **`DEVELOPER`**, plus the super admin, who sees and can do everything. Developers can report bugs too. |
| D3 | How accounts get in | **The same as CRM users and blog writers:** the super admin enters name and email, the person gets an invite link, sets their own password, and signs in with a code each time (or an authenticator app). The super admin never knows a password. |
| D4 | Which products | **HostelCare only.** GymCare has its own separate ecosystem, so there are no projects to add: a bug has an **app** (Web app, Android app, iOS app, API, Website) and a module. |
| D5 | Who closes | **Any QA account or the super admin.** A developer marks Fixed (or suggests a reason) and it waits for one of them. |
| D6 | Attachments | Images, PDFs and text/log files **up to 10 MB each, 10 per bug or comment**, through the API. **Videos up to 50 MB** go straight from the browser to S3, which needs a one-time CORS setting on the bucket (owner, see "One-time setup"); until then a video is a link field. |
| D7 | Emails | On by default: assigned to you, your bug was fixed / needs info / reopened, a comment on a bug you're on, an @mention. Each person can switch groups off. No WhatsApp. |
| D8 | Later sprints | BT5 (releases and a board) and BT6 (test checklists, GitHub commit links) are optional; **decide after BT4 is in use.** |

## Sprints

Each sprint is backend and web together, ends with tests (service tests on a
throwaway schema, the permission audit with the new roles, smoke) and a check
in the browser, and is deployable on its own.

### BT1 — Accounts and workspace (small)

- Migration (additive): `Role` gets `QA` and `DEVELOPER`; table `BugModule`.
- Both roles fenced to `/api/bug-tracker` + `/api/auth`, with the CRM user's
  sign-in rules (`alwaysTwoStep`).
- `/api/bug-tracker/team` (super admin): invite a tester or developer, edit,
  send a password link, sign out everywhere, switch off and on. Invite page at
  `/bugs/invite/:token`.
- `/bugs` workspace (lazy-loaded): testers and developers land there after
  sign-in; the super admin opens it from "Bug tracker" in their menu. Sections:
  Bugs, My work, Team (super admin), Settings (super admin), Profile.
- Settings: the modules list (add, rename, archive; a default developer per
  module, optional), seeded with HostelCare's modules. The apps are a fixed
  list in the code (D4).
- Tests: every existing route refuses the two roles; hostel, CRM and blog
  accounts can't open the tracker.

### BT2 — Report and find bugs (large)

- Tables `Bug`, `BugAttachment`, `BugComment`, `BugEvent` (history), `BugWatcher`,
  `BugLink`, a counter for `BUG-n`.
- Report form: the fields above, required ones marked, browser and device
  pre-filled, screenshots pasted or dragged in, a draft kept in the browser
  until it is submitted.
- "Looks like these": while the title is typed, open bugs with similar titles
  are listed, to stop duplicates before they are filed.
- List: server-side pages, search by text or key, filters (status, severity,
  priority, app, module, environment, assignee, reporter, tenant type), sort, and the filters kept in the address so a view can be shared.
- Bug page: details, files with previews, comments (Markdown, @mentions,
  files), full history.
- Files private under `platform/bug-tracker/`, type read from the bytes,
  ten-minute links; a file can be removed by its uploader or the super admin.
- Tests: rules for who edits what, attachment checks, key sequence, search.

### BT3 — The fix-and-verify loop (medium)

- Statuses and who may move a bug where (the table and diagram above), enforced
  on the server; each move asks for what it needs (a fix note for Fixed, a
  reason for Reopened, the original for Duplicate).
- Assign, reassign, "take it"; module's default developer on a new bug.
- Fix details: note, commit or pull-request link, fixed-in release (free text
  until BT5).
- My work: for a developer "Assigned to me" and "Reopened"; for QA "Waiting for
  me to verify", "Needs my answer", "Reported by me"; counts in the menu.
- Bulk actions on the list: assign, set priority, close as duplicate.
- Tests: every allowed and refused move for each role; reopen count; a
  developer can't close.

### BT4 — Emails and the super admin's view (medium)

- Emails (D7), one per event per person, with the bug's key, title and a link;
  per-person switches; nothing sent to a switched-off account.
- In-app: a bell with unread items and "mark all read".
- Dashboard (super admin; a short version for the team): open bugs by severity,
  by module, by developer; waiting for QA; older than 7 and 30 days; opened vs
  closed per week; reopen rate; average time to fix and to verify.
- Export the filtered list to Excel.
- A weekly summary email to the super admin (Monday).

### BT5 — Releases and board (optional)

- Releases per app (name, date, notes; e.g. "Web 18 Nov", "Android 1.4.2").
  "Fixed in" becomes a choice; marking a release as deployed tells QA what is
  ready to verify, and gives release notes from the bugs fixed in it.
- "Found in" version from the same list.
- Board: columns by status, drag a card to move it (the same rules apply).

### BT6 — Test checklists and GitHub (optional)

- Checklists: a reusable list of things to test (login, onboarding a resident,
  an invoice …). A run of a checklist against a release marks each item pass,
  fail or skipped; "fail" opens the report form pre-filled and links the bug.
- GitHub: a commit or pull request that says `Fixes BUG-123` adds its link to
  the bug and moves it to Fixed when merged (a webhook from the three repos).

## Order

BT1 → BT2 → BT3 gives a working tracker (report, assign, fix, verify, close).
BT4 makes it something the team doesn't have to keep checking, and gives the
super admin the numbers. BT5 and BT6 only if wanted.

## One-time setup (owner)

- **For video uploads (D6), when wanted:** a CORS rule on the S3 bucket that
  allows `PUT` from `https://app.hostelcare.co.in`. Until it is there, the
  report form offers a video link instead; nothing else depends on it.
- After BT1 is deployed: Super admin → Bug tracker → Team → invite the testers
  and developers.

## Notes for the build

- Platform-level data (no `tenantId`): the unscoped client, reached only through
  a `requireBugAccess` door that checks the account is on and not signed out,
  on every request (as the CRM and blog do).
- Screenshots of production may show residents' details: private bucket,
  short-lived links, tracker accounts only; the report form reminds people not
  to paste passwords or card details.
- Additive API only; nothing here touches hostel, PG, dormitory or Enterprise
  screens or the mobile app.
- Module code in `src/modules/bug-tracker/` (backend) and `src/features/bugs/`,
  `src/pages/bugs/` (web).

## Progress

### BT1 — accounts and workspace (built 16 Nov 2026)

**Backend (`hostelcare-backend`)**

- Migration `20261219090000_bug_tracker_accounts`: role values `QA` and
  `DEVELOPER`, table `BugModule`. Additive only.
- `authenticate.ts`: the per-role fences are now one table (`FENCED`) covering
  CRM users, blog writers, QA and developers; the two new roles reach only
  `/api/bug-tracker` and `/api/auth`. `alwaysTwoStep()` covers them.
- `src/modules/bug-tracker/`: `bug-access.ts` (`requireBugAccess`, checked
  against the database on every request; a session whose role no longer matches
  the account is refused), `bug-team.service.ts`, `bug-modules.service.ts`
  (`BUG_APPS` fixed list; starter modules seeded once, on first use),
  `bug-tracker.routes.ts`. Invite email `bugTrackerInviteEmail`.
- Endpoints under `/api/bug-tracker`: `GET|POST /invites/:token[/accept]`
  (public); `GET /workspace` (me, apps, open modules, active members);
  `/team` (super admin): list (`?role=`), add (with `role`), edit (name, email,
  phone, **role** — a new role or email signs the person out), `send-link`,
  `deactivate`, `reactivate`, `sign-out`; `/modules` (super admin): list with
  archived, add, edit (name, default developer, archived), `PUT /order`.
- A module's default developer must be a switched-on DEVELOPER; switching a
  developer off, or making them a tester, clears them from their modules.
- Tests: `src/tests/bug-tracker.test.ts` (9 cases, throwaway schema
  `hc_bug_test`) in `npm run test:isolation`; `npm run audit:permissions` has
  both roles on every route plus the tracker's own cases (3,641 passed);
  `npm run smoke` 2,171 passed.
- Also fixed: the smoke suite only passed before 13:00 IST (its dormitory
  walk-in was booked for noon "today", and a booking that has ended is
  refused). After the morning it now plans for tomorrow, so it passes at any hour.

**Web (`hostelcare-frontend`)**

- `/bugs` workspace (`src/pages/bugs/BugApp.tsx`, loaded only when opened, 13 KB):
  QA and developers land there after sign-in; the super admin opens it from
  "Bug tracker" in their menu. `/bugs/invite/:token` is the set-password page
  (the shared `InvitePage`).
- `src/features/bugs/`: `BugsHome` (who is on the tracker and where bugs are
  filed; says reporting opens with the next update), `BugTeamSection` (QA
  testers / Developers tabs in the shared `CrmUsersPanel`, which gained an
  optional `move` action: "Make a developer" / "Make a QA tester"),
  `BugModulesSection` (add, rename, default developer, order, archive,
  restore), `bugChecks` (+ test). API calls: `bugApi` in `src/lib/api.ts`.
  `isPlatformTeam(role)` in `types.ts` replaces the role lists in the profile
  screen.
- Checked in the browser against a throwaway API (schema `hc_bug_ui`, since
  dropped): super admin → Bug tracker → Team → invite a tester → "Make a
  developer" (moved lists) → Settings → a duplicate module name refused, a new
  module added with her as its developer → sign out → her invite link → set
  password → sign in with the emailed code → lands in the tracker as Developer
  with only Bugs and Profile; phone width. Web tests 262, build clean.

### BT2 — report and find bugs (built 16 Nov 2026)

**Backend**

- Migration `20261220090000_bug_tracker_bugs`: enums `BugApp`, `BugType`,
  `BugSeverity`, `BugPriority`, `BugEnvironment`, `BugStatus`, `BugResolution`,
  `BugLinkKind`; tables `Bug` (number = a sequence, key `BUG-<number>`),
  `BugAttachment`, `BugComment`, `BugEvent`, `BugWatcher`, `BugLink`. The
  columns BT3 needs (status, resolution, fix note/link/release, reopen count)
  are already there, so BT3 needs no migration for them. Additive only.
- `bug-rules.ts` (every shape and limit, zod), `bug-files.service.ts`,
  `bug-bugs.service.ts`, `bug-jobs.ts` (hourly: files never attached are removed
  after a day). Files: `putBugObject` / `presignBugObject` / `deleteBugObject`
  under `platform/bug-tracker/` in `uploads.service.ts`.
- Endpoints under `/api/bug-tracker` (the whole team): `GET /bugs` (page, `q`
  by text or key, filters `status,severity,priority,app,environment,type,
  tenantKind` as comma lists, `moduleId`, `assigneeId` or `none`, `reporterId`,
  `sort`), `GET /bugs/similar?title=`, `POST /bugs`, `GET|PATCH /bugs/:number`,
  `POST /bugs/:number/{files,comments,watch,links}`, `DELETE
  /bugs/:number/links/:id`, `PATCH|DELETE /comments/:id`, `POST /files` (raw
  body, `?filename=`), `DELETE /files/:id`.
- Rules: a bug needs steps, expected and actual (a suggestion only the first);
  a new bug is OPEN and goes to its module's developer if it has one; the
  reporter and assignee follow it. Edit: super admin and developers any bug; QA
  their own, or anyone's until it is closed. Status can't be set by editing
  (BT3's moves do that). Files: type read from the bytes (images incl. GIF,
  PDF, UTF-8 text stored as plain text), 10 MB, 10 per bug or comment; a file
  is uploaded first and claimed by its uploader when the report or comment is
  sent, so naming another's file id attaches nothing; removed by its uploader or
  the super admin. Comments: author edits; author or super admin removes (its
  files go too); only real, switched-on members can be mentioned, and they then
  follow the bug. Every change leaves a `BugEvent`.
- Tests: `src/tests/bug-tracker.test.ts` now 19 cases (S3 stood in for);
  `audit:permissions` 3,767 passed with the bug routes for every role;
  `smoke` green.

**Web**

- `src/features/bugs/`: `BugListSection` (status tabs with counts, search by
  text or key, filters, sort, pages; the whole view is in the address, e.g.
  `#bugs?status=OPEN&severity=CRITICAL`; filters fold behind a button on
  phones), `BugReportForm` (bug or suggestion; steps / expected / actual; app,
  module, environment, version, browser and device pre-filled for web bugs,
  page address; severity with what each means; priority; tenant type and role;
  screenshots pasted, dropped or chosen; a video link; "Looks like these" open
  bugs while the title is typed; kept as a draft in the browser until sent;
  also the edit form), `BugPage` (details, files with a viewer, related bugs,
  followers, one activity thread of changes and comments, a comment box with
  @mentions and files), `BugBits` (badges, safe Markdown, uploads),
  `bugChecks` (+ 9 tests). Addresses: `#bugs`, `#bugs/12`, `#edit/12`, `#report`.
- Checked in the browser against a throwaway API with file storage stood in
  for (schema `hc_bug_ui`, since dropped): a tester signs in → the list →
  report form: the duplicate hint found BUG-1 from different wording; sending
  it empty marks all six required boxes; a pasted screenshot uploads; a reload
  restores the draft; report sent with a screenshot and a `.json` file →
  BUG-2's page; a comment with an @mention (the developer then follows it);
  link BUG-1 as related; edit severity and priority → the history says so in
  words; list filters by severity, search by key and by text, and "unassigned";
  phone width for the list and the bug page. Not checked: real S3 (file storage
  was stood in for), and a file download's "save as" behaviour.

### BT3 — the fix-and-verify loop (built 16 Nov 2026)

No migration: BT2's tables already had the columns.

**Backend**

- `bug-rules.ts`: `allowedActions(actor, bug)` is the one place the rule lives.
  A developer (or the super admin) may `start`, `ask`, `fix`, `suggest` on a bug
  that is open, in progress, reopened or waiting for information; QA (or the
  super admin) may `close` anything not closed and `reopen` anything fixed or
  closed; the reporter or QA may `answer`. A developer never closes or reopens.
- `bug-workflow.service.ts`:
  - `moveBug`: start → IN_PROGRESS (a developer who starts a bug takes it); ask
    → NEEDS_INFO (question required); answer → OPEN; fix → FIXED (note
    required; optional https link and "fixed in"; a developer fixing an
    unassigned bug gets it); suggest → FIXED carrying the reason (Duplicate,
    Not a bug, Can't reproduce, Won't fix; a duplicate needs its original and
    links the two, and two bugs can't be duplicates of each other); close →
    CLOSED (from FIXED with no reason: "verified", or the suggested reason;
    from an open bug a reason is required); reopen → REOPENED (reason required,
    reopen count +1, the duplicate link removed, it stays with its developer).
    Two people pressing at once make one move; the other is told the bug changed.
  - `assignBug`: to a switched-on DEVELOPER or to nobody; anyone on the tracker;
    not once closed. The assignee follows the bug.
  - `bulk`: assign, set priority, or close as duplicates of one bug, for up to
    50 bugs; each follows the same rules and reports its own result.
  - `myWork` / `attentionCount`: per role. Developer: Reopened, Assigned to me,
    Waiting for an answer, Unassigned, My fixes waiting for QA. QA: Waiting for
    QA, Needs my answer, Reported by me. Super admin: Unassigned, Waiting for
    QA, Reopened, Waiting for information, Not triaged. Each group carries the
    list filters that show the same bugs.
- Endpoints: `POST /bugs/:number/move`, `POST /bugs/:number/assign`,
  `POST /bugs/bulk`, `GET /my-work`, `GET /my-work/count`. A bug's reply now has
  `can.actions` and `can.assign`. Events: `STATUS` (with the move's note) and
  `ASSIGNED`.
- Tests: `bug-tracker.test.ts` now 26 cases (the whole matrix of role × status;
  the full walk open → fixed → reopened → verified; suggested reasons; a race;
  assignment; bulk; my work); `audit:permissions` 3,830 passed.

**Web**

- `BugActions.tsx`: the buttons for the moves open to the signed-in person
  (from `can.actions`), each with a dialog for what it needs; a line saying
  where the bug stands (fixed and waiting, the suggested reason, closed and
  why, reopened and with whom) with the fix note, release and link; the
  "Assigned to" control and "Take it".
- `BugMyWork.tsx` ("#work") with the count beside "My work" in the menu,
  refreshed after every move.
- Bug list: tick boxes and a bar to assign, set priority or close as
  duplicates; a bug waiting for QA with a suggested reason shows as
  "Not a bug?" / "Duplicate?".
- The thread shows each move in words, with its note as a card.
- Checked in the browser against a throwaway API (schema `hc_bug_ui`, since
  dropped): as a developer — My work lists the unassigned bugs, most severe
  first; Start work takes the bug; Mark as fixed refuses an empty note, then
  shows the fix with its release and link, and leaves the developer no buttons;
  "Not a fix…" as a duplicate of BUG-3 links the two. As a tester — My work
  (2) shows both waiting; Verify and close → "Closed · verified fixed";
  "Disagree: reopen" → reopened, back with the developer, the duplicate link
  gone, the menu count updated; ticking three bugs and assigning them changes
  two and names the closed one with the reason. Phone width.

### BT4 — emails, the bell, the dashboard (built 16 Nov 2026)

Migration `20261221090000_bug_tracker_notifications` (additive): `BugNotification`,
`BugNotifyPrefs`, `BugSummaryLog`.

**Backend**

- `bug-notify.service.ts`. Every event that concerns someone leaves them one
  `BugNotification`: the bell's row, and one email unless they switched that
  group off. Never to the person who did it; nothing to a switched-off account
  (checked when the row is written and again when the email is sent).

  | Event | Who is told | Email switch |
  |---|---|---|
  | A new bug goes to its module's developer; a bug is assigned | the assignee | ASSIGNED |
  | ask, answer, fix, suggest, close, reopen ("start" is not news) | everyone following the bug, and its assignee | STATUS |
  | A comment | everyone who was following, and the assignee | COMMENT |
  | An @mention (in a new comment, or added by an edit) | the person mentioned | MENTION |

  A person named twice for one event gets one notification (a mention wins
  over "a comment"). The row is written with the change; the email goes out
  afterwards in the background (`settle()` waits for it in tests), so a slow
  mail server never slows the tracker. Each row records how its email went
  (`NONE | PENDING | SENDING | SENT | DRY_RUN | FAILED`). A bulk change gives
  each person one email for the lot ("Asha assigned 3 bugs to you"), and still
  one row per bug in the bell. The hourly job sends anything a restart left
  unsent (PENDING for over five minutes; each row is claimed, so nothing goes
  twice).
- Emails: `bugNotificationEmail` (subject `[BUG-12] Reopened · <title>`, the
  note or comment quoted, status / severity / module, a button to the bug, and
  how to switch it off); the bulk and weekly emails use the CRM's sectioned
  layout. Links open `/bugs#bugs/12`.
- Switches: `BugNotifyPrefs.emailOff` holds what a person turned off; no row
  means everything is on (D7). The super admin has one more, `WEEKLY`.
- `bug-insights.service.ts`:
  - `dashboard`: seven tiles (open, unassigned, waiting for QA, reopened,
    critical, open over 7 and over 30 days), open bugs by severity and by
    module, and reported vs closed for the last eight weeks (weeks start on
    Monday, India time). "Open" means not closed. Every number carries the
    list filters that show the same bugs. The super admin also gets, per
    developer: to fix, reopened, waiting for QA, fixed and sent back; and for
    the last 90 days the average time to fix (report or reopen → "fixed"), the
    average time for QA to verify, and the share of fixes QA sent back. The
    team's version has the bugs, not the people.
  - `exportBugs`: the list as filtered and sorted, as an .xlsx (first 5,000),
    written with `lib/xlsx.ts`.
  - `runWeeklySummary`: Monday from 09:00 India time, to every super admin who
    has not switched it off: last week's reported and closed, what is open,
    what needs attention, the five oldest open bugs, each developer's line, and
    the times. `BugSummaryLog`'s unique key makes it go once. Nothing is sent
    while the tracker has no bugs.
- The list has a new filter, `olderThan` (days since reported), for the
  dashboard's age tiles.
- Endpoints: `GET /notifications`, `POST /notifications/read`,
  `GET/PUT /notifications/settings`, `GET /dashboard`, `GET /bugs/export`;
  `GET /my-work/count` now also returns `unread`; `GET /bugs/:number` marks
  what I was told about that bug as read.
- `bug-jobs.ts` (hourly): file clean-up, leftover emails, the Monday summary.
- Tests: `bug-tracker.test.ts` now 33 cases (the mail sender is stood in for);
  `audit:permissions` 3,907 passed.

**Web**

- `BugBell.tsx`: a bell in the top bar (a new `headerExtra` slot on `Shell`)
  with the unread count, the ten latest, "Mark all read" and a link to the
  full page. The count is asked for on every navigation, once a minute, when
  the tab regains focus, and after a bug has loaded.
- `BugNotifications.tsx` ("#notifications"): everything I was told (All /
  Unread), and "Email me when" with a tick box per group, saved as it is
  ticked.
- `BugDashboard.tsx` ("#dashboard", in the menu for everyone): the tiles, bars
  by severity and module, the weekly chart; for the super admin the developers
  table and the three facts. Every tile and bar opens the bug list on those bugs.
- Bug list: "Export" (the list as filtered, as Excel) and a removable
  "Reported over N days ago" chip.
- Checked in the browser against a throwaway API (schema `hc_bug_ui`, since
  dropped): as a developer — the bell shows 8, the panel lists them with their
  notes; opening one opens its bug and the count drops; the Notifications page
  and switching "comments" off (saved); the team dashboard; "Open over 7 days"
  opens the four bugs it counted; Export downloads `hostelcare-bugs-<date>.xlsx`
  and says how many. As the super admin — the full dashboard with the
  developers table and fix times; phone width with no sideways scroll. As a
  tester — "Mark all read" clears the bell. The single and weekly emails were
  opened as pages to check their layout.

**To deploy BT1 to BT4:** backend first (three additive migrations: the roles,
the bug tables, the notifications), then the web app. Then Super admin → Bug
tracker → Team → invite the testers and developers. Emails need nothing new:
they go through the mail settings the server already has, and link to
`PUBLIC_WEB_URL`.

### BT5 — releases and the board (built 16 Nov 2026)

Migration `20261222090000_bug_tracker_releases` (additive): table `BugRelease`;
`Bug.fixedInReleaseId` and `Bug.foundInReleaseId` (both optional, set to null if
a release is ever deleted).

**Releases**

- A release is one app and a name ("1.4.2" of the Android app, "18 Nov" of the
  web app), with an optional planned day and notes. One name per app, whatever
  the capitals. The app cannot be changed afterwards.
- Who: everyone on the tracker reads releases. **Developers and the super admin
  add, edit and mark as deployed; only the super admin archives.** (The plan's
  table gave developers "add" only; they also edit and mark as deployed, since
  they are the ones who know when it went out.) An archived release leaves the
  choices; the bugs that name it keep it.
- "Fixed in" is a choice: the fix dialog offers the bug's app's releases, "Not in
  a release yet", or "Another version…" (typed, as before). A chosen release
  sets `fixedInReleaseId` and writes its name into `fixedIn`, so the export,
  the emails and the history read as before. Renaming a release renames it on
  its bugs.
- "Found in" on the report form works the same way (`foundInReleaseId`, with
  the name in `appVersion`). Typing a version by hand, or moving the bug to
  another app, takes the release off.
- **Deployed.** A fix in a release that has not gone out cannot be tested, so:
  - the tester's "My work" has "Ready to verify" (no release named, or its
    release is deployed) and a separate "Fixed, not deployed yet";
  - the list has the filters `fixedInReleaseId`, `foundInReleaseId` and
    `deploy=ready|waiting`, and shows "Fixed · not deployed" on such a bug;
  - marking a release as deployed writes "deployed <release>: this fix can be
    verified now" on each waiting bug's thread and tells the people on those
    bugs **and every tester** (kind `DEPLOYED`, the STATUS email switch): one
    row per bug in the bell, **one email per person** ("Web app 18 Nov is
    deployed: 3 fixes are ready to verify"). Marking it again tells nobody.
    "Not deployed after all" takes it back, quietly.
  - The notification for "fixed" is now labelled "Fixed"; "Ready to verify" is
    the label for a deployment.
- A release's page: its numbers (fixes in it, waiting for QA, verified, sent
  back, found in it; each opens the list), the bugs fixed in it and found in
  it, and **release notes** written from the fixes that held (bugs under
  "Fixed", suggestions under "Improved"; a fix QA sent back is left out), with
  a Copy button.
- `bug-releases.service.ts`; endpoints `GET/POST /releases`,
  `GET/PATCH /releases/:id`, `POST /releases/:id/deployed`,
  `POST /releases/:id/archived`. `/workspace` now also returns `releases` (the
  choices for the forms). A bug's reply has `fixedInRelease` and
  `foundInRelease`.

**The board**

- `GET /board` (the list's filters; a status filter is ignored): six columns in
  the order work flows — Open, Reopened, In progress, Needs info, Waiting for
  QA, Closed (the last 14 days) — each with its total and its first 40 cards,
  most severe first. Each card carries `actions`, from the same
  `allowedActions` as a bug's page.
- Dragging a card to another column is a move (`moveFor` in bugChecks.ts):
  → In progress = start, → Needs info = ask, Needs info → Open = answer,
  → Waiting for QA = fix, → Closed = close, → Reopened = reopen. While a card
  is dragged, only the columns this person may drop it on light up and say
  what dropping does; the rest dim. "Start" happens at once; every other move
  opens the same dialog as on the bug's page (note, reason, release), and goes
  through `moveBug`, so nothing can be done on the board that can't be done on
  the page.
- Each card also has a "Move…" menu with the same moves, for phones and
  keyboards. Cards a person can do nothing with are not draggable.
- Filters: assigned to, app, module (kept in the address, `#board?…`).

**Tests:** `bug-tracker.test.ts` 38 cases (releases: who may write, names, a fix
and a report naming a release, deployed tells QA once and in one email, the
numbers and notes follow QA, rename and archive; the board: columns, the moves
per role, filters, the Closed window); `audit:permissions` 3,996 passed; web
unit tests 275.

**Web:** `BugReleases.tsx` ("#releases", "#releases/<id>"), `BugBoard.tsx`
("#board"), `BugReleaseBits.tsx` (the release picker used by the fix dialog and
the report form); both in the menu for everyone.

**Checked in the browser** against a throwaway API (schema `hc_bug_ui`, since
dropped): as a developer — the Releases list and a release's page with its
notes; the board; dropping BUG-6 on "In progress" (the drop was sent to the
page as drag events from a script, because the test tool's mouse cannot start a
browser's own drag: three columns lit up with what a drop does, two dimmed, and
the card moved and was taken); "Mark as fixed" from a card's Move menu, choosing
the release; the card then reads "18 Nov: not deployed" and has no Move menu
for a developer; marking the release as deployed. As a tester — My work shows
four "Ready to verify"; the bug's page reads "Fixed in 18 Nov (deployed 16
Nov)" with the deployment in its thread; the report form offers the web app's
releases under "Found in"; at phone width the board's columns scroll sideways
and the page does not; "Verify and close" from a card's Move menu closed the bug.

**To deploy BT5:** backend first (one additive migration), then the web app.

### BT6 — test checklists and GitHub (built 16 Nov 2026)

Migration `20261223090000_bug_tracker_testing_github` (additive): tables
`BugChecklist`, `BugChecklistItem`, `BugTestRun`, `BugTestResult`,
`BugCodeLink`, `BugGithubDelivery`; column `BugNotifyPrefs.githubLogin`.

**Test checklists and runs** (`bug-testing.service.ts`)

- A checklist is a named, ordered list of things to test, each with an optional
  "how to test it" (Markdown) and a module; optionally for one app. **QA and the
  super admin write checklists; anyone on the tracker runs one.** An edit sends
  the whole list: kept items keep their id, the rest are removed. Archived
  checklists can't be run.
- A run is one go through a checklist, against a release (the app is the
  release's) or with no release (then an app is chosen), in an environment. It
  **copies the items when it starts**, so editing the checklist later changes
  no past run.
- Each item is Pass, Fail or Skipped (pressing the chosen one again puts it
  back to "not tested"), with a note. A failure names its bug in one of two
  ways:
  - **"Report a bug"** opens the report form filled in from the run (title,
    steps, app, module, environment, found-in release); sending it creates the
    bug, marks the item failed, links the two, and returns to the run. The
    bug's thread reads "reported this while testing “…” (Smoke test)" and its
    page shows the failed test.
  - **"It is already reported"** links an existing bug by its number.
  Only a failure has a bug: passing the item takes the link off.
- "Finish the run" closes it to changes (it asks first when items are not
  tested); it can be reopened. Whoever started a run, or the super admin, can
  delete it; bugs reported from it stay.
- Tests page: runs in progress, then the checklists with how their last run
  went. A release's page lists the runs against it.
- Endpoints: `GET/POST /checklists`, `GET/PATCH /checklists/:id`,
  `GET/POST /runs`, `GET/DELETE /runs/:id`, `PUT /runs/:id/results/:resultId`,
  `POST /runs/:id/finished`. `POST /bugs` takes `testResultId`.

**GitHub** (`bug-github.service.ts`, `bug-github.webhook.ts`)

- `POST /api/webhooks/github`: no sign-in; GitHub signs the raw body with the
  secret (`X-Hub-Signature-256`), and a request without a matching signature is
  refused (401) before anything is read. Without `BUG_GITHUB_WEBHOOK_SECRET`
  the endpoint answers 503.
- A **push** or **pull request** whose text names a bug (`BUG-12`) is linked to
  it: the bug's page gets a "Code" card and a line in its thread. One that says
  **Fixes / Closes / Resolves BUG-12** also **moves the bug to Fixed once it is
  merged**: the pull request is merged into a main branch, or the commit is
  pushed to one. Main branches are the repository's default branch and
  `BUG_GITHUB_MERGED_BRANCHES` (default `main,master`). QA then verifies it as
  for any fix. A bug that is already fixed or closed is only linked.
- The fix is in the name of the developer who wrote it, matched by the **GitHub
  username** they enter under Notifications, or by their account's email; with
  nobody to match, it reads "GitHub marked BUG-12 as fixed". It goes into the
  app's coming release when there is exactly one.
- Each delivery is handled once (`BugGithubDelivery`, by GitHub's delivery id,
  kept 30 days), and a change moves a bug to Fixed at most once
  (`BugCodeLink.appliedAt`): a bug QA reopened is not "fixed" again by an old
  event, only by a new commit.
- What GitHub sends is treated as data: only bug numbers and the words before
  them are read; links are built here from the repository's name and the
  commit's hash (never taken from the payload); `BUG_GITHUB_REPOS` can limit
  which repositories are listened to.
- Super admin → Settings shows whether it is set up, the address to give
  GitHub, and the latest deliveries (`GET /github`).

**To switch GitHub on** (after deploying):
1. On the server add `BUG_GITHUB_WEBHOOK_SECRET=<a long random value>` to the
   API's environment and restart it. (Optional: `BUG_GITHUB_REPOS`,
   `BUG_GITHUB_MERGED_BRANCHES`.)
2. In each of the three repositories on GitHub: Settings → Webhooks → Add
   webhook. Payload URL `https://api.hostelcare.co.in/api/webhooks/github`,
   content type `application/json`, the same secret, events "Pushes" and
   "Pull requests".
3. Each developer enters their GitHub username under Notifications in the
   tracker.
Until step 1 is done nothing changes: the endpoint refuses everything.

**Tests:** `bug-tracker.test.ts` 43 cases; `audit:permissions` 4,148 passed
(including the webhook's signature over HTTP: unsigned and wrongly signed
refused, a signed push linked, a repeat ignored); web unit tests 277.

**Web:** `BugTesting.tsx` ("#tests", "#tests/<id>", "#runs/<id>"),
`BugGithub.tsx` (the Code card, the username card, the Settings card); the
report form takes a failed test item ("#report?run=…&test=…").

**Checked in the browser** against a throwaway API (schema `hc_bug_ui`, since
dropped): as a tester — the Tests page; writing a checklist (a new row takes
the cursor); starting a run of "Smoke test" against a release; Pass and Fail
with the progress bar; "Report a bug" opening the form filled in, and sending
it returning to the run with BUG-3 linked; the run at phone width. Then three
deliveries sent to the local API with a throwaway secret: unsigned → 401; a
signed pull request → linked; a signed commit on master saying "Fixes BUG-3" →
the bug's page read "Fixed · waiting for 20 Nov to be deployed" in the
developer's name, with both changes under "Code". The tester's bell showed the
fix; a GitHub username already taken was refused with a message; the super
admin's Settings showed "Set up on the server" and both deliveries.

**To deploy BT5 + BT6:** backend first (two additive migrations), then the web
app.

### Test cases to and from Excel (16 Nov 2026, after BT6)

No migration.

- **Import** (Tests → Import; QA and the super admin): an Excel or CSV file with
  one row per test case — `Checklist`, `App`, `Description`, `Item`,
  `How to test it`, `Module` (other common header names are recognised:
  "Test suite", "Test case", "Test steps", "Feature" …). Rows with the same
  checklist name are one checklist, in order. The browser reads the file; the
  server first says what it would do (new, items replaced, or already there
  and left as it is), with every problem by line. Nothing is saved until
  "Import" is pressed, and then all of it or none. An unknown module is a
  note, not an error (the item is added without one). A checklist that exists
  is left alone unless "Replace the items" is ticked; runs keep their items.
  Up to 5,000 rows at a time (`POST /checklists/import`, `dryRun` first).
- **Export** (anyone): the Tests page exports every checklist (archived too
  when they are shown); a checklist's page exports that one. Same columns, so a
  file can go out, be edited and come back (`GET /checklists/export`).
  `GET /checklists/template` is an example to fill in, with a "How to fill it
  in" sheet.
- `bug-checklist-io.service.ts`; web `BugChecklistImport.tsx`.

**The tests we have written, as test cases:** `scripts/test-cases-export.ts`
reads the automated suites (smoke, permission audit, bug tracker, blog CMS,
hostel isolation) and writes them in the import format to
`docs/test-cases/hostelcare-test-cases.xlsx`: 78 checklists, about 2,000 test
cases, each filed under a module. Every check becomes an item in its own
words; a check that only adds to the one before ("and …") becomes an "Also:"
note on it; an expected refusal ("(403)") becomes "Expected: it is refused …".
The permission audit's generated route-by-role matrix is left out (it is not
a hand test); its named checks are in. Run it again as tests are added:
`npx tsx scripts/test-cases-export.ts`.

Checked in the browser against a throwaway API (schema `hc_bug_ui`, since
dropped): the generated file was read as 2,013 rows and 78 checklists, the one
that already existed shown as "left as it is"; ticked "replace" and imported;
the checklists and their notes read correctly; importing it again with
nothing ticked offered nothing to do; with "replace", 78 replaced; Export
downloaded all 78 with 2,018 test cases. Tests: bug-tracker.test.ts 45 cases;
web unit tests 278.

**Left for later:** video upload straight to S3
(needs the bucket's CORS); browser notifications; a daily digest instead of
one email per event, if the team finds the emails too many.
