Phase 2: share system + analytics feed (backend)

- share_links model/queries; opaque 12-char base62 tokens (PRD §17.1)
- POST /v1/cards/{id}/share — create share link (owner-scoped, modality-validated)
- GET /v1/s/{token} — record modality-attributed event (qr→qr_scan, nfc→nfc_tap)
  and 302-redirect to the profile; unknown/expired → 404
- GET /v1/cards/{id}/share-links — list a card's links
- analytics_events now carry the share_token correlation
- GET /v1/cards/{id}/analytics/feed — chronological event feed (§6.7.2)

6 new integration tests; 73 backend tests total. fmt + clippy clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

cardclaws-backend/crates/cardclaws-db/src/models/analytics.rs

@@ -1,3 +1,4 @@
+use chrono::{DateTime, Utc};
 use serde::Serialize;
 use sqlx::FromRow;
 
@@ -12,3 +13,15 @@ pub struct AnalyticsSummary {
     pub contact_saves: i64,
     pub link_clicks: i64,
 }
+
+/// One row of the chronological event feed (PRD §6.7.2).
+#[derive(Debug, Clone, FromRow, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FeedEvent {
+    pub id: i64,
+    pub event_type: String,
+    pub share_token: Option<String>,
+    pub country: Option<String>,
+    pub city: Option<String>,
+    pub occurred_at: DateTime<Utc>,
+}

cardclaws-backend/crates/cardclaws-db/src/models/mod.rs

@@ -4,4 +4,5 @@
 pub mod analytics;
 pub mod card;
 pub mod session;
+pub mod share_link;
 pub mod user;

cardclaws-backend/crates/cardclaws-db/src/models/share_link.rs

@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::Serialize;
+use sqlx::FromRow;
+use uuid::Uuid;
+
+/// Raw `share_links` row (PRD §17.1). The token is an opaque base62 id; it
+/// encodes nothing and resolves purely via DB lookup.
+#[derive(Debug, Clone, FromRow, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ShareLinkRow {
+    pub token: String,
+    pub card_id: Uuid,
+    pub modality: String,
+    pub campaign: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub expires_at: Option<DateTime<Utc>>,
+}

cardclaws-backend/crates/cardclaws-db/src/queries/analytics.rs

@@ -5,23 +5,26 @@
 
 use uuid::Uuid;
 
-use crate::models::analytics::AnalyticsSummary;
+use crate::models::analytics::{AnalyticsSummary, FeedEvent};
 use crate::Db;
 
 pub struct NewEvent<'a> {
     pub card_id: Uuid,
     pub event_type: &'a str,
+    /// Correlates the event to the share link that produced it (PRD §6.5.2).
+    pub share_token: Option<&'a str>,
     pub ip_hash: Option<&'a str>,
     pub user_agent: Option<&'a str>,
 }
 
 pub async fn insert_event(db: &Db, ev: NewEvent<'_>) -> Result<(), sqlx::Error> {
     sqlx::query(
-        r#"INSERT INTO analytics_events (card_id, event_type, ip_hash, user_agent)
-           VALUES ($1, $2, $3, $4)"#,
+        r#"INSERT INTO analytics_events (card_id, event_type, share_token, ip_hash, user_agent)
+           VALUES ($1, $2, $3, $4, $5)"#,
     )
     .bind(ev.card_id)
     .bind(ev.event_type)
+    .bind(ev.share_token)
     .bind(ev.ip_hash)
     .bind(ev.user_agent)
     .execute(db)
@@ -48,3 +51,18 @@ pub async fn summary(db: &Db, card_id: Uuid) -> Result<AnalyticsSummary, sqlx::E
     .fetch_one(db)
     .await
 }
+
+/// Most recent events for a card, newest first (PRD §6.7.2).
+pub async fn feed(db: &Db, card_id: Uuid, limit: i64) -> Result<Vec<FeedEvent>, sqlx::Error> {
+    sqlx::query_as(
+        r#"SELECT id, event_type, share_token, country, city, occurred_at
+           FROM analytics_events
+           WHERE card_id = $1
+           ORDER BY occurred_at DESC, id DESC
+           LIMIT $2"#,
+    )
+    .bind(card_id)
+    .bind(limit)
+    .fetch_all(db)
+    .await
+}

cardclaws-backend/crates/cardclaws-db/src/queries/mod.rs

@@ -4,4 +4,5 @@
 pub mod analytics;
 pub mod cards;
 pub mod sessions;
+pub mod share;
 pub mod users;

cardclaws-backend/crates/cardclaws-db/src/queries/share.rs

@@ -0,0 +1,52 @@
+//! Share-link queries (PRD §17).
+
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+
+use crate::models::share_link::ShareLinkRow;
+use crate::Db;
+
+pub struct NewShareLink<'a> {
+    pub token: &'a str,
+    pub card_id: Uuid,
+    pub modality: &'a str,
+    pub campaign: Option<&'a str>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+pub async fn insert(db: &Db, new: NewShareLink<'_>) -> Result<ShareLinkRow, sqlx::Error> {
+    sqlx::query_as(
+        r#"
+        INSERT INTO share_links (token, card_id, modality, campaign, expires_at)
+        VALUES ($1, $2, $3, $4, $5)
+        RETURNING token, card_id, modality, campaign, created_at, expires_at
+        "#,
+    )
+    .bind(new.token)
+    .bind(new.card_id)
+    .bind(new.modality)
+    .bind(new.campaign)
+    .bind(new.expires_at)
+    .fetch_one(db)
+    .await
+}
+
+pub async fn find_by_token(db: &Db, token: &str) -> Result<Option<ShareLinkRow>, sqlx::Error> {
+    sqlx::query_as(
+        r#"SELECT token, card_id, modality, campaign, created_at, expires_at
+           FROM share_links WHERE token = $1"#,
+    )
+    .bind(token)
+    .fetch_optional(db)
+    .await
+}
+
+pub async fn list_by_card(db: &Db, card_id: Uuid) -> Result<Vec<ShareLinkRow>, sqlx::Error> {
+    sqlx::query_as(
+        r#"SELECT token, card_id, modality, campaign, created_at, expires_at
+           FROM share_links WHERE card_id = $1 ORDER BY created_at DESC"#,
+    )
+    .bind(card_id)
+    .fetch_all(db)
+    .await
+}