Docs: handoff moved to docs/aimsight/, CLAUDE.md and README.md rewritten (D-083)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
0df340231a
commit
cbdf91068b
4 files changed
+136
-157
No files matched your search
@@ -0,0 +1,149 @@
|
||||
# Handoff: site health and client notifications (G)
|
||||
|
||||
25 oct. 2026 · @Someone
|
||||
|
||||
> Document de cadrage reçu du product owner (collé par l'utilisateur le 2026-10-26), enregistré tel quel en anglais. Seule la section « Écarts constatés » en fin de fichier est de nous.
|
||||
|
||||
## Why this exists
|
||||
|
||||
Your work is sub-project G of a larger effort: make the client responsible for the quality of their installation, so that AIMsight stops doing unpaid support for problems that are not the instrument's fault.
|
||||
|
||||
Today, when a target is dirty, hidden by vegetation, a reference falls off a wall, or the camera support moves, the client sees a jump in the data and calls AIMsight. A Leica or Topcon user would never call the manufacturer about a dirty prism. The goal is the same for AIMsight: the system detects these conditions, says clearly what happened and who has to act, and tells the client's own contact person directly.
|
||||
|
||||
The full map is in Installation Quality Map. It splits the effort into seven sub-projects:
|
||||
|
||||
| Id | Sub-project | Who | What G takes from it |
|
||||
|---|---|---|---|
|
||||
| A | Quality contract and responsibility split | Product owner | The words for each state and who is responsible for each cause |
|
||||
| B | Target visibility and signal health | Separate thread | Per-target visibility status (bright enough, contrasted, dimming over time) |
|
||||
| C | Reference network quality engine | Later | Reference network score per measurement |
|
||||
| D | Planning assessor | Later | Nothing directly |
|
||||
| E | Commissioning acceptance report | Later | The baseline a site is compared against |
|
||||
| F | Stricter filtering and marking of degraded data | Separate thread | Quality state per measurement (valid, degraded, withheld) with a reason |
|
||||
| G | Site health and client notifications | You | |
|
||||
|
||||
In short, G is the part the client sees every day: the health of each site and the messages that tell them to act.
|
||||
|
||||
## Scope of G
|
||||
|
||||
G covers four things: a health status per site, notifications to the client, self-service explanations of events, and the rule that every status says who has to act.
|
||||
|
||||
### In scope
|
||||
|
||||
- **Site health page and home page status.** One line per domain, per site, per day. Your system domains (battery, storage, cellular, temperature, offline) are the first half. The second half is the measurement domains: images arriving on schedule, targets visible, references available, camera stable.
|
||||
- **Notifications to the client's contact person** by e-mail, SMS or web, using the existing alarm and notification framework. The message names the site, what happened, since when, and what the client should check.
|
||||
- **Event explanation for jumps in the data** (your Analyze tab): obstruction or visibility loss, reference change, camera movement, or real movement of the structure. Each reading says "consistent with", never more.
|
||||
- **Responsibility label on each status**: instrument (AIMsight acts), installation (client acts: clean, clear, re-fix), environment (fog, snow, rain: nobody acts, it passes), or unknown.
|
||||
|
||||
### Out of scope (owned by other threads, consume their output)
|
||||
|
||||
- How visibility is measured per target (B). G shows it and notifies on it.
|
||||
- Which measurements are withheld from exports and alarms (F). G explains why data is withheld.
|
||||
- Reference network geometry and precision (C).
|
||||
- The meaning of quality states and what is billable support (A).
|
||||
|
||||
Until B and F deliver their states, G can start from what already exists: the match error per target (`error`, `error_threshold`), the per-reference status code (`inlier`), `sigma0`, and the camera movement signals (pan, tilt, rotation, scale).
|
||||
|
||||
## What exists today
|
||||
|
||||
Most of the building blocks G needs are already in the cloud code. Checked on 25 Oct 2026 in monitoring-dashboard (branches `new_db` and `origin/explo`).
|
||||
|
||||
| Building block | Where | State |
|
||||
|---|---|---|
|
||||
| System domains: battery, storage, cellular, temperature, with a colour per day | `app/diagnostics/<domain>/`, `domains.py`, `status.py` (branch explo) | Your work. Shown on the System page and the home page |
|
||||
| Offline stations | `app/diagnostics/offline.py` (branch explo) | Your work. "Recently offline" list, "Before going offline" section |
|
||||
| Displacement views and Analyze tab, with the first method (measurement error during a jump) | `Dashboard/explore_analyze.py`, `app/diagnostics/displacement/` (branch explo) | Your work. Test bench, judged case by case by the product owner |
|
||||
| Match error per target and frame, with per-target threshold | datapoint `error`, property `error_threshold` (default 0.7) | Production. 0 = perfect match, 1 = target lost |
|
||||
| Per-reference status code | datapoint `inlier`: 1 in fit, 0 out of fit, -1 rejected (error above threshold), -2 interpolated | Production. In the aggregates the column names are swapped: `inlier_no_redundancy` counts -1 and `inlier_rejected` counts -2 |
|
||||
| Camera movement | sensor `camera_movement`: pan, tilt, rotation, scale, sigma0 (degrees) | Production |
|
||||
| Image quality per target: peak, flux, sharpness, fwhm, dominance, snr | `app/aggregates.py` columns | Empty for most devices today; sub-project B fills them |
|
||||
| Hiding degraded data | `Device.sigma0_threshold` | Production, off when empty. Used by Explore and exports, not by alarms |
|
||||
| Alarms and notifications | `app/tasks/recuring_tasks.py` (`check_alarms`, `generate_alarm_report`), `app/base/notifications.py` | Production. E-mail, SMS (per group, opt-in) and web notifications, with templates in `alarms/` |
|
||||
| Legacy obstruction alarm | `Dashboard/processing.py` `obstruction_index`, access flag "Obstruction Alarm" | Remnant, status unclear. Check before reusing the name |
|
||||
|
||||
One data gap matters for the Analyze tab: on aggregate-only devices `pattern_type` is empty, so targets and references cannot be told apart. Report it to the F thread rather than working around it.
|
||||
|
||||
## How the explo work fits
|
||||
|
||||
The explo work is well aligned: it already follows the right principles (rules without database access, a colour per day, nothing shown when the data does not allow a conclusion, readings that say "consistent with"). What is missing is the measurement side and the link to who has to act. This is a first reading from the code and docs on origin/explo, not a full review.
|
||||
|
||||
| Part | Fits the goal | Adjust |
|
||||
|---|---|---|
|
||||
| Domain framework (`DOMAINS`, `day_color`, `STATUS_BADGE`, hourly `compute_statuses`) | Yes. This is the backbone of G | Add measurement domains to it (milestone 1) rather than building a second framework |
|
||||
| Battery, storage, cellular, temperature | Yes. These are instrument health: AIMsight's side | Add the responsibility label. Battery and power can be the client's side (solar panel, mains) |
|
||||
| Offline stations | Yes | Distinguish "no images" from "no metrics": a station can send metrics but no images (camera or schedule fault) |
|
||||
| Home page "Status" list, customer's own stations | Yes. Client-facing, which is the point | Each line should say what the client can do |
|
||||
| Analyze tab, measurement error method | Yes. It is the start of the event explainer | Add methods that use the reference status codes and camera movement (milestone 3). Use "target" for tracked objects in readings, not "sensor" |
|
||||
| Displacement views (View, Diagnosis, Displacements) | Partly. Useful for AIMsight staff and for testing methods | Decide with the product owner which parts the client sees |
|
||||
| UI text in English only, written in the code | Not yet | Client-facing text must go through the translations (French, German, Spanish, Italian) |
|
||||
| Local app on production database | Risky | Test writing features (notifications) on staging.aimsight.ch, never from the local app |
|
||||
|
||||
## Next milestones
|
||||
|
||||
The next step is to add measurement domains to the framework you already built, using data that exists today. Each milestone is shown to the product owner before the next one starts.
|
||||
|
||||
1. **Measurement domains, read-only.** Add to `DOMAINS`, with the same day-colour rules:
|
||||
- Images: measurements received against the schedule (missing images while metrics still arrive).
|
||||
- Target visibility: share of frames above `error_threshold` per target per day; later replaced by B's visibility status.
|
||||
- References: references observed against references configured, from the `inlier` codes; flag days running on 2 or 1 reference.
|
||||
- Camera stability: pan and tilt change per day against the site's usual range.
|
||||
2. **Responsibility label.** Each status line and each Analyze reading gets one of: instrument, installation, environment, unknown. The wording comes from sub-project A; until then, use provisional text and mark it.
|
||||
3. **More Analyze methods.** Reference change during a jump (`inlier` codes switching), camera movement during a jump, all targets up together (environment) against one target (installation). Same function shape as `event_error.py`, each with an offline test.
|
||||
4. **Client notifications.** A daily or on-change message to the site's contact, through the existing e-mail, SMS and web channels. Start with: station offline, images missing, a target not visible for more than N hours, a reference lost. Rate-limit: one message per cause per site until it is resolved. Test on staging.aimsight.ch.
|
||||
5. **Consume B and F when they land.** Replace your provisional visibility and reference rules with their states, so the same quality decision drives the health page, exports and alarms.
|
||||
|
||||
## Rules to follow
|
||||
|
||||
These rules apply across the whole project and come from the product owner.
|
||||
|
||||
- **Legacy devices keep working.** Many stations run old firmware and keep pushing old data. Everything in G must work from what the cloud already receives; never require a firmware update. A domain whose data is missing on a station shows nothing, as your framework already does.
|
||||
- **Glossary.** "Target" is the tracked object (not marker, not sensor in client text). "Point" is only a surveyed location with coordinates. "Reference" is a target used to correct camera movement. Glossary: AIMsight glossary. Code identifiers stay as they are.
|
||||
- **Translations.** Client-facing text goes through the UI translations (French first, then German, Spanish, Italian). Keep sentences short and complete so they translate well.
|
||||
- **Never claim a cause.** A reading says "consistent with". The system shows evidence; the client or AIMsight staff decides.
|
||||
- **Production safety.** Never start beat or the root `docker-compose.yml` locally (alarms send real e-mails and SMS). Anything that sends messages is tested on staging.aimsight.ch. Clients are warned before a change in what they receive.
|
||||
- **Thresholds are provisional until reviewed on real cases.** Say so in the rule text, as you already do.
|
||||
|
||||
## Self-check of your work so far
|
||||
|
||||
Go through each item for your current branch and add a short note where the answer is no or partly. The product owner will read this before your next review.
|
||||
|
||||
- [ ] Every status line shown to a client says what happened, since when, and what the client can do.
|
||||
- [ ] Every status or reading can be labelled instrument, installation, environment or unknown.
|
||||
- [ ] Nothing is shown when the data does not allow a conclusion (no false alarm from missing data).
|
||||
- [ ] Stations on old firmware or with missing metrics do not break a page or a task.
|
||||
- [ ] Readings say "consistent with" and list the facts behind them.
|
||||
- [ ] Client-facing words follow the glossary (target, reference, point).
|
||||
- [ ] Client-facing text can be translated (no sentences built from fragments in code).
|
||||
- [ ] Rules have no database access and have an offline test with a real station's data.
|
||||
- [ ] Nothing was written to the production database or sent to a client during development.
|
||||
- [ ] The domain framework can take a measurement domain (images, visibility, references, camera) without a redesign.
|
||||
- [ ] The work does not duplicate what B (target visibility) or F (data filtering) will provide; where it overlaps, the code is easy to switch to their output.
|
||||
|
||||
## Open questions for the product owner
|
||||
|
||||
- Who receives notifications: the client's contact only, or AIMsight support too? Sending only to the client is what shifts responsibility.
|
||||
- Which Explore tabs (View, Diagnosis, Displacements, Analyze) should clients see, and which stay for AIMsight staff?
|
||||
- Is the old "Obstruction Alarm" still used by any client, or can G replace it?
|
||||
- When the explo work should be reviewed and merged, and onto which branch (`new_db` or `main`).
|
||||
|
||||
---
|
||||
|
||||
## Écarts constatés (Support-Agent, 2026-10-26)
|
||||
|
||||
Relevé de l'alignement de ce dépôt (prototype) sur les instructions ci-dessus. Rien n'est tranché ici : chaque écart attend l'arbitrage de l'utilisateur.
|
||||
|
||||
**Alignés**
|
||||
- Pas d'accès base dans les règles, une couleur par jour, rien d'affiché si la donnée manque, seuils dits provisoires, lecture seule (pompage), anciens firmwares (D-029 à D-043).
|
||||
- Domaines système Energy, Storage, Cellular, Temperature : c'est la première moitié de G.
|
||||
|
||||
**Écarts**
|
||||
1. **Cause jamais affirmée** : le handoff impose « consistent with ». Le journal du matin (D-056) vise l'inverse, des phrases catégoriques voulues par l'utilisateur (`vues-deplacements/contexte/journal-du-matin.md:67`). Contradiction à arbitrer ; les règles épistémiques de `CLAUDE.md` vont dans le sens du handoff.
|
||||
2. **`inlier`** : le handoff bâtit les domaines « References » et la méthode d'Analyze sur les codes `inlier` (jalons 1 et 3). `CLAUDE.md` interdit de rien construire sur `inlier` binaire (RANSAC sera remplacé par des poids continus) ; D-056 écarte aussi de partir des `inlier` ou de `sigma0`. À rapprocher : les codes sont à 4 valeurs, pas binaires, mais l'interdit vise l'estimateur futur.
|
||||
3. **Étiquette de responsabilité** (instrument / installation / environment / unknown) : absente des domaines, du journal (onze catégories de `categories.py`) et des notifications.
|
||||
4. **Domaines de mesure** (images à l'heure, visibilité des cibles, références, stabilité de la caméra) : absents du cadre de domaines ; le journal détecte la visibilité, les sauts et les trous, mais hors de ce cadre.
|
||||
5. **Offline** : pas de domaine « station hors ligne » ici, ni la distinction « pas d'images » / « pas de métriques ».
|
||||
6. **Destinataires** : nos notifications vont au support (D-025, D-039), la vue client est un lien ; le handoff veut le contact du client, e-mail / SMS / web. Question ouverte du handoff, à trancher.
|
||||
7. **Langue et traductions** : nos textes site sont en anglais seulement (D-023) ; le handoff demande le passage par les traductions FR / DE / ES / IT, phrases courtes et complètes, non construites par fragments.
|
||||
8. **Lexique** : « target », « reference », « point » : à vérifier dans les textes client (aucun « sensor » ni « marker » trouvé dans `maquettes/user` ni les guides).
|
||||
9. **Quoi dit au client** : chaque ligne doit dire quoi, depuis quand, quoi faire ; nos phrases de la vue client disent le quoi, rarement le « quoi faire ».
|
||||
10. **Terrain de livraison** : le handoff vise `monitoring-dashboard` (branches `explo`, `new_db`) et staging.aimsight.ch ; ce dépôt reste un prototype dont le portage est un point du plan du journal du matin.
|
||||
Reference in new issue
Block a user