# User Guide

Aumni AMS is Aumni Techworks LLP's internal asset management system: the
register of company hardware, who currently holds it, its warranty cover,
and the paper trail behind every one of those facts.

This guide covers everything an ordinary signed-in account can do. Almost
every screen in the system — the asset register, employees, assignments,
returns, warranty, QR labels, imports, reports and the audit log — is open
to every signed-in user. The exceptions are called out where they matter:
deleting a record is generally restricted to **master users**, and two areas
(user accounts, application settings) are master-only end to end. If you are
a master user, read this guide first, then `docs/ADMIN_GUIDE.md` for what's
exclusive to your role.

---

## 1. Signing In

Go to your organisation's Aumni AMS address and sign in with the email
address and password a master user gave you.

There is no "Forgot password?" link. This system has no email-based
password reset — if you've forgotten your password, contact a master user
and ask them to reset it (see `docs/ADMIN_GUIDE.md`).

Sign-in attempts are rate-limited: too many wrong passwords in a short time
(from the same address or the same network) locks further attempts out for
a short cooldown before you can try again.

### Choosing your password

If a master user just created your account or reset your password, you were
given a **temporary password**. The system will not let you do anything
else until you replace it — signing in redirects you straight to **Choose a
new password**, and every other page bounces you back there until you do.

1. Enter the new password twice.
2. Click **Update Password**.

Your new password must meet the minimum length configured for the system
(10 characters by default; a master user can raise this in Settings, never
lower it below 10). Changing your password immediately signs out every
other session your account has open — including, after a forced change, the
master user's own view of your account.

If you'd rather not set a password right now, **Sign out instead** is
available from the same screen.

### Changing your password later

From the account menu in the top-right corner, choose **Change Password**.
This time you'll need your current password as well as the new one — the
new password must also be different from your current one. As with a forced
change, saving signs you out everywhere else.

### Your profile

The same account menu has **My Profile**, where you can update your own
name and the email address you sign in with. Your access level (regular
user or master) and account status are not editable here — only a master
user can change those.

---

## 2. The Dashboard

The dashboard is your landing page after signing in and after any forced
password change. It's a live snapshot, cached for about five minutes, so a
number here can lag a very recent change by a few minutes.

**KPI cards** across the top (each one links to a filtered list):

| Card | What it counts |
|---|---|
| Total Assets | Every asset on the register |
| Assigned | Assets currently issued to someone |
| Available | Assets in stock and active |
| Under Repair | Assets currently at repair |
| Lost | Assets marked lost |
| Retired | Assets marked retired |
| Warranty Expiring | Featured warranty periods expiring within 30 days |
| Warranty Expired | Featured warranty periods already expired |
| Total Employees | Every employee on record |
| Active Employees | Employees with status Active |

**Charts**: Assets by Category, Asset Status Distribution, Assets by
Department, Assets by Location, Warranty Status, and Monthly Asset
Procurement (purchases by month, trailing 12 months). Category/department/
location charts show the top entries plus a single "Other" bar once there
are more than a handful.

**Operational widgets**, each linking through to the full list:

- **Recently Assigned Assets** and **Recently Returned Assets** — the latest
  handovers and returns.
- **Assets Awaiting Return** — active assignments past their expected return
  date.
- **Upcoming Warranty Expiry** — featured coverage expiring in the next 90
  days.
- **Recent Activity** — the latest audit log entries system-wide.
- **Employees Holding Most Assets** — who currently holds the most items.

**Quick Actions** at the bottom link straight to Add Asset, Import Assets,
Assign Asset, Add Employee and Warranty → Expiring Soon.

If you're a master user, an **Administration** panel also appears, showing
user-account counts (total, active, disabled, masters) — see
`docs/ADMIN_GUIDE.md`.

---

## 3. The Asset Register

**Assets → All Assets** is the full inventory.

### Browsing, searching and filtering

The filter bar supports:

- **Search** — matches asset tag, name, serial number and manufacturer.
- **Status** — In Stock, Assigned, Under Repair, Damaged, Lost, Retired,
  Disposed.
- **Condition** — New, Good, Fair, Poor, Unusable.
- **Category**, **Location**, **Department**.

