# v1.1.0 — Approval Workflow v2 + CEO v1 plan polish

**Status:** DRAFT (waiting on staging soak ≥7 days for Approval Workflow v2).
**Soak window:** started 2026-05-08, target tag date ≥2026-05-15.
**Previous release:** [v1.0.9](https://git.nstart.cloud/2-6/2-6-4/terravault/ordinis/-/tags/v1.0.9) — dict-relationships-v2 epic (4 phases).
**Range:** 13 commits, `v1.0.9..main`.

Two parallel work streams ship in this release. Both have been fully validated locally + on staging; prod cutover requires soak observation of the Approval workflow under real user load.

---

## Track A — Approval Workflow v2 epic (P0–P4 complete)

The maker-checker pattern for sensitive dictionaries. Per-dict opt-in via `dictionary_definitions.approval_required`. Reviewers approve/reject drafts; live data only changes after approval.

**Design doc:** `~/.gstack/projects/claude/zimin-main-design-approval-workflow-v2-20260507-121632.md`

### What's new

**Schema (Liquibase 0019, 0020):**
- `record_drafts` table with EXCLUDE constraint (one pending draft per business_key) + check constraints + FK to `dictionary_definitions`.
- `approval_required` (BOOLEAN, default false) + `approval_min_role` (VARCHAR) on `dictionary_definitions`.
- 0020 fixes Hibernate UPPERCASE enum vs lowercase check constraint mismatch (caught only by Phase 3 e2e — masked в P0/P1 because unit tests used in-memory stub repo).

**Lifecycle (DraftService):**
- `submit` (POST /api/v1/dictionaries/{name}/records/drafts) — maker proposes CREATE/UPDATE/CLOSE.
- `approve` (POST /api/v1/drafts/{id}/approve) — SERIALIZABLE tx, COPY → live + outbox event + audit. Self-approve guard (DB constraint + Java).
- `reject` (POST /api/v1/drafts/{id}/reject) — reason required (compliance). Status=REJECTED kept (D4 soft-archive).
- `withdraw` (DELETE /api/v1/drafts/{id}) — maker-only; status=WITHDRAWN.
- 6 error codes: `draft_required`, `draft_already_pending`, `draft_not_pending`, `self_approve_forbidden`, `self_reject_forbidden`, `not_draft_maker`, `reject_reason_required`.

**Approval gate (DictionaryRecordService):**
- `requireApprovalGate()` pre-checks `approval_required=true` on create/update/close → 409 `draft_required` with hint `POST /api/v1/dictionaries/{name}/records/drafts`.
- `applyApprovedCreate/Update/Close` bypass methods called only by `DraftService.approve` (validate-on-approve, not on submit).

**Bundle integration:**
- `BundleManifest.DictionaryEntry` extended with optional `approvalRequired` + `approvalMinRole`.
- `CuodBundleProperties.honorApprovalPolicy` (default false) gates whether manifest values are applied — bundle 1.3.1 ships `approvalRequired=true` for `spacecraft` + `ground_station` but prod ignores until explicitly enabled.
- Helm: `writer.bundleHonorApprovalPolicy` env-gated; staging override `true`, prod default `false`.

**Admin UI:**
- `/reviews` route — global pool queue (D3 model). Multi-select + bulk approve/reject (parallel mutations, per-draft error reporting).
- `/my-drafts` route — maker self-tracking (all statuses, withdraw button on PENDING).
- `DictionaryEditorDialog` — toggle "Require approval" + optional min reviewer role.
- Records list — "На review" / "Pending review" badge per row when business_key has pending draft.

**Phase 4 monitoring (Micrometer → Prometheus):**
- `nsi_draft_pending_total` — Gauge, global queue depth.
- `nsi_draft_submit_total{dictionary,operation,outcome=ok|already_pending|error}` — Counter.
- `nsi_draft_decision_total{dictionary,operation,outcome=approved|rejected|withdrawn}` — Counter.
- `nsi_draft_review_duration_seconds` — Timer (publishPercentileHistogram for p95/p99).

**Prometheus alerts (`ordinis.approval` rule group):**
- `OrdinisApprovalQueueDeep` — pending > 50 for 30m → warn.
- `OrdinisApprovalReviewLatencyHigh` — p95 review_duration > 8h for 30m → warn.
- `OrdinisApprovalRejectionRateHigh` — reject share > 50% for 30m → warn.
- `OrdinisApprovalSubmitErrors` — `outcome=error` > 0 for 5m → critical (catches schema bugs that previously masked as `draft_already_pending`).

**Operational docs:**
- `ordinis-infra/docs/runbooks/approval-workflow-v2.md` — debug procedures per alert + emergency disable + soak readiness checklist + SQL queries.

### Decisions (auto-applied per design doc)

| ID | Choice | Rationale |
|----|--------|-----------|
| D1 | A — per-dict policy via `dictionary_definitions` columns | Flexibility without separate config table. UI toggle obvious. |
| D2 | A — legacy CRUD on approval-required dict → 409 `draft_required` | Clean cut. Forces clients to use drafts API. |
| D3 | A — pool model for reviewers | No assignment overhead. First approver handles. |
| D4 | A — keep rejected drafts (soft archive) | Compliance + maker sees rejection reason. |

### Backward compatibility

- **Default-off:** `approval_required` defaults to `false`. Existing CRUD on existing dicts is identical.
- **Bundle policy off in prod:** even after deploy, `honorApprovalPolicy=false` in `values-prod` means bundle's `approvalRequired:true` is ignored. Explicit opt-in required.
- **Records seeding bypasses gate:** `CuodBundleImporter` writes via `recordRepository.save()` directly, not via service — so bundle imports work even on approval-required dicts.

---

## Track B — CEO v1 plan gap closures (5 features)

Closes the last 5 gaps from `~/.gstack/projects/claude/ceo-plans/2026-05-02-nsi-product-foundation.md`.

### B1 — Webhook event preview tab (`5bc82d2`)

`DictionaryEditorDialog` got a new "Event preview" tab generating 5 sample envelope JSONs (`RecordCreated/Updated/Deleted`, `DefinitionCreated/Updated`). Integrators see exactly what their HMAC-signed payload will look like before subscribing.

### B2 — JMH benchmark module (`c11044c`)

New `ordinis-bench/` Maven module with `LineageBenchmark.java` measuring hot paths (parseRef, schema traversal). Build via `mvn -P bench package -pl ordinis-bench` produces uber-jar; manual GitLab CI job `maven-bench` runs on-demand. Baseline numbers in `ordinis-bench/README.md` (parseRef ~20ns, schemaTraversal ~417ns).

### B3 — Per-dict Redis projection feature flag (CEO plan E2 tiered perf, `0a8275e`)

Liquibase 0017 added `redis_projection_enabled BOOLEAN` on `dictionary_definitions` (default false). `ProjectionWriter` early-returns when flag is off — only flipped dicts get materialized to Redis. UI toggle in `DictionaryEditorDialog` metadata tab. Cuts projection traffic by 10x on cold dicts.

### B4 — Time-travel UI (`08405fe`)

Records list route accepts `?at=<ISO timestamp>` searchParam. Datepicker control sends the parameter through `useRecords` → backend reads via existing `at=` query string. View any dict as-of any past moment. Bookmarkable URL.

### B5 — Smart JSONB search across dictionaries (`48df5ce`)

Liquibase 0018 added `pg_trgm` extension + GIN trigram index on `dictionary_records.data::text`. New endpoint `GET /api/v1/search?q=&size&perDict` runs native SQL with `ROW_NUMBER() OVER (PARTITION BY dictionary_id)` per-dict cap. New `/search` admin UI route shows grouped results by dict with display names. Min 3 chars (trigram limitation).

---

## Migrations applied (Liquibase)

| ID | Description |
|----|-------------|
| 0017 | `redis_projection_enabled` column on `dictionary_definitions` |
| 0018 | `pg_trgm` extension + GIN trigram index on `dictionary_records.data::text` |
| 0019 | `record_drafts` table + `approval_required`/`approval_min_role` columns |
| 0020 | Fix `record_drafts_status_check` + exclusion constraint UPPERCASE values (matches Hibernate enum serialization) |

All apply cleanly via testcontainers e2e (28/28 PASS).

---

## API surface (added)

**Approval Workflow v2:**
- `POST /api/v1/dictionaries/{name}/records/drafts` — maker submit
- `GET /api/v1/dictionaries/{name}/records/drafts` — pending list per dict
- `GET /api/v1/drafts/{id}` — single draft
- `DELETE /api/v1/drafts/{id}` — withdraw (maker-only)
- `POST /api/v1/drafts/{id}/approve?comment=` — reviewer approve
- `POST /api/v1/drafts/{id}/reject?comment=` — reviewer reject (reason required)
- `GET /api/v1/admin/reviews/pending?page&size` — global queue (D3 pool)
- `GET /api/v1/drafts/me?page&size` — maker self-tracking

**CEO v1 gaps:**
- `GET /api/v1/search?q=&size&perDict` — smart JSONB search

---

## Test counts

| Suite | Pass | Notes |
|-------|------|-------|
| ordinis-rest-api unit | 119/119 | +30 since v1.0.9 (DraftService, MV, Cascade, Lineage) |
| ordinis-app e2e (testcontainers) | 28/28 | +8 ApprovalWorkflowE2ETest |
| ordinis-admin-ui vitest | 89/89 | unchanged |
| helm lint (staging+prod) | clean | new approval rule group renders |
| glab ci lint | clean | maven-bench manual job added |

---

## Lessons learned (preserved)

1. **Hibernate `@Enumerated(EnumType.STRING)` writes UPPERCASE** but Liquibase 0019 declared lowercase check constraint. Every draft insert failed silently — masked by overly broad `DataIntegrityViolationException` catch in `DraftService.submit` mapping everything to `draft_already_pending`. Phase 3 e2e exposed it; migration 0020 + SQLSTATE 23P01-only mapping fixed it.

2. **Generic exception catch-all is an anti-pattern** when error codes are user-facing. We now alert specifically on `nsi_draft_submit_total{outcome=error}` to catch future schema mismatches early.

3. **JDBC `PreparedStatement` interprets every `?` as a parameter placeholder** — JSONB `?` operator must be rewritten as `-> 'key' IS NOT NULL` in Liquibase SQL. Same for regex `$` anchor → use `LIKE '%.%'`.

4. **`mvn verify -pl '!ordinis-app'` skips e2e** (testcontainers profile). Migration changes now require local `mvn -P e2e -pl ordinis-app -am test` pre-push.

5. **Bundle importer needs env-gate for policy changes** — shipping `approvalRequired=true` in manifest without `honorApprovalPolicy` flag would auto-flip prod on next deploy. Default-off pattern keeps prod safe; staging opts in.

6. **Liquibase XSD ordering** is strict: `preConditions` → `comment` → operations.

---

## Cluster ops checklist (operator, not code)

After tag is pushed:

- [ ] Click `trigger-deploy-prod` in tag pipeline (or now via `glab api -X POST projects/:id/jobs/<id>/play`).
- [ ] Verify prod health: `curl https://ordinis.k8s.264.nstart.cloud/actuator/health`.
- [ ] Verify metrics flowing: `kubectl -n ordinis-prod exec deploy/ordinis-app -- curl -s localhost:8080/actuator/prometheus | grep nsi_draft_`.
- [ ] Decide rollout strategy:
  - **Option A:** flip `bundleHonorApprovalPolicy: true` in `values-prod.yaml` → bundle 1.3.1 auto-applies approval to spacecraft + ground_station on next deploy.
  - **Option B:** point per-dict UI flip via DictionaryEditorDialog → operator chooses scope.

---

## Out of scope (deferred to v3 design doc)

- Multi-step approval chains (3+ levels)
- SLA auto-escalate timers
- Email/Slack notifications for reviewers
- ML anomaly detection for high-risk submissions
- Federation between MDM clusters

---

## Commit list

```
361f3b4 feat(approval): bulk approve/reject в /reviews queue (Phase 4 polish)
aedeafc feat(approval): /my-drafts maker self-tracking view + /api/v1/drafts/me
b2e7fd8 feat(approval): Approval Workflow v2 Phase 4 monitoring + pending-review badges
d229c54 feat(approval): bundle-driven approval policy + spacecraft/ground_station soak flag
9ef9b81 feat(approval): Approval Workflow v2 Phase 3 — e2e suite + 0020 case fix
84a4de4 feat(approval): Approval Workflow v2 Phase 2 — admin UI reviewer queue + toggle
2020af9 feat(approval): Approval Workflow v2 Phase 1 — full lifecycle + approval gate
e438c4c feat(approval): Approval Workflow v2 Phase 0 — schema + skeleton API
48df5ce feat(search): smart JSONB search across all dictionaries
08405fe feat(admin-ui): time-travel UI — view dictionary as-of any past date
0a8275e feat(redis-projection): per-dict feature flag (CEO plan E2 tiered perf)
c11044c feat(bench): JMH microbenchmarks module + manual CI job
5bc82d2 feat(admin-ui): webhook event preview tab в DictionaryEditorDialog
```

Companion ordinis-infra commits since `6f8b92c`:
```
a640339 docs(runbook): Approval Workflow v2 debug runbook + alert runbook_url wiring
bbd4f2a feat(monitoring): Approval Workflow v2 Phase 4 — 4 Prometheus alerts
28b9b93 feat(helm): wire bundleHonorApprovalPolicy + opt staging in soak
```