feat(db): add vocabulary/term repository with multilingual labels

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

crates/db/src/lib.rs

@@ -1,6 +1,7 @@
 //! Database access. All SQL lives in this crate.
 
 pub mod audit;
+pub mod vocab;
 
 use sqlx::postgres::{PgPool, PgPoolOptions};
 

crates/db/src/vocab.rs

@@ -0,0 +1,141 @@
+//! Controlled vocabularies and terms.
+
+use domain::{LocalizedLabel, NewTerm, Term, TermId, TermRef, Vocabulary, VocabularyId};
+use sqlx::Row;
+
+/// Labels aggregated per row as JSON, to read a term and its labels in one query.
+const LABELS_JSON: &str = "COALESCE(json_agg(json_build_object('lang', tl.lang, 'label', tl.label) \
+     ORDER BY tl.lang) FILTER (WHERE tl.term_id IS NOT NULL), '[]'::json)";
+
+/// Create a vocabulary with the given key.
+pub async fn create_vocabulary<'e, E>(executor: E, key: &str) -> Result<Vocabulary, sqlx::Error>
+where
+    E: sqlx::PgExecutor<'e>,
+{
+    let id = VocabularyId::new();
+
+    sqlx::query("INSERT INTO vocabulary (id, key) VALUES ($1, $2)")
+        .bind(id.to_uuid())
+        .bind(key)
+        .execute(executor)
+        .await?;
+
+    Ok(Vocabulary {
+        id,
+        key: key.to_owned(),
+    })
+}
+
+/// Look up a vocabulary by its key.
+pub async fn vocabulary_by_key<'e, E>(
+    executor: E,
+    key: &str,
+) -> Result<Option<Vocabulary>, sqlx::Error>
+where
+    E: sqlx::PgExecutor<'e>,
+{
+    let row = sqlx::query("SELECT id, key FROM vocabulary WHERE key = $1")
+        .bind(key)
+        .fetch_optional(executor)
+        .await?;
+
+    Ok(row.map(|r| Vocabulary {
+        id: VocabularyId::from_uuid(r.get("id")),
+        key: r.get("key"),
+    }))
+}
+
+/// Insert a term and its labels. Multiple statements — pass a transaction
+/// connection (`&mut *tx`) so the term and its labels commit atomically.
+pub async fn add_term(conn: &mut sqlx::PgConnection, new: &NewTerm) -> Result<TermId, sqlx::Error> {
+    let id = TermId::new();
+
+    sqlx::query("INSERT INTO term (id, vocabulary_id, external_uri) VALUES ($1, $2, $3)")
+        .bind(id.to_uuid())
+        .bind(new.vocabulary_id.to_uuid())
+        .bind(new.external_uri.as_deref())
+        .execute(&mut *conn)
+        .await?;
+
+    for label in &new.labels {
+        sqlx::query("INSERT INTO term_label (term_id, lang, label) VALUES ($1, $2, $3)")
+            .bind(id.to_uuid())
+            .bind(&label.lang)
+            .bind(&label.label)
+            .execute(&mut *conn)
+            .await?;
+    }
+
+    Ok(id)
+}
+
+/// Fetch one term (with its labels).
+pub async fn term_by_id<'e, E>(executor: E, id: TermId) -> Result<Option<Term>, sqlx::Error>
+where
+    E: sqlx::PgExecutor<'e>,
+{
+    let sql = format!(
+        "SELECT t.id, t.vocabulary_id, t.external_uri, {LABELS_JSON} AS labels \
+         FROM term t LEFT JOIN term_label tl ON tl.term_id = t.id \
+         WHERE t.id = $1 GROUP BY t.id"
+    );
+
+    let row = sqlx::query(&sql)
+        .bind(id.to_uuid())
+        .fetch_optional(executor)
+        .await?;
+
+    row.map(map_term).transpose()
+}
+
+/// List all terms in a vocabulary (with labels), ordered by id.
+pub async fn list_terms<'e, E>(
+    executor: E,
+    vocabulary_id: VocabularyId,
+) -> Result<Vec<Term>, sqlx::Error>
+where
+    E: sqlx::PgExecutor<'e>,
+{
+    let sql = format!(
+        "SELECT t.id, t.vocabulary_id, t.external_uri, {LABELS_JSON} AS labels \
+         FROM term t LEFT JOIN term_label tl ON tl.term_id = t.id \
+         WHERE t.vocabulary_id = $1 GROUP BY t.id ORDER BY t.id"
+    );
+
+    let rows = sqlx::query(&sql)
+        .bind(vocabulary_id.to_uuid())
+        .fetch_all(executor)
+        .await?;
+
+    rows.into_iter().map(map_term).collect()
+}
+
+/// Resolve a term to a [`TermRef`], confirming it belongs to `vocabulary_id`.
+pub async fn resolve_term<'e, E>(
+    executor: E,
+    vocabulary_id: VocabularyId,
+    term_id: TermId,
+) -> Result<Option<TermRef>, sqlx::Error>
+where
+    E: sqlx::PgExecutor<'e>,
+{
+    let found =
+        sqlx::query_scalar::<_, i32>("SELECT 1 FROM term WHERE id = $1 AND vocabulary_id = $2")
+            .bind(term_id.to_uuid())
+            .bind(vocabulary_id.to_uuid())
+            .fetch_optional(executor)
+            .await?;
+
+    Ok(found.map(|_| TermRef::new(term_id, vocabulary_id)))
+}
+
+fn map_term(row: sqlx::postgres::PgRow) -> Result<Term, sqlx::Error> {
+    let labels: sqlx::types::Json<Vec<LocalizedLabel>> = row.try_get("labels")?;
+
+    Ok(Term {
+        id: TermId::from_uuid(row.try_get("id")?),
+        vocabulary_id: VocabularyId::from_uuid(row.try_get("vocabulary_id")?),
+        external_uri: row.try_get("external_uri")?,
+        labels: labels.0,
+    })
+}

