feat: support plane view.

Author: PttCodingMan

backend/app/config.py

@@ -23,6 +23,11 @@ class Settings(BaseSettings):
     # Repo on ghcr.io for the image-tag lookup. Matches docker-compose.yml.
     UPDATE_CHECK_IMAGE: str = "pttcodingman/justwiki/backend"
 
+    # Repeat views by the same user within this window don't re-increment
+    # a page's view_count. Keeps counts meaningful across refreshes / tab
+    # switches without permanently storing per-user reading history.
+    VIEW_DEDUP_MINUTES: int = 30
+
     model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
 
 

backend/app/database.py

@@ -210,6 +210,16 @@
 CREATE INDEX IF NOT EXISTS idx_page_acl_page ON page_acl(page_id);
 CREATE INDEX IF NOT EXISTS idx_page_acl_principal ON page_acl(principal_type, principal_id);
 
+-- Short-lived dedup keys for view_count. Rows are hashes, not user ids,
+-- so a plain DB dump can't be used to reconstruct a reading history.
+CREATE TABLE IF NOT EXISTS view_dedup (
+    dedup_key      TEXT PRIMARY KEY,
+    page_id        INTEGER NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
+    last_viewed_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_view_dedup_last ON view_dedup(last_viewed_at);
+
 """
 
 WELCOME_PAGE_CONTENT_EN = r"""# Welcome to JustWiki

backend/app/routers/pages.py

@@ -1,7 +1,11 @@
+import hashlib
 import json
+import random
 import re
+import time
 import unicodedata
 from fastapi import APIRouter, HTTPException, Depends, Query
+from app.config import settings
 from app.schemas import PageCreate, PageUpdate, PageResponse, PageListResponse, PageMoveRequest
 from app.auth import get_current_user
 from app.database import get_db
@@ -15,6 +19,46 @@
 router = APIRouter(prefix="/api/pages", tags=["pages"])
 
 
+async def _should_count_view(db, user_id: int, page_id: int) -> bool:
+    """Record this view and return True if it should bump view_count.
+
+    Counts at most once per (user, page) per VIEW_DEDUP_MINUTES. Keyed on
+    sha256(user|page|SECRET_KEY) so a plain DB dump doesn't expose reading
+    history — note that an attacker with both the DB and SECRET_KEY can
+    still brute-force the small user_id × page_id space.
+    """
+    cooldown = settings.VIEW_DEDUP_MINUTES * 60
+    now = int(time.time())
+    cutoff = now - cooldown
+    dedup_key = hashlib.sha256(
+        f"u:{user_id}|{page_id}|{settings.SECRET_KEY}".encode()
+    ).hexdigest()
+
+    # Single-statement UPSERT so two concurrent views for the same key can't
+    # both see no row and race on INSERT. The WHERE clause makes the UPDATE
+    # branch a no-op while still inside the cooldown window, so rowcount
+    # cleanly distinguishes "counted" (1) from "deduped" (0).
+    cursor = await db.execute(
+        """
+        INSERT INTO view_dedup (dedup_key, page_id, last_viewed_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(dedup_key) DO UPDATE SET last_viewed_at = excluded.last_viewed_at
+          WHERE view_dedup.last_viewed_at < ?
+        """,
+        (dedup_key, page_id, now, cutoff),
+    )
+    if cursor.rowcount != 1:
+        return False
+
+    # Opportunistic cleanup so the table doesn't grow unbounded. 1% of counted
+    # views prune expired rows — amortises cleanup across traffic, no cron needed.
+    if random.random() < 0.01:
+        await db.execute(
+            "DELETE FROM view_dedup WHERE last_viewed_at < ?", (cutoff,)
+        )
+    return True
+
+
 def _build_id_clause(ids: set[int], column: str = "id") -> tuple[str, list]:
     """Produce a parameterized ``column IN (SELECT value FROM json_each(?))``
     clause plus params.
@@ -276,13 +320,15 @@ async def get_page(slug: str, user=Depends(get_current_user)):
         # the existence of restricted pages.
         raise HTTPException(status_code=404, detail="Page not found")
 
-    # Increment view count (does not bump the content version)
-    await db.execute(
-        "UPDATE pages SET view_count = view_count + 1 WHERE slug = ?", (slug,)
-    )
+    # Increment view count (does not bump the content version), deduplicated
+    # so refreshes / tab-switches by the same user don't inflate the count.
+    if await _should_count_view(db, user["id"], page["id"]):
+        await db.execute(
+            "UPDATE pages SET view_count = view_count + 1 WHERE id = ?", (page["id"],)
+        )
+        page["view_count"] += 1
     await db.commit()
 
-    page["view_count"] += 1
     page["effective_permission"] = permission
     return page
 

backend/tests/test_optimistic_lock.py

@@ -103,4 +103,5 @@ async def test_get_page_does_not_bump_version(auth_client):
         res = await auth_client.get("/api/pages/lock-view")
         assert res.status_code == 200
     assert res.json()["version"] == 1
-    assert res.json()["view_count"] == 3
+    # View dedup collapses the 3 refreshes by the same user into one count.
+    assert res.json()["view_count"] == 1

backend/tests/test_public_page.py

@@ -237,21 +237,17 @@ async def test_view_count_unchanged_by_public_endpoint(auth_client, client):
     })
     await auth_client.put("/api/pages/public-vc", json={"is_public": True})
 
-    # Reset view count to 0 (it may have been incremented by the PUT flow? no — only GET bumps)
-    # Hit the public endpoint several times
+    # Snapshot the current view_count via one authed GET (dedup makes
+    # subsequent same-user GETs inert inside the cooldown window).
+    before = (await auth_client.get("/api/pages/public-vc")).json()["view_count"]
+
+    # Public reads must not touch view_count.
     for _ in range(5):
         res = await client.get("/api/public/pages/public-vc")
         assert res.status_code == 200
 
-    # Look at the raw page row (auth_client GETs would bump it further, so query DB)
-    # Use a dedicated authed GET that we know bumps by 1 and reason about the delta.
-    res = await auth_client.get("/api/pages/public-vc")
-    first = res.json()["view_count"]
-    res = await auth_client.get("/api/pages/public-vc")
-    second = res.json()["view_count"]
-    # Public reads should not have bumped view_count, so two sequential authed GETs
-    # must differ by exactly 1.
-    assert second - first == 1
+    after = (await auth_client.get("/api/pages/public-vc")).json()["view_count"]
+    assert after == before
 
 
 @pytest.mark.asyncio

backend/tests/test_view_count_dedup.py

@@ -0,0 +1,97 @@
+import pytest
+
+from app.database import get_db
+
+
+@pytest.mark.asyncio
+async def test_same_user_repeat_does_not_increment(auth_client):
+    await auth_client.post("/api/pages", json={
+        "title": "View Dedup Same User",
+        "content_md": "x",
+        "slug": "view-dedup-same",
+    })
+
+    first = await auth_client.get("/api/pages/view-dedup-same")
+    assert first.status_code == 200
+    count_after_first = first.json()["view_count"]
+
+    second = await auth_client.get("/api/pages/view-dedup-same")
+    assert second.status_code == 200
+    assert second.json()["view_count"] == count_after_first
+
+    third = await auth_client.get("/api/pages/view-dedup-same")
+    assert third.json()["view_count"] == count_after_first
+
+
+@pytest.mark.asyncio
+async def test_different_users_each_count(auth_client, admin_client):
+    await auth_client.post("/api/pages", json={
+        "title": "View Dedup Two Users",
+        "content_md": "x",
+        "slug": "view-dedup-two-users",
+    })
+
+    r1 = await auth_client.get("/api/pages/view-dedup-two-users")
+    first_count = r1.json()["view_count"]
+
+    r2 = await admin_client.get("/api/pages/view-dedup-two-users")
+    assert r2.json()["view_count"] == first_count + 1
+
+    # Each user's refresh still dedups against their own slot.
+    r1b = await auth_client.get("/api/pages/view-dedup-two-users")
+    assert r1b.json()["view_count"] == first_count + 1
+
+
+@pytest.mark.asyncio
+async def test_expired_dedup_counts_again(auth_client):
+    await auth_client.post("/api/pages", json={
+        "title": "View Dedup Expired",
+        "content_md": "x",
+        "slug": "view-dedup-expired",
+    })
+
+    r1 = await auth_client.get("/api/pages/view-dedup-expired")
+    count_after_first = r1.json()["view_count"]
+
+    r2 = await auth_client.get("/api/pages/view-dedup-expired")
+    assert r2.json()["view_count"] == count_after_first
+
+    # Backdate every dedup row for this page past the cooldown.
+    db = await get_db()
+    page_rows = await db.execute_fetchall(
+        "SELECT id FROM pages WHERE slug = ?", ("view-dedup-expired",)
+    )
+    page_id = page_rows[0]["id"]
+    await db.execute(
+        "UPDATE view_dedup SET last_viewed_at = 0 WHERE page_id = ?", (page_id,)
+    )
+    await db.commit()
+
+    r3 = await auth_client.get("/api/pages/view-dedup-expired")
+    assert r3.json()["view_count"] == count_after_first + 1
+
+
+@pytest.mark.asyncio
+async def test_dedup_row_is_hashed(auth_client):
+    """Row stores a sha256 hex digest, not a raw (user, page) pair."""
+    await auth_client.post("/api/pages", json={
+        "title": "View Dedup Hash",
+        "content_md": "x",
+        "slug": "view-dedup-hash",
+    })
+    await auth_client.get("/api/pages/view-dedup-hash")
+
+    db = await get_db()
+    page_rows = await db.execute_fetchall(
+        "SELECT id FROM pages WHERE slug = ?", ("view-dedup-hash",)
+    )
+    page_id = page_rows[0]["id"]
+    rows = await db.execute_fetchall(
+        "SELECT dedup_key FROM view_dedup WHERE page_id = ?", (page_id,)
+    )
+    assert rows, "expected a dedup row after first view"
+    key = rows[0]["dedup_key"]
+    assert len(key) == 64
+    assert all(c in "0123456789abcdef" for c in key)
+    # The structured plaintext form must never hit disk.
+    assert "|" not in key and "u:" not in key

frontend/src/pages/GraphView.jsx

@@ -53,6 +53,31 @@ export default function GraphView() {
     return () => ro.disconnect()
   }, [graphData])
 
+  // Bump 3D zoom sensitivity. TrackballControls ships with zoomSpeed=1.2
+  // which feels sluggish on typical trackpads. The graph ref is populated
+  // after the Suspense-lazy component mounts, so retry briefly until the
+  // controls handle is available.
+  useEffect(() => {
+    if (mode !== '3d' || !graphData) return
+    let cancelled = false
+    const apply = () => {
+      if (cancelled) return
+      const g = graphRef.current
+      if (g && typeof g.controls === 'function') {
+        const c = g.controls()
+        if (c) {
+          c.zoomSpeed = 4
+          return
+        }
+      }
+      setTimeout(apply, 50)
+    }
+    apply()
+    return () => {
+      cancelled = true
+    }
+  }, [mode, graphData])
+
   // Pre-compute link counts so nodes with more connections can be rendered
   // larger. react-force-graph mutates nodes/links (replaces string IDs with
   // object refs), so we derive a stable degree count first.