534f179ee6
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.
138 lines
6.1 KiB
Markdown
138 lines
6.1 KiB
Markdown
<!-- docmeta
|
|
purpose: howto
|
|
audience: operator, adopter
|
|
status: current
|
|
summary: Load floor plans, place markers, and move every marker safely when a plan is redrawn.
|
|
loadwith:
|
|
-->
|
|
|
|
# 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](adr/ADR-017-buildings-and-levels.md).
|
|
|
|
## 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.**
|
|
|
|
1. Add a building if you do not have one. A single-building site needs exactly
|
|
one, and it can be called anything.
|
|
2. 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.
|
|
3. 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:
|
|
|
|
1. 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.
|
|
2. For each, give the old coordinates and the new ones.
|
|
3. 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.
|
|
4. 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](PRINTER-INSTALLER.md) 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](IMPORT-API.md).
|