backend: add the reference library (参考文献)
One table per document the writer has read, and one for its contributors:
reference id, type, title, subtitle, title_translated,
container_title, volume, issue, pages, publisher,
publisher_place, event_*, publication_year/month/day,
accessed_date, doi, isbn, issn, url, patent_*,
standard_number, report_number, arxiv_id, abstract,
keywords, note, citation_key, language
reference_author reference_id, sort, name, family_name, given_name, role
The field set is the intersection of the formats a paper has to survive, taken
from the CSL JSON schema (103 fields, 45 types — what Zotero, Mendeley and
Pandoc exchange) against GB/T 7714-2015, BibTeX and RIS. The mapping is on
`app.models.reference` rather than in a commit message, because the next person
to add a column needs it more than this one does. Three decisions worth naming:
* **Partial dates.** Year, month and day are separate nullable integers, which
is CSL's `issued`: a book has a year, a newspaper article a day, a patent its
公告日期, and nothing invents the rest.
* **Contributors are rows, not a column.** A citation prints an ordered list
with 编 / 译 marks, and styles rewrite names (「张三」 / "Zhang, S." /
"S. Zhang"), so the printed form and its two halves are stored separately —
display reads `name`, a reformatting style reads the halves, and an
institutional author has neither.
* **`volume` / `issue` / `pages` are strings.** Journals print `12(Suppl.)`,
`S1` and `e12345`, and a citation reproduces what is printed.
The library is global: the same article is cited from several papers, so the
entry cannot belong to one of them. The citation stays on the paper side in
`paper_sentence_reference`, which now carries a real foreign key to `reference`
(`ON DELETE RESTRICT`) — the column had been a loose integer waiting for this
table. A sentence may quote several documents and a document may be quoted by
many sentences, which is why the relation is a table and not a column on
`paper_sentence`.
Refusals are raised once, in the data layer, as `UnknownReference`, and
translated where each caller speaks: `400` with the offending ids for REST (one
exception handler, no route carries the check), a readable tool error for MCP
(one wrapper in the tool registry). Neither entry point can skip it, so the
foreign key never has to be the thing that complains.
API: `/references` CRUD plus batch delete, and `/references/{id}/citations` for
the reverse lookup — "where have I used this article?" — which is what tells a
writer whether an entry is safe to delete.
Verified: 29 new checks in `scripts/smoke_references.py` (partial dates, DOI
normalisation, author order and roles, search by author/type/year/cited, the
citation round trip, 400 on a phantom id, 409 on a cited entry), the paper
suite's 45 and the MCP suite's 47 still pass. The MCP suite now cites a real
entry instead of a phantom id, which is what an agent has to do now.
This commit is contained in:
@@ -63,6 +63,7 @@ def check(label: str, condition: bool, detail: str = "") -> None:
|
||||
|
||||
def main() -> int:
|
||||
created_papers: list[int] = []
|
||||
created_references: list[int] = []
|
||||
|
||||
try:
|
||||
# The database may already hold real papers, so "nothing of ours is
|
||||
@@ -117,6 +118,21 @@ def main() -> int:
|
||||
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}",
|
||||
@@ -124,12 +140,14 @@ def main() -> int:
|
||||
"sentences": [
|
||||
{
|
||||
"content": " 第一句话,用于验证空白折叠。 ",
|
||||
"citations": [{"reference_id": 7, "quote": "被引用的第一段内容"}],
|
||||
"citations": [
|
||||
{"reference_id": reference["id"], "quote": "被引用的第一段内容"}
|
||||
],
|
||||
},
|
||||
{
|
||||
"content": "第二句话。",
|
||||
"citations": [
|
||||
{"reference_id": 9, "quote": "引文甲"},
|
||||
{"reference_id": reference["id"], "quote": "引文甲"},
|
||||
{"quote": "只有引用内容、暂时没有引用 id"},
|
||||
],
|
||||
},
|
||||
@@ -230,7 +248,16 @@ def main() -> int:
|
||||
bad = call(
|
||||
"PUT",
|
||||
f"/papers/{paper['id']}/paragraphs/{first_sort}",
|
||||
{"sentences": [{"content": "x", "citations": [{"reference_id": 3, "quote": " "}]}]},
|
||||
{
|
||||
"sentences": [
|
||||
{
|
||||
"content": "x",
|
||||
"citations": [
|
||||
{"reference_id": reference["id"], "quote": " "}
|
||||
],
|
||||
}
|
||||
]
|
||||
},
|
||||
expect=422,
|
||||
)
|
||||
check("citation without content refused", "detail" in bad)
|
||||
@@ -361,6 +388,9 @@ def main() -> int:
|
||||
print("15. 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,
|
||||
@@ -371,6 +401,11 @@ def main() -> int:
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user