fix(std-platform): citation_insert -- correct target FK dispatch + citation_text guard + insert/verify column split

Author: Gemini CLI

data_agent/api/standards_routes.py

@@ -325,43 +325,77 @@ async def citation_insert(request: Request):
     if not clause_id or not cand:
         return JSONResponse({"error": "clause_id and candidate required"},
                             status_code=400)
+
+    # Fix #4: validate citation_text early
+    citation_text = (cand.get("snippet") or "").strip()[:500]
+    if not citation_text:
+        return JSONResponse({"error": "citation_text is required"},
+                            status_code=400)
+
+    # Fix #3: dispatch target_kind to the correct FK column
     kind = cand.get("kind", "")
-    target_kind_map = {
-        "std_clause": "std_clause",
-        "std_data_element": "std_clause",  # element belongs to a clause
-        "std_term": "std_clause",
-        "kb_chunk": "internet_search",
-        "web_snapshot": "web_snapshot",
-    }
-    target_kind = target_kind_map.get(kind)
-    if target_kind is None:
-        return JSONResponse(
-            {"error": f"unsupported candidate kind: {kind}"},
-            status_code=400)
     target_clause_id = None
-    target_url = cand.get("target_url")
+    target_data_element_id = None
+    target_term_id = None
+    target_document_id = None
+    target_url = None
     snapshot_id = None
-    if kind in ("std_clause",):
+
+    if kind == "std_clause":
+        target_kind = "std_clause"
         target_clause_id = cand.get("target_id")
+    elif kind == "std_data_element":
+        target_kind = "std_data_element"
+        target_data_element_id = cand.get("target_id")
+    elif kind == "std_term":
+        target_kind = "std_term"
+        target_term_id = cand.get("target_id")
+    elif kind == "std_document":
+        target_kind = "std_document"
+        target_document_id = cand.get("target_id")
+    elif kind == "kb_chunk":
+        # KB chunk has no FK target — record as internet_search with the
+        # source URL if the candidate carried one.
+        target_kind = "internet_search"
+        target_url = cand.get("target_url")
     elif kind == "web_snapshot":
+        target_kind = "web_snapshot"
         snapshot_id = cand.get("target_id")
-    citation_text = (cand.get("snippet") or "")[:500]
+        target_url = cand.get("target_url")
+    elif kind == "external_url":
+        target_kind = "external_url"
+        target_url = cand.get("target_url")
+    else:
+        return JSONResponse(
+            {"error": f"unsupported candidate kind: {kind}"},
+            status_code=400)
+
     confidence = cand.get("extra", {}).get("confidence")
     eng = get_engine()
     import uuid as _u
     ref_id = str(_u.uuid4())
+    # Fix #5: inserted_by/inserted_at instead of verified_by/verified_at;
+    # verification_status defaults to 'pending' via DB DEFAULT.
     with eng.begin() as conn:
         conn.execute(text("""
             INSERT INTO std_reference (
-                id, source_clause_id, target_kind, target_clause_id,
-                target_url, snapshot_id, citation_text, confidence,
-                verified_by, verified_at)
-            VALUES (:i, :sc, :tk, :tc, :tu, :sn, :ct, :cf, :u, now())
+                id, source_clause_id, target_kind,
+                target_clause_id, target_data_element_id, target_term_id,
+                target_document_id, target_url, snapshot_id,
+                citation_text, confidence,
+                inserted_by, inserted_at)
+            VALUES (:i, :sc, :tk,
+                    :tc, :tde, :tt,
+                    :td, :tu, :sn,
+                    :ct, :cf,
+                    :u, now())
         """), {
             "i": ref_id, "sc": clause_id, "tk": target_kind,
-            "tc": target_clause_id, "tu": target_url,
-            "sn": snapshot_id, "ct": citation_text,
-            "cf": confidence, "u": username,
+            "tc": target_clause_id, "tde": target_data_element_id,
+            "tt": target_term_id, "td": target_document_id,
+            "tu": target_url, "sn": snapshot_id,
+            "ct": citation_text, "cf": confidence,
+            "u": username,
         })
     return JSONResponse({"ref_id": ref_id, "citation_text": citation_text})
 

data_agent/standards_platform/tests/test_api_citation.py

