docs(docs): V1-2.6 annotations-findings complement, boards 17-22, study
Owner brief: bidirectional navigation between annotations and findings. Relations audit (one finding_zone_id link, no new association), six boards from the equine draft data, placement U2b, risks, tests, owner decisions F1-F16. Design only; U1 plan untouched.
This commit is contained in:
1 parent
2e46c14697
commit
212126c6ce
15 files changed
+1002
No files matched your search
@@ -0,0 +1,196 @@
|
||||
# V1-2.6 UX complement: navigation between annotations and findings
|
||||
|
||||
Status: PROPOSAL for the owner, 2026-11-06 (brief « Nouvelle exigence UX : navigation bidirectionnelle entre
|
||||
annotations et constats »). Design only: no application, Rust, SQL or worker change; nothing here authorises code.
|
||||
The U1 plan (`.claude/tasks/plans/2026-11-06-v1-2-6-ux-u1.md`, commit 2e46c14) is unchanged by this track.
|
||||
Contract: `.claude/tasks/contracts/2026-11-06-v1-2-6-findings-nav-design.md`. Boards:
|
||||
`docs/design/v1-2-6-constats/` (17 to 22, after the 16 validated v1-2-6 boards).
|
||||
|
||||
Paths: `core/` stands for `crates/core/src/`, `app/` for `apps/app/src/`.
|
||||
|
||||
## 1. Audit of the existing relations (request C)
|
||||
|
||||
### 1.1 Links and who holds them
|
||||
|
||||
| Link | Held by | Cardinality | Core rule |
|
||||
|---|---|---|---|
|
||||
| annotation → view | `view_id` on every annotation (`core/domain/sheet/schema.rs:421`, `:447`) | many to one | error `annotation.view.missing` (`validate.rs:266-280`) |
|
||||
| detail view → parent view | `parent_view_id` (`schema.rs:270-271`) | many to one | errors `view.parent.missing`, `view.parent.cycle`, `view.unreachable` (`validate.rs:146-223`) |
|
||||
| detail trigger → view it opens | `opens_view_id` (`schema.rs:460-461`) | many to one: a trigger opens exactly one view, a detail view is opened by 1 to N triggers | error `annotation.opens_view.invalid` (`validate.rs:298-328`, the target is a direct child of the trigger's view); `view.unreachable` asks for at least one trigger per detail view (`validate.rs:200-223`); no uniqueness rule; a trigger has no finding zone and no region by type (`schema.rs:439-462`) |
|
||||
| annotation → annotation category | `category_id` (`schema.rs:423`, `:449`) | many to one | error `annotation.category.missing` (`validate.rs:282-296`); the category has no link to findings |
|
||||
| observable annotation → finding zone | `finding_zone_id: Option` (`schema.rs:432-433`) | an annotation names 0 or 1 zone; a zone is named by 0 to N annotations | error `annotation.finding_zone.missing` when it dangles (`validate.rs:330-346`); warning `annotation.no_findings` when null (`:367-386`); warning `finding_zone.unreferenced` when no annotation names a zone (`:437-457`); no uniqueness rule, and `docs/development/ANATOMICAL_SHEET_MODEL.md:102-103` says several annotations may share a zone |
|
||||
| observable annotation → vertebral region | `vertebral_region_code` (`schema.rs:434-435`) | many to one | error `annotation.region.missing` (`validate.rs:348-365`); a region has no link to findings, it opens the practitioner's vertebra picker (`core/domain/editor/zone.rs:101-103`) |
|
||||
| finding zone → families → findings | `categories` (`schema.rs:592`), `FindingCategory` with `kind` (`:568-583`), recursive `FindingNode` (`:538-556`) | tree, depth ≤ 8 (`edit.rs:397-420`) | ids unique among siblings (`finding.id.duplicate`, `validate.rs:410-435`); a finding is addressed by (zone, path) (`keys.rs:42-46`) |
|
||||
| family kind | `FindingCategoryKind = dysfunction / consultation_reason / anamnesis / custom` (`schema.rs:558-566`) | on the category, never on nodes | no rule per zone (no « one of each ») |
|
||||
| findings → references | `reference_ids` on categories and nodes (`schema.rs:578-579`, `:550-551`) | many to many | error `finding.reference.missing` (`validate.rs:466-499`) |
|
||||
| laterality | annotation only (`unpaired / bilateral / left / right`, `schema.rs:393-402`) | none on zones or findings | the side exists only in reports, for bilateral annotations (`zone.rs:104-112`) |
|
||||
|
||||
There is no reverse link (zone → annotations) in the document, in the core index (`core/domain/sheet/index.rs:25-33`,
|
||||
`index_data.rs:19-45`, `preview.rs:330-342`) or in the editor. The only core computation that returns the annotations
|
||||
of a zone is `sheet.dependents` (`edit.rs:894-977`, relation `links_zone`), a free op over the whole document text,
|
||||
used for delete confirmations. BDR-031 already rejected an `annotation_finding_map` array.
|
||||
|
||||
### 1.2 Equine draft data (`supabase/seed/anatomical-sheets/equine/draft/document.json`)
|
||||
|
||||
- 2 views (main, head detail), 28 annotations (22 points, 5 zones, 1 detail trigger), 27 finding zones, 811 families
|
||||
and findings (81 families, 730 findings, every zone with exactly one family of each of the three kinds, no custom
|
||||
family), depth 3, 48 references.
|
||||
- Every finding zone is named by exactly one annotation; no observable annotation lacks a zone; zone ids equal
|
||||
annotation ids; no left/right pair, no main + detail duplicate, no point + polygon on one zone. The duplicate cases
|
||||
of the request do not exist in this sheet; they exist only in synthetic core fixtures (`crates/core/tests/oracles/r3/highlight.json`, hip ×5;
|
||||
`crates/core/tests/conformance/annotation-id-duplicate.json`, atm ×2).
|
||||
- Labels repeat: 283 distinct French labels over 811 elements; the family name « Anamnèse / facteurs rapportés » is shared by all 27 zones, with three distinct subtrees (8 cranial zones, 9 spinal zones, 10 limb and pelvic zones), and
|
||||
« Restriction en flexion » appears 15 times. A search result without its zone would be ambiguous.
|
||||
- Grasset: annotation `stifle` (point, main view, bilateral) names zone `stifle`: 3 families, 29 findings (16, 7, 6),
|
||||
3 with a veterinary referral flag, one reference cited.
|
||||
|
||||
### 1.3 What the editor and the core already offer
|
||||
|
||||
- Editor: one `selectedId` on the canvas (`app/editor/annotations/uiState.ts:14-67`), one marked annotation
|
||||
(`useCanvasBuild.ts:70-83`); « Zone de constats » select in the annotation properties (`AnnotationFields.tsx:162-187`)
|
||||
and at creation (`CreationFields.tsx:141-161`); the Constats tab as an ARIA tree over `buildItems`
|
||||
(`app/editor/findings/tree.ts:161-196`), creation of zones, families and findings (`FindingCreateForm.tsx`); no search,
|
||||
no filter, no link between the two tabs; the Annotations tab cannot create a finding zone.
|
||||
- Read-only precedents: the catalogue's `ZonePanel` (`app/components/catalogue/ZonePanel.tsx:62-133`) shows the
|
||||
findings of the selected annotation's zone by family; the report editor de-duplicates by zone and side
|
||||
(`app/components/observation/ObservationCard.tsx:78-93`) and marks several annotations at once
|
||||
(`app/components/canvas/AnatomyCanvas.tsx:79-85`).
|
||||
- Core: no search op, no reverse map; the composed canvas tags every annotation with `data-anno-zone`
|
||||
(`core/anatomy/layer.rs:176-208`, contract `docs/ANNOTATION-RENDERING.md:50-66`).
|
||||
|
||||
### 1.4 Conclusion of the audit
|
||||
|
||||
The request needs no new association: an annotation already names its finding zone, the findings belong to the zone,
|
||||
and « the findings of an annotation » are the findings of that zone. « Gérer l'association anatomique » is the existing
|
||||
`finding_zone_id` field. Duplicates are handled by grouping on the zone id: findings are listed and counted once per
|
||||
zone, whatever the number of annotations naming it. No document structure change is proposed.
|
||||
|
||||
## 2. Design (boards 17 to 22)
|
||||
|
||||
| Board | Content |
|
||||
|---|---|
|
||||
| 17 | Annotations tab, an annotation selected: the side column gains a « Constats · n » segment beside « Propriétés »: the zone (with « Changer » and the other annotations that show it), the families of the zone in document order with their counts, « Ajouter un constat », « Ouvrir dans Constats » |
|
||||
| 18 | From the selection: A, add a finding in the zone (family, parent, FR/EN names; « Ajouter » / « Abandonner »); B, edit a finding with the same fields and component as the Constats tab detail (C9) |
|
||||
| 19 | Association: A, change the finding zone (searchable list, current zone first, « n annotations » per zone, the rule « no finding moves »); B, an annotation without zone (link to an existing zone, or create one for it); C, a detail trigger has no findings (segment disabled with its reason); D, a zone shown by two annotations (illustrative, absent from the equine draft) |
|
||||
| 20 | Constats tab: instant search, result count over the total, « Filtrer sur le schéma », « Réinitialiser les filtres »; results shown in their tree (zone, family, ancestors in grey); each zone row links to the drawing (« Sur le schéma ») |
|
||||
| 21 | « Filtrer sur le schéma »: non-modal right panel; views chosen as chips (one or more); click on points or zones to add or remove them; selection chips; the tree on the left updates at each click and combines with the text |
|
||||
| 22 | States: no result (with the count outside the drawing filter and « Retirer le filtre du schéma »); keyboard list of the annotations with checkboxes; read-only (rights, frozen, historical); below 1 024 px, consultation with the list only |
|
||||
|
||||
Bidirectional path: drawing → « Ouvrir dans Constats » (focus request on the zone or finding key); Constats →
|
||||
« Sur le schéma » (focus request on the annotation key, Constats segment open). Filters are interface state: kept while
|
||||
the page lives (U1 keeps the Constats tab mounted), never written to the document, never saved, never arming the leave
|
||||
guard.
|
||||
|
||||
## 3. U1 integration points (work item 1)
|
||||
|
||||
No integration point has to be added to U1, and no amendment of the U1 plan is proposed. The seams the feature needs
|
||||
are already in the plan:
|
||||
|
||||
- `navigate(target)` with `zone`, `finding` and `annotation` keys (`targetOfKey`, U1 plan §1) gives both directions of
|
||||
the jump; `PropertiesPanel` receives `navigate` from Lot B1 (its unmeasured-view link is retargeted there).
|
||||
- The Constats tab stays mounted (U1 plan §2), so search and drawing filters survive tab changes without any store.
|
||||
- `usePlaceVisible()` and the « one composed copy of a view » rule (U1 plan §2) cover the filter panel's drawing: it
|
||||
detaches while its place is hidden, and the Annotations drawing is hidden while Constats is shown.
|
||||
- `folded` exported in Lot C (case- and accent-insensitive match) serves the findings search.
|
||||
- The secondary panel slot of the references panel (U1 plan §5) is where the filter panel goes; the reducer gains a
|
||||
second panel kind when this feature lands, a local change (owner precision 10: no global navigation rebuilt). Watch
|
||||
item for the U2b executors: the filter panel is a variant, not a copy: no scrim and no `inert` on the tab panels
|
||||
(F5: the tree stays live), unlike the references panel.
|
||||
|
||||
One watch item for the U1 executors, with no plan change: keep the Constats tab's selection, expansion and future
|
||||
filter state local to the kept-mounted `FindingsTab` (as the plan already does), not in the navigation reducer.
|
||||
|
||||
## 4. Placement (work item 2)
|
||||
|
||||
Recommended: a dedicated sub-step **U2b · Annotations et constats**, after U2 and before U3, on its own owner
|
||||
authorisation.
|
||||
|
||||
- Why after U2: U2 rewrites the selection, pointer and keyboard model of the same canvas and the same
|
||||
`PropertiesPanel`; the Constats segment sits in that panel and the drawing filter reuses the pointer rules
|
||||
(§2 G of the UX plan: a second pointer cancels, arrows pan only on the canvas box).
|
||||
- Why before U3-U6: none of them changes the zone link or the findings tree; U3 and U6 touch `AnnotationFields`
|
||||
(colour, roles, region picker), not the zone field nor the Constats tab; U4 and U5 add views, which the view chips
|
||||
list by construction; U6's internal `cat-access` and the detail triggers never carry findings, so they never appear
|
||||
as filter choices.
|
||||
- Alternative: after U6 (less rework risk in `AnnotationFields`, later delivery).
|
||||
- Files: `app/components/editor/annotations/{PropertiesPanel,EditableAnnotations,ConstatsSegment (new),
|
||||
ZoneLink (new)}.tsx`, `app/components/editor/tabs/FindingsTab.tsx`, `app/components/editor/findings/{FindingTree,
|
||||
FindingDetail,FindingContent,FindingCreateForm,FindingsSearch (new),SchemaFilterPanel (new)}.tsx`,
|
||||
`app/editor/findings/{tree,filter (new)}.ts`, `app/editor/annotations/zoneIndex.ts` (new), the canvas marking state,
|
||||
`docs/ANNOTATION-RENDERING.md` (new page state for filter marks, updated first), i18n.
|
||||
- Rust ops: none. Wasm budget: unchanged (margin 7 857 B kept for U2, U5, U6, LRN-118).
|
||||
- Boundary (BDR-043, EVAL-034): the zone → annotations map is a group-by on a field the document already holds, and
|
||||
the search filters what the page displays; neither decides validity, accepts a change or computes a rule. Same kind
|
||||
of read as `citationCounts` (U1) and the catalogue's sheet-name search (`filterCatalog`, BDR-095). Every change made
|
||||
from the new surfaces goes through the existing `sheet.edit` commands (finding insert and update, annotation update),
|
||||
so the core keeps the last word. A core op would be justified only if a measure on a large sheet showed the page-side
|
||||
derivation over the 500 ms budget.
|
||||
- Acceptance (proposal): boards 17-22 built; A and B work with mouse, touch from 1 024 px and keyboard; every finding
|
||||
change undoable as one entry; filters never change the document; read-only modes show no edit control; axe clean.
|
||||
- Owner demo: select the grasset, read its 29 findings, add one, undo it; search « restriction »; filter on grasset and
|
||||
jarret; reset; jump both ways.
|
||||
- Rollback: revert of the sub-step's commits (no data, no schema).
|
||||
|
||||
## 5. Technical risks (work item 4)
|
||||
|
||||
| Risk | Probability | Mitigation |
|
||||
|---|---|---|
|
||||
| Editing findings from annotation A changes them for every annotation naming the zone | medium | the segment names the zone and lists the other annotations (board 17, 19 D); edits go to the zone, never copied |
|
||||
| Changing an annotation's zone changes what practitioners are offered and turns the annotation `to_confirm` (`edit.rs:495-509`) | medium | the change goes through the existing field and its review rule; old reports keep their zone id and path (`core/domain/report/rebase.rs:148-157`, BDR-010) |
|
||||
| Search results ambiguous (repeated labels across 27 zones) | high | results always shown under their zone and family; the count names zones too |
|
||||
| Count unit undefined (zones, families, findings, leaves) | high | decision F2 (recommendation: findings at any depth) |
|
||||
| Multi-annotation marking needs a new page state on the composed canvas | medium | page-side restyle only (BDR-053), `ANNOTATION-RENDERING.md` updated before the code |
|
||||
| A third composition of a view in the page (filter panel) | medium | U1's detach-while-hidden rule; one visible composition per view at a time |
|
||||
| Kept-mounted Constats tab recomputing filters on each commit | low | memoised on the parsed document and the filter state; measured with the U1 commit-to-paint check (500 ms budget) |
|
||||
| Duplicates never exercised by the equine data | high | unit and e2e fixtures with two annotations on one zone (main + detail, left + right), modelled on the core's synthetic fixtures |
|
||||
| Terminology: « zone » is an annotation kind and a finding zone; « catégorie » is an annotation category and a family | high | labels « Zone de constats » and « Famille » proposed (decision F7), kept apart from « Zone » (shape) and « Catégorie » (colour category) |
|
||||
| Creating a zone from an annotation is two changes (zone, link) | medium | one batch commit, all or nothing, one undo entry (decision F8) |
|
||||
| Rework if U2, U3 or U6 change the panel structure afterwards | medium | placement after U2 (section 4) |
|
||||
| Laterality: a left and a right annotation on one zone show the same findings | low | expected (findings carry no side; the report adds it); stated in the segment's help |
|
||||
| Wasm budget | low | no core op (section 4) |
|
||||
|
||||
## 6. Tests (work item 4)
|
||||
|
||||
- Unit: zone index (zone → annotations, annotation → zone, triggers and null zones excluded); findings filter (text in
|
||||
FR and EN, accents and case, zone names, ancestors kept, counts per unit, combination with the drawing filter, empty
|
||||
result, reset); de-duplication with two annotations on one zone (main + detail, left + right); the Constats segment
|
||||
(families in order, counts, add and edit through the existing commands, one undo entry each, change of zone, null
|
||||
zone, detail trigger disabled with its reason, read-only in every read-only mode); « Ouvrir dans Constats » and
|
||||
« Sur le schéma » focus requests (found, kept, none); filters absent from the document text and from the leave
|
||||
guard; filter state kept across tab changes and pruned when an undo removes a filtered zone or annotation.
|
||||
- E2E (sandbox): grasset journey (select, read, add, undo, edit, change zone and back); search with count; drawing
|
||||
filter with mouse and touch at 1 024 and 1 180 px; keyboard-only filter through the list; reset; both jumps; narrow
|
||||
read-only at 375 px (search and list filter, no edit control); no horizontal scroll at 1 024, 1 180, 1 280, 375 px.
|
||||
- Accessibility: axe on the segment, the search, the filter panel open, the narrow mode; count in a polite live region
|
||||
after a typing pause; checkboxes named with annotation and zone; focus after each jump on its target, never `body`.
|
||||
- Regression: C9 (findings detail), C13 (recovery), C14 (history bound), C16 (narrow read-only), the U1 suites; the
|
||||
core suites unchanged (no core change); `pnpm r5:import-equine --check` unchanged.
|
||||
|
||||
## 7. Decisions to take (owner)
|
||||
|
||||
None is decided by this proposal; each has a recommendation (F1 to F16).
|
||||
|
||||
| Id | Question | Recommendation |
|
||||
|---|---|---|
|
||||
| F1 | Sub-step | dedicated U2b after U2 (alternative: after U6) |
|
||||
| F2 | What the counters count | findings at any depth; families and zones are not counted as findings; the result line also names the zones (« 108 constats sur 730, dans 26 zones ») |
|
||||
| F3 | Search scope | finding names in French and English, accents and case ignored; a zone whose name matches shows all its findings; descriptions and references not searched |
|
||||
| F4 | Drawing filter semantics | the chosen views give the drawings to pick on, and all their zones while nothing is picked; once one annotation is picked, only the picked zones count; text and drawing combine with AND; applied at each click, no « Appliquer » |
|
||||
| F5 | Filter panel | non-modal right panel without scrim (the tree stays live); one secondary panel at a time (opening « Références » closes it, the filter stays active as a chip) |
|
||||
| F6 | Below 1 024 px | consultation: search and filter available, zones chosen in a list (44 px targets), no selection on the drawing |
|
||||
| F7 | Labels | « Accès : <vue> » as the name shown for a detail trigger (it has no name in the document), « Constats » for the segment, « Zone de constats » for the link, « Famille » for a finding category (today the Constats tab says « Catégorie », to align at the label review), « Filtrer sur le schéma », « Réinitialiser les filtres » |
|
||||
| F8 | Creating a zone from an annotation without one | allowed, one batch (zone with the annotation's name, editable, then the link), one undo entry |
|
||||
| F9 | Editing a finding from the drawing | in the side column, with the shared detail component; « Ouvrir dans Constats » for the tree context |
|
||||
| F10 | Filter lifetime | kept while the page lives (tab changes included), cleared by « Réinitialiser les filtres » and on reload; a filtered zone or annotation removed by an undo leaves the filter silently narrower with its chip updated |
|
||||
| F11 | « Sur le schéma » from a zone named by several annotations | selects the first in document order and lists the others in the segment |
|
||||
| F12 | Multi-annotation marking in the filter panel | accent outline and check disc (board 21), a new page state recorded in `docs/ANNOTATION-RENDERING.md` before any code |
|
||||
| F13 | Finding detail while the filter panel is open | hidden, the tree takes the width; it comes back when the panel closes (board 21) |
|
||||
| F14 | Grouping of the keyboard list of annotations | by annotation category (colour), as the drawing shows them, with a caption saying so; not by finding family (board 22 B) |
|
||||
| F15 | Choosing a zone already shown by another annotation | allowed, with a notice naming the other annotation before the change is applied (board 19 A) |
|
||||
| F16 | « Constats » segment of a detail trigger | shown disabled with its reason rather than hidden, so the panel keeps the same layout (board 19 C) |
|
||||
|
||||
## 8. Out of scope
|
||||
|
||||
Findings attached to several zones, moving findings between zones, drag and drop in the tree, bulk import (all level 2,
|
||||
contract §8.3 and §16.12); practitioner-side search (V1-3 reports); the catalogue (BDR-095 keeps its search to sheet
|
||||
names); any core op, schema change or V1-2.7 control.
|
||||
Reference in new issue
Block a user