Files
paper-doc/backend/scripts/smoke_papers.py
T
govin 76708ce767 backend: print the 参考文献 list as a bibliography, one entry per work
The list was printing each citation's quote under a `引用 #53` tag: no authors,
no year, no pages, no DOI — the quoted passage where the entry should be — and
it numbered *citations*, so a paper with 86 citations to 65 works listed 21 of
them two or three times under different numbers. The same article was `[5]` in
one paragraph and `[17]` in another.

Two rules were wrong, so two are stated here:

**A work is numbered where the reader first meets it.** A citation is a place
in the text; an entry is a work. `citations` still has one row per place, and
each row now carries the number of its *work*, so the marker in the text, the
tooltip on it and the entry in the list are the same number. The document grew
a `references` list — the entries, in order — and `reference_style`, which
names the style that wrote them.

**How a reference prints is a property of a style, not of a citation.** The new
`app/citation_styles` package holds one module per style; `springer.py`
implements Springer's basic style, whose shape is
`Names: Title. <where it sits> (year). <identifier>` with a branch per document
type — a journal with its volume(issue) and pages, a book with publisher and
place, a chapter inside somebody else's book, a patent with its number, a page
whose URL is its source.

Three of its rules are decisions rather than transcription, and each is
documented where it applies: up to six contributors are named and more become
three plus `et al.`; a journal prints under its 刊名缩写 when the writer stored
one, because no algorithm abbreviates an arbitrary title correctly; and a CJK
name keeps its printed form even with halves filled in, because dotting 「三」
into an initial is wrong in Chinese and insufficient in English.

Nothing is invented to fill a gap. An entry says what it knows and reports the
rest as `missing` (「缺 责任者、出版年」), and the document warns about the
incomplete ones by number: an entry that is short because fields are empty
looks like a fact about the document rather than a library that needs attention.

`document_text` had the same bug in the MCP surface and now prints the entries,
with in-text markers taken from the document's numbering rather than from each
sentence's local position — which is what made the text an agent reads disagree
with the list under it.

`scripts/check_citation_styles.py` checks the formatter with no server and no
database: one reference of every type, and the exact entry the style calls for.
2026-09-22 21:50:27 +08:00

442 lines
18 KiB
Python

