diff --git a/backend/app/core/storage.py b/backend/app/core/storage.py
index 676f191..58b548b 100644
--- a/backend/app/core/storage.py
+++ b/backend/app/core/storage.py
@@ -219,7 +219,16 @@ class ImageStore:
return
except ClientError as error:
code = error.response.get("Error", {}).get("Code", "")
- if code not in {"404", "NoSuchBucket", "NotFound"}:
+ if code in {"404", "NoSuchBucket", "NotFound"}:
+ pass # not there — fall through and make it
+ elif code in {"403", "AccessDenied"}:
+ # Being refused a look at the bucket is not the same as the
+ # bucket being absent. A key scoped to objects alone (PutObject /
+ # GetObject, no ListBucket) gets exactly this answer, and the
+ # upload that follows is the honest test of whether it works —
+ # so return rather than turning a working key into a 503.
+ return
+ else:
raise self._unavailable(error) from error
try:
diff --git a/backend/scripts/check_storage.py b/backend/scripts/check_storage.py
new file mode 100644
index 0000000..6ee3865
--- /dev/null
+++ b/backend/scripts/check_storage.py
@@ -0,0 +1,301 @@
+"""Check the image storage rules without a bucket.
+
+Run it with no server and no object store::
+
+ .venv/bin/python scripts/check_storage.py
+
+``smoke_images.py`` proves the endpoints work against a real MinIO; this one
+checks the rules that decide *what may be stored and served at all*, which are
+the rules that fail silently. A format sniffed from the wrong offset, a key
+pattern that lets one more shape through, a `Cache-Control` that promises
+immutability the key does not provide — none of those break the happy path a
+smoke test walks, and each of them is a way to serve something other than what
+was uploaded.
+
+boto3's client is replaced by a stub here, so nothing here needs credentials or
+network. It exits non-zero on the first failed expectation.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Running this as a plain script puts scripts/ on sys.path, not backend/, so
+# `import app` would fail. Anchor to the backend directory instead.
+BACKEND_DIR = Path(__file__).resolve().parents[1]
+if str(BACKEND_DIR) not in sys.path:
+ sys.path.insert(0, str(BACKEND_DIR))
+
+from botocore.exceptions import ClientError # noqa: E402
+
+from app.core.config import Settings # noqa: E402
+from app.core.storage import ( # noqa: E402
+ IMAGE_FORMATS,
+ ImageNotFound,
+ ImageStore,
+ StorageUnavailable,
+ UnsupportedImage,
+ content_type_for,
+ image_url,
+ is_key,
+ markdown_for,
+ sniff,
+)
+
+_checks = 0
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+ """Assert one expectation and report it."""
+ global _checks
+ _checks += 1
+ if not condition:
+ raise AssertionError(f"{label}: {detail}")
+ print(f" ok {label}")
+
+
+def equal(label: str, actual: object, expected: object) -> None:
+ """Assert one value, showing both sides when it differs."""
+ check(label, actual == expected, f"{actual!r} != {expected!r}")
+
+
+# --- stubs -------------------------------------------------------------------
+
+
+class FakeBody:
+ """A boto3 streaming body that says whether it was closed."""
+
+ def __init__(self, data: bytes) -> None:
+ self.data = data
+ self.closed = False
+
+ def iter_chunks(self, size: int):
+ for start in range(0, len(self.data), size):
+ yield self.data[start : start + size]
+
+ def close(self) -> None:
+ self.closed = True
+
+
+class FakeClient:
+ """The four calls :class:`ImageStore` makes, with the answers we choose."""
+
+ def __init__(self, *, head_error: str | None = None, get_error: str | None = None) -> None:
+ self.head_error = head_error
+ self.get_error = get_error
+ self.created: list[str] = []
+ self.puts: list[dict] = []
+ self.body = FakeBody(b"stored bytes")
+ self.heads: list[str] = []
+
+ def head_bucket(self, Bucket: str): # noqa: N803 — boto3's own keyword names
+ self.heads.append(Bucket)
+ if self.head_error:
+ raise ClientError({"Error": {"Code": self.head_error, "Message": "stub"}}, "HeadBucket")
+ return {}
+
+ def create_bucket(self, Bucket: str): # noqa: N803
+ self.created.append(Bucket)
+ return {}
+
+ def put_object(self, **kwargs):
+ self.puts.append(kwargs)
+ return {}
+
+ def get_object(self, Bucket: str, Key: str): # noqa: N803
+ if self.get_error:
+ raise ClientError({"Error": {"Code": self.get_error, "Message": "stub"}}, "GetObject")
+ return {"Body": self.body, "ContentLength": len(self.body.data)}
+
+
+def store(client: FakeClient | None = None, **overrides) -> ImageStore:
+ """A store whose boto3 client is the stub, so nothing leaves this process."""
+ settings = Settings(
+ minio_endpoint="http://minio.test:9000",
+ minio_access_key="test-key",
+ minio_secret_key="test-secret",
+ minio_bucket="paper-images",
+ **overrides,
+ )
+ instance = ImageStore(settings)
+ if client is not None:
+ instance._client = client # noqa: SLF001 — the seam this script exists to use
+ return instance
+
+
+# --- the formats -------------------------------------------------------------
+
+PNG = b"\x89PNG\r\n\x1a\n" + b"0" * 32
+JPEG = b"\xff\xd8\xff\xe0" + b"0" * 32
+GIF87 = b"GIF87a" + b"0" * 32
+GIF89 = b"GIF89a" + b"0" * 32
+WEBP = b"RIFF" + b"\x00\x00\x00\x00" + b"WEBP" + b"0" * 32
+
+
+def main() -> int:
+ print("1. the format is read from the bytes")
+ equal("a PNG is a PNG", sniff(PNG), "png")
+ equal("a JPEG is a JPEG", sniff(JPEG), "jpeg")
+ equal("GIF87a", sniff(GIF87), "gif")
+ equal("GIF89a", sniff(GIF89), "gif")
+ equal("RIFF….WEBP", sniff(WEBP), "webp")
+ equal("every accepted format has a type and an extension", len(IMAGE_FORMATS), 4)
+
+ print("2. what is refused, whatever it claims to be")
+ for label, data in [
+ ("an SVG", b''),
+ ("a PHP file renamed to .png", b""),
+ ("HTML", b""),
+ ("a PDF", b"%PDF-1.7\n"),
+ ("an empty file", b""),
+ ("four bytes that begin like a RIFF but are not WEBP", b"RIFF\x00\x00\x00\x00AVI "),
+ ]:
+ try:
+ sniff(data)
+ check(f"{label} is refused", False, "it was accepted")
+ except UnsupportedImage as error:
+ check(f"{label} is refused", "SVG" in str(error) or "格式" in str(error), str(error))
+
+ print("3. the served key space is exactly what we write")
+ ours = "2026/09/9f8c1a4b7e2d0c33.png"
+ check("our own key is servable", is_key(ours), ours)
+ equal("…and its content type comes from the extension", content_type_for(ours), "image/png")
+ equal("a .jpg key", content_type_for("2026/09/9f8c1a4b7e2d0c33.jpg"), "image/jpeg")
+
+ for label, key in [
+ ("another bucket's layout", "mattermost/20260724/teams/logo.png"),
+ ("a key with no date", "9f8c1a4b7e2d0c33.png"),
+ ("a traversal attempt", "2026/09/../../../etc/passwd"),
+ ("a nested path", "2026/09/extra/9f8c1a4b7e2d0c33.png"),
+ ("an uppercase digest", "2026/09/9F8C1A4B7E2D0C33.png"),
+ ("a digest that is too short", "2026/09/9f8c.png"),
+ ("a format we would not serve", "2026/09/9f8c1a4b7e2d0c33.svg"),
+ ("an extension we would not serve", "2026/09/9f8c1a4b7e2d0c33.bmp"),
+ ("a double extension", "2026/09/9f8c1a4b7e2d0c33.png.html"),
+ ("a month that is not a month", "2026/9/9f8c1a4b7e2d0c33.png"),
+ ]:
+ check(f"{label} is refused", not is_key(key), key)
+ equal(f"…and {label} has no content type", content_type_for(key), None)
+
+ print("4. the URL and the Markdown a sentence keeps")
+ settings = Settings(api_prefix="/api", minio_bucket="paper-images")
+ equal("the URL is the API's own path", image_url(ours, settings), f"/api/images/{ours}")
+ equal(
+ "the Markdown carries the caption",
+ markdown_for(ours, "试验装置", settings),
+ f"",
+ )
+ equal(
+ "a caption cannot close the brackets early",
+ markdown_for(ours, "a]b(c)", settings),
+ f"",
+ )
+ equal("an empty caption is allowed", markdown_for(ours, "", settings), f"")
+ equal(
+ "the prefix follows the settings",
+ image_url(ours, Settings(api_prefix="/v2")),
+ f"/v2/images/{ours}",
+ )
+
+ print("5. unconfigured storage refuses in the API's words")
+ bare = ImageStore(Settings(minio_endpoint="", minio_access_key="", minio_secret_key=""))
+ for label, call in [
+ ("save", lambda: bare.save(PNG)),
+ ("stream", lambda: bare.stream(ours)),
+ ]:
+ try:
+ call()
+ check(f"{label} without credentials is refused", False, "it went ahead")
+ except StorageUnavailable as error:
+ check(
+ f"{label} without credentials names the missing variables",
+ "MINIO_ENDPOINT" in str(error),
+ str(error),
+ )
+
+ print("6. storing asks MinIO for exactly what we intend")
+ client = FakeClient(head_error="404")
+ saved = store(client)
+ key, content_type, digest = saved.save(PNG)
+ check("the key is the digest", digest[:16] in key, key)
+ check("…with the right extension", key.endswith(".png"), key)
+ check("…and a servable shape", is_key(key), key)
+ equal("the type is the sniffed one", content_type, "image/png")
+ equal("it looked for the bucket once", len(client.heads), 1)
+ equal("and created it, because it was missing", client.created, ["paper-images"])
+ put = client.puts[0]
+ equal("the bucket", put["Bucket"], "paper-images")
+ equal("the key", put["Key"], key)
+ equal("the bytes", put["Body"], PNG)
+ equal("the content type", put["ContentType"], "image/png")
+ check(
+ "the cache promise matches the content-addressed key",
+ "immutable" in put["CacheControl"],
+ put["CacheControl"],
+ )
+
+ print("7. the same bytes are the same object")
+ again = FakeClient()
+ key_again, _, digest_again = store(again).save(PNG)
+ equal("same key", key_again, key)
+ equal("same digest", digest_again, digest)
+ other = FakeClient()
+ key_other, _, _ = store(other).save(PNG + b"x")
+ check("different bytes are a different object", key_other != key, key_other)
+
+ print("8. a key that may not look at the bucket still works")
+ # A least-privilege key (PutObject / GetObject, no ListBucket) gets a 403
+ # from HeadBucket. Treating that as "the bucket is missing" would turn a
+ # working key into a 503, so the upload has to carry on.
+ denied = FakeClient(head_error="403")
+ store(denied).save(PNG)
+ equal("it did not try to create the bucket", denied.created, [])
+ equal("but it did store the object", len(denied.puts), 1)
+
+ print("9. reading refuses first, translates second")
+ for label, key in [("a key we did not write", "mattermost/logo.png")]:
+ try:
+ store(FakeClient()).stream(key)
+ check(f"{label} is refused", False, "it was served")
+ except ImageNotFound:
+ check(f"{label} is refused before boto3 is asked", True)
+
+ try:
+ store(FakeClient(get_error="NoSuchKey")).stream(ours)
+ check("a missing object is ImageNotFound", False, "it was served")
+ except ImageNotFound:
+ check("a missing object is ImageNotFound", True)
+
+ streaming_client = FakeClient()
+ chunks, stream_type, length = store(streaming_client).stream(ours)
+ body = b"".join(chunks)
+ equal("the bytes come back", body, b"stored bytes")
+ equal("with their type", stream_type, "image/png")
+ equal("and their length", length, len(b"stored bytes"))
+ check("the connection is released", streaming_client.body.closed)
+
+ print("10. a wrong endpoint is reported, not raised as a stack trace")
+ try:
+ ImageStore(
+ Settings(
+ minio_endpoint="http://127.0.0.1:1",
+ minio_access_key="k",
+ minio_secret_key="s",
+ minio_bucket="paper-images",
+ )
+ ).save(PNG)
+ check("an unreachable endpoint is StorageUnavailable", False, "it went ahead")
+ except StorageUnavailable as error:
+ check(
+ "an unreachable endpoint is StorageUnavailable",
+ "连不上" in str(error) or "对象存储" in str(error),
+ str(error),
+ )
+
+ print(f"\nall {_checks} checks passed")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
index 3494f29..9927a79 100644
--- a/docs/OVERVIEW.md
+++ b/docs/OVERVIEW.md
@@ -878,12 +878,15 @@ paper-doc/
│ ├── scripts/smoke_images.py # end-to-end check of upload, serve and refusal
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
│ │ # (no server, no database)
+│ ├── scripts/check_storage.py # the image rules: formats, keys, refusals
+│ │ # (no server, no bucket)
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
│ ├── alembic.ini
│ ├── requirements.txt
│ └── .env.example
├── frontend/ # Vue 3 SPA
+│ ├── scripts/check-image.mjs # the browser check: does a figure draw?
│ ├── src/
│ │ ├── api/ # axios instance and endpoint modules
│ │ ├── components/ # shell, field, template, paper and reference
@@ -951,6 +954,31 @@ cd backend
alembic upgrade head
```
+**Object storage**
+
+The images a paper embeds live in MinIO, deployed in the same k3s cluster
+(namespace `minio`, manifests in `/opt/kubectl/minio/`): the S3 API on NodePort
+`30090`, the console on `30091`. From inside the cluster the Service is
+`http://minio.minio.svc.cluster.local:9000`.
+
+```bash
+# backend/.env — never committed
+MINIO_ENDPOINT=http://192.168.1.88:30090
+MINIO_ACCESS_KEY=… # a dedicated key, not the MinIO root account
+MINIO_SECRET_KEY=…
+MINIO_BUCKET=paper-images # created on the first upload if it is absent
+```
+
+The bucket stays **private**. Nothing is made public to display a figure: the
+API streams the object out of the bucket on `/api/images/{key}`, which is both
+what keeps the paper's addresses portable and what keeps the bucket from being a
+second, unauthenticated way into the deployment.
+
+A key scoped to objects alone (`PutObject` / `GetObject`, no `ListBucket`) is
+enough, and is the better choice: the upload tolerates the `403` that such a key
+gets when it checks whether the bucket exists, rather than mistaking it for a
+missing bucket.
+
**Seed data**
`scripts/seed.py` fills the title library with a standard academic outline (20
@@ -1010,6 +1038,52 @@ cd backend
.venv/bin/python scripts/smoke_papers.py
```
+**Checking images**
+
+Three scripts, because the feature has three layers that fail differently.
+`scripts/check_storage.py` needs nothing running: it replaces boto3's client
+with a stub and checks the rules that decide what may be stored and served at
+all — the format sniffed from the magic bytes (and SVG refused), the key pattern
+that the read route will serve and nothing outside it, the Markdown a caption
+may not break out of, what is asked of MinIO on a write, and that a key which is
+not allowed to *look* at the bucket still works.
+
+```bash
+cd backend
+.venv/bin/python scripts/check_storage.py # no server, no bucket
+.venv/bin/python scripts/smoke_images.py # against a running API + MinIO
+```
+
+`scripts/smoke_images.py` is the end-to-end one: it uploads each accepted
+format, fetches every one back byte for byte, checks the refusals (`415` for
+text, an SVG and a mislabelled file, `400` for an empty one, `404` for a key
+this application never wrote), proves the same bytes are stored once, and writes
+a sentence holding a figure through the paper endpoints to show the Markdown
+survives them unchanged. Nothing needs cleaning up afterwards, and that is
+itself the property under test — a key is the digest of its picture, so a second
+run stores the same objects rather than more copies of them.
+
+The third layer is the page, and it is the one neither of the other two can
+reach: bytes can be stored and returned perfectly while the `` shows
+nothing. `frontend/scripts/check-image.mjs` therefore measures what the browser
+did — that the picture decoded (`naturalWidth`), that a figure took a line of
+its own and is centred on the column, that `{width=50%}` came out at exactly
+half the column, that the 图注 prints *under* the picture, that an image inside a
+sentence stayed in that line, and that the editor's 「插入图片」 button ends with
+the picture in the paper after saving. It needs Playwright, which is not a
+dependency of the app:
+
+```bash
+cd frontend
+pnpm add -D playwright && npx playwright install chromium
+pnpm check:image
+# or point at an install that lives elsewhere
+PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs pnpm check:image
+```
+
+It creates a throwaway paper for the run and deletes it, so it can be pointed at
+a database that holds real work.
+
**Checking the MCP server**
`scripts/mcp_server.py --check` connects to the database once and prints the
diff --git a/frontend/package.json b/frontend/package.json
index 09160c2..2613993 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -8,7 +8,8 @@
"build": "run-p type-check \"build-only {@}\" --",
"preview": "vite preview",
"build-only": "vite build",
- "type-check": "vue-tsc --build"
+ "type-check": "vue-tsc --build",
+ "check:image": "node scripts/check-image.mjs"
},
"dependencies": {
"@element-plus/icons-vue": "^2.3.2",
diff --git a/frontend/scripts/check-image.mjs b/frontend/scripts/check-image.mjs
new file mode 100644
index 0000000..6222341
--- /dev/null
+++ b/frontend/scripts/check-image.mjs
@@ -0,0 +1,280 @@
+/**
+ * Does an inserted picture actually show?
+ *
+ * pnpm check:image # API on :8000 and the web app on :5173
+ * PAPER_WEB=http://… pnpm check:image
+ *
+ * This is the check `backend/scripts/smoke_images.py` cannot make. That one
+ * proves the endpoints store and return the bytes; this one proves the page
+ * *draws* them: that the `` really decoded (`naturalWidth`), that a figure
+ * took a line of its own and is centred on the column, that `{width=50%}` came
+ * out at half the column, that the 图注 is printed under the picture rather than
+ * beside it, that an image inside a sentence stayed in that line, and that the
+ * editor's 「插入图片」 button ends with the picture in the paper after saving.
+ *
+ * It creates a throwaway paper for the run and deletes it afterwards, so it can
+ * be pointed at a database that holds real work.
+ *
+ * It needs Playwright, which is deliberately not a dependency of the app:
+ *
+ * pnpm add -D playwright && npx playwright install chromium
+ *
+ * An install that lives elsewhere can be pointed at instead, which is how this
+ * was verified on the machine that runs the paper:
+ *
+ * PLAYWRIGHT_MODULE=/path/to/node_modules/playwright/index.mjs pnpm check:image
+ */
+import { deflateSync } from 'node:zlib'
+
+const WEB = process.env.PAPER_WEB ?? 'http://127.0.0.1:5173'
+const API = process.env.PAPER_API ?? 'http://127.0.0.1:8000/api'
+
+let chromium
+try {
+ ;({ chromium } = await import(process.env.PLAYWRIGHT_MODULE ?? 'playwright'))
+} catch {
+ console.error(
+ 'playwright is not installed. Either install it:\n' +
+ ' pnpm add -D playwright && npx playwright install chromium\n' +
+ 'or point at an existing install with PLAYWRIGHT_MODULE=…/playwright/index.mjs',
+ )
+ process.exit(2)
+}
+
+// --- a real PNG, built here so the script carries its own fixture ------------
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, index) => {
+ let value = index
+ for (let bit = 0; bit < 8; bit += 1) {
+ value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1
+ }
+ return value >>> 0
+})
+
+function crc32(buffer) {
+ let crc = 0xffffffff
+ for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8)
+ return (crc ^ 0xffffffff) >>> 0
+}
+
+function chunk(tag, payload) {
+ const body = Buffer.concat([Buffer.from(tag, 'ascii'), payload])
+ const length = Buffer.alloc(4)
+ length.writeUInt32BE(payload.length)
+ const crc = Buffer.alloc(4)
+ crc.writeUInt32BE(crc32(body))
+ return Buffer.concat([length, body, crc])
+}
+
+/** A gradient, so two fixtures differ and the size is honest. */
+function makePng(width = 480, height = 300) {
+ const raw = Buffer.alloc(height * (1 + width * 3))
+ let offset = 0
+ for (let y = 0; y < height; y += 1) {
+ raw[offset] = 0 // filter: none
+ offset += 1
+ for (let x = 0; x < width; x += 1) {
+ raw[offset] = Math.round((x * 255) / Math.max(width - 1, 1))
+ raw[offset + 1] = Math.round((y * 255) / Math.max(height - 1, 1))
+ raw[offset + 2] = 128
+ offset += 3
+ }
+ }
+
+ const header = Buffer.alloc(13)
+ header.writeUInt32BE(width, 0)
+ header.writeUInt32BE(height, 4)
+ header[8] = 8 // bit depth
+ header[9] = 2 // truecolour
+ return Buffer.concat([
+ Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+ chunk('IHDR', header),
+ chunk('IDAT', deflateSync(raw, { level: 9 })),
+ chunk('IEND', Buffer.alloc(0)),
+ ])
+}
+
+// --- the API, spoken with fetch ---------------------------------------------
+
+async function api(method, path, body) {
+ const response = await fetch(`${API}${path}`, {
+ method,
+ headers: { 'Content-Type': 'application/json' },
+ body: body ? JSON.stringify(body) : undefined,
+ })
+ if (!response.ok && response.status !== 204) {
+ throw new Error(`${method} ${path} -> ${response.status}: ${await response.text()}`)
+ }
+ return response.status === 204 ? null : response.json()
+}
+
+const results = []
+function check(label, ok, detail = '') {
+ results.push([label, ok])
+ console.log(`${ok ? ' ok ' : ' FAIL'}${label}${ok ? '' : ` — ${detail}`}`)
+}
+
+const png = makePng()
+const uploadResponse = await fetch(`${API}/images`, {
+ method: 'POST',
+ body: (() => {
+ const form = new FormData()
+ form.append('file', new Blob([png], { type: 'image/png' }), '试验装置.png')
+ return form
+ })(),
+})
+if (!uploadResponse.ok) {
+ throw new Error(`upload -> ${uploadResponse.status}: ${await uploadResponse.text()}`)
+}
+const image = await uploadResponse.json()
+console.log(`uploaded ${image.url} (${image.size} bytes)`)
+
+const browser = await chromium.launch()
+let paperId = null
+try {
+ const context = await browser.newContext({ viewport: { width: 1600, height: 950 } })
+ const page = await context.newPage()
+
+ const template = (await api('GET', '/templates?page_size=1')).items[0]
+ paperId = (await api('POST', '/papers', { title: '插图浏览器测试', template_id: template.id })).id
+ const outline = await api('GET', `/templates/${template.id}`)
+ const sort = outline.placements[0].sort
+
+ // One paragraph with an image inside a sentence, and one figure half the
+ // column wide. Written through the API so the *rendering* is what is checked.
+ await api('PUT', `/papers/${paperId}/paragraphs/${sort}`, {
+ sentences: [
+ { content: `试验装置如  所示,量测点布置在试件中部。` },
+ { content: `{width=50%}`, line_break_before: true },
+ ],
+ })
+
+ await page.goto(`${WEB}/papers/${paperId}`, { waitUntil: 'networkidle' })
+ await page.waitForSelector('.paragraph-body')
+ // `naturalWidth` is the proof it decoded; give the decode a moment.
+ await page.waitForTimeout(800)
+
+ const geometry = await page.evaluate(() => {
+ const body = document.querySelector('.paragraph-body')
+ const bodyBox = body.getBoundingClientRect()
+ const figure = document.querySelector('.sentence--figure')
+ const figureImage = figure.querySelector('img')
+ const figureBox = figureImage.getBoundingClientRect()
+ const caption = figure.querySelector('.figure-caption')
+ const inline = [...document.querySelectorAll('.sentence img')].find(
+ (node) => !node.closest('.sentence--figure'),
+ )
+ const inlineBox = inline.getBoundingClientRect()
+
+ return {
+ bodyWidth: Math.round(bodyBox.width),
+ bodyCenter: Math.round(bodyBox.left + bodyBox.width / 2),
+ figure: {
+ src: figureImage.getAttribute('src'),
+ natural: [figureImage.naturalWidth, figureImage.naturalHeight],
+ width: Math.round(figureBox.width),
+ center: Math.round(figureBox.left + figureBox.width / 2),
+ caption: caption.textContent.trim(),
+ gapBelowImage: Math.round(caption.getBoundingClientRect().top - figureBox.bottom),
+ siblings: figure.closest('.paragraph-line').querySelectorAll('.sentence').length,
+ },
+ inline: {
+ width: Math.round(inlineBox.width),
+ height: Math.round(inlineBox.height),
+ inFigure: Boolean(inline.closest('.sentence--figure')),
+ lineHasText: inline.closest('.paragraph-line').textContent.includes('量测点'),
+ },
+ }
+ })
+
+ const { figure, inline } = geometry
+ check('the picture decoded', figure.natural[0] === 480, JSON.stringify(figure.natural))
+ check('it is served from our own path', figure.src.startsWith('/api/images/'), figure.src)
+ check(
+ '{width=50%} is half the column',
+ Math.abs(figure.width - geometry.bodyWidth * 0.5) <= 2,
+ `${figure.width} vs ${geometry.bodyWidth * 0.5}`,
+ )
+ check(
+ 'the figure is centred on the column',
+ Math.abs(figure.center - geometry.bodyCenter) <= 2,
+ `${figure.center} vs ${geometry.bodyCenter}`,
+ )
+ check('the 图注 is the text in the brackets', figure.caption === '试验装置示意图', figure.caption)
+ check('…and it is printed under the picture', figure.gapBelowImage > 0, `${figure.gapBelowImage}`)
+ check('the figure owns its line', figure.siblings === 1, `${figure.siblings} sentences`)
+ check(
+ 'an image inside a sentence stays inline',
+ !inline.inFigure && inline.lineHasText,
+ JSON.stringify(inline),
+ )
+ check(
+ 'the inline image keeps its aspect ratio',
+ Math.abs(inline.width / inline.height - 480 / 300) < 0.02,
+ `${inline.width}x${inline.height}`,
+ )
+
+ await page.locator('.sentence--figure img').click()
+ await page.waitForTimeout(400)
+ check(
+ 'clicking opens the picture at full size',
+ await page.evaluate(() => Boolean(document.querySelector('.el-image-viewer__wrapper'))),
+ )
+ await page.keyboard.press('Escape')
+ await page.waitForTimeout(400)
+
+ // --- the editor's own 「插入图片」 -----------------------------------------
+ // Scoped to a paragraph header: 「编辑信息」 in the toolbar also contains 编辑.
+ await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
+ await page.waitForSelector('.editor .rows', { timeout: 15000 })
+ await page.locator('.editor input[type=file]').setInputFiles({
+ name: '第二张图.png',
+ mimeType: 'image/png',
+ buffer: png,
+ })
+
+ // Wait for the *new* thumbnail: the dialog already shows the two the API
+ // wrote, so waiting for any `.row-image img` would return immediately.
+ await page.waitForFunction(
+ () =>
+ [...document.querySelectorAll('.row-image figcaption')].some(
+ (node) => node.textContent.trim() === '第二张图',
+ ),
+ { timeout: 20000 },
+ )
+ check(
+ 'the editor shows the uploaded picture',
+ (await page.locator('.row-image img').count()) === 3,
+ `${await page.locator('.row-image img').count()} thumbnails`,
+ )
+ check(
+ 'the row caption comes from the filename',
+ (await page.locator('.row-image figcaption', { hasText: '第二张图' }).first().textContent()).trim() ===
+ '第二张图',
+ )
+
+ await page.getByRole('button', { name: '保存段落' }).click()
+ await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
+ await page.waitForTimeout(800)
+
+ const saved = await page.evaluate(() => {
+ const figures = [...document.querySelectorAll('.sentence--figure')]
+ return {
+ count: figures.length,
+ captions: figures.map((node) => node.querySelector('.figure-caption').textContent.trim()),
+ decoded: figures.map((node) => node.querySelector('img').naturalWidth),
+ }
+ })
+ check('the inserted figure is in the paper', saved.count === 2, JSON.stringify(saved))
+ check('and it is the one that was uploaded', saved.captions.includes('第二张图'), saved.captions.join())
+ check('both pictures decoded', saved.decoded.every((width) => width === 480), saved.decoded.join())
+} finally {
+ await browser.close()
+ if (paperId) {
+ await api('DELETE', `/papers/${paperId}`).catch((error) => console.error('cleanup:', error.message))
+ }
+}
+
+const failed = results.filter(([, ok]) => !ok)
+console.log(`\n${results.length - failed.length}/${results.length} checks passed`)
+process.exit(failed.length ? 1 : 0)