cesnimda
46 lines
8.0 KiB
Markdown
46 lines
8.0 KiB
Markdown
# PRE-P10-UX design and scope
|
||
|
||
27 October 2026. Owner specification: CV-QA Addendum/PRE-P10-UX and appended administrator attribution/failure-diagnostics requirements, supplied in the attachment `03bb825f-4d45-40ea-8574-548831f24611/Pasted text.txt`.
|
||
|
||
The owner explicitly authorises autonomous safe implementation, validation, commits and pushes in the stated sequence. Routine design choices below are engineering decisions under that authorisation, not a claim that the owner separately reviewed this document. No additional design approval loop is required. Production, main merge, live-model activation and original Phase10 cleanup remain excluded.
|
||
|
||
## Verified entry
|
||
|
||
The completed CV-QA baseline is `4a8c907d70cbed235728f7d690b5409e72b93abe`, with remote equality verified. Its conditional acceptance permits development/QA; extraction, human/device/print and production qualifications remain limited. It contains `ef425c2` and CV-UX `4a0af62`. An attached managed worktree isolates unrelated local Docker/tooling/security work. Corrective branch: `codex/cv-builder-blank-undo`.
|
||
|
||
## A: blank creation and interactive history
|
||
|
||
Root causes found in source: `sections=[]` means inherit defaults on both server resolver and editor hydration; contact is always inherited; document AI/application matching also treat absent rows as visible. Undo mutates history inside React state updater callbacks, contains settings but not the document name, and has no document-level keyboard handling. Runtime reproduction and failing tests must precede fixes.
|
||
|
||
Use nullable settings-JSON flags `sectionsExplicit` and `includeProfileContact`. Missing flags retain legacy behavior and serialization/no-op compatibility. Blank explicitly selects zero sections and suppresses inherited contact/header/photo. Manual custom sections remain CV-specific content; adding existing Career Profile content is a deliberate action. From Career Profile exposes actual available-section/contact choices. A template changes presentation; duplicate preserves content and flags. Every resolver/context consumer must use the same inclusion semantics. Empty resolved content receives clear export validation before PDF allocation; no fictional placeholders are inserted.
|
||
|
||
Alternatives rejected: changing the meaning of every existing empty list would rewrite old CVs; hiding seeded defaults only in the UI would leave render/AI/matching leaks. A new master-profile or revision store is unnecessary.
|
||
|
||
Interactive undo/redo uses immutable document snapshots, pure state updates and bounded session-only stacks. Text editing groups by focus/edit burst; structural/design actions are individual transactions. New edits discard redo. Autosave uses the existing queue and expected server revision; success is acknowledged only after durable save. Conflict reload/restore/new-document hydration deliberately resets session history, while ordinary saves preserve it. Native input/contenteditable undo remains native; document shortcuts operate outside editable controls. History cannot cross document IDs, and delayed saves/previews must not rehydrate another document.
|
||
|
||
## B: versioned template quality and optional photographs
|
||
|
||
Keep all nine existing IDs for compatibility; this is the justified alternative to a numerical6–8 target. The catalogue already spans the requested layout families. Improve actual distinctness/spacing rather than add near-duplicates. Audit short/medium/long/dense equivalents across all nine, render PDF page images and inspect them.
|
||
|
||
Known source defects/limits: sidebar CSS ignores configured sidebar palette; Technical's usable identity width is30mm after padding, causing aggressive word wrapping; conservative section keep-together rules can produce sparse pages. Measure before changing shared pagination. Introduce an opt-in design revision if new styling would alter legacy lens renders; missing revision stays legacy. New creation/explicit template Apply may opt into revised styling. Duplicate/restore retain the chosen revision; frozen stored HTML/bytes remain untouched. Reuse licensed embedded fonts and existing photo upload/storage/crop pipeline; add accessible crop alternatives and explicit CV entry points where needed. No generated portraits or second image store.
|
||
|
||
## C: interactive dashboard
|
||
|
||
Replace form-heavy arrangement with an edit mode on the actual widgets: drag handles, resizing, accessible visibility/catalogue controls, save/discard/reset, keyboard movement/resizing and status announcements. Keep widget data/actions and the existing preference hook/owner/revision contract. Assess the current official React-Grid-Layout API/licence/React compatibility/bundle cost before selecting it; avoid reimplementing a collision engine without evidence.
|
||
|
||
Schema v2 stays in existing preference JSON/revision columns. Deterministic migration preserves v1 stored order, size and visibility; no automatic reset or write on viewport change. Persist bounded geometry with responsive behavior and per-widget minima; retain hidden geometry and future-widget rules. Old-schema clients cannot overwrite newer stored layout data. Phone/touch interactions preserve scrolling and functional widget controls; drag is never the only authoring method. No dashboard SQL migration is needed.
|
||
|
||
## D: administrator processing monitor
|
||
|
||
Reuse real `UserOperation`, queue/leases, CV runs and actual task-specific job-subject decoding. Current rows provide latest state, not historical transitions. Add a bounded owned operation-event table with monotonic cursor, UTC time, attempt and allowlisted event/status/stage/error codes. Append only successful transitions atomically; do not save unrelated tracked entities or log every heartbeat. Do not invent history for old rows. Include additive migration, retention, account erasure/export and actual MariaDB tests.
|
||
|
||
Dedicated server-admin-authorised list/detail/event APIs project safe metadata. Existing admin audit permits cross-owner identity/job metadata; ordinary APIs remain owner-scoped. Every association is checked against the operation owner. Display original user ID plus current permitted name/email; CV imports show no linked application, safe retained file metadata and known page count only. Deleted/mismatched relationships remain unavailable. No existing user-detail route is assumed.
|
||
|
||
Use bounded cursor polling with pause/resume/reconnect, filters, pagination and finite retention; SSE is optional, not required infrastructure. No raw document/prompt/completion/request/exception/stack/connection/lease data enters events or responses. Sanitisation occurs before storage/transmission. Unknown failures remain unknown. Operation GUID is the correlation key; propagate safe correlation across actual worker/backend/sidecar boundaries. Read-only monitoring avoids new privileged cancellation/retry paths unless separately proven safe. Audit any sensitive administrative action through existing owners. Disabled/disconnected model assistance is shown honestly; no live inference is started.
|
||
|
||
## Publication, preservation and acceptance
|
||
|
||
After validated A, create `feature/cv-template-library-review` from accepted A; then `feature/dashboard-interactive-grid` from accepted B; then `feature/admin-processing-monitor` from accepted C. Consolidate on `test/pre-phase10-ux-acceptance` from accepted D. No disconnected branch omits earlier work. Each checkpoint has focused RED/GREEN evidence, review, documentation, commit/push and remote check. Final regression serialises native build/browser/provider lanes and retains independent counts/source/runtime identities.
|
||
|
||
Preserve all57 capability groups/33 routes, canonical Career Profile, overrides, document/history/letter/application revisions, ownership/authentication, v1 dashboard data and licensed physical rendering. Keep old evidence/goldens; if intentional new design output differs, use separate versioned specimens rather than conceal regressions. Human/device/native-language/print/live-model/deployed acceptance is only recorded when actually performed. Final independent verdicts cover all requested areas, with owner actions and Phase10-vs-production scopes. Stop after the new Phase10 handoff; do not start cleanup.
|