96 lines
4.7 KiB
Markdown
96 lines
4.7 KiB
Markdown
# UX Reference: Clean Release Compliance Subsystem Redesign
|
||
|
||
**Feature Branch**: `025-clean-release-compliance`
|
||
**Created**: 2026-03-09
|
||
**Status**: Draft
|
||
|
||
## 1. User Persona & Context
|
||
|
||
- **Who is the user?**: Release manager, compliance operator, enterprise support engineer.
|
||
- **What is their goal?**: Safely move a release candidate through candidate preparation, compliance, approval and publication without hidden state.
|
||
- **Context**: Usually works in terminal-first infrastructure, often in restricted or headless environments, sometimes with a TTY, sometimes from CI.
|
||
|
||
## 2. The Happy Path Narrative
|
||
|
||
Оператор регистрирует кандидата и импортирует артефакты через CLI или API. Затем он открывает TUI и сразу видит candidate overview: latest manifest, active policy snapshot, latest run, violations и publication state. Нажатие `F6` строит manifest, `F5` запускает compliance, а экран показывает реальный прогресс stage-by-stage из task/run logs, а не локальную имитацию. После `PASSED` оператор выполняет `F8` approve и `F9` publish, и каждое действие мгновенно отражается в overview без скрытых сайд-эффектов.
|
||
|
||
## 3. Interface Mockups
|
||
|
||
### CLI Interaction
|
||
|
||
```bash
|
||
$ clean-release candidate register \
|
||
--candidate-id 2026.03.09-rc1 \
|
||
--version 1.2.0 \
|
||
--source-snapshot v1.2.0-rc1
|
||
|
||
Candidate created: 2026.03.09-rc1
|
||
Status: DRAFT
|
||
|
||
$ clean-release manifest build --candidate-id 2026.03.09-rc1
|
||
Manifest created: man-001
|
||
Manifest digest: sha256:9fa...
|
||
Status: MANIFEST_BUILT
|
||
|
||
$ clean-release compliance run --candidate-id 2026.03.09-rc1 --json
|
||
{
|
||
"run_id": "run-001",
|
||
"candidate_id": "2026.03.09-rc1",
|
||
"status": "PENDING",
|
||
"task_id": "task-123"
|
||
}
|
||
```
|
||
|
||
### TUI Layout & Flow
|
||
|
||
**Screen/Component**: Clean Release Overview
|
||
|
||
- **Layout**: Three-pane terminal layout.
|
||
- Top header: current candidate, lifecycle state, active mode (`real` or `demo`).
|
||
- Left pane: candidate summary, latest manifest, approval/publication state.
|
||
- Right pane: latest compliance run, stage timeline, violations list.
|
||
- Bottom action bar: `F5 Run`, `F6 Manifest`, `F7 Refresh`, `F8 Approve`, `F9 Publish`, `F10 Exit`.
|
||
- **Key Elements**:
|
||
- **Candidate Summary**: shows candidate id, version, source snapshot, current state.
|
||
- **Latest Manifest Card**: manifest id, version, digest, created time.
|
||
- **Policy Snapshot Card**: policy id/version and registry version used for latest run.
|
||
- **Violations Table**: severity, code, artifact path, short message.
|
||
- **States**:
|
||
- **Default**: Existing overview visible, no hidden mutation.
|
||
- **Running**: Current run and current stage are highlighted; logs update live from task events.
|
||
- **Passed**: Action bar enables `Approve` when transition is legal.
|
||
- **Blocked/Error**: Violations or failure reason become the dominant focus; approval/publish actions stay disabled.
|
||
|
||
## 4. The Error Experience
|
||
|
||
**Philosophy**: Surface the real state and tell the operator what transition is blocked. Never hide missing prerequisites by auto-fixing them in the UI.
|
||
|
||
### Scenario A: Missing Manifest
|
||
|
||
- **User Action**: Presses `F5` to run compliance before a manifest exists.
|
||
- **System Response**:
|
||
- TUI: inline error banner `Manifest required before compliance run` and highlight on `F6 Build manifest`.
|
||
- CLI: `Error: candidate 2026.03.09-rc1 has no manifest. Build a manifest first.`
|
||
- **Recovery**: Operator runs build manifest, returns to overview, retries compliance.
|
||
|
||
### Scenario B: Blocked By Policy
|
||
|
||
- **System Response**: Run ends in `BLOCKED`, latest report card turns warning state, violations table is focused automatically.
|
||
- **Recovery**: Operator can inspect violations, export/report details, fix candidate inputs, build a new manifest and request a new run.
|
||
|
||
### Scenario C: Policy Store Unavailable
|
||
|
||
- **System Response**: Request is rejected as input/system error before stage execution; UI explicitly says policy snapshot could not be resolved.
|
||
- **Recovery**: Retry when trusted policy source is restored. No fake run is shown.
|
||
|
||
### Scenario D: Headless Environment
|
||
|
||
- **System Response**: TUI refuses to start without TTY and instructs operator to use CLI/API flow.
|
||
- **Recovery**: Run equivalent `clean-release ...` command or call API.
|
||
|
||
## 5. Tone & Voice
|
||
|
||
- **Style**: Concise, operational, deterministic.
|
||
- **Terminology**: Use `candidate`, `manifest`, `policy snapshot`, `compliance run`, `report`, `approval`, `publication` consistently.
|
||
- **Avoided Terms**: Avoid vague legacy words like `checker`, `fake run`, `history cleanup`, `headless ready` inside the operator UX.
|