Each row shows the asset tag and name, category, location, department,
status, and — if it's currently assigned — who holds it. Selecting rows
with the checkboxes enables **Export Selected** (downloads exactly the
assets you ticked, ignoring the current filters); leaving nothing selected
and clicking the plain **Export** button in the page header exports
whatever the current filters show. Either way you get an `.xlsx` file.

Master users additionally see a **Deleted** count/link and a **Delete
Selected** bulk action; deleting an asset is master-only (see below).

### Adding and editing assets

**Add Asset** is open to every user. The form is grouped into sections:

- **Identity** — Asset Name (required), Serial Number (optional, must be
  unique).
- **Initial Status** *(create only)* — an asset can only start life as
  **In Stock**, **Under Repair** or **Damaged**; every other status is
  reached later through a governed transition (see below). Plus
  **Condition**.
- **Classification** — Category (required), Location, Department.
- **Technical Information** — Manufacturer and Model (both offer
  autocomplete from values already on file), plus an open-ended
  **Specifications** table (attribute/value rows — RAM, CPU, IMEI, whatever
  is relevant to that kind of asset).
- **Purchase Information** — Vendor (autocomplete), Purchase Date (cannot be
  in the future), Purchase Cost, Currency, Invoice Number, PO Number.
- **Notes** — free text, visible to anyone who can view the record.
- **Availability** — an **Asset is active** checkbox; an inactive asset
  keeps its history but won't be offered when assigning to an employee.

You never type an asset tag. Every asset — created by hand or through
import — is issued one automatically (e.g. `AUM-LAP-0042`), following the
prefix, numbering scope and digit-padding a master has configured in
Settings.

**Edit Asset** has the same fields except Status, which never appears on
the edit form — status only moves through the dedicated **Change status**
control on the asset's own detail page, so there is always a record of who
changed it and when.

### The asset detail page

Opening an asset (its tag, from any list) shows:

- **Overview** — tag, serial number, category, location, department, active
  flag, current status and condition badges.
- **Technical Information** and **Purchase Information** — everything from
  the form above, plus a computed **Age** in months from the purchase date.
- **Assignment History** — every custody period this asset has ever had:
  employee, assigned-on and returned-on dates, condition on issue vs.
  return, and status (Currently Held / Returned), with an **Overdue** badge
  if applicable.
- **Warranty History** — every coverage period on record for this asset,
  with type, provider, coverage dates and status (Active / Expiring Soon /
  Expired). The row marked **Current** is the one the rest of the system
  (dashboard, warranty alerts) treats as this asset's active coverage.
- **Notes**, if any were recorded.
- **Recent Activity** — the last six audit entries for this asset, with a
  **View Full History** link to the complete, paginated trail.

The right-hand column carries the working panels:

