Files
paper-doc/backend/scripts/smoke_references.py
T
govin 6020310b3f backend: tag the literature, in a table of its own
A tag is the writer's filing of a row — 「综述」, 「必读」 — and it is a
different fact from `reference.keywords`, which are the 关键词 printed on
the article. A tag never prints, one document carries several, and the same
label is on many documents, so it gets two tables rather than a column:

  reference_tag       name (unique), colour, note
  reference_tag_link  reference_id + tag_id — the pair is the primary key

The link is a bare link, which is why it is `_link` and not `_placement`:
there is no `sort` to own, so the pair *is* the row and the same label
cannot be applied twice.

A tag is made first and applied second: `tag_ids`, never tag names, so a
typo cannot invent a label — an unknown id is a 400 naming it, and nothing
is written. Deleting a tag is deliberately *not* guarded the way deleting a
cited reference is: both foreign keys cascade, so the labels go and the
literature stays.

`GET /references?tag=1&tag=2` narrows rather than widens — the rows carrying
both labels — because that is what a second filter reads as.

The smoke test now walks the whole flow in the order the feature intends:
labels first, then tagged references, then a rename that follows every row.
2026-09-22 17:55:15 +08:00

405 lines
17 KiB
Python

"""End-to-end check of the reference library, against a running API.
Run it while the backend is up::
.venv/bin/python scripts/smoke_references.py
It walks the whole loop the library exists for — make the labels, add
literature and tag it, find it again by author, by type and by tag, link a
sentence to it, look the citation up from the reference side, be refused when
deleting something in use, then clean up — and exits non-zero on the first
failed expectation. Everything it creates is deleted, including the throwaway
paper it cites from.
The order of the first two steps is the point of the tag library rather than an
accident of the script: **tags are made first and applied second**. A reference
is created *with* tag ids, never with tag names, so a typo cannot invent a label
— which is what step 4 checks.
"""
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."""
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_references: list[int] = []
created_papers: list[int] = []
created_tags: list[int] = []
try:
print("1. the labels come first: create two tags")
survey = call(
"POST",
"/reference-tags",
{"name": " 综述 ", "color": "rgb(64, 158, 255)", "note": "综述性文献"},
expect=201,
)
created_tags.append(survey["id"])
check("a name is trimmed to one spelling", survey["name"] == "综述", survey["name"])
check(
"a colour is canonicalised",
survey["color"] == "#409EFF",
survey["color"],
)
check("nothing carries it yet", survey["reference_count"] == 0)
must_read = call(
"POST",
"/reference-tags",
{"name": "必读", "color": "#f56c6c"},
expect=201,
)
created_tags.append(must_read["id"])
check("the second tag is stored", must_read["name"] == "必读")
print("2. a tag name is unique, and only a real colour is accepted")
duplicate = call(
"POST", "/reference-tags", {"name": "综述"}, expect=409
)
check("the refusal names the label", "综述" in duplicate["detail"], duplicate["detail"])
call("POST", "/reference-tags", {"name": "怪颜色", "color": "blue"}, expect=422)
call("POST", "/reference-tags", {"name": " "}, expect=422)
check("a blank name and a non-colour are refused", True)
print("3. add an article with four authors and both tags")
article = call(
"POST",
"/references",
{
"type": "journal-article",
"title": "技术惯性与冲量的耦合机制",
"subtitle": "基于科学与技术融合网络的实证分析",
"title_translated": "Coupling inertia and impulse in technology evolution",
"container_title": "Technological Forecasting and Social Change",
"container_title_short": "Technol. Forecast. Soc. Change",
"volume": "198",
"issue": "3",
"pages": "122-141",
"publication_year": 2024,
"publication_month": 5,
"doi": "https://doi.org/10.1016/j.techfore.2024.123456",
"language": "zh",
"keywords": "技术演化, 惯性, 冲量",
"tag_ids": [survey["id"], must_read["id"]],
"authors": [
{"name": "张三", "family_name": "张", "given_name": "三"},
{"name": "李四"},
{"name": "Wang Wu", "family_name": "Wang", "given_name": "Wu"},
{"name": "世界卫生组织", "role": "compiler"},
],
},
expect=201,
)
created_references.append(article["id"])
check("the DOI lost its URL prefix", article["doi"] == "10.1016/j.techfore.2024.123456", article["doi"])
check("four contributors stored", len(article["authors"]) == 4)
check(
"they keep the order they were sent in",
[a["name"] for a in article["authors"]] == ["张三", "李四", "Wang Wu", "世界卫生组织"],
str([a["name"] for a in article["authors"]]),
)
check(
"sort is numbered from 1",
[a["sort"] for a in article["authors"]] == [1, 2, 3, 4],
str([a["sort"] for a in article["authors"]]),
)
check("roles survive", article["authors"][3]["role"] == "compiler")
check("partial date kept as sent", article["publication_year"] == 2024 and article["publication_month"] == 5)
check("no day invented", article["publication_day"] is None)
check("not cited yet", article["citation_count"] == 0)
check(
"both tags are on the row",
sorted(tag["name"] for tag in article["tags"]) == ["必读", "综述"],
str(article["tags"]),
)
print("4. a tag that does not exist is refused by name, not invented")
missing_tag = call(
"POST",
"/references",
{"title": "引用了不存在的标签", "type": "book", "tag_ids": [999999]},
expect=400,
)
check("the refusal names the id", "999999" in missing_tag["detail"], missing_tag["detail"])
orphan = call("GET", "/references?keyword=引用了不存在的标签")
check("nothing was stored half-labelled", orphan["total"] == 0, str(orphan["total"]))
print("5. add a patent, which needs a country and a number")
patent = call(
"POST",
"/references",
{
"type": "patent",
"title": "一种基于多层聚类的人工智能技术识别方法",
"patent_country": "中国",
"patent_number": "CN114000000A",
"publication_year": 2023,
"tag_ids": [must_read["id"]],
"authors": [{"name": "张三"}],
},
expect=201,
)
created_references.append(patent["id"])
check("patent stored", patent["type"] == "patent" and patent["patent_number"] == "CN114000000A")
check(
"tagging works on create for more than one entry",
[tag["name"] for tag in patent["tags"]] == ["必读"],
str(patent["tags"]),
)
print("6. a webpage without a URL is refused")
call(
"POST",
"/references",
{"type": "web-page", "title": "某网页"},
expect=422,
)
check("web page without URL refused", True)
print("7. a bad type and a missing title are refused")
call("POST", "/references", {"type": "blog-post", "title": "x"}, expect=422)
call("POST", "/references", {"title": " "}, expect=422)
call(
"POST",
"/references",
{"title": "没有标签的书", "authors": [{"name": "甲"}], "type": "book"},
expect=201,
)
probe = call("GET", "/references?keyword=没有标签的书")
created_references.append(probe["items"][0]["id"])
check("a book needs nothing else", probe["total"] == 1)
check("and may carry no tags at all", probe["items"][0]["tags"] == [])
print("8. find it again: by author, by type, by year, by tag")
by_author = call("GET", "/references?keyword=Wang")
check("search matches an author name", by_author["total"] == 1, str(by_author["total"]))
check(
"the row prints an author line",
by_author["items"][0]["authors_line"].startswith("张三, 李四, Wang Wu"),
by_author["items"][0]["authors_line"],
)
by_type = call("GET", "/references?type=patent")
check("filter by type", by_type["total"] == 1, str(by_type["total"]))
by_year = call("GET", "/references?year=2024")
check("filter by year", by_year["total"] == 1, str(by_year["total"]))
uncited = call("GET", "/references?cited=false")
check("filter by not-yet-cited", uncited["total"] == len(created_references))
by_tag = call("GET", f"/references?tag={must_read['id']}")
check("filter by tag", by_tag["total"] == 2, str(by_tag["total"]))
both = call(
"GET",
f"/references?tag={survey['id']}&tag={must_read['id']}",
)
check(
"two tags narrow to the rows carrying both",
both["total"] == 1 and both["items"][0]["id"] == article["id"],
str(both["total"]),
)
print("9. the tag table counts what carries each label")
tags = call("GET", "/reference-tags")
counts = {tag["name"]: tag["reference_count"] for tag in tags["items"]}
check("two labels in the library", tags["total"] == 2, str(tags["total"]))
check("the shared label counts two rows", counts["必读"] == 2, str(counts))
check("the other counts one", counts["综述"] == 1, str(counts))
found = call("GET", "/reference-tags?keyword=综述")
check("tags are searchable by name", found["total"] == 1, str(found["total"]))
print("10. renaming a label follows it everywhere it is used")
renamed = call(
"PATCH",
f"/reference-tags/{survey['id']}",
{"name": "综述文章", "note": "综述与述评"},
)
check("the label is renamed", renamed["name"] == "综述文章")
after = call("GET", f"/references/{article['id']}")
check(
"the reference prints the new name",
sorted(tag["name"] for tag in after["tags"]) == ["必读", "综述文章"],
str(after["tags"]),
)
taken = call(
"PATCH", f"/reference-tags/{survey['id']}", {"name": "必读"}, expect=409
)
check("renaming onto a taken name is refused", "必读" in taken["detail"], taken["detail"])
print("11. edit it: replace the contributor list, a field and its tags")
updated = call(
"PATCH",
f"/references/{article['id']}",
{
"pages": "122-145",
"tag_ids": [must_read["id"]],
"authors": [
{"name": "张三", "family_name": "张", "given_name": "三"},
{"name": "李四"},
],
},
)
check("pages updated", updated["pages"] == "122-145")
check("author list replaced wholesale", len(updated["authors"]) == 2)
check(
"tag list replaced wholesale too",
[tag["name"] for tag in updated["tags"]] == ["必读"],
str(updated["tags"]),
)
check("untouched fields kept", updated["container_title"] == "Technological Forecasting and Social Change")
cleared = call("PATCH", f"/references/{patent['id']}", {"tag_ids": None})
check(
"omitting tags leaves them alone",
[tag["name"] for tag in cleared["tags"]] == ["必读"],
str(cleared["tags"]),
)
print("12. cite it from a sentence")
templates = call("GET", "/templates?page_size=1")["items"]
paper = call(
"POST",
"/papers",
{"title": "参考文献冒烟测试论文", "template_id": templates[0]["id"]},
expect=201,
)
created_papers.append(paper["id"])
outline = call("GET", f"/templates/{templates[0]['id']}")
position = outline["placements"][0]["sort"]
call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{position}",
{
"sentences": [
{
"content": "技术惯性约束了同时具有高冲量的可能。",
"citations": [
{"reference_id": article["id"], "quote": "高惯性技术几乎不可能同时具有高冲量。"}
],
}
]
},
)
check("a citation to a real reference is accepted", True)
missing = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{position}",
{"sentences": [{"content": "x", "citations": [{"reference_id": 999999, "quote": "y"}]}]},
expect=400,
)
check("a citation to nothing is refused by name", "999999" in missing["detail"], missing["detail"])
print("13. the reverse lookup: which sentences use this article?")
citations = call("GET", f"/references/{article['id']}/citations")
check("one citation found", len(citations) == 1, str(len(citations)))
check("it names the sentence", "技术惯性约束" in citations[0]["sentence_content"])
check("and the paper", citations[0]["paper_id"] == paper["id"])
check("and the paragraph heading", citations[0]["paragraph_name"] is not None, str(citations[0]))
cited = call("GET", "/references?cited=true")
check("the cited filter now finds it", cited["total"] == 1, str(cited["total"]))
print("14. a cited reference cannot be deleted; an uncited one can")
conflict = call("DELETE", f"/references/{article['id']}", expect=409)
check("refusal explains itself", "正被论文引用" in conflict["detail"], conflict["detail"])
call("DELETE", f"/references/{patent['id']}", expect=204)
created_references.remove(patent["id"])
check("an uncited reference deletes cleanly", True)
print("15. deleting a tag unlabels the literature instead of deleting it")
call("DELETE", f"/reference-tags/{must_read['id']}", expect=204)
created_tags.remove(must_read["id"])
survivor = call("GET", f"/references/{article['id']}")
check("the reference is still there", survivor["title"] == article["title"])
check("and has lost that label", survivor["tags"] == [], str(survivor["tags"]))
left = call("GET", f"/references?tag={survey['id']}")
check(
"the other label no longer matches anything",
left["total"] == 0,
str(left["total"]),
)
print("16. clean up")
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()
for tag_id in created_tags:
call("DELETE", f"/reference-tags/{tag_id}", expect=204)
created_tags.clear()
remaining = call("GET", "/references")
check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"]))
check(
"and no labels either",
call("GET", "/reference-tags")["total"] == 0,
str(call("GET", "/reference-tags")["total"]),
)
print(f"\nall {_checks} checks passed")
return 0
finally:
for paper_id in created_papers:
try:
call("DELETE", f"/papers/{paper_id}", expect=204)
except Exception as error: # noqa: BLE001 - cleanup must not mask the failure
print(f"cleanup of paper {paper_id} failed: {error}", file=sys.stderr)
for reference_id in created_references:
try:
call("DELETE", f"/references/{reference_id}", expect=204)
print(f"cleaned up reference {reference_id}")
except Exception as error: # noqa: BLE001
print(f"cleanup of reference {reference_id} failed: {error}", file=sys.stderr)
for tag_id in created_tags:
try:
call("DELETE", f"/reference-tags/{tag_id}", expect=204)
print(f"cleaned up tag {tag_id}")
except Exception as error: # noqa: BLE001
print(f"cleanup of tag {tag_id} failed: {error}", file=sys.stderr)
if __name__ == "__main__":
sys.exit(main())