Files

cproudlock 534f179ee6 Make main the lean product a site receives

main was 16 days and 259 commits behind the line the product is actually built
on, at contract 0.30.0 against 0.35.0, with no per-PC credential code at all. It
was neither current nor curated - just stale. This brings it forward and, at the
same time, makes it mean something: main is what a receiving site installs, and
nothing else.

WHAT IT CARRIES. Twelve plugins - backups, computers, endpoints, guides,
knowledgebase, machines, network, notifications, printers, slides, tools,
warranty - plus applications, which is manifest-less core and always ships. The
only manifest dependency inside that set is endpoints on computers, and both are
in it, so the closure is self-contained.

WHAT IT DOES NOT. employees, geenforce, measuringtools, printedparts and usb
stay on the site line. So do the Windows installer tree, the VM rehearsal
helpers, the agent tooling config, one site's data loader, the internal audit
and findings records, and the planner spreadsheet. 1,135 tracked files against
1,438.

A REMOVAL THAT BREAKS THE APP IS NOT A REMOVAL, and two nearly shipped:

deploy/site-profile-universal.json still named all seventeen plugins. It is the
file docs/DEPLOY.md tells a site to provision from, so a fresh install would
have failed at `flask plugin apply-profile` with PluginError - the first thing a
receiving site does, broken by the branch meant to serve them. It now names the
twelve that exist, and its comment says the two must agree.

agent/ was never refreshed. Whoever populated this branch copied shopdb/,
plugins/, frontend/ and tests/ from the site line and left the agent tree at its
September state: 22 C# and PowerShell sources missing, including AgentCredentials,
EnrollmentService, AgentHttpFactory and the fleet-alert client, plus one file the
site line had deleted still present. The old tree is internally consistent, so it
compiles, and nothing in CI builds it - every gate was green over a server that
speaks enrollment and per-PC credentials to a bundled agent source that cannot.
Resynced whole.

DECISIONS THIS ENCODES, rather than defers:

- The plugin-authoring lab builds printedparts, whose manifest depends on
  employees, so it could not stay. The lab remains on the site line and main
  ships no build-along tutorial. That is a real loss for an adopting developer
  and is recorded here rather than discovered later.
- Recognition, Training and Recertification notifications are no longer seeded.
  Each splits one notification into a card per employee and renders a photo,
  which needs a plugin this branch does not bundle. Seeding them would offer an
  author a type that cannot resolve anybody. A site that installs employees gets
  them from that plugin's own seed.
- Windows/IIS is documented as the legacy path throughout, and the README leads
  with Docker, because that is what a receiving site gets.

The API description is regenerated for THIS branch - 347 paths and 483
operations, down from 415 and 573 - so the published contract describes what is
here rather than what the site line serves. docs/CONFIG.md lost the two
measuring-tool label keys the code no longer declares, which two lanes had
decided opposite ways.

Suite: 3124 passed, 6 skipped. Naming and style gates pass. The docs gates run
rather than skip, and every index line count is derived from the file it names.

2026-09-19 11:24:40 -04:00

6.1 KiB

Raw Blame History

The floor map: buildings, levels and marker positions

The map shows where things physically are. This page is the operator's view for whoever maintains it: loading a floor plan, adding a second floor or a second building, and moving the markers when the plan changes. The reasoning behind the model is ADR-017.

The model in three sentences

A building holds one or more levels. A level owns a floor-plan image (one per theme) and the pixel size of that image. A marker's position is an X and Y in the pixels of ONE level, so every position names the level it belongs to.

That last point is the whole design. Coordinates alone are meaningless: 1200,900 is a spot on the ground floor and a different spot on the second floor. A marker whose level is unknown shows as level unknown and is not drawn, because drawing it on the default plan would look completely correct while pointing at the wrong part of the building.

Loading a floor plan

Settings > Buildings and levels.

Add a building if you do not have one. A single-building site needs exactly one, and it can be called anything.
Add a level. Give it a name people use out loud - "Ground floor", "Mezzanine", "Second floor" - and a sort order that puts the list in the order someone would walk it. Name and order are separate on purpose: levels are not reliably numbered, and leaving gaps in the order lets you insert one later without renumbering everything.
Upload the plan, per theme. A light-theme image is enough to start; if there is no dark version, the light one is used in both.

The level takes its pixel size from the image you upload, while the level is still empty. Once markers are on it, an upload whose size does not match reports the mismatch and changes nothing. That is deliberate - see below.

Supported: PNG, JPEG, GIF, WEBP and SVG. An SVG is served with headers that stop it executing as script, so a plan exported from a CAD tool is safe to use.

Placing markers

Two ways, both fine:

One at a time, from the asset's own form: the map-position picker opens on the level the marker is already on, and you can switch level inside the picker. The saved position states which drawing it is on.
Many at once, in the map editor. Filter to what you are working through - unplaced, needs-review, or one level - search for a specific thing, place it, and confirm. Placing a marker by hand counts as confirming it.

A location can carry a position too, which acts as the default for assets in it.

When the floor plan changes

This is the case that needs care, and the reason the tooling exists.

A new plan of the SAME dimensions: upload it and you are done. Markers keep their coordinates and still line up.

A new plan of DIFFERENT dimensions, or a real move: the coordinates are pixels of the old image, so every marker is now in the wrong place relative to the drawing. Do NOT fix this by editing the level's width and height - that just reinterprets every existing position against a new scale.

Use Recalibrate in the map editor:

Pick two or more landmarks - features you can find on both the old and the new plan. Corners of the building, a doorway, a column. Two is the minimum; three or four spread across the plan is better.
For each, give the old coordinates and the new ones.
Review the dry run. It lists every marker's old and new position and flags anything that would land off the drawing. Nothing has changed yet.
Apply it. The previous positions are snapshotted first.

The transform is worked out separately for the X and Y axes from your landmarks, and never guessed from the image dimensions. That matters in the exact case this was built for: a plan that gained a floor below it got taller without anything being rescaled, and a size-derived scale would have stretched everything vertically.

After a recalibration every affected marker is marked needs review, because a transform is a good starting guess and nothing in the coordinates can tell you which machines actually moved. Work the needs-review filter, correct what is off, and confirm as you go.

Undo

Every bulk change snapshots the positions first, and a restore snapshots before it restores, so an undo is itself undoable. The history is in the map editor: what caused each snapshot, when, and whether it has been restored. A restore puts back the level and the review state, not only the coordinates.

Assets deleted since a snapshot are reported and skipped rather than failing the whole restore.

Adding a second building or a second floor

Add it, upload its plan, then move the markers that belong on it. In the map editor, markers on other levels are badged, so you can see what still needs moving.

Do not stack two floors onto one tall image. It looks simpler and it makes the level implicit in the Y coordinate - "above 2550 means upstairs" - which nothing can validate and which breaks the moment either plan is redrawn.

Things that are not levels

Locations are where something is in words ("Cell 4", "Gage lab"). A level is which drawing. A location can name a level, but they are different things.
Business units are organisational, not physical.

Known limits

The printer-installer map (the standalone program that installs printers by clicking a floor plan) has one plan compiled into it and does not know about levels. It is accurate for the default level only. See PRINTER-INSTALLER section 6.
The first-run setup wizard still asks for one site-wide blueprint; those settings no longer drive the map. Use Settings > Buildings and levels.
Map PDF export covers the level you are looking at.

For integrators

Reading levels is public and writing them needs an admin; repositioning markers needs assets.edit. The rules and the parameters are both in the generated spec at /api/docs. If you import positions from another system, send levelid with every coordinate - see IMPORT-API.

6.1 KiB Raw Blame History