POSA_Copyrighter/docs/plans/2026-06-03-operator-console-quality-improvement-plan.md

status	created	type	title
active	2026-06-03	quality	Operator console quality improvement plan

Operator Console Quality Improvement Plan

Scope

This plan responds to the concrete quality issues raised during review of the current operator console:

• static tests rely too heavily on string presence;
• visible Korean copy is partially corrupted;
• web/operator-gui/app.js carries too many responsibilities;
• the case workbench still needs stronger next-action guidance;
• submission upload and folder reload UX needs clearer operator feedback.
• the product purpose is not explicit enough in the UI.

1. Strengthen Tests Beyond String Presence

Problem: The operator GUI tests catch missing selectors and accidental deletion, but they do not prove the main flows work in a browser.

Plan:

• Keep static tests as fast contract checks.
• Add server-backed behavior tests for upload, reload, and manual search.
• Add future browser smoke tests for queue selection, workbench tab switching, and suggested-query fill behavior.

Immediate action: Completed:

• tests/operator_gui/test_browser_smoke.py now verifies the suggested-query browser flow: selecting a recommendation fills the manual query input without running a search.
• tests/operator_gui/test_browser_smoke.py now verifies the real browser upload flow through the local HTTP server: file selection, /api/submissions/upload-image, saved image file, new queue item, workbench navigation, and selected uploaded submission.
• tests/rights_filter/server/test_http_app.py::test_http_server_uploads_submission_image_into_active_queue verifies the upload HTTP contract saves the image into the active queue and returns the uploaded submission in the refreshed bootstrap payload.
• tests/operator_gui/test_static_workbench.py retains fast structural checks and now also protects module load order, mojibake prevention, product purpose copy, workflow guidance, and upload UX contracts.

2. Repair Corrupted Korean Copy

Problem: Several operator-facing status strings in app.js are mojibake. This weakens trust in a review tool.

Plan:

• Prioritize visible workflow copy over legacy compatibility strings.
• Replace high-use status text first: reload, folder import, image upload, bulk rerun, manual search, and decision memo errors.
• Keep compatibility-only tokens isolated until tests can be rewritten around clean labels.

Immediate action: Completed:

• Reload, folder import, upload, bulk rerun, manual search, evidence, provider, knowledge DB, candidate, correction, and empty-state copy were normalized to readable Korean.
• A mojibake regression check now scans the operator GUI files for common corrupted UTF-8 fragments.
• The operator GUI JavaScript files pass node --check.

3. Split app.js Responsibilities

Problem: app.js owns queue rendering, workbench rendering, search, knowledge DB, provider controls, upload, and audit events.

Plan:

• First extract pure helpers: file payload reading, evidence sufficiency, query suggestions, and import status formatting.
• Then split rendering domains into small static modules if the deployment can safely move to module scripts.
• Avoid a broad framework migration.

Immediate action: Completed:

• web/operator-gui/operator-labels.js owns visible label dictionaries.
• web/operator-gui/submission-import.js owns submission import/upload file payload helpers and import status message helpers.
• web/operator-gui/evidence-guidance.js owns evidence sufficiency checks, follow-up reasons, query seed normalization, and suggested evidence queries.
• web/operator-gui/operator-search.js owns query status labels, query strategy labels, and manual search provider normalization.
• web/operator-gui/app.js now delegates those concerns to the extracted helpers while retaining rendering and event orchestration.

Remaining:

• Rendering domains are still mostly in app.js. Further extraction should focus on evidence rendering and knowledge/candidate rendering only if needed, because the current no-framework static runtime is now split enough to reduce the most immediate risk.

4. Improve Next-Action Guidance

Problem: The workbench shows evidence, but does not always tell the operator what to do when evidence is thin.

Plan:

• Keep the existing "근거 보강 추천" panel.
• Expand the sufficiency heuristic with clearer reasons: no direct match, too few searchable results, provider empty state, or duplicate queries.
• Add a browser smoke test to ensure clicking a recommendation fills the manual query form without running a search.

Immediate action: Completed:

• The "근거 보강 추천" panel now explains concrete insufficiency reasons such as missing direct/page evidence, fewer than two searchable results, empty provider results, and failed provider history.
• Suggested queries fill the manual search input and switch to the query tab without automatically running a search.
• Browser smoke coverage verifies this non-automatic behavior.

5. Clarify Upload And Folder Reload UX

Problem: Operators should not need to understand active queue internals. After adding a photo or changing folders, the UI should say what happened.

Plan:

• Provide a file picker for adding a photo to the active queue.
• Save uploaded files into the active queue folder and rescan immediately.
• Select the uploaded submission when available.
• Show clear status text for imported count, selected ID, upload progress, and active folder label.

Immediate action: Completed:

• The upload endpoint and UI are implemented.
• Upload success selects the uploaded submission, resets queue filters, moves to the workbench evidence tab, and tells the operator the new case was selected.
• The queue header now explains that adding a photo creates a new review case and opens it for case review.
• Browser smoke coverage verifies the real upload flow end to end.

6. Clarify Product Purpose And Workflow

Problem: The console exposed many implementation concepts and actions, but the product purpose and operator flow were not explicit enough.

Plan:

• State the product purpose in the top bar.
• Show the operator's expected flow on the queue screen.
• Keep this copy stable with static tests.

Completed:

• The top bar now states: "이미지 저작권 위험 심사" and explains that submitted images, external search evidence, and the internal criteria DB are reviewed together.
• The queue screen now shows a three-step operating flow: "심사 건 추가", "근거 보강", and "운영 결정".
• Static tests protect the purpose copy and workflow copy.

Verification

Run:

python -m pytest tests\operator_gui\test_static_workbench.py
python -m pytest tests\operator_gui\test_browser_smoke.py
python -m pytest tests\rights_filter\server\test_http_app.py::test_http_server_uploads_submission_image_into_active_queue
node --check web\operator-gui\app.js
node --check web\operator-gui\operator-labels.js
node --check web\operator-gui\submission-import.js
node --check web\operator-gui\evidence-guidance.js
node --check web\operator-gui\operator-search.js

Latest local verification:

• python -m pytest tests\operator_gui\test_static_workbench.py tests\operator_gui\test_browser_smoke.py -> 39 passed.
• python -m pytest tests\rights_filter\server\test_http_app.py::test_http_server_uploads_submission_image_into_active_queue -> 1 passed.
• node --check passed for app.js, operator-labels.js, submission-import.js, evidence-guidance.js, and operator-search.js.

Future verification:

• If more rendering code is extracted from app.js, add a browser smoke check for that affected flow before relying on static checks.
• If the visual layout changes again, refresh the ui-overhaul-final-results.json overflow audit and screenshots.