l2-market-parser/docs/goals/merchant-hud-and-location-capture/PLAN.md

Merchant HUD And Location Capture Implementation Plan

Intent: Дать игроку спокойную оперативную обратную связь поверх окна Lineage II и позволить вручную сохранить примерное место торговца вместе с посещением магазина. Current Behavior: Состояние распознавания видно только в большом окне аудита. Превью уже умеет рисовать найденные области и прогресс иконок, но при возврате в игру оно скрыто. Сервер сохраняет OCR-наблюдения и общую калибровку, но отдельного посещения магазина и изображения места нет. Expected Outcome: Из аудита открывается один компактный always-on-top HUD. Он использует уже существующее состояние выбранного источника и показывает торговца, сторону сделки, прогресс предметов и последнюю распознанную позицию. Пользователь может снять текущий кадр, увидеть сжатую миниатюру и явно сохранить её как место текущего посещения магазина. Target-Perspective Output: Игрок возвращается в Lineage II и поверх окна видит Покупка · Dwa, сетку с найденными и ожидающими иконками и последнюю цену. После Снять место он видит миниатюру, подтверждает сохранение и получает устойчивый статус Место сохранено. Truth Owner: Браузерный result владеет только живым состоянием HUD и текущим shopVisitId. PostgreSQL в home-service владеет сохранённым посещением и его JPEG. Каталог home-service остаётся владельцем канонических имён и иконок предметов. Contract Boundary: Parser отправляет authenticated same-origin JSON с UUID посещения, торговцем, стороной, временем, исходными размерами и JPEG data URL. Каждое OCR-наблюдение получает необязательный shopVisitId, чтобы связать товары с тем же посещением. Cutover: HUD читает тот же result, что текущие source preview и results; отдельного второго состояния распознавания не создаётся. После появления HUD существующие маленькие status chips в source preview остаются fallback внутри страницы, но перестают быть основным игровым feedback path. Displaced Path: Постоянное переключение из игры в большую вкладку Результат для контроля процесса демотируется до подробной диагностики. Автоматическая или покадровая запись мест не добавляется. Value Density: Первый срез использует нативный Document Picture-in-Picture вместо Electron/Tauri и сохраняет только один подтверждённый сжатый кадр на посещение. Acceptance Evidence: В поддерживаемом Chrome/Edge игрок открывает HUD, возвращается в игру, видит неизменного торговца при tooltip, наблюдает переход одного слота из ожидания в найденный, снимает место и после server acknowledgement видит сохранённый статус. В PostgreSQL находится одна строка посещения с тем же shopVisitId; связанное наблюдение содержит тот же ID. Evidence Lane: Автоматически: parser unit tests, HUD model tests, contracts/backend route tests, migration smoke, parser/frontend/backend builds и git diff --check. Вручную только после отдельного разрешения: реальное always-on-top поведение над Lineage II, читаемость и полезность сжатого снимка. Kill Criteria: Не создавать второй recognition loop, не копировать OCR-состояние в независимый store, не сохранять full-resolution кадры, не снимать экран автоматически, не добавлять native wrapper до доказанного ограничения PiP. Если требуется несколько независимых overlay одновременно или click-through поверх каждого окна игры, остановить web-срез и отдельно спланировать Windows companion. Architecture Slice: l2-market-parser владеет HUD, visit lifecycle и компрессией кадра; shared contract, BFF, Nest service и PostgreSQL table живут в home-service; ingress меняется только для bounded screenshot body. Plan Review Gate: Requires PRE review before execution.

Physical Scene And Interface Contract

Игрок работает вечером на большом мониторе с несколькими оконными клиентами Lineage II. HUD лежит поверх текущего клиента и должен читаться на любом игровом фоне, не требуя переключения внимания.

• Один solid dark utility surface примерно 320 × 420, без прозрачного стекла, игровых рамок и декоративной анимации.
• Верхняя строка: выбранный источник и состояние сбора.
• Главная строка: Покупает/Продаёт · торговец. Она занимает фиксированное место и не прыгает при OCR.
• Сетка 6 × 3: каноническая иконка для найденного предмета, нейтральная ячейка для ожидающего, понятный ? для неоднозначного.
• Последний результат: название, количество, цена и короткий статус совпадения с каталогом.
• Действие Снять место создаёт inline-миниатюру. Рядом появляются Сохранить и Переснять; modal не используется.
• Успех, ошибка и ожидание меняют текст/цвет в фиксированном status slot. Движение только для смены состояния, 150–200 ms, без layout animation.
• Document PiP открывается только по нажатию пользователя и только в secure context. Если API недоступен, большая страница продолжает работать и объясняет, что нужен актуальный Chrome/Edge.
• Web-страница не может задавать позицию PiP и поддерживает только одно такое окно. Пользователь размещает его сам; HUD показывает выбранный источник.

Architecture Map

Files to create

l2-market-parser:

• src/market-hud.js: одно представление HUD из существующего result, открытие/закрытие Document PiP и fallback-status.
• test/market-hud.test.js: модель торговца, прогресс слотов, последний предмет и unsupported fallback.

home-service:

• Следующая свободная backend/migrations/*.sql: таблица l2_market_shop_visits.
• Соответствующий backend/migrations/meta/*_snapshot.json и _journal.json только через текущий Drizzle workflow.
• frontend/src/app/api/l2/market/visits/route.ts: authenticated same-origin BFF PUT.

Files to modify

l2-market-parser:

• index.html: кнопка Поверх игры и минимальные fallback/status hooks.
• src/main.js: передача выбранного result в HUD, lifecycle одного shopVisitId, захват текущего источника и явное сохранение миниатюры.
• src/frame-analyzer.js: новый visit ID при подтверждённой смене/повторном открытии магазина; очистка ID вместе с transient shop progress; добавление ID в observation.
• src/style.css: общие HUD tokens и компактная layout-сетка без отдельной визуальной системы.
• src/parser.js: чистый helper экспорта HUD/visit данных, только если он уменьшает дублирование.

home-service:

• contracts/src/l2.ts: strict L2MarketShopVisitSchema, bounded JPEG data URL, размеры и optional shopVisitId у observation.
• backend/src/database/schema.ts: l2MarketShopVisits с UUID, временем, source, side, merchant, dimensions, bounded image text и indexes.
• backend/src/l2/market/l2-market.controller.ts: PUT /l2/market/visits/:id.
• backend/src/l2/market/l2-market.service.ts: idempotent insert/update одного пользовательски подтверждённого кадра посещения.
• backend/src/l2/market/l2-market.service.spec.ts и controller spec: strict validation, idempotency и linkage ID.
• frontend/src/lib/l2-session.spec.ts: unauthenticated/cross-origin rejection и authenticated forwarding.
• docs/goals/l2-craft-farm-planner/l2-vault.nginx: exact visits route с bounded body limit только если итоговый JSON превышает текущие 16 KiB.
• frontend/public/l2/market-audit/**: только сгенерированный production bundle после parser build.

Files to avoid

• Не менять catalog matching, OCR, calibration geometry и quote/snapshot semantics.
• Не хранить изображение внутри каждого item observation или каждого retry batch.
• Не трогать другие home-service сайты, admin access и backend public port.
• Не добавлять Electron, Tauri, React/state library, object storage или image processing dependency.

Source of truth and paths

• Read path: state.results → buildHudModel(result) → один PiP document. Каталожные имена/иконки уже приходят через существующий fuzzy resolver.
• Screenshot path: выбранный source video → canvas downscale → JPEG quality reduction → inline preview → explicit confirm → BFF → Nest → PostgreSQL.
• Observation link: activateShop создаёт shopVisitId; каждое последующее observation этого магазина несёт ID; закрытие магазина после существующего miss policy очищает ID.
• Compression ceiling: начать с max width 640, JPEG quality 0.35; при превышении contract size уменьшать quality/width до bounded payload. Сохранять исходные и итоговые размеры.
• Write semantics: повторный PUT с тем же visit ID заменяет только подтверждённую миниатюру и capture metadata; OCR observations остаются append-only batch payloads.

Tasks

1. Зафиксировать visit lifecycle и shared contracts

Allowed scope: src/frame-analyzer.js, parser tests, contracts/src/l2.ts, market service tests.

• Добавить shopVisitId и shopVisitStartedAt в transient result.
• Создавать ID только при первом подтверждённом заголовке после reset или реальной смене shop key.
• Не менять ID, пока tooltip закрывает заголовок.
• Добавить optional ID в observation и strict visit screenshot contract.

Verification: npm test; focused contracts build and market specs.

Acceptance: тест воспроизводит header → tooltip → несколько items и доказывает один visit ID и неизменного торговца.

2. Построить один PiP HUD из существующего result

Allowed scope: market-hud.js, main.js, index.html, style.css, HUD test.

• Открывать Document PiP только по явному нажатию.
• Подключить модель выбранного source result без второго timer/recognition loop.
• Рендерить merchant, side, slot progress, icons, unresolved state и last item.
• Перерисовывать HUD после текущего drawSourceOverlay/result update.
• Закрытие PiP не останавливает сбор; закрытие основной страницы закрывает PiP нативно.

Verification: parser unit tests and production build.

Acceptance: mocked supported/unsupported window tests; модель сохраняет фиксированную геометрию при idle/found/error.

3. Добавить ручной capture с inline preview

Allowed scope: parser HUD/main code and tests.

• Снять место доступно только при active source и подтверждённом merchant/visit ID.
• Захватить один текущий frame, downscale/compress без новой зависимости.
• До отправки показать миниатюру, размер и Сохранить/Переснять.
• После ошибки оставить миниатюру для повторного сохранения; не делать background screenshots.

Verification: deterministic canvas compression test with a generated fixture; payload always satisfies contract limit.

Acceptance: одна кнопка создаёт один preview; cancel/reshoot не пишет сервер.

4. Сохранить место торговца в home-service

Allowed scope: migration/schema, shared contract, market controller/service, exact BFF route and tests.

• Создать bounded visit table and index by merchant/seenAt.
• Реализовать authenticated same-origin PUT and idempotent backend write.
• Не принимать PNG, произвольный MIME, oversized base64 или mismatched path/body ID.
• Не возвращать изображение из unrelated snapshot/catalog endpoints.

Verification: Drizzle migration generation/check, market service/controller specs, frontend BFF test, contracts/backend/frontend builds.

Acceptance: database smoke verifies one replaceable visit row and observation payload with the same shopVisitId.

5. Интегрировать и доказать cutover

Allowed scope: generated audit bundle, relevant README/evidence, exact ingress body rule if required.

• Пересобрать parser directly into frontend/public/l2/market-audit.
• Проверить bundle на отсутствие embedded tokens/full-resolution fixtures.
• Programmatic public route check remains password-gated.
• Не объявлять игровой overlay доказанным без отдельного manual permission.

Verification: both repository builds, focused tests, git diff --check, migration smoke.

Acceptance: automated lane green; target lane recorded as either proven over a real game window or implemented but visually unproven.

PRE Self-Review

• Mode: PRE
• Verdict: aligned
• Blockers: none for the web prototype.
• Major constraint: Document PiP gives one user-positioned always-on-top window, not multiple click-through overlays attached to game windows. This is explicit in UX and kill criteria.
• Major security constraint: screenshots may contain chat/account information; capture stays manual with inline preview, strict JPEG/size validation and authenticated storage.
• Smallest next gate: owner accepts the one-PiP limitation and manual screenshot confirmation, then execution starts with Task 1.