"""End-to-end smoke test for the paper feature, against a running API.
Run it while the backend is up::
.venv/bin/python scripts/smoke_papers.py
It walks the whole writing loop — create a paper on a template, verify the
empty structure, fill a paragraph with sentences and citations, read the
document back, switch the template, and check that unmatched positions survive
under an unset heading — then deletes everything it created. Exits non-zero on
the first failed expectation, so it is usable as a gate.
"""
from __future__ import annotations
import json
import sys
import urllib.error
import urllib.parse
import urllib.request
from typing import Any
BASE = "http://127.0.0.1:8000/api"
_checks = 0
def call(method: str, path: str, body: Any = None, expect: int = 200) -> Any:
"""Perform one API call and assert its status code.
The path is quoted so a Chinese search keyword travels as UTF-8 percent
escapes instead of blowing up the ASCII request line.
"""
data = json.dumps(body).encode() if body is not None else None
url = BASE + urllib.parse.quote(path, safe="/?&=%")
request = urllib.request.Request(
url,
data=data,
method=method,
headers={"Content-Type": "application/json"},
)
try:
with urllib.request.urlopen(request, timeout=20) as response:
status = response.status
payload = response.read().decode()
except urllib.error.HTTPError as error:
status = error.code
payload = error.read().decode()
if status != expect:
raise AssertionError(f"{method} {path} -> {status}, expected {expect}: {payload}")
return json.loads(payload) if payload else None
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 main() -> int:
created_papers: list[int] = []
created_references: list[int] = []
try:
# The database may already hold real papers, so "nothing of ours is
# left" is measured against a baseline rather than against zero.
baseline = call("GET", "/papers")["total"]
print(f"0. baseline: {baseline} paper(s) already in the database")
print("1. pick two templates with different paragraph positions")
templates = call("GET", "/templates?page_size=50")["items"]
check("templates exist", len(templates) >= 2, f"got {len(templates)}")
wide = max(templates, key=lambda item: item["placement_count"])
narrow = min(templates, key=lambda item: item["placement_count"])
wide_full = call("GET", f"/templates/{wide['id']}")
narrow_full = call("GET", f"/templates/{narrow['id']}")
print(f" wide={wide['name']} ({wide['placement_count']}), narrow={narrow['name']}")
print("2. create a paper")
paper = call(
"POST",
"/papers",
{
"title": "冒烟测试论文",
"template_id": wide["id"],
"author": "测试作者",
"status": "writing",
"keywords": "关键词A,关键词B;关键词A",
"target_journal": "测试期刊",
},
expect=201,
)
created_papers.append(paper["id"])
check("keywords normalised", paper["keywords"] == "关键词A, 关键词B", paper["keywords"])
check(
"paragraph denominator counts the template",
paper["template_paragraph_count"]
== len({p["sort"] for p in wide_full["placements"]}),
str(paper["template_paragraph_count"]),
)
check("no sentences yet", paper["sentence_count"] == 0)
print("3. the empty paper already has its structure")
document = call("GET", f"/papers/{paper['id']}/document")
check(
"every template position is a paragraph",
len(document["paragraphs"]) == len({p["sort"] for p in wide_full["placements"]}),
str(len(document["paragraphs"])),
)
check("all paragraphs empty", all(not p["sentences"] for p in document["paragraphs"]))
check("all paragraphs matched", all(p["matched"] for p in document["paragraphs"]))
check("no citations", document["citations"] == [])
first_sort = document["paragraphs"][0]["paper_template_filed_sort"]
print("4. write a paragraph: two sentences, citations on both")
# A citation names real literature now, so the library needs an entry
# first — and a citation with no id at all stays legal.
reference = call(
"POST",
"/references",
{
"type": "journal-article",
"title": "用于验证引用链路的文献",
"container_title": "测试期刊",
"publication_year": 2024,
"authors": [{"name": "测试作者"}],
},
expect=201,
)
created_references.append(reference["id"])
document = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{first_sort}",
{
"sentences": [
{
"content": " 第一句话,用于验证空白折叠。 ",
"citations": [
{"reference_id": reference["id"], "quote": "被引用的第一段内容"}
],
},
{
"content": "第二句话。",
"citations": [
{"reference_id": reference["id"], "quote": "引文甲"},
{"quote": "只有引用内容、暂时没有引用 id"},
],
},
]
},
)
paragraph = document["paragraphs"][0]
check("two sentences", len(paragraph["sentences"]) == 2, str(len(paragraph["sentences"])))
check("content trimmed", paragraph["sentences"][0]["content"] == "第一句话,用于验证空白折叠。")
check(
"sorts numbered from 1",
[s["sort"] for s in paragraph["sentences"]] == [1, 2],
str([s["sort"] for s in paragraph["sentences"]]),
)
check("citations numbered", [c["sort"] for c in paragraph["sentences"][1]["citations"]] == [1, 2])
check("three citations in the paper", len(document["citations"]) == 3)
check(
"a citation carries the number of its work, not of itself",
[c["index"] for c in document["citations"]] == [1, 1, 2],
str([c["index"] for c in document["citations"]]),
)
print("5. the 参考文献 list: one entry per work, in Springer's basic style")
check(
"two works — the article cited twice, and the unlinked quote",
len(document["references"]) == 2,
str(len(document["references"])),
)
first, second = document["references"]
check("both places that cite the article share its entry", len(first["citations"]) == 2)
check(
"the entry is a bibliography line, not the quote",
first["text"]
== "测试作者: 用于验证引用链路的文献. 测试期刊 (2024)",
first["text"],
)
check(
"what a complete entry still lacks is named",
first["missing"] == ["卷期页码"],
str(first["missing"]),
)
check("the unlinked quote is its own entry", second["reference_id"] is None)
check("and prints no fabricated entry", second["text"] == "", second["text"])
check("the style is reported", document["reference_style"] == "springer", document["reference_style"])
check("sentence template stamped", paragraph["sentences"][0]["template_id"] == wide["id"])
print("6. explicit sorts decide the order, not the order they were sent")
second_sort = document["paragraphs"][1]["paper_template_filed_sort"]
reordered = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{
"sentences": [
{"sort": 20, "content": "排序在后的句子。"},
{"sort": 10, "content": "排序在前的句子。"},
]
},
)
second = next(
p
for p in reordered["paragraphs"]
if p["paper_template_filed_sort"] == second_sort
)
check(
"ascending sort wins over arrival order",
[s["content"] for s in second["sentences"]]
== ["排序在前的句子。", "排序在后的句子。"],
str([s["content"] for s in second["sentences"]]),
)
check("explicit sorts are stored as sent", [s["sort"] for s in second["sentences"]] == [10, 20])
# Clear it again so the counts asserted below stay meaningful.
call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{"sentences": []},
)
print("7. the seam between sentences depends on the language")
# Chinese needs nothing after 。; English needs a space, or two
# sentences print as `First.Second.`
mixed = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{
"sentences": [
{"content": "第一句。"},
{"content": "第二句。"},
{"content": "This is English."},
{"content": "So is this."},
]
},
)
paragraph_mixed = next(
p
for p in mixed["paragraphs"]
if p["paper_template_filed_sort"] == second_sort
)
separators = [s["separator_before"] for s in paragraph_mixed["sentences"]]
check("no space between Chinese sentences", separators[:2] == ["", ""], str(separators))
check("a space before an English sentence", separators[2] == " ", str(separators))
check("a space between English sentences", separators[3] == " ", str(separators))
assembled = "".join(
s["separator_before"] + s["content"] for s in paragraph_mixed["sentences"]
)
check(
"the assembled paragraph reads correctly",
assembled == "第一句。第二句。 This is English. So is this.",
assembled,
)
check(
"the separator is not part of the stored text",
all(
not s["content"].startswith(" ") and not s["content"].endswith(" ")
for s in paragraph_mixed["sentences"]
),
)
# Clear it again so the counts asserted below stay meaningful.
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
print("8. reject a citation with no quote")
bad = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{first_sort}",
{
"sentences": [
{
"content": "x",
"citations": [
{"reference_id": reference["id"], "quote": " "}
],
}
]
},
expect=422,
)
check("citation without content refused", "detail" in bad)
print("9. a sentence with no paragraph in the template survives a switch")
# A position neither template defines, so the check means the same
# thing before and after the switch below.
orphan_sort = (
max(
p["sort"]
for p in wide_full["placements"] + narrow_full["placements"]
)
+ 5
)
call(
"POST",
f"/papers/{paper['id']}/sentences",
{"paper_template_filed_sort": orphan_sort, "content": "新模板里没有这个位置的句子。"},
expect=201,
)
document = call("GET", f"/papers/{paper['id']}/document")
check(
"orphan position is rendered",
any(
p["paper_template_filed_sort"] == orphan_sort and not p["matched"]
for p in document["paragraphs"]
),
)
check("orphan heading has no name", next(
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort
)["name"] is None)
print("10. switch the template")
switched = call("PATCH", f"/papers/{paper['id']}", {"template_id": narrow["id"]})
check("template changed", switched["template_id"] == narrow["id"])
document = call("GET", f"/papers/{paper['id']}/document")
matched = [p for p in document["paragraphs"] if p["matched"]]
unmatched = [p for p in document["paragraphs"] if not p["matched"]]
check(
"structure follows the new template",
len(matched) == len({p["sort"] for p in narrow_full["placements"]}),
str(len(matched)),
)
check("unmatched positions kept", len(unmatched) >= 1, str(len(unmatched)))
check(
"all sentences still present",
sum(len(p["sentences"]) for p in document["paragraphs"]) == 3,
)
check(
"positions ascend",
[p["paper_template_filed_sort"] for p in document["paragraphs"]]
== sorted(p["paper_template_filed_sort"] for p in document["paragraphs"]),
)
check(
"sentences re-stamped with the new template",
all(
s["template_id"] == narrow["id"]
for p in document["paragraphs"]
for s in p["sentences"]
),
)
print("11. move one paragraph onto another position")
document = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{orphan_sort}",
{"sentences": [{"content": "搬到别处的一句。"}], "target_sort": first_sort},
)
target = next(
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == first_sort
)
check("moved sentence appended after the existing ones", len(target["sentences"]) == 3)
check(
"source position gone",
all(p["paper_template_filed_sort"] != orphan_sort for p in document["paragraphs"]),
)
print("12. paper list reports progress")
listing = call("GET", f"/papers?keyword=冒烟&status=writing")
check("found by keyword and status", listing["total"] == 1, str(listing["total"]))
row = listing["items"][0]
check("paragraph count", row["paragraph_count"] == 1, str(row["paragraph_count"]))
check("sentence count", row["sentence_count"] == 3, str(row["sentence_count"]))
print("13. a template in use cannot be deleted")
conflict = call("DELETE", f"/templates/{narrow['id']}", expect=409)
check("template delete refused", "正被论文使用" in conflict["detail"], conflict["detail"])
print("14. single sentence edit and delete")
sentence_id = target["sentences"][0]["id"]
updated = call(
"PATCH",
f"/papers/{paper['id']}/sentences/{sentence_id}",
{"content": "改写后的一句话。", "sort": 5},
)
check("sentence updated", updated["content"] == "改写后的一句话。")
check("sentence sort updated", updated["sort"] == 5)
call("DELETE", f"/papers/{paper['id']}/sentences/{sentence_id}", expect=204)
document = call("GET", f"/papers/{paper['id']}/document")
check(
"sentence deleted",
sum(len(p["sentences"]) for p in document["paragraphs"]) == 2,
)
print("15. a paper with no template still works")
bare = call(
"POST",
"/papers",
{"title": "冒烟测试-无模板论文", "template_id": None, "status": "draft"},
expect=201,
)
created_papers.append(bare["id"])
empty_doc = call("GET", f"/papers/{bare['id']}/document")
check("no template means no structure", empty_doc["paragraphs"] == [])
call(
"POST",
f"/papers/{bare['id']}/sentences",
{"paper_template_filed_sort": 1, "content": "没有模板时写下的第一句。"},
expect=201,
)
bare_doc = call("GET", f"/papers/{bare['id']}/document")
check("content creates its own paragraph", len(bare_doc["paragraphs"]) == 1)
check("that paragraph has no heading", bare_doc["paragraphs"][0]["matched"] is False)
check("and the reader is warned", len(bare_doc["warnings"]) >= 1)
call("DELETE", f"/papers/{bare['id']}", expect=204)
created_papers.remove(bare["id"])
print("16. delete the paper")
call("DELETE", f"/papers/{paper['id']}", expect=204)
created_papers.clear()
for reference_id in created_references:
call("DELETE", f"/references/{reference_id}", expect=204)
created_references.clear()
check(
"gone from the list",
call("GET", "/papers")["total"] == baseline,
f"expected {baseline} paper(s) to remain",
)
print(f"\nall {_checks} checks passed")
return 0
finally:
# Never leave test rows behind, even on a failed expectation.
for reference_id in created_references:
try:
call("DELETE", f"/references/{reference_id}", expect=204)
except Exception as error: # noqa: BLE001 - cleanup must not mask the failure
print(f"cleanup of reference {reference_id} failed: {error}", file=sys.stderr)
for paper_id in created_papers:
try:
call("DELETE", f"/papers/{paper_id}", expect=204)
print(f"cleaned up paper {paper_id}")
except Exception as error: # noqa: BLE001 - cleanup must not mask the failure
print(f"cleanup of paper {paper_id} failed: {error}", file=sys.stderr)
if __name__ == "__main__":
sys.exit(main())