Add parse crop controls and motion

AGENTS.md

@@ -0,0 +1,456 @@
+# BHA Search Agent Guide
+
+Read this file before changing `bha-search-lite`. This project is a Chinese-focused, accuracy-first search service for the BHA article corpus. It is deployed as a Hugging Face Space and combines Elasticsearch with SQLite-derived metadata, summaries, facets, and warmup data.
+
+## Deployment
+
+- Production: `https://vomebook-bha-search.hf.space/`
+- Runtime: FastAPI, Uvicorn, and Elasticsearch on Hugging Face Spaces
+- Search engine: Elasticsearch
+- Derived local data: SQLite stores for documents, summaries, facets, and warmup paths
+- Checkout index-version contract: `INDEX_VERSION = "1.0.0"`; confirm the deployed version through production readiness metadata after deployment.
+- Parsed repositories default to `https://github.com/anftm`; only `BHA_PARSED_REPO_PREFIX` may override this. The legacy generic `REPO_PREFIX` is intentionally ignored so a stale Space variable cannot silently switch production back to the upstream archives.
+- This index version is not a cache-busting version. Do not bump it merely because files were pushed; Hugging Face rebuilds the Space after deployment.
+
+## Important Files
+
+- `app/main.py`: FastAPI composition root, middleware/lifecycle wiring, router registration, static files, and SPA fallback.
+- `app/search_logic.py`: `SearchRequest`, normal/exact query DSL, literal `*`/`?` handling, date filters, sorting, local highlighting, and snippets.
+- `app/proofread_core.py`: pure PatchV2 validation, UTF-16 delta replay, change previews, and auto-merge cost policy evaluation.
+- `app/parse_core.py`: parse request models, queue DTOs, page-range coverage, date/OCR validation, and generated article-ID collision checks.
+- `app/pipeline_dispatch.py`: repository-dispatch transport, Git blob chunking, and payload integrity metadata.
+- `app/document_identity.py`: stable content identity shared by preview, parse, and proofreading submissions.
+- `app/source_files.py`: source mirror state, SSRF-safe upstream access, source previews, and TXT/source/ZIP download routes.
+- `app/runtime.py`: Elasticsearch client, readiness/status, bounded response caches, facet/source routes, activity tracking, and auxiliary warmup.
+- `app/bootstrap_api.py`: generation-scoped default search and initial facet payload for first-screen hydration.
+- `app/search_api.py`: search HTTP route, Elasticsearch execution, literal candidate verification, and SQLite result assembly.
+- `app/preview_api.py`: article/random preview routes, ETag handling, variants, and source-preview metadata assembly.
+- `app/parse_api.py`: parse queue/OCR/submission routes and parse pipeline dispatch policy.
+- `app/proofread_api.py`: proofreading validation policy, rate limiting, idempotency, submission route, and pipeline dispatch.
+- `app/reindex_api.py`: authenticated reindex jobs, deferred bucket snapshot publication, and generation recovery coordination.
+- `app/indexer.py`: Elasticsearch mappings, document ingestion, bulk indexing, readiness metadata, and final refresh.
+- `app/data_loader.py`: source loading, normalization, metadata token fields, and record preparation.
+- `app/doc_store.py`: SQLite document access and warmup reads.
+- `app/facet_store.py`: SQLite facet storage and paginated facet reads.
+- `scripts/start.sh`: Elasticsearch/FastAPI startup configuration.
+- `Dockerfile`: multi-stage Elasticsearch extraction, esbuild static minification, and the final Python runtime image.
+- `scripts/install-elasticsearch.sh`: build-stage Elasticsearch download and SHA-512 verification.
+- `requirements.txt`: runtime dependencies, including the pinned jieba version.
+- `tests/test_search.py`: query DSL, tokenization, mapping, filtering, highlighting, snippets, and indexing contracts.
+- `tests/test_api.py`: FastAPI behavior, mocked Elasticsearch, error paths, and warmup contracts.
+- `tests/test_data_loader.py`: parsed-corpus normalization and generated document contracts.
+- `tests/test_indexer.py`: mapping metadata, activation/rollback, facet, and build contracts.
+- `tests/test_stores.py`: real temporary SQLite document/facet round trips, exact counts, pagination, variants, and years.
+- `tests/test_storage_lock.py`: serving/build generation lock contracts.
+- `tests/test_downloads.py`: TXT/source/ZIP download contracts, archive integrity, limits, cleanup, and SSRF defenses.
+- `tests/test_frontend.py`: static frontend control, escaping, cache, timeout, race, IME, preview, and filter contracts.
+- `tests/test_browser.py`: optional Playwright desktop/mobile interaction and browser download E2E with mocked API responses.
+- `tests/test_live_smoke.py`: read-only production smoke tests.
+- `TESTING.md`: local, live, and manual testing instructions.
+
+## Accuracy Priority
+
+Search accuracy is more important than isolated indexing or query benchmarks. Do not make a performance change if it changes result semantics, exact totals, field coverage, or user-visible correctness without explicit approval.
+
+This project does not use semantic or vector search. Do not add it as a “quality” improvement.
+
+## Search Semantics
+
+### Normal Search
+
+- Multiple query terms must use AND semantics.
+- Do not restore single-character OR behavior.
+- Short metadata fields use normalized jieba-derived `*_words` fields.
+- Full article content uses the Elasticsearch CJK analyzer.
+- Normal query routes use boundary-aware CJK matching.
+- Phrase matches may receive a relevance boost, but phrase boosts must not widen the result set.
+- `手机` must not be treated as equivalent to `手。机`.
+- Searching `文化 革命` must require both terms according to the existing route semantics.
+- Do not reduce searched fields to improve latency.
+- Do not use truncated candidates, approximate totals, or sampled results.
+
+### Exact Search
+
+- Exact title and publication/source matching uses literal fields. User-supplied `*` and `?`
+  are escaped before querying Elasticsearch wildcard fields.
+- Exact content uses phrase matching through the single CJK-analyzed `content` field.
+- Exact queries containing non-whitespace punctuation use Elasticsearch as a complete candidate/ranking oracle, then verify every candidate literally against SQLite metadata and content before recomputing total and pagination. This preserves literal `*`, `?`, and punctuation without a duplicate content index.
+- `authors.literal` is reserved for exact-search author substring matching; author filters continue to use `authors.keyword`, and normal search continues to use `authors_words`.
+- `*` and `?` are literal characters in both metadata and content searches; they are not
+  wildcard operators. Searches such as `手*机` and `手?机` must match those characters
+  literally in search results, snippets, and previews.
+- Do not reintroduce `query_string`, unrestricted Lucene syntax, or arbitrary Elasticsearch query input.
+- Do not describe the current implementation as intervals-based or as supporting content
+  wildcards. Those are removed behaviors.
+
+### Dates, Filters, and Facets
+
+- Date filters must preserve exact year/month/day shape semantics.
+- Do not add broader date fallbacks to an exact date filter.
+- Archive, author, source, tag, date, and other filters must remain composable with search mode.
+- Facet pagination must return exact SQLite-backed counts according to the existing data model.
+- Do not replace exact facet counts with estimates.
+- Invalid dates and unknown facets must retain their tested behavior.
+
+## Index and Data Rules
+
+- Elasticsearch index data is derived and rebuildable.
+- Index metadata `archive_revisions` contains parsed Git tree SHAs, not commit SHAs. Commit SHAs remain transport identities used to fetch exact refs; identical trees must not trigger indexing.
+- Local parsed data, SQLite sidecars, serving locks, and Elasticsearch indexes are generated snapshots and may be stale. Never report local document or facet counts as production counts.
+- Free Hugging Face Spaces do not provide dependable persistent volumes; do not assume Elasticsearch data survives a rebuild.
+- A pushed file change rebuilds the Space, but a valid bucket snapshot is restored instead of regenerating Elasticsearch and SQLite. A stale snapshot remains available while a revision-scoped convergence plan runs in the background. If remote tree revisions cannot be verified, startup keeps the restored snapshot and waits for the pipeline's explicit revision update rather than cloning every archive.
+- Incremental failure must preserve the serving generation and fail the update. A complete rebuild is allowed only when explicitly requested or when no valid serving generation exists; never turn an incremental safety failure into an implicit full rebuild.
+- Keep `INDEX_VERSION = "1.0.0"` unless the user explicitly requests a logical index-version change.
+- A file upload alone does not require an `INDEX_VERSION` bump.
+- `build_fingerprint()` intentionally hashes the mapping plus explicit document/index/SQLite schema versions, not whole Python modules. Runtime-only edits must not force a rebuild. Bump the relevant schema constant when changing indexed document generation, facet generation, or SQLite schema semantics.
+- Both mappings and query builders must be changed together when a field changes.
+- If a mapping or analyzer changes, rebuild and run the complete index/query tests before deployment.
+- Do not run jieba over the complete article body. The current design intentionally limits Python tokenization to short metadata.
+- Do not add `content_words` or duplicate full-content CJK fields merely to chase a benchmark.
+- Do not restore removed full-content wildcard or literal fields without measuring index size, build time, memory, and exactness.
+- Preserve the current single primary CJK content field unless a deliberate mapping migration is approved.
+- The approved `content.index_phrases` accelerator preserves the single content field and exact phrase semantics; assess its rebuild time, index size, and production phrase timings after each mapping generation.
+- Elasticsearch indexes `content` for CJK search but excludes `content` from `_source`; the
+  field is not separately stored and has no term vectors. Elasticsearch therefore returns
+  matching IDs but is not the production source of result-list content highlights.
+- Bulk ingestion limits are intentionally bounded:
+
+```text
+BULK_CHUNK_SIZE = 100
+BULK_MAX_BYTES = 16 MiB
+```
+
+Do not increase them blindly for remote Elasticsearch. Verify memory and failure behavior first.
+
+## Snapshot And Production Boundary
+
+Generated files, parsed corpora, local SQLite sidecars, local Elasticsearch indexes, counts, timings, and discrepancies describe only the checked-out or locally rebuilt snapshot and may be stale. Do not report them as production facts. Use `https://vomebook-bha-search.hf.space/` as the post-deployment acceptance layer and require a ready index before accepting document counts or analyzer behavior.
+
+## Index Build Settings
+
+The current build configuration intentionally favors safe, observable rebuilds:
+
+- `refresh_interval` remains `30s` during indexing.
+- Elasticsearch translog uses the default synchronous behavior.
+- Elasticsearch index buffer uses the default setting.
+- The final build performs an explicit refresh before marking the index ready.
+- Every completed build performs one `max_num_segments=1` force merge before marking ready; it preserves query semantics. Detailed phase and segment timing logs were removed after production acceptance.
+- Progressive builds reset live sidecars and activate the empty build index under the exclusive serving lock. Any progressive failure removes the partial physical index, alias, and sidecars instead of serving incomplete results.
+- Complete-generation activation checkpoints both incoming and currently served SQLite files, removes WAL/SHM companions, and preserves switch state when the Elasticsearch alias commit result is uncertain.
+- Documents should become progressively visible during a rebuild.
+
+Do not reintroduce these previously tested-and-rejected settings without new measurements and explicit approval:
+
+```text
+refresh_interval = -1
+translog.durability = async
+translog.sync_interval = 30s
+indices.memory.index_buffer_size = 20%
+```
+
+Do not add a final flush or dynamic `put_settings` cleanup solely to claim a faster build.
+
+## Readiness Initialization And Connection Keepalive
+
+- The server does not run fixed-query or periodic Elasticsearch search warmup. A concrete
+  query warms query-specific Lucene data and is not a general fix for browser connection
+  setup latency. Do not reintroduce representative search terms without new measurements.
+- Jieba is initialized during FastAPI startup without issuing a search. This moves its
+  one-time dictionary load out of the first ordinary user query; it is tokenizer
+  initialization, not fixed-query Elasticsearch warmup.
+- `initialize_when_ready()` polls index readiness, then runs one best-effort initialization
+  of SQLite document access, sources, years, facets, and static files.
+- The auxiliary warmup continues every 5-9 minutes while no user request was active in the
+  prior 90 seconds. It warms SQLite/facets/static files and performs one result-free
+  Elasticsearch `match_all` query (`size: 0`, no total tracking, no `_source`) to reduce
+  cold working-set recovery. It must not issue a query containing user or fixed search terms.
+- `warmup_db()` is intentional preview-path warmup, not search-term warmup. It reads document
+  content and performs a title lookup to cover the SQLite access patterns used by `get_doc()`
+  and `variants_for_title()` when opening a preview. Keep it in both ready-state and periodic
+  auxiliary warmup unless current preview measurements show it is unnecessary.
+- Ready-state initialization must clear stale status, source, facet, and search response
+  caches before rebuilding auxiliary cached data. It must not issue Elasticsearch searches.
+- Ready-state initialization must remain best-effort and must not make the API unavailable
+  when one auxiliary component fails.
+- While the page is visible, the frontend sends `GET /api/ping` approximately every 45
+  seconds. It also pings after the page becomes visible, the browser comes online, or the
+  search input receives focus after the minimum gap.
+- `/api/ping` returns an empty `204` with `Cache-Control: no-store`. It must not inspect
+  Elasticsearch, SQLite, readiness, facets, or source data.
+- Browser connection keepalive does not prevent Space suspension and cannot preserve a
+  connection after the page closes, the browser freezes it, the network changes, or Hugging
+  Face replaces the route.
+
+## Snippets and Highlighting
+
+- Result-list metadata and complete article content are read from SQLite after Elasticsearch
+  returns the current page of document IDs.
+- The search-specific SQLite projection excludes preview/download-only columns, including
+  source-file URLs and internal IDs. Do not replace it with `SELECT *` on the search path.
+- Search result payloads include only fields used by the shipped frontend. They deliberately
+  omit `article_id`, `publication_id`, `archive_id`, `path`, and Elasticsearch `score`.
+- `title_highlight` is included only when the title contains an actual `<mark>` match. The
+  frontend escapes and displays `title` when that optional field is absent.
+- Production search requests deliberately do not request Elasticsearch highlights. The
+  `highlight` consumption and maximum-fragment guard in `trim_hit()` are compatibility
+  defenses for supplied hit payloads, not evidence that production Elasticsearch provides
+  snippets.
+- Python builds bounded result snippets and `<mark>` highlights from the SQLite content.
+  `*` and `?` remain literal characters in this local path.
+- Result-list SQLite reads use `app/search_store.py` to return only the first 220 characters or a bounded window around the earliest exact/normal highlight term. This is a query-only optimization and is intentionally excluded from the index build fingerprint; preview and download paths still read complete content.
+- Do not restore stored Elasticsearch content, term vectors, a duplicate content field, or
+  Elasticsearch highlighting without measuring index size, build time, search memory, and
+  result semantics and completing a coherent index rebuild.
+- Do not read entire large article bodies repeatedly for every page without first measuring
+  the SQLite read and local snippet phases. Any optimization must preserve useful snippets
+  for matches located beyond a short content prefix.
+- Preserve HTML escaping in title, content, and snippet highlighting.
+- Highlighting must never create an XSS path.
+
+## Frontend Motion
+
+- Successful search and parse-queue responses animate only the first 15 result rows. Non-request rerenders, including closing a preview or returning from the parse editor, must remain static.
+- Preview entrance motion runs only when the user actively opens an article. URL restoration, theme/highlight changes, compare/proofread rerenders, and history restoration must not replay it.
+- Preserve `prefers-reduced-motion` behavior for all result and preview entrance motion.
+
+## Date Controls
+
+- The custom year picker must include every year returned by the facets API. Keep the list scrollable rather than truncating available years.
+- Default year-picker options include only four-digit numeric years. Do not guess, rewrite, or expose malformed year values as normal options.
+- Before year facets are available, the picker fallback range is 1843 through 2025 inclusive.
+
+## Caching and Readiness
+
+- Preserve readiness response semantics and stable health responses.
+- Search/status/source/facet caches must have bounded size and explicit TTL behavior.
+- Responses of at least 500 bytes use application-level Brotli quality 5 when accepted and
+  fall back to GZip for older clients. Download routes are excluded. Hugging Face did not
+  compress measured production search responses on behalf of the app, so preserve this
+  middleware unless current end-to-end measurements establish an equivalent replacement.
+- Source and facet response caches use a 600-second TTL. Search responses remain at 30
+  seconds and health/status responses remain at 5 seconds.
+- `/api/bootstrap` combines the default empty-query page with archives/types/years and the
+  first source/author/tag facet pages. It keeps one server-side payload without a time TTL,
+  keyed by the current SQLite serving-generation token; a generation change replaces it.
+  Its HTTP response remains `no-store`, so browsers and intermediaries cannot serve an old
+  generation. The default frontend must hydrate from this one request and fall back to the
+  ordinary search/facet APIs when bootstrap is unavailable or URL state is non-default.
+- The source-mirror manifest cache (BHA source-file proxy) is refreshed in the background every
+  `BHA_SOURCE_MIRROR_TTL_SECONDS` (default 600, configurable; e.g. 86400 once the mirror fill is
+  complete) and never stalls a request that finds a fresh cache. A failed refresh keeps the last
+  good manifest and backs off for the same TTL; requests fall back to the upstream URL either way.
+- Mirrored source files are fetched directly from the mirror base URL with `follow_redirects=True`,
+  skipping the per-hop `open_source_response` IP validation. This is safe because the mirror URL is
+  constructed from the cached manifest (`mirrored_source_url` pins the host to
+  `SOURCE_MIRROR_BASE_URL` and restricts paths to `archives*` without `..`). Non-mirror URLs still go
+  through the full SSRF validation in `open_source_response`.
+- Cache keys must include all query and filter options that affect results.
+- Do not cache partial-build search responses as if they were final data.
+- Do not allow stale pre-ready facet or source responses to survive into the ready state.
+- Do not use cache invalidation as a substitute for correct index readiness.
+- Temporary request timing headers and Elasticsearch profile routes were removed after production acceptance. Do not restore them as permanent public diagnostics.
+
+## API Safety
+
+Current safety constraints are intentional:
+
+```text
+query length <= 256 characters
+page >= 1
+page_size bounded by the existing API model
+sort values restricted to supported modes
+date and size values validated
+```
+
+- Keep Elasticsearch query construction server-side.
+- Do not expose arbitrary DSL, query string, script, or field injection through request parameters.
+- Unknown facet and invalid route behavior must remain stable.
+- Preserve CORS and compression behavior unless explicitly requested.
+- `POST /api/reindex` is an administrative index-update route. It performs an incremental update by default; `POST /api/reindex?full=true` explicitly requests the complete rebuild fallback. Both require the `BHA_REINDEX_TOKEN` Space Secret as a Bearer token, use a ten-minute accidental-repeat cooldown, and must never expose the token in URLs, frontend code, responses, or logs.
+- Automated reindex callers send complete `archive_commits` and `archive_revisions` maps. The service fetches exact commits, verifies their tree SHAs, and skips network fetches for already matching local archives before indexing.
+- An API-triggered index becomes `ready` after atomic index/sidecar activation. Bucket snapshot publication then runs in a background thread and reports its own status; snapshot latency or failure must not hold online revision acceptance open.
+- `POST /api/proofread` accepts proofreading changes only for a `doc_id` present in the served SQLite generation. It derives archive/article/publication routing server-side, rate-limits submissions, and dispatches the pipeline `submit-proofread` workflow. Configure the Space Secret `BHA_PROOFREAD_GITHUB_TOKEN`; `BHA_PROOFREAD_PIPELINE_REPOSITORY` defaults to `anftm/pipeline`. Never expose the GitHub token in frontend code, responses, or logs.
+- The initial parsing workbench is limited to archive 25 documents whose titles begin with `【文章待拆分】`. `GET /api/parse/queue` reads that queue from the served SQLite generation, and per-page OCR is fetched through the same-origin parse endpoint. The original-image pane provides a normalized draggable OCR crop for an article and optional current-page overrides; crop changes filter the OCR/body preview and are submitted as `content_thresholds`. `POST /api/parse` accepts only structured article metadata, page ranges, edited content, OCR options, and the bounded OCR baseline size; it requires complete page coverage and rejects duplicate generated article IDs. The separate pipeline `submit-parse` workflow creates one config PR and one batch `ocr_patch` PR so edited bodies persist and later proofreading can continue from them. It must never accept complete TypeScript config content from the browser, and both parsing PRs always require manual review.
+- Proofreading body changes use the upstream PatchV2 structure and target `ocr_patch`. Supported metadata changes target `config`: single-value title/source name/source author/source type and multi-value authors/dates/tags/source files. Keep these targets separate.
+- Proofreading text deltas are generated with the SRI-pinned `diff_match_patch` 20121119 browser build and may contain any number of ordered `=`, `-`, and `+` operations. The frontend preview, API change preview, and pipeline submission code must all replay the same multi-operation UTF-16 delta semantics. Inserted text remains Unicode and escapes only delta delimiters; do not restore whole-middle replacement or URI-encode every Chinese character.
+- Applying the proofreading full-text editor back to structured parts must sequence-align unchanged lines before creating patches. Inserting, splitting, joining, or deleting a paragraph must preserve the original DOM identity and PatchV2 index of later unchanged parts; never map full-text lines to existing parts by array position alone.
+- Proofreading is limited to 30 accepted submissions per client IP per hour. Only body/comment corrections are eligible for pipeline auto-merge: parts may be unlimited in number, total diff cost (including the complete text of inserted paragraphs) must stay within 500 UTF-16 code units, and the net paragraph delta (deletes minus inserts) must stay within ±3. Semantically empty operations such as identity diffs, unchanged types, empty insert lists, and `delete: false` are removed during normalization; a request with no effective change is rejected. Every metadata change, including tags, requires manual review. Branch protection or merge conflicts may still leave an otherwise eligible PR for manual review.
+- Proofreading payload limits use serialized Unicode character counts, not UTF-8 byte counts. Direct `repository_dispatch` payloads stay below 60,000 characters and at most 10 top-level properties; larger accepted submissions are split into ordered Git blobs and dispatched by SHA, then reassembled and SHA-256 verified by the pipeline workflow. Keep the service and pipeline transport contracts in sync.
+- Proofreading tracker issues and auto-merge log comments retain complete original/edited full text. When the combined body exceeds GitHub's limit, the pipeline moves each full-text section into idempotent, size-bounded follow-up comments and splits oversized sections without silently dropping text.
+
+## Testing
+
+### Fast Default
+
+Install runtime dependencies and run deterministic local tests. Elasticsearch calls are mocked; SQLite tests use real temporary databases:
+
+```bash
+python3 -m pip install -r requirements.txt
+python3 -m unittest \
+  tests.test_search tests.test_api tests.test_data_loader tests.test_indexer \
+  tests.test_stores tests.test_storage_lock tests.test_downloads tests.test_frontend \
+  tests.test_bucket_probe tests.test_bucket_snapshot tests.test_search_store -v
+```
+
+Run syntax checks:
+
+```bash
+python3 -m py_compile app/main.py app/indexer.py app/data_loader.py app/doc_store.py app/facet_store.py
+bash -n scripts/start.sh
+```
+
+### Browser Integration
+
+Run optional browser E2E tests explicitly:
+
+```bash
+python3 -m pip install -r requirements-test.txt
+playwright install chromium
+APP_ROOT="$PWD" python3 -m unittest tests.test_browser -v
+```
+
+### Rebuild And Real Elasticsearch
+
+A local real-Elasticsearch index build is explicit heavy acceptance, not part of the default suite. Require it for mapping, analyzer, ingestion, alias/activation, or index-generation changes when a provisioned Elasticsearch and representative parsed corpus are available. Full-corpus rebuilds remain release work.
+
+### Production Acceptance
+
+Run read-only production smoke tests:
+
+```bash
+BHA_LIVE_BASE_URL="https://vomebook-bha-search.hf.space" python3 -m unittest tests.test_live_smoke -v
+```
+
+The local suite deliberately mocks Elasticsearch. Local SQLite and corpus artifacts may be stale and do not prove deployed index state. The live smoke suite is the acceptance
+layer for the real CJK analyzer, phrase and literal-character behavior, exact totals, stable pagination,
+facet composition, previews, and TXT downloads. It must remain read-only and must never
+call `/api/reindex` or remote source-file proxy downloads.
+
+Minimum manual query matrix:
+
+```text
+手机
+手。机
+文化 革命
+文化革命
+手*机
+手?机
+normal mode
+exact mode
+fulltext on/off
+metadata-only search
+archive/source/author/tag filters
+date filters
+relevance/date sorting
+pagination
+facet pagination
+preview and snippets
+Chinese IME input
+mobile layout
+```
+
+For live exact-content tests, verify the original article or preview text when necessary. Do not decide correctness from a list snippet alone.
+
+## Deployment Upload Matrix
+
+Query/API/runtime-only change:
+
+```text
+app/main.py
+app/runtime.py, for readiness, caches, facets, sources, or warmup
+app/bootstrap_api.py, for default first-screen hydration
+app/search_api.py, for the search route
+app/preview_api.py, for article previews
+app/source_files.py, for source previews or downloads
+app/reindex_api.py, for reindex or snapshot coordination
+```
+
+Search request/query/result semantics change:
+
+```text
+app/main.py
+app/search_api.py
+app/search_logic.py
+```
+
+Proofreading patch semantics change:
+
+```text
+app/main.py
+app/proofread_api.py
+app/proofread_core.py
+app/pipeline_dispatch.py, when dispatch transport changes
+app/document_identity.py, when content identity changes
+```
+
+Parse workbench semantics change:
+
+```text
+app/main.py
+app/parse_api.py
+app/parse_core.py
+app/pipeline_dispatch.py, when dispatch transport changes
+app/document_identity.py, when content identity changes
+```
+
+Mapping/indexer change:
+
+```text
+app/main.py
+app/indexer.py
+app/data_loader.py, if data fields change
+scripts/start.sh, if startup settings change
+```
+
+Dependency change:
+
+```text
+requirements.txt
+```
+
+Container build change:
+
+```text
+Dockerfile
+.dockerignore, when build-context rules change
+scripts/install-elasticsearch.sh, when the Elasticsearch artifact changes
+requirements.txt, when Python runtime dependencies change
+```
+
+Keep `ES_VERSION` and `ES_SHA512` in the Dockerfile synchronized. The final image intentionally excludes build-only `tar`, `curl`, Node.js, esbuild, and the Elasticsearch installer; runtime readiness uses Python's standard library. Frontend source remains readable under `static/`; Docker serves only the minified builder output with the same filenames.
+
+Tests/documentation:
+
+```text
+tests/
+TESTING.md
+AGENTS.md
+```
+
+Under the current deployment workflow, HF is expected to rebuild the Space after deployment. Verify `/api/health`, document count, index readiness, deployed index metadata, and the live smoke suite rather than assuming the rebuild completed correctly.
+
+## Explicit Prohibitions
+
+- Do not add semantic/vector search.
+- Do not weaken exactness for speed.
+- Do not change AND to OR.
+- Do not make `手机` equal `手。机`.
+- Do not truncate candidates, totals, facets, or fields.
+- Do not use approximate counts.
+- Do not reduce fields or filters to make queries faster.
+- Do not bump `INDEX_VERSION = "1.0.0"` just because files were uploaded or the Space rebuilt.
+- Do not assume a free HF Space has persistent storage.
+- Do not use Elasticsearch async translog settings or a 20% index buffer without explicit new evidence and approval.
+- Do not restore `refresh_interval=-1` without a measured benefit and a rebuild-visibility review.
+- Do not run jieba over full article content.
+- Do not add arbitrary `query_string` or raw Elasticsearch DSL input.
+- Do not disable bounded local snippets or HTML escaping.
+- Do not add fixed-query or periodic search warmup without current measurements.
+- Do not introduce unbounded caches.
+- Do not commit credentials, tokens, secrets, or private data.
+- Do not run destructive Git commands or revert user changes.
+- Do not modify CCRD, GitHub Search, Hugging Face Search, or unrelated projects while working here.
+
+## Engineering Priority
+
+Prefer the smallest correct change. Preserve Chinese search semantics, exact totals, stable filters, progressive index visibility, and deployability. If a performance optimization conflicts with accuracy, stop and ask rather than guessing.