@@ -70,13 +70,13 @@ def test_insert_citation_creates_std_reference(monkeypatch, engine, fresh_clause
         with engine.connect() as conn:
             row = conn.execute(text(
                 "SELECT source_clause_id, target_clause_id, citation_text, "
-                "confidence, verified_by FROM std_reference WHERE id=:i"
+                "confidence, inserted_by FROM std_reference WHERE id=:i"
             ), {"i": ref_id}).first()
         assert str(row.source_clause_id) == cid
         assert str(row.target_clause_id) == target_clause
         assert row.citation_text == "test snippet"
         assert float(row.confidence) == 0.85
-        assert row.verified_by == "admin"
+        assert row.inserted_by == "admin"
     finally:
         with engine.begin() as c:
             c.execute(text("DELETE FROM std_document WHERE id=:d"),
@@ -92,3 +92,197 @@ def test_insert_citation_rejects_invalid_kind(monkeypatch, fresh_clause):
     r = _client().post("/api/std/citation/insert",
                        json={"clause_id": cid, "candidate": cand})
     assert r.status_code == 400
+
+
+# ---------------------------------------------------------------------------
+# Wave 3 v1 fixes: Fix #3 (target FK dispatch) + Fix #4 (empty text guard)
+# + Fix #5 (inserted_by / verification_status)
+# ---------------------------------------------------------------------------
+
+import uuid as _uuid_mod
+
+
+def _seed_data_element(engine, version_id):
+    de_id = str(_uuid_mod.uuid4())
+    with engine.begin() as conn:
+        conn.execute(text(
+            "INSERT INTO std_data_element (id, document_version_id, "
+            "name_zh, code) VALUES (:i, :v, '测试要素', :c)"
+        ), {"i": de_id, "v": version_id, "c": f"DE-W3-{de_id[:6]}"})
+    return de_id
+
+
+def _seed_term(engine, version_id):
+    t_id = str(_uuid_mod.uuid4())
+    with engine.begin() as conn:
+        conn.execute(text(
+            "INSERT INTO std_term (id, document_version_id, term_code, "
+            "name_zh, definition) VALUES (:i, :v, :tc, '测试术语', '定义')"
+        ), {"i": t_id, "v": version_id, "tc": f"TC-W3-{t_id[:6]}"})
+    return t_id
+
+
+def test_citation_insert_data_element_target(monkeypatch, engine, fresh_clause):
+    """Fix #3: target_kind=std_data_element writes target_data_element_id,
+    not target_clause_id."""
+    cid, _, vid = fresh_clause
+    de_id = _seed_data_element(engine, vid)
+    _auth_user(monkeypatch, username="admin", role="admin")
+    ref_id = None
+    try:
+        r = _client().post("/api/std/citation/insert", json={
+            "clause_id": cid,
+            "candidate": {
+                "kind": "std_data_element",
+                "target_id": de_id,
+                "snippet": "数据要素引用",
+                "extra": {"confidence": 0.85},
+            },
+        })
+        assert r.status_code == 200, r.text
+        ref_id = r.json()["ref_id"]
+        with engine.connect() as conn:
+            row = conn.execute(text(
+                "SELECT target_kind, target_clause_id, target_data_element_id, "
+                "target_term_id, inserted_by, verified_by, verification_status "
+                "FROM std_reference WHERE id=:i"
+            ), {"i": ref_id}).first()
+        assert row[0] == "std_data_element"
+        assert row[1] is None
+        assert str(row[2]) == de_id
+        assert row[3] is None
+        assert row[4] == "admin"      # inserted_by populated (Fix #5)
+        assert row[5] is None         # verified_by NULL (Fix #5)
+        assert row[6] == "pending"    # verification_status default (Fix #5)
+    finally:
+        with engine.begin() as c:
+            # ON DELETE CASCADE from std_data_element → std_reference
+            c.execute(text("DELETE FROM std_data_element WHERE id=:i"), {"i": de_id})
+
+
+def test_citation_insert_term_target(monkeypatch, engine, fresh_clause):
+    """Fix #3: target_kind=std_term writes target_term_id."""
+    cid, _, vid = fresh_clause
+    t_id = _seed_term(engine, vid)
+    _auth_user(monkeypatch, username="admin", role="admin")
+    try:
+        r = _client().post("/api/std/citation/insert", json={
+            "clause_id": cid,
+            "candidate": {
+                "kind": "std_term",
+                "target_id": t_id,
+                "snippet": "术语引用",
+                "extra": {"confidence": 0.75},
+            },
+        })
+        assert r.status_code == 200, r.text
+        ref_id = r.json()["ref_id"]
+        with engine.connect() as conn:
+            row = conn.execute(text(
+                "SELECT target_kind, target_term_id, target_clause_id "
+                "FROM std_reference WHERE id=:i"
+            ), {"i": ref_id}).first()
+        assert row[0] == "std_term"
+        assert str(row[1]) == t_id
+        assert row[2] is None
+    finally:
+        with engine.begin() as c:
+            # ON DELETE CASCADE from std_term → std_reference
+            c.execute(text("DELETE FROM std_term WHERE id=:i"), {"i": t_id})
+
+
+def test_citation_insert_clause_target_still_works(monkeypatch, engine, fresh_clause):
+    """Regression: target_kind=std_clause still works post-fix."""
+    cid, _, _ = fresh_clause
+    _auth_user(monkeypatch, username="admin", role="admin")
+    ref_id = None
+    try:
+        r = _client().post("/api/std/citation/insert", json={
+            "clause_id": cid,
+            "candidate": {
+                "kind": "std_clause",
+                "target_id": cid,  # self-reference for test purposes
+                "snippet": "条款引用",
+                "extra": {"confidence": 0.9},
+            },
+        })
+        assert r.status_code == 200, r.text
+        ref_id = r.json()["ref_id"]
+    finally:
+        if ref_id:
+            with engine.begin() as c:
+                c.execute(text("DELETE FROM std_reference WHERE id=:i"), {"i": ref_id})
+
+
+def test_citation_insert_empty_text_rejected(monkeypatch, fresh_clause):
+    """Fix #4: empty citation_text returns 400."""
+    cid, _, _ = fresh_clause
+    _auth_user(monkeypatch, username="admin", role="admin")
+    r = _client().post("/api/std/citation/insert", json={
+        "clause_id": cid,
+        "candidate": {
+            "kind": "std_clause",
+            "target_id": cid,
+            "snippet": "",
+            "extra": {"confidence": 0.5},
+        },
+    })
+    assert r.status_code == 400
+    assert "citation_text" in r.json().get("error", "")
+
+
+def test_citation_insert_whitespace_text_rejected(monkeypatch, fresh_clause):
+    """Fix #4: whitespace-only citation_text returns 400."""
+    cid, _, _ = fresh_clause
+    _auth_user(monkeypatch, username="admin", role="admin")
+    r = _client().post("/api/std/citation/insert", json={
+        "clause_id": cid,
+        "candidate": {
+            "kind": "std_clause",
+            "target_id": cid,
+            "snippet": "   \n\t",
+            "extra": {"confidence": 0.5},
+        },
+    })
+    assert r.status_code == 400
+
+
+def test_citation_insert_web_snapshot_target(monkeypatch, engine, fresh_clause):
+    """Regression: web_snapshot target writes target_url and snapshot_id."""
+    cid, _, _ = fresh_clause
+    snap_id = str(_uuid_mod.uuid4())
+    with engine.begin() as conn:
+        conn.execute(text(
+            "INSERT INTO std_web_snapshot (id, url, http_status, "
+            "extracted_text) VALUES (:i, 'https://example.com/x', 200, "
+            "'snippet')"
+        ), {"i": snap_id})
+    _auth_user(monkeypatch, username="admin", role="admin")
+    ref_id = None
+    try:
+        r = _client().post("/api/std/citation/insert", json={
+            "clause_id": cid,
+            "candidate": {
+                "kind": "web_snapshot",
+                "target_id": snap_id,
+                "target_url": "https://example.com/x",
+                "snippet": "网页引用",
+                "extra": {"confidence": 0.6},
+            },
+        })
+        assert r.status_code == 200, r.text
+        ref_id = r.json()["ref_id"]
+        with engine.connect() as conn:
+            row = conn.execute(text(
+                "SELECT target_kind, target_url, snapshot_id "
+                "FROM std_reference WHERE id=:i"
+            ), {"i": ref_id}).first()
+        assert row[0] == "web_snapshot"
+        assert row[1] == "https://example.com/x"
+        assert str(row[2]) == snap_id
+    finally:
+        if ref_id:
+            with engine.begin() as c:
+                c.execute(text("DELETE FROM std_reference WHERE id=:i"), {"i": ref_id})
+        with engine.begin() as c:
+            c.execute(text("DELETE FROM std_web_snapshot WHERE id=:i"), {"i": snap_id})