osdb-1-claude-opusplan/docs/planning/specs/04-fruit-publications.md

Spec: 04 · Fruit Publications

Taiga Story: #4 · 04-fruit-publications Status: Ready Branch: feature/04-fruit-publications Depends on: 02-manage-fruits (fruits table)

---

1. Goal

Maintainers can manage publications (books, catalogues) that document fruits. Each publication has a cover image, linked fruits, linked PDFs per fruit, and linked fruit images from the publication. Fruit detail page shows descriptions and publication images.

---

2. Background / Scope / Context / Constraints

• osdb_pub_id is the unique external identifier (label: "OSDB Kürzel").
• Cover image stored as BYTEA in publications.image_data.
• PDF stored as BYTEA in publication_descriptions.pdf_data (one PDF per fruit per publication).
• Fruit images from publications stored in publication_fruit_images (BYTEA); image_type hardcoded to 'fruit', cannot be changed.
• On fruit detail page: show description list only if at least one description exists; link text = publication title; link opens PDF.
• On fruit detail page: show publication fruit images labeled "Publication title · Author".
• Mouseclick on cover image → overlay/drawer with full-size image.

---

3. Necessary Refactorings

• fruit_images.image_type already defined in story #2 — no changes.
• thumbnail_data column on publication_fruit_images deferred to story #7 migration.

---

4. Related Data Model

-- Migration: 000003_create_publications.up.sql

CREATE TABLE publications (
  id           SERIAL PRIMARY KEY,
  title        VARCHAR(255) NOT NULL,
  author       VARCHAR(255),
  osdb_pub_id  VARCHAR(50)  NOT NULL UNIQUE,
  image_data   BYTEA,
  created_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
  updated_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW()
);

CREATE TABLE publication_fruits (
  publication_id INTEGER NOT NULL REFERENCES publications(id) ON DELETE CASCADE,
  fruit_id       INTEGER NOT NULL REFERENCES fruits(id) ON DELETE CASCADE,
  PRIMARY KEY (publication_id, fruit_id)
);

CREATE TABLE publication_descriptions (
  id             SERIAL PRIMARY KEY,
  publication_id INTEGER NOT NULL REFERENCES publications(id) ON DELETE CASCADE,
  fruit_id       INTEGER NOT NULL REFERENCES fruits(id) ON DELETE CASCADE,
  pdf_data       BYTEA   NOT NULL,
  created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE (publication_id, fruit_id)
);

CREATE TABLE publication_fruit_images (
  id             SERIAL PRIMARY KEY,
  publication_id INTEGER      NOT NULL REFERENCES publications(id) ON DELETE CASCADE,
  fruit_id       INTEGER      NOT NULL REFERENCES fruits(id) ON DELETE CASCADE,
  filename       VARCHAR(255),
  data           BYTEA        NOT NULL,
  image_type     VARCHAR(20)  NOT NULL DEFAULT 'fruit',  -- hardcoded
  created_at     TIMESTAMPTZ  NOT NULL DEFAULT NOW()
);
-- Note: thumbnail_data column added in story #07 migration

---

5. Affected Places / Related Components

Backend

File	Purpose
backend/internal/domain/publication.go	Publication, PublicationDescription, PublicationFruitImage structs
backend/internal/repository/publication_repo.go	DB queries
backend/internal/handler/publication_handler.go	Echo handlers
backend/cmd/server/router.go	Register /api/v1/publications routes
migrations/000003_create_publications.up.sql	Schema above
migrations/000003_create_publications.down.sql	DROP TABLEs

API Endpoints

Method	Path	Description
GET	/api/v1/publications	List
POST	/api/v1/publications	Create
GET	/api/v1/publications/:id	Get (with linked fruits list)
PUT	/api/v1/publications/:id	Update
DELETE	/api/v1/publications/:id	Delete
POST	/api/v1/publications/:id/image	Upload cover image
GET	/api/v1/publications/:id/image	Serve cover image
DELETE	/api/v1/publications/:id/image	Delete cover image
GET	/api/v1/publications/:id/fruits	List linked fruits
POST	/api/v1/publications/:id/fruits	Link a fruit
DELETE	/api/v1/publications/:id/fruits/:fruitId	Unlink a fruit
GET	/api/v1/publications/:id/descriptions	List descriptions (fruit + link metadata)
POST	/api/v1/publications/:id/descriptions	Upload PDF description (body: fruitId + PDF)
GET	/api/v1/publications/:id/descriptions/:descId	Serve PDF
DELETE	/api/v1/publications/:id/descriptions/:descId	Delete
GET	/api/v1/publications/:id/fruit-images	List pub fruit images
POST	/api/v1/publications/:id/fruit-images	Upload fruit image (fruitId + image)
GET	/api/v1/publications/:id/fruit-images/:imgId	Serve image
DELETE	/api/v1/publications/:id/fruit-images/:imgId	Delete
GET	/api/v1/fruits/:id/descriptions	All descriptions for a fruit (across publications)
GET	/api/v1/fruits/:id/publication-images	All pub images for a fruit

Frontend

File	Purpose
frontend/src/api/publications.ts	API wrapper
frontend/src/stores/publicationStore.ts	Pinia store
frontend/src/views/PublicationList.vue	List + link to detail
frontend/src/views/PublicationDetail.vue	Full management UI
frontend/src/components/ImageOverlayDrawer.vue	Full-size image overlay on click
frontend/src/views/FruitDetail.vue	Extended: descriptions section + pub images section
frontend/src/router/index.ts	Add /publications, /publications/:id

---

6. Out of Scope

• Bulk import from XML (story #5)
• Thumbnail generation (story #7)
• Authentication guards (story #8)

---

7. Verification

Check	Expected
Create publication with duplicate osdb_pub_id	409 Conflict
Upload cover image → serve back → correct bytes	Pass
Link fruit to publication → appears in GET /publications/:id/fruits	Pass
Upload PDF description → GET description → Content-Type: application/pdf	Pass
Fruit detail page: no descriptions → section hidden	Pass
Fruit detail page: 1+ description → links visible	Pass
Click cover image thumbnail → overlay opens full-size	Pass
Pub fruit images on fruit detail labeled correctly	Publication title · Author shown
go test ./...	Green
npm run test	Green

---

8. Open Questions

#	Question	Impact
1	Is one PDF per (publication, fruit) pair enforced (UNIQUE) or allow multiples?	Schema + UI
2	Can a fruit image exist in a publication without the fruit being linked via publication_fruits?	Data integrity
3	Listing publications: include fruit count or just metadata?	API response shape
4	PDF viewer: open in new tab or inline browser PDF viewer?	UX