crates/db/tests/vocab.rs

@@ -0,0 +1,114 @@
+use db::{Db, vocab};
+use domain::{LocalizedLabel, NewTerm};
+use sqlx::PgPool;
+
+#[sqlx::test]
+async fn vocabulary_create_and_lookup(pool: PgPool) {
+    let db = Db::from_pool(pool);
+    let v = vocab::create_vocabulary(db.pool(), "material")
+        .await
+        .unwrap();
+
+    let found = vocab::vocabulary_by_key(db.pool(), "material")
+        .await
+        .unwrap()
+        .unwrap();
+
+    assert_eq!(found.id, v.id);
+    assert_eq!(found.key, "material");
+    assert!(
+        vocab::vocabulary_by_key(db.pool(), "nope")
+            .await
+            .unwrap()
+            .is_none()
+    );
+}
+
+#[sqlx::test]
+async fn term_with_multilingual_labels_round_trips(pool: PgPool) {
+    let db = Db::from_pool(pool);
+    let v = vocab::create_vocabulary(db.pool(), "material")
+        .await
+        .unwrap();
+
+    let mut tx = db.pool().begin().await.unwrap();
+    let term_id = vocab::add_term(
+        &mut *tx,
+        &NewTerm {
+            vocabulary_id: v.id,
+            external_uri: Some("http://vocab.getty.edu/aat/300011914".into()),
+            labels: vec![
+                LocalizedLabel {
+                    lang: "sv".into(),
+                    label: "trä".into(),
+                },
+                LocalizedLabel {
+                    lang: "en".into(),
+                    label: "wood".into(),
+                },
+            ],
+        },
+    )
+    .await
+    .unwrap();
+    tx.commit().await.unwrap();
+
+    let term = vocab::term_by_id(db.pool(), term_id)
+        .await
+        .unwrap()
+        .unwrap();
+
+    assert_eq!(term.vocabulary_id, v.id);
+    assert_eq!(
+        term.external_uri.as_deref(),
+        Some("http://vocab.getty.edu/aat/300011914")
+    );
+    assert_eq!(term.labels.len(), 2);
+    assert_eq!(domain::pick_label(&term.labels, "sv", "en"), Some("trä"));
+    assert_eq!(domain::pick_label(&term.labels, "de", "en"), Some("wood"));
+
+    let listed = vocab::list_terms(db.pool(), v.id).await.unwrap();
+
+    assert_eq!(listed.len(), 1);
+    assert_eq!(listed[0].id, term_id);
+}
+
+#[sqlx::test]
+async fn resolve_term_checks_vocabulary_membership(pool: PgPool) {
+    let db = Db::from_pool(pool);
+    let material = vocab::create_vocabulary(db.pool(), "material")
+        .await
+        .unwrap();
+    let technique = vocab::create_vocabulary(db.pool(), "technique")
+        .await
+        .unwrap();
+
+    let mut tx = db.pool().begin().await.unwrap();
+    let term_id = vocab::add_term(
+        &mut *tx,
+        &NewTerm {
+            vocabulary_id: material.id,
+            external_uri: None,
+            labels: vec![LocalizedLabel {
+                lang: "en".into(),
+                label: "wood".into(),
+            }],
+        },
+    )
+    .await
+    .unwrap();
+    tx.commit().await.unwrap();
+
+    assert!(
+        vocab::resolve_term(db.pool(), material.id, term_id)
+            .await
+            .unwrap()
+            .is_some()
+    );
+    assert!(
+        vocab::resolve_term(db.pool(), technique.id, term_id)
+            .await
+            .unwrap()
+            .is_none()
+    );
+}