741dda5be7
The 0.11.0 release changed what a map position means and six documents still described the model it replaced. Each of these could have caused a real mistake rather than being merely out of date: - IMPORT-API mapped legacy mapleft/maptop to mapx/mapy with no mention of the level, so a scripted import - including the classic-ASP one still to run against production - would have produced markers the map shows as "level unknown". It now maps levelid too and says how to resolve the default level. - API-REFERENCE enumerates the unauthenticated surface in full, because that is what a deploy reviewer reads, and the three public /api/maplevels reads were missing from it. Also records why the write split is asymmetric: repositioning needs assets.edit, creating a level needs admin, since a level's dimensions are the coordinate space every marker on it is expressed in. - CONFIG still presented the four map_* settings as live, telling the reader to re-upload a blueprint in a settings page that no longer drives the map. They are marked superseded and kept for downgrade. - UPGRADE gained a 0.11.0 section: nothing moves on screen, and replacing a blueprint with one of different dimensions moves every marker on that level, so recalibrate from landmarks rather than editing width and height. - PLUGIN-HOOKS now states that a map overlay keys on assetid and must not return coordinates or a level - a second copy of a position is one that can disagree. Adds FLOOR-MAP.md, the operator's page: loading a plan, placing markers, and what to do when the plan changes, with the reasoning left in ADR-017. START-HERE routes to it from the new-site path, and specifically as the page to read BEFORE a floor plan changes.
3.0 KiB
Start here
ShopDB is a per-site asset platform: one instance per plant, plugins for what each site tracks. These pages document the server, the plugin contract, and the tools that run on shop-floor PCs.
Find yourself below. Each row is the shortest correct path, not everything that exists.
I am standing up ShopDB at a new site
- INSTALL-WINDOWS - one offline installer, start to finish.
- OPERATE-WINDOWS - restart, logs, backups, upgrades.
- CSV-IMPORT if the site's data is in spreadsheets, or IMPORT-API if there is a source database to script against.
- FLOOR-MAP - load the site's floor plans and place markers. Also the page to read BEFORE a plan changes: it covers moving every marker onto a redrawn plan without doing it one at a time.
Do not follow INSTALL-WINDOWS-IIS for a new site. That is the manual procedure, kept for hand-built servers that predate the installer, and following it produces a server the installer then refuses to upgrade.
I am deploying the shop-floor tools
Read FLEET-ARCHITECTURE first - it is one page and it is what makes the rest make sense.
Then ADOPTING-AT-ANOTHER-SITE, which has worked examples for Intune, GE-Enforce and manual installation, and says where each artifact comes from.
I am writing a plugin
- PLUGIN-QUICKSTART - scaffold and first run.
- PLUGIN-HOOKS - the contract. Authoritative.
- PLUGIN-LAB-PRINTEDPARTS - a real plugin built end to end, to type along with.
- PLUGIN-EXTERNAL-REPO if it lives in its own repository, and CONTRACT-STABILITY before you choose a version pin.
I am integrating with the API
- LLM-GUIDE (
docs/llms.txtin the repo, also served at/api/docs/llms.txt) - auth, the response envelope, common recipes. Short, and the envelope section is the part people get wrong. GET /api/docson any running instance - the full spec, browsable.- API-REFERENCE for prose, COLLECTOR-INTEGRATION if you are feeding data in from a PC.
I am trying to understand why something is built this way
The ADRs. They are the decision record, they say what was rejected and why, and they are the fastest way to avoid relitigating a settled question. PROJECT-MAP lists them all with their status, along with the current versions and every migration head - it is generated, so it is never stale.
Something is broken
- Server: OPERATE-WINDOWS, then
shopdb-admin.ps1 check -Json. - A PC or a bay: the symptom table at the end of FLEET-ARCHITECTURE says which piece to open first.
- A deploy that half-worked: UPGRADE and BACKUP-RESTORE.