- **Current Status** — shows who currently holds it (if assigned), and a
  **Change status to** dropdown offering only the statuses this asset is
  legally allowed to move to next (a Disposed asset, for example, offers
  none — that's a final state).
- **Warranty** — the current coverage at a glance, with **Renew** (if one
  exists) or **Add** (if none does).
- **QR Code** — see §5.
- **Record** — who added the asset and when, and who last updated it.
- **Delete asset** *(master users only)* — soft-deletes the asset; a
  deleted asset can be restored from the Deleted list. Deleting is refused
  outright while the asset is currently assigned — return it first.

From this page, an **Assign** button appears if the asset is available, or
**Record Return** if it's currently out with someone.

---

## 4. Assigning and Returning Assets

Custody is a two-step workflow: issuing an asset, and — separately, later —
recording its return.

### Assigning an asset

Start from **Assets → Assign Asset**, or from an available asset's own
**Assign** button (which preselects that asset), or from an employee's
**Assign Asset** button (which preselects that employee).

1. Choose the **Asset** (only assets currently In Stock are offered) and
   the **Employee** (only employees with status Active or On Notice can
   receive assets).
2. **Assigned On** (defaults to today, cannot be in the future) and,
   optionally, an **Expected Return Date** — leave it blank for an
   open-ended issue.
3. **Condition on Issue** (defaults to the asset's current condition).
4. Optionally, a **Handover Location**, an **Acknowledgement Reference**
   (if you have a signed handover form), and **Issue Notes**.
5. Click **Assign Asset**.

The asset's status becomes **Assigned** and it disappears from the
available pool until it's returned. Only one active assignment can exist
for a given asset at a time — the system enforces this even against a
mistake or a race between two people acting at once.

### Returning an asset

**Assets → Returns** lists every assignment currently outstanding, oldest
expected-return-date first so overdue items surface at the top. Each row
has a **Return** button (also reachable from the asset's own detail page,
or the employee's **Assets Held** panel).

1. On the return form, confirm the asset and who is returning it.
2. **Returned On** (defaults to today; cannot be before the date it was
   assigned).
3. **Condition on Return** — this matters: a **Poor** condition
   automatically routes the asset to **Under Repair**, and **Unusable**
   routes it to **Damaged**, instead of back into the available pool. New,
   Good or Fair conditions send it back to **In Stock**.
4. Optionally, **Return Notes**.
5. Click **Record Return**.

An assignment that has already been returned cannot be returned again.

---

## 5. QR Labels

Every asset has a QR code that, when scanned, opens straight to its detail
page (scanning doesn't require you to have finished a pending password
change first — a physical label handed to you has nothing to do with your
own account).

### A single asset's label

From an asset's detail page, the **QR Code** panel offers:

- **SVG** / **PNG** — download the code image directly.
- **Print Label** — a print-ready single label sized for clarity, opened in
  its own page with a **Print** button that opens your browser's print
  dialog.

### Bulk label sheets

**Assets → QR Labels** is a picker with the same search/category/location/
department filters and row-selection checkboxes as the asset register.

1. Filter and tick the assets you want labels for (the count of selected
   assets is shown above the table).
2. Choose a **template**:

   | Template | Layout | Labels per sheet |
   |---|---|---|
   | Standard | 3 × 8 | 24 |
   | Large | 2 × 5 | 10 |

3. Click **Preview Labels**. The preview page shows exactly what the PDF
   will contain.
4. From the preview, either **Print** (browser print dialog) or **Download
   PDF** for the sharpest, most reliable print quality on label stationery.

A single run is capped at **500 assets** (about 21 sheets on the Standard
template). Selecting more than that, or selecting nothing at all, sends you
back to the picker with an explanatory message — split a larger batch into
multiple runs.

---

## 6. Warranty

**Assets → Warranty** is the full register of coverage periods across every
asset, with cards for Active, Expiring in 30/60/90 Days, and Expired, each
linking to that filtered view. **Expiring Soon** groups everything into
Critical (≤30 days), Upcoming, and Expired. Filters on the main list: search
(asset, provider or reference), Type (Manufacturer Warranty, Extended
Warranty, AMC, Insurance), and Status (Active / Expiring Soon / Expired).

An asset can carry more than one coverage record at a time (a manufacturer
warranty plus an AMC, for instance) — only one per asset is ever the
**Current** one shown on the dashboard and in warranty alerts.

### Recording new coverage

From an asset's detail page, **Warranty → Add** (or **Add Warranty** in the
Warranty History panel):

1. **Type** — Manufacturer Warranty, Extended Warranty, AMC or Insurance.
2. **Provider** and **Reference / Policy Number** (optional; provider
   offers autocomplete from values already on file).
3. **Start Date** and **End Date** (end cannot be before start).
4. **Cost**, optional.
5. **Notes**, optional.
6. **Document** — optionally attach the contract, invoice or a photo of the
   warranty card (PDF, JPG or PNG, up to 10 MB).
7. Click **Add Warranty**.

An asset's very first warranty is always made the featured ("Current") one
automatically.

### Renewing coverage

From an asset's **Warranty** panel, click **Renew** (only offered against
the current coverage period). Renewing **does not edit** the old record —
it closes it exactly as it stands and opens a brand-new one of the same
type, defaulting to start the day after the old one ends and run a year
from there. You can change the dates, provider, reference, cost, notes, and
attach a new document before saving. The old coverage period stays on the
Warranty History panel for reference.

### Downloading a warranty document

Where a document was attached, a download icon appears next to that
warranty on the asset's Warranty History panel.

### Deleting coverage

Deleting a warranty record is master-only, and soft — it can be restored
from the deleted list afterwards.

---

## 7. Employees

**People → Employees** lists the company roster assets are issued to.
Filters: search (name, code, email, designation), Status (Active, On
Notice, Exited, Inactive), Department, Team.

**Add Employee** / **Edit Employee** capture: Employee Code (required,
unique), First/Last Name, Work Email, Personal Email, Phone, Department,
Designation, Team, Location, Reports To (their manager), Status, Date of
Joining, Date of Exit, and Notes. An employee cannot be set to report,
directly or indirectly, to themselves.

Employee status governs what they can do in the rest of the system:

| Status | Can receive assets? |
|---|---|
| Active | Yes |
| On Notice | Yes |
| Exited | No |
| Inactive | No |

An employee's detail page shows their profile, employment and reporting
line, plus:

- **Assets Held** — everything currently issued to them, each with a
  one-click **Return** button.
- **Assignment History** — every asset they've ever been issued, returned
  or not.

Deleting an employee is master-only, and is refused outright while they
still hold any asset — return everything first.

---

## 8. Reference Data: Categories, Departments, Locations

**Configure → Categories / Departments / Locations** hold the lookup values
the rest of the system is built on. Viewing, creating and editing all three
are open to every signed-in user; deleting and restoring are master-only
(see `docs/ADMIN_GUIDE.md`).

Worth knowing as a regular user:

- **Categories** support one level of subcategory (e.g. "Computers /
  Laptops"). A category's short code (e.g. `LAP`) becomes the middle
  segment of every asset tag issued under it.
- **Locations** carry a full postal address (used on exports and reports).
- **Departments** can optionally have a head employee.

---

## 9. Importing Assets in Bulk

**Data → Import** brings an existing spreadsheet of assets into the
register, without typing them in one at a time. It's a three-step flow:
upload, preview, confirm — nothing is written to the register until you
explicitly confirm.

1. **Download the Template** (`.xlsx`) — start from its exact columns:
   Asset Name, Category, Serial Number, Manufacturer, Model, Vendor,
   Location, Department, Status, Condition, Purchase Date, Purchase Cost,
   Currency, Invoice Number, PO Number, Notes. Category, Location and
   Department are matched **by name** against what's already set up in
   Categories/Locations/Departments — a subcategory can be written as
   either its own name or `Parent / Child`. You never type an Asset Tag;
   one is issued automatically per imported row, exactly as for a
   manually-added asset.
2. **Upload** the filled-in file (Excel `.xlsx` or CSV, up to 10 MB).
3. **Preview** — every row is validated (nothing is written yet), with
   problem rows listed first. Three counts are shown: Total Rows, Ready To
   Import, Will Be Skipped. Each invalid row lists exactly what's wrong
   with it.
4. **Import** — click the button to write only the rows that passed. Rows
   that failed are never written, and never block the rows that were fine.

After the import finishes, the batch's own page shows how many rows
succeeded and how many failed. If any failed, **Download Error Report**
gives you back the same file with an extra column explaining each problem —
fix those rows and upload the corrected file again; rows that already
succeeded won't be duplicated as long as their Serial Number is unchanged.

A single import is capped at a configurable number of rows (2,000 by
default) — a much larger file is rejected outright with a message telling
you to split it.

### What common row errors mean

- **"Asset Name is required."** — that cell was empty.
- **"Category ':name' was not found."** (also Location / Department) — the
  text in that cell doesn't match any name already set up under
  Configure → Categories/Locations/Departments. Add it there first, or fix
  the spelling in your file.
- **"Status ':value' is not valid on import — use In Stock, Under Repair or
  Damaged."** — an imported asset, like a manually-created one, can only
  start in one of those three statuses. Anything else (Assigned, Lost,
  Retired, Disposed) is reached later through the asset's own **Change
  status** control, not through import.
- **"Serial Number ':serial' already exists. It may be in the deleted
  list."** — another asset (possibly a deleted one) already has that
  serial number.
- **"Serial Number ':serial' is duplicated in this file (also row
  :row)."** — the same serial number appears twice in your spreadsheet.
- **"Purchase Date ':value' could not be read. Use DD-MM-YYYY."** — the
  date didn't parse; retype it in that format (or as a real date cell in
  Excel).

---

## 10. Reports

**Insights → Reports** is a catalogue of 22 reports across five categories.
Every report is filterable, sortable, paginated on screen, and exportable —
the on-screen table, the Excel file and the PDF are always built from the
exact same definition, so they can never disagree.

| Category | Covers | Reports |
|---|---|---|
| Inventory Reports | The asset register itself | Complete Asset Register, Assets by Category, Assets by Department, Assets by Location, Assets by Status, Asset Ageing Report |
| Employee Reports | Who holds what | Employee Asset Report, Unassigned Employees, Employees Holding Multiple Assets, Employee Assignment History |
| Assignment Reports | The custody ledger | Current Assignments, Returned Assets, Overdue Returns, Asset Movement History |
| Warranty Reports | Coverage standing | Active Warranties, Expiring Warranties, Expired Warranties, Warranty Renewal History |
| Audit Reports | The compliance trail | User Activity, Asset Activity, Assignment Activity, Import Activity |

To run one: open it from the Reports landing page, apply whatever filters
it offers (search, dropdowns, date ranges — each report offers only the
filters that make sense for it), and use the column headers to sort where a
column supports it.

### Exporting

Each report's toolbar offers:

- **Export Excel** — downloads every row matching your current filters as
  an `.xlsx` file. There is no row limit on this.
- **Export PDF** — renders the same rows to a landscape A4 PDF. This *is*
  capped, at 2,000 rows; if your filtered result is larger, the button
  returns you to the report with a message asking you to narrow the
  filters or use Excel instead.
- **Print** — opens your browser's print dialog directly on the report.

---

## 11. Audit Log History

**Insights → Audit Logs** is the read-only compliance trail: every create,
update, delete and restore on the records that carry history (Assets,
Assignments, Warranties, Employees, Departments, Locations, Categories,
Users), plus sign-ins/sign-outs, password changes, assignment/return
events, status changes, exports, imports and settings changes. Nothing on
this screen ever writes anything — that's what makes it safe for every
signed-in user to see, not just masters.

The top of the page shows Total Events, Today, This Week and Active Users
(30 days). Filters: search (matches the description text), User, Module,
Action (event type), and a date range. Click **View** on any row to see the
full detail: timestamp, user, module, record ID, IP address, user agent,
the URL the action was performed from, and — for anything that changed
data — a **Changes** table listing every field's before and after value.

For an individual record — an asset, an employee, and so on — the fastest
path is usually that record's own **Recent Activity** panel and its **View
Full History** link, rather than filtering the global log by hand.

**Export** downloads the currently filtered log as an `.xlsx` file.

---

## 12. Troubleshooting

- **"Status ':value' is not valid on import..."** — see §9. An imported
  asset can only start In Stock, Under Repair or Damaged; other statuses
  are set afterwards from the asset's own page.
- **An Export or Print button doesn't seem to do anything.** Excel/PDF
  exports and the audit log export are plain file downloads, not an
  on-screen action — there is no progress spinner for them. Check your
  browser's download tray or downloads folder, and check whether your
  browser or an extension is blocking a pop-up/download from this site.
  (Import's upload/confirm buttons *do* show a spinner while working —
  those genuinely take a few seconds for a large file.)
- **A PDF export refuses with "This report has more than 2,000 rows..."**
  — narrow the report's filters, or use Export Excel instead, which has no
  row cap.
- **"Select 500 assets or fewer for one label run..."** on QR Labels — you
  selected more than the bulk cap. Split the run: print in batches of 500
  or fewer.
- **A field disappeared from the form / a status option isn't offered.**
  Assets and assignments only offer the transitions or values that are
  currently legal (e.g. an asset already Assigned won't offer "In Stock" as
  a status option; only In Stock assets are offered when assigning). This
  is deliberate — it's a rule, not a bug.
- **"An asset with this serial number already exists. It may be in the
  deleted list."** — a deleted asset still occupies that serial number for
  uniqueness purposes. Check the Deleted list (a master user can restore
  it) rather than creating a duplicate.
- **You can't delete a category, department or location.** — these refuse
  to delete while anything still references them (subcategories, assets,
  employees). The error message tells you exactly what's still attached;
  reassign or delete those first, or deactivate the record instead of
  deleting it.
- **You were signed out unexpectedly.** Changing your password (forced or
  voluntary) signs out every other session on your account by design. A
  master user disabling or deleting an account also ends its sessions
  immediately.
- **Locked out after too many failed sign-in attempts.** Wait for the
  cooldown shown in the error message, then try again — or ask a master
  user to confirm your account isn't disabled.

If something doesn't match this guide, check with a master user before
assuming it's a bug — several behaviours described above (row caps,
password length, what's on the dashboard) are configurable and may have
been changed for your organisation.
