fix(admin,studio,docs): Sections 9-14 UAT — Add Mapping UI, packet format, demo reset gate (#30) by Taleef7 · Pull Request #45 · Taleef7/workwell

Taleef7 · 2026-05-20T20:49:29Z

Summary

Closes #30. Addresses all reported Section 9, 11, and 14 UAT bugs plus walkthrough-guide inaccuracies for Sections 9–14.

S9-4 — Add Mapping UI on Terminology Mappings panel: the Local code mappings panel header now exposes an "Add Mapping" button that toggles a labelled inline form. The form validates the four required fields (local code/system, standard code/system), enforces a 0.0–1.0 confidence range, and POSTs to the existing /api/admin/terminology-mappings endpoint. The table auto-refreshes and the form auto-closes on success.
S11 — Audit packet format selector on all three entry points: the Studio Release & Approval tab still rendered an old direct-JSON-download button. It now uses the shared AuditPacketExportButton, so case detail, run detail panel, and Studio Release & Approval tab (and the Studio header) all expose the same JSON/HTML format dropdown.
S14-1 — Hide Reset Demo Data in production: the Reset demo data card on /admin is now gated on process.env.NEXT_PUBLIC_DEMO_MODE === "true". Because frontend/next.config.ts already fails fast if a production build is configured with NEXT_PUBLIC_DEMO_MODE=true, the card is structurally absent in production Vercel builds, not merely hidden via CSS. The backend @Profile("!prod") 403 remains the second line of defence.
Guide updates in docs/WALKTHROUGH_GUIDE.md:
- Section 9: renamed panel heading to Local code mappings, documented Reviewed By + Notes columns, clarified that Validate Mappings lives on the Source mappings panel (not the terminology panel), and documented the new Add Mapping inline form.
- Section 10: documented the actual button labels and noted the audit-events CSV export lives on the Cases page (not Admin).
- Section 11: documented the consistent JSON/HTML format dropdown across all three entry points.
- Section 12: added an explicit Claude Desktop config-file path, JSON config snippet with Authorization: Bearer <JWT>, and instructions for acquiring a WorkWell JWT.
- Section 13: added a Bug-4 cross-reference for the /login redirect on session expiry so it's not mistaken for an RBAC denial.
- Section 14: documented the inline (non-modal) confirmation, the frontend visibility gate, and the seven-measure / four-lifecycle catalog left after a Demo Reset.

Acceptance criteria

Terminology Mappings panel has "Add Mapping" UI (option A from the issue)
All three audit packet entry points offer JSON / HTML format selection
"Reset Demo Data" button hidden in production Vercel deployment
Guide inaccuracies for Sections 9–14 corrected in docs/WALKTHROUGH_GUIDE.md

Test plan

frontend/npm run lint — passed (only the pre-existing test/mocks/next-font.ts anonymous-default-export warning)
frontend/npm test — 40/40 passed
frontend/npx tsc --noEmit — clean
Playwright local E2E:
- Logged in as admin@workwell.dev, opened Add Mapping form on /admin, submitted ANNUAL-FIT-TEST → SNOMED 415070008, observed the new row in the table and the form auto-closing.
- With NEXT_PUBLIC_DEMO_MODE=true: Reset demo data card renders on /admin.
- With NEXT_PUBLIC_DEMO_MODE=false: Reset demo data card does not render on /admin; Admin page (including the Local code mappings panel + Add Mapping button) still renders normally.
- Opened Audiogram in Studio → Release & Approval tab, confirmed both packet export controls (header + tab) expose the JSON/HTML dropdown.

Notes for reviewer

Status promotion (PROPOSED → REVIEWED → APPROVED → REJECTED) for existing mappings is currently API-only; the Add Mapping flow exists for creating new mappings. This is called out in the WALKTHROUGH_GUIDE.md Section 9 update.
This PR is based on main (post-merge of PR fix: address Section 5 case detail UAT issues #43) and does not depend on the still-open fix/sprint-1-uat-sections-6-8 branch.

🤖 Generated with Claude Code

…rmat, demo reset gate (#30) Address all reported Section 9, 11, and 14 UAT bugs from issue #30 plus walkthrough-guide inaccuracies for Sections 9–14. S9-4: Local code mappings panel now exposes a toggleable "Add Mapping" inline form that POSTs to /api/admin/terminology-mappings with client- side validation for required fields and confidence range. S11: Studio Release & Approval tab now uses the shared AuditPacketExportButton so the JSON/HTML format dropdown is consistent across all three packet entry points (case detail, run detail, Studio). S14-1: The Reset Demo Data card is gated on NEXT_PUBLIC_DEMO_MODE === "true" so the card is structurally absent in production Vercel builds. next.config.ts already fails fast if a prod build is configured with that flag enabled, so this guarantees the section never renders in production. Walkthrough guide: corrected Section 9 (panel heading + Reviewed By / Notes columns + Validate Mappings location), Section 10 (button labels + audit CSV on Cases page), Section 11 (consistent format dropdown across all three entry points), Section 12 (Claude Desktop config and JWT acquisition), Section 13 (Bug 4 cross-reference for /login redirect), Section 14 (inline confirmation, visibility gate, post-reset catalog). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

vercel · 2026-05-20T20:49:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
workwell-measure-studio	Ready	Preview, Comment	May 21, 2026 1:14am

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Taleef7

I found a couple of blockers before merge. The new Add Mapping UI turns terminology mapping creation into a normal admin workflow, but the underlying create path does not write an audit event, which violates the repo rule that every state change is audited. Also, the form/status documentation currently undercuts the claimed review workflow by allowing direct APPROVED/REVIEWED/REJECTED creation while the guide says promotion happens through API calls that do not actually update existing mappings. I would fix these before merging.

Taleef7 · 2026-05-20T21:03:25Z

+    setSavingMapping(true);
+    setMappingError(null);
+    try {
+      await api.post("/api/admin/terminology-mappings", {


This newly exposed admin workflow creates a terminology mapping, but the backend path it calls (AdminController#createTerminologyMapping -> ValueSetGovernanceService#createTerminologyMapping) only inserts into terminology_mappings; it does not write an audit_events row. The repo hard rule says every state change writes audit_event, and this PR makes the state change reachable from the UI. Please add an audited event for mapping creation (including actor, local/standard codes, status/confidence) and regression coverage before merge.

Taleef7 · 2026-05-20T21:03:26Z

+              </label>
+              <label className="text-xs font-medium text-slate-700">
+                Status
+                <select


This selector lets an admin create a brand-new mapping directly as APPROVED, REVIEWED, or REJECTED, but the form text says new mappings default to PROPOSED and require review before promotion. Since the create endpoint does not populate reviewed_by/reviewed_at, an APPROVED row created here looks approved with no reviewer metadata. Either constrain this UI to create PROPOSED mappings only, or implement a real reviewed/promotion path that records reviewer metadata and audit history.

… status to PROPOSED - Backend: emit TERMINOLOGY_MAPPING_CREATED audit event from ValueSetGovernanceService.createTerminologyMapping (actor, local/standard codes, status, confidence) — satisfies the hard rule that every state change writes audit_event - Frontend: remove status selector from Add Mapping form; new mappings are always PROPOSED — prevents creating APPROVED/REVIEWED rows with no reviewed_by/reviewed_at metadata - Tests: add createsTerminologyMappingWithProposedStatus and rejectsTerminologyMappingMissingRequiredFields to AdminControllerTest Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The JOURNAL.md conflict resolution in the GitHub PR UI dropped the Sections 6-8 entry from main. Reinsert it between the Sections 9-14 and Section 5 entries so all three daily log entries are present. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…L conflict Both branches added entries at the top of docs/JOURNAL.md. Kept both: Sections 9-14 entry (branch) followed by Sections 6-8 entry (main). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…eation Adds regression coverage for the hard rule that every state change writes audit_event. The createTerminologyMappingPersists integration test now queries audit_events by entity_id and asserts a TERMINOLOGY_MAPPING_CREATED row exists with the correct event_type, entity_type, local code, and status. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings May 20, 2026 20:49

vercel Bot deployed to Preview May 20, 2026 20:49 View deployment

Copilot started reviewing on behalf of Taleef7 May 20, 2026 20:50 View session

Copilot AI reviewed May 20, 2026

View reviewed changes

Taleef7 commented May 20, 2026

View reviewed changes

Taleef7 self-assigned this May 20, 2026

vercel Bot deployed to Preview May 20, 2026 21:55 View deployment

vercel Bot deployed to Preview May 21, 2026 01:00 View deployment

chore: merge main into fix/sprint-1-uat-sections-9-14, resolve JOURNA…

7fe37cd

…L conflict Both branches added entries at the top of docs/JOURNAL.md. Kept both: Sections 9-14 entry (branch) followed by Sections 6-8 entry (main). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 21, 2026 01:08 View deployment

vercel Bot deployed to Preview May 21, 2026 01:14 View deployment

Taleef7 merged commit c6c8d21 into main May 21, 2026
8 checks passed

Taleef7 deleted the fix/sprint-1-uat-sections-9-14 branch May 21, 2026 01:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(admin,studio,docs): Sections 9-14 UAT — Add Mapping UI, packet format, demo reset gate (#30)#45

fix(admin,studio,docs): Sections 9-14 UAT — Add Mapping UI, packet format, demo reset gate (#30)#45
Taleef7 merged 5 commits into
mainfrom
fix/sprint-1-uat-sections-9-14

Taleef7 commented May 20, 2026

Uh oh!

vercel Bot commented May 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Taleef7 left a comment

Uh oh!

Taleef7 May 20, 2026

Uh oh!

Taleef7 May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Taleef7 commented May 20, 2026

Summary

Acceptance criteria

Test plan

Notes for reviewer

Uh oh!

vercel Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Taleef7 left a comment

Choose a reason for hiding this comment

Uh oh!

Taleef7 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Taleef7 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented May 20, 2026 •

edited

Loading