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.
This commit is contained in:
2026-09-22 17:55:15 +08:00
parent d7bb777264
commit 6020310b3f
14 changed files with 1042 additions and 29 deletions
+161 -17
View File
@@ -4,11 +4,17 @@ Run it while the backend is up::
.venv/bin/python scripts/smoke_references.py
It walks the whole loop the library exists for — add literature, find it again
by author and by type, 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.
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
@@ -60,9 +66,44 @@ def check(label: str, condition: bool, detail: str = "") -> None:
def main() -> int:
created_references: list[int] = []
created_papers: list[int] = []
created_tags: list[int] = []
try:
print("1. add an article with four authors")
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",
@@ -81,6 +122,7 @@ def main() -> int:
"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": "李四"},
@@ -107,8 +149,24 @@ def main() -> int:
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("2. add a patent, which needs a country and a number")
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",
@@ -118,14 +176,20 @@ def main() -> int:
"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("3. a webpage without a URL is refused")
print("6. a webpage without a URL is refused")
call(
"POST",
"/references",
@@ -134,20 +198,21 @@ def main() -> int:
)
check("web page without URL refused", True)
print("4. a bad type, a phantom citation target and a missing title are refused")
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"},
{"title": "没有标签的书", "authors": [{"name": "甲"}], "type": "book"},
expect=201,
)
probe = call("GET", "/references?keyword=引用了不存在")
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("5. find it again: by author, by type, by year")
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(
@@ -162,12 +227,52 @@ def main() -> int:
uncited = call("GET", "/references?cited=false")
check("filter by not-yet-cited", uncited["total"] == len(created_references))
print("6. edit it: replace the contributor list, change a field")
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": "李四"},
@@ -176,9 +281,21 @@ def main() -> int:
)
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")
print("7. cite it from a sentence")
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",
@@ -214,7 +331,7 @@ def main() -> int:
)
check("a citation to nothing is refused by name", "999999" in missing["detail"], missing["detail"])
print("8. the reverse lookup: which sentences use this article?")
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"])
@@ -224,21 +341,42 @@ def main() -> int:
cited = call("GET", "/references?cited=true")
check("the cited filter now finds it", cited["total"] == 1, str(cited["total"]))
print("9. a cited reference cannot be deleted; an uncited one can")
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("10. clean up")
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
@@ -254,6 +392,12 @@ def main() -> int:
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__":