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.
68 lines
3.0 KiB
Markdown
68 lines
3.0 KiB
Markdown
# 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
|
|
|
|
1. [INSTALL-WINDOWS](INSTALL-WINDOWS.md) - one offline installer, start to finish.
|
|
2. [OPERATE-WINDOWS](OPERATE-WINDOWS.md) - restart, logs, backups, upgrades.
|
|
3. [CSV-IMPORT](CSV-IMPORT.md) if the site's data is in spreadsheets, or
|
|
[IMPORT-API](IMPORT-API.md) if there is a source database to script against.
|
|
4. [FLOOR-MAP](FLOOR-MAP.md) - 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](INSTALL-WINDOWS-IIS.md) 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](FLEET-ARCHITECTURE.md) first - it is one page and it
|
|
is what makes the rest make sense.
|
|
|
|
Then [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md), which has worked
|
|
examples for Intune, GE-Enforce and manual installation, and says where each
|
|
artifact comes from.
|
|
|
|
## I am writing a plugin
|
|
|
|
1. [PLUGIN-QUICKSTART](PLUGIN-QUICKSTART.md) - scaffold and first run.
|
|
2. [PLUGIN-HOOKS](PLUGIN-HOOKS.md) - the contract. Authoritative.
|
|
3. [PLUGIN-LAB-PRINTEDPARTS](PLUGIN-LAB-PRINTEDPARTS.md) - a real plugin built
|
|
end to end, to type along with.
|
|
4. [PLUGIN-EXTERNAL-REPO](PLUGIN-EXTERNAL-REPO.md) if it lives in its own
|
|
repository, and [CONTRACT-STABILITY](CONTRACT-STABILITY.md) before you choose
|
|
a version pin.
|
|
|
|
## I am integrating with the API
|
|
|
|
1. [LLM-GUIDE](LLM-GUIDE.md) (`docs/llms.txt` in 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.
|
|
2. `GET /api/docs` on any running instance - the full spec, browsable.
|
|
3. [API-REFERENCE](API-REFERENCE.md) for prose, [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md)
|
|
if you are feeding data in from a PC.
|
|
|
|
## I am trying to understand why something is built this way
|
|
|
|
[The ADRs](ADR-001-asset-as-platform-contract.md). 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](PROJECT-MAP.md) 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](OPERATE-WINDOWS.md), then `shopdb-admin.ps1 check -Json`.
|
|
- A PC or a bay: the symptom table at the end of
|
|
[FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) says which piece to open first.
|
|
- A deploy that half-worked: [UPGRADE](UPGRADE.md) and
|
|
[BACKUP-RESTORE](BACKUP-RESTORE.md).
|