static/app.js

@@ -121,6 +121,7 @@ let previewCloseUrl = "/";
 let previewResultsScrollTop = 0;
 let animateNextPreview = false;
 let previewAnimationCleanup = null;
+let parseCropDrag = null;
 let activeYearInput = null;
 let yearPickerPointer = null;
 let searchComposing = false;
@@ -1517,7 +1518,7 @@ function parseQueueHTML(item) {
   return `<div class="result-item parse-queue-item"><div class="result-file-icon"><span class="ui-icon ui-icon-file" aria-hidden="true"></span></div><div class="result-main"><div class="result-line"><div class="result-info"><div class="result-title">${escapeHTML(item.publication_name || item.title)}</div><div class="result-path"><span>Archive ${escapeHTML(item.archive_id)}</span><span class="path-sep">/</span><span>${start === end ? `第 ${start} 页` : `第 ${start}-${end} 页`}</span>${dates ? `<span class="path-sep">/</span><span>${escapeHTML(dates)}</span>` : ""}</div></div><div class="result-actions"><button class="result-action-btn primary" data-parse-open="${escapeHTML(item.doc_id)}">开始解析</button></div></div></div></div>`;
 }
 
-function renderParseQueue() {
+function renderParseQueue({ animate = false } = {}) {
   const pageSize = STATE.parsePageSize;
   const totalPages = Math.max(1, Math.ceil(STATE.parseTotal / pageSize));
   DOM.resultCount.textContent = `待解析 ${STATE.parseTotal.toLocaleString()} 份`;
@@ -1530,6 +1531,7 @@ function renderParseQueue() {
   DOM.results.hidden = !STATE.parseItems.length;
   DOM.emptyState.style.display = STATE.parseItems.length ? "none" : "flex";
   DOM.results.innerHTML = STATE.parseItems.map(parseQueueHTML).join("");
+  if (animate) animateResultRows(Array.from(DOM.results.children).slice(0, 15));
 }
 
 async function loadParseQueue() {
@@ -1542,7 +1544,7 @@ async function loadParseQueue() {
     if (!STATE.parseMode) return;
     STATE.parseTotal = Number(data.total) || 0;
     STATE.parseItems = Array.isArray(data.items) ? data.items : [];
-    renderParseQueue();
+    renderParseQueue({ animate: true });
   } catch (error) {
     DOM.statusText.textContent = "待解析队列加载失败";
     showToast(`待解析队列加载失败：${error.message || "未知错误"}`);
@@ -1556,14 +1558,16 @@ function parseDateParts(article) {
 
 function parseArticleRowHTML(article, index, maxPage) {
   const date = parseDateParts(article);
-  return `<fieldset class="parse-article" data-parse-article><legend>文章 ${index + 1}</legend><div class="parse-article-actions"><button type="button" class="text-btn-sm" data-parse-remove ${index === 0 ? "disabled" : ""}>删除</button></div><label class="proofread-field"><span>标题</span><input data-parse-title value="${escapeHTML(article.title || "")}" required></label><label class="proofread-field"><span>作者</span><input data-parse-authors value="${escapeHTML((article.authors || []).join("、"))}"></label><div class="parse-date-row"><label class="proofread-field"><span>年</span><input data-parse-year type="number" min="1" max="9999" value="${escapeHTML(date.year)}"></label><label class="proofread-field"><span>月</span><input data-parse-month type="number" min="1" max="12" value="${escapeHTML(date.month)}"></label><label class="proofread-field"><span>日</span><input data-parse-day type="number" min="1" max="31" value="${escapeHTML(date.day)}"></label></div><div class="parse-range-row"><label class="proofread-field"><span>开始页</span><input data-parse-start type="number" min="1" max="${maxPage}" value="${article.page_start || 1}" required></label><label class="proofread-field"><span>结束页</span><input data-parse-end type="number" min="1" max="${maxPage}" value="${article.page_end || maxPage}" required></label></div><label class="proofread-field parse-body-field"><span class="parse-body-heading"><span>正文</span><span><span class="parse-body-status" data-parse-body-status></span><button type="button" class="text-btn-sm" data-parse-refresh-body>从 OCR 刷新</button></span></span><textarea data-parse-content required>${escapeHTML(article.content || "")}</textarea></label></fieldset>`;
+  const ocr = escapeHTML(JSON.stringify(article.ocr || {}));
+  const exceptions = escapeHTML(JSON.stringify(article.ocr_exceptions || {}));
+  return `<fieldset class="parse-article" data-parse-article data-parse-ocr="${ocr}" data-parse-ocr-exceptions="${exceptions}"><legend>文章 ${index + 1}</legend><div class="parse-article-actions"><button type="button" class="text-btn-sm" data-parse-crop-open>裁剪</button><button type="button" class="text-btn-sm" data-parse-remove ${index === 0 ? "disabled" : ""}>删除</button></div><label class="proofread-field"><span>标题</span><input data-parse-title value="${escapeHTML(article.title || "")}" required></label><label class="proofread-field"><span>作者</span><input data-parse-authors value="${escapeHTML((article.authors || []).join("、"))}"></label><div class="parse-date-row"><label class="proofread-field"><span>年</span><input data-parse-year type="number" min="1" max="9999" value="${escapeHTML(date.year)}"></label><label class="proofread-field"><span>月</span><input data-parse-month type="number" min="1" max="12" value="${escapeHTML(date.month)}"></label><label class="proofread-field"><span>日</span><input data-parse-day type="number" min="1" max="31" value="${escapeHTML(date.day)}"></label></div><div class="parse-range-row"><label class="proofread-field"><span>开始页</span><input data-parse-start type="number" min="1" max="${maxPage}" value="${article.page_start || 1}" required></label><label class="proofread-field"><span>结束页</span><input data-parse-end type="number" min="1" max="${maxPage}" value="${article.page_end || maxPage}" required></label></div><label class="proofread-field parse-body-field"><span class="parse-body-heading"><span>正文</span><span><span class="parse-body-status" data-parse-body-status></span><button type="button" class="text-btn-sm" data-parse-refresh-body>从 OCR 刷新</button></span></span><textarea data-parse-content required>${escapeHTML(article.content || "")}</textarea></label></fieldset>`;
 }
 
 function parseEditorHTML(item) {
   const article = item.article || {};
   const maxPage = Number(article.page_end) || (item.source_files || []).length || 1;
   const initial = { title: "", authors: [], dates: article.dates || [], page_start: 1, page_end: maxPage };
-  return `<div class="preview-header"><div class="preview-heading"><div class="preview-title">${escapeHTML(item.publication_name || item.title)}</div><div class="preview-compare-note">待解析 / ${maxPage} 页</div></div><div class="preview-actions"><button type="button" class="text-btn-sm" data-parse-back>返回队列</button><button type="button" class="icon-btn-sm" data-parse-close aria-label="关闭">×</button></div></div><div class="parse-workbench"><section class="parse-source-pane"><div class="proofread-pane-header"><span>原图与 OCR</span><label class="proofread-page-control">页码 <input data-parse-page type="number" min="1" max="${maxPage}" value="1"></label></div><div class="parse-page-tools"><button type="button" class="text-btn-sm" data-parse-page-prev disabled>上一页</button><button type="button" class="text-btn-sm" data-parse-page-next ${maxPage === 1 ? "disabled" : ""}>下一页</button><span data-parse-page-status>1 / ${maxPage}</span></div><div class="parse-page-content"><div class="parse-image-stage"><img data-parse-image alt="原文件第 1 页"></div><pre class="parse-ocr-text" data-parse-ocr>正在加载 OCR...</pre></div></section><form class="proofread-editor parse-editor" data-parse-form data-max-page="${maxPage}"><div class="proofread-pane-header"><span>文章列表</span><button type="submit" class="result-action-btn primary">提交解析</button></div><div data-parse-articles>${parseArticleRowHTML(initial, 0, maxPage)}</div><div class="proofread-form-actions"><button type="button" class="text-btn-sm" data-parse-add>添加文章</button></div><label class="proofread-field"><span>解析备注</span><textarea data-parse-description></textarea></label><div class="date-error" data-parse-error hidden></div></form></div>`;
+  return `<div class="preview-header"><div class="preview-heading"><div class="preview-title">${escapeHTML(item.publication_name || item.title)}</div><div class="preview-compare-note">待解析 / ${maxPage} 页</div></div><div class="preview-actions"><button type="button" class="text-btn-sm" data-parse-back>返回队列</button><button type="button" class="icon-btn-sm" data-parse-close aria-label="关闭">×</button></div></div><div class="parse-workbench"><section class="parse-source-pane"><div class="proofread-pane-header"><span>原图与 OCR</span><label class="proofread-page-control">页码 <input data-parse-page type="number" min="1" max="${maxPage}" value="1"></label></div><div class="parse-page-tools"><button type="button" class="text-btn-sm" data-parse-page-prev disabled>上一页</button><button type="button" class="text-btn-sm" data-parse-page-next ${maxPage === 1 ? "disabled" : ""}>下一页</button><span data-parse-page-status>1 / ${maxPage}</span><button type="button" class="text-btn-sm parse-crop-toggle" data-parse-crop-toggle>裁剪 OCR</button></div><div class="parse-crop-toolbar" data-parse-crop-toolbar hidden><span data-parse-crop-target>文章 1</span><div class="parse-crop-scope" role="group" aria-label="裁剪范围"><button type="button" class="text-btn-sm primary" data-parse-crop-scope="article">整篇</button><button type="button" class="text-btn-sm" data-parse-crop-scope="page">仅本页</button></div><span data-parse-crop-values>上 0% 下 0% 左 0% 右 0%</span><button type="button" class="text-btn-sm" data-parse-crop-reset>重置</button><button type="button" class="text-btn-sm" data-parse-crop-close>完成</button></div><div class="parse-page-content"><div class="parse-image-stage"><div class="parse-image-wrap"><img data-parse-image alt="原文件第 1 页"><div class="parse-crop-overlay" data-parse-crop-overlay hidden><div class="parse-crop-box" data-parse-crop-box><span class="parse-crop-handle top" data-crop-handle="top"></span><span class="parse-crop-handle right" data-crop-handle="right"></span><span class="parse-crop-handle bottom" data-crop-handle="bottom"></span><span class="parse-crop-handle left" data-crop-handle="left"></span><span class="parse-crop-handle top-left" data-crop-handle="top-left"></span><span class="parse-crop-handle top-right" data-crop-handle="top-right"></span><span class="parse-crop-handle bottom-right" data-crop-handle="bottom-right"></span><span class="parse-crop-handle bottom-left" data-crop-handle="bottom-left"></span></div></div></div></div><pre class="parse-ocr-text" data-parse-ocr>正在加载 OCR...</pre></div></section><form class="proofread-editor parse-editor" data-parse-form data-max-page="${maxPage}"><div class="proofread-pane-header"><span>文章列表</span><button type="submit" class="result-action-btn primary">提交解析</button></div><div data-parse-articles>${parseArticleRowHTML(initial, 0, maxPage)}</div><div class="proofread-form-actions"><button type="button" class="text-btn-sm" data-parse-add>添加文章</button></div><label class="proofread-field"><span>解析备注</span><textarea data-parse-description></textarea></label><div class="date-error" data-parse-error hidden></div></form></div>`;
 }
 
 async function loadParsePage(page) {
@@ -1572,6 +1576,17 @@ async function loadParsePage(page) {
   const maxPage = Number((item.article || {}).page_end) || (item.source_files || []).length || 1;
   page = Math.min(maxPage, Math.max(1, Number(page) || 1));
   STATE.parseCurrentPage = page;
+  const cropToolbar = DOM.previewPanel.querySelector("[data-parse-crop-toolbar]");
+  if (cropToolbar && !cropToolbar.hidden) {
+    const selected = parseCropTargetRow();
+    const coversPage = selected
+      && Number(selected.querySelector("[data-parse-start]").value) <= page
+      && Number(selected.querySelector("[data-parse-end]").value) >= page;
+    if (!coversPage) {
+      if (selected) selected.classList.remove("is-crop-target");
+      setParseCropTarget(parseCropTargetRow());
+    }
+  }
   const image = DOM.previewPanel.querySelector("[data-parse-image]");
   const text = DOM.previewPanel.querySelector("[data-parse-ocr]");
   const input = DOM.previewPanel.querySelector("[data-parse-page]");
@@ -1587,18 +1602,229 @@ async function loadParsePage(page) {
   try {
     const data = await parseOCRPage(item, page);
     if (!STATE.parseItem || STATE.parseItem.doc_id !== item.doc_id || STATE.parseCurrentPage !== page) return;
-    if (text) text.textContent = parseOCRText(data);
+    if (text) text.textContent = parseOCRText(data, parseOCRThresholds(parseCropTargetRow(), page));
+    updateParseCropUI();
   } catch (error) {
     if (text) text.textContent = `OCR 加载失败：${error.message || "未知错误"}`;
   }
 }
 
-function parseOCRText(data) {
-  return (data.ocr_results || []).slice()
-    .sort((a, b) => ((a.box || [[0, 0]])[0][1] - (b.box || [[0, 0]])[0][1]) || ((a.box || [[0, 0]])[0][0] - (b.box || [[0, 0]])[0][0]))
+function parseOCRThresholds(row, page) {
+  if (!row) return [0, 0, 0, 0];
+  let ocr = {};
+  let exceptions = {};
+  try { ocr = JSON.parse(row.dataset.parseOcr || "{}"); } catch (_error) { /* invalid local state falls back to no crop */ }
+  try { exceptions = JSON.parse(row.dataset.parseOcrExceptions || "{}"); } catch (_error) { /* invalid local state falls back to no crop */ }
+  const options = { ...ocr, ...(exceptions[String(page)] || {}) };
+  const values = Array.isArray(options.content_thresholds) ? options.content_thresholds : [0, 0, 0, 0];
+  return values.map((value) => Math.min(0.98, Math.max(0, Number(value) || 0)));
+}
+
+function parseOCRRows(data, thresholds = [0, 0, 0, 0]) {
+  const dimensions = data.dimensions || {};
+  const width = Number(dimensions.width) || 0;
+  const height = Number(dimensions.height) || 0;
+  const [top, bottom, left, right] = thresholds;
+  return (data.ocr_results || []).filter((row) => {
+    if (!width || !height || !Array.isArray(row.box) || !row.box.length) return true;
+    const xs = row.box.map((point) => Number(point[0]) || 0);
+    const ys = row.box.map((point) => Number(point[1]) || 0);
+    const centerX = (Math.min(...xs) + Math.max(...xs)) / 2;
+    const centerY = (Math.min(...ys) + Math.max(...ys)) / 2;
+    return centerX >= left * width && centerX <= (1 - right) * width
+      && centerY >= top * height && centerY <= (1 - bottom) * height;
+  }).slice().sort((a, b) => ((a.box || [[0, 0]])[0][1] - (b.box || [[0, 0]])[0][1]) || ((a.box || [[0, 0]])[0][0] - (b.box || [[0, 0]])[0][0]));
+}
+
+function parseOCRText(data, thresholds = [0, 0, 0, 0]) {
+  return parseOCRRows(data, thresholds)
     .map((row) => row.text || "").filter(Boolean).join("\n");
 }
 
+function parseCropTargetRow() {
+  const rows = Array.from(DOM.previewPanel.querySelectorAll("[data-parse-article]"));
+  const selected = rows.find((row) => row.classList.contains("is-crop-target"));
+  if (selected) return selected;
+  return rows.find((row) => {
+    const start = Number(row.querySelector("[data-parse-start]").value);
+    const end = Number(row.querySelector("[data-parse-end]").value);
+    return start <= STATE.parseCurrentPage && end >= STATE.parseCurrentPage;
+  }) || rows[0] || null;
+}
+
+function setParseCropTarget(row) {
+  DOM.previewPanel.querySelectorAll("[data-parse-article]").forEach((candidate) => candidate.classList.toggle("is-crop-target", candidate === row));
+  updateParseCropUI();
+}
+
+function parseCropScope() {
+  const toolbar = DOM.previewPanel.querySelector("[data-parse-crop-toolbar]");
+  return toolbar && toolbar.dataset.scope === "page" ? "page" : "article";
+}
+
+function setParseCropScope(scope) {
+  const toolbar = DOM.previewPanel.querySelector("[data-parse-crop-toolbar]");
+  if (!toolbar) return;
+  toolbar.dataset.scope = scope === "page" ? "page" : "article";
+  toolbar.querySelectorAll("[data-parse-crop-scope]").forEach((button) => button.classList.toggle("primary", button.dataset.parseCropScope === toolbar.dataset.scope));
+  updateParseCropUI();
+}
+
+function cropOptions(row, scope, page) {
+  let options = {};
+  try {
+    if (scope === "page") {
+      const exceptions = JSON.parse(row.dataset.parseOcrExceptions || "{}");
+      options = exceptions[String(page)] || {};
+    } else {
+      options = JSON.parse(row.dataset.parseOcr || "{}");
+    }
+  } catch (_error) { /* invalid local state falls back to defaults */ }
+  return options;
+}
+
+function setParseCropThresholds(row, scope, page, thresholds, reset = false) {
+  if (!row) return;
+  const key = scope === "page" ? "parseOcrExceptions" : "parseOcr";
+  let value = {};
+  try { value = JSON.parse(row.dataset[key] || "{}"); } catch (_error) { value = {}; }
+  if (scope === "page") {
+    if (reset) delete value[String(page)];
+    else value[String(page)] = { ...(value[String(page)] || {}), content_thresholds: thresholds };
+  } else if (reset) {
+    delete value.content_thresholds;
+  } else {
+    value.content_thresholds = thresholds;
+  }
+  row.dataset[key] = JSON.stringify(value);
+}
+
+function updateParseCropUI() {
+  const toolbar = DOM.previewPanel.querySelector("[data-parse-crop-toolbar]");
+  const box = DOM.previewPanel.querySelector("[data-parse-crop-box]");
+  if (!toolbar || !box || toolbar.hidden) return;
+  const row = parseCropTargetRow();
+  if (!row) return;
+  const rows = Array.from(DOM.previewPanel.querySelectorAll("[data-parse-article]"));
+  const label = toolbar.querySelector("[data-parse-crop-target]");
+  const scope = parseCropScope();
+  const page = STATE.parseCurrentPage;
+  const options = cropOptions(row, scope, page);
+  const thresholds = Array.isArray(options.content_thresholds)
+    ? options.content_thresholds.map((value) => Number(value) || 0)
+    : parseOCRThresholds(row, page);
+  if (label) label.textContent = `文章 ${rows.indexOf(row) + 1}${scope === "page" ? ` / 第 ${page} 页` : ""}`;
+  box.style.top = `${thresholds[0] * 100}%`;
+  box.style.bottom = `${thresholds[1] * 100}%`;
+  box.style.left = `${thresholds[2] * 100}%`;
+  box.style.right = `${thresholds[3] * 100}%`;
+  const values = toolbar.querySelector("[data-parse-crop-values]");
+  if (values) values.textContent = `上 ${Math.round(thresholds[0] * 100)}% 下 ${Math.round(thresholds[1] * 100)}% 左 ${Math.round(thresholds[2] * 100)}% 右 ${Math.round(thresholds[3] * 100)}%`;
+}
+
+function openParseCrop(row = null) {
+  const toolbar = DOM.previewPanel.querySelector("[data-parse-crop-toolbar]");
+  const overlay = DOM.previewPanel.querySelector("[data-parse-crop-overlay]");
+  if (!toolbar || !overlay) return;
+  row = row || parseCropTargetRow();
+  if (!row) return;
+  const start = Number(row.querySelector("[data-parse-start]").value) || 1;
+  const end = Number(row.querySelector("[data-parse-end]").value) || start;
+  if (STATE.parseCurrentPage < start || STATE.parseCurrentPage > end) loadParsePage(start);
+  toolbar.hidden = false;
+  overlay.hidden = false;
+  setParseCropTarget(row);
+  setParseCropScope("article");
+}
+
+function closeParseCrop() {
+  const toolbar = DOM.previewPanel.querySelector("[data-parse-crop-toolbar]");
+  const overlay = DOM.previewPanel.querySelector("[data-parse-crop-overlay]");
+  if (toolbar) toolbar.hidden = true;
+  if (overlay) overlay.hidden = true;
+  parseCropDrag = null;
+}
+
+async function updateParsePageOCR() {
+  const item = STATE.parseItem;
+  const text = DOM.previewPanel.querySelector("[data-parse-ocr]");
+  if (!item || !text) return;
+  try {
+    const page = STATE.parseCurrentPage;
+    const data = await parseOCRPage(item, page);
+    if (!STATE.parseItem || STATE.parseItem.doc_id !== item.doc_id || STATE.parseCurrentPage !== page) return;
+    text.textContent = parseOCRText(data, parseOCRThresholds(parseCropTargetRow(), page));
+  } catch (error) {
+    text.textContent = `OCR 加载失败：${error.message || "未知错误"}`;
+  }
+}
+
+function finishParseCropChange(row) {
+  if (!row) return;
+  const textarea = row.querySelector("[data-parse-content]");
+  const status = row.querySelector("[data-parse-body-status]");
+  if (textarea && textarea.dataset.edited === "1") {
+    if (status) status.textContent = "裁剪已更改，需刷新正文";
+  } else {
+    refreshParseArticleBody(row, true);
+  }
+}
+
+function beginParseCropDrag(event) {
+  const box = event.target.closest("[data-parse-crop-box]");
+  const overlay = event.target.closest("[data-parse-crop-overlay]");
+  const row = parseCropTargetRow();
+  if (!box || !overlay || !row || event.button !== 0) return;
+  event.preventDefault();
+  const handle = event.target.closest("[data-crop-handle]");
+  const page = STATE.parseCurrentPage;
+  const scope = parseCropScope();
+  const options = cropOptions(row, scope, page);
+  const thresholds = Array.isArray(options.content_thresholds)
+    ? options.content_thresholds.map((value) => Number(value) || 0)
+    : parseOCRThresholds(row, page);
+  parseCropDrag = {
+    row, scope, page, thresholds, handle: handle ? handle.dataset.cropHandle : "move",
+    startX: event.clientX, startY: event.clientY, rect: overlay.getBoundingClientRect(),
+  };
+  if (box.setPointerCapture) box.setPointerCapture(event.pointerId);
+}
+
+function moveParseCrop(event) {
+  const drag = parseCropDrag;
+  if (!drag || !drag.rect.width || !drag.rect.height) return;
+  event.preventDefault();
+  const dx = (event.clientX - drag.startX) / drag.rect.width;
+  const dy = (event.clientY - drag.startY) / drag.rect.height;
+  const values = drag.thresholds.slice();
+  const minimum = 0.02;
+  const clamp = (value, opposite) => Math.min(1 - opposite - minimum, Math.max(0, value));
+  if (drag.handle === "move") {
+    const moveX = Math.min(values[3], Math.max(-values[2], dx));
+    const moveY = Math.min(values[1], Math.max(-values[0], dy));
+    values[0] += moveY;
+    values[1] -= moveY;
+    values[2] += moveX;
+    values[3] -= moveX;
+  } else {
+    if (drag.handle.includes("top")) values[0] = clamp(values[0] + dy, values[1]);
+    if (drag.handle.includes("bottom")) values[1] = clamp(values[1] - dy, values[0]);
+    if (drag.handle.includes("left")) values[2] = clamp(values[2] + dx, values[3]);
+    if (drag.handle.includes("right")) values[3] = clamp(values[3] - dx, values[2]);
+  }
+  const rounded = values.map((value) => Math.round(value * 10000) / 10000);
+  setParseCropThresholds(drag.row, drag.scope, drag.page, rounded);
+  updateParseCropUI();
+}
+
+function endParseCrop() {
+  if (!parseCropDrag) return;
+  const row = parseCropDrag.row;
+  parseCropDrag = null;
+  updateParsePageOCR();
+  finishParseCropChange(row);
+}
+
 async function parseOCRPage(item, page) {
   const key = `${item.doc_id}:${page}`;
   if (parseOCRCache.has(key)) {
@@ -1629,8 +1855,9 @@ async function refreshParseArticleBody(row, force = false) {
   if (status) status.textContent = "正在读取...";
   try {
     const pages = await Promise.all(Array.from({ length: end - start + 1 }, (_value, index) => parseOCRPage(STATE.parseItem, start + index)));
-    const body = pages.map(parseOCRText).filter(Boolean).join("\n");
-    const boxCount = pages.reduce((total, page) => total + (page.ocr_results || []).length, 0);
+    const pageTexts = pages.map((data, index) => parseOCRText(data, parseOCRThresholds(row, start + index)));
+    const body = pageTexts.filter(Boolean).join("\n");
+    const boxCount = pages.reduce((total, data, index) => total + parseOCRRows(data, parseOCRThresholds(row, start + index)).length, 0);
     textarea.value = body;
     textarea.dataset.edited = "0";
     row.dataset.basePartCount = String(boxCount);
@@ -1655,6 +1882,7 @@ async function openParseEditor(docId) {
     DOM.previewPanel.innerHTML = parseEditorHTML(item);
     DOM.results.hidden = true;
     DOM.emptyState.style.display = "none";
+    animatePreviewPanel();
     loadParsePage(1);
     DOM.previewPanel.querySelectorAll("[data-parse-article]").forEach((row) => refreshParseArticleBody(row));
   } catch (error) {
@@ -1671,7 +1899,11 @@ function collectParseArticles(form) {
     if (year) date.year = year;
     if (month) date.month = month;
     if (day) date.day = day;
-    return {
+    let ocr = {};
+    let ocrExceptions = {};
+    try { ocr = JSON.parse(row.dataset.parseOcr || "{}"); } catch (_error) { /* validation reports malformed state */ }
+    try { ocrExceptions = JSON.parse(row.dataset.parseOcrExceptions || "{}"); } catch (_error) { /* validation reports malformed state */ }
+    const article = {
       title: row.querySelector("[data-parse-title]").value.trim(),
       authors: row.querySelector("[data-parse-authors]").value.split(/[、,，/]/).map((value) => value.trim()).filter(Boolean),
       dates: Object.keys(date).length ? [date] : [],
@@ -1681,6 +1913,9 @@ function collectParseArticles(form) {
       content: row.querySelector("[data-parse-content]").value,
       base_part_count: Number(row.dataset.basePartCount) || 0,
     };
+    if (Object.keys(ocr).length) article.ocr = ocr;
+    if (Object.keys(ocrExceptions).length) article.ocr_exceptions = ocrExceptions;
+    return article;
   });
 }
 
@@ -3445,6 +3680,34 @@ function attachEvents() {
       renderParseQueue();
       return;
     }
+    const cropOpen = event.target.closest("[data-parse-crop-open]");
+    if (cropOpen) {
+      openParseCrop(cropOpen.closest("[data-parse-article]"));
+      return;
+    }
+    if (event.target.closest("[data-parse-crop-toggle]")) {
+      const toolbar = DOM.previewPanel.querySelector("[data-parse-crop-toolbar]");
+      if (toolbar && toolbar.hidden) openParseCrop();
+      else closeParseCrop();
+      return;
+    }
+    const cropScope = event.target.closest("[data-parse-crop-scope]");
+    if (cropScope) {
+      setParseCropScope(cropScope.dataset.parseCropScope);
+      return;
+    }
+    if (event.target.closest("[data-parse-crop-reset]")) {
+      const row = parseCropTargetRow();
+      setParseCropThresholds(row, parseCropScope(), STATE.parseCurrentPage, [0, 0, 0, 0], true);
+      updateParseCropUI();
+      updateParsePageOCR();
+      finishParseCropChange(row);
+      return;
+    }
+    if (event.target.closest("[data-parse-crop-close]")) {
+      closeParseCrop();
+      return;
+    }
     if (event.target.closest("[data-parse-page-prev]")) {
       loadParsePage(STATE.parseCurrentPage - 1);
       return;
@@ -3474,8 +3737,10 @@ function attachEvents() {
     const removeArticle = event.target.closest("[data-parse-remove]");
     if (removeArticle && !removeArticle.disabled) {
       const row = removeArticle.closest("[data-parse-article]");
+      const wasCropTarget = row && row.classList.contains("is-crop-target");
       if (row) row.remove();
       DOM.previewPanel.querySelectorAll("[data-parse-article] legend").forEach((legend, index) => { legend.textContent = `文章 ${index + 1}`; });
+      if (wasCropTarget) setParseCropTarget(parseCropTargetRow());
       return;
     }
     const partInsert = event.target.closest("[data-add-part-before], [data-add-part-after]");
@@ -3600,6 +3865,12 @@ function attachEvents() {
     if (event.target.closest("[data-preview-theme]")) toggleTheme();
     if (event.target.closest("[data-preview-mobile]")) toggleMobileMode();
   });
+  DOM.previewPanel.addEventListener("pointerdown", (event) => {
+    if (event.target.closest("[data-parse-crop-box]")) beginParseCropDrag(event);
+  });
+  window.addEventListener("pointermove", moveParseCrop, { passive: false });
+  window.addEventListener("pointerup", endParseCrop);
+  window.addEventListener("pointercancel", endParseCrop);
   DOM.previewPanel.addEventListener("change", (event) => {
     const parsePage = event.target.closest("[data-parse-page]");
     if (parsePage) {
@@ -3608,7 +3879,9 @@ function attachEvents() {
     }
     const parseRange = event.target.closest("[data-parse-start], [data-parse-end]");
     if (parseRange) {
-      refreshParseArticleBody(parseRange.closest("[data-parse-article]"));
+      const row = parseRange.closest("[data-parse-article]");
+      refreshParseArticleBody(row);
+      if (row && row.classList.contains("is-crop-target")) updateParseCropUI();
       return;
     }
     const select = event.target.closest("[data-compare-select]");

static/style.css

@@ -713,6 +713,48 @@ body.parse-mode .sidebar-content > #parse-page-size-section {
   font-size: 12px;
 }
 
+.parse-crop-toggle {
+  margin-left: auto;
+}
+
+.parse-crop-toolbar {
+  display: flex;
+  min-height: 42px;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  border-bottom: 1px solid var(--outline-variant);
+  background: var(--surface-container);
+  color: var(--on-surface-variant);
+  font-size: 12px;
+}
+
+.parse-crop-toolbar[hidden] {
+  display: none;
+}
+
+.parse-crop-scope {
+  display: inline-flex;
+  border: 1px solid var(--outline-variant);
+  border-radius: 5px;
+  overflow: hidden;
+}
+
+.parse-crop-scope .text-btn-sm {
+  border-radius: 0;
+}
+
+.parse-crop-scope .text-btn-sm.primary {
+  background: var(--primary-container);
+  color: var(--on-primary-container);
+}
+
+[data-parse-crop-values] {
+  flex: 1;
+  min-width: 180px;
+  text-align: center;
+}
+
 .parse-page-content {
   display: grid;
   grid-template-columns: minmax(0, 1fr) minmax(220px, 34%);
@@ -727,12 +769,60 @@ body.parse-mode .sidebar-content > #parse-page-size-section {
   background: #fff;
 }
 
+.parse-image-wrap {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+}
+
 .parse-image-stage img {
   display: block;
   width: 100%;
   height: auto;
 }
 
+.parse-crop-overlay {
+  position: absolute;
+  inset: 0;
+  touch-action: none;
+}
+
+.parse-crop-overlay[hidden] {
+  display: none;
+}
+
+.parse-crop-box {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  min-width: 20px;
+  min-height: 20px;
+  border: 2px solid #00a878;
+  box-shadow: 0 0 0 9999px rgb(0 0 0 / 48%);
+  cursor: move;
+}
+
+.parse-crop-handle {
+  position: absolute;
+  width: 14px;
+  height: 14px;
+  border: 2px solid #fff;
+  border-radius: 50%;
+  background: #00a878;
+  box-shadow: 0 1px 4px rgb(0 0 0 / 40%);
+}
+
+.parse-crop-handle.top { top: -8px; left: 50%; cursor: ns-resize; transform: translateX(-50%); }
+.parse-crop-handle.right { top: 50%; right: -8px; cursor: ew-resize; transform: translateY(-50%); }
+.parse-crop-handle.bottom { bottom: -8px; left: 50%; cursor: ns-resize; transform: translateX(-50%); }
+.parse-crop-handle.left { top: 50%; left: -8px; cursor: ew-resize; transform: translateY(-50%); }
+.parse-crop-handle.top-left { top: -8px; left: -8px; cursor: nwse-resize; }
+.parse-crop-handle.top-right { top: -8px; right: -8px; cursor: nesw-resize; }
+.parse-crop-handle.bottom-right { right: -8px; bottom: -8px; cursor: nwse-resize; }
+.parse-crop-handle.bottom-left { bottom: -8px; left: -8px; cursor: nesw-resize; }
+
 .parse-ocr-text {
   min-width: 0;
   overflow: auto;
@@ -762,6 +852,11 @@ body.parse-mode .sidebar-content > #parse-page-size-section {
   position: relative;
 }
 
+.parse-article.is-crop-target {
+  border-color: #00a878;
+  box-shadow: inset 3px 0 #00a878;
+}
+
 .parse-article-actions {
   position: absolute;
   top: 5px;
@@ -824,6 +919,15 @@ body.mobile .parse-page-content {
   grid-template-columns: 1fr;
 }
 
+body.mobile .parse-crop-toolbar {
+  flex-wrap: wrap;
+}
+
+body.mobile [data-parse-crop-values] {
+  order: 4;
+  width: 100%;
+}
+
 body.mobile .parse-ocr-text {
   max-height: 280px;
   border-top: 1px solid var(--outline-variant);

tests/test_api.py

@@ -0,0 +1,1062 @@
+import asyncio
+import json
+import unittest
+import tempfile
+from contextlib import nullcontext
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from fastapi.testclient import TestClient
+from elasticsearch.exceptions import BadRequestError
+
+from app import bootstrap_api, document_identity, main, parse_api, pipeline_dispatch, preview_api, proofread_api, proofread_core, reindex_api, runtime, search_api, search_logic, source_files
+
+
+class SearchApiTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.client = TestClient(main.app)
+
+    def setUp(self):
+        runtime.search_response_cache.clear()
+        bootstrap_api.bootstrap_cache = None
+        proofread_api.proofread_requests.clear()
+        proofread_api.proofread_dispatches.clear()
+
+    def test_preview_etag_and_proofread_content_hash(self):
+        stored = {"doc_id": "doc-1", "title": "标题", "article": {"parts": [{"text": "正文"}]}}
+        content_hash = document_identity.content_hash(stored)
+        payload = {"content_hash": content_hash, "source_files": []}
+        with patch.object(runtime, "index_status", return_value="ready"), \
+                patch.object(preview_api, "serving_lock", return_value=nullcontext()), \
+                patch.object(preview_api, "get_doc", return_value=stored), \
+                patch.object(preview_api, "preview_payload", AsyncMock(return_value=payload)):
+            response = self.client.get("/api/preview/doc-1")
+            cached = self.client.get("/api/preview/doc-1", headers={"If-None-Match": response.headers["etag"]})
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["content_hash"], content_hash)
+        self.assertEqual(cached.status_code, 304)
+
+    def test_proofread_rejects_stale_hash_and_deduplicates_dispatch(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "标题",
+            "article": {"parts": [{"text": "旧", "type": "paragraph"}], "comments": []},
+        }
+        request = {
+            "doc_id": "doc-1",
+            "patch": {"version": 2, "parts": {"0": {"diff": "-1\t+新"}}, "comments": {}, "description": ""},
+        }
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            stale = self.client.post("/api/proofread", json={**request, "base_content_hash": "0" * 64})
+            current_hash = document_identity.content_hash(stored)
+            first = self.client.post("/api/proofread", json={**request, "base_content_hash": current_hash})
+            duplicate = self.client.post("/api/proofread", json={**request, "base_content_hash": current_hash})
+        self.assertEqual(stale.status_code, 409)
+        self.assertEqual(first.status_code, 202)
+        self.assertEqual(duplicate.status_code, 200)
+        self.assertEqual(duplicate.json()["status"], "duplicate")
+        self.assertEqual(first.json()["request_id"], duplicate.json()["request_id"])
+        dispatch.assert_awaited_once()
+
+    def test_proofread_requires_server_github_token(self):
+        with patch.object(proofread_api, "GITHUB_TOKEN", ""):
+            response = self.client.post("/api/proofread", json={"doc_id": "doc-1", "patch": {"version": 2}})
+        self.assertEqual(response.status_code, 503)
+
+    def test_parse_queue_uses_placeholder_store(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 25, "publication_id": "a" * 36,
+            "publication_name": "小报", "title": "【文章待拆分】小报",
+            "article": {"page_start": 1, "page_end": 2}, "source_files": ["one", "two"],
+        }
+        with patch.object(parse_api, "serving_lock", return_value=nullcontext()), \
+                patch.object(parse_api, "parse_queue_docs", return_value=(1, [stored])):
+            response = self.client.get("/api/parse/queue?page=1&page_size=20")
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["total"], 1)
+        self.assertEqual(response.json()["items"][0]["page_end"], 2)
+
+    def test_parse_submission_dispatches_structured_articles(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 25, "article_id": "placeholder",
+            "publication_id": "052417de-42fb-4781-9885-af4fb006e9b6",
+            "publication_name": "革命楼通讯", "title": "【文章待拆分】革命楼通讯",
+            "source_files": ["one", "two"],
+            "article": {
+                "title": "【文章待拆分】革命楼通讯", "page_start": 1, "page_end": 2,
+                "dates": [{"year": 1967, "month": 8, "day": 29}],
+            },
+        }
+        dispatch = AsyncMock()
+        articles = [
+            {"title": "第一篇", "authors": ["作者甲"], "dates": [{"year": 1967, "month": 8, "day": 29}], "page_start": 1, "page_end": 1, "content": "第一篇正文", "base_part_count": 12, "ocr": {"content_thresholds": [0.1, 0.05, 0.08, 0.07]}, "ocr_exceptions": {"1": {"content_thresholds": [0.12, 0.05, 0.08, 0.07]}}},
+            {"title": "第二篇", "authors": [], "dates": [{"year": 1967, "month": 8, "day": 29}], "page_start": 2, "page_end": 2, "content": "第二篇正文", "base_part_count": 15},
+        ]
+        with patch.object(parse_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(parse_api, "dispatch_parse", dispatch):
+            response = self.client.post("/api/parse", json={
+                "doc_id": "doc-1", "base_content_hash": document_identity.content_hash(stored),
+                "articles": articles, "description": "拆分",
+            })
+        self.assertEqual(response.status_code, 202)
+        dispatch.assert_awaited_once()
+        payload = dispatch.await_args.args[0]
+        self.assertEqual(payload["kind"], "parse")
+        self.assertEqual(payload["archive_id"], 25)
+        self.assertEqual(len(payload["body"]["articles"]), 2)
+        self.assertEqual(payload["body"]["locator"]["page_end"], 2)
+        self.assertEqual(payload["body"]["articles"][0]["ocr"]["content_thresholds"], [0.1, 0.05, 0.08, 0.07])
+        self.assertIn("1", payload["body"]["articles"][0]["ocr_exceptions"])
+
+    def test_parse_submission_rejects_missing_pages_and_duplicate_ids(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 25,
+            "publication_id": "052417de-42fb-4781-9885-af4fb006e9b6",
+            "title": "【文章待拆分】革命楼通讯",
+            "article": {"title": "【文章待拆分】革命楼通讯", "page_start": 1, "page_end": 2},
+        }
+        base = {"doc_id": "doc-1", "articles": [{"title": "同题", "page_start": 1, "page_end": 1, "content": "正文", "base_part_count": 1}]}
+        duplicate = {"doc_id": "doc-1", "articles": [
+            {"title": "同题", "page_start": 1, "page_end": 1, "content": "正文一", "base_part_count": 1},
+            {"title": "同题", "page_start": 2, "page_end": 2, "content": "正文二", "base_part_count": 1},
+        ]}
+        with patch.object(parse_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored):
+            missing = self.client.post("/api/parse", json=base)
+            collision = self.client.post("/api/parse", json=duplicate)
+        self.assertEqual(missing.status_code, 400)
+        self.assertIn("cover", missing.json()["error"])
+        self.assertEqual(collision.status_code, 400)
+        self.assertIn("duplicate", collision.json()["error"])
+
+    def test_proofread_rate_limit_uses_forwarded_client_on_space(self):
+        request = MagicMock()
+        request.headers = {"x-forwarded-for": "198.51.100.8, 203.0.113.7"}
+        request.client.host = "10.0.0.2"
+        with patch.object(proofread_api, "TRUST_PROXY", True), patch.object(proofread_api, "PROXY_NETWORKS", (proofread_api.ipaddress.ip_network("10.0.0.0/8"),)):
+            self.assertIsNone(proofread_api.proofread_rate_error(request))
+        self.assertIn("198.51.100.8", proofread_api.proofread_requests)
+
+    def test_proofread_dispatches_body_and_metadata_tasks(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "旧标题",
+            "article": {"title": "旧标题", "page_start": 1, "page_end": 2, "parts": [{"text": "旧", "type": "paragraph"}], "comments": []},
+        }
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={
+                "doc_id": "doc-1",
+                "patch": {"version": 2, "parts": {"0": {"diff": "-1\t+新"}}, "comments": {}, "description": ""},
+                "metadata": {"article": {"title": "新标题", "authors": ["作者"], "dates": [{"year": 1967}], "tags": [{"name": "标签", "type": "主题/事件"}]}},
+            })
+        self.assertEqual(response.status_code, 202)
+        self.assertEqual(response.json()["tasks"], 1)
+        dispatch.assert_awaited_once()
+        payload = dispatch.await_args.args[0]
+        self.assertEqual(payload["kind"], "proofread")
+        self.assertEqual(payload["archive_id"], 3)
+        self.assertLessEqual(len(payload), 10)
+        self.assertNotIn("patch", payload)
+        self.assertNotIn("metadata", payload)
+        self.assertNotIn("locator", payload)
+        self.assertIn("patch", payload["body"])
+        self.assertIn("metadata", payload["body"])
+        self.assertIn("locator", payload["body"])
+        self.assertFalse(payload.get("auto_merge"))
+        changed = payload["changed"]
+        self.assertEqual(changed[0], {"kind": "part", "index": 1, "original": "旧", "edited": "新"})
+        self.assertEqual(changed[1], {"kind": "metadata", "field": "title", "old": "旧标题", "new": "新标题"})
+        self.assertEqual(changed[2]["field"], "authors")
+        self.assertEqual(changed[3]["field"], "dates")
+        self.assertEqual(changed[4]["field"], "tags")
+
+    def test_proofread_change_preview_covers_comments_description_and_inserts(self):
+        patch = {
+            "version": 2,
+            "parts": {"0": {"diff": "=1\t-1\t+新", "insertAfter": [{"text": "插入段", "type": "paragraph"}]}, "2": {"delete": True}},
+            "comments": {"1": {"diff": "=1\t+注\t=1"}},
+            "description": "+描述",
+        }
+        article = {
+            "parts": [{"text": "旧文", "type": "paragraph"}, {"text": "二", "type": "paragraph"}, {"text": "三", "type": "paragraph"}],
+            "comments": ["注释", "已删注释"],
+            "description": "",
+        }
+        source = {"publication_name": "来源甲", "publication_author": "著者", "publication_type": "书", "source_files": [{"url": "https://x/a"}]}
+        changes = proofread_core.proofread_change_preview(patch, article, {"source": {"name": "来源乙"}}, source)
+        self.assertEqual(changes[0]["kind"], "part")
+        self.assertEqual(changes[0]["index"], 1)
+        self.assertEqual(changes[0]["original"], "旧文")
+        self.assertEqual(changes[0]["edited"], "旧新")
+        self.assertEqual(changes[1], {"kind": "part", "index": 1, "insert": True, "text": "插入段", "part_type": "paragraph"})
+        self.assertEqual(changes[2], {"kind": "part", "index": 3, "delete": True, "original": "三"})
+        self.assertEqual(changes[3], {"kind": "comment", "index": 1, "original": "注释", "edited": "注注释"})
+        self.assertEqual(changes[4], {"kind": "description", "original": "", "edited": "描述"})
+        self.assertEqual(changes[5], {"kind": "metadata", "field": "name", "old": "来源甲", "new": "来源乙"})
+
+    def test_multi_operation_delta_replays_moved_text_and_utf16(self):
+        self.assertEqual(proofread_core.apply_text_delta("甲乙丙丁", "-2\t=2\t+甲乙"), "丙丁甲乙")
+        self.assertEqual(proofread_core.apply_text_delta("甲😀乙", "=1\t-2\t+校\t=1"), "甲校乙")
+
+    def test_change_preview_includes_type_and_new_comment_but_skips_unchanged_metadata(self):
+        article = {
+            "title": "标题",
+            "parts": [{"text": "正文", "type": "paragraph"}],
+            "comments": [],
+        }
+        changes = proofread_core.proofread_change_preview(
+            {"version": 2, "parts": {"0": {"type": "quotation"}}, "comments": {}, "description": "", "newComments": ["新增注释"]},
+            article,
+            {"article": {"title": "标题"}},
+            {},
+        )
+        self.assertEqual(changes, [
+            {"kind": "part_type", "index": 1, "old": "paragraph", "new": "quotation"},
+            {"kind": "new_comment", "index": 1, "text": "新增注释"},
+        ])
+
+    def test_change_preview_keeps_full_text_within_budget(self):
+        long_text = "长文" * 1000
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "标题",
+            "article": {"title": "标题", "page_start": 1, "page_end": 1, "parts": [{"text": long_text, "type": "paragraph"}], "comments": []},
+        }
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={
+                "doc_id": "doc-1",
+                "patch": {"version": 2, "parts": {"0": {"diff": "=1999\t-1\t+新"}}, "comments": {}, "description": ""},
+            })
+        self.assertEqual(response.status_code, 202)
+        changed = dispatch.await_args.args[0]["changed"]
+        self.assertEqual(len(changed[0]["original"]), 2000)
+        self.assertNotIn("…", changed[0]["original"])
+        self.assertEqual(changed[0]["edited"], long_text[:1999] + "新")
+
+    def test_oversized_change_preview_is_clipped_before_dispatch(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "标题",
+            "article": {"title": "标题", "page_start": 1, "page_end": 1, "parts": [{"text": "长文" * 15000, "type": "paragraph"}], "comments": []},
+        }
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={
+                "doc_id": "doc-1",
+                "patch": {"version": 2, "parts": {"0": {"diff": "=29999\t-1\t+新"}}, "comments": {}, "description": ""},
+            })
+        self.assertEqual(response.status_code, 202)
+        payload = dispatch.await_args.args[0]
+        self.assertLessEqual(len(json.dumps(payload, ensure_ascii=False)), proofread_api.CHANGE_PREVIEW_BUDGET_CHARACTERS)
+        original = payload["changed"][0]["original"]
+        self.assertEqual(len(original), 2001)
+        self.assertTrue(original.endswith("…"))
+
+    def test_unicode_payload_over_old_byte_limit_is_accepted(self):
+        inserted = "校" * 18000
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "标题",
+            "article": {"title": "标题", "parts": [{"text": "", "type": "paragraph"}], "comments": []},
+        }
+        dispatch = AsyncMock()
+        request = {
+            "doc_id": "doc-1",
+            "patch": {"version": 2, "parts": {"0": {"diff": f"+{inserted}"}}, "comments": {}, "description": ""},
+        }
+        self.assertGreater(len(json.dumps(request, ensure_ascii=False).encode("utf-8")), 50 * 1024)
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json=request)
+        self.assertEqual(response.status_code, 202)
+        dispatch.assert_awaited_once()
+
+    def test_dispatch_segments_oversized_payload_into_git_blobs(self):
+        calls = []
+
+        class Response:
+            def __init__(self, status_code, payload=None):
+                self.status_code = status_code
+                self._payload = payload or {}
+
+            def json(self):
+                return self._payload
+
+        class Client:
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *_args):
+                return None
+
+            async def post(self, url, **kwargs):
+                calls.append((url, kwargs["json"]))
+                if url.endswith("/git/blobs"):
+                    return Response(201, {"sha": f"{len(calls):040x}"})
+                return Response(204)
+
+        payload = {"request_id": "request-1", "body": {"patch": "中文" * 100}}
+        with patch.object(proofread_api, "DISPATCH_MAX_CHARACTERS", 80), \
+                patch.object(proofread_api, "BLOB_CHUNK_CHARACTERS", 40), \
+                patch.object(pipeline_dispatch.httpx, "AsyncClient", return_value=Client()):
+            asyncio.run(proofread_api.dispatch_proofread(payload))
+        blob_calls = [item for item in calls if item[0].endswith("/git/blobs")]
+        self.assertGreater(len(blob_calls), 1)
+        serialized = "".join(item[1]["content"] for item in blob_calls)
+        self.assertEqual(json.loads(serialized), payload)
+        dispatch = calls[-1][1]["client_payload"]
+        self.assertEqual(dispatch["payload_characters"], len(serialized))
+        self.assertEqual(dispatch["payload_sha256"], proofread_api.hashlib.sha256(serialized.encode()).hexdigest())
+        self.assertEqual(dispatch["request_id"], "request-1")
+
+        calls.clear()
+        property_payload = {f"field_{index}": index for index in range(11)}
+        property_payload["request_id"] = "request-2"
+        with patch.object(proofread_api, "DISPATCH_MAX_CHARACTERS", 1_000_000), \
+                patch.object(pipeline_dispatch.httpx, "AsyncClient", return_value=Client()):
+            asyncio.run(proofread_api.dispatch_proofread(property_payload))
+        self.assertTrue(any(item[0].endswith("/git/blobs") for item in calls))
+        self.assertEqual(calls[-1][1]["client_payload"]["request_id"], "request-2")
+
+    def test_small_body_correction_is_marked_for_auto_merge(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "标题",
+            "article": {
+                "title": "标题", "page_start": 1, "page_end": 1,
+                "parts": [{"text": "旧文", "type": "paragraph"}],
+                "comments": [], "comment_pivots": [], "description": "",
+            },
+        }
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={
+                "doc_id": "doc-1",
+                "patch": {"version": 2, "parts": {"0": {"diff": "=1\t-1\t+新"}}, "comments": {}, "description": ""},
+            })
+        self.assertEqual(response.status_code, 202)
+        self.assertTrue(response.json()["auto_merge"])
+        self.assertTrue(dispatch.await_args.args[0]["auto_merge"])
+
+    def test_multi_part_correction_with_type_and_insert_is_marked_for_auto_merge(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "标题",
+            "article": {
+                "title": "标题", "page_start": 1, "page_end": 1,
+                "parts": [{"text": "第一段", "type": "paragraph"}, {"text": "第二段", "type": "paragraph"}],
+                "comments": [], "comment_pivots": [], "description": "",
+            },
+        }
+        dispatch = AsyncMock()
+        patch_doc = {
+            "version": 2,
+            "parts": {
+                "0": {"diff": "=2\t-1\t+改", "insertAfter": [{"text": "插入段", "type": "paragraph"}]},
+                "1": {"type": "quotation"},
+            },
+            "comments": {}, "description": "",
+        }
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={"doc_id": "doc-1", "patch": patch_doc})
+        self.assertEqual(response.status_code, 202)
+        self.assertTrue(response.json()["auto_merge"])
+        self.assertTrue(dispatch.await_args.args[0]["auto_merge"])
+
+    def test_auto_merge_allows_500_cost_but_rejects_501_or_large_delta(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "标题",
+            "article": {
+                "title": "标题", "page_start": 1, "page_end": 1,
+                "parts": [{"text": "第一段", "type": "paragraph"}],
+                "comments": [], "comment_pivots": [], "description": "",
+            },
+        }
+        dispatch = AsyncMock()
+        cases = [
+            ({"0": {"diff": "=3\t+" + "改" * 500}}, True),
+            ({"0": {"diff": "=3\t+" + "改" * 501}}, False),
+            ({"0": {"insertAfter": [{"text": "改" * 500, "type": "paragraph"}]}}, True),
+            ({"0": {"insertAfter": [{"text": "改" * 501, "type": "paragraph"}]}}, False),
+            ({"0": {"diff": "=3\t+改", "insertAfter": [{"text": "a", "type": "paragraph"} for _ in range(4)]}}, False),
+        ]
+        for patch_doc, expected_auto_merge in cases:
+            with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                    patch.object(source_files, "get_source_doc", return_value=stored), \
+                    patch.object(proofread_api, "dispatch_proofread", dispatch):
+                response = self.client.post("/api/proofread", json={"doc_id": "doc-1", "patch": {"version": 2, "parts": patch_doc, "comments": {}, "description": ""}})
+            self.assertEqual(response.status_code, 202)
+            self.assertEqual(response.json()["auto_merge"], expected_auto_merge)
+            self.assertEqual(dispatch.await_args.args[0].get("auto_merge") is True, expected_auto_merge)
+
+    def test_malformed_patch_is_rejected_before_dispatch(self):
+        stored = {"doc_id": "doc-1", "archive_id": 3, "article_id": "a", "publication_id": "p", "article": {"parts": [], "comments": []}}
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), patch.object(source_files, "get_source_doc", return_value=stored), patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={"doc_id": "doc-1", "patch": {"version": 2}})
+        self.assertEqual(response.status_code, 400)
+        dispatch.assert_not_awaited()
+
+    def test_semantically_empty_patch_is_rejected_before_dispatch(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "a", "publication_id": "p",
+            "article": {"parts": [{"text": "正文", "type": "paragraph"}], "comments": ["注释"]},
+        }
+        patches = [
+            {"version": 2, "parts": {"0": {"delete": False}}, "comments": {}, "description": ""},
+            {"version": 2, "parts": {"0": {"diff": "=2"}}, "comments": {}, "description": ""},
+            {"version": 2, "parts": {"0": {"type": "paragraph"}}, "comments": {}, "description": ""},
+            {"version": 2, "parts": {"0": {"insertAfter": []}}, "comments": {}, "description": ""},
+            {"version": 2, "parts": {}, "comments": {"1": {"diff": "=2"}}, "description": ""},
+            {"version": 2, "parts": {}, "comments": {}, "description": "=0"},
+        ]
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            responses = [self.client.post("/api/proofread", json={"doc_id": "doc-1", "patch": value}) for value in patches]
+        self.assertTrue(all(response.status_code == 400 for response in responses))
+        dispatch.assert_not_awaited()
+
+    def test_unchanged_metadata_is_rejected_before_dispatch(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "a", "publication_id": "p",
+            "title": "标题", "article": {"title": "标题", "parts": [], "comments": []},
+        }
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={
+                "doc_id": "doc-1", "metadata": {"article": {"title": "标题"}},
+            })
+        self.assertEqual(response.status_code, 400)
+        dispatch.assert_not_awaited()
+
+    def test_metadata_requires_exact_string_types(self):
+        stored = {"doc_id": "doc-1", "archive_id": 3, "article_id": "a", "publication_id": "p", "article": {}}
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), patch.object(source_files, "get_source_doc", return_value=stored), patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={"doc_id": "doc-1", "metadata": {"article": {"title": []}}})
+        self.assertEqual(response.status_code, 400)
+        dispatch.assert_not_awaited()
+
+    def test_tag_correction_requires_manual_review(self):
+        stored = {
+            "doc_id": "doc-1", "archive_id": 3, "article_id": "article-1",
+            "publication_id": "publication-1", "title": "标题",
+            "article": {"title": "标题", "page_start": 1, "page_end": 1, "tags": []},
+        }
+        dispatch = AsyncMock()
+        with patch.object(proofread_api, "GITHUB_TOKEN", "secret"), \
+                patch.object(source_files, "get_source_doc", return_value=stored), \
+                patch.object(proofread_api, "dispatch_proofread", dispatch):
+            response = self.client.post("/api/proofread", json={
+                "doc_id": "doc-1",
+                "metadata": {"article": {"tags": [{"name": "标签", "type": "主题/事件"}]}},
+            })
+        self.assertEqual(response.status_code, 202)
+        self.assertFalse(response.json()["auto_merge"])
+        self.assertNotIn("auto_merge", dispatch.await_args.args[0])
+
+    def test_query_length_is_limited(self):
+        response = self.client.post("/api/search", json={"q": "甲" * 257})
+        self.assertEqual(response.status_code, 422)
+        self.assertNotIn("server-timing", response.headers)
+
+    def test_search_rejects_invalid_sort_and_filter_lists_over_500(self):
+        invalid_sort = self.client.post("/api/search", json={"q": "手机", "sort": "dat_desc"})
+        too_many_filters = self.client.post("/api/search", json={"q": "手机", "sources": [str(index) for index in range(501)]})
+        self.assertEqual(invalid_sort.status_code, 422)
+        self.assertEqual(too_many_filters.status_code, 422)
+
+    def test_search_request_mutable_defaults_are_isolated(self):
+        first = search_logic.SearchRequest()
+        second = search_logic.SearchRequest()
+        first.sources.append("刊物")
+        first.date_terms.append({"year": 1966})
+        self.assertEqual(second.sources, [])
+        self.assertEqual(second.date_terms, [])
+
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    @patch.object(runtime, "has_index_data", return_value=False)
+    def test_search_without_index_returns_stable_shape(self, _has_index, _status):
+        response = self.client.post("/api/search", json={"q": "手机", "page": -2, "page_size": 500})
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["results"], [])
+        self.assertEqual(response.json()["page"], 1)
+
+    @patch.object(search_api, "get_search_docs")
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_search_calls_es_and_trims_results(self, _status, _has_index, get_search_docs):
+        stored = {
+            "doc-1": {
+                "doc_id": "doc-1",
+                "title": "手机资料",
+                "publication_name": "测试刊物",
+                "content": "这是手机资料",
+            }
+        }
+        get_search_docs.return_value = stored
+        fake_es = MagicMock()
+        fake_es.search.return_value = {
+            "hits": {
+                "total": {"value": 1},
+                "hits": [{"_id": "doc-1", "_score": 2.0, "highlight": {"content": ["这是<mark>手机</mark>资料"]}}],
+            }
+        }
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": "手机", "exact": False, "page_size": 500})
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["total"], 1)
+        self.assertEqual(payload["page_size"], 100)
+        self.assertEqual(payload["results"][0]["doc_id"], "doc-1")
+        self.assertEqual(payload["results"][0]["title_highlight"], "<mark>手机</mark>资料")
+        for field in ("article_id", "publication_id", "archive_id", "path", "score"):
+            self.assertNotIn(field, payload["results"][0])
+        kwargs = fake_es.search.call_args.kwargs
+        self.assertEqual(kwargs["size"], 100)
+        self.assertNotIn("highlight", kwargs)
+
+    @patch.object(search_api, "get_search_docs", return_value={})
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_empty_relevance_search_uses_stable_doc_id_sort(self, _status, _has_index, _get_docs):
+        fake_es = MagicMock()
+        fake_es.search.return_value = {"hits": {"total": {"value": 0}, "hits": []}}
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": ""})
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(
+            fake_es.search.call_args.kwargs["sort"],
+            [{"doc_id": {"order": "asc"}}],
+        )
+
+    @patch.object(search_api, "get_search_docs", return_value={
+        "doc-1": {"doc_id": "doc-1", "title": "无关标题", "content": "正文手机内容"},
+    })
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_search_omits_redundant_title_highlight(self, _status, _has_index, _get_docs):
+        fake_es = MagicMock()
+        fake_es.search.return_value = {
+            "hits": {"total": {"value": 1}, "hits": [{"_id": "doc-1", "_score": 1.0}]},
+        }
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": "手机"})
+        item = response.json()["results"][0]
+        self.assertEqual(item["title"], "无关标题")
+        self.assertNotIn("title_highlight", item)
+
+    @patch.object(search_api, "get_search_docs", return_value={})
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_identical_search_requests_use_bounded_response_cache(self, _status, _has_index, _get_docs):
+        fake_es = MagicMock()
+        fake_es.search.return_value = {"hits": {"total": {"value": 0}, "hits": []}}
+        with patch.object(runtime, "es", fake_es):
+            first = self.client.post("/api/search", json={"q": "手机", "page": 1, "page_size": 20})
+            second = self.client.post("/api/search", json={"q": "手机", "page": 1, "page_size": 20})
+        self.assertEqual(first.status_code, 200)
+        self.assertEqual(second.status_code, 200)
+        self.assertEqual(fake_es.search.call_count, 1)
+
+    @patch.object(search_api, "get_search_docs", return_value={})
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_search_cache_key_separates_page_and_filter_options(self, _status, _has_index, _get_docs):
+        fake_es = MagicMock()
+        fake_es.search.return_value = {"hits": {"total": {"value": 0}, "hits": []}}
+        with patch.object(runtime, "es", fake_es):
+            self.client.post("/api/search", json={"q": "手机", "page": 1, "page_size": 20})
+            self.client.post("/api/search", json={"q": "手机", "page": 2, "page_size": 20})
+            self.client.post("/api/search", json={"q": "手机", "page": 1, "page_size": 20, "archive_id": 1})
+        self.assertEqual(fake_es.search.call_count, 3)
+
+    def test_search_cache_key_covers_every_result_option(self):
+        base = search_logic.SearchRequest(q="手机")
+        variants = [
+            search_logic.SearchRequest(q="手机", page=2), search_logic.SearchRequest(q="手机", page_size=50),
+            search_logic.SearchRequest(q="手机", exact=False), search_logic.SearchRequest(q="手机", fulltext=False),
+            search_logic.SearchRequest(q="手机", sort="title"), search_logic.SearchRequest(q="手机", source="刊物甲"),
+            search_logic.SearchRequest(q="手机", sources=["刊物甲"]), search_logic.SearchRequest(q="手机", exclude_sources=["刊物乙"]),
+            search_logic.SearchRequest(q="手机", author="作者甲"), search_logic.SearchRequest(q="手机", authors=["作者甲"]),
+            search_logic.SearchRequest(q="手机", exclude_authors=["作者乙"]), search_logic.SearchRequest(q="手机", tag="标签甲"),
+            search_logic.SearchRequest(q="手机", tags=["标签甲"]), search_logic.SearchRequest(q="手机", exclude_tags=["标签乙"]),
+            search_logic.SearchRequest(q="手机", archive_id=3), search_logic.SearchRequest(q="手机", publication_type="期刊"),
+            search_logic.SearchRequest(q="手机", date_from=19660101), search_logic.SearchRequest(q="手机", date_to=19661231),
+            search_logic.SearchRequest(q="手机", date_terms=[{"year": 1966, "month": 5}]),
+        ]
+        keys = {runtime.search_cache_key(item, max(1, item.page), min(max(1, item.page_size), 100)) for item in [base, *variants]}
+        self.assertEqual(len(keys), 1 + len(variants))
+
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_invalid_es_query_returns_400(self, _status, _has_index):
+        fake_es = MagicMock()
+        fake_es.search.side_effect = BadRequestError("bad query", meta=MagicMock(status=400), body={"error": "bad query"})
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": "手机"})
+        self.assertEqual(response.status_code, 400)
+        self.assertEqual(response.json()["error"], "invalid search query")
+
+    @patch.object(search_api, "get_search_docs", return_value={})
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_fulltext_off_does_not_request_highlights(self, _status, _has_index, _get_docs):
+        fake_es = MagicMock()
+        fake_es.search.return_value = {"hits": {"total": {"value": 0}, "hits": []}}
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": "手机", "fulltext": False})
+        self.assertEqual(response.status_code, 200)
+        self.assertNotIn("highlight", fake_es.search.call_args.kwargs)
+
+    @patch.object(search_api, "get_search_docs", side_effect=search_api.SearchStoreError("sidecar failed"))
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_search_storage_failure_returns_503_and_is_not_cached(self, _status, _has_index, _get_docs):
+        fake_es = MagicMock()
+        fake_es.search.return_value = {"hits": {"total": {"value": 1}, "hits": [{"_id": "doc-1"}]}}
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": "手机"})
+        self.assertEqual(response.status_code, 503)
+        self.assertEqual(response.json()["error"], "search storage unavailable")
+        self.assertEqual(runtime.search_response_cache, {})
+
+    @patch.object(search_api, "get_search_docs", return_value={
+        "doc-3": {"doc_id": "doc-3", "title": "手。机资料", "content": "正文手。机内容"},
+    })
+    @patch.object(search_api, "literal_match_ids", return_value={"doc-3"})
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_literal_exact_verification_recomputes_total_across_all_candidates(
+        self, _status, _has_index, _literal_ids, _get_docs,
+    ):
+        fake_es = MagicMock()
+        fake_es.search.side_effect = [
+            {"hits": {"total": {"value": 3}, "hits": [{"_id": "doc-1", "_score": 3.0}]}},
+            {"hits": {"total": {"value": 3}, "hits": [
+                {"_id": "doc-1", "_score": 3.0},
+                {"_id": "doc-2", "_score": 2.0},
+                {"_id": "doc-3", "_score": 1.0},
+            ]}},
+        ]
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post(
+                "/api/search", json={"q": "手。机", "exact": True, "fulltext": True, "page_size": 1},
+            )
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["total"], 1)
+        self.assertEqual([item["doc_id"] for item in response.json()["results"]], ["doc-3"])
+        self.assertEqual(fake_es.search.call_count, 2)
+
+    @patch.object(search_api, "get_search_docs")
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_missing_or_oversized_highlight_fetches_full_fallback_content(self, _status, _has_index, get_search_docs):
+        stored = {"doc-1": {"doc_id": "doc-1", "title": "标题", "content": "后文手机正文"}}
+        get_search_docs.return_value = stored
+        fake_es = MagicMock()
+        fake_es.search.return_value = {
+            "hits": {"total": {"value": 1, "relation": "eq"}, "hits": [
+            {"_id": "doc-1", "highlight": {"content": ["甲" * (search_logic.MAX_HIGHLIGHT_FRAGMENT_CHARS + 1)]}}
+            ]}
+        }
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": "手机", "fulltext": True})
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("<mark>手机</mark>", response.json()["results"][0]["snippet"][0])
+        self.assertEqual(get_search_docs.call_count, 1)
+
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": True, "index_status": "ready"})
+    def test_result_window_limit(self, _status, _has_index):
+        response = self.client.post("/api/search", json={"q": "手机", "page": 5001, "page_size": 100})
+        self.assertEqual(response.status_code, 400)
+        self.assertEqual(response.json()["error"], "result window exceeded")
+
+    def test_unknown_facet_returns_404(self):
+        response = self.client.get("/api/facet/not-a-facet")
+        self.assertEqual(response.status_code, 404)
+
+    @patch.object(runtime, "FACET_DB")
+    @patch.object(runtime, "cached_status_payload", return_value={"index_ready": False, "index_status": "indexing"})
+    def test_sources_and_facets_have_stable_building_shapes_without_sidecar(self, _status, facet_db):
+        facet_db.exists.return_value = False
+        sources = self.client.get("/api/sources").json()
+        facet = self.client.get("/api/facet/source?page=-2&page_size=999").json()
+        self.assertEqual(sources["sources"], [])
+        self.assertTrue(sources["indexing"])
+        self.assertEqual(facet["items"], [])
+        self.assertEqual(facet["page"], 1)
+
+    @patch.object(preview_api, "variants_for_title", return_value=[{"doc_id": "doc-2", "publication_name": "另一刊物"}])
+    @patch.object(preview_api, "get_doc")
+    def test_preview_random_and_spa_routes(self, get_doc, _variants):
+        get_doc.return_value = {
+            "doc_id": "doc-1", "title": "标题", "publication_name": "刊物", "publication_type": "期刊",
+            "authors": ["作者"], "tag_names": ["标签"], "date_display": ["1966/5/16"],
+            "source_files": [], "source_file_count": 0, "content": "正文",
+        }
+        preview = self.client.get("/api/preview/doc-1")
+        self.assertEqual(preview.status_code, 200)
+        self.assertEqual(preview.json()["variants"][0]["doc_id"], "doc-2")
+        with patch.object(preview_api, "random_doc", return_value=get_doc.return_value):
+            self.assertEqual(self.client.get("/api/random").json()["doc_id"], "doc-1")
+        with patch.object(preview_api, "get_doc", return_value=None), patch.object(preview_api, "random_doc", return_value=None):
+            self.assertEqual(self.client.get("/api/preview/missing").status_code, 404)
+            self.assertEqual(self.client.get("/api/random").status_code, 404)
+        self.assertEqual(self.client.get("/").status_code, 200)
+        self.assertEqual(self.client.get("/route/that/does/not/exist").status_code, 200)
+        self.assertIn("BHA Search", self.client.get("/route/that/does/not/exist").text)
+
+    def test_cors_contract(self):
+        response = self.client.options(
+            "/api/search",
+            headers={"Origin": "https://example.com", "Access-Control-Request-Method": "POST"},
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.headers["access-control-allow-origin"], "*")
+        self.assertNotIn("server-timing", response.headers)
+
+    def test_large_responses_prefer_brotli_and_fall_back_to_gzip(self):
+        brotli = self.client.get("/", headers={"Accept-Encoding": "br, gzip"})
+        gzip = self.client.get("/", headers={"Accept-Encoding": "gzip"})
+        identity = self.client.get("/", headers={"Accept-Encoding": "identity"})
+        self.assertEqual(brotli.status_code, 200)
+        self.assertEqual(brotli.headers["content-encoding"], "br")
+        self.assertEqual(gzip.headers["content-encoding"], "gzip")
+        self.assertNotIn("content-encoding", identity.headers)
+        self.assertEqual(brotli.content, identity.content)
+        self.assertEqual(gzip.content, identity.content)
+
+    @patch.object(runtime, "index_status", return_value="failed")
+    @patch.object(runtime, "index_ready", return_value=False)
+    @patch.object(runtime, "document_count", return_value=0)
+    def test_health_ok_reflects_readiness(self, _count, _ready, _status):
+        runtime.status_response_cache = None
+        with patch.object(runtime, "bucket_snapshot_status", return_value={"state": "unavailable", "stage": "validate_sidecars"}):
+            payload = runtime.cached_status_payload()
+        self.assertFalse(payload["ok"])
+        self.assertFalse(payload["index_ready"])
+        self.assertEqual(payload["bucket_snapshot"]["stage"], "validate_sidecars")
+
+    def test_external_generation_switch_changes_response_cache_keys(self):
+        old_generation = ((1, 2, 3, 4), (5, 6, 7, 8))
+        new_generation = ((1, 9, 3, 10), (5, 11, 7, 12))
+        request = search_logic.SearchRequest(q="test")
+        with patch.object(runtime, "serving_generation_token", return_value=old_generation):
+            old_key = runtime.search_cache_key(request, 1, 20)
+        with patch.object(runtime, "serving_generation_token", return_value=new_generation):
+            new_key = runtime.search_cache_key(request, 1, 20)
+        self.assertNotEqual(old_key, new_key)
+
+    def test_serving_generation_is_not_ready_until_shell_status_is_ready(self):
+        with patch.object(runtime, "index_ready", return_value=True), patch.object(runtime, "index_status", return_value="restoring"):
+            self.assertFalse(runtime.serving_generation_ready())
+        with patch.object(runtime, "index_ready", return_value=True), patch.object(runtime, "index_status", return_value="ready"):
+            self.assertTrue(runtime.serving_generation_ready())
+
+    @patch.object(runtime, "cached_status_payload", return_value={
+        "ok": False,
+        "index_ready": False,
+        "document_count": 0,
+        "index_status": "indexing",
+        "progress": {"status": "indexing", "indexed": 42},
+        "es": True,
+    })
+    def test_health_returns_progress_json_with_not_ready_status(self, _status):
+        response = self.client.get("/api/health")
+        self.assertEqual(response.status_code, 503)
+        self.assertEqual(response.json()["progress"]["indexed"], 42)
+        self.assertNotIn("server-timing", response.headers)
+
+    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_bootstrap_is_cached_until_serving_generation_changes(self):
+        generation = ((1, 2, 3, 4), (5, 6, 7, 8))
+        search = bootstrap_api.JSONResponse({
+            "results": [{"doc_id": "doc-1"}], "total": 1, "page": 1, "page_size": 20,
+            "indexing": False, "index_status": "ready",
+        })
+        facet_payloads = {
+            kind: {"items": [{"name": kind}], "total": 1, "page": 1, "page_size": 200, "has_more": False}
+            for kind in ("source", "author", "tag")
+        }
+        with patch.object(runtime, "index_status", return_value="ready"), \
+                patch.object(runtime, "serving_generation_ready", return_value=True), \
+                patch.object(runtime, "serving_generation_token", return_value=generation) as token, \
+                patch.object(runtime, "cached_sources_payload", return_value={"archives": [], "types": [], "years": []}), \
+                patch.object(runtime, "cached_facet_payload", side_effect=lambda kind, *_args: facet_payloads[kind]), \
+                patch.object(bootstrap_api.search_api, "search", return_value=search) as default_search, \
+                patch.object(bootstrap_api, "serving_lock", return_value=nullcontext()):
+            first = bootstrap_api.bootstrap()
+            second = bootstrap_api.bootstrap()
+            token.return_value = ((9, 10, 11, 12), generation[1])
+            third = bootstrap_api.bootstrap()
+        self.assertEqual(first.status_code, 200)
+        self.assertEqual(second.body, first.body)
+        self.assertNotEqual(json.loads(third.body)["generation"], json.loads(first.body)["generation"])
+        self.assertEqual(default_search.call_count, 2)
+        self.assertEqual(first.headers["cache-control"], "no-store")
+
+    def test_reindex_requires_configured_bearer_token(self):
+        with patch.object(reindex_api, "REINDEX_TOKEN", ""), patch.object(reindex_api, "acquire_index_lock") as acquire_lock:
+            response = self.client.post("/api/reindex")
+        self.assertEqual(response.status_code, 503)
+        self.assertEqual(response.headers["cache-control"], "no-store")
+        acquire_lock.assert_not_called()
+
+        with patch.object(reindex_api, "REINDEX_TOKEN", "secret"), patch.object(reindex_api, "acquire_index_lock") as acquire_lock:
+            response = self.client.post("/api/reindex", headers={"Authorization": "Bearer wrong"})
+        self.assertEqual(response.status_code, 401)
+        self.assertEqual(response.headers["www-authenticate"], "Bearer")
+        acquire_lock.assert_not_called()
+
+    def test_authenticated_reindex_starts_once_with_short_cooldown(self):
+        lock_file = MagicMock()
+        with tempfile.TemporaryDirectory() as directory, \
+                patch.object(reindex_api, "REINDEX_TOKEN", "secret"), \
+                patch.object(reindex_api, "REINDEX_LAST_START", Path(directory) / "last-start"), \
+                patch.object(reindex_api, "acquire_index_lock", return_value=lock_file), \
+                patch.object(reindex_api, "start_reindex_worker") as start_worker:
+            response = self.client.post("/api/reindex", headers={"Authorization": "Bearer secret"})
+        self.assertEqual(response.status_code, 202)
+        self.assertEqual(response.json()["cooldown_seconds"], 600)
+        start_worker.assert_called_once_with(lock_file, reset=False)
+        self.assertEqual(response.json()["mode"], "incremental")
+        lock_file.close.assert_not_called()
+
+    def test_authenticated_reindex_can_request_explicit_full_rebuild(self):
+        lock_file = MagicMock()
+        with tempfile.TemporaryDirectory() as directory, \
+                patch.object(reindex_api, "REINDEX_TOKEN", "secret"), \
+                patch.object(reindex_api, "REINDEX_LAST_START", Path(directory) / "last-start"), \
+                patch.object(reindex_api, "acquire_index_lock", return_value=lock_file), \
+                patch.object(reindex_api, "start_reindex_worker") as start_worker:
+            response = self.client.post(
+                "/api/reindex?full=true", headers={"Authorization": "Bearer secret"}
+            )
+        self.assertEqual(response.status_code, 202)
+        self.assertEqual(response.json()["mode"], "full")
+        start_worker.assert_called_once_with(lock_file, reset=True)
+
+    def test_reindex_passes_exact_archive_identities_to_worker(self):
+        lock_file = MagicMock()
+        commits = {str(value): "a" * 40 for value in range(32)}
+        revisions = {str(value): "b" * 40 for value in range(32)}
+        with tempfile.TemporaryDirectory() as directory, \
+                patch.object(reindex_api, "REINDEX_TOKEN", "secret"), \
+                patch.object(reindex_api, "REINDEX_LAST_START", Path(directory) / "last-start"), \
+                patch.object(reindex_api, "acquire_index_lock", return_value=lock_file), \
+                patch.object(reindex_api, "start_reindex_worker") as start_worker:
+            response = self.client.post("/api/reindex", headers={"Authorization": "Bearer secret"}, json={
+                "archive_commits": commits,
+                "archive_revisions": revisions,
+                "changed_archives": [0, 4],
+            })
+        self.assertEqual(response.status_code, 202)
+        start_worker.assert_called_once_with(
+            lock_file, reset=False,
+            expected_commits={value: "a" * 40 for value in range(32)},
+            expected_revisions={value: "b" * 40 for value in range(32)},
+            changed_archives=[0, 4],
+        )
+
+    def test_reindex_marks_ready_before_starting_snapshot_publish(self):
+        lock_file = MagicMock()
+        thread = MagicMock()
+        with tempfile.TemporaryDirectory() as directory, \
+                patch.object(runtime, "INDEX_STATUS_PATH", Path(directory) / "status"), \
+                patch.object(reindex_api, "BUCKET_DIR", Path(directory)), \
+                patch.object(reindex_api, "ensure_index", return_value=True), \
+                patch.object(reindex_api.threading, "Thread", return_value=thread):
+            reindex_api.run_reindex(lock_file)
+            self.assertEqual(runtime.INDEX_STATUS_PATH.read_text(encoding="utf-8"), "ready")
+        thread.start.assert_called_once_with()
+        lock_file.close.assert_called_once_with()
+
+    def test_reindex_noop_does_not_publish_snapshot(self):
+        lock_file = MagicMock()
+        thread = MagicMock()
+        with tempfile.TemporaryDirectory() as directory, \
+                patch.object(runtime, "INDEX_STATUS_PATH", Path(directory) / "status"), \
+                patch.object(reindex_api, "BUCKET_DIR", Path(directory)), \
+                patch.object(reindex_api, "ensure_index", return_value=False), \
+                patch.object(reindex_api.threading, "Thread", return_value=thread):
+            reindex_api.run_reindex(lock_file)
+        thread.assert_not_called()
+        lock_file.close.assert_called_once_with()
+
+    def test_reindex_failure_with_pending_switch_is_not_marked_ready(self):
+        lock_file = MagicMock()
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            switch_state = root / "index-switch.json"
+            switch_state.write_text("{}", encoding="utf-8")
+            status = root / "index-status"
+            with patch.object(runtime, "INDEX_SWITCH_STATE_PATH", switch_state), \
+                    patch.object(runtime, "INDEX_STATUS_PATH", status), \
+                    patch.object(reindex_api, "BUCKET_DIR", None), \
+                    patch.object(reindex_api, "ensure_index", side_effect=RuntimeError("uncertain switch")), \
+                    patch.object(runtime, "index_ready", return_value=True):
+                reindex_api.run_reindex(lock_file)
+            self.assertEqual(status.read_text(encoding="utf-8"), "failed")
+            lock_file.close.assert_called_once_with()
+
+    def test_reindex_failure_keeps_valid_serving_generation_ready(self):
+        lock_file = MagicMock()
+        with tempfile.TemporaryDirectory() as directory:
+            status = Path(directory) / "index-status"
+            with patch.object(runtime, "INDEX_SWITCH_STATE_PATH", Path(directory) / "missing-switch.json"), \
+                    patch.object(runtime, "INDEX_STATUS_PATH", status), \
+                    patch.object(reindex_api, "BUCKET_DIR", None), \
+                    patch.object(reindex_api, "ensure_index", side_effect=RuntimeError("database is locked")), \
+                    patch.object(runtime, "serving_generation_valid", return_value=True):
+                reindex_api.run_reindex(lock_file)
+            self.assertEqual(status.read_text(encoding="utf-8"), "ready")
+            lock_file.close.assert_called_once_with()
+
+    def test_serving_generation_validation_retries_transient_sidecar_lock(self):
+        fake_es = MagicMock()
+        fake_es.get.return_value = {"_source": {"version": "1"}}
+        with patch.object(runtime, "es", fake_es), \
+                patch.object(runtime, "sidecars_ready", side_effect=[False, False, True]) as sidecars_ready, \
+                patch.object(runtime.time, "sleep") as sleep:
+            self.assertTrue(runtime.serving_generation_valid())
+        self.assertEqual(sidecars_ready.call_count, 3)
+        self.assertEqual(sleep.call_count, 2)
+
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "index_status", return_value="restoring")
+    def test_search_does_not_read_restoring_generation(self, _status, _has_data):
+        fake_es = MagicMock()
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": "文化革命"})
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["results"], [])
+        self.assertTrue(response.json()["indexing"])
+        fake_es.search.assert_not_called()
+
+    @patch.object(runtime, "has_index_data", return_value=True)
+    @patch.object(runtime, "index_status", return_value="failed")
+    def test_search_does_not_serve_failed_generation(self, _status, _has_data):
+        fake_es = MagicMock()
+        with patch.object(runtime, "es", fake_es):
+            response = self.client.post("/api/search", json={"q": "文化革命"})
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["results"], [])
+        self.assertEqual(response.json()["index_status"], "failed")
+        fake_es.search.assert_not_called()
+
+    @patch.object(runtime, "index_status", return_value="restoring")
+    @patch.object(preview_api, "get_doc")
+    def test_preview_is_blocked_during_restore(self, get_doc, _status):
+        response = self.client.get("/api/preview/doc-1")
+        self.assertEqual(response.status_code, 503)
+        get_doc.assert_not_called()
+
+    def test_preview_payload_exposes_mirrored_pdf_page_previews(self):
+        stored = {
+            "doc_id": "doc-1", "title": "资料",
+            "source_files": ["https://raw.githubusercontent.com/o/r/main/a.pdf"],
+        }
+        entry = {"page_previews": {"paths": ["archives0/aa/one.webp", "archives0/bb/two.webp"]}}
+        with patch.object(source_files, "source_mirror_entry", AsyncMock(return_value=entry)), \
+                patch.object(preview_api, "serving_lock", return_value=nullcontext()):
+            payload = asyncio.run(preview_api.preview_payload(stored))
+        self.assertEqual(
+            payload["source_files"][0]["pages"],
+            [
+                "https://huggingface.co/datasets/vomebook/BHA-Source-Files/resolve/main/archives0/aa/one.webp",
+                "https://huggingface.co/datasets/vomebook/BHA-Source-Files/resolve/main/archives0/bb/two.webp",
+            ],
+        )
+
+    def test_source_and_facet_cache_ttl_is_ten_minutes(self):
+        self.assertEqual(runtime.FACET_CACHE_TTL_SECONDS, 600)
+
+    @patch.object(runtime, "warm_static_files", return_value=True)
+    @patch.object(runtime, "clear_response_caches")
+    @patch.object(runtime, "cached_facet_payload", return_value={"items": []})
+    @patch.object(runtime, "available_years", return_value=[1966])
+    @patch.object(runtime, "cached_sources_payload", return_value={})
+    @patch.object(runtime, "warmup_db", return_value=True)
+    @patch.object(runtime, "warmup_elasticsearch", return_value=True)
+    def test_full_auxiliary_warmup_clears_caches_and_loads_sidecars(
+        self,
+        _elasticsearch,
+        _warmup_db,
+        _sources,
+        _years,
+        facet,
+        clear_caches,
+        _static,
+    ):
+        result = runtime.run_auxiliary_warmup(full=True)
+        self.assertTrue(result["ok"])
+        self.assertTrue(result["elasticsearch_warmed"])
+        self.assertEqual(facet.call_count, 3)
+        clear_caches.assert_called_once()
+
+    @patch.object(runtime, "warm_static_files", return_value=True)
+    @patch.object(runtime, "clear_response_caches")
+    @patch.object(runtime, "cached_facet_payload", return_value={"items": []})
+    @patch.object(runtime, "available_years", return_value=[])
+    @patch.object(runtime, "cached_sources_payload", return_value={})
+    @patch.object(runtime, "warmup_db", return_value=True)
+    @patch.object(runtime, "warmup_elasticsearch", return_value=True)
+    def test_periodic_auxiliary_warmup_preserves_response_caches(
+        self,
+        _elasticsearch,
+        _warmup_db,
+        _sources,
+        _years,
+        facet,
+        clear_caches,
+        _static,
+    ):
+        result = runtime.run_auxiliary_warmup(full=False)
+        self.assertTrue(result["ok"])
+        self.assertEqual(facet.call_count, 3)
+        clear_caches.assert_not_called()
+
+    @patch.object(runtime, "es")
+    def test_elasticsearch_warmup_is_a_result_free_match_all_query(self, fake_es):
+        self.assertTrue(runtime.warmup_elasticsearch())
+        fake_es.search.assert_called_once_with(
+            index=runtime.INDEX_NAME,
+            size=0,
+            track_total_hits=False,
+            query={"match_all": {}},
+            _source=False,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_browser.py

@@ -0,0 +1,627 @@
+import json
+import os
+import re
+import base64
+import socket
+import subprocess
+import sys
+import time
+import unittest
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+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():
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+def minimal_pdf():
+    stream = b"BT /F1 18 Tf 20 100 Td (BHA PDF) Tj ET"
+    objects = [
+        b"<< /Type /Catalog /Pages 2 0 R >>",
+        b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+        b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Resources << /Font << /F1 5 0 R >> >> /Contents 4 0 R >>",
+        b"<< /Length " + str(len(stream)).encode() + b" >>\nstream\n" + stream + b"\nendstream",
+        b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    ]
+    payload = bytearray(b"%PDF-1.4\n%\xe2\xe3\xcf\xd3\n")
+    offsets = [0]
+    for number, body in enumerate(objects, 1):
+        offsets.append(len(payload))
+        payload.extend(f"{number} 0 obj\n".encode() + body + b"\nendobj\n")
+    xref = len(payload)
+    payload.extend(f"xref\n0 {len(objects) + 1}\n".encode())
+    payload.extend(b"0000000000 65535 f \n")
+    for offset in offsets[1:]:
+        payload.extend(f"{offset:010d} 00000 n \n".encode())
+    payload.extend(f"trailer\n<< /Size {len(objects) + 1} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n".encode())
+    return bytes(payload)
+
+
+@unittest.skipUnless(sync_playwright, "install requirements-test.txt and run: playwright install chromium")
+class BrowserInteractionTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.port = free_port()
+        cls.base_url = f"http://127.0.0.1:{cls.port}"
+        env = {**os.environ, "APP_ROOT": str(BASE_DIR), "DATA_ROOT": str(BASE_DIR / "data")}
+        cls.server = subprocess.Popen(
+            [sys.executable, "-m", "uvicorn", "app.main:app", "--host", "127.0.0.1", "--port", str(cls.port), "--log-level", "warning"],
+            cwd=BASE_DIR, env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        )
+        for _ in range(80):
+            try:
+                with urlopen(cls.base_url + "/", timeout=1) as response:
+                    if response.status == 200:
+                        break
+            except Exception:
+                time.sleep(0.25)
+        else:
+            cls.server.terminate()
+            raise RuntimeError("BHA browser test server did not start")
+        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()
+        cls.server.terminate()
+        try:
+            cls.server.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            cls.server.kill()
+
+    def open_page(self, viewport=None, preview_parts=None, track_empty=False, bootstrap_total=1):
+        context = self.browser.new_context(viewport=viewport or {"width": 1440, "height": 900}, accept_downloads=True)
+        page = context.new_page()
+        errors = []
+        if track_empty:
+            page.add_init_script("""
+              window.__emptyStateWasVisible = false;
+              document.addEventListener("DOMContentLoaded", () => {
+                const empty = document.querySelector("#empty-state");
+                new MutationObserver(() => {
+                  if (getComputedStyle(empty).display !== "none") window.__emptyStateWasVisible = true;
+                }).observe(empty, { attributes: true, attributeFilter: ["style", "hidden"] });
+              });
+            """)
+        page.on("pageerror", lambda error: errors.append(str(error)))
+        results = [{
+            "doc_id": "doc-1", "title": "手机资料", "title_highlight": "<mark>手机</mark>资料",
+            "publication_name": "测试刊物", "publication_type": "期刊", "authors": ["作者甲"],
+            "tag_names": ["标签甲"], "date_display": ["1966/5/16"], "source_file_count": 0,
+            "snippet": ["这是<mark>手机</mark>正文"], "score": 1,
+        }]
+        preview = {
+            "doc_id": "doc-1", "title": "手机资料", "publication_name": "测试刊物",
+            "publication_author": "出版者", "publication_type": "期刊", "authors": ["作者甲"], "tag_names": ["标签甲"],
+            "date_display": ["1966/5/16"], "source_file_count": 1, "content": "这是手机正文", "variants": [],
+            "article_id": "article-1", "publication_id": "publication-1", "archive_id": 1,
+            "source_files": [{"index": 0, "name": "原稿.pdf", "url": "https://example.com/source.pdf"}],
+            "article": {"title": "手机资料", "authors": ["作者甲"], "dates": [{"year": 1966, "month": 5, "day": 16}], "tags": [{"type": "主题/事件", "name": "标签甲"}, {"name": "标签乙"}], "page_start": 2, "page_end": 2, "description": "", "parts": preview_parts or [{"type": "paragraph", "text": "这是手机正文"}], "comments": [], "comment_pivots": []},
+        }
+        pdf = minimal_pdf()
+
+        def route_api(route, request):
+            path = request.url.split(self.base_url, 1)[-1]
+            if path.startswith("/api/bootstrap"):
+                facet = lambda name: {"items": [{"name": name, "value": name, "count": 1}], "total": 1, "page": 1, "page_size": 200, "has_more": False}
+                payload = {
+                    "generation": "test-generation",
+                    "search": {"results": results, "total": bootstrap_total, "page": 1, "page_size": 20, "indexing": False, "index_status": "ready"},
+                    "sources": {"archives": [{"name": "3", "value": 3, "count": 1}], "types": [{"name": "期刊", "value": "期刊", "count": 1}], "years": [{"name": "1966", "value": 1966, "count": 0}]},
+                    "facets": {"source": facet("测试刊物"), "author": facet("作者甲"), "tag": facet("标签甲")},
+                }
+            elif path.startswith("/api/search"):
+                body = request.post_data_json or {}
+                payload = {"results": results, "total": bootstrap_total, "page": body.get("page", 1), "page_size": body.get("page_size", 20), "indexing": False, "index_status": "ready"}
+            elif path.startswith("/api/sources"):
+                payload = {"sources": [], "authors": [], "tags": [], "archives": [{"name": "3", "value": 3, "count": 1}], "types": [{"name": "期刊", "value": "期刊", "count": 1}], "years": [{"name": "1966", "value": 1966, "count": 0}], "indexing": False, "index_status": "ready"}
+            elif path.startswith("/api/facet/"):
+                kind = path.split("/api/facet/", 1)[1].split("?", 1)[0]
+                name = {"source": "测试刊物", "author": "作者甲", "tag": "标签甲"}[kind]
+                has_query = bool(parse_qs(urlparse(path).query).get("q"))
+                show_item = has_query or kind != "tag"
+                payload = {"items": [{"name": name, "value": name, "count": 1}] if show_item else [], "total": 1 if show_item else 0, "page": 1, "page_size": 500 if has_query else 200, "has_more": False, "indexing": False, "index_status": "ready"}
+            elif path.startswith("/api/preview/source/"):
+                match = re.fullmatch(r"bytes=(\d+)-(\d+)", request.headers.get("range", ""))
+                if not match:
+                    route.fulfill(status=416, body=b"")
+                    return
+                begin = int(match.group(1))
+                end = min(int(match.group(2)), len(pdf) - 1)
+                chunk = pdf[begin:end + 1]
+                route.fulfill(status=206, body=chunk, headers={
+                    "Content-Type": "application/pdf",
+                    "Content-Range": f"bytes {begin}-{end}/{len(pdf)}",
+                    "Content-Length": str(len(chunk)),
+                    "Accept-Ranges": "bytes",
+                })
+                return
+            elif path.startswith("/api/preview/") or path.startswith("/api/random"):
+                payload = preview
+            elif path.startswith("/api/health"):
+                payload = {"ok": True, "es": True, "index_ready": True, "index_status": "ready", "document_count": 1, "progress": None}
+            elif path.startswith("/api/download/txt/"):
+                route.fulfill(status=200, body="标题：手机资料\n\n这是手机正文", headers={"Content-Type": "text/plain; charset=utf-8", "Content-Disposition": "attachment; filename*=UTF-8''test.txt"})
+                return
+            else:
+                payload = {}
+            route.fulfill(status=200, content_type="application/json", body=json.dumps(payload, ensure_ascii=False))
+
+        page.route("**/api/**", route_api)
+        page.goto(self.base_url, wait_until="domcontentloaded")
+        page.locator(".result-item").wait_for(timeout=15000)
+        return context, page, errors
+
+    def test_default_screen_hydrates_then_prefetches_the_next_page(self):
+        context, page, errors = self.open_page(track_empty=True, bootstrap_total=21)
+        try:
+            page.wait_for_function("""performance.getEntriesByType('resource')
+                .some((entry) => new URL(entry.name).pathname === '/api/search')""")
+            api_paths = page.evaluate("""performance.getEntriesByType('resource')
+                .map((entry) => new URL(entry.name).pathname).filter((path) => path.startsWith('/api/'))""")
+            self.assertEqual(api_paths, ["/api/bootstrap", "/api/search"])
+            self.assertEqual(page.locator("#source-filter [data-source]").count(), 1)
+            self.assertFalse(page.evaluate("window.__emptyStateWasVisible"))
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_parse_crop_filters_ocr_and_submits_page_thresholds(self):
+        context = self.browser.new_context(viewport={"width": 1440, "height": 900})
+        page = context.new_page()
+        errors = []
+        submitted = []
+        page.on("pageerror", lambda error: errors.append(str(error)))
+        page.on("dialog", lambda dialog: dialog.accept())
+        png = base64.b64decode("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=")
+        queue_item = {
+            "doc_id": "parse-doc", "archive_id": 25, "publication_id": "052417de-42fb-4781-9885-af4fb006e9b6",
+            "publication_name": "待拆小报", "title": "【文章待拆分】待拆小报", "publication_type": "img",
+            "authors": [], "date_display": ["1967/5/12"], "page_start": 1, "page_end": 1, "source_files": ["one"],
+        }
+        preview = {
+            **queue_item, "content_hash": "a" * 64, "content": "页眉\n正文", "variants": [],
+            "article": {"title": queue_item["title"], "authors": [], "dates": [{"year": 1967, "month": 5, "day": 12}], "page_start": 1, "page_end": 1},
+        }
+
+        def route_api(route, request):
+            path = request.url.split(self.base_url, 1)[-1]
+            if path.startswith("/api/parse/queue"):
+                payload = {"total": 1, "page": 1, "page_size": 100, "items": [queue_item]}
+            elif path.startswith("/api/parse/parse-doc/ocr"):
+                payload = {"page": 1, "dimensions": {"width": 1000, "height": 1000}, "ocr_results": [
+                    {"text": "页眉", "box": [[400, 20], [600, 20], [600, 80], [400, 80]]},
+                    {"text": "正文", "box": [[400, 450], [600, 450], [600, 550], [400, 550]]},
+                ]}
+            elif path.startswith("/api/preview/source/parse-doc"):
+                route.fulfill(status=200, body=png, headers={"Content-Type": "image/png"})
+                return
+            elif path.startswith("/api/preview/parse-doc"):
+                payload = preview
+            elif path == "/api/parse" and request.method == "POST":
+                submitted.append(request.post_data_json)
+                route.fulfill(status=202, content_type="application/json", body='{"ok":true}')
+                return
+            elif path.startswith("/api/health"):
+                payload = {"ok": True, "es": True, "index_status": "ready", "progress": None}
+            elif path.startswith("/api/sources"):
+                payload = {"sources": [], "authors": [], "tags": [], "archives": [], "types": [], "years": [], "indexing": False, "index_status": "ready"}
+            elif path.startswith("/api/facet/"):
+                payload = {"items": [], "total": 0, "page": 1, "page_size": 200, "has_more": False}
+            else:
+                payload = {}
+            route.fulfill(status=200, content_type="application/json", body=json.dumps(payload, ensure_ascii=False))
+
+        page.route("**/api/**", route_api)
+        try:
+            page.goto(self.base_url + "/?parse=1", wait_until="domcontentloaded")
+            page.locator("[data-parse-open]").click()
+            page.locator("[data-parse-content]").wait_for()
+            page.wait_for_function("document.querySelector('[data-parse-content]').value.includes('页眉')")
+            page.locator("[data-parse-crop-toggle]").click()
+            page.locator("[data-parse-crop-scope='page']").click()
+            overlay = page.locator("[data-parse-crop-overlay]").bounding_box()
+            handle = page.locator("[data-crop-handle='top']").bounding_box()
+            page.mouse.move(handle["x"] + handle["width"] / 2, handle["y"] + handle["height"] / 2)
+            page.mouse.down()
+            page.mouse.move(handle["x"] + handle["width"] / 2, handle["y"] + overlay["height"] * 0.2)
+            page.mouse.up()
+            page.wait_for_function("document.querySelector('[data-parse-content]').value === '正文'")
+            page.set_viewport_size({"width": 390, "height": 844})
+            page.locator("#mobile-toggle-btn").click()
+            self.assertTrue(page.locator("body").evaluate("node => node.classList.contains('mobile')"))
+            self.assertLessEqual(page.evaluate("document.documentElement.scrollWidth"), 390)
+            page.locator("[data-parse-title]").fill("第一篇")
+            page.locator("[data-parse-form] button[type='submit']").click()
+            page.wait_for_function("document.querySelector('#toast').textContent.includes('解析已提交')")
+            thresholds = submitted[0]["articles"][0]["ocr_exceptions"]["1"]["content_thresholds"]
+            self.assertGreater(thresholds[0], 0.15)
+            self.assertEqual(submitted[0]["articles"][0]["content"], "正文")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_desktop_search_filters_preview_theme_and_download(self):
+        context, page, errors = self.open_page()
+        try:
+            page.locator("#search-input").fill("文化革命")
+            page.wait_for_timeout(250)
+            self.assertIn("q=", page.url)
+            page.locator("label:has(#exact-toggle)").click()
+            page.locator("label:has(#fulltext-toggle)").click()
+            page.locator("#sort-filter").select_option("title")
+            page.locator("#source-filter [data-source]").click()
+            self.assertIn("source=", page.url)
+            original = page.locator("body").get_attribute("class")
+            page.locator("#theme-btn").click()
+            self.assertNotEqual(original, page.locator("body").get_attribute("class"))
+            page.locator("[data-preview]").click()
+            page.locator("#preview-panel").wait_for(state="visible")
+            self.assertIn("这是", page.locator(".preview-body").text_content())
+            page.locator("[data-close-preview]").click()
+            with page.expect_download(timeout=10000) as info:
+                page.locator('a[href^="/api/download/txt/"]').click()
+            self.assertTrue(info.value.suggested_filename.endswith(".txt"))
+            page.locator("#random-book-btn").click()
+            page.locator("#preview-panel").wait_for(state="visible")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_result_date_click_syncs_date_terms_ui(self):
+        context, page, errors = self.open_page()
+        try:
+            page.locator("#left-toggle").click()
+            page.locator("[data-date-term-label='1966/5/16']").click()
+            term = page.locator("[data-date-term-index='0']")
+            self.assertEqual(term.locator("[data-date-term-field='year']").input_value(), "1966")
+            self.assertEqual(term.locator("[data-date-term-field='month']").input_value(), "5")
+            self.assertEqual(term.locator("[data-date-term-field='day']").input_value(), "16")
+            self.assertIn("date_term=year%3A1966-month%3A5-day%3A16", page.url)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_proofread_compare_mode_is_usable_on_desktop_and_mobile(self):
+        for viewport in ({"width": 1440, "height": 900}, {"width": 390, "height": 844}):
+            context, page, errors = self.open_page(viewport)
+            try:
+                if page.locator("body").evaluate("node => node.classList.contains('mobile')") and page.locator("#left-sidebar").evaluate("node => node.classList.contains('open')"):
+                    page.locator("#left-toggle").click()
+                page.locator("[data-preview]").click()
+                if viewport["width"] > 600:
+                    page.locator("[data-proofread-select]").evaluate("node => { const range = document.createRange(); range.selectNodeContents(node); const selection = window.getSelection(); selection.removeAllRanges(); selection.addRange(range); node.dispatchEvent(new MouseEvent('mouseup', { bubbles: true })); }")
+                else:
+                    page.locator("[data-compare-select]").select_option("__proofread__")
+                page.locator("[data-proofread-form]").wait_for(state="visible")
+                page.wait_for_function("typeof diff_match_patch !== 'undefined'")
+                self.assertTrue(page.locator("[data-proofread-back]").is_visible())
+                self.assertTrue(page.locator("[data-preview-mobile]").is_visible() if viewport["width"] <= 600 else True)
+                self.assertEqual(page.locator("[data-meta-title]").input_value(), "手机资料")
+                self.assertEqual(page.locator("[data-proofread-part-input='0']").input_value(), "这是手机正文")
+                delta = page.evaluate("textDelta('旧〔1〕文', '新〔1〕文')")
+                self.assertIn("新", delta)
+                self.assertNotIn("%E6%96%B0", delta)
+                applied = page.evaluate("([original, delta]) => applyTextDelta(original, delta)", ["旧〔1〕文", delta])
+                self.assertEqual(applied, "新〔1〕文")
+                moved = page.evaluate("() => { const original = '甲乙共同段丙丁'; const edited = '丙丁甲乙共同段'; const delta = textDelta(original, edited); return { delta, applied: applyTextDelta(original, delta) }; }")
+                self.assertEqual(moved["applied"], "丙丁甲乙共同段")
+                self.assertIn("=", moved["delta"], (viewport, moved))
+                self.assertGreaterEqual(len(moved["delta"].split("\t")), 3)
+                escaped = page.evaluate("() => { const original = '甲乙'; const edited = '甲%\t校乙'; const delta = textDelta(original, edited); return { delta, applied: applyTextDelta(original, delta) }; }")
+                self.assertEqual(escaped["applied"], "甲%\t校乙")
+                self.assertIn("%25", escaped["delta"])
+                self.assertIn("%09", escaped["delta"])
+                source_box = page.locator(".proofread-source").bounding_box()
+                editor_box = page.locator(".proofread-editor").bounding_box()
+                self.assertIsNotNone(source_box)
+                self.assertIsNotNone(editor_box)
+                if viewport["width"] > 600:
+                    self.assertLessEqual(source_box["x"] + source_box["width"], editor_box["x"] + 1)
+                else:
+                    self.assertLessEqual(source_box["y"] + source_box["height"], editor_box["y"] + 1)
+                self.assertEqual(errors, [])
+            finally:
+                context.close()
+
+    def test_proofread_page_images_refit_and_recover_after_error(self):
+        context, page, errors = self.open_page()
+        first = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='80'%3E%3Crect width='120' height='80' fill='white'/%3E%3C/svg%3E"
+        broken = "data:image/webp;base64,AAAA"
+        third = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='800' height='100'%3E%3Crect width='800' height='100' fill='white'/%3E%3C/svg%3E"
+        try:
+            page.locator("[data-preview]").click()
+            page.locator("#preview-panel").wait_for(state="visible")
+            page.evaluate("""([first, broken, third]) => {
+              const item = getCachedPreview(STATE.preview);
+              item.source_files = [{ index: 0, name: "原稿.pdf", url: "https://example.com/source.pdf", pages: [first, broken, third] }];
+              STATE.proofreadFile = "0";
+              STATE.proofreadPage = "1";
+              openProofread(item, null, true);
+            }""", [first, broken, third])
+            image = page.locator("[data-proofread-source-image]")
+            page.wait_for_function("document.querySelector('[data-proofread-source-image]').naturalWidth === 120")
+            first_width = image.get_attribute("data-image-base-width")
+            page.locator("[data-page-image-next]").click()
+            page.locator("[data-image-error]").wait_for(state="visible")
+            self.assertTrue(image.is_hidden())
+            page.locator("[data-page-image-next]").click()
+            page.wait_for_function("document.querySelector('[data-proofread-source-image]').naturalWidth === 800 && !document.querySelector('[data-proofread-source-image]').hidden")
+            self.assertNotEqual(first_width, image.get_attribute("data-image-base-width"))
+            self.assertEqual(page.locator("[data-page-image-input]").input_value(), "3")
+            self.assertIn("proofread_page=3", page.url)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_pdf_range_transport_rejects_invalid_followup_ranges(self):
+        context, page, errors = self.open_page()
+        try:
+            result = page.evaluate("""async () => {
+              class Transport {
+                constructor(length, initialData) { this.length = length; this.initialData = initialData; }
+                onDataRange() {}
+              }
+              const originalFetch = window.fetch;
+              let request = 0;
+              window.fetch = async () => {
+                request += 1;
+                if (request === 1) {
+                  return new Response(new Uint8Array(8), { status: 206, headers: { "Content-Range": "bytes 0-7/8" } });
+                }
+                return new Response(new Uint8Array(4), { status: 206, headers: { "Content-Range": "bytes 0-3/8" } });
+              };
+              try {
+                const range = await createPDFRangeTransport({ PDFDataRangeTransport: Transport }, "https://example.test/file.pdf");
+                range.requestDataRange(4, 8);
+                try { await range.failurePromise; return false; } catch (_error) { return true; }
+              } finally {
+                window.fetch = originalFetch;
+              }
+            }""")
+            self.assertTrue(result)
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_real_pdf_worker_renders_and_download_stays_in_toolbar(self):
+        context, page, errors = self.open_page()
+        try:
+            page.locator("[data-preview]").click()
+            page.locator("[data-compare-select]").select_option("__proofread__")
+            page.wait_for_function("document.querySelector('[data-pdf-status]')?.textContent === '1 / 1'", timeout=20000)
+            self.assertGreater(page.locator("[data-pdf-canvas]").evaluate("canvas => canvas.width"), 0)
+            download = page.locator(".proofread-pdf-tools [data-pdf-download-link]")
+            self.assertTrue(download.is_visible())
+            page.locator('[data-pdf-action="zoom-in"]').evaluate("button => { button.click(); button.click(); button.click(); }")
+            page.wait_for_timeout(300)
+            self.assertEqual(page.locator("[data-pdf-status]").text_content(), "1 / 1")
+            self.assertEqual(page.evaluate("pdfDocumentCache.size"), 1)
+            page.evaluate("window.dispatchEvent(new PageTransitionEvent('pagehide'))")
+            page.wait_for_function("pdfDocumentCache.size === 0")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_proofread_draft_writes_are_debounced(self):
+        context, page, errors = self.open_page()
+        try:
+            page.locator("[data-preview]").click()
+            page.locator("[data-compare-select]").select_option("__proofread__")
+            page.evaluate("sessionStorage.removeItem(`bha-proofread-draft:${STATE.preview}`)")
+            page.locator('[data-proofread-part-input="0"]').fill("防抖后的正文")
+            self.assertIsNone(page.evaluate("sessionStorage.getItem(`bha-proofread-draft:${STATE.preview}`)"))
+            page.wait_for_timeout(500)
+            draft = json.loads(page.evaluate("sessionStorage.getItem(`bha-proofread-draft:${STATE.preview}`)"))
+            self.assertEqual(draft["parts"]["0"], "防抖后的正文")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_fulltext_apply_is_idempotent_and_syncs_with_parts(self):
+        context, page, errors = self.open_page()
+        try:
+            page.locator("[data-preview]").click()
+            page.locator("#preview-panel").wait_for(state="visible")
+            page.locator("[data-proofread-select]").evaluate("node => { const range = document.createRange(); range.selectNodeContents(node); const selection = window.getSelection(); selection.removeAllRanges(); selection.addRange(range); node.dispatchEvent(new MouseEvent('mouseup', { bubbles: true })); }")
+            page.locator("[data-proofread-form]").wait_for(state="visible")
+            page.locator("[data-fulltext-input]").fill("第一段\n第二段\n第三段")
+            page.locator("[data-fulltext-apply]").click()
+            page.wait_for_timeout(150)
+            self.assertEqual(page.locator("[data-proofread-new-part]").count(), 2)
+            self.assertEqual(page.locator("[data-proofread-new-part]").last.locator("textarea").input_value(), "第三段")
+            page.locator("[data-fulltext-apply]").click()
+            page.wait_for_timeout(150)
+            self.assertEqual(page.locator("[data-proofread-new-part]").count(), 2)
+            page.locator("[data-fulltext-toggle]").click()
+            page.locator("[data-part-editor-toggle]").click()
+            page.locator("[data-add-part-after='0']").click()
+            page.locator("[data-proofread-part-group='0'] [data-part-insert-after] [data-proofread-new-part]").last.locator("textarea").fill("中间段")
+            page.locator("[data-fulltext-toggle]").click()
+            self.assertIn("中间段", page.locator("[data-fulltext-input]").input_value())
+            page.locator("[data-fulltext-input]").fill("临时修改未应用")
+            page.locator("[data-fulltext-toggle]").click()
+            page.locator("[data-fulltext-toggle]").click()
+            self.assertEqual(page.locator("[data-fulltext-input]").input_value(), "临时修改未应用")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_result_path_clicks_sync_filters_and_url(self):
+        context, page, errors = self.open_page()
+        try:
+            page.locator(".result-item [data-source]").click()
+            self.assertIn("source=%E6%B5%8B%E8%AF%95%E5%88%8A%E7%89%A9", page.url)
+            page.locator(".result-item [data-author]").click()
+            self.assertIn("author=%E4%BD%9C%E8%80%85%E7%94%B2", page.url)
+            page.locator(".result-item [data-tag]").click()
+            self.assertIn("tag=%E6%A0%87%E7%AD%BE%E7%94%B2", page.url)
+            page.locator("#tag-filter [data-tag='标签甲'] .checkbox-count").wait_for(state="visible")
+            self.assertEqual(page.locator("#tag-filter [data-tag='标签甲'] .checkbox-count").text_content(), "1")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_mobile_sidebar_date_and_pagination_controls(self):
+        context, page, errors = self.open_page({"width": 390, "height": 844})
+        try:
+            self.assertTrue(page.locator("body").evaluate("node => node.classList.contains('mobile')"))
+            if page.locator("#left-sidebar").evaluate("node => node.classList.contains('open')"):
+                page.locator("#left-toggle").click()
+            page.locator("#left-toggle").click()
+            self.assertTrue(page.locator("#left-sidebar").evaluate("node => node.classList.contains('open')"))
+            page.locator("#date-from-year").fill("1966")
+            page.locator("#date-from-year").press("Enter")
+            page.locator("#date-from-month").select_option("5")
+            page.locator("#date-from-day").select_option("16")
+            self.assertIn("date_from=19660516", page.url)
+            page.locator("#date-clear").click()
+            self.assertNotIn("date_from=", page.url)
+            if page.locator("#left-sidebar").evaluate("node => node.classList.contains('open')"):
+                page.locator("#left-toggle").click()
+            page.locator("[data-date-term-label='1966/5/16']").click()
+            term = page.locator("[data-date-term-index='0']")
+            self.assertEqual(term.locator("[data-date-term-field='year']").input_value(), "1966")
+            self.assertEqual(term.locator("[data-date-term-field='month']").input_value(), "5")
+            self.assertEqual(term.locator("[data-date-term-field='day']").input_value(), "16")
+            self.assertIn("date_term=year%3A1966-month%3A5-day%3A16", page.url)
+            page.locator("#mobile-toggle-btn").click()
+            self.assertFalse(page.locator("body").evaluate("node => node.classList.contains('mobile')"))
+            page.keyboard.press("/")
+            self.assertTrue(page.locator("#search-input").evaluate("node => document.activeElement === node"))
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_year_picker_lists_and_selects_every_available_year(self):
+        context, page, errors = self.open_page()
+        try:
+            page.evaluate("STATE.facets.years = [...Array.from({ length: 140 }, (_, index) => ({ value: 1880 + index })), { value: '66' }, { value: '未知' }, { value: '12345' }]")
+            page.locator("#date-from-year").click()
+            options = page.locator("#year-picker .year-option")
+            self.assertEqual(options.count(), 140)
+            self.assertEqual(page.locator("#year-picker [data-year-value='66']").count(), 0)
+            self.assertEqual(page.locator("#year-picker [data-year-value='12345']").count(), 0)
+            page.locator("#year-picker").evaluate("node => { node.scrollTop = node.scrollHeight; }")
+            options.last.click()
+            self.assertEqual(page.locator("#date-from-year").input_value(), "2019")
+            page.evaluate("STATE.facets.years = []")
+            page.locator("#date-to-year").click()
+            fallback_options = page.locator("#year-picker .year-option")
+            self.assertEqual(fallback_options.count(), 183)
+            self.assertEqual(fallback_options.first.get_attribute("data-year-value"), "1843")
+            self.assertEqual(fallback_options.last.get_attribute("data-year-value"), "2025")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+
+    def test_proofread_submit_requires_confirm_and_posts_payload(self):
+        context, page, errors = self.open_page()
+        try:
+            submitted = []
+
+            def route_proofread(route, request):
+                if request.method == "POST":
+                    submitted.append(request.post_data_json)
+                route.fulfill(status=202, content_type="application/json", body=json.dumps({"ok": True, "status": "accepted", "tasks": 1, "auto_merge": True}))
+
+            page.route("**/api/proofread", route_proofread)
+            page.locator("[data-preview]").click()
+            page.locator("[data-compare-select]").select_option("__proofread__")
+            page.locator("[data-proofread-form]").wait_for(state="visible")
+            page.locator("[data-proofread-part-input]").fill("这是手机正文（已校订）")
+            page.locator('button[type="submit"]').click()
+            confirm = page.locator("[data-proofread-confirm]")
+            confirm.wait_for(state="visible")
+            self.assertIn("段落 1", confirm.text_content())
+            self.assertIn("diff-del", confirm.inner_html())
+            page.locator("[data-cancel-proofread]").first.click()
+            confirm.wait_for(state="hidden")
+            self.assertEqual(submitted, [])
+            page.locator('button[type="submit"]').click()
+            page.locator("[data-confirm-proofread]").click()
+            page.wait_for_function("document.querySelector('[data-proofread-confirm]') === null")
+            self.assertEqual(len(submitted), 1)
+            body = submitted[0]
+            self.assertEqual(body["doc_id"], "doc-1")
+            self.assertIn("0", body["patch"]["parts"])
+            self.assertIn("diff", body["patch"]["parts"]["0"])
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+    def test_fulltext_split_preserves_following_part_indices(self):
+        parts = [
+            {"type": "paragraph", "text": "第一段完整内容"},
+            {"type": "paragraph", "text": "第二段保持不变"},
+            {"type": "paragraph", "text": "第三段保持不变"},
+        ]
+        context, page, errors = self.open_page(preview_parts=parts)
+        try:
+            page.locator("[data-preview]").click()
+            page.locator("[data-compare-select]").select_option("__proofread__")
+            form = page.locator("[data-proofread-form]")
+            form.wait_for(state="visible")
+            form.locator("[data-fulltext-input]").fill("第一段\n完整内容\n第二段保持不变\n第三段保持不变")
+            form.locator("[data-fulltext-apply]").click()
+            payload = page.evaluate("() => proofreadPayload(STATE.proofreadItem, document.querySelector('[data-proofread-form]'))")
+            self.assertEqual(set(payload["patch"]["parts"]), {"0"})
+            change = payload["patch"]["parts"]["0"]
+            self.assertIn("diff", change)
+            self.assertEqual(change["insertAfter"], [{"text": "��整内容", "type": "paragraph"}])
+            self.assertEqual(form.locator("[data-proofread-part-input='1']").input_value(), "第二段保持不变")
+            self.assertEqual(form.locator("[data-proofread-part-input='2']").input_value(), "第三段保持不变")
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+
+    def test_proofread_review_ignores_untouched_tags_with_varying_key_order(self):
+        context, page, errors = self.open_page()
+        try:
+            submitted = []
+
+            def route_proofread(route, request):
+                if request.method == "POST":
+                    submitted.append(request.post_data_json)
+                route.fulfill(status=202, content_type="application/json", body=json.dumps({"ok": True, "status": "accepted", "tasks": 1, "auto_merge": True}))
+
+            page.route("**/api/proofread", route_proofread)
+            page.locator("[data-preview]").click()
+            page.locator("[data-compare-select]").select_option("__proofread__")
+            page.locator("[data-proofread-form]").wait_for(state="visible")
+            page.locator('button[type="submit"]').click()
+            self.assertEqual(page.locator("[data-proofread-confirm]").count(), 0)
+            self.assertEqual(page.evaluate("document.querySelector('#toast').textContent"), "没有需要提交的修改")
+            page.locator("[data-proofread-part-input]").fill("这是手机正文（已校订）")
+            page.locator('button[type="submit"]').click()
+            confirm = page.locator("[data-proofread-confirm]")
+            confirm.wait_for(state="visible")
+            self.assertNotIn("标签", confirm.text_content())
+            page.locator("[data-confirm-proofread]").click()
+            page.wait_for_function("document.querySelector('[data-proofread-confirm]') === null")
+            self.assertEqual(len(submitted), 1)
+            self.assertIsNone(submitted[0].get("metadata"))
+            self.assertIn("0", submitted[0]["patch"]["parts"])
+            self.assertEqual(errors, [])
+        finally:
+            context.close()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_frontend.py

@@ -0,0 +1,242 @@
+import unittest
+from html.parser import HTMLParser
+from pathlib import Path
+
+from app.config import APP_ROOT
+
+
+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", "form"} and values.get("id"):
+            self.ids.add(values["id"])
+
+
+class FrontendContractTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.static = Path(APP_ROOT) / "static"
+        cls.html = (cls.static / "index.html").read_text(encoding="utf-8")
+        cls.source = (cls.static / "app.js").read_text(encoding="utf-8")
+        cls.css = (cls.static / "style.css").read_text(encoding="utf-8")
+
+    def test_every_static_control_is_cached_and_bound(self):
+        parser = InteractiveIdParser()
+        parser.feed(self.html)
+        expected = {
+            "search-form", "search-input", "left-toggle", "mobile-toggle-btn", "theme-btn",
+            "parse-btn",
+            "sidebar-expand", "exact-toggle", "preview-highlight-toggle", "fulltext-toggle",
+            "page-size", "sort-filter", "source-search", "author-search", "tag-search",
+            "archive-filter", "type-filter", "date-from-year", "date-from-month",
+            "date-from-day", "date-to-year", "date-to-month", "date-to-day", "date-clear",
+            "date-term-add", "clear-filters", "empty-random-btn", "random-book-btn",
+            "prev-page", "next-page", "page-input",
+        }
+        self.assertTrue(expected.issubset(parser.ids), expected - parser.ids)
+        for control_id in expected - {"search-form"}:
+            self.assertIn(f'$("#{control_id}")', self.source, control_id)
+        self.assertIn("DOM.searchForm.addEventListener", self.source)
+
+    def test_parse_queue_editor_uses_structured_same_origin_contracts(self):
+        for contract in (
+            'apiWithTimeout(`/api/parse/queue?page=${STATE.parsePage}&page_size=${STATE.parsePageSize}`)',
+            'apiWithTimeout(`/api/parse/${encodeURIComponent(item.doc_id)}/ocr?page=${page}`',
+            'apiWithTimeout("/api/parse", { method: "POST"',
+            "function collectParseArticles(form)",
+            "function parseCoverageError(articles, maxPage)",
+            "function refreshParseArticleBody(row, force = false)",
+            "base_part_count: Number(row.dataset.basePartCount) || 0",
+            "data-parse-content",
+            'data-parse-page-prev',
+            'data-parse-add',
+            'data-parse-crop-toggle',
+            'data-parse-crop-scope="page"',
+            "function beginParseCropDrag(event)",
+            "content_thresholds: thresholds",
+            "article.ocr_exceptions = ocrExceptions",
+            "parseOCRText(data, parseOCRThresholds(row, start + index))",
+            "renderParseQueue({ animate: true })",
+        ):
+            self.assertIn(contract, self.source)
+        self.assertNotIn("replace_articles", self.source)
+
+    def test_search_race_timeout_cache_and_ime_guards_are_present(self):
+        for contract in (
+            "const REQUEST_TIMEOUT_MS = 12000", "const SEARCH_CACHE_LIMIT = 60",
+            "const SEARCH_CACHE_TTL = 8 * 60 * 1000", "searchRequestSeq",
+            "searchAbortController.abort()", 'addEventListener("compositionstart"',
+            'addEventListener("compositionend"', "requestSeq !== searchRequestSeq",
+            'data.index_status === "ready" && !data.indexing',
+        ):
+            self.assertIn(contract, self.source)
+
+    def test_default_screen_uses_one_generation_scoped_bootstrap(self):
+        for contract in (
+            'window.__bhaBootstrapPromise = fetch("/api/bootstrap"',
+            "function canUseInitialBootstrap()",
+            "async function loadInitialBootstrap()",
+            "earlyBootstrap ? await earlyBootstrap : await apiWithTimeout(\"/api/bootstrap\", {}, 25000)",
+            "setCachedSearch(stableStringify(searchPayload()), search)",
+            "scheduleNextSearchPagePrefetch(searchPayload())",
+            "if (!searchAbortController && !bootstrapPending) renderResults()",
+            "canUseInitialBootstrap() ? loadInitialBootstrap() : Promise.all([doSearch(), loadFacets()])",
+        ):
+            self.assertIn(contract, self.html + self.source)
+
+    def test_preview_cache_has_ttl_and_bounded_size(self):
+        for contract in (
+            "const PREVIEW_CACHE_TTL = 10 * 60 * 1000",
+            "Date.now() - entry.time > PREVIEW_CACHE_TTL",
+            "previewCache.delete(docId)",
+            "PREVIEW_CACHE_MAX_CHARS",
+        ):
+            self.assertIn(contract, self.source)
+        self.assertIn("function getCachedPreview(docId)", self.source)
+        self.assertIn("function setCachedPreview(docId, value)", self.source)
+
+    def test_visible_page_keeps_the_search_connection_warm(self):
+        for contract in (
+            "const KEEPALIVE_INTERVAL_MS = 45 * 1000",
+            'fetch("/api/ping"',
+            "if (document.hidden || !navigator.onLine || keepalivePending)",
+            'window.addEventListener("online", () => warmConnection(true))',
+            'document.addEventListener("visibilitychange"',
+            "window.setInterval(() => warmConnection(), KEEPALIVE_INTERVAL_MS)",
+        ):
+            self.assertIn(contract, self.source)
+
+    def test_dynamic_output_is_escaped_and_download_routes_are_explicit(self):
+        self.assertIn("function escapeHTML(value)", self.source)
+        self.assertIn("highlightPreviewText(item.content || \"\")", self.source)
+        self.assertIn("/api/download/txt/", self.source)
+        self.assertIn("/api/download/source-zip/", self.source)
+        self.assertIn("/api/download/source/", self.source)
+        self.assertIn("/api/preview/source/", self.source)
+        self.assertIn("encodeURIComponent(item.doc_id)", self.source)
+
+    def test_result_tags_keep_compact_metadata_text(self):
+        self.assertIn('class="result-size"', self.source)
+        self.assertRegex(self.css, r"\.result-size\s*\{[^}]*font-size:\s*11px;")
+
+    def test_proofread_delta_keeps_unicode_and_escapes_only_delimiters(self):
+        self.assertNotIn("diff_match_patch/20121119/diff_match_patch.js", self.html)
+        self.assertIn("diff_match_patch/20121119/diff_match_patch.js", self.source)
+        self.assertIn("sha512-5YZxUisfaneUbwv58nPp10qwt6DefHuJ", self.source)
+        self.assertIn("function loadDiffMatchPatch()", self.source)
+        self.assertIn("loadDiffMatchPatch();", self.source)
+        self.assertIn("differ.diff_main(original, edited, true)", self.source)
+        self.assertIn('inserted.replace(/%/g, "%25").replace(/\\t/g, "%09")', self.source)
+        self.assertNotIn('encodeURI(inserted)', self.source)
+        self.assertIn('if (cursor !== source.length) throw new Error("delta length mismatch")', self.source)
+
+    def test_preview_filters_dates_pagination_and_mobile_have_handlers(self):
+        for contract in (
+            'DOM.results.addEventListener("click"', 'DOM.previewPanel.addEventListener("click"',
+            'window.addEventListener("popstate"', "toggleResultFilter", "toggleResultDateTerm",
+            "refreshSelectedFacetItem", "commitResultPage", "commitFilterPage", "validateDateRange", "localStorage.setItem(\"mobileMode\"",
+            'showToast("随机文章加载失败")',
+        ):
+            self.assertIn(contract, self.source)
+
+    def test_result_and_preview_motion_is_bounded_and_reduced_motion_safe(self):
+        for contract in (
+            'window.matchMedia("(prefers-reduced-motion: reduce)")',
+            "renderResults({ animate: true })",
+            "children).slice(0, 15)",
+            "let animateNextPreview = false",
+            "if (animateNextPreview) animatePreviewPanel()",
+            "function stopPreviewAnimation()",
+            "function openProofread(item, focusPart = null, restoring = false) {\n  if (!item) return;\n  stopPreviewAnimation();",
+        ):
+            self.assertIn(contract, self.source)
+        for contract in (
+            ".result-item.result-enter",
+            "animation: result-enter 320ms",
+            ".preview-panel.preview-enter",
+            "animation: preview-enter 360ms",
+        ):
+            self.assertIn(contract, self.css)
+
+    def test_year_picker_does_not_truncate_available_years(self):
+        self.assertIn('const isFourDigitYear = (value) => /^\\d{4}$/.test(String(value))', self.source)
+        self.assertIn("Array.from({ length: 183 }, (_, index) => String(1843 + index))", self.source)
+        self.assertIn("const years = yearItems().filter", self.source)
+        self.assertNotIn(".filter((year) => !keyword || String(year).includes(keyword)).slice", self.source)
+        self.assertIn("const openAbove = spaceBelow", self.source)
+        self.assertIn('DOM.yearPicker.style.bottom = openAbove ?', self.source)
+
+    def test_proofreading_uses_compare_menu_selection_and_source_proxy(self):
+        for contract in (
+            "对比原文件并校对", 'value="__proofread__"', "data-proofread-select",
+            'addEventListener("mouseup"', "/api/download/source/", "/api/preview/source/", "inline=true",
+            'apiWithTimeout("/api/proofread"', "data-meta-title", "data-list=",
+        ):
+            self.assertIn(contract, self.source)
+
+    def test_proofreading_persists_state_and_supports_structural_editing(self):
+        for contract in ("sessionStorage", "STATE.compare", "STATE.proofread", "STATE.proofreadItem", "STATE.proofreadPage", "data-add-part-before", "data-add-part-after", "data-delete-part", "data-fulltext-input", "flushProofreadDraft", "setTimeout(flushProofreadDraft, 400)", 'addEventListener("pagehide"', "校订内容已过期，请重新打开校对页"):
+            self.assertIn(contract, self.source)
+        self.assertIn('data-fulltext-toggle>收起全文编辑</button>', self.source)
+        self.assertIn('<div data-fulltext-box><textarea data-fulltext-input>', self.source)
+        self.assertNotIn('<div data-fulltext-box hidden>', self.source)
+
+    def test_proofreading_shows_change_preview_before_submitting(self):
+        for contract in (
+            "校订提交预览", "data-confirm-proofread", "data-cancel-proofread",
+            "确认提交", "返回继续编辑", "function proofreadReviewHTML",
+            "function applyTextDelta", "function postProofread",
+            "元数据对照", "proofread-metadata-table", "原元数据", "修改后元数据",
+            "function metadataItemText", "function metadataCellHTML",
+        ):
+            self.assertIn(contract, self.source)
+        self.assertIn("function matchingLineAnchors(current, desired)", self.source)
+        self.assertIn("const anchors = [...matchingLineAnchors(current, lines)", self.source)
+        self.assertIn('apiWithTimeout("/api/proofread"', self.source)
+        self.assertNotIn("JSON.stringify(oldValues[key])", self.source)
+
+    def test_proofreading_mobile_places_fulltext_editor_at_top(self):
+        for contract in (
+            "data-fulltext-section", "function relocateFulltextEditor",
+            "STATE.isMobile ? fulltextSection :", "STATE.isMobile ? partToggle :",
+            "relocateFulltextEditor();",
+        ):
+            self.assertIn(contract, self.source)
+
+    def test_proofreading_image_fallback_and_compact_body_editor(self):
+        for contract in (
+            "data-proofread-source-image", "data-image-zoom", "loading=\"eager\"", "fetchpriority=\"high\"", "data-proofread-back", "data-preview-mobile", "图片无法在线显示",
+            "没有原文件", "仍可编辑正文并提交校对", "data-part-editor-toggle", "收起段落编辑",
+            "在上新建段落", "在下新建段落", "删除当前段落", "proofread-structure-closed",
+            "proofread-description-heading", "proofread-grid-no-source", '"校对"',
+            "isPDFSource", "pageImageViewerHTML", "initial_page", "initial_page_number", "page_numbers", "data-page-image-viewer", "data-page-count", "source-page", "data-page-image-prev", "data-page-image-next", "此原文件暂不支持在线预览", "proofread-document-viewer",
+            "loadPDFJS", "data-pdf-canvas", "proofread-pdf-stage is-loading", "is-loading", "is-error", "pdf.worker.min.mjs", "getCachedPDFDocument", "PDF_DOCUMENT_CACHE_LIMIT = 8", "createPDFRangeTransport", "readPDFRange", "failurePromise", "destroyPDFCacheEntry", "PDFDataRangeTransport", "Range: \"bytes=0-524287\"", "requestDataRange(begin, end)", "disableAutoFetch", "disableStream: true", "disableRange: false", "rangeChunkSize: 512 * 1024", "RenderingCancelledException", "ResizeObserver", "data-image-error", "data-pdf-download-link", "decoding=\"async\"", "PDF 无法在线预览",
+        ):
+            self.assertIn(contract, self.source)
+
+    def test_preview_open_limits_text_selection_to_the_preview_panel(self):
+        self.assertIn("body.preview-open {\n  user-select: none;", self.css)
+        self.assertIn("-webkit-user-select: none;", self.css)
+        self.assertIn("body.preview-open #preview-panel {\n  user-select: text;", self.css)
+        self.assertIn("body.preview-open #preview-panel .preview-header {\n  user-select: none;", self.css)
+
+    def test_pdfjs_is_pinned_and_preconnected(self):
+        self.assertIn('cdnjs.cloudflare.com/ajax/libs/pdf.js/4.10.38/pdf.min.mjs', self.source)
+        self.assertIn('cdnjs.cloudflare.com/ajax/libs/pdf.js/4.10.38/pdf.worker.min.mjs', self.source)
+        self.assertIn('rel="preconnect" href="https://cdnjs.cloudflare.com"', self.html)
+        self.assertIn('rel="preconnect" href="https://huggingface.co"', self.html)
+        self.assertIn("fetchInitialPDFRange", self.source)
+        self.assertIn("Promise.all([pdfjsLoad, initialLoad])", self.source)
+        self.assertIn('navigator.serviceWorker.register("/static/sw.js"', self.source)
+        service_worker = (self.static / "sw.js").read_text(encoding="utf-8")
+        self.assertIn('bha-page-webp-v1.0.1', service_worker)
+        self.assertIn('"/api/preview/source-page/"', service_worker)
+        self.assertIn("MAX_ENTRIES = 50", service_worker)
+
+
+if __name__ == "__main__":
+    unittest.main()