Files
lmxopcua/docs/ui-consistency/evidence/ot13-csv-import/verification.md
T
2026-11-13 23:54:11 -05:00

56 lines
10 KiB
Markdown

# OT13 staged CSV import checkpoint
Owned production scope is exactly `Components/Shared/Raw/RawCsvImportModal.razor`. New RawCsvImportModalAccessibilityTests, the loopback synthetic canary/browser harness and this evidence are owned by this slice. No callers, RawTree, shared ModalFrame/JS/CSS, parser, service, model/schema, endpoint, authorization policy or package pins were changed.
## Behavior and preserved contracts
The wrapper now uses the accepted shared ModalFrame, an explicitly named CSV input with associated instructions, safe Cancel entry and a named locally scrollable review table. Existing per-row verdict, typed/fallback/override provenance and row-removal semantics remain; removal controls name their file row and tag. Virtualize still receives the precomputed `_view.VisibleRows`, uses tr spacers and its original 34px initial size. No loop over all parsed rows was introduced.
All original public parameters remain; only optional nonconfidential Target is additive. The default identity includes DeviceId, TagGroupId and DriverType, so direct A→B replacement resets the review and retires old reads and child callbacks. Unrelated rerenders retain the current staged result and removals. Group-path resolution preserves original device-id precedence and original unknown-group fallback. A read exception now reports target unavailability, blocks upload until Retry succeeds and never silently parses under an unresolved prefix. This is a read-only retry of the same existing group reader, not a new endpoint.
The actual InputFile, 16 MiB stream limit, StreamReader, RawTagCsvMapper, per-driver column maps, RawCsvReviewView and all-or-nothing ImportTagsAsync are retained. Selecting a file stages data only. Invalid remaining rows or an empty result still block committing. Reset returns to the named upload, and only removing invalid rows can make the remaining valid review eligible. Unknown JSON, data types and target group prefixes are preserved. Source hashes and retained-contract checks are in `source-guard.json`.
Uploads capture presentation, driver type and group prefix before awaiting the file read. A retired InputFile callback cannot begin another read, and old upload success/failure/finally cannot replace B's review or clear B's busy state. Read-only target resolution and parsing remain dismissible; their late results are discarded after close/replacement/disposal.
Commit snapshots the originating device, immutable import records/array and the rendered save/close callbacks before the service await. Duplicate entry, Reset, removal and close are guarded while a mutation is pending; the native body/close actions are disabled. A dispatched import is not cancelled or replayed. Current failure retains staged rows and allows an explicit retry; no automatic retry is added.
The existing explicit committed-write refresh contract is preserved: successful dispatched A still invokes its **captured A OnSaved** after external close/replacement, even if B is now displayed. It never reads B's live OnSaved, installs an A error into B or closes B. All UI callbacks are suppressed after disposal. The parent RawTree caller owns its own generation checks inside an already-dispatched refresh; wrapper guards cannot retroactively guard the inner await of an external callback. Parent/primary coordinated that separate caller gate. Existing ModalStaleOpenGuardTests' committed-after-close assertion remains unchanged and passes.
## Managed verification
Final aggregate: **70 passed, zero failed/skipped** in `contracts-final.trx` / `contracts-final.log`. This includes **14 new cases** plus existing RawCsvRenderingTests, ModalStaleOpenGuardTests, RawTagCsvRoundTripTests, CsvColumnMapReflectionTests, CsvMergeEvidenceTests and UnsTreeServiceImportTests. Existing parser, virtualized source, serialization, merge, all-or-nothing and legacy committed-refresh assertions remain unchanged.
The new tests cover visible names/instructions; repeated commit and competing Reset/Cancel; captured A success/failure/exception versus B; disposal without cancellation/callbacks; retired upload success/failure and retained InputFile callback entry; invalid-row commit rejection/reset; pending-upload single-flight and close; direct-retarget group success/failure; group-read retry/prefix; and actual oversize upload rejection/recovery. Group-retarget tests await the actual first OnParametersSetAsync completion through a test-only derived component, so they cannot pass before the stale continuation runs. Actual InputFile uploads use the existing bUnit helper; retained OnChange EventCallbacks exercise retired child work. Pending button/reset events are forced through current rendered handlers to prove server guards despite native disabling, not claimed as retained DOM event IDs.
Before production edits, `red.trx` recorded **eight meaningful failures, zero passes**. Original naming, duplicate mutation, stale upload, replacement and disposal defects are retained. Additional group/limit cases are positive behavioral contracts. No assertions, skips, policy checks or package audits were weakened.
Every test invocation used the mandatory private owned-loopback SQL runner, including discovery. No private state/credential file was read or copied. Tests use synthetic proxy results and EF InMemory group context; no SQL or production service mutation is claimed. Isolated artifacts are repository-anchored under `artifacts/ot13-csv-import`, preserving existing source-ancestry guards and other workers' outputs.
Final command from the OtOpcUa repository root:
```sh
python3 infra/tools/ui-consistency/with_private_sql.py --state "$OT_PRIVATE_SQL_STATE" -- dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj -c Debug --artifacts-path artifacts/ot13-csv-import --filter 'FullyQualifiedName~RawCsvImportModalAccessibilityTests|FullyQualifiedName~RawCsvRenderingTests|FullyQualifiedName~ModalStaleOpenGuardTests|FullyQualifiedName~RawTagCsvRoundTripTests|FullyQualifiedName~CsvColumnMapReflectionTests|FullyQualifiedName~CsvMergeEvidenceTests|FullyQualifiedName~UnsTreeServiceImportTests' --logger 'trx;LogFileName=contracts-final.trx' --results-directory docs/ui-consistency/evidence/ot13-csv-import
```
## Actual browser verification
`browser-confirmation.json` records **12/12 scenes and 336 passing assertions** at 1440px, 390px and actual browser 200% (720px layout viewport/DPR2). Each width runs invalid/failure/recovery, 127-row virtualized success, replacement with late A failure and replacement with late A success.
Checks include resolved modal name and safe initial Cancel focus, linked upload instructions, outside focus denial, 12 native Tab steps, invalid rows blocking import, named row removal, local review region, fewer rendered rows than the full 127-row file, full immutable payload/unknown JSON/group prefix, actual double-click single dispatch, native busy body/close/Escape guards, visible footer, current failure with no replay, explicit successful retry, A-only saved callback with B retained, original trigger focus return, no document overflow, no page errors, no external HTTP and no forbidden service calls. Desktop review, phone scrolled review and real200 busy captures were visually inspected. On a narrow screen the review table intentionally scrolls locally to expose all technical columns; row labels remain available.
The canary is actual source-linked ModalFrame/RawCsvImportModal/InputFile/parser/Virtualize with real packaged shared CSS/JS. It registers only Razor, an ephemeral data-protection provider, EF InMemory read-only group context and an ImportTagsAsync-only proxy. Its synthetic HTTP retarget/release endpoints only change per-circuit fixture state and fabricate completion. All other service operations refuse. Mandatory loopback/provenance/provider checks run before browser interaction. No driver, gateway, LDAP, real secret, database mutation or production endpoint is reachable from this fixture. Source served CSS/JS parity is recorded, not a whole-package release proof. Final validation origin was `http://127.0.0.1:53065`, OS assigned; the earlier initial fixture used 52900 and was stopped before the final build.
Reproduce while the disposable fixture is running:
```sh
python3 docs/ui-consistency/evidence/ot13-csv-import/browser.py --origin http://127.0.0.1:53065 --output browser-confirmation.json
```
## Retained failures and limits
Initial harness corrections are retained: a duplicate pending request was initially awaited before its fake completion, loose JS returned false for the new ModalFrame activation until the positive activation fixture was supplied, and an old AngleSharp button reference had to be re-queried after rerender. The generic helper's class constraint was corrected for bUnit interface covariance. These are not described as product failures. Two compilation attempts intersected other workers' explicitly incomplete source/test edits; their logs are retained and were rerun after coordination, without editing those workers' files.
The first native matrix passed 10/12 scenes: two large-file cases sampled Virtualize before its first IntersectionObserver rows arrived. The retained screenshot shows initial spacers. The confirmation waits for an actual first row before checking bounded rendering; all 12 scenes pass. No production workaround or virtualization removal was used. Early/intermediate test counts are historical, not final acceptance substitutes.
This is a bounded wrapper checkpoint, not OT13/OT14 whole-task acceptance or production import certification. Live SQL all-or-nothing behavior is covered by its existing separate integration gate, not fabricated here. No manual screen-reader or Windows/IIS claim is made. Parent caller identities/inner refresh guards and combined consumer/package proofs remain separate acceptance gates. No publication, push, deployment or schema/data migration occurred. Roll back this scoped source change through normal review if needed; published shared packages stay immutable. The owned disposable canary is stopped after review/evidence capture; no other agent's host or private SQL lifecycle is owned here.