till/cards
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Phase 9l: Image-Occlusion als 4. MVP-CardType

Browse source 
Domain: CardTypeSchema öffnet 'image-occlusion'. Neues Modul
@cards/domain/src/image-occlusion.ts mit MaskRegionSchema (zod-strict,
0..1-relative Coords + optionalem Label, max 100 Regionen),
parseMaskRegions (parse + sort-by-id), maskRegionCount, maskForSubIndex.

Field-Schema (cards.fields):
  image_ref:    string  — media_files.id (Phase 9k Storage)
  mask_regions: string  — JSON-Array<MaskRegion>
  note?:        string  — optionale Bildunterschrift

subIndexCount('image-occlusion') wirft analog zu cloze, weil die
Anzahl text-abhängig ist. Card-POST-Handler ruft maskRegionCount
und lehnt 422 ab, wenn das Mask-Array leer / kaputt ist (vor dem
Deck-Lookup).

UI-Komponenten:
  - ImageOcclusionEditor: File-Picker → uploadMedia (Phase 9k),
    SVG-Overlay über das Bild, Drag-to-create-Rectangle (mind. 2%
    Größe, sonst Klick-Filter), Mask-Liste mit Label-Input und
    Delete-Button. Pointer-Events für Touch-Mobile-Support.
  - ImageOcclusionView (Study-Render): Bild + SVG-Overlay; aktive
    Mask ist im Prompt opake schwarz, im Reveal transparent grün
    mit Label-Text; andere Masken bleiben dezent gelb-durchsichtig
    als Lern-Hinweis.

/cards/new + /cards/[id]/edit: Type-Picker um Image-Occlusion
erweitert, Branch-Logik schaltet auf den Editor um. canSave-
Validierung: imageRef gesetzt + mind. 1 Mask. /study/[deckId]
nutzt ImageOcclusionView statt Markdown-Render. /decks/[id]-Liste
zeigt "🖼 image-occlusion · <ref-prefix>" statt "(leer) → (leer)".

i18n DE/EN: type_image_occlusion, toast_image_occlusion,
image_occlusion-Namespace (image_label, draw_hint,
label_placeholder, delete_mask, no_image_selected, etc.).

Tests: 11 neue Domain-Tests für MaskRegion-Schema/Parse/Mapping
(66 Domain ges.), 3 neue API-Tests für 422-Branches und
Validation-vor-Deck-Lookup-Pfad (56 API ges.). 129 Tests grün
ges. (66 + 56 + 7), type-check 384 files 0 errors, prod-Build
sauber.

E2E-Smoke: Image-Occlusion-Card mit 2 Masken (image_ref auf das
Sprint-9k-Test-PNG) → API legt content_hash + 2 Reviews mit
sub_index 0+1 an, reviews/due returnt sie korrekt typisiert.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Till JS 2026-05-08 18:50:45 +02:00
parent c9eb0a6f80
commit 39b1791fb9
17 changed files with 682 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

18
apps/api/src/routes/cards.ts
View file

@ -5,6 +5,7 @@ import {
CardCreateSchema,
CardUpdateSchema,
cardContentHash,
maskRegionCount,
newReview,
subIndexCount,
subIndexCountForCloze,
@ -40,9 +41,9 @@ export function cardsRouter(deps: CardsDeps = {}): Hono<{ Variables: AuthVars }>
}
const userId = c.get('userId');
// Cloze: Sub-Index-Anzahl hängt vom Cluster-Markup im Text ab.
// Eine Cloze-Karte ohne `{{cN::…}}` ist sinnlos — vor dem Deck-Lookup
// ablehnen, damit Validation-Errors konsistent 422 statt 404 sind.
// Text-abhängige Sub-Index-Counts (Cloze, Image-Occlusion) vor
// dem Deck-Lookup auflösen — Validation-Errors bleiben 422 statt
// versehentlich auf 404 zu fallen.
let count: number;
if (parsed.data.type === 'cloze') {
count = subIndexCountForCloze(parsed.data.fields.text ?? '');
@ -52,6 +53,17 @@ export function cardsRouter(deps: CardsDeps = {}): Hono<{ Variables: AuthVars }>
422
);
}
} else if (parsed.data.type === 'image-occlusion') {
count = maskRegionCount(parsed.data.fields.mask_regions ?? '');
if (count === 0) {
return c.json(
{
error: 'invalid_input',
issues: ['image-occlusion.mask_regions must be a JSON array with >=1 valid region'],
},
422
);
}
} else {
count = subIndexCount(parsed.data.type);
}

55
apps/api/tests/cards.test.ts
View file

@ -68,13 +68,64 @@ describe('cardsRouter — Input-Validation', () => {
headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
body: JSON.stringify({
deck_id: 'd-1',
type: 'image-occlusion',
fields: { image_ref: 'x', mask_regions: 'y' },
type: 'audio',
fields: { audio_ref: 'x' },
}),
});
expect(res.status).toBe(422);
});
it('POST mit image-occlusion ohne mask_regions ist 422', async () => {
const { app } = buildApp();
const res = await app.request('/api/v1/cards', {
method: 'POST',
headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
body: JSON.stringify({
deck_id: 'd-1',
type: 'image-occlusion',
fields: { image_ref: 'm1' },
}),
});
expect(res.status).toBe(422);
});
it('POST mit image-occlusion mit kaputtem mask_regions ist 422', async () => {
const { app } = buildApp();
const res = await app.request('/api/v1/cards', {
method: 'POST',
headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
body: JSON.stringify({
deck_id: 'd-1',
type: 'image-occlusion',
fields: { image_ref: 'm1', mask_regions: 'not json' },
}),
});
expect(res.status).toBe(422);
const body = (await res.json()) as { issues: string[] };
expect(body.issues[0]).toMatch(/mask_regions/);
});
it('POST mit gültiger image-occlusion erreicht Deck-Lookup (404 bei stub)', async () => {
const { app } = buildApp();
const res = await app.request('/api/v1/cards', {
method: 'POST',
headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
body: JSON.stringify({
deck_id: 'd-1',
type: 'image-occlusion',
fields: {
image_ref: 'm1',
mask_regions: JSON.stringify([
{ id: 'r1', x: 0.1, y: 0.1, w: 0.1, h: 0.1 },
]),
},
}),
});
expect(res.status).toBe(404);
const body = (await res.json()) as { error: string };
expect(body.error).toBe('deck_not_found');
});
it('POST mit cloze-Card ohne text-Feld ist 422', async () => {
const { app } = buildApp();
const res = await app.request('/api/v1/cards', {