test: publish project tests and ignore rules

Restore root metadata, publish test sources and test requirements; exclude local guides, reports, caches, benchmarks and snapshots.

.gitignore

@@ -0,0 +1,16 @@
+data/fulltext/
+data/production-snapshot/
+*.sqlite3
+*.sqlite3.*
+*.tmp
+*.bak
+*.before-rebuild
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.venv/
+env/
+tests/benchmark-results.json
+AGENTS.md
+TESTING.md

ocr_release.py

@@ -0,0 +1,266 @@
+"""Strict, startup-pinned OCR text/index releases. No network, pointers or deletion."""
+from __future__ import annotations
+
+from collections import defaultdict
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import shutil
+import sqlite3
+import tempfile
+import unicodedata
+
+
+BUCKET = "vomebook/ccrd-index"
+TOKENIZER = "cjk-bigram-boundary-fts5-v6-snippet-anchors"
+SOURCE = "OCR"
+SOURCE_NAME = "OCR成果"
+
+
+def canonical(value) -> bytes:
+    return (json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False) + "\n").encode()
+
+
+def digest(value) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def sha(value) -> str:
+    if not isinstance(value, str) or not re.fullmatch(r"[0-9a-f]{64}", value):
+        raise ValueError("invalid release SHA-256")
+    return value
+
+
+def safe_path(value: str) -> str:
+    if (not isinstance(value, str) or not value or value.startswith("/") or "\\" in value
+            or any(part in {"", ".", ".."} for part in value.split("/"))
+            or any(ord(char) < 32 for char in value)):
+        raise ValueError("invalid release relative path")
+    return value
+
+
+def read_resource(root: Path, ref: dict) -> bytes:
+    if not isinstance(ref, dict) or ref.get("bucket") != BUCKET:
+        raise ValueError("wrong OCR release bucket")
+    path = safe_path(ref.get("path"))
+    if not path.startswith(("text/objects/", "text/exports/", "indexes/ocr/")):
+        raise ValueError("unmanaged OCR resource path")
+    expected = sha(ref.get("sha256"))
+    size = ref.get("bytes")
+    if type(size) is not int or size < 1:
+        raise ValueError("invalid OCR resource size")
+    root = root.resolve()
+    target = (root / path).resolve()
+    if root not in target.parents or not target.is_file():
+        raise ValueError("missing OCR release resource or path escape")
+    raw = target.read_bytes()
+    if len(raw) != size or digest(raw) != expected:
+        raise ValueError("OCR release resource checksum mismatch")
+    return raw
+
+
+def export_record(root: Path, ref: dict) -> tuple[dict, dict]:
+    export = json.loads(read_resource(root, ref))
+    if (export.get("kind") != "ccrd-ocr-text-export" or export.get("version") != 1
+            or export.get("complete") is not True or export.get("recipe") != "ocr-plain-utf8-pages-v1"):
+        raise ValueError("unsupported OCR export schema")
+    if not re.fullmatch(r"OCR:[1-9][0-9]*", str(export.get("doc_id", ""))) or int(export["doc_id"].split(":")[1]) >= 1 << 63:
+        raise ValueError("invalid OCR document identity")
+    repo, original = export.get("origin_repo"), safe_path(export.get("origin_rel_path"))
+    if not isinstance(repo, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*/[A-Za-z0-9][A-Za-z0-9_.-]*", repo):
+        raise ValueError("invalid OCR origin repository")
+    if not re.fullmatch(r"[0-9a-f]{40}", str(export.get("origin_revision", ""))):
+        raise ValueError("OCR origin must be commit-pinned")
+    readable = safe_path(export.get("readable_rel_path"))
+    expected_path = repo + "/" + str(PurePosixPath(original).with_suffix(".txt"))
+    if readable != expected_path:
+        raise ValueError("OCR readable path does not preserve its origin")
+    raw = read_resource(root, export.get("text"))
+    body = raw.decode("utf-8", errors="strict")
+    if body.startswith("\ufeff"):
+        raise ValueError("plain OCR export must not hide a BOM in its indexed text")
+    identity = {key: export[key] for key in ("recipe", "origin_repo", "origin_rel_path", "origin_revision",
+                "source_sha256", "doc_id", "text_generation", "txt_sha256")}
+    for field in ("source_sha256", "text_generation", "txt_sha256", "generation", "book_id"):
+        sha(export.get(field))
+    generation = digest(canonical(identity).rstrip(b"\n"))
+    if (generation != export["generation"] or digest(raw) != export["txt_sha256"]
+            or export["book_id"] != digest((repo + "\0" + original).encode())):
+        raise ValueError("OCR export generation mismatch")
+    pages, count = export.get("pages"), export.get("page_count")
+    if type(count) is not int or count < 1 or not isinstance(pages, list) or len(pages) != count:
+        raise ValueError("OCR export is missing pages")
+    if export.get("offset_unit") != "unicode-codepoint" or export.get("page_separator") != "\n\n":
+        raise ValueError("unsupported page offset recipe")
+    cursor, reviewed = 0, 0
+    for number, page in enumerate(pages, 1):
+        start, end = page.get("start"), page.get("end")
+        if (page.get("page") != number or type(start) is not int or type(end) is not int
+                or start != cursor or not start <= end <= len(body)):
+            raise ValueError("OCR page order/offset mismatch")
+        sha(page.get("text_generation"))
+        if digest(body[start:end].encode()) != sha(page.get("text_sha256")):
+            raise ValueError("OCR page text digest mismatch")
+        if page.get("quality") not in {"unreviewed", "partially-reviewed", "accepted"}:
+            raise ValueError("invalid OCR page quality")
+        reviewed += page["quality"] != "unreviewed"
+        cursor = end
+        if number < count:
+            if body[cursor:cursor + 2] != "\n\n":
+                raise ValueError("OCR page separator mismatch")
+            cursor += 2
+    if cursor != len(body) or export.get("accepted_pages") != reviewed or export.get("quality") != ("partially-reviewed" if reviewed else "unreviewed"):
+        raise ValueError("OCR whole-book coverage/quality mismatch")
+    resources = export.get("retained_reader_resources")
+    if not isinstance(resources, list) or not resources:
+        raise ValueError("OCR provenance retention references are missing")
+    for resource in resources:
+        if resource.get("bucket") not in {"vomebook/reader-assets-v2", "vomebook/pdf-pages-v2", "melsm/pdf-archive-v2"}:
+            raise ValueError("unknown retained Reader bucket")
+        safe_path(resource.get("path")); sha(resource.get("sha256"))
+        if type(resource.get("bytes")) is not int or resource["bytes"] < 1:
+            raise ValueError("invalid retained Reader resource")
+    path = PurePosixPath(readable)
+    record = {"doc_id": export["doc_id"], "source": SOURCE, "source_name": SOURCE_NAME,
+              "display_name": path.stem, "display_dirs": list(path.parts[:-1]), "display_rel_path": readable,
+              "extension": "txt", "size": len(raw), "has_preview": True, "has_fulltext": True,
+              "storage_root": ".", "storage_rel_path": export["text"]["path"],
+              "text_generation": export["text_generation"], "text_quality": export["quality"]}
+    return record, export
+
+
+def directory_payloads(records: list[dict]) -> tuple[list[dict], dict]:
+    browser = defaultdict(lambda: {"folders": [], "files": []})
+    counts, direct = defaultdict(int), defaultdict(list)
+    children = defaultdict(set)
+    for record in records:
+        parts = record["display_dirs"]
+        for depth in range(len(parts) + 1):
+            path = "/".join(parts[:depth]); counts[path] += 1
+            if depth < len(parts): children[path].add(parts[depth])
+        direct["/".join(parts)].append(record)
+    for path in counts:
+        browser[path]["folders"] = [{"name": name, "path": (path + "/" if path else "") + name,
+                                      "count": counts[(path + "/" if path else "") + name]} for name in sorted(children[path])]
+        browser[path]["files"] = [{"name": item["display_name"], "ext": "txt", "size": item["size"],
+                                    "doc_id": item["doc_id"]} for item in sorted(direct[path], key=lambda item: (item["display_name"], item["doc_id"]))]
+    def node(name, path):
+        return {"name": name, "path": path, "count": counts[path], "hasDirectFiles": bool(direct[path]),
+                "hasChildren": bool(children[path]), "showSelfToggle": bool(path and direct[path] and children[path]),
+                "children": [node(child, (path + "/" if path else "") + child) for child in sorted(children[path])]}
+    return [node(SOURCE_NAME, "")], dict(browser)
+
+
+def zip_member(record: dict) -> str:
+    """Keep legal origin hierarchy; bound non-portable components deterministically."""
+    replacements = {":": "：", "*": "＊", "?": "？", '"': "＂", "<": "＜", ">": "＞", "|": "｜", "\\": "＼"}
+    def component(original):
+        value = re.sub(r'[:*?"<>|\\\x00-\x1f]', lambda match: replacements.get(match[0], "_"), original).rstrip(" .") or "_"
+        if value != original or len(value.encode()) > 180:
+            suffix = "-" + digest(original.encode())[:12]
+            raw = value.encode()[:180 - len(suffix)]
+            value = raw.decode("utf-8", errors="ignore").rstrip(" .") + suffix
+        return value
+    parts = safe_path(record["display_rel_path"]).split("/")
+    parts[-1] = component(PurePosixPath(parts[-1]).stem) + ".txt"
+    return "/".join([SOURCE_NAME, *[component(part) for part in parts[:-1]], parts[-1]])
+
+
+def validate_database(path: Path, records: list[dict], text_root: Path) -> None:
+    with sqlite3.connect(f"file:{path.resolve()}?mode=ro&immutable=1", uri=True) as db:
+        if db.execute("PRAGMA integrity_check").fetchone()[0] != "ok":
+            raise ValueError("invalid OCR SQLite integrity")
+        version = db.execute("SELECT value FROM metadata WHERE key='tokenizer_version'").fetchone()
+        if version != (TOKENIZER,):
+            raise ValueError("OCR tokenizer mismatch")
+        ids = {row[0] for row in db.execute("SELECT doc_id FROM documents")}
+        if ids != {record["doc_id"] for record in records}:
+            raise ValueError("OCR metadata/database ID set mismatch")
+        if db.execute("SELECT COUNT(*) FROM content_fts").fetchone()[0] != len(records):
+            raise ValueError("OCR content rows mismatch")
+        for record in records:
+            body = (text_root / record["storage_rel_path"]).read_text(encoding="utf-8", errors="strict")
+            normalized = unicodedata.normalize("NFKC", body).casefold().replace("\0", " ")
+            row = db.execute("SELECT content FROM content_fts WHERE rowid=?", (int(record["doc_id"].split(":")[1]),)).fetchone()
+            if row != (normalized,):
+                raise ValueError("OCR indexed content differs from readable TXT")
+        columns = {row[1] for row in db.execute("PRAGMA table_info(snippet_anchors)")}
+        if not {"token_hash", "doc_number", "char_offset"} <= columns:
+            raise ValueError("OCR snippet anchor schema missing")
+
+
+def load_release(bucket: Path, manifest_path: str, expected_sha256: str, base_metadata_sha256: str) -> dict:
+    safe_path(manifest_path); sha(expected_sha256); sha(base_metadata_sha256)
+    bucket = bucket.resolve()
+    target = (bucket / manifest_path).resolve()
+    if bucket not in target.parents or not manifest_path.startswith("releases/ocr-"):
+        raise ValueError("OCR release path outside immutable release namespace")
+    raw = target.read_bytes()
+    if digest(raw) != expected_sha256:
+        raise ValueError("OCR release manifest checksum mismatch")
+    manifest = json.loads(raw)
+    if (manifest.get("kind") != "ccrd-ocr-search-release" or manifest.get("version") != 1
+            or manifest.get("tokenizer_version") != TOKENIZER or manifest.get("base_metadata_sha256") != base_metadata_sha256):
+        raise ValueError("incompatible OCR release/base snapshot")
+    sha(manifest.get("generation")); sha(manifest.get("builder_sha256"))
+    identity = {key: manifest[key] for key in ("version", "kind", "base_metadata_sha256", "builder_sha256", "tokenizer_version", "exports")}
+    if (manifest["generation"] != digest(canonical(identity))
+            or manifest_path != f'releases/ocr-{manifest["generation"]}/manifest.json'):
+        raise ValueError("OCR release identity/path mismatch")
+    refs = manifest.get("exports")
+    if not isinstance(refs, list) or not refs:
+        raise ValueError("empty OCR release")
+    records, exports = [], []
+    ids, paths = set(), set()
+    for ref in refs:
+        record, export = export_record(bucket, ref)
+        if record["doc_id"] in ids or record["display_rel_path"] in paths:
+            raise ValueError("OCR ID/readable-path collision; no silent overwrite")
+        ids.add(record["doc_id"]); paths.add(record["display_rel_path"])
+        records.append(record); exports.append(export)
+    if manifest.get("documents") != len(records):
+        raise ValueError("OCR release count mismatch")
+    database = manifest.get("database")
+    read_resource(bucket, database)
+    db_path = (bucket / database["path"]).resolve()
+    if database["path"] != f'indexes/ocr/{manifest["generation"]}/OCR.sqlite3':
+        raise ValueError("OCR database must retain its source namespace")
+    validate_database(db_path, records, bucket)
+    tree, browser = directory_payloads(records)
+    return {"manifest": manifest, "records": records, "exports": exports, "database": db_path,
+            "text_paths": {record["doc_id"]: bucket / record["storage_rel_path"] for record in records},
+            "tree": tree, "browser": browser}
+
+
+def pin_release(bucket: Path, manifest_path: str, expected_sha256: str,
+                base_metadata_sha256: str, cache: Path) -> dict:
+    """Verify the whole candidate before pinning a process-local immutable copy."""
+    candidate = load_release(bucket, manifest_path, expected_sha256, base_metadata_sha256)
+    cache.mkdir(parents=True, exist_ok=True)
+    destination = cache / candidate["manifest"]["generation"]
+    if destination.exists():
+        return load_release(destination, manifest_path, expected_sha256, base_metadata_sha256)
+    stage = Path(tempfile.mkdtemp(prefix="ocr-stage-", dir=cache))
+    try:
+        refs = [*candidate["manifest"]["exports"], candidate["manifest"]["database"],
+                *[export["text"] for export in candidate["exports"]]]
+        for ref in refs:
+            raw = read_resource(bucket, ref)
+            target = stage / ref["path"]
+            target.parent.mkdir(parents=True, exist_ok=True)
+            with target.open("wb") as output:
+                output.write(raw); output.flush(); os.fsync(output.fileno())
+        target = stage / manifest_path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        manifest_raw = (bucket / manifest_path).read_bytes()
+        if digest(manifest_raw) != expected_sha256:
+            raise ValueError("OCR candidate changed while being copied")
+        target.write_bytes(manifest_raw)
+        load_release(stage, manifest_path, expected_sha256, base_metadata_sha256)
+        stage.rename(destination)
+    finally:
+        if stage.exists():
+            shutil.rmtree(stage)
+    return load_release(destination, manifest_path, expected_sha256, base_metadata_sha256)

requirements-test.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+httpx==0.28.1
+playwright==1.63.0

tests/test_archive_compat.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import gzip
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import unittest
+import zipfile
+from pathlib import Path
+from unittest.mock import patch
+
+import app
+
+
+BASE_DIR = Path(__file__).resolve().parents[1]
+RUN_LARGE = os.environ.get("CCRD_LARGE_ARCHIVE_TEST") == "1"
+
+
+class ArchiveNameCompatibilityTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        app.load_data()
+
+    def test_every_corpus_record_maps_to_unique_portable_member_name(self):
+        entries = app.zip_entries([record["doc_id"] for record in app.records])
+        names = [name for name, _path in entries]
+        self.assertEqual(len(names), 47250)
+        self.assertEqual(len(names), len(set(names)))
+        self.assertTrue(all(name.count("/") == 1 for name in names))
+        self.assertTrue(all(not any(character in name for character in ':*?"<>|\\') for name in names))
+        self.assertTrue(all(not any(part.endswith((" ", ".")) for part in name.split("/")) for name in names))
+        self.assertLessEqual(max(len(name.encode("utf-8")) for name in names), 220)
+
+    def test_multiple_independent_extractors_accept_adversarial_archive(self):
+        payload = json.loads(gzip.decompress((BASE_DIR / "data/search_data.json.gz").read_bytes()))
+        records = payload["records"]
+        selected = sorted(
+            records,
+            key=lambda record: (
+                any(character in record["display_name"] for character in ':*?"<>|\\'),
+                len(record["display_name"].encode("utf-8")),
+            ),
+            reverse=True,
+        )[:100]
+        response = app.zip_response([record["doc_id"] for record in selected])
+        archive_path = Path(response.path)
+        try:
+            with zipfile.ZipFile(archive_path) as archive:
+                self.assertEqual(len(archive.namelist()), 100)
+                self.assertIsNone(archive.testzip())
+            commands = []
+            if shutil.which("unzip"):
+                commands.append(["unzip", "-t", str(archive_path)])
+            if shutil.which("7z"):
+                commands.append(["7z", "t", str(archive_path)])
+            if shutil.which("bsdtar"):
+                commands.append(["bsdtar", "-tf", str(archive_path)])
+            self.assertGreaterEqual(len(commands), 3)
+            for command in commands:
+                result = subprocess.run(command, capture_output=True, timeout=120)
+                self.assertEqual(result.returncode, 0, f"{command}: {result.stderr.decode(errors='ignore')}")
+        finally:
+            archive_path.unlink(missing_ok=True)
+
+
+@unittest.skipUnless(RUN_LARGE, "set CCRD_LARGE_ARCHIVE_TEST=1 to test the 500 largest documents")
+class MaximumArchiveCompatibilityTests(unittest.TestCase):
+    def test_500_largest_documents_open_with_multiple_extractors(self):
+        app.load_data()
+        selected = sorted(app.records, key=lambda record: record["size"], reverse=True)[:500]
+        response = app.zip_response([record["doc_id"] for record in selected])
+        archive_path = Path(response.path)
+        try:
+            self.assertGreater(archive_path.stat().st_size, 0)
+            with zipfile.ZipFile(archive_path) as archive:
+                self.assertEqual(len(archive.namelist()), 500)
+                self.assertIsNone(archive.testzip())
+            for command in (["unzip", "-t", str(archive_path)], ["7z", "t", str(archive_path)], ["bsdtar", "-tf", str(archive_path)]):
+                result = subprocess.run(command, capture_output=True, timeout=300)
+                self.assertEqual(result.returncode, 0, f"{command}: {result.stderr.decode(errors='ignore')}")
+        finally:
+            archive_path.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_benchmark.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import json
+import os
+import socket
+import statistics
+import subprocess
+import sys
+import time
+import unittest
+from datetime import datetime, timezone
+from urllib.request import Request, urlopen
+
+RESULTS_PATH = os.path.join(os.path.dirname(__file__), "benchmark-results.json")
+
+
+def _git_sha():
+    try:
+        return subprocess.run(
+            ["git", "log", "-1", "--format=%H"],
+            capture_output=True, text=True, timeout=5,
+        ).stdout.strip()
+    except Exception:
+        return ""
+
+
+def _save_results(project, queries):
+    existing = {"results": []}
+    if os.path.isfile(RESULTS_PATH):
+        try:
+            with open(RESULTS_PATH) as f:
+                existing = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            pass
+    existing.setdefault("results", []).append({
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "project": project,
+        "git_sha": _git_sha(),
+        "queries": queries,
+    })
+    existing["results"] = existing["results"][-50:]
+    with open(RESULTS_PATH, "w") as f:
+        json.dump(existing, f, indent=2, ensure_ascii=False)
+
+
+def _print_and_collect(results_list, label, iterations, times):
+    median = statistics.median(times)
+    mn = min(times)
+    mx = max(times)
+    print(f"  {label:<46s} median={median:>8.3f}ms  min={mn:>8.3f}ms  max={mx:>8.3f}ms  (n={iterations})")
+    results_list.append({
+        "label": label.strip(),
+        "iterations": iterations,
+        "median_ms": round(median, 3),
+        "min_ms": round(mn, 3),
+        "max_ms": round(mx, 3),
+    })
+
+
+def free_port():
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+# ---- shared server for API & browser tests ----
+_server_proc = None
+_server_port = None
+
+
+def start_server():
+    global _server_proc, _server_port
+    if _server_proc is not None:
+        return
+    _server_port = free_port()
+    _server_proc = subprocess.Popen(
+        [sys.executable, "-m", "uvicorn", "app:app",
+         "--host", "127.0.0.1", "--port", str(_server_port),
+         "--log-level", "error"],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+    )
+    for _ in range(120):
+        try:
+            with urlopen(f"http://127.0.0.1:{_server_port}/api/sources", timeout=2) as r:
+                if r.status == 200:
+                    return
+        except Exception:
+            time.sleep(0.5)
+    stop_server()
+    raise RuntimeError("CCRD server did not start")
+
+
+def stop_server():
+    global _server_proc, _server_port
+    if _server_proc:
+        try:
+            _server_proc.terminate()
+            _server_proc.wait(timeout=10)
+        except Exception:
+            _server_proc.kill()
+        _server_proc = None
+        _server_port = None
+
+
+# ---- local benchmarks (pure function) ----
+import app  # noqa: E402
+
+
+class LocalSearchBenchmarkTests(unittest.TestCase):
+    _results: list = []
+
+    @classmethod
+    def setUpClass(cls):
+        if not app.source_counts:
+            app.load_data()
+
+    def _bench(self, label, fn, iterations=10):
+        times = []
+        for _ in range(iterations):
+            start = time.perf_counter()
+            fn()
+            elapsed = (time.perf_counter() - start) * 1000
+            times.append(elapsed)
+        _print_and_collect(self._results, label, iterations, times)
+
+    def test_benchmarks(self):
+        self._bench('"手机" normal', lambda: app.search("手机"))
+        self._bench('"手机" exact', lambda: app.search("手机", exact=True))
+        self._bench('"文化革命" exact', lambda: app.search("文化革命", exact=True))
+        self._bench('"文化 革命" normal', lambda: app.search("文化 革命"))
+        self._bench('"手。机" exact', lambda: app.search("手。机", exact=True))
+        self._bench('"手*机" exact', lambda: app.search("手*机", exact=True))
+        self._bench('"手?机" exact', lambda: app.search("手?机", exact=True))
+        self._bench('"文" exact', lambda: app.search("文", exact=True))
+        self._bench('"ABC" normal', lambda: app.search("ABC"))
+        self._bench('"文化革命" exact search_paths=False',
+                     lambda: app.search("文化革命", exact=True, search_paths=False))
+        self._bench('"手机" exact min_size=100',
+                     lambda: app.search("手机", exact=True, min_size=100))
+        self._bench('sort by name', lambda: app.search(page=1, page_size=100, sort="name"))
+        self._bench('sort by size', lambda: app.search(page=1, page_size=100, sort="size"))
+
+    @classmethod
+    def tearDownClass(cls):
+        if cls._results:
+            _save_results("CCRD-Search-local", cls._results)
+
+
+# ---- API benchmarks (HTTP to local server) ----
+class ApiSearchBenchmarkTests(unittest.TestCase):
+    _results: list = []
+
+    def _bench(self, label, path, payload=None, iterations=5):
+        body = json.dumps(payload).encode() if payload else None
+        req = Request(f"http://127.0.0.1:{_server_port}{path}", data=body,
+                      headers={"Content-Type": "application/json"} if body else {})
+        times = []
+        for i in range(iterations + 1):
+            start = time.perf_counter()
+            with urlopen(req, timeout=60) as r:
+                r.read()
+            elapsed = (time.perf_counter() - start) * 1000
+            if i > 0:
+                times.append(elapsed)
+        _print_and_collect(self._results, label, iterations, times)
+
+    def test_search_api_benchmarks(self):
+        self._bench('"手机" normal', "/api/search", {"q": "手机"})
+        self._bench('"手机" exact', "/api/search", {"q": "手机", "exact": True})
+        self._bench('"文化革命" exact', "/api/search", {"q": "文化革命", "exact": True})
+        self._bench('"文化 革命" normal', "/api/search", {"q": "文化 革命"})
+        self._bench('"手。机" exact', "/api/search", {"q": "手。机", "exact": True})
+        self._bench('"手*机" exact', "/api/search", {"q": "手*机", "exact": True})
+        self._bench('"手?机" exact', "/api/search", {"q": "手?机", "exact": True})
+        self._bench('"文" exact', "/api/search", {"q": "文", "exact": True})
+        self._bench('"ABC" normal', "/api/search", {"q": "ABC"})
+        self._bench('sources', "/api/sources")
+
+    @classmethod
+    def tearDownClass(cls):
+        if cls._results:
+            _save_results("CCRD-Search-api", cls._results)
+
+
+# ---- browser benchmarks (Playwright) ----
+try:
+    from playwright.sync_api import sync_playwright
+except ImportError:
+    sync_playwright = None
+
+
+@unittest.skipUnless(sync_playwright, "install requirements-test.txt, run: playwright install chromium")
+class BrowserSearchBenchmarkTests(unittest.TestCase):
+    _results: list = []
+
+    @classmethod
+    def setUpClass(cls):
+        cls.playwright = sync_playwright().start()
+        cls.browser = cls.playwright.chromium.launch(headless=True, args=["--no-sandbox",
+            "--disable-gpu", "--disable-dev-shm-usage"])
+
+    @classmethod
+    def tearDownClass(cls):
+        if cls._results:
+            _save_results("CCRD-Search-browser", cls._results)
+        cls.browser.close()
+        cls.playwright.stop()
+
+    def _bench_search(self, label, query, iterations=3):
+        ctx = self.browser.new_context(viewport={"width": 1440, "height": 900})
+        page = ctx.new_page()
+        times = []
+        for i in range(iterations + 1):
+            page.goto(f"http://127.0.0.1:{_server_port}/")
+            page.wait_for_selector("#results-list .result-item", timeout=30000)
+            before_hash = page.evaluate("""() => {
+                const items = document.querySelectorAll('.result-item');
+                return Array.from(items).slice(0, 3).map(el => el.textContent.substring(0, 50)).join('|');
+            }""")
+            inp = page.locator("#search-input")
+            start = time.perf_counter()
+            inp.fill(query)
+            page.wait_for_function(f"""
+                () => {{
+                    const items = document.querySelectorAll('.result-item');
+                    if (items.length > 0) {{
+                        const hash = Array.from(items).slice(0, 3).map(el => el.textContent.substring(0, 50)).join('|');
+                        if (hash !== {json.dumps(before_hash)}) return true;
+                    }}
+                    const empty = document.querySelector('#empty-state');
+                    return !!(empty && empty.style.display !== 'none');
+                }}
+            """, timeout=15000)
+            elapsed = (time.perf_counter() - start) * 1000
+            if i > 0:
+                times.append(elapsed)
+        ctx.close()
+        _print_and_collect(self._results, label, iterations, times)
+
+    def test_browser_search_benchmarks(self):
+        self._bench_search('"手机" normal', "手机")
+        self._bench_search('"文化革命" exact', "文化革命")
+        self._bench_search('"手*机" exact', "手*机")
+
+
+def setUpModule():
+    start_server()
+
+
+def tearDownModule():
+    stop_server()

tests/test_browser.py

@@ -0,0 +1,722 @@
+from __future__ import annotations
+
+import io
+import os
+import socket
+import subprocess
+import sys
+import time
+import unittest
+import zipfile
+from pathlib import Path
+from urllib.request import urlopen
+
+try:
+    from playwright.sync_api import sync_playwright
+except ImportError:
+    sync_playwright = None
+
+
+BASE_DIR = Path(__file__).resolve().parents[1]
+
+
+def free_port() -> int:
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+@unittest.skipUnless(sync_playwright, "install requirements-test.txt and run: playwright install chromium")
+class BrowserInteractionTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.base_url = os.environ.get("CCRD_BROWSER_BASE_URL", "").rstrip("/")
+        cls.server = None
+        if not cls.base_url:
+            cls.port = free_port()
+            cls.base_url = f"http://127.0.0.1:{cls.port}"
+            cls.server = subprocess.Popen(
+                [
+                    sys.executable, "-m", "uvicorn", "app:app", "--host", "127.0.0.1",
+                    "--port", str(cls.port), "--log-level", "warning",
+                ],
+                cwd=BASE_DIR,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            for _ in range(120):
+                if cls.server.poll() is not None:
+                    raise RuntimeError("Uvicorn exited before browser tests started")
+                try:
+                    with urlopen(cls.base_url + "/api/sources", timeout=1) as response:
+                        if response.status == 200:
+                            break
+                except Exception:
+                    time.sleep(0.25)
+            else:
+                cls.server.terminate()
+                raise RuntimeError("Uvicorn did not become ready")
+        cls.playwright = sync_playwright().start()
+        cls.browser = cls.playwright.chromium.launch(headless=True, args=["--no-sandbox"])
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.browser.close()
+        cls.playwright.stop()
+        if cls.server is not None:
+            cls.server.terminate()
+            try:
+                cls.server.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                cls.server.kill()
+
+    def page(self, viewport=None):
+        context = self.browser.new_context(
+            viewport=viewport or {"width": 1440, "height": 900},
+            accept_downloads=True,
+        )
+        page = context.new_page()
+        errors = []
+        page.on("pageerror", lambda error: errors.append(str(error)))
+        page.goto(self.base_url, wait_until="domcontentloaded")
+        page.locator(".result-item").first.wait_for(timeout=30000)
+        return context, page, errors
+
+    def search_request_pages(self, page):
+        pages = []
+
+        def handle_request(request):
+            if request.method != "POST":
+                return
+            if not request.url.endswith("/api/search") and "/api/search/" not in request.url:
+                return
+            try:
+                body = request.post_data_json
+            except Exception:
+                return
+            pages.append(body.get("page"))
+
+        page.on("request", handle_request)
+        return pages
+
+    def test_late_initial_payload_cannot_take_over_a_new_search(self):
+        context, page, errors = self.page()
+        try:
+            result = page.evaluate("""async () => {
+                abortSearchPrefetch();
+                let releaseInitial;
+                loadInitialPayload = () => new Promise(resolve => { releaseInitial = resolve; });
+                STATE.query = '';
+                STATE.page = 1;
+                DOM.sortSelect.value = 'relevance';
+                const oldSearch = doSearch();
+                STATE.query = 'new-query';
+                const requests = [];
+                API.search = (body, source, signal) => new Promise(resolve => {
+                    requests.push({signal, resolve});
+                });
+                const newSearch = doSearch();
+                await Promise.resolve();
+                const owner = STATE.searchController;
+                releaseInitial(null);
+                for (let i = 0; i < 10; i++) await Promise.resolve();
+                const retainedOwner = STATE.searchController === owner;
+                for (const request of requests) request.resolve({results: [], total: 0});
+                await Promise.all([oldSearch, newSearch]);
+                return {retainedOwner, requests: requests.length, loading: STATE.isLoading};
+            }""")
+            self.assertEqual(result, {"retainedOwner": True, "requests": 1, "loading": False})
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_initial_json_body_timeout_falls_back_to_search(self):
+        context, page, errors = self.page()
+        try:
+            result = page.evaluate("""async () => {
+                abortSearchPrefetch();
+                initialPayloadCache.clear();
+                const originalFetch = window.fetch;
+                const originalTimeout = window.setTimeout;
+                let aborted = false;
+                window.setTimeout = (fn, ms, ...args) => originalTimeout(fn, ms === REQUEST_TIMEOUT_MS ? 30 : ms, ...args);
+                window.fetch = (url, options = {}) => Promise.resolve({ok: true,
+                    json: () => new Promise((resolve, reject) => {
+                        if (options.signal) options.signal.addEventListener('abort', () => {
+                            aborted = true;
+                            reject(new DOMException('aborted', 'AbortError'));
+                        }, {once: true});
+                    })});
+                let searched = false;
+                API.search = async () => { searched = true; return {results: [], total: 0}; };
+                STATE.query = '';
+                STATE.page = 1;
+                DOM.sortSelect.value = 'relevance';
+                const completed = await Promise.race([
+                    doSearch().then(() => true),
+                    new Promise(resolve => originalTimeout(() => resolve(false), 500))
+                ]);
+                window.fetch = originalFetch;
+                window.setTimeout = originalTimeout;
+                return {completed, aborted, searched};
+            }""")
+            self.assertEqual(result, {"completed": True, "aborted": True, "searched": True})
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_stale_search_failure_does_not_change_current_page(self):
+        context, page, errors = self.page()
+        try:
+            result = page.evaluate("""async () => {
+                abortSearchPrefetch();
+                let failOld;
+                let finishNew;
+                const toasts = [];
+                showToast = message => toasts.push(message);
+                API.search = body => new Promise((resolve, reject) => {
+                    if (body.q === 'old-query') failOld = reject;
+                    else finishNew = resolve;
+                });
+                STATE.query = 'old-query';
+                const oldSearch = doSearch();
+                await Promise.resolve();
+                STATE.query = 'new-query';
+                STATE.page = 2;
+                const newSearch = doSearch();
+                await Promise.resolve();
+                failOld(new TypeError('late network failure'));
+                await oldSearch;
+                const currentPage = STATE.page;
+                finishNew({results: [], total: 0});
+                await newSearch;
+                return {currentPage, toasts};
+            }""")
+            self.assertEqual(result, {"currentPage": 2, "toasts": []})
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_failed_sidebar_payload_can_be_retried(self):
+        context, page, errors = self.page()
+        try:
+            result = page.evaluate("""async () => {
+                sidebarInitialCache.clear();
+                let attempts = 0;
+                window.fetch = async () => {
+                    if (++attempts === 1) throw new TypeError('connection lost');
+                    return {ok: true, json: async () => ({sources: []})};
+                };
+                await loadSidebarInitial(null).catch(() => null);
+                const data = await loadSidebarInitial(null).catch(() => null);
+                return {attempts, recovered: Array.isArray(data && data.sources)};
+            }""")
+            self.assertEqual(result, {"attempts": 2, "recovered": True})
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_late_root_sidebar_does_not_replace_open_folder(self):
+        for initial in (True, False):
+            with self.subTest(initial=initial):
+                context, page, errors = self.page()
+                try:
+                    result = page.evaluate("""async initial => {
+                        STATE.source = 'CCRD';
+                        const route = ++routeRenderId;
+                        let release;
+                        const rootData = {source: 'CCRD', folders: [{name: 'root', path: 'root'}], files: []};
+                        loadSidebarInitial = initial
+                            ? () => new Promise(resolve => { release = () => resolve(rootData); })
+                            : async () => null;
+                        API.getContents = (source, path) => path
+                            ? Promise.resolve({folders: [], files: [{doc_id: 'child', name: '当前目录文件'}]})
+                            : new Promise(resolve => { release = () => resolve(rootData); });
+                        const pending = renderSidebar(route);
+                        for (let i = 0; i < 5; i++) await Promise.resolve();
+                        await openFolder('child', route);
+                        const html = DOM.sidebarContent.innerHTML;
+                        release();
+                        await pending;
+                        return {preserved: DOM.sidebarContent.innerHTML === html, path: sidebarCurrentPath};
+                    }""", initial)
+                    self.assertEqual(result, {"preserved": True, "path": "child"})
+                    self.assertEqual(errors, [])
+                finally:
+                    context.close()
+
+    def test_old_sidebar_retry_cannot_reopen_previous_folder(self):
+        context, page, errors = self.page()
+        try:
+            result = page.evaluate("""async () => {
+                STATE.source = 'CCRD';
+                const route = ++routeRenderId;
+                const originalTimeout = window.setTimeout;
+                const retries = [];
+                window.setTimeout = (fn, ms, ...args) => ms === 1200
+                    ? (retries.push(fn), 0) : originalTimeout(fn, ms, ...args);
+                const paths = [];
+                API.getContents = async (source, path) => {
+                    paths.push(path);
+                    if (path === 'old') throw new TypeError('offline');
+                    return {folders: [], files: [{doc_id: 'new', name: '新目录'}]};
+                };
+                await openFolder('old', route);
+                await openFolder('new', route);
+                for (const retry of retries.slice()) retry();
+                for (let i = 0; i < 5; i++) await Promise.resolve();
+                window.setTimeout = originalTimeout;
+                return {paths, path: sidebarCurrentPath, visible: DOM.sidebarContent.textContent.includes('新目录')};
+            }""")
+            self.assertEqual(result, {"paths": ["old", "new"], "path": "new", "visible": True})
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_folder_http_errors_are_not_treated_as_empty_directories(self):
+        context, page, errors = self.page()
+        try:
+            result = page.evaluate("""async () => {
+                folderTreePending.clear();
+                folderContentsPending.clear();
+                STATE.folderContentsCache.clear();
+                window.fetch = async () => ({ok: false, status: 503, json: async () => ({folders: [], files: []})});
+                const treeRejected = await API.getFolders('CCRD').then(() => false, () => true);
+                const contentsRejected = await API.getContents('CCRD', 'retry').then(() => false, () => true);
+                let requests = 0;
+                window.fetch = async () => {
+                    requests++;
+                    return {ok: true, json: async () => ({folders: [], files: [{doc_id: 'recovered'}]})};
+                };
+                const recovered = await API.getContents('CCRD', 'retry');
+                return {treeRejected, contentsRejected, requests, recovered: recovered.files[0]?.doc_id};
+            }""")
+            self.assertEqual(result, {"treeRejected": True, "contentsRejected": True, "requests": 1, "recovered": "recovered"})
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_old_folder_navigation_does_not_restart_search_after_going_home(self):
+        context, page, errors = self.page()
+        try:
+            result = page.evaluate("""async () => {
+                let release;
+                renderSidebar = () => STATE.source
+                    ? new Promise(resolve => { release = resolve; }) : Promise.resolve();
+                const searches = [];
+                const trees = [];
+                renderFolderTree = async () => trees.push(STATE.source);
+                doSearch = () => searches.push(STATE.source);
+                const oldNavigation = navigateToSourceFolder('CCRD', 'old');
+                navigateHome();
+                release();
+                await oldNavigation;
+                return {searches, trees, source: STATE.source};
+            }""")
+            self.assertEqual(result, {"searches": [None], "trees": [None], "source": None})
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_desktop_controls_search_preview_and_selection(self):
+        context, page, errors = self.page()
+        try:
+            static_controls = (
+                "hamburger-btn", "search-input", "settings-btn", "theme-btn", "mobile-toggle-btn",
+                "multi-select-toggle", "multi-select-all", "multi-deselect", "multi-batch-download",
+                "multi-zip-download", "empty-random-btn", "close-filters-btn", "fulltext-toggle",
+                "search-paths-toggle", "history-toggle", "exact-search-toggle", "folder-select-all",
+                "folder-deselect-all", "source-filter-cancel", "folder-filter-cancel",
+                "filter-min-size", "filter-min-unit", "filter-max-size",
+                "filter-max-unit", "random-book-btn", "sort-select",
+            )
+            for control_id in static_controls:
+                self.assertEqual(page.locator(f"#{control_id}").count(), 1, control_id)
+
+            original_theme = page.locator("body").get_attribute("class")
+            page.locator("#theme-btn").click()
+            self.assertNotEqual(page.locator("body").get_attribute("class"), original_theme)
+            self.assertEqual(page.locator("body.theme-transitioning").count(), 0)
+            self.assertGreater(page.locator("#theme-btn .theme-icon-svg").evaluate("node => node.getAnimations().length"), 0)
+
+            page.locator("#settings-btn").click()
+            self.assertTrue(page.evaluate("STATE.rightSidebarOpen"))
+            page.locator("#close-filters-btn").click()
+            self.assertFalse(page.evaluate("STATE.rightSidebarOpen"))
+
+            page.locator("#mobile-toggle-btn").click()
+            self.assertTrue(page.locator("body").evaluate("node => node.classList.contains('mobile')"))
+            page.locator("#mobile-toggle-btn").click()
+            self.assertFalse(page.locator("body").evaluate("node => node.classList.contains('mobile')"))
+
+            page.locator("#settings-btn").click()
+            page.locator("label:has(#fulltext-toggle)").click()
+            self.assertEqual(page.locator("#search-input").get_attribute("placeholder"), "搜索 TXT 文件或路径...")
+            page.locator("label:has(#exact-search-toggle)").click()
+            page.locator("label:has(#search-paths-toggle)").click()
+            page.locator("label:has(#history-toggle)").click()
+            self.assertIn("fulltext=0", page.url)
+            self.assertIn("exact=0", page.url)
+            self.assertIn("search_paths=0", page.url)
+            self.assertIn("history=0", page.url)
+            page.locator("#close-filters-btn").click()
+
+            page.locator("#sort-select").select_option("name")
+            page.locator("#search-input").fill("文化革命")
+            page.wait_for_timeout(400)
+            page.locator(".result-item").first.wait_for(timeout=30000)
+            self.assertIn("q=", page.url)
+
+            page.locator("#multi-select-toggle").check()
+            page.locator(".result-checkbox").first.check()
+            self.assertIn("已选 1 项", page.locator("#multi-selected-count").text_content())
+            page.locator("#multi-select-all").click()
+            self.assertGreater(page.locator(".result-checkbox:checked").count(), 0)
+            page.locator("#multi-select-all").click()
+            self.assertEqual(page.locator(".result-checkbox:checked").count(), 0)
+            page.locator("#multi-deselect").click()
+            self.assertEqual(page.locator(".result-checkbox:checked").count(), 0)
+
+            page.locator("[data-action='preview']").first.click()
+            page.locator("#preview-panel").wait_for(state="visible", timeout=30000)
+            self.assertEqual(page.locator("[data-action='close-preview']").count(), 1)
+            page.locator("[data-action='close-preview']").click()
+            page.locator("#preview-panel").wait_for(state="hidden")
+
+            page.locator("#random-book-btn").click()
+            page.locator("#preview-panel").wait_for(state="visible", timeout=30000)
+            page.keyboard.press("Escape")
+            page.locator("#preview-panel").wait_for(state="hidden")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_section_filter_cancel_buttons_preserve_other_filters(self):
+        context, page, errors = self.page()
+        try:
+            page.locator("#settings-btn").click()
+            page.locator("#filter-min-size").fill("1")
+            page.locator("#filter-source-list input").first.check()
+            page.locator("#source-filter-cancel").wait_for(state="visible")
+            page.locator("#source-filter-cancel").click()
+            self.assertEqual(page.evaluate("STATE.selectedSources"), [])
+            self.assertEqual(page.locator("#filter-min-size").input_value(), "1")
+            page.goto(self.base_url + "/CCRD", wait_until="domcontentloaded")
+            page.locator(".result-item").first.wait_for(timeout=30000)
+            page.locator("#settings-btn").click()
+            page.locator("#folder-select-all").click()
+            page.locator("#folder-filter-cancel").wait_for(state="visible")
+            page.locator("#folder-filter-cancel").click()
+            self.assertEqual(page.evaluate("STATE.folderSelections"), [])
+            self.assertNotIn("folder=", page.url)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_short_snippet_does_not_keep_three_line_height(self):
+        context, page, errors = self.page()
+        try:
+            lazy_rendering = page.locator(".result-item").first.evaluate(
+                "node => ({ visibility: getComputedStyle(node).contentVisibility, intrinsicSize: getComputedStyle(node).containIntrinsicSize })"
+            )
+            self.assertEqual(lazy_rendering["visibility"], "auto")
+            self.assertIn("112px", lazy_rendering["intrinsicSize"])
+            page.locator(".result-snippet").first.wait_for()
+            page.locator(".result-snippet").first.evaluate("node => node.textContent = '短摘要'")
+            height = page.locator(".result-snippet").first.bounding_box()["height"]
+            self.assertLess(height, 40)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_theme_switch_does_not_animate_large_result_tree(self):
+        context, page, errors = self.page()
+        try:
+            page.locator("#results-list").evaluate(
+                """list => {
+                    const template = list.querySelector('.result-item');
+                    while (list.children.length < 500) list.appendChild(template.cloneNode(true));
+                }"""
+            )
+            page.locator("#theme-btn").click()
+            result_animations = page.locator("#results-list").evaluate(
+                "list => list.getAnimations({subtree: true}).length"
+            )
+            icon_animations = page.locator("#theme-btn .theme-icon-svg").evaluate(
+                "node => node.getAnimations().length"
+            )
+            self.assertEqual(page.locator(".result-item").count(), 500)
+            self.assertEqual(result_animations, 0)
+            self.assertGreater(icon_animations, 0)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_long_snippet_clamps_to_three_lines(self):
+        context, page, errors = self.page()
+        try:
+            page.locator(".result-snippet").first.wait_for()
+            page.locator(".result-snippet").first.evaluate("node => { node.textContent = ['第一行','第二行','第三行','第四行','第五行'].join('\\n'); }")
+            height = page.locator(".result-snippet").first.bounding_box()["height"]
+            self.assertLess(height, 90)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_source_folder_controls_and_mobile_sidebars(self):
+        context = self.browser.new_context(viewport={"width": 390, "height": 844})
+        page = context.new_page()
+        errors = []
+        page.on("pageerror", lambda error: errors.append(str(error)))
+        try:
+            page.goto(self.base_url + "/CCRD", wait_until="domcontentloaded")
+            page.locator(".result-item").first.wait_for(timeout=30000)
+            self.assertTrue(page.locator("body").evaluate("node => node.classList.contains('mobile')"))
+            page.locator("#hamburger-btn").click()
+            self.assertTrue(page.evaluate("STATE.leftSidebarOpen"))
+            page.locator("#overlay").click(position={"x": 380, "y": 400})
+            self.assertFalse(page.evaluate("STATE.leftSidebarOpen"))
+            page.locator("#settings-btn").click()
+            self.assertTrue(page.evaluate("STATE.rightSidebarOpen"))
+            page.locator("#close-filters-btn").click()
+            self.assertFalse(page.evaluate("STATE.rightSidebarOpen"))
+            page.locator("#settings-btn").click()
+            page.locator("#folder-select-all").click()
+            self.assertGreaterEqual(page.locator("#filter-folder-tree input:checked").count(), 1)
+            page.evaluate("""() => {
+              const paths = [];
+              flattenNodes(STATE.folderTree, paths);
+              const leaf = paths.sort((left, right) => right.split('/').length - left.split('/').length)[0];
+              applyFolderSelections(deselectFolderPath(leaf));
+              applyFolderSelections(selectFolderPath(leaf));
+            }""")
+            page.locator("#folder-select-all").click()
+            self.assertEqual(page.evaluate("STATE.folderSelections"), [])
+            page.locator("#folder-select-all").click()
+            page.locator("#folder-deselect-all").click()
+            page.locator("#filter-min-size").fill("1")
+            page.locator("#filter-min-unit").select_option("KB")
+            page.locator("#close-filters-btn").click()
+            page.locator("#clear-filters-btn").click()
+            self.assertEqual(page.locator("#filter-min-size").input_value(), "")
+            page.locator("[data-action='preview']").first.click()
+            page.locator("#preview-panel").wait_for(state="visible", timeout=30000)
+            page.locator("[data-action='toggle-preview-theme']").click()
+            page.locator("[data-action='close-preview']").click()
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_mobile_long_folder_uses_remaining_path_line(self):
+        context, page, errors = self.page({"width": 390, "height": 844})
+        try:
+            layout = page.evaluate("""async () => {
+                STATE.results = [{
+                    Source: "CCRD",
+                    SourceName: "CCRD",
+                    File: "路径换行测试",
+                    Folder: [
+                        "马列之声ebook小组第七批成果集成(2018.8.17)",
+                        "马列之声ebook小组第七批成果集成(2018.8.17)part 1a",
+                        "2018.8 part 1",
+                    ],
+                    Size: 1,
+                    doc_id: "browser-path-test",
+                    snippet: "",
+                    snippet_complete: true,
+                }];
+                STATE.total = 1;
+                renderResults({ animate: false });
+                await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+                const path = document.querySelector('.result-path');
+                const folders = [...path.querySelectorAll('.path-folder')];
+                const first = document.createRange();
+                first.selectNodeContents(folders[1]);
+                const source = folders[0].getBoundingClientRect();
+                const firstRect = first.getClientRects()[0];
+                return {
+                    sourceTop: source.top,
+                    firstTop: firstRect.top,
+                    firstLeft: firstRect.left,
+                    separatorsNested: [...path.querySelectorAll('.path-sep')].every(sep => sep.parentElement.classList.contains('path-folder')),
+                };
+            }""")
+            self.assertAlmostEqual(layout["firstTop"], layout["sourceTop"], delta=1)
+            self.assertGreater(layout["firstLeft"], 0)
+            self.assertTrue(layout["separatorsNested"])
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_individual_batch_and_zip_downloads_are_browser_valid(self):
+        context, page, errors = self.page()
+        try:
+            with page.expect_download(timeout=30000) as download_info:
+                page.locator(".result-action-btn.primary").first.click()
+            individual = download_info.value
+            self.assertTrue(individual.suggested_filename.endswith(".txt"))
+            self.assertGreater(Path(individual.path()).stat().st_size, 0)
+
+            page.locator("#multi-select-toggle").check()
+            page.locator(".result-checkbox").first.check()
+            with page.expect_download(timeout=30000) as download_info:
+                page.locator("#multi-batch-download").click()
+            batch = download_info.value
+            self.assertTrue(batch.suggested_filename.endswith(".txt"))
+            self.assertGreater(Path(batch.path()).stat().st_size, 0)
+
+            checkboxes = page.locator(".result-checkbox")
+            checkboxes.nth(1).check()
+            with page.expect_download(timeout=120000) as download_info:
+                page.locator("#multi-zip-download").click()
+            archive_download = download_info.value
+            archive_bytes = Path(archive_download.path()).read_bytes()
+            self.assertTrue(archive_bytes.startswith(b"PK"))
+            with zipfile.ZipFile(io.BytesIO(archive_bytes)) as archive:
+                self.assertEqual(len(archive.namelist()), 2)
+                self.assertIsNone(archive.testzip())
+            self.assertNotIn(b"PK\x06\x06", archive_bytes)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_navigation_history_source_filters_and_keyboard(self):
+        context, page, errors = self.page()
+        try:
+            page.locator("#hamburger-btn").click()
+            self.assertFalse(page.evaluate("STATE.leftSidebarOpen"))
+            page.locator("#hamburger-btn").click()
+            self.assertTrue(page.evaluate("STATE.leftSidebarOpen"))
+
+            page.locator("#settings-btn").click()
+            source_inputs = page.locator("#filter-source-list input")
+            self.assertEqual(source_inputs.count(), 2)
+            page.locator("#filter-source-list label").first.click()
+            self.assertEqual(len(page.evaluate("STATE.selectedSources")), 1)
+            page.locator("#close-filters-btn").click()
+            page.locator("#clear-filters-btn").click()
+            self.assertEqual(page.evaluate("STATE.selectedSources"), [])
+
+            page.locator("#search-input").fill("文化")
+            page.wait_for_timeout(400)
+            page.locator(".result-item").first.wait_for(timeout=30000)
+            page.locator("#search-input").fill("")
+            page.wait_for_timeout(400)
+            page.locator("#search-input").focus()
+            history_item = page.locator("#search-history-dropdown [data-query]").first
+            history_item.wait_for(state="visible", timeout=10000)
+            history_item.click()
+            self.assertEqual(page.locator("#search-input").input_value(), "文化")
+
+            page.locator("#search-input").press("Escape")
+            self.assertFalse(page.evaluate("STATE.leftSidebarOpen"))
+            page.keyboard.press("/")
+            self.assertTrue(page.locator("#search-input").evaluate("node => document.activeElement === node"))
+
+            page.goto(self.base_url + "/CCRD", wait_until="domcontentloaded")
+            page.locator(".result-item").first.wait_for(timeout=30000)
+            self.assertTrue(page.locator("#sidebar-expand-btn").is_visible())
+            page.locator("#sidebar-expand-btn").click()
+            self.assertTrue(page.locator("#left-sidebar").evaluate("node => node.classList.contains('expanded-wide')"))
+            page.locator("#sidebar-expand-btn").click()
+            self.assertFalse(page.locator("#left-sidebar").evaluate("node => node.classList.contains('expanded-wide')"))
+            back_home = page.locator("#back-home")
+            if back_home.count():
+                back_home.click()
+                self.assertEqual(page.url.rstrip("/"), self.base_url)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_accessibility_keyboard_paths_sidebar_state_and_preview_focus(self):
+        context, page, errors = self.page()
+        try:
+            self.assertEqual(page.locator("#search-input").get_attribute("aria-label"), "搜索 TXT 文件和正文")
+            self.assertEqual(page.locator("#results-list").get_attribute("role"), "list")
+            path = page.locator(".path-folder[role='button']").first
+            self.assertEqual(path.get_attribute("tabindex"), "0")
+            self.assertTrue(path.get_attribute("aria-label"))
+
+            page.locator("#settings-btn").press("Enter")
+            self.assertEqual(page.locator("#settings-btn").get_attribute("aria-expanded"), "true")
+            self.assertFalse(page.locator("#right-sidebar").evaluate("node => node.inert"))
+            page.keyboard.press("Escape")
+            self.assertEqual(page.locator("#settings-btn").get_attribute("aria-expanded"), "false")
+            self.assertEqual(page.evaluate("document.activeElement.id"), "hamburger-btn")
+
+            page.locator("[data-action='preview']").first.click()
+            page.locator("#preview-panel").wait_for(state="visible", timeout=30000)
+            self.assertEqual(page.locator("#preview-panel").get_attribute("role"), "dialog")
+            self.assertEqual(page.locator("#preview-panel").get_attribute("aria-modal"), "true")
+            self.assertTrue(page.locator("#header").evaluate("node => node.inert"))
+            self.assertEqual(page.evaluate("document.activeElement.getAttribute('data-action')"), "close-preview")
+            page.keyboard.press("Escape")
+            page.locator("#preview-panel").wait_for(state="hidden")
+            self.assertFalse(page.locator("#header").evaluate("node => node.inert"))
+            self.assertEqual(page.evaluate("document.activeElement.getAttribute('data-action')"), "preview")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_search_prefetch_advances_to_third_page_after_second_page_loads(self):
+        context, page, errors = self.page()
+        try:
+            pages = self.search_request_pages(page)
+            page.locator("#search-input").fill("文化")
+            page.wait_for_timeout(400)
+            page.locator(".result-item").first.wait_for(timeout=30000)
+
+            page.locator("#results-container").evaluate("el => { el.scrollTop = el.scrollHeight; }")
+            page.wait_for_timeout(1200)
+            page.wait_for_timeout(1200)
+            self.assertGreaterEqual(page.evaluate("STATE.results.length"), 200)
+            self.assertIn(1, pages)
+            self.assertIn(2, pages)
+            self.assertIn(3, pages)
+            self.assertEqual(pages.count(3), 1)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_initial_search_prefetches_second_page_once(self):
+        context = self.browser.new_context(viewport={"width": 1440, "height": 900})
+        page = context.new_page()
+        errors = []
+        page.on("pageerror", lambda error: errors.append(str(error)))
+        pages = self.search_request_pages(page)
+        try:
+            page.goto(self.base_url, wait_until="domcontentloaded")
+            page.locator(".result-item").first.wait_for(timeout=30000)
+            page.wait_for_timeout(2500)
+            self.assertEqual(pages.count(2), 1)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_initial_results_skip_entry_animation_but_search_results_animate(self):
+        context, page, errors = self.page()
+        try:
+            self.assertEqual(page.locator(".result-item.result-enter").count(), 0)
+            page.evaluate("""
+                window.__sawResultEnter = false;
+                new MutationObserver((mutations, observer) => {
+                    if (!mutations.some((mutation) =>
+                        mutation.target instanceof Element && mutation.target.classList.contains("result-enter")
+                    )) return;
+                    window.__sawResultEnter = true;
+                    observer.disconnect();
+                }).observe(document.querySelector("#results-list"), {
+                    subtree: true,
+                    attributes: true,
+                    attributeFilter: ["class"],
+                });
+            """)
+            page.locator("#search-input").fill("文化")
+            page.wait_for_function("window.__sawResultEnter", timeout=30000)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_integration.py

@@ -0,0 +1,529 @@
+from __future__ import annotations
+
+import gzip
+import io
+import json
+import sqlite3
+import tempfile
+import threading
+import unittest
+import zipfile
+from pathlib import Path
+from unittest.mock import patch
+from urllib.parse import urlencode
+
+from fastapi.testclient import TestClient
+
+import app
+import build_fulltext_db
+
+
+def create_fts_database(path: Path, rows: list[tuple[int, str]]) -> None:
+    with sqlite3.connect(path) as connection:
+        connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+        connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+        connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+        connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+        connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+        connection.execute("CREATE TABLE snippet_anchors (token_hash BLOB NOT NULL, doc_number INTEGER NOT NULL, char_offset INTEGER NOT NULL, PRIMARY KEY (token_hash, doc_number)) WITHOUT ROWID")
+        for number, content in rows:
+            connection.execute("INSERT INTO documents VALUES (?, ?)", (f"CCRD:{number}", content[:700]))
+            connection.execute("INSERT INTO content_fts(rowid, content) VALUES (?, ?)", (number, content))
+            connection.executemany(
+                "INSERT INTO snippet_anchors VALUES (?, ?, ?)",
+                ((token_hash, number, char_offset) for token_hash, char_offset in build_fulltext_db.snippet_anchors(content).items()),
+            )
+            for token in build_fulltext_db.index_tokens(content) | build_fulltext_db.literal_tokens(content):
+                token_hash = __import__("hashlib").sha256(token.encode("utf-8")).digest()[:16]
+                existing = connection.execute("SELECT docs FROM postings WHERE token_hash = ?", (token_hash,)).fetchone()
+                numbers = [number] if existing is None else sorted(build_doc_numbers(existing[0]) | {number})
+                payload = build_fulltext_db.encode_doc_ids(numbers)
+                connection.execute(
+                    "INSERT OR REPLACE INTO postings VALUES (?, ?, ?)",
+                    (token_hash, payload, len(numbers)),
+                )
+
+
+def build_doc_numbers(payload: bytes) -> set[int]:
+    return app.decode_doc_numbers(payload)
+
+
+class FulltextIntegrationTests(unittest.TestCase):
+    def test_match_cache_is_complete_isolated_mode_scoped_and_expiring(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            create_fts_database(root / "CCRD.sqlite3", [(1, "文化 革命"), (2, "文化革命")])
+            databases = app.FulltextDatabases(root)
+            original = databases._search_source_connection
+            try:
+                with patch.object(databases, "_search_source_connection", wraps=original) as search, \
+                        patch.object(app.time, "monotonic", return_value=100) as clock:
+                    first = databases.search_source("CCRD", "文化 革命")
+                    first.clear()
+                    self.assertEqual(databases.search_source("CCRD", "文化 革命"), {1, 2})
+                    self.assertEqual(search.call_count, 1)
+                    self.assertEqual(databases.search_source("CCRD", "文化 革命", True), {1})
+                    self.assertEqual(search.call_count, 2)
+                    clock.return_value = 401
+                    self.assertEqual(databases.search_source("CCRD", "文化 革命"), {1, 2})
+                    self.assertEqual(search.call_count, 3)
+                self.assertEqual(databases.match_inflight, {})
+            finally:
+                databases.close()
+
+    def test_match_cache_obeys_entry_and_total_id_budgets_without_truncation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            create_fts_database(root / "CCRD.sqlite3", [(1, "正文")])
+            databases = app.FulltextDatabases(root)
+            try:
+                with patch.object(app, "FULLTEXT_MATCH_CACHE_MAX_ENTRIES", 2), \
+                        patch.object(app, "FULLTEXT_MATCH_CACHE_MAX_TOTAL_IDS", 3), \
+                        patch.object(databases, "_search_source_connection", return_value={1, 2}):
+                    for query in ("甲", "乙", "丙"):
+                        self.assertEqual(databases.search_source("CCRD", query), {1, 2})
+                    self.assertEqual(len(databases.match_cache), 1)
+                    self.assertLessEqual(sum(len(value[1]) for value in databases.match_cache.values()), 3)
+                    databases.match_cache.clear()
+                    with patch.object(databases, "_search_source_connection", return_value={1}) as search:
+                        for query in ("甲", "乙", "丙"):
+                            self.assertEqual(databases.search_source("CCRD", query), {1})
+                        self.assertEqual(len(databases.match_cache), 2)
+                    databases.match_cache.clear()
+                    with patch.object(databases, "_search_source_connection", return_value={1, 2, 3, 4}) as search:
+                        for _ in range(2):
+                            self.assertEqual(databases.search_source("CCRD", "oversized"), {1, 2, 3, 4})
+                        self.assertEqual(search.call_count, 2)
+                        self.assertEqual(databases.match_cache, {})
+                self.assertEqual(databases.match_inflight, {})
+            finally:
+                databases.close()
+
+    def test_concurrent_source_queries_share_complete_work_and_failures_release(self):
+        import concurrent.futures
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            create_fts_database(root / "CCRD.sqlite3", [(1, "正文")])
+            databases = app.FulltextDatabases(root)
+            entered = threading.Event()
+            joined = threading.Event()
+            release = threading.Event()
+            calls = []
+            def execute(*_args):
+                calls.append(1)
+                entered.set()
+                self.assertTrue(release.wait(5))
+                return {1, 2, 3}
+            try:
+                with patch.object(databases, "_search_source_connection", side_effect=execute):
+                    with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
+                        first = executor.submit(databases.search_source, "CCRD", "query")
+                        try:
+                            self.assertTrue(entered.wait(5))
+                            pending = next(iter(databases.match_inflight.values()))
+                            original_wait = pending.wait
+                            def wait(timeout=None):
+                                joined.set()
+                                return original_wait(timeout)
+                            with patch.object(pending, "wait", side_effect=wait):
+                                second = executor.submit(databases.search_source, "CCRD", "query")
+                                self.assertTrue(joined.wait(5))
+                                self.assertEqual(len(calls), 1)
+                        finally:
+                            release.set()
+                        self.assertEqual(first.result(timeout=5), {1, 2, 3})
+                        self.assertEqual(second.result(timeout=5), {1, 2, 3})
+                self.assertEqual(len(calls), 1)
+                self.assertEqual(databases.match_inflight, {})
+                with patch.object(databases, "_search_source_connection", side_effect=[RuntimeError("failed"), {9}]) as search:
+                    with self.assertRaises(RuntimeError):
+                        databases.search_source("CCRD", "failure")
+                    self.assertEqual(databases.match_inflight, {})
+                    self.assertEqual(databases.search_source("CCRD", "failure"), {9})
+                    self.assertEqual(search.call_count, 2)
+            finally:
+                databases.close()
+    def test_fulltext_databases_can_load_in_memory(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            create_fts_database(path, [(1, "开头 文化革命 正文")])
+            databases = app.FulltextDatabases(Path(directory), in_memory=True)
+            try:
+                self.assertEqual(databases.search_source("CCRD", "文化革命", exact=True), {1})
+                self.assertEqual(databases.search_source("CCRD", "文化 革命", exact=False), {1})
+            finally:
+                databases.close()
+
+    def test_short_latin_exact_and_latin_wildcards_do_not_miss_substrings(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            create_fts_database(path, [(1, "smartphone abc123xyz"), (2, "alpha beta"), (3, "unrelated")])
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                self.assertEqual(databases.search_source("CCRD", "abc", exact=True), {1})
+                self.assertEqual(databases.search_source("CCRD", "phone", exact=True), {1})
+                self.assertEqual(databases.search_source("CCRD", "abc*xyz", exact=True), {1})
+                self.assertEqual(databases.search_source("CCRD", "a?c*xyz", exact=True), {1})
+            finally:
+                databases.close()
+
+    def test_builder_creates_complete_reusable_database(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            corpus = root / "corpus"
+            corpus.mkdir()
+            (corpus / "one.txt").write_text("开头 文化革命 正文", encoding="utf-8")
+            (corpus / "two.txt").write_text("全角ＡＢＣ和手机", encoding="utf-8")
+            records = [
+                {"doc_id": "TEST:1", "storage_root": "corpus", "storage_rel_path": "one.txt"},
+                {"doc_id": "TEST:2", "storage_root": "corpus", "storage_rel_path": "two.txt"},
+            ]
+            with patch.object(build_fulltext_db, "BASE_DIR", root), patch.object(build_fulltext_db, "FULLTEXT_DIR", root / "fulltext"):
+                build_fulltext_db.FULLTEXT_DIR.mkdir()
+                build_fulltext_db.build_source_db("TEST", records)
+                database = build_fulltext_db.FULLTEXT_DIR / "TEST.sqlite3"
+                first_bytes = database.read_bytes()
+                self.assertTrue(build_fulltext_db.database_ready(database, 2))
+                with sqlite3.connect(database) as connection:
+                    self.assertEqual(connection.execute("SELECT COUNT(*) FROM documents").fetchone()[0], 2)
+                    self.assertEqual(connection.execute("SELECT COUNT(*) FROM content_fts").fetchone()[0], 2)
+                    self.assertGreater(connection.execute("SELECT COUNT(*) FROM snippet_anchors").fetchone()[0], 0)
+                    self.assertEqual(connection.execute("SELECT value FROM metadata WHERE key='tokenizer_version'").fetchone()[0], app.TOKENIZER_VERSION)
+                    self.assertGreater(connection.execute("SELECT COUNT(*) FROM postings").fetchone()[0], 0)
+                build_fulltext_db.build_source_db("TEST", records)
+                self.assertEqual(database.read_bytes(), first_bytes)
+
+    def test_builder_rejects_invalid_document_ids_without_publishing_database(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            corpus = root / "corpus"
+            corpus.mkdir()
+            (corpus / "one.txt").write_text("正文", encoding="utf-8")
+            record = {"doc_id": "invalid", "storage_root": "corpus", "storage_rel_path": "one.txt"}
+            with patch.object(build_fulltext_db, "BASE_DIR", root), patch.object(build_fulltext_db, "FULLTEXT_DIR", root / "fulltext"):
+                build_fulltext_db.FULLTEXT_DIR.mkdir()
+                with self.assertRaises(ValueError):
+                    build_fulltext_db.build_source_db("TEST", [record])
+                self.assertFalse((build_fulltext_db.FULLTEXT_DIR / "TEST.sqlite3").exists())
+
+    def test_builder_does_not_publish_database_with_missing_files(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            record = {"doc_id": "TEST:1", "storage_root": "corpus", "storage_rel_path": "missing.txt"}
+            with patch.object(build_fulltext_db, "BASE_DIR", root), patch.object(build_fulltext_db, "FULLTEXT_DIR", root / "fulltext"):
+                build_fulltext_db.FULLTEXT_DIR.mkdir()
+                with self.assertRaises(RuntimeError):
+                    build_fulltext_db.build_source_db("TEST", [record])
+                self.assertFalse((build_fulltext_db.FULLTEXT_DIR / "TEST.sqlite3").exists())
+                self.assertFalse((build_fulltext_db.FULLTEXT_DIR / "TEST.sqlite3.tmp").exists())
+
+    def test_atomic_database_replacement_reopens_and_increments_generation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            path = root / "CCRD.sqlite3"
+            create_fts_database(path, [(1, "旧数据库文化")])
+            databases = app.FulltextDatabases(root)
+            first_generation = databases.generation
+            replacement = root / "replacement.sqlite3"
+            create_fts_database(replacement, [(2, "新数据库革命资料")])
+            replacement.replace(path)
+            databases.refresh()
+            try:
+                self.assertGreater(databases.generation, first_generation)
+                self.assertEqual(databases.search_source("CCRD", "革命"), {2})
+                self.assertEqual(databases.search_source("CCRD", "文化"), set())
+            finally:
+                databases.close()
+
+    def test_refresh_builds_replacement_without_blocking_existing_queries(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            path = root / "CCRD.sqlite3"
+            create_fts_database(path, [(1, "旧数据库文化")])
+            databases = app.FulltextDatabases(root, in_memory=True)
+            replacement = root / "replacement.sqlite3"
+            create_fts_database(replacement, [(2, "新数据库革命资料")])
+            replacement.replace(path)
+            opening = threading.Event()
+            release = threading.Event()
+            original_open = databases._open_candidate
+
+            def blocked_open(candidate_path):
+                opening.set()
+                self.assertTrue(release.wait(2))
+                return original_open(candidate_path)
+
+            thread = threading.Thread(target=databases.refresh)
+            try:
+                with patch.object(databases, "_open_candidate", side_effect=blocked_open):
+                    thread.start()
+                    self.assertTrue(opening.wait(2))
+                    self.assertEqual(databases.search_source("CCRD", "文化"), {1})
+                    release.set()
+                    thread.join(2)
+                    self.assertFalse(thread.is_alive())
+                self.assertEqual(databases.search_source("CCRD", "革命"), {2})
+            finally:
+                release.set()
+                thread.join(2)
+                databases.close()
+
+    def test_active_query_keeps_retired_connection_alive_until_release(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            path = root / "CCRD.sqlite3"
+            create_fts_database(path, [(1, "旧数据库文化")])
+            databases = app.FulltextDatabases(root, in_memory=True)
+            entered = threading.Event()
+            release = threading.Event()
+            result = []
+            original_search = databases._search_source_connection
+
+            def blocked_search(connection, query, exact, state):
+                entered.set()
+                self.assertTrue(release.wait(2))
+                return original_search(connection, query, exact, state)
+
+            thread = threading.Thread(target=lambda: result.append(databases.search_source("CCRD", "文化")))
+            try:
+                with patch.object(databases, "_search_source_connection", side_effect=blocked_search):
+                    thread.start()
+                    self.assertTrue(entered.wait(2))
+                    replacement = root / "replacement.sqlite3"
+                    create_fts_database(replacement, [(2, "新数据库革命资料")])
+                    replacement.replace(path)
+                    databases.refresh()
+                    self.assertTrue(databases.retired_connections)
+                    release.set()
+                    thread.join(2)
+                    self.assertFalse(thread.is_alive())
+                self.assertEqual(result, [{1}])
+                self.assertFalse(databases.retired_connections)
+                self.assertEqual(databases.match_cache, {})
+                self.assertEqual(databases.search_source("CCRD", "革命"), {2})
+            finally:
+                release.set()
+                thread.join(2)
+                databases.close()
+
+
+class HttpIntegrationTests(unittest.TestCase):
+    def test_fulltext_in_memory_defaults_enabled(self):
+        self.assertTrue(app.FULLTEXT_IN_MEMORY)
+
+    @classmethod
+    def setUpClass(cls):
+        app.load_data()
+        cls.original_databases = app.fulltext_databases
+        app.fulltext_databases = app.FulltextDatabases(Path("/tmp/ccrd-test-no-index"))
+        cls.client = TestClient(app.app)
+
+    @classmethod
+    def tearDownClass(cls):
+        app.fulltext_databases.close()
+        app.fulltext_databases = cls.original_databases
+
+    def test_search_http_validation_and_option_isolation(self):
+        valid = self.client.post("/api/search", json={"q": "文化 革命", "fulltext": False, "page_size": 1})
+        self.assertEqual(valid.status_code, 200)
+        self.assertEqual(valid.json()["page_size"], 1)
+        self.assertEqual(self.client.post("/api/search", json={"q": "x" * 257}).status_code, 422)
+        self.assertEqual(self.client.post("/api/search", json={"page": 0}).status_code, 422)
+        self.assertEqual(self.client.post("/api/search", json={"page_size": 201}).status_code, 422)
+        self.assertEqual(self.client.post("/api/search", json={"min_size": -1}).status_code, 422)
+        self.assertEqual(self.client.post("/api/search/missing", json={}).status_code, 404)
+
+    def test_preview_snippet_and_download_http_contracts(self):
+        doc_id, record = next(iter(app.record_map.items()))
+        preview = self.client.get(f"/api/preview/{doc_id}")
+        self.assertEqual(preview.status_code, 200)
+        self.assertEqual(preview.json()["doc_id"], doc_id)
+        snippet = self.client.get(f"/api/snippet/{doc_id}", params={"q": "文化", "exact": "false"})
+        self.assertEqual(snippet.status_code, 200)
+        self.assertIn("snippet", snippet.json())
+        download = self.client.get(f"/api/download/{doc_id}")
+        self.assertEqual(download.status_code, 200)
+        self.assertTrue(download.headers["content-type"].startswith("text/plain"))
+        self.assertIn("attachment", download.headers["content-disposition"])
+        self.assertEqual(download.content, app.get_doc_storage_path(record).read_bytes())
+        self.assertEqual(self.client.get("/api/preview/missing:1").status_code, 404)
+        self.assertEqual(self.client.get("/api/snippet/missing:1").status_code, 404)
+        self.assertEqual(self.client.get("/api/download/missing:1").status_code, 404)
+        self.assertEqual(self.client.get(f"/api/snippet/{doc_id}", params={"q": "x" * 257}).status_code, 422)
+
+    def test_json_and_form_zip_are_valid_and_enforce_limits(self):
+        selected = sorted(app.records, key=lambda record: record["size"])[:2]
+        ids = [record["doc_id"] for record in selected]
+        for response in (
+            self.client.post("/api/zip", json={"doc_ids": ids}),
+            self.client.post(
+                "/api/zip-download",
+                content=urlencode([("doc_id", ids[0]), ("doc_id", ids[1]), ("doc_id", ids[0])]),
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            ),
+        ):
+            self.assertEqual(response.status_code, 200)
+            self.assertEqual(response.headers["content-type"], "application/zip")
+            self.assertIn("attachment", response.headers["content-disposition"])
+            self.assertEqual(response.headers["cache-control"], "no-store")
+            self.assertEqual(response.headers["content-encoding"], "identity")
+            self.assertEqual(int(response.headers["content-length"]), len(response.content))
+            self.assertTrue(response.content.startswith(b"PK"))
+            self.assertNotIn(b"PK\x06\x06", response.content)
+            with zipfile.ZipFile(io.BytesIO(response.content)) as archive:
+                self.assertEqual(len(archive.namelist()), 2)
+                self.assertEqual(archive.testzip(), None)
+            with self.assertRaises(zipfile.BadZipFile):
+                with zipfile.ZipFile(io.BytesIO(response.content[:-22])) as truncated:
+                    truncated.testzip()
+        self.assertEqual(self.client.post("/api/zip", json={"doc_ids": []}).status_code, 400)
+        self.assertEqual(self.client.post("/api/zip", json={"doc_ids": ["x"] * 501}).status_code, 422)
+        too_many = [("doc_id", f"CCRD:{index}") for index in range(501)]
+        self.assertEqual(self.client.post(
+            "/api/zip-download",
+            content=urlencode(too_many),
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        ).status_code, 400)
+        self.assertEqual(self.client.post("/api/zip-download", json={"doc_id": ids}).status_code, 415)
+        self.assertEqual(self.client.get("/api/zip-download").status_code, 400)
+        legacy = self.client.post(
+            "/api/zip-download",
+            content=urlencode([("doc_id", ids[0]), ("doc_id", ids[1])]),
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            follow_redirects=False,
+        )
+        self.assertEqual(legacy.status_code, 303)
+        self.assertTrue(legacy.headers["location"].startswith("/api/zip-download/"))
+        legacy_download = self.client.get(legacy.headers["location"])
+        self.assertTrue(legacy_download.content.startswith(b"PK"))
+        prepared = self.client.post("/api/zip-prepare", json={"doc_ids": ids})
+        self.assertEqual(prepared.status_code, 200)
+        self.assertEqual(prepared.json()["file_count"], 2)
+        download_url = prepared.json()["download_url"]
+        for _attempt in range(2):
+            downloaded = self.client.get(download_url, headers={"Accept-Encoding": "gzip"})
+            self.assertEqual(downloaded.status_code, 200)
+            self.assertEqual(downloaded.headers["content-encoding"], "identity")
+            self.assertTrue(downloaded.content.startswith(b"PK"))
+            with zipfile.ZipFile(io.BytesIO(downloaded.content)) as archive:
+                self.assertEqual(len(archive.namelist()), 2)
+                self.assertIsNone(archive.testzip())
+        self.assertEqual(self.client.get("/api/zip-download/invalid-token").status_code, 404)
+
+    def test_zip_disambiguates_duplicate_display_paths_and_deduplicates_ids(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            first = root / "first.txt"
+            second = root / "second.txt"
+            first.write_text("first", encoding="utf-8")
+            second.write_text("second", encoding="utf-8")
+            original_map = app.record_map
+            app.record_map = {
+                "CCRD:1": {"source": "CCRD", "display_name": 'same:name*?"<>|', "display_rel_path": "same/name.txt"},
+                "CCRD:2": {"source": "CCRD", "display_name": 'same:name*?"<>|', "display_rel_path": "same/name.txt"},
+            }
+            paths = {"CCRD:1": first, "CCRD:2": second}
+            try:
+                with patch.object(app, "get_doc_storage_path", side_effect=lambda record: paths[next(key for key, value in app.record_map.items() if value is record)]):
+                    response = app.zip_response(["CCRD:1", "CCRD:1", "CCRD:2"])
+                self.assertEqual(response.status_code, 200)
+                with open(response.path, "rb") as archive_file:
+                    payload = archive_file.read()
+                self.assertNotIn(b"PK\x06\x06", payload)
+                with zipfile.ZipFile(io.BytesIO(payload)) as archive:
+                    self.assertEqual(len(set(archive.namelist())), 2)
+                    self.assertTrue(all(not any(character in name for character in ':*?"<>|\\') for name in archive.namelist()))
+                    self.assertTrue(all(len(name.encode("utf-8")) <= 220 for name in archive.namelist()))
+                    self.assertEqual(sorted(archive.read(name).decode() for name in archive.namelist()), ["first", "second"])
+            finally:
+                app.record_map = original_map
+
+    def test_static_status_and_cors_contracts(self):
+        self.assertEqual(self.client.get("/manifest.json").status_code, 200)
+        self.assertIn("javascript", self.client.get("/sw.js").headers["content-type"])
+        status = self.client.get("/api/index-status")
+        self.assertEqual(status.status_code, 200)
+        self.assertEqual(status.json()["loaded_sources"], [])
+        cors = self.client.options(
+            "/api/search",
+            headers={"Origin": "https://example.com", "Access-Control-Request-Method": "POST"},
+        )
+        self.assertEqual(cors.status_code, 200)
+        self.assertEqual(cors.headers["access-control-allow-origin"], "*")
+        self.assertEqual(self.client.get("/data/fulltext/CCRD.sqlite3").status_code, 404)
+        self.assertEqual(self.client.get("/data/fulltext/CCRD.sqlite3.tmp").status_code, 404)
+
+    def test_ping_is_empty_and_not_cached(self):
+        response = self.client.get("/api/ping")
+        self.assertEqual(response.status_code, 204)
+        self.assertEqual(response.content, b"")
+        self.assertEqual(response.headers["cache-control"], "no-store")
+
+    def test_sources_extensions_folders_random_and_spa_routes(self):
+        sources = self.client.get("/api/sources")
+        self.assertEqual(sources.status_code, 200)
+        self.assertEqual({item["slug"] for item in sources.json()}, {"CCRD", "CW"})
+        self.assertEqual(self.client.get("/api/extensions").json(), [{"name": "txt", "count": 47250}])
+        self.assertEqual(self.client.get("/api/extensions", params={"source": "CCRD"}).json(), [{"name": "txt", "count": 35586}])
+        folders = self.client.get("/api/folders/CCRD")
+        self.assertEqual(folders.status_code, 200)
+        self.assertIsInstance(folders.json(), list)
+        contents = self.client.get("/api/folders/CCRD/contents")
+        self.assertEqual(contents.status_code, 200)
+        self.assertEqual(contents.json()["current_path"], "")
+        random_doc = self.client.get("/api/random", params={"source": "CW"})
+        self.assertEqual(random_doc.status_code, 200)
+        self.assertEqual(random_doc.json()["Source"], "CW")
+        self.assertEqual(self.client.get("/api/random", params={"source": "missing"}).status_code, 404)
+        for route in ("/", "/CCRD", "/CW"):
+            page = self.client.get(route)
+            self.assertEqual(page.status_code, 200)
+            self.assertIn("text/html", page.headers["content-type"])
+            self.assertIn("initial-sidebar-data", page.text)
+
+    def test_search_cache_ttl_is_longer_than_burst_idle_gap(self):
+        self.assertGreaterEqual(app.SEARCH_CACHE_TTL_SECONDS, 300)
+
+    def test_search_cache_returns_identical_payload(self):
+        app.search_response_cache.clear()
+        body = {"q": "server-timing-unique-query", "fulltext": False, "page_size": 1}
+        first = self.client.post("/api/search", json=body)
+        second = self.client.post("/api/search", json=body)
+        self.assertEqual(first.status_code, 200)
+        self.assertEqual(first.json(), second.json())
+
+    def test_missing_physical_files_return_stable_errors(self):
+        original_map = app.record_map
+        app.record_map = {
+            "CCRD:missing": {
+                "display_name": "missing", "display_rel_path": "missing.txt", "source_name": "CCRD",
+                "storage_root": "CCRD", "storage_rel_path": "does-not-exist.txt",
+            }
+        }
+        try:
+            for endpoint in ("preview", "snippet", "download"):
+                response = self.client.get(f"/api/{endpoint}/CCRD:missing")
+                self.assertEqual(response.status_code, 404)
+                self.assertIn("missing file", response.json()["error"])
+        finally:
+            app.record_map = original_map
+
+
+class CorpusIntegrityTests(unittest.TestCase):
+    def test_metadata_counts_and_every_storage_file_exists(self):
+        payload = json.loads(gzip.decompress((Path(app.BASE_DIR) / "data/search_data.json.gz").read_bytes()))
+        records = payload["records"]
+        self.assertEqual(len(records), 47250)
+        counts = {source["slug"]: source["count"] for source in payload["sources"]}
+        self.assertEqual(counts, {"CCRD": 35586, "CW": 11664})
+        doc_ids = {record["doc_id"] for record in records}
+        self.assertEqual(len(doc_ids), len(records))
+        missing = [
+            record["doc_id"] for record in records
+            if not (Path(app.BASE_DIR) / record["storage_root"] / record["storage_rel_path"]).is_file()
+        ]
+        self.assertEqual(missing, [])
+        self.assertEqual(sum(record["source"] == "CCRD" for record in records), 35586)
+        self.assertEqual(sum(record["source"] == "CW" for record in records), 11664)
+        archive_keys = [(record["source"], record["display_rel_path"], record["doc_id"]) for record in records]
+        self.assertEqual(len(archive_keys), len(set(archive_keys)))

tests/test_live_smoke.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import json
+import io
+import os
+import time
+import unittest
+import zipfile
+from http.client import RemoteDisconnected
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+BASE_URL = os.environ.get("CCRD_LIVE_BASE_URL", "").rstrip("/")
+
+
+@unittest.skipUnless(BASE_URL, "set CCRD_LIVE_BASE_URL to run deployment smoke tests")
+class LiveSmokeTests(unittest.TestCase):
+    def request_json(self, path: str, payload: dict | None = None):
+        data = json.dumps(payload).encode() if payload is not None else None
+        for attempt in range(3):
+            request = Request(
+                BASE_URL + path,
+                data=data,
+                headers={"Content-Type": "application/json"} if data else {},
+            )
+            try:
+                with urlopen(request, timeout=45) as response:
+                    self.assertEqual(response.status, 200)
+                    return json.load(response)
+            except HTTPError as exc:
+                if exc.code < 500 or attempt == 2:
+                    raise
+            except (RemoteDisconnected, TimeoutError, URLError):
+                if attempt == 2:
+                    raise
+            time.sleep(attempt + 1)
+        self.fail("request retries exhausted")
+
+    def request_text(self, path: str):
+        with urlopen(BASE_URL + path, timeout=45) as response:
+            self.assertEqual(response.status, 200)
+            return response.read().decode("utf-8")
+
+    def test_sources_and_extensions_match_corpus(self):
+        sources = self.request_json("/api/sources")
+        self.assertEqual({item["slug"] for item in sources}, {"CCRD", "CW"})
+        self.assertEqual(sum(item["count"] for item in sources), 47250)
+        extensions = self.request_json("/api/extensions")
+        self.assertEqual(extensions, [{"name": "txt", "count": 47250}])
+
+    def test_exact_fulltext_results_contain_contiguous_query(self):
+        status = self.request_json("/api/index-status")
+        if not status.get("ready"):
+            self.skipTest(f'fulltext indexes still building: {status.get("building_sources", [])}')
+        payload = self.request_json("/api/search", {
+            "q": "手机",
+            "page": 1,
+            "page_size": 5,
+            "exact": True,
+            "fulltext": True,
+        })
+        self.assertGreater(payload["total"], 0)
+        self.assertLessEqual(len(payload["results"]), 5)
+        for item in payload["results"]:
+            preview = self.request_json(f'/api/preview/{item["doc_id"]}')
+            searchable = " ".join([item.get("DisplayPath", ""), preview.get("text", "")])
+            self.assertIn("手机", searchable)
+
+    def test_source_filter_and_pagination_are_stable(self):
+        request = {
+            "q": "文化 革命",
+            "page": 1,
+            "page_size": 5,
+            "exact": False,
+            "fulltext": True,
+        }
+        first = self.request_json("/api/search/CCRD", request)
+        request["page"] = 2
+        second = self.request_json("/api/search/CCRD", request)
+        first_ids = {item["doc_id"] for item in first["results"]}
+        second_ids = {item["doc_id"] for item in second["results"]}
+        self.assertTrue(first_ids)
+        self.assertTrue(second_ids)
+        self.assertTrue(first_ids.isdisjoint(second_ids))
+        self.assertTrue(all(item["Source"] == "CCRD" for item in first["results"] + second["results"]))
+
+    def test_deployed_ui_contains_controls_and_matching_javascript(self):
+        html = self.request_text("/")
+        javascript = self.request_text("/static/app.js")
+        css = self.request_text("/static/style.css")
+        for control_id in (
+            "hamburger-btn", "search-input", "settings-btn", "theme-btn", "mobile-toggle-btn",
+            "multi-select-toggle", "multi-select-all", "multi-deselect", "multi-batch-download",
+            "multi-zip-download", "fulltext-toggle", "search-paths-toggle", "history-toggle",
+            "exact-search-toggle", "folder-select-all", "folder-deselect-all", "source-filter-cancel",
+            "folder-filter-cancel", "random-book-btn",
+        ):
+            self.assertIn(f'id="{control_id}"', html)
+        for binding in (
+            "DOM.hamburgerBtn.addEventListener", "DOM.searchInput.addEventListener",
+            "DOM.multiBatchDownload.addEventListener", "DOM.multiZipDownload.addEventListener",
+            "DOM.resultsList.addEventListener", "DOM.previewPanel.addEventListener",
+        ):
+            self.assertIn(binding, javascript)
+        self.assertIn(".result-snippet", css)
+
+    def test_deployed_zip_is_not_http_gzipped_and_opens(self):
+        prepared = self.request_json("/api/zip-prepare", {"doc_ids": ["CCRD:0", "CW:0"]})
+        request = Request(
+            BASE_URL + prepared["download_url"],
+            headers={
+                "Accept-Encoding": "gzip",
+            },
+        )
+        with urlopen(request, timeout=120) as response:
+            payload = response.read()
+            self.assertEqual(response.status, 200)
+            self.assertEqual(response.headers.get("Content-Encoding"), "identity")
+            self.assertEqual(int(response.headers["Content-Length"]), len(payload))
+        self.assertTrue(payload.startswith(b"PK"))
+        self.assertNotIn(b"PK\x06\x06", payload)
+        with zipfile.ZipFile(io.BytesIO(payload)) as archive:
+            self.assertEqual(len(archive.namelist()), 2)
+            self.assertIsNone(archive.testzip())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_ocr_release.py

@@ -0,0 +1,168 @@
+"""Tiny real SQLite/text candidates; never open/rebuild production databases."""
+import copy
+import gzip
+import hashlib
+import json
+from pathlib import Path
+import tempfile
+import unittest
+from unittest.mock import patch
+
+import app
+import build_fulltext_db as builder
+import ocr_release as release
+from fastapi.testclient import TestClient
+
+
+class OcrReleaseTests(unittest.TestCase):
+    def setUp(self):
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.root = Path(temporary.name)
+        self.bucket = self.root / "bucket"
+        self.bucket.mkdir()
+        self.base = self.root / "base.json.gz"
+        base_record = {"doc_id": "CCRD:1", "source": "CCRD", "source_name": "CCRD",
+                       "storage_root": "CCRD", "storage_rel_path": "old.txt", "display_name": "旧文件",
+                       "display_dirs": [], "display_rel_path": "旧文件.txt", "size": 7, "extension": "txt"}
+        self.base.write_bytes(gzip.compress(json.dumps({"records": [base_record], "sources": [
+            {"slug": "CCRD", "name": "CCRD", "count": 1}]}).encode(), mtime=0))
+        self.base_sha = hashlib.sha256(self.base.read_bytes()).hexdigest()
+        self.content = "手机文化\n\n\n\n末页手。机 ABC"
+        texts = ["手机文化", "", "末页手。机 ABC"]
+        body = self.content.encode()
+        txt_sha = release.digest(body)
+        text_ref = {"bucket": release.BUCKET, "path": f"text/objects/{txt_sha[:2]}/{txt_sha}.txt",
+                    "sha256": txt_sha, "bytes": len(body), "role": "runtime"}
+        self.write(text_ref["path"], body)
+        original = "原目录/book.pdf"
+        identity = {"recipe": "ocr-plain-utf8-pages-v1", "origin_repo": "VoiceOfML/Test", "origin_rel_path": original,
+                    "origin_revision": "b" * 40, "source_sha256": "a" * 64, "doc_id": "OCR:1",
+                    "text_generation": "c" * 64, "txt_sha256": txt_sha}
+        generation = release.digest(release.canonical(identity).rstrip(b"\n"))
+        book_id = release.digest(("VoiceOfML/Test\0" + original).encode())
+        pages, cursor = [], 0
+        for number, text in enumerate(texts, 1):
+            pages.append({"page": number, "start": cursor, "end": cursor + len(text),
+                          "text_sha256": release.digest(text.encode()), "text_generation": str(number) * 64,
+                          "quality": "partially-reviewed" if number == 1 else "unreviewed"})
+            cursor += len(text) + 2
+        self.export = {"version": 1, "kind": "ccrd-ocr-text-export", "complete": True, **identity,
+                       "generation": generation, "book_id": book_id, "title": "book", "page_count": 3,
+                       "readable_rel_path": "VoiceOfML/Test/原目录/book.txt", "accepted_pages": 1,
+                       "quality": "partially-reviewed", "offset_unit": "unicode-codepoint", "page_separator": "\n\n",
+                       "pages": pages, "text": text_ref,
+                       "retained_reader_resources": [{"bucket": "vomebook/pdf-pages-v2", "path": "objects/aa/reading-manifest.json",
+                                                      "sha256": "a" * 64, "bytes": 1, "role": "provenance"}]}
+        self.export_path = f"text/exports/{book_id}/{generation}/manifest.json"
+        self.export_ref = self.ref(self.export_path, release.canonical(self.export))
+        core = {"version": 1, "kind": "ccrd-ocr-search-release", "base_metadata_sha256": self.base_sha,
+                "builder_sha256": release.digest(Path(builder.__file__).read_bytes()), "tokenizer_version": release.TOKENIZER,
+                "exports": [self.export_ref]}
+        generation = release.digest(release.canonical(core))
+        records = [release.export_record(self.bucket, self.export_ref)[0]]
+        db_relative = f"indexes/ocr/{generation}/OCR.sqlite3"
+        directory = self.bucket / Path(db_relative).parent
+        directory.mkdir(parents=True)
+        with patch.object(builder, "BASE_DIR", self.bucket), patch.object(builder, "FULLTEXT_DIR", directory):
+            builder.build_source_db("OCR", records)
+        self.manifest = {**core, "generation": generation, "documents": 1,
+                         "database": self.ref(db_relative, (self.bucket / db_relative).read_bytes())}
+        self.manifest_path = f"releases/ocr-{generation}/manifest.json"
+        raw = release.canonical(self.manifest)
+        self.write(self.manifest_path, raw)
+        self.manifest_sha = release.digest(raw)
+
+    def write(self, path, body):
+        target = self.bucket / path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(body)
+
+    def ref(self, path, body):
+        self.write(path, body)
+        return {"bucket": release.BUCKET, "path": path, "sha256": release.digest(body), "bytes": len(body), "role": "runtime"}
+
+    def load(self):
+        return release.load_release(self.bucket, self.manifest_path, self.manifest_sha, self.base_sha)
+
+    def test_whole_release_is_verified_and_origin_hierarchy_is_preserved(self):
+        candidate = self.load()
+        self.assertEqual(candidate["records"][0]["display_rel_path"], "VoiceOfML/Test/原目录/book.txt")
+        self.assertEqual(candidate["text_paths"]["OCR:1"].read_text(), self.content)
+        self.assertEqual(candidate["tree"][0]["count"], 1)
+        self.assertEqual(candidate["browser"]["VoiceOfML/Test/原目录"]["files"][0]["doc_id"], "OCR:1")
+
+    def test_corrupt_text_or_database_blocks_the_release(self):
+        for ref in (self.export["text"], self.manifest["database"]):
+            target = self.bucket / ref["path"]
+            original = target.read_bytes()
+            try:
+                target.write_bytes(original + b"damage")
+                with self.assertRaisesRegex(ValueError, "checksum"):
+                    self.load()
+            finally:
+                target.write_bytes(original)
+
+    def test_wrong_manifest_or_base_identity_cannot_activate(self):
+        for manifest_sha, base_sha in (("d" * 64, self.base_sha), (self.manifest_sha, "e" * 64)):
+            with self.subTest(manifest_sha=manifest_sha), self.assertRaises(ValueError):
+                release.load_release(self.bucket, self.manifest_path, manifest_sha, base_sha)
+
+    def test_export_page_offsets_and_missing_provenance_are_rejected(self):
+        for change in ({"pages": []}, {"retained_reader_resources": []}, {"readable_rel_path": "wrong/book.txt"},
+                       {"accepted_pages": 3}, {"origin_repo": "../bad"}):
+            value = {**copy.deepcopy(self.export), **change}
+            ref = self.ref(self.export_path, release.canonical(value))
+            with self.subTest(change=list(change)), self.assertRaises(ValueError):
+                release.export_record(self.bucket, ref)
+
+    def test_pin_copies_verified_data_and_is_independent_of_the_mount(self):
+        pinned = release.pin_release(self.bucket, self.manifest_path, self.manifest_sha, self.base_sha, self.root / "cache")
+        self.assertNotIn(self.bucket, pinned["database"].parents)
+        self.assertEqual(pinned["text_paths"]["OCR:1"].read_text(), self.content)
+        self.write(self.export["text"]["path"], b"changed remote mount")
+        self.assertEqual(pinned["text_paths"]["OCR:1"].read_text(), self.content)
+
+    def test_small_index_uses_existing_in_memory_search_contract(self):
+        candidate = self.load()
+        databases = app.FulltextDatabases(self.root / "empty-db", in_memory=True, extra_paths=[candidate["database"]])
+        try:
+            self.assertEqual(databases.search_source("OCR", "手机", exact=False), {1})
+            self.assertEqual(databases.search_source("OCR", "手。机", exact=True), {1})
+            self.assertEqual(databases.search_source("OCR", "文化 ABC", exact=False), {1})
+            self.assertEqual(databases.search_source("OCR", "手机 ABC", exact=True), set())
+            self.assertEqual(databases.connections["OCR"].execute("PRAGMA database_list").fetchone()[2], "")
+        finally:
+            databases.close()
+
+    def test_startup_loads_one_pinned_release_and_serves_plain_txt(self):
+        tree, browser = self.root / "tree.gz", self.root / "browser.gz"
+        tree.write_bytes(gzip.compress(b'{"CCRD":[]}')); browser.write_bytes(gzip.compress(b'{"CCRD":{}}'))
+        saved = {key: getattr(app, key) for key in ("records", "record_map", "record_map_index", "sources", "source_counts",
+                 "folder_tree_data", "folder_browser_data", "active_ocr_release")}
+        try:
+            with patch.dict("os.environ", {"CCRD_INDEX_BUCKET_DIR": str(self.bucket), "CCRD_OCR_RELEASE_PATH": self.manifest_path,
+                                          "CCRD_OCR_RELEASE_SHA256": self.manifest_sha}), \
+                    patch.object(app, "DATA_PATH", self.base), patch.object(app, "FOLDER_TREE_PATH", tree), \
+                    patch.object(app, "FOLDER_BROWSER_PATH", browser), patch.object(app, "BASE_DIR", self.root):
+                app.load_data()
+            self.assertEqual(app.source_counts, {"CCRD": 1, "OCR": 1})
+            self.assertEqual(app.record_map["CCRD:1"]["display_name"], "旧文件")
+            client = TestClient(app.app)
+            response = client.get("/txt/OCR/VoiceOfML/Test/原目录/book.txt")
+            self.assertEqual(response.status_code, 200)
+            self.assertEqual(response.text, self.content)
+            self.assertIn("inline", response.headers["content-disposition"])
+            self.assertEqual(client.get("/txt/OCR/missing.txt").status_code, 404)
+            self.assertEqual(client.get("/api/preview/OCR:1").json()["text"], self.content)
+            self.assertEqual(json.loads(app.sidebar_payload_for_path(""))["sources"][-1]["slug"], "OCR")
+            self.assertEqual(app.zip_entries(["OCR:1"])[0][0], "OCR成果/VoiceOfML/Test/原目录/book.txt")
+            self.assertEqual(client.get("/data/sidebar/global.json").json()["sources"][-1]["slug"], "OCR")
+            self.assertEqual(client.get("/data/initial/sources/OCR.json").json()["total"], 1)
+        finally:
+            for key, value in saved.items(): setattr(app, key, value)
+            app.build_indexes()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_prepare_fulltext_index.py

@@ -0,0 +1,135 @@
+import hashlib
+import json
+import os
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PREPARE = ROOT / "prepare_fulltext_index.py"
+TOKENIZER_VERSION = "cjk-bigram-boundary-fts5-v6-snippet-anchors"
+
+
+def create_database(path: Path, doc_id: str) -> str:
+    with sqlite3.connect(path) as connection:
+        connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+        connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (TOKENIZER_VERSION,))
+        connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+        connection.execute("INSERT INTO documents VALUES (?, 'summary')", (doc_id,))
+        connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+        connection.execute("INSERT INTO content_fts (rowid, content) VALUES (1, 'content')")
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+class PrepareFulltextIndexTests(unittest.TestCase):
+    def setUp(self):
+        self.temporary = tempfile.TemporaryDirectory()
+        self.root = Path(self.temporary.name)
+        self.bucket = self.root / "bucket"
+        self.generation = self.bucket / "generations/test"
+        self.generation.mkdir(parents=True)
+        self.fulltext = self.root / "fulltext"
+
+    def tearDown(self):
+        self.temporary.cleanup()
+
+    def write_manifest(self, hashes):
+        self.bucket.joinpath("current.json").write_text(json.dumps({
+            "format": 1,
+            "tokenizer_version": TOKENIZER_VERSION,
+            "databases": {
+                source: {
+                    "path": f"generations/test/{source}.sqlite3",
+                    "sha256": digest,
+                    "bytes": (self.generation / f"{source}.sqlite3").stat().st_size,
+                    "documents": 1,
+                    "fts_rows": 1,
+                }
+                for source, digest in hashes.items()
+            },
+        }), encoding="utf-8")
+
+    def run_prepare(self):
+        environment = os.environ | {
+            "CCRD_INDEX_BUCKET_DIR": str(self.bucket),
+            "CCRD_FULLTEXT_DIR": str(self.fulltext),
+        }
+        return subprocess.run([sys.executable, str(PREPARE)], env=environment, capture_output=True, text=True)
+
+    def test_activates_verified_bucket_generation(self):
+        hashes = {
+            source: create_database(self.generation / f"{source}.sqlite3", f"{source}:1")
+            for source in ("CCRD", "CW")
+        }
+        self.write_manifest(hashes)
+        newer = self.bucket / "generations/ccrd-newer"
+        newer.mkdir(parents=True)
+        for source in ("CCRD", "CW"):
+            create_database(newer / f"{source}.sqlite3", f"{source}:newer")
+
+        result = self.run_prepare()
+
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        status = json.loads((self.fulltext / "bucket-index-status.json").read_text())
+        self.assertEqual(status['state'], 'ready')
+        for source in hashes:
+            target = self.fulltext / f"{source}.sqlite3"
+            self.assertTrue(target.is_file())
+            self.assertFalse(target.is_symlink())
+            self.assertEqual(target.read_bytes(), (self.generation / f"{source}.sqlite3").read_bytes())
+
+    def test_rejects_invalid_hash_format(self):
+        hashes = {
+            source: create_database(self.generation / f"{source}.sqlite3", f"{source}:1")
+            for source in ("CCRD", "CW")
+        }
+        hashes["CW"] = "not-a-sha256"
+        self.write_manifest(hashes)
+
+        result = self.run_prepare()
+
+        self.assertNotEqual(result.returncode, 0)
+        status = json.loads((self.fulltext / "bucket-index-status.json").read_text())
+        self.assertEqual(status['state'], 'unavailable')
+        self.assertEqual(status['error'], 'ValueError')
+        self.assertFalse((self.fulltext / "CCRD.sqlite3").exists())
+
+    def test_recovers_from_stale_pointer_with_latest_complete_generation(self):
+        latest = self.bucket / "generations/ccrd-new"
+        latest.mkdir(parents=True)
+        for source in ("CCRD", "CW"):
+            create_database(latest / f"{source}.sqlite3", f"{source}:latest")
+        self.bucket.joinpath("current.json").write_text(json.dumps({
+            "format": 1,
+            "tokenizer_version": TOKENIZER_VERSION,
+            "databases": {
+                source: {
+                    "path": f"generations/ccrd-old/{source}.sqlite3",
+                    "sha256": "0" * 64,
+                    "bytes": 1,
+                    "documents": 1,
+                    "fts_rows": 1,
+                }
+                for source in ("CCRD", "CW")
+            },
+        }), encoding="utf-8")
+
+        result = self.run_prepare()
+
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        status = json.loads((self.fulltext / "bucket-index-status.json").read_text())
+        self.assertEqual(status["state"], "ready")
+        self.assertEqual(status["pointer_error"]["error"], "ValueError")
+        for source in ("CCRD", "CW"):
+            self.assertEqual(
+                (self.fulltext / f"{source}.sqlite3").read_bytes(),
+                (latest / f"{source}.sqlite3").read_bytes(),
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_search.py

@@ -0,0 +1,1214 @@
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import tempfile
+import unittest
+from html.parser import HTMLParser
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import app
+import build_fulltext_db
+
+
+class InteractiveIdParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.ids = set()
+
+    def handle_starttag(self, tag, attrs):
+        values = dict(attrs)
+        if tag in {"button", "input", "select", "a"} and values.get("id"):
+            self.ids.add(values["id"])
+
+
+def encode_doc_numbers(numbers: list[int]) -> bytes:
+    return build_fulltext_db.encode_doc_ids(numbers)
+
+
+class TokenizationTests(unittest.TestCase):
+    def test_normalized_snippet_payload_matches_current_path(self):
+        text = build_fulltext_db.fts_content("前文\nＡＢＣ 与 文化 革命，后文。")
+        self.assertEqual(
+            app.build_normalized_snippet_payload(text, "文化 革命"),
+            app.build_snippet_payload(text, "文化 革命"),
+        )
+
+    def test_normalized_exact_snippet_payload_matches_current_path(self):
+        text = build_fulltext_db.fts_content("前文\nＡＢＣ 与 文化革命，后文。")
+        self.assertEqual(
+            app.build_normalized_exact_snippet_payload(text, "文化革命"),
+            app.build_snippet_payload(text, "文化革命", exact=True),
+        )
+
+    def test_normalizes_latin_and_indexes_chinese_unigrams_and_bigrams(self):
+        self.assertEqual(app.query_terms("ＡＢＣ 手机"), ["abc", "手机"])
+        self.assertEqual(app.query_tokens("文化革命"), ["文化", "化革", "革命"])
+        self.assertEqual(app.index_tokens("手机"), {"手", "机", "手机"})
+
+    def test_builder_and_runtime_tokenizers_stay_in_sync(self):
+        text = "文化革命 ABC 手机"
+        self.assertEqual(app.index_tokens(text), build_fulltext_db.index_tokens(text))
+        expected_hashes = {
+            hashlib.sha256(token.encode("utf-8")).digest()[:16]
+            for token in build_fulltext_db.index_tokens(text) | build_fulltext_db.literal_tokens(text)
+        }
+        self.assertEqual(build_fulltext_db.token_hashes(text), expected_hashes)
+
+    def test_literal_tokens_preserve_punctuation_boundaries(self):
+        self.assertEqual(app.literal_query_tokens("手。机"), ["\0literal:手。机"])
+        self.assertEqual(
+            set(app.literal_query_tokens("手。机")),
+            build_fulltext_db.literal_tokens("手。机"),
+        )
+        self.assertEqual(app.literal_query_tokens("文化革命"), [])
+        self.assertEqual(app.literal_query_tokens("手。机文化"), ["\0literal:手。机"])
+
+    def test_snippet_anchors_use_normalized_character_offsets_for_all_token_types(self):
+        anchors = build_fulltext_db.snippet_anchors("ＡＢＣ 手机 手。机")
+        offset_for = lambda token: anchors[hashlib.sha256(token.encode("utf-8")).digest()[:16]]
+        self.assertEqual(offset_for("abc"), 0)
+        self.assertEqual(offset_for("手机"), 4)
+        self.assertEqual(offset_for("手"), 4)
+        self.assertEqual(offset_for("\0literal:手。机"), 7)
+
+    def test_exact_wildcards_are_non_greedy_and_cross_newlines(self):
+        self.assertTrue(app.matches_exact_query("手\n持电话机", "手*机"))
+        self.assertTrue(app.matches_exact_query("手机", "手?"))
+        self.assertFalse(app.matches_exact_query("手持电话机", "手?机"))
+
+    def test_wildcard_required_tokens_keep_only_cjk_fixed_parts(self):
+        self.assertEqual(app.wildcard_required_tokens("手*机"), ["手", "机"])
+        self.assertEqual(app.wildcard_required_tokens("文化*资料"), ["文化", "资料"])
+        self.assertEqual(app.wildcard_required_tokens("ABC*文化"), ["文化"])
+
+
+class MetadataSearchTests(unittest.TestCase):
+    def setUp(self):
+        self.original_records = app.records
+        self.original_sources = app.source_counts
+        app.records = [
+            self.record("CCRD:0", "文化革命资料", ["历史"]),
+            self.record("CCRD:1", "文化资料", ["革命文献"]),
+            self.record("CW:2", "革命资料", ["其他"]),
+        ]
+        app.source_counts = {"CCRD": 2, "CW": 1}
+        app.build_indexes()
+
+    def tearDown(self):
+        app.records = self.original_records
+        app.source_counts = self.original_sources
+        app.build_indexes()
+
+    @staticmethod
+    def record(doc_id: str, name: str, dirs: list[str]) -> dict:
+        source = doc_id.split(":", 1)[0]
+        path = "/".join([*dirs, name + ".txt"])
+        return {
+            "doc_id": doc_id,
+            "source": source,
+            "source_name": source,
+            "display_name": name,
+            "display_dirs": dirs,
+            "display_rel_path": path,
+            "extension": ".txt",
+            "size": 100,
+            "storage_root": source,
+            "storage_rel_path": path,
+        }
+
+    def test_multiple_terms_are_and_not_or(self):
+        result = app.search("文化 革命")
+        self.assertEqual(result["total"], 2)
+        self.assertEqual({item["doc_id"] for item in result["results"]}, {"CCRD:0", "CCRD:1"})
+
+    def test_metadata_prefilter_keeps_shared_postings_and_matches_direct_intersection(self):
+        snapshot = {token: set(indices) for token, indices in app.word_index.items()}
+        for terms in (["文化", "革命"], ["革命", "文化"], ["文化革命"], ["不存在"], ["文化", "文化"], ["。"], []):
+            expected = None
+            for term in terms:
+                for token in app.query_tokens(term):
+                    posting = snapshot.get(token, set())
+                    expected = set(posting) if expected is None else expected & posting
+            with self.subTest(terms=terms):
+                self.assertEqual(app.metadata_prefilter(terms, True), expected)
+                self.assertEqual(app.word_index, snapshot)
+
+    def test_mixed_latin_metadata_candidates_keep_path_option_and_substrings(self):
+        app.records = [
+            self.record("CCRD:0", "文化 ABC123", []),
+            self.record("CCRD:1", "文化", ["ABC123"]),
+            self.record("CW:2", "革命 ABC123", []),
+        ]
+        app.build_indexes()
+        for paths, expected in ((True, {0, 1}), (False, {0})):
+            for terms in (["文化", "abc"], ["abc", "文化"]):
+                self.assertEqual(app.metadata_prefilter(terms, paths), expected)
+
+    def test_search_paths_false_excludes_path_only_match(self):
+        result = app.search("革命", search_paths=False)
+        self.assertEqual({item["doc_id"] for item in result["results"]}, {"CCRD:0", "CW:2"})
+
+    def test_filters_sorting_and_pagination_are_stable(self):
+        app.records[0]["size"] = 50
+        app.records[1]["size"] = 200
+        app.build_indexes()
+        result = app.search("文化", sources_filter=["CCRD"], min_size=100, sort="size", page_size=1)
+        self.assertEqual(result["total"], 1)
+        self.assertEqual(result["results"][0]["doc_id"], "CCRD:1")
+
+    def test_directory_filter_preserves_boundaries_and_root_semantics(self):
+        app.records = [
+            self.record("CCRD:0", "one", []),
+            self.record("CCRD:1", "two", ["a"]),
+            self.record("CCRD:2", "three", ["a", "b"]),
+            self.record("CW:3", "four", ["ab"]),
+            self.record("CW:4", "five", ["x", "y"]),
+            self.record("CW:5", "six", ["", "a"]),
+            self.record("CW:6", "seven", ["a", "", "b"]),
+        ]
+        for folders in ([], [""], ["a"], ["a", "x"], ["", "a"], ["a/", "x/y"], ["missing", "ab"], ["a", "a"]):
+            for sources in (None, [], ["CCRD"], ["CCRD", "CW"]):
+                with self.subTest(folders=folders, sources=sources):
+                    expected = [
+                        idx for idx, rec in enumerate(app.records)
+                        if (sources is None or rec["source"] in sources)
+                        and (not folders or any(
+                            "/".join(rec["display_dirs"]) == folder
+                            or "/".join(rec["display_dirs"]).startswith(folder + "/")
+                            for folder in folders
+                        ))
+                    ]
+                    self.assertEqual(app.apply_filters(range(len(app.records)), sources, folders), expected)
+
+    def test_unfiltered_candidates_do_not_read_record_fields(self):
+        with patch.object(app, "records", [None, None, None]):
+            self.assertEqual(app.apply_filters(iter([2, 0, 1])), [2, 0, 1])
+
+    def test_precomputed_name_and_size_orders_match_previous_sort_keys(self):
+        app.records[0]["size"] = 50
+        app.records[1]["size"] = 200
+        app.records[2]["size"] = 200
+        app.build_indexes()
+        expected_name = sorted(
+            range(len(app.records)),
+            key=lambda idx: (app.records[idx]["display_rel_path"].lower(), app.records[idx]["doc_id"]),
+        )
+        expected_size = sorted(
+            range(len(app.records)),
+            key=lambda idx: (-app.records[idx]["size"], app.records[idx]["display_rel_path"].lower(), app.records[idx]["doc_id"]),
+        )
+        self.assertEqual(app.name_order, expected_name)
+        self.assertEqual(app.size_order, expected_size)
+        self.assertEqual(app.source_name_order["CCRD"], [idx for idx in expected_name if app.records[idx]["source"] == "CCRD"])
+        self.assertEqual(app.source_size_order["CCRD"], [idx for idx in expected_size if app.records[idx]["source"] == "CCRD"])
+        self.assertEqual(app.ordered_page(set(range(len(app.records))), app.size_order, 1, 2), expected_size[1:3])
+
+    def test_sparse_ordered_pages_match_global_order_with_ties(self):
+        app.records = [
+            self.record(f"CCRD:{number}", "Name" if number % 2 else "name", [str(number % 3)])
+            for number in range(40)
+        ]
+        app.build_indexes()
+        for ordering in (app.name_order, app.size_order, list(reversed(app.name_order))):
+            for candidates in ([39, 2, 10, 1], list(range(40)), []):
+                expected = [idx for idx in ordering if idx in set(candidates)]
+                for start, page_size in ((0, 1), (0, 10), (1, 10), (4, 10), (30, 10)):
+                    with self.subTest(candidates=len(candidates), start=start, page_size=page_size):
+                        self.assertEqual(
+                            app.ordered_page(candidates, ordering, start, page_size),
+                            expected[start:start + page_size],
+                        )
+
+    def test_empty_global_and_single_source_queries_bypass_filtering_and_order_scan(self):
+        with patch.object(app, "apply_filters", side_effect=AssertionError("fast path scanned records")), \
+             patch.object(app, "ordered_page", side_effect=AssertionError("fast path scanned order")):
+            global_name = app.search("", sort="name", page=2, page_size=1)
+            source_size = app.search("", sources_filter=["CCRD"], sort="size", page_size=2)
+        self.assertEqual(global_name["results"][0]["doc_id"], app.records[app.name_order[1]]["doc_id"])
+        self.assertEqual(
+            [item["doc_id"] for item in source_size["results"]],
+            [app.records[idx]["doc_id"] for idx in app.source_size_order["CCRD"][:2]],
+        )
+
+    def test_empty_query_with_record_filters_keeps_general_path(self):
+        with patch.object(app, "apply_filters", wraps=app.apply_filters) as filtered:
+            result = app.search("", sources_filter=["CCRD"], min_size=100, sort="size")
+        filtered.assert_called_once()
+        self.assertEqual(result["total"], 2)
+
+    def test_bounded_relevance_page_matches_full_sort(self):
+        indices = list(range(len(app.records)))
+        tokens = app.query_tokens("文化 革命")
+        for search_paths in (False, True):
+            expected = sorted(
+                indices,
+                key=lambda idx: (
+                    -app.score_record(idx, tokens, search_paths),
+                    app.records[idx]["display_rel_path"].lower(),
+                    app.records[idx]["doc_id"],
+                ),
+            )
+            for start, page_size in ((0, 1), (1, 2), (2, 2)):
+                self.assertEqual(
+                    app.relevance_page(indices, tokens, search_paths, start, page_size),
+                    expected[start:start + page_size],
+                )
+
+    def test_heavy_relevance_pages_preserve_full_order_and_duplicates(self):
+        app.records = [self.record(f"CCRD:{number:05d}", ("文化" if number % 3 else "革命"), [str(number % 7)])
+                       for number in range(10020)]
+        app.build_indexes()
+        indices = list(range(len(app.records)))
+        for paths in (True, False):
+            tokens = app.query_tokens("文化 革命")
+            expected = sorted(indices, key=lambda idx: (
+                -app.score_record(idx, tokens, paths), app.records[idx]["_rank_path_key"], app.records[idx]["doc_id"],
+            ))
+            for start in (0, 100, 999, 1000, 5000, 9900, 10020):
+                self.assertEqual(app.relevance_page(indices, tokens, paths, start, 200), expected[start:start + 200])
+        duplicate_indices = indices + [0]
+        expected = sorted(duplicate_indices, key=lambda idx: (
+            -app.score_record(idx, tokens, True), app.records[idx]["_rank_path_key"], app.records[idx]["doc_id"],
+        ))
+        self.assertEqual(app.relevance_page(duplicate_indices, tokens, True, 1000, 200), expected[1000:1200])
+        self.assertEqual(app.relevance_page(duplicate_indices, tokens, True, 0, 200), expected[:200])
+
+    def test_shallow_relevance_stops_only_after_enough_maximum_score_hits(self):
+        app.records = [self.record(f"CCRD:{number}", "文化革命", ["same"])
+                       for number in range(10020)]
+        app.build_indexes()
+        candidates = list(range(len(app.records)))
+        for paths in (True, False):
+            with self.subTest(paths=paths), patch.object(app, "score_record", wraps=app.score_record) as scored:
+                self.assertEqual(app.relevance_page(candidates, ["文化", "革命"], paths, 100, 100), app.name_order[100:200])
+                self.assertEqual(scored.call_count, 200)
+        # A file-only source-name match cannot attain the path-inclusive maximum.
+        with patch.object(app, "score_record", wraps=app.score_record) as scored:
+            self.assertEqual(app.relevance_page(candidates, ["ccrd"], True, 0, 100), app.name_order[:100])
+            self.assertEqual(scored.call_count, len(candidates))
+
+    def test_numeric_fulltext_mapping_preserves_source_identity_and_missing_ids(self):
+        app.records = [
+            self.record("CW:0", "first", []),
+            self.record("CCRD:0", "second", []),
+            self.record("CCRD:7", "third", []),
+            self.record("CCRD:007", "padded", []),
+            self.record("CCRD:invalid", "invalid", []),
+        ]
+        app.build_indexes()
+        fake = MagicMock()
+        fake.search_source.side_effect = lambda source, q, exact: {0, 7, 99}
+        with patch.object(app, "fulltext_databases", fake), \
+             patch.object(app, "add_summaries", side_effect=lambda items, *args, **kwargs: items):
+            result = app.fulltext_search("missing", sort="name")
+            self.assertEqual(result["total"], 3)
+            self.assertEqual({item["doc_id"] for item in result["results"]}, {"CW:0", "CCRD:0", "CCRD:7"})
+            cw = app.fulltext_search("missing", sources_filter=["CW"])
+            self.assertEqual([item["doc_id"] for item in cw["results"]], ["CW:0"])
+            self.assertEqual(app.fulltext_search("missing", sources_filter=["unknown"])["total"], 0)
+        app.records = [self.record("CCRD:99", "replacement", [])]
+        app.build_indexes()
+        self.assertEqual(app.source_doc_number_index, {"CCRD": {99: 0}})
+
+    def test_shallow_relevance_falls_back_when_maximum_score_hits_are_insufficient(self):
+        app.records = [self.record(f"CCRD:{number}", "文化革命" if number < 3 else "文化", ["same"])
+                       for number in range(10020)]
+        for record in app.records:
+            record["source_name"] = "文化 革命"
+        app.build_indexes()
+        candidates = list(reversed(range(len(app.records))))
+        tokens = ["文化", "革命"]
+        expected = sorted(candidates, key=lambda idx: (
+            -app.score_record(idx, tokens, True), app.records[idx]["_rank_path_key"], app.records[idx]["doc_id"],
+        ))
+        for start in (0, 100):
+            self.assertEqual(app.relevance_page(candidates, tokens, True, start, 100), expected[start:start + 100])
+
+    def test_fulltext_relevance_respects_search_paths_false(self):
+        original_databases = app.fulltext_databases
+        fake_databases = MagicMock()
+        fake_databases.search_source.return_value = set()
+        fake_databases.has_content_fts = {"CCRD": False, "CW": False}
+        fake_databases.summaries.return_value = {}
+        fake_databases.matched_snippets.return_value = {}
+        app.fulltext_databases = fake_databases
+        try:
+            result = app.fulltext_search("文化", search_paths=False)
+            expected = sorted(
+                app.metadata_matches("文化", False, False),
+                key=lambda idx: (-app.score_record(idx, app.query_tokens("文化"), False), app.records[idx]["display_rel_path"].lower()),
+            )
+            self.assertEqual([item["doc_id"] for item in result["results"]], [app.records[idx]["doc_id"] for idx in expected])
+        finally:
+            app.fulltext_databases = original_databases
+
+    def test_exact_metadata_index_matches_full_scan(self):
+        for query in ("文化革命", "革命资料", "不存在"):
+            indexed = app.metadata_matches(query, True, True)
+            scanned = {
+                idx for idx, record in enumerate(app.records)
+                if app.matches_exact_query(record["_search_text"], query)
+            }
+            self.assertEqual(indexed, scanned)
+
+    def test_exact_search_uses_metadata_candidate_path(self):
+        with patch.object(app, "metadata_matches", wraps=app.metadata_matches) as metadata_matches:
+            result = app.search("文化革命", exact=True)
+        metadata_matches.assert_called_once_with("文化革命", True, True)
+        self.assertEqual({item["doc_id"] for item in result["results"]}, {"CCRD:0"})
+
+    def test_metadata_match_cache_is_option_scoped_bounded_and_cleared_on_rebuild(self):
+        app.metadata_match_cache.clear()
+        with patch.object(app, "_metadata_matches_uncached", wraps=app._metadata_matches_uncached) as uncached:
+            first = app.metadata_matches("文化革命", True, True)
+            second = app.metadata_matches("文化革命", True, True)
+            self.assertEqual(first, second)
+            first.clear()
+            self.assertEqual(app.metadata_matches("文化革命", True, True), second)
+            self.assertEqual(uncached.call_count, 1)
+            app.metadata_matches("文化革命", True, False)
+            app.metadata_matches("文化 革命", False, True)
+            self.assertEqual(uncached.call_count, 3)
+        with patch.object(app, "METADATA_MATCH_CACHE_MAX_ENTRIES", 2):
+            app.metadata_matches("甲", False, True)
+            app.metadata_matches("乙", False, True)
+            app.metadata_matches("丙", False, True)
+        self.assertLessEqual(len(app.metadata_match_cache), 2)
+        app.build_indexes()
+        self.assertEqual(app.metadata_match_cache, {})
+
+    def test_metadata_cache_id_budget_never_truncates_results(self):
+        app.clear_metadata_match_cache()
+        with patch.object(app, "METADATA_MATCH_CACHE_MAX_TOTAL_IDS", 3), \
+                patch.object(app, "_metadata_matches_uncached", return_value={0, 1}):
+            for query in ("甲", "乙", "丙"):
+                self.assertEqual(app.metadata_matches(query, False, True), {0, 1})
+            self.assertEqual(sum(map(len, app.metadata_match_cache.values())), 2)
+            app.clear_metadata_match_cache()
+            with patch.object(app, "_metadata_matches_uncached", return_value={0, 1, 2, 3}) as search:
+                for _ in range(2):
+                    self.assertEqual(app.metadata_matches("oversized", False, True), {0, 1, 2, 3})
+                self.assertEqual(search.call_count, 2)
+                self.assertEqual(app.metadata_match_cache, {})
+
+    def test_old_metadata_computation_cannot_repopulate_after_invalidation(self):
+        app.clear_metadata_match_cache()
+        def old_result(*_args):
+            app.clear_metadata_match_cache()
+            return {99}
+        with patch.object(app, "_metadata_matches_uncached", side_effect=old_result):
+            self.assertEqual(app.metadata_matches("文化", False, True), {99})
+        self.assertEqual(app.metadata_match_cache, {})
+        with patch.object(app, "_metadata_matches_uncached", side_effect=RuntimeError("failure")):
+            with self.assertRaises(RuntimeError):
+                app.metadata_matches("文化", False, True)
+        self.assertEqual(app.metadata_match_cache, {})
+
+    def test_exact_metadata_wildcard_preserves_full_scan_semantics(self):
+        for query in ("文化*资料", "手?机", "*文化*"):
+            indexed = app.metadata_matches(query, True, True)
+            scanned = {
+                idx for idx, record in enumerate(app.records)
+                if app.matches_exact_query(record["_search_text"], query)
+            }
+            self.assertEqual(indexed, scanned)
+
+    def test_exact_and_normal_latin_metadata_substrings_are_not_lost(self):
+        app.records[0]["display_name"] = "smartphone"
+        app.records[0]["display_rel_path"] = "folder/smartphone.txt"
+        app.build_indexes()
+        self.assertIn(0, app.metadata_matches("phone", True, False))
+        self.assertIn(0, app.metadata_matches("phone", False, False))
+
+
+class FulltextDatabaseTests(unittest.TestCase):
+    def test_uses_rarest_posting_first_and_intersects_all_tokens(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                for token, numbers in (("文化", [1, 2, 3]), ("化革", [2]), ("革命", [2, 3])):
+                    token_hash = hashlib.sha256(token.encode()).digest()[:16]
+                    connection.execute("INSERT INTO postings VALUES (?, ?, ?)", (token_hash, encode_doc_numbers(numbers), len(numbers)))
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                self.assertEqual(databases.search_source("CCRD", "文化革命"), {2})
+            finally:
+                databases.close()
+
+    def test_exact_phrase_uses_literal_postings(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                for token in [*app.query_tokens("手。机"), *app.literal_query_tokens("手。机")]:
+                    token_hash = hashlib.sha256(token.encode()).digest()[:16]
+                    connection.execute("INSERT INTO postings VALUES (?, ?, ?)", (token_hash, encode_doc_numbers([7]), 1))
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                self.assertEqual(databases.search_source("CCRD", "手。机", exact=True), {7})
+                self.assertEqual(databases.search_source("CCRD", "手机", exact=True), set())
+            finally:
+                databases.close()
+
+    def test_short_exact_query_uses_postings_before_verification(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+                for token in [*app.query_tokens("手机"), *app.literal_query_tokens("手机")]:
+                    token_hash = hashlib.sha256(token.encode()).digest()[:16]
+                    connection.execute("INSERT INTO postings VALUES (?, ?, ?)", (token_hash, encode_doc_numbers([7]), 1))
+                connection.execute("INSERT INTO content_fts(rowid, content) VALUES (?, ?)", (7, "这是手机测试"))
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                self.assertEqual(databases.search_source("CCRD", "手机", exact=True), {7})
+            finally:
+                databases.close()
+
+    def test_fts_content_strictly_verifies_wildcard_candidates(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+                connection.executemany("INSERT INTO content_fts(rowid, content) VALUES (?, ?)", [
+                    (1, "手持电话机"),
+                    (2, "手工劳动和机器"),
+                    (3, "只有手持机"),
+                    (4, "字面[手持机"),
+                ])
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                connection = databases.connections["CCRD"]
+                self.assertEqual(databases.verify_wildcard_content(connection, {1, 2, 3, 4}, "手?机"), {3, 4})
+                self.assertEqual(databases.verify_wildcard_content(connection, {1, 2, 3, 4}, "手*机"), {1, 2, 3, 4})
+                self.assertEqual(databases.verify_wildcard_content(connection, {1, 2, 3, 4}, "[手?机"), {4})
+            finally:
+                databases.close()
+
+    def test_large_wildcard_candidates_use_one_fts_scan_without_widening_results(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+                connection.executemany("INSERT INTO content_fts(rowid, content) VALUES (?, ?)",
+                    [(number, "文化资料" if number % 2 else "其他") for number in range(1, 10001)])
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                connection = databases.connections["CCRD"]
+                with patch.object(databases, "verify_wildcard_content", wraps=databases.verify_wildcard_content) as verifier:
+                    result = databases.verify_wildcard_content(connection, set(range(1, 10001)), "文化*资料", fts_filtered=True)
+                self.assertEqual(result, set(range(1, 10001, 2)))
+                verifier.assert_called_once()
+            finally:
+                databases.close()
+
+    def test_short_wildcard_uses_required_postings_before_fts_verification(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+                for token, numbers in (("手", [1, 2]), ("机", [1, 3])):
+                    token_hash = hashlib.sha256(token.encode()).digest()[:16]
+                    connection.execute("INSERT INTO postings VALUES (?, ?, ?)", (token_hash, encode_doc_numbers(numbers), len(numbers)))
+                connection.executemany("INSERT INTO content_fts(rowid, content) VALUES (?, ?)", [
+                    (1, "手持机"), (2, "手持电话"), (3, "机器"), (4, "手机"),
+                ])
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                self.assertEqual(databases.search_source("CCRD", "手*机", exact=True), {1})
+            finally:
+                databases.close()
+
+    def test_content_fts_returns_contiguous_cjk_phrase(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+                connection.execute("INSERT INTO content_fts(rowid, content) VALUES (7, ?)", ("这是文化革命资料",))
+                connection.execute("INSERT INTO content_fts(rowid, content) VALUES (8, ?)", ("这是文化和革命资料",))
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                self.assertEqual(databases.search_source("CCRD", "文化革命", exact=True), {7})
+            finally:
+                databases.close()
+
+    def test_exact_short_non_cjk_literals_verify_against_fts_content(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+                connection.executemany("INSERT INTO content_fts(rowid, content) VALUES (?, ?)", [
+                    (1, "smartphone abc123xyz"),
+                    (2, "手 单独"),
+                    (3, "手。句号"),
+                    (4, "手机 没有句号"),
+                ])
+                for token, numbers in (("手", [2, 3, 4]), ("机", [4])):
+                    token_hash = hashlib.sha256(token.encode()).digest()[:16]
+                    connection.execute("INSERT INTO postings VALUES (?, ?, ?)", (token_hash, encode_doc_numbers(numbers), len(numbers)))
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                # Latin substrings shorter than three characters must not be lost.
+                self.assertEqual(databases.search_source("CCRD", "ab", exact=True), {1})
+                self.assertEqual(databases.search_source("CCRD", "a", exact=True), {1})
+                self.assertEqual(databases.search_source("CCRD", "12", exact=True), {1})
+                # Short punctuation-separated CJK must not collapse to the bare character.
+                self.assertEqual(databases.search_source("CCRD", "手。", exact=True), {3})
+                # Pure CJK single characters still resolve through postings.
+                self.assertEqual(databases.search_source("CCRD", "手", exact=True), {2, 3, 4})
+            finally:
+                databases.close()
+
+    def test_builder_sanitizes_nul_before_fts_indexing(self):
+        self.assertEqual(build_fulltext_db.fts_content("ＡＢＣ\0文化革命"), "abc 文化革命")
+
+    def test_metadata_only_result_does_not_read_original_text_for_snippet(self):
+        original_records = app.records
+        original_map = app.record_map
+        original_indices = app.record_map_index
+        original_databases = app.fulltext_databases
+        app.records = [{"doc_id": "CCRD:0", "storage_root": "unused", "storage_rel_path": "unused"}]
+        app.record_map = {"CCRD:0": app.records[0]}
+        app.record_map_index = {"CCRD:0": 0}
+        try:
+            item = {"doc_id": "CCRD:0"}
+            fake_databases = MagicMock()
+            fake_databases.summaries.return_value = {"CCRD:0": "摘要没有查询词"}
+            with patch.object(app, "get_doc_storage_path", side_effect=AssertionError("metadata hit read source text")):
+                app.fulltext_databases = fake_databases
+                self.assertEqual(app.add_summaries([item], "手机", True, set()), [item])
+        finally:
+            app.records = original_records
+            app.record_map = original_map
+            app.record_map_index = original_indices
+            app.fulltext_databases = original_databases
+
+    def test_fulltext_result_list_uses_stored_summaries_without_source_reads(self):
+        original_databases = app.fulltext_databases
+        fake_databases = MagicMock()
+        fake_databases.summaries.return_value = {"CCRD:0": "文档摘要"}
+        fake_databases.matched_snippets.return_value = {}
+        app.fulltext_databases = fake_databases
+        try:
+            item = {"doc_id": "CCRD:0"}
+            with patch.object(app, "get_doc_storage_path", side_effect=AssertionError("list summary read source text")):
+                result = app.add_summaries([item], "手机", matched_snippets=False, content_indices={0})
+            self.assertEqual(result[0]["snippet"], "文档摘要")
+        finally:
+            app.fulltext_databases = original_databases
+
+    def test_current_page_snippets_are_bounded_and_read_from_fts(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+                connection.execute("INSERT INTO content_fts(rowid, content) VALUES (7, ?)", ("甲" * 1000 + "文化革命" + "乙" * 1000,))
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                calls = []
+                def counted_instr(content, needle):
+                    calls.append(needle)
+                    return content.find(needle) + 1
+                databases.connections["CCRD"].create_function("instr", 2, counted_instr)
+                payload = databases.matched_snippets(["CCRD:7"], "文化革命", exact=True)["CCRD:7"]
+                self.assertIn("文化革命", payload["snippet"])
+                self.assertIn("文化革命", payload["highlights"])
+                self.assertLessEqual(len(payload["snippet"]), 230)
+                self.assertEqual(calls, ["文化革命"])
+            finally:
+                databases.close()
+
+    def test_normal_snippets_seek_token_anchors_without_instr_scanning(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            content = "甲" * 1000 + "文化革命" + "乙" * 1000
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+                connection.execute("CREATE TABLE snippet_anchors (token_hash BLOB NOT NULL, doc_number INTEGER NOT NULL, char_offset INTEGER NOT NULL, PRIMARY KEY (token_hash, doc_number)) WITHOUT ROWID")
+                connection.execute("INSERT INTO content_fts(rowid, content) VALUES (7, ?)", (content,))
+                for token_hash, char_offset in build_fulltext_db.snippet_anchors(content).items():
+                    connection.execute("INSERT INTO snippet_anchors VALUES (?, 7, ?)", (token_hash, char_offset))
+            databases = app.FulltextDatabases(Path(directory))
+            statements = []
+            databases.connections["CCRD"].set_trace_callback(statements.append)
+            try:
+                payload = databases.matched_snippets(["CCRD:7"], "文化革命")["CCRD:7"]
+                self.assertIn("文化", payload["highlights"])
+                self.assertIn("snippet_anchors", "\n".join(statements))
+                self.assertNotIn("instr(content", "\n".join(statements).lower())
+            finally:
+                databases.close()
+
+    def test_fulltext_results_use_synchronous_fts_snippets(self):
+        original_records = app.records
+        original_map = app.record_map
+        original_indices = app.record_map_index
+        original_counts = app.source_counts
+        original_databases = app.fulltext_databases
+        record = {
+            "doc_id": "CCRD:7", "source": "CCRD", "source_name": "CCRD",
+            "display_name": "文档", "extension": "txt", "display_dirs": [],
+            "display_rel_path": "文档.txt", "size": 10,
+            "_file_search_text": "文档 ccrd", "_path_search_text": "文档.txt",
+            "_search_text": "文档 ccrd 文档.txt",
+        }
+        fake_databases = MagicMock()
+        fake_databases.search_source.return_value = {7}
+        fake_databases.summaries.return_value = {"CCRD:7": "开头摘要"}
+        fake_databases.matched_snippets.return_value = {
+            "CCRD:7": {"snippet": "...命中文化革命正文...", "highlights": ["文化革命"]}
+        }
+        app.records = [record]
+        app.record_map = {"CCRD:7": record}
+        app.record_map_index = {"CCRD:7": 0}
+        app.source_counts = {"CCRD": 1}
+        app.build_indexes()
+        app.fulltext_databases = fake_databases
+        try:
+            result = app.fulltext_search("文化革命", exact=True)
+            self.assertEqual(result["results"][0]["snippet"], "...命中文化革命正文...")
+            self.assertEqual(result["results"][0]["snippet_highlights"], ["文化革命"])
+            self.assertTrue(result["results"][0]["snippet_complete"])
+            fake_databases.matched_snippets.assert_called_once_with(["CCRD:7"], "文化革命", exact=True, timings=None)
+        finally:
+            app.records = original_records
+            app.record_map = original_map
+            app.record_map_index = original_indices
+            app.source_counts = original_counts
+            app.build_indexes()
+            app.fulltext_databases = original_databases
+
+    def test_normal_snippet_uses_actual_bigram_match(self):
+        payload = app.build_snippet_payload("前文很多内容，文化在这里，后面另有革命。", "文化革命")
+        self.assertIn("文化", payload["snippet"])
+        self.assertIn("文化", payload["highlights"])
+
+    def test_exact_snippet_requires_contiguous_query(self):
+        text = "手。机只是干扰，后文才出现手机。"
+        payload = app.build_snippet_payload(text, "手机", exact=True)
+        self.assertIn("后文才出现手机", payload["snippet"])
+        self.assertEqual(payload["highlights"], ["手机"])
+
+    def test_snippet_returns_original_text_for_normalized_highlight(self):
+        payload = app.build_snippet_payload("正文使用全角ＡＢＣ字符。", "ABC", exact=True)
+        self.assertEqual(payload["highlights"], ["ＡＢＣ"])
+
+    def test_wildcard_snippet_highlights_fixed_original_parts(self):
+        payload = app.build_snippet_payload("这是手持电话机测试。", "手*机", exact=True)
+        self.assertEqual(payload["highlights"], ["手", "机"])
+
+    def test_missing_token_returns_no_matches(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                self.assertEqual(databases.search_source("CCRD", "不存在"), set())
+            finally:
+                databases.close()
+
+    def test_missing_runtime_database_returns_no_matches_until_hot_loaded(self):
+        with tempfile.TemporaryDirectory() as directory:
+            databases = app.FulltextDatabases(Path(directory))
+            try:
+                self.assertEqual(databases.search_source("CCRD", "文化革命", exact=True), set())
+            finally:
+                databases.close()
+
+    def test_hot_loading_increments_cache_generation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            databases = app.FulltextDatabases(root)
+            self.assertEqual(databases.generation, 0)
+            path = root / "CCRD.sqlite3"
+            with sqlite3.connect(path) as connection:
+                connection.execute("CREATE TABLE documents (doc_id TEXT PRIMARY KEY, summary TEXT NOT NULL)")
+                connection.execute("CREATE TABLE postings (token_hash BLOB PRIMARY KEY, docs BLOB NOT NULL, doc_count INTEGER NOT NULL)")
+                connection.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+                connection.execute("INSERT INTO metadata VALUES ('tokenizer_version', ?)", (app.TOKENIZER_VERSION,))
+                connection.execute("CREATE VIRTUAL TABLE content_fts USING fts5(content, tokenize='trigram', detail='full')")
+            databases.refresh()
+            try:
+                self.assertEqual(databases.generation, 1)
+            finally:
+                databases.close()
+
+
+class RequestValidationTests(unittest.TestCase):
+    def test_search_request_limits_expensive_inputs(self):
+        with self.assertRaises(ValueError):
+            app.SearchRequest(q="x" * 257)
+        with self.assertRaises(ValueError):
+            app.SearchRequest(page=0)
+        with self.assertRaises(ValueError):
+            app.SearchRequest(page_size=201)
+        with self.assertRaises(ValueError):
+            app.SearchRequest(sort="unknown")
+
+    def test_zip_request_has_independent_default_list(self):
+        first = app.ZipRequest()
+        second = app.ZipRequest()
+        first.doc_ids.append("CCRD:1")
+        self.assertEqual(second.doc_ids, [])
+
+    def test_zip_entries_deduplicate_ids_and_preserve_safe_paths(self):
+        original_map = app.record_map
+        try:
+            with tempfile.TemporaryDirectory() as directory:
+                path = Path(directory) / "article.txt"
+                path.write_bytes(b"x" * 70000)
+                record = {
+                    "source": "CCRD", "display_rel_path": "folder/article.txt",
+                    "storage_root": "unused", "storage_rel_path": "unused",
+                }
+                app.record_map = {"CCRD:1": record}
+                with patch.object(app, "get_doc_storage_path", return_value=path):
+                    entries = app.zip_entries(["CCRD:1", "CCRD:1"])
+                self.assertEqual(entries, [("CCRD/article [CCRD_1].txt", path)])
+        finally:
+            app.record_map = original_map
+
+    def test_unknown_source_returns_404_shape(self):
+        original_counts = app.source_counts
+        app.source_counts = {"CCRD": 1}
+        try:
+            response = app.api_search_source("missing", app.SearchRequest())
+            self.assertEqual(response.status_code, 404)
+            self.assertIn(b'"total":0', response.body)
+        finally:
+            app.source_counts = original_counts
+
+    def test_index_status_reports_background_build_progress(self):
+        original_databases = app.fulltext_databases
+        original_counts = app.source_counts
+        fake_databases = MagicMock()
+        fake_databases.connections = {"CCRD": MagicMock()}
+        fake_databases.tokenizer_versions = {"CCRD": app.TOKENIZER_VERSION}
+        fake_databases.has_content_fts = {"CCRD": True}
+        fake_databases.document_counts = {"CCRD": 1}
+        fake_databases.fts_counts = {"CCRD": 1}
+        app.fulltext_databases = fake_databases
+        app.source_counts = {"CCRD": 1, "CW": 1}
+        try:
+            response = app.api_index_status()
+            payload = __import__("json").loads(response.body)
+            self.assertFalse(payload["ready"])
+            self.assertEqual(payload["loaded_sources"], ["CCRD"])
+            self.assertEqual(payload["building_sources"], ["CW"])
+        finally:
+            app.fulltext_databases = original_databases
+            app.source_counts = original_counts
+
+    def test_index_status_rejects_wrong_version_or_incomplete_database(self):
+        original_databases = app.fulltext_databases
+        original_counts = app.source_counts
+        fake = MagicMock()
+        fake.connections = {"CCRD": MagicMock()}
+        fake.tokenizer_versions = {"CCRD": "wrong-version"}
+        fake.has_content_fts = {"CCRD": True}
+        fake.document_counts = {"CCRD": 1}
+        fake.fts_counts = {"CCRD": 1}
+        app.fulltext_databases = fake
+        app.source_counts = {"CCRD": 1}
+        try:
+            payload = __import__("json").loads(app.api_index_status().body)
+            self.assertFalse(payload["ready"])
+            self.assertEqual(payload["loaded_sources"], [])
+            self.assertEqual(payload["building_sources"], ["CCRD"])
+        finally:
+            app.fulltext_databases = original_databases
+            app.source_counts = original_counts
+
+    def test_index_status_rejects_database_without_snippet_anchors(self):
+        original_databases = app.fulltext_databases
+        original_counts = app.source_counts
+        fake = MagicMock()
+        fake.connections = {"CCRD": MagicMock()}
+        fake.tokenizer_versions = {"CCRD": app.TOKENIZER_VERSION}
+        fake.has_content_fts = {"CCRD": True}
+        fake.has_snippet_anchors = {"CCRD": False}
+        fake.document_counts = {"CCRD": 1}
+        fake.fts_counts = {"CCRD": 1}
+        app.fulltext_databases = fake
+        app.source_counts = {"CCRD": 1}
+        try:
+            payload = __import__("json").loads(app.api_index_status().body)
+            self.assertFalse(payload["ready"])
+            self.assertEqual(payload["building_sources"], ["CCRD"])
+        finally:
+            app.fulltext_databases = original_databases
+            app.source_counts = original_counts
+
+    def test_identical_search_requests_use_bounded_response_cache(self):
+        original_records = app.records
+        original_sources = app.source_counts
+        original_cache = app.search_response_cache
+        app.records = []
+        app.source_counts = {}
+        app.search_response_cache = {}
+        try:
+            with patch.object(app, "search", wraps=app.search) as search_call:
+                first = app.run_search(app.SearchRequest(q="手机"))
+                second = app.run_search(app.SearchRequest(q="手机"))
+            self.assertEqual(first, second)
+            self.assertEqual(search_call.call_count, 1)
+            self.assertTrue(any(key[0] == "search" for key in app.search_response_cache))
+        finally:
+            app.search_response_cache = original_cache
+            app.records = original_records
+            app.source_counts = original_sources
+
+    def test_search_cache_key_isolates_every_result_option(self):
+        original_cache = app.search_response_cache
+        app.search_response_cache = {}
+        try:
+            base = app.SearchRequest(q="手机")
+            variants = [
+                app.SearchRequest(q="手机", page=2),
+                app.SearchRequest(q="手机", page_size=1),
+                app.SearchRequest(q="手机", exact=True),
+                app.SearchRequest(q="手机", fulltext=True),
+                app.SearchRequest(q="手机", search_paths=False),
+                app.SearchRequest(q="手机", sort="name"),
+                app.SearchRequest(q="手机", sources=["CCRD"]),
+                app.SearchRequest(q="手机", folders=["历史"]),
+                app.SearchRequest(q="手机", min_size=1),
+                app.SearchRequest(q="手机", max_size=100),
+            ]
+            app.run_search(base)
+            for variant in variants:
+                app.run_search(variant)
+            keys = [key for key in app.search_response_cache if key[0] == "search"]
+            self.assertEqual(len(keys), 1 + len(variants))
+        finally:
+            app.search_response_cache = original_cache
+
+    def test_api_cache_expires_and_evicts_oldest_entry(self):
+        original_cache = app.api_response_cache
+        app.api_response_cache = {}
+        try:
+            with patch.object(app.time, "monotonic", side_effect=[0, 0, 0, app.API_CACHE_TTL_SECONDS + 1, app.API_CACHE_TTL_SECONDS + 1]):
+                first = app.cached_payload(("sources",), lambda: object())
+                cached = app.cached_payload(("sources",), lambda: object())
+                expired = app.cached_payload(("sources",), lambda: object())
+                self.assertIs(first, cached)
+                self.assertIsNot(first, expired)
+            app.api_response_cache = {
+                ("entry", index): (float(index), index) for index in range(501)
+            }
+            with patch.object(app.time, "monotonic", return_value=1000):
+                app.cached_payload(("new",), lambda: "value")
+            self.assertLessEqual(len(app.api_response_cache), app.API_CACHE_MAX_ENTRIES)
+            self.assertNotIn(("entry", 0), app.api_response_cache)
+        finally:
+            app.api_response_cache = original_cache
+
+    def test_search_and_api_caches_evict_independently(self):
+        original_api_cache = app.api_response_cache
+        original_search_cache = app.search_response_cache
+        app.api_response_cache = {("sources",): (1.0, "sources")}
+        app.search_response_cache = {("search", 1): (1.0, "results")}
+        try:
+            with patch.object(app, "API_CACHE_MAX_ENTRIES", 1):
+                app.cached_payload(("folders", "CCRD"), lambda: [])
+            self.assertEqual(app.search_response_cache[("search", 1)][1], "results")
+            with patch.object(app, "SEARCH_CACHE_MAX_ENTRIES", 1):
+                app.cached_search_payload(("search", 2), lambda: {"results": []})
+            self.assertIn(("folders", "CCRD"), app.api_response_cache)
+        finally:
+            app.api_response_cache = original_api_cache
+            app.search_response_cache = original_search_cache
+
+
+class FrontendContractTests(unittest.TestCase):
+    def test_every_static_control_exists_is_cached_and_has_behavior(self):
+        html = (Path(app.BASE_DIR) / "static" / "index.html").read_text(encoding="utf-8")
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        parser = InteractiveIdParser()
+        parser.feed(html)
+        expected = {
+            "hamburger-btn", "header-logo", "search-input", "settings-btn", "mobile-toggle-btn",
+            "theme-btn", "sidebar-expand-btn", "multi-select-toggle", "clear-filters-btn", "sort-select",
+            "multi-select-all", "multi-deselect", "multi-batch-download", "multi-zip-download",
+            "empty-random-btn", "close-filters-btn", "fulltext-toggle", "search-paths-toggle",
+            "history-toggle", "exact-search-toggle", "folder-select-all", "folder-deselect-all",
+            "source-filter-cancel", "folder-filter-cancel",
+            "filter-min-size", "filter-min-unit", "filter-max-size", "filter-max-unit", "random-book-btn",
+        }
+        self.assertEqual(parser.ids, expected)
+        selector_exceptions = {"header-logo", "search-input"}
+        for control_id in expected - selector_exceptions:
+            self.assertIn(f'$("#{control_id}")', source, control_id)
+        self.assertIn('DOM.headerLogo = $("#header-logo")', source)
+        self.assertIn('DOM.searchInput = $("#search-input")', source)
+        event_objects = {
+            "hamburger-btn": "DOM.hamburgerBtn", "header-logo": "DOM.headerLogo",
+            "search-input": "DOM.searchInput", "settings-btn": "DOM.settingsBtn",
+            "mobile-toggle-btn": "DOM.mobileToggleBtn", "theme-btn": "DOM.themeBtn",
+            "sidebar-expand-btn": "DOM.sidebarExpandBtn", "multi-select-toggle": "DOM.multiSelectToggle",
+            "clear-filters-btn": "DOM.clearFiltersBtn", "sort-select": "DOM.sortSelect",
+            "multi-select-all": "DOM.multiSelectAll", "multi-deselect": "DOM.multiDeselect",
+            "multi-batch-download": "DOM.multiBatchDownload", "multi-zip-download": "DOM.multiZipDownload",
+            "empty-random-btn": "DOM.emptyRandomBtn", "close-filters-btn": "DOM.closeFiltersBtn",
+            "fulltext-toggle": "DOM.fulltextToggle", "search-paths-toggle": "DOM.searchPathsToggle",
+            "history-toggle": "DOM.historyToggle", "exact-search-toggle": "DOM.exactToggle",
+            "folder-select-all": "DOM.folderSelectAll", "folder-deselect-all": "DOM.folderDeselectAll",
+            "source-filter-cancel": "DOM.sourceFilterCancel", "folder-filter-cancel": "DOM.folderFilterCancel",
+            "filter-min-size": "DOM.filterMinSize", "filter-min-unit": "DOM.filterMinUnit",
+            "filter-max-size": "DOM.filterMaxSize", "filter-max-unit": "DOM.filterMaxUnit",
+            "random-book-btn": "DOM.randomBookBtn",
+        }
+        for control_id, object_name in event_objects.items():
+            self.assertIn(f'{object_name}.addEventListener(', source, control_id)
+
+    def test_section_filter_cancel_buttons_clear_only_their_selected_state(self):
+        html = (Path(app.BASE_DIR) / "static" / "index.html").read_text(encoding="utf-8")
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        css = (Path(app.BASE_DIR) / "static" / "style.css").read_text(encoding="utf-8")
+        for control_id in ("source-filter-cancel", "folder-filter-cancel"):
+            self.assertRegex(html, rf'id="{control_id}"[^>]*hidden>取消<')
+        self.assertIn("DOM.sourceFilterCancel.hidden = STATE.selectedSources.length === 0", source)
+        self.assertIn("DOM.folderFilterCancel.hidden = STATE.folderSelections.length === 0", source)
+        self.assertIn('DOM.folderFilterCancel.addEventListener("click", () => applyFolderSelections([]))', source)
+        self.assertIn(".filter-title-leading", css)
+
+    def test_dynamic_controls_have_delegated_event_roots(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        self.assertIn('DOM.resultsList.addEventListener("click"', source)
+        self.assertIn('DOM.sidebarContent.addEventListener("click"', source)
+        self.assertIn('DOM.previewPanel.addEventListener("click"', source)
+        self.assertIn('DOM.searchHistoryDropdown.addEventListener("click"', source)
+        for selector in (
+            ".result-checkbox", "[data-action='preview']", ".path-folder[data-folder]",
+            "[data-source]", "#back-home", "[data-folder-open]", "[data-folder-nav]",
+            "[data-doc-id]", "[data-action='close-preview']", "[data-action='toggle-preview-theme']", "[data-query]",
+        ):
+            self.assertIn(selector, source)
+
+    def test_mobile_result_paths_keep_separators_with_their_folder(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        css = (Path(app.BASE_DIR) / "static" / "style.css").read_text(encoding="utf-8")
+        self.assertIn("${highlightText(part, STATE.query)}${separator}</span>", source)
+        self.assertNotIn('<span class="path-sep">/</span><span class="path-folder"', source)
+        self.assertIn("body.mobile .result-path", css)
+        self.assertIn("word-break: break-all", css)
+        self.assertIn("overflow-wrap: normal", css)
+
+    def test_highlighting_is_bounded_for_common_single_character_queries(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        self.assertIn("const MAX_HIGHLIGHTS_PER_TEXT = 16", source)
+        self.assertIn("if (!remaining) return match", source)
+
+    def test_search_debounce_allows_ime_input_to_settle(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        self.assertIn("const SEARCH_DEBOUNCE_MS = 120", source)
+        self.assertIn("}, SEARCH_DEBOUNCE_MS);", source)
+
+    def test_visible_page_keeps_the_search_connection_warm(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        html = (Path(app.BASE_DIR) / "static" / "index.html").read_text(encoding="utf-8")
+        self.assertIn("const KEEPALIVE_INTERVAL_MS = 45 * 1000", source)
+        self.assertIn('fetch("/api/ping"', source)
+        self.assertIn('fetch("/api/ping", { cache: "no-store" }).catch(() => {})', html)
+        self.assertLess(html.index('fetch("/api/ping"'), html.index('<link rel="stylesheet"'))
+        self.assertIn("if (document.hidden || !navigator.onLine || keepalivePending)", source)
+        self.assertIn('window.addEventListener("online", () => warmConnection(true))', source)
+        self.assertIn('document.addEventListener("visibilitychange"', source)
+        self.assertIn("window.setInterval(() => warmConnection(), KEEPALIVE_INTERVAL_MS)", source)
+
+    def test_visible_results_lazily_load_exact_snippets(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        self.assertIn("const SNIPPET_CONCURRENCY = 4", source)
+        self.assertIn('priority: "low"', source)
+        self.assertIn("function pauseSnippetLoadingForPreview()", source)
+        self.assertIn("pauseSnippetLoadingForPreview();", source)
+        self.assertIn('priority: "high"', source)
+        append_results = source[source.index("function appendResults(items)") : source.index("function renderResults({ animate = false } = {})")]
+        self.assertNotIn("animateResultRows", append_results)
+        self.assertNotIn("preview-loading", source)
+        self.assertIn("new IntersectionObserver", source)
+        self.assertIn("API.snippet(task.docId, task.query, task.exact, controller.signal)", source)
+        self.assertIn("for (const controller of snippetControllers) controller.abort()", source)
+        self.assertIn("task.sequence !== STATE.searchSequence", source)
+        self.assertIn("data.highlights || []", source)
+        self.assertIn('if (node.dataset.snippetPending !== "1") return', source)
+        self.assertIn('node.querySelector(".snippet-loading")', source)
+        self.assertIn("正在提取摘要...", source)
+        self.assertIn("function renderResults({ animate = false } = {}) {\n  resetSnippetObserver();", source)
+
+    def test_zip_download_uses_native_form_instead_of_buffering_blob(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        self.assertIn('fetch("/api/zip-prepare"', source)
+        self.assertIn("window.location.assign(data.download_url)", source)
+        self.assertNotIn('const blob = await resp.blob()', source)
+        self.assertIn("合并下载最多支持 500 个文件", source)
+        self.assertNotIn("zip-download-frame", source)
+
+    def test_results_reserve_snippet_height_and_clear_stale_selection(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        style = (Path(app.BASE_DIR) / "static" / "style.css").read_text(encoding="utf-8")
+        html = (Path(app.BASE_DIR) / "static" / "index.html").read_text(encoding="utf-8")
+        self.assertIn("if (STATE.page === 1 && STATE.selectedIds.size)", source)
+        self.assertIn("min-height: 1.5em", style)
+        self.assertIn("-webkit-line-clamp: 3", style)
+        self.assertIn("content-visibility: auto", style)
+        self.assertIn("contain-intrinsic-size: auto 112px", style)
+        self.assertIn('id="multi-select-all" class="multi-action-btn">全选</button>', html)
+        self.assertNotIn("全选已加载", html)
+
+    def test_frontend_motion_preserves_loading_and_accessibility_contracts(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        style = (Path(app.BASE_DIR) / "static" / "style.css").read_text(encoding="utf-8")
+        html = (Path(app.BASE_DIR) / "static" / "index.html").read_text(encoding="utf-8")
+        self.assertIn('matchMedia("(prefers-reduced-motion: reduce)")', source)
+        self.assertIn('setSearchMotion(true, STATE.page === 1 && STATE.results.length > 0)', source)
+        self.assertIn('DOM.resultsContainer.setAttribute("aria-busy", loading ? "true" : "false")', source)
+        self.assertIn("function renderResults({ animate = false } = {})", source)
+        self.assertIn("if (animate) animateResultRows", source)
+        self.assertIn("renderResults({ animate: true })", source)
+        self.assertIn("Math.round(24 * Math.sqrt(index))", source)
+        self.assertIn('classList.add("preview-enter")', source)
+        self.assertIn(".result-item.result-enter", style)
+        self.assertIn("animation: result-enter 320ms cubic-bezier(0.2, 0, 0, 1) both", style)
+        self.assertIn(".results-container.is-refreshing .results-list", style)
+        self.assertIn("--motion-emphasized-easing: cubic-bezier(0.05, 0.7, 0.1, 1)", style)
+        self.assertIn("--motion-spring-easing: cubic-bezier(0.18, 1.32, 0.32, 1)", style)
+        self.assertIn(".preview-panel.preview-enter .preview-body", style)
+        self.assertIn("transition: width 150ms ease, opacity 150ms ease", style)
+        self.assertIn('document.querySelectorAll(".theme-icon-svg")', source)
+        self.assertIn("icon.getAnimations().forEach", source)
+        self.assertIn('DOM.resultsList.classList.add("theme-static")', source)
+        self.assertIn(".results-list.theme-static *", style)
+        self.assertNotIn("document.body.offsetWidth", source)
+        self.assertNotIn("theme-transitioning", source + style)
+        self.assertNotIn("sidebar-opening", source + style)
+        self.assertIn("@media (prefers-reduced-motion: reduce)", style)
+        self.assertIn('id="results-container" class="results-container" aria-busy="false"', html)
+        self.assertIn('id="toast" class="toast" role="status" aria-live="polite"', html)
+
+    def test_preview_open_limits_text_selection_to_the_preview_panel(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        style = (Path(app.BASE_DIR) / "static" / "style.css").read_text(encoding="utf-8")
+        do_search = source[source.index("async function doSearch()") : source.index("function resultPathHtml")]
+        self.assertNotIn('DOM.previewPanel.style.display = "none"', do_search)
+        self.assertNotIn('document.body.classList.remove("preview-open")', do_search)
+        self.assertIn('document.body.classList.add("preview-open")', source)
+        self.assertIn('document.body.classList.remove("preview-open")', source)
+        self.assertIn("body.preview-open {\n  user-select: none;", style)
+        self.assertIn("body.preview-open #preview-panel {\n  user-select: text;", style)
+        self.assertIn("body.preview-open #preview-panel .preview-header {\n  user-select: none;", style)
+
+    def test_frontend_guards_initial_search_races_and_popup_blocking(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        self.assertIn("async function applyInitialSearch(sequence)", source)
+        self.assertIn("sequence !== STATE.searchSequence", source)
+        self.assertIn("if (await applyInitialSearch(sequence)) return", source)
+        self.assertIn('frame.src = `/api/download/${encodeURIComponent(id)}`', source)
+        self.assertNotIn("window.open(`/api/download/", source)
+        self.assertIn('if (event.key === "Escape")', source)
+        self.assertIn('showToast("随机文章加载失败")', source)
+        self.assertIn('DOM.searchInput.placeholder = STATE.fulltext ?', source)
+        self.assertIn('if (!resp.ok) throw new Error(`HTTP ${resp.status}`)', source)
+        self.assertIn('if (value && value.indexing) return', source)
+        self.assertIn('if (STATE.page > 1) STATE.page -= 1', source)
+        self.assertIn('showToast(timedOut ? "搜索超时，请重试" : "搜索失败")', source)
+        self.assertIn("text = highlightText(rawText, keyword)", source)
+
+    def test_sidebar_uses_inline_payload_before_network(self):
+        source = (Path(app.BASE_DIR) / "static" / "app.js").read_text(encoding="utf-8")
+        self.assertIn('readInlineJson("initial-sidebar-data")', source)
+        self.assertIn('readInlineJson("initial-sidebar-sources")', source)
+
+    def test_server_embeds_route_sidebar_payload(self):
+        html = app.render_index_html("CCRD")
+        self.assertIn('id="initial-sidebar-data"', html)
+        self.assertIn('id="initial-sidebar-sources"', html)
+        self.assertIn('"source":"CCRD"', html)
+
+    def test_docker_build_generates_indexes_in_image(self):
+        dockerfile = (Path(app.BASE_DIR) / "Dockerfile").read_text(encoding="utf-8")
+        self.assertIn("FROM node:26.11.1-bookworm-slim AS static-assets", dockerfile)
+        self.assertIn("ARG ESBUILD_VERSION=0.28.2", dockerfile)
+        self.assertIn("esbuild static/app.js --minify --target=es2019 --charset=utf8 --legal-comments=none", dockerfile)
+        self.assertIn("esbuild static/style.css --minify", dockerfile)
+        self.assertIn("esbuild static/sw.js --minify --target=es2019 --charset=utf8 --legal-comments=none", dockerfile)
+        self.assertIn("COPY --from=static-assets /out/ static/", dockerfile)
+        self.assertEqual(dockerfile.count("FROM node:"), 1)
+        self.assertEqual(dockerfile.count("FROM python:"), 1)
+        self.assertIn("COPY CCRD/ CCRD/", dockerfile)
+        self.assertIn("COPY CW/ CW/", dockerfile)
+        self.assertIn("COPY app.py build_fulltext_db.py prepare_fulltext_index.py start.sh ./", dockerfile)
+        self.assertIn('CMD ["sh", "/app/start.sh"]', dockerfile)
+        self.assertNotIn("RUN python build_fulltext_db.py", dockerfile)
+        start_script = (Path(app.BASE_DIR) / "start.sh").read_text(encoding="utf-8")
+        self.assertIn("python /app/prepare_fulltext_index.py", start_script)
+        self.assertIn("python /app/build_fulltext_db.py", start_script)
+        self.assertIn(") &", start_script)
+        self.assertIn("exec uvicorn", start_script)
+
+    def test_generated_indexes_are_excluded_from_build_context(self):
+        dockerignore = (Path(app.BASE_DIR) / ".dockerignore").read_text(encoding="utf-8")
+        gitattributes = (Path(app.BASE_DIR) / ".gitattributes").read_text(encoding="utf-8")
+        self.assertIn("data/fulltext/", dockerignore)
+        self.assertNotIn("data/fulltext/CCRD.sqlite3", gitattributes)
+        self.assertNotIn("data/fulltext/CW.sqlite3", gitattributes)
+
+    def test_service_worker_only_caches_explicit_static_assets(self):
+        source = (Path(app.BASE_DIR) / "static" / "sw.js").read_text(encoding="utf-8")
+        precache = source.split("];", 1)[0]
+        self.assertNotIn('"/",', precache)
+        self.assertNotIn("/data/initial/manifest.json", precache)
+        self.assertNotIn("/data/sidebar/manifest.json", precache)
+        self.assertNotIn("cacheManifestUrls", source)
+        self.assertIn('event.request.method !== "GET"', source)
+        self.assertIn('url.pathname.startsWith("/static/")', source)
+        self.assertIn('url.pathname.startsWith("/data/initial/")', source)
+        self.assertIn('url.pathname.startsWith("/data/sidebar/")', source)
+        self.assertIn("if (!cacheable)", source)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_search_oracle.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import gzip
+import json
+import os
+import re
+import time
+import unicodedata
+import unittest
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+BASE_DIR = Path(__file__).resolve().parents[1]
+BASE_URL = os.environ.get("CCRD_ORACLE_BASE_URL", "").rstrip("/")
+TOKEN_RE = re.compile(r"[a-z0-9]+|[\u4e00-\u9fff\u3400-\u4dbf]+")
+
+
+def normalize(value: str) -> str:
+    return unicodedata.normalize("NFKC", value or "").casefold()
+
+
+def unique(values):
+    return list(dict.fromkeys(values))
+
+
+def parts(query: str) -> list[str]:
+    return unique(TOKEN_RE.findall(normalize(query)))
+
+
+def query_tokens(query: str) -> list[str]:
+    result = []
+    for part in parts(query):
+        if re.fullmatch(r"[\u4e00-\u9fff\u3400-\u4dbf]+", part) and len(part) > 1:
+            result.extend(part[index:index + 2] for index in range(len(part) - 1))
+        else:
+            result.append(part)
+    return unique(result)
+
+
+def body_tokens(text: str) -> set[str]:
+    result = set()
+    for part in TOKEN_RE.findall(text):
+        if re.fullmatch(r"[\u4e00-\u9fff\u3400-\u4dbf]+", part):
+            result.update(part)
+            result.update(part[index:index + 2] for index in range(len(part) - 1))
+        else:
+            result.add(part)
+    return result
+
+
+def wildcard_regex(query: str):
+    pattern = []
+    for character in normalize(query):
+        pattern.append(".*?" if character == "*" else "." if character == "?" else re.escape(character))
+    return re.compile("".join(pattern), re.DOTALL)
+
+
+def metadata_text(record: dict, search_paths: bool) -> str:
+    fields = [record["display_name"], record["source_name"]]
+    if search_paths:
+        fields.append(record["display_rel_path"])
+    return normalize(" ".join(fields))
+
+
+def metadata_match(record: dict, query: str, exact: bool, search_paths: bool) -> bool:
+    text = metadata_text(record, search_paths)
+    if exact:
+        return bool(wildcard_regex(query).search(text)) if "*" in query or "?" in query else normalize(query) in text
+    terms = parts(query)
+    return bool(terms) and all(term in text for term in terms)
+
+
+@unittest.skipUnless(BASE_URL, "set CCRD_ORACLE_BASE_URL to run brute-force corpus oracle")
+class ProductionSearchOracleTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        payload = json.loads(gzip.decompress((BASE_DIR / "data/search_data.json.gz").read_bytes()))
+        cls.records = payload["records"]
+        cls.by_id = {record["doc_id"]: record for record in cls.records}
+        status = cls.request_json("/api/index-status")
+        if not status.get("ready"):
+            raise unittest.SkipTest(f'fulltext indexes are not ready: {status.get("building_sources", [])}')
+        cls.matrix = [
+            ("手机", True), ("手。机", True), ("文化革命", True),
+            ("手*机", True), ("手?机", True), ("文化 革命", False),
+            ("ABC", True), ("ＡＢＣ", True), ("hair", True), ("hair", False),
+        ]
+        cls.body_matches = {(query, exact): set() for query, exact in cls.matrix}
+        started = time.monotonic()
+        for record in cls.records:
+            text = normalize((BASE_DIR / record["storage_root"] / record["storage_rel_path"]).read_text(encoding="utf-8", errors="ignore"))
+            tokens = None
+            for query, exact in cls.matrix:
+                if exact:
+                    matched = bool(wildcard_regex(query).search(text)) if "*" in query or "?" in query else normalize(query) in text
+                else:
+                    if tokens is None:
+                        tokens = body_tokens(text)
+                    matched = all(token in tokens for token in query_tokens(query))
+                if matched:
+                    cls.body_matches[(query, exact)].add(record["doc_id"])
+        print(f"oracle_scanned={len(cls.records)} elapsed_seconds={time.monotonic() - started:.2f}")
+
+    @classmethod
+    def request_json(cls, path: str, payload: dict | None = None):
+        data = json.dumps(payload).encode() if payload is not None else None
+        for attempt in range(3):
+            try:
+                with urlopen(Request(BASE_URL + path, data=data, headers={"Content-Type": "application/json"} if data else {}), timeout=120) as response:
+                    return json.load(response)
+            except (HTTPError, URLError, TimeoutError):
+                if attempt == 2:
+                    raise
+                time.sleep(attempt + 1)
+
+    @classmethod
+    def api_ids(cls, body: dict, path: str = "/api/search") -> tuple[set[str], int]:
+        first = cls.request_json(path, {**body, "page": 1, "page_size": 200})
+        total = first["total"]
+        page_count = (total + 199) // 200
+        ids_by_page = {1: [item["doc_id"] for item in first["results"]]}
+
+        def fetch(page: int):
+            payload = cls.request_json(path, {**body, "page": page, "page_size": 200})
+            if payload["total"] != total:
+                raise AssertionError(f"total changed during pagination for {body}: {payload['total']} != {total}")
+            return page, [item["doc_id"] for item in payload["results"]]
+
+        with ThreadPoolExecutor(max_workers=6) as executor:
+            for page, page_ids in executor.map(fetch, range(2, page_count + 1)):
+                ids_by_page[page] = page_ids
+        ids = [doc_id for page in range(1, page_count + 1) for doc_id in ids_by_page[page]]
+        if len(ids) != len(set(ids)):
+            raise AssertionError(f"duplicate IDs for {body}")
+        if len(ids) != total:
+            raise AssertionError(f"pagination did not cover total for {body}: {len(ids)} != {total}")
+        return set(ids), total
+
+    def expected_ids(self, query: str, exact: bool, fulltext: bool = True, search_paths: bool = True, sources=None, folders=None, min_size=None, max_size=None):
+        body = self.body_matches[(query, exact)] if fulltext else set()
+        result = set()
+        for record in self.records:
+            if record["doc_id"] not in body and not metadata_match(record, query, exact, search_paths):
+                continue
+            if sources and record["source"] not in sources:
+                continue
+            rel_dir = "/".join(record["display_dirs"])
+            if folders and not any(rel_dir == folder or rel_dir.startswith(folder + "/") for folder in folders):
+                continue
+            if min_size is not None and record["size"] < min_size:
+                continue
+            if max_size is not None and record["size"] > max_size:
+                continue
+            result.add(record["doc_id"])
+        return result
+
+    def test_full_result_sets_and_totals_match_independent_oracle(self):
+        for query, exact in unique(self.matrix):
+            with self.subTest(query=query, exact=exact):
+                body = {"q": query, "exact": exact, "fulltext": True, "search_paths": True, "sort": "name"}
+                actual, total = self.api_ids(body)
+                expected = self.expected_ids(query, exact)
+                self.assertEqual(total, len(expected))
+                self.assertEqual(actual, expected)
+
+    def test_filters_modes_and_normalization_match_oracle(self):
+        query, exact = "文化 革命", False
+        folder = self.records[0]["display_dirs"][0]
+        variants = [
+            {"fulltext": False, "search_paths": True},
+            {"fulltext": False, "search_paths": False},
+            {"fulltext": True, "search_paths": False, "sources": ["CCRD"]},
+            {"fulltext": True, "search_paths": True, "sources": ["CW"]},
+            {"fulltext": True, "search_paths": True, "sources": ["CCRD"], "folders": [folder]},
+            {"fulltext": True, "search_paths": True, "min_size": 1000, "max_size": 10000},
+        ]
+        for options in variants:
+            with self.subTest(options=options):
+                body = {"q": query, "exact": exact, "sort": "name", **options}
+                actual, total = self.api_ids(body)
+                expected = self.expected_ids(query, exact, **options)
+                self.assertEqual(total, len(expected))
+                self.assertEqual(actual, expected)
+        self.assertEqual(self.body_matches[("ABC", True)], self.body_matches[("ＡＢＣ", True)])
+
+    def test_sorting_page_sizes_source_route_and_exact_snippets(self):
+        base = {"q": "手机", "exact": True, "fulltext": True, "search_paths": True, "sources": ["CW"]}
+        expected = self.expected_ids("手机", True, sources=["CW"])
+        reconstructed = []
+        for page_size in (17, 100, 200):
+            page = 1
+            ids = []
+            while len(ids) < len(expected):
+                payload = self.request_json("/api/search", {**base, "sort": "size", "page": page, "page_size": page_size})
+                batch = payload["results"]
+                if not batch:
+                    break
+                ids.extend(item["doc_id"] for item in batch)
+                sizes = [item["Size"] for item in batch]
+                self.assertEqual(sizes, sorted(sizes, reverse=True))
+                page += 1
+            self.assertEqual(set(ids), expected)
+            self.assertEqual(len(ids), len(expected))
+            reconstructed.append(set(ids))
+        self.assertTrue(all(result == reconstructed[0] for result in reconstructed))
+
+        route_ids, route_total = self.api_ids({**base, "sort": "name", "sources": ["CW"]}, "/api/search/CCRD")
+        expected_ccrd = self.expected_ids("手机", True, sources=["CCRD"])
+        self.assertEqual(route_total, len(expected_ccrd))
+        self.assertEqual(route_ids, expected_ccrd)
+
+        for query in ("手机", "文化革命", "手*机", "手?机"):
+            payload = self.request_json("/api/search", {
+                "q": query, "exact": True, "fulltext": True, "search_paths": True,
+                "page": 1, "page_size": 20,
+            })
+            pattern = wildcard_regex(query) if "*" in query or "?" in query else None
+            for item in payload["results"]:
+                record = self.by_id[item["doc_id"]]
+                content = normalize((BASE_DIR / record["storage_root"] / record["storage_rel_path"]).read_text(encoding="utf-8", errors="ignore"))
+                metadata = metadata_text(record, True)
+                self.assertTrue(bool(pattern.search(content) or pattern.search(metadata)) if pattern else normalize(query) in content or normalize(query) in metadata)
+
+
+if __name__ == "__main__":
+    unittest.main()