Backend (src-api) — карта кода

1. Проекты (src-api)

2. Стек и текущее состояние

• net10, ASP.NET Core: контроллеры + OpenAPI (Microsoft.AspNetCore.OpenApi, эндпоинт /openapi/v1.json). Enum сериализуются строкой (JsonStringEnumConverter, ADR-SRV-002).
• Самописный CQRS (без MediatR): query- и command-ветки, авто-регистрация обработчиков, без pipeline-шагов. Контроллер зависит от процессора (IIcdQueryProcessor/IIcdCommandProcessor).
• Единая обёртка ответа — IcdBaseRequestResult { RequestId?, IsSuccess, StatusCode, Message?, Errors[] }, полезная нагрузка в Payload наследника (ADR-SRV-001).
• Персистентность — EF Core + PostgreSQL (IcdDbContext, миграции в Infrastructure/Persistence/Migrations, строка подключения ConnectionStrings:IcdDb). Сущности — по ADR-SRV-003 (enum строкой, FK-каскад).
• Файловое хранилище — IFileStorage (диск, Storage:RootPath); на стенде заменяется S3/MinIO той же абстракцией.
• Нормализация изображений — IImageNormalizer (OrthocoverImageNormalizer — HTTP-клиент внешнего orthocover: multipart-запрос, разбор multipart/mixed; ADR-SRV-005). Конфиг Orthocover:Url/ApiKey (секрет — в appsettings.Local.json/env, вне git).
• Срезы: сдача POST /api/InputPacket (multipart: произвольный набор кадров без плана/ролей/идентификаторов — ADR-007 → номер П-ГГГГММДД-NNN от максимального суффикса за день, ключи хранения <номер>/<NN>.<ext> по ADR-002, файлы в хранилище, пакет в БД, состояние Queued); чтение очереди GET /api/InputPacket (список с составом из БД, мягко удалённые исключены); содержимое кадра GET /api/InputPacket/{id}/frames/{order}/content (поток из хранилища; variant=normalized — обработанное); обработка POST /api/InputPacket/{id}/frames/{order}/normalize (нормализация кадра через orthocover, хранит обработанный PNG; есть и пакетный .../normalize); удаление DELETE /api/InputPacket/{id} (мягкое — флаг Deleted) и .../force (жёсткое — запись каскадом + файлы кадров). Русские подписи идентификаторов — Application/CaptureLabels. Аутентификация, read/write-split, pipeline, автозапуск обработки (очередь), определение вида ИК/ролей и извлечение полей — ещё не введены.
• Конфигурация по средам — appsettings.json (IConfiguration); CORS-origins фронта из Cors:AllowedOrigins (пусто = разрешить любой, локально); Swagger UI только в Development. Конфиги сред генерятся devops/configs-generator (ADR-SRV-004).
• Централизованные версии пакетов — src-api/Directory.Packages.props.
• Solution — Ban.Icd.slnx на корне репозитория; ведётся отдельно от спеки (sdaid/Ban.Sdaid.sln), у которой свой процесс сборки-рендера.

3. Соответствие spec → code

Раскладка спеки (sdaid) и кода (src-api) различаются — целевой маппинг:

Каждый код-файл реализации несёт XML-<remarks> со ссылкой на артефакт спеки sdaid (правило в CLAUDE.md). Операции ввода/очереди описаны контрактом в спеке: 45_Api/Endpoints/InputPackets/{SubmitInputPacket, GetInputQueue, DeleteInputPacket, GetFrameContent, NormalizePacket} (endpoint + команда/запрос + результат), парные 55_Backend/Handlers/... (сценарии; у GetFrameContent handler-а нет — прямая отдача файла из хранилища); базовые типы — 45_Api/Based. Внешние интеграции — под своим ADR (нормализация изображений — ADR-SRV-005).

4. Сборка и запуск

dotnet build Ban.Icd.slnx
# БД: PostgreSQL по строке ConnectionStrings:IcdDb; применить миграции:
dotnet ef database update --project src-api/Ban.Icd.Infrastructure --startup-project src-api/Ban.Icd.Api
dotnet run --project src-api/Ban.Icd.Api --urls http://localhost:5080
# сдача:   POST http://localhost:5080/api/InputPacket   (multipart)
# очередь: GET  http://localhost:5080/api/InputPacket
# контракт/UI: /openapi/v1.json, /swagger (Development)

Особенности окружения (расположение dotnet SDK, DOTNET_ROOT для dotnet ef, доступ к PostgreSQL) относятся к конкретной машине разработчика и в спеке не фиксируются.

5. Связанные документы

• FrontendCodeMap — карта кода фронта; фронт потребляет контракт этого backend.
• ADR_SRV_001_Cqrs — CQRS и обёртка ответа, которым следует код.
• ADR_SRV_002_GridQueryContract — контракт списочных запросов (для будущих гридов).
• ADR_SRV_003_EntityAndEfMapping — правила сущностей и EF (для write-ветки с БД).
• ADR_SRV_004_AppConfigAndCors — конфигурация по средам и CORS.
• ADR_SRV_005_ImageNormalizationOrthocover — нормализация изображений (orthocover).