using Ban.Sdaid.Notation.Documents;
namespace Ban.Sdaid.Icd.Epics.RecognitionStand
{
/// <summary>Эпик «Стенд распознавания карт» — аналитический инструментарий для разметки трафаретов по видам бланков и проверки извлечения данных.</summary>
public class EPIC_RecognitionStand : IEpicDocument
{
public static string _refName = "эпик «Стенд распознавания карт»";
public string Name => "Стенд распознавания карт";
public string Description =>
@"Браузерный инструментарий аналитика: разметить трафарет (геометрию клеток) по эталонному бланку, применить его к сканам, прочитать отметки офлайн и текст выбранным движком, сравнить подходы. Живёт вне продуктового кода, в src-tools.";
public string Version => "0.1";
public string Status => "draft";
public string[] Comments => new[]
{
"2026-08-24. Первичная фиксация: стенд вынесен в src-tools/card-extraction-stand, оформлен как эпик инструментов.",
"2026-08-25. Детектор Y-границы кадра переведён с боковых чернил на крайние горизонтали сетки (frameYbyLines); регистрация по линиям сделана тождество-сохраняющей. OQ-RS-2 сужен до прод-устойчивости.",
};
public static string S1_Goal = """
## Цель
Дать аналитику средства **спроектировать распознавание** одного вида бумажной карты и
**проверить его на реальных сканах**, не трогая продуктовый код. Ключевой результат
стенда — переиспользуемые **трафареты по видам страниц** (`page_type`): описание точной
геометрии клеток бланка, снятое один раз с эталонного скана.
Устройство подчинено принципу **«математика вперёд, модель — только на текст»**:
выравнивание, привязка сетки, детекция отметок — детерминированные алгоритмы по пикселям
(бесплатно, воспроизводимо, мгновенно); большая языковая модель (VLM) или облачный OCR
вызывается **только** для чтения рукописного/печатного значения в непустой ячейке.
Стенд — исследовательский слой перед реализацией: на нём отрабатывается подход, который
затем ложится в продуктовую обработку пакета (см. Связанные артефакты).
""";
public static string S2_Actors = """
## Акторы
| Актор | Роль в эпике |
|---|---|
| Аналитик | размечает трафареты по эталонным бланкам, применяет к сканам, читает зоны, сравнивает движки распознавания |
| Разработчик | сопровождает стенд, переносит отработанный подход в продуктовую обработку |
""";
public static string S3_Scope = """
## Границы
**Входит:**
- **Редактор трафарета** — разметка клеток (checkbox/text) по эталону: детекция линий сетки,
примагничивание, клик-по-клетке, id клетки из подписи (translit), экспорт/импорт JSON.
- **Применение трафарета** — загрузка скана, выравнивание вертикали (deskew), опциональная
привязка по линиям сетки, чтение зон: отметки (офлайн, прототип-вычитание) и текст
(Qwen-VL / Yandex OCR), вывод в JSON и читаемый список полей.
- **OCR-лаборатории** — сравнение движков распознавания текста и координатной привязки (grounding) на отдельных страницах.
- **Локальный сервер** — прокси (обход CORS к Yandex/Qwen/orthocover).
- **Библиотека трафаретов** — JSON по видам страниц (front_v1/v2, back_v1/v2).
**Не входит:** продуктовая обработка пакета и её конвейер, сервис нормализации кадра
(orthocover) как таковой, обучение/дообучение моделей, ведение форм и видов ИК
(администрирование). Стенд их **использует** или **имитирует**, но не реализует.
""";
public static string S4_AcceptanceCriteria = """
## Критерии приёмки
1. Трафарет — это JSON вида страницы (`page_type`): рамка-якорь, линии сетки и клетки
`{id, type: checkbox|text, section (путь), label, x, y, w, h}` в долях 0..1.
2. Разные виды бланка требуют **своего** трафарета: они отличаются не только координатами,
но и составом колонок (пример: Декор-Обрез — 5 опций в back_v1 против 3 в back_v2).
3. Отметки (галочка/крестик/штрих — любая) читаются **офлайн**, без обращения к модели;
устойчивость к форме метки обеспечивает прототип-вычитание по колонке.
4. Текст читается выбранным движком; перед вызовом — офлайн-проверка «есть ли чернила»,
пустые клетки не отправляются.
5. Скан обрабатывается без нормализации: по умолчанию только выравнивание вертикали (deskew);
нормализация (orthocover) и привязка по линиям — опциональны.
6. Инструменты — статические HTML, открываются в браузере через локальный прокси;
ключи доступа проходят насквозь и никуда, кроме целевого API, не пишутся.
""";
public static string S5_OpenQuestions = $"""
## Открытые вопросы
| № | Вопрос |
|---|---|
| OQ-RS-1 | Автоопределение вида страницы (`page_type`) — чтобы форма подбиралась сама. Механизм решён геометрическим детектором — {nameof(Ban.Sdaid.Icd.Arch.Adr.ADR_015_FormPageDetection)}; открытым остаётся перенос в продуктовую обработку и прод-устойчивость (см. OQ-RS-2) |
| OQ-RS-2 | Запас прочности привязки на произвольном (прод) фото. На эталонных сканах решено: Y-граница кадра берётся по крайним горизонталям сетки (frameYbyLines), регистрация по линиям регуляризована к аффинной (мёртвая зона + отбраковка выбросов) — на «своём» скане вырождается в тождество. Открыт вопрос устойчивости на сильно «плывущих» и низкокачественных сканах |
| OQ-RS-3 | Потолок точности упирается в разрешение фото (~816px, клетка ~55px); при съёмке 2000px+ офлайн и VLM резко точнее |
| OQ-RS-4 | Формат и версионирование библиотеки трафаретов, перенос отработанного подхода в продуктовую обработку |
""";
public static string S99_Related = $"""
## Связанные артефакты
- {nameof(Ban.Sdaid.Icd.Epics.CardExtraction.EPIC_CardExtraction)} — эпик извлечения данных из карты (продуктовая цель, которую стенд обслуживает).
- Инструменты: `src-tools/card-extraction-stand/` — редактор и применение трафарета, OCR-лаборатории, сервер, библиотека трафаретов.
""";
}
}