feat(task-013): add draft assembly API, immutable versioning, and editor preview

2026-05-21 23:33:15 +03:00
parent 8ebb5ad623
commit c3914bf8be
19 changed files with 2416 additions and 16 deletions
@@ -0,0 +1,395 @@
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from fastapi.testclient import TestClient
+
+
+BACKEND_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(BACKEND_ROOT))
+
+from src.application.seed_data import seed_reference_data  # noqa: E402
+from src.infrastructure.repositories import open_backend_repository  # noqa: E402
+from src.presentation.dependencies import get_repository  # noqa: E402
+from src.presentation.main import app  # noqa: E402
+
+
+DEMO_EDITOR_EMAIL = "editor@example.com"
+DEMO_ADMIN_EMAIL = "admin@example.com"
+DEMO_USER_EMAIL_HEADER = "X-Demo-User-Email"
+
+
+class DraftAssemblyPublicApiTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp_dir = tempfile.TemporaryDirectory()
+        os.environ["OBJECT_STORAGE_LOCAL_ROOT"] = str(Path(self.tmp_dir.name) / "objects")
+        dsn = f"sqlite:///{Path(self.tmp_dir.name) / 'draft-assembly.db'}"
+        self.repository = open_backend_repository(dsn)
+        self.repository.setup()
+        seed_reference_data(self.repository)
+        app.dependency_overrides[get_repository] = lambda: self.repository
+        self.client = TestClient(app)
+
+    def tearDown(self) -> None:
+        app.dependency_overrides.clear()
+        os.environ.pop("OBJECT_STORAGE_LOCAL_ROOT", None)
+        self.tmp_dir.cleanup()
+
+    def test_assemble_draft_includes_all_sections_in_order_and_full_payload(self) -> None:
+        article_id, section_headings = self._prepare_article_for_draft_assembly()
+        section_jobs = self._start_parallel_production(article_id)
+
+        for index, job in enumerate(section_jobs, start=1):
+            if index == 1:
+                draft_markdown = (
+                    f"## {job['payload']['heading']}\n\n"
+                    "Use [official documentation](https://example.com/docs) for setup.\n\n"
+                    "| Step | Result |\n"
+                    "| --- | --- |\n"
+                    "| 1 | Ready |\n\n"
+                    "![Existing mock](placeholder://existing/mock)\n"
+                )
+            else:
+                draft_markdown = (
+                    f"## {job['payload']['heading']}\n\n"
+                    f"Body for section {index}."
+                )
+            completed = self._complete_job(
+                job["id"],
+                output={
+                    "status": "SUCCEEDED",
+                    "output_files": [{"path": f"outputs/section-{index}.md"}],
+                    "payload": {
+                        "used_evidence_ids": job["payload"]["used_evidence_ids"],
+                        "unsupported_claims": [],
+                        "suggested_visuals": [{"title": f"Visual {index}"}],
+                        "draft_markdown": draft_markdown,
+                    },
+                },
+            )
+            self.assertEqual("SUCCEEDED", completed["status"])
+
+        assemble_response = self.client.post(
+            f"/api/articles/{article_id}/draft/assemble",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(201, assemble_response.status_code, assemble_response.text)
+
+        draft = assemble_response.json()["draft"]
+        self.assertEqual(1, draft["version"])
+        self.assertTrue(draft["meta_title"])
+        self.assertTrue(draft["meta_description"])
+        self.assertGreaterEqual(len(draft["faq_items"]), 1)
+        self.assertGreaterEqual(len(draft["visual_placeholders"]), 1)
+        self.assertGreaterEqual(len(draft["evidence_references"]), 1)
+        self.assertIn("unsupported_claim_warnings", draft)
+
+        body_markdown = draft["body_markdown"]
+        cursor = -1
+        for heading in section_headings:
+            position = body_markdown.find(f"## {heading}")
+            self.assertGreater(position, cursor)
+            cursor = position
+
+        self.assertIn("## Evidence References", body_markdown)
+        self.assertIn("## Visual Placeholders", body_markdown)
+        self.assertIn("## FAQ", body_markdown)
+        self.assertIn("| Step | Result |", body_markdown)
+        self.assertIn("[official documentation](https://example.com/docs)", body_markdown)
+        self.assertIn("![Existing mock](placeholder://existing/mock)", body_markdown)
+
+        drafts_response = self.client.get(
+            f"/api/articles/{article_id}/drafts",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(200, drafts_response.status_code, drafts_response.text)
+        self.assertEqual(1, len(drafts_response.json()["drafts"]))
+
+        draft_id = draft["id"]
+        draft_detail_response = self.client.get(
+            f"/api/articles/{article_id}/drafts/{draft_id}",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(200, draft_detail_response.status_code, draft_detail_response.text)
+        self.assertEqual(draft["body_markdown"], draft_detail_response.json()["draft"]["body_markdown"])
+
+    def test_patch_creates_new_immutable_draft_version(self) -> None:
+        article_id, _ = self._prepare_article_for_draft_assembly()
+        section_jobs = self._start_parallel_production(article_id)
+        self._complete_all_sections_success(section_jobs)
+        first_draft = self._assemble(article_id)
+
+        patch_response = self.client.patch(
+            f"/api/articles/{article_id}/drafts/{first_draft['id']}",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+            json={
+                "meta_title": "Updated metadata title",
+                "body_markdown": first_draft["body_markdown"] + "\n\nRevision marker.\n",
+            },
+        )
+        self.assertEqual(200, patch_response.status_code, patch_response.text)
+        second_draft = patch_response.json()["draft"]
+        self.assertEqual(2, second_draft["version"])
+        self.assertEqual(first_draft["id"], second_draft["based_on_draft_id"])
+        self.assertEqual("Updated metadata title", second_draft["meta_title"])
+        self.assertIn("Revision marker.", second_draft["body_markdown"])
+
+        first_draft_refresh = self.client.get(
+            f"/api/articles/{article_id}/drafts/{first_draft['id']}",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        ).json()["draft"]
+        self.assertEqual(1, first_draft_refresh["version"])
+        self.assertNotIn("Revision marker.", first_draft_refresh["body_markdown"])
+        self.assertNotEqual(second_draft["meta_title"], first_draft_refresh["meta_title"])
+
+        list_response = self.client.get(
+            f"/api/articles/{article_id}/drafts",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(200, list_response.status_code, list_response.text)
+        versions = [item["version"] for item in list_response.json()["drafts"]]
+        self.assertEqual([2, 1], versions)
+
+    def test_assemble_fails_with_clear_conflict_when_scaffold_missing(self) -> None:
+        article_id, section_headings = self._prepare_article_for_draft_assembly()
+        section_jobs = self._start_parallel_production(article_id)
+        self.assertGreaterEqual(len(section_jobs), 2)
+
+        for job in section_jobs[:-1]:
+            completed = self._complete_job(
+                job["id"],
+                output={
+                    "status": "SUCCEEDED",
+                    "output_files": [{"path": "outputs/ready.md"}],
+                    "payload": {
+                        "used_evidence_ids": job["payload"]["used_evidence_ids"],
+                        "unsupported_claims": [],
+                        "draft_markdown": f"## {job['payload']['heading']}\n\nReady.",
+                    },
+                },
+            )
+            self.assertEqual("SUCCEEDED", completed["status"])
+
+        missing_heading = section_headings[-1]
+        assemble_response = self.client.post(
+            f"/api/articles/{article_id}/draft/assemble",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(409, assemble_response.status_code, assemble_response.text)
+        self.assertIn("Missing successful section scaffolds", assemble_response.text)
+        self.assertIn(missing_heading, assemble_response.text)
+
+    def test_assemble_carries_unsupported_claim_warnings_from_scaffold_attempts(self) -> None:
+        article_id, _ = self._prepare_article_for_draft_assembly()
+        section_jobs = self._start_parallel_production(article_id)
+        self.assertGreaterEqual(len(section_jobs), 1)
+
+        first_job = section_jobs[0]
+        failed = self._complete_job(
+            first_job["id"],
+            output={
+                "status": "SUCCEEDED",
+                "output_files": [{"path": "outputs/failed.md"}],
+                "payload": {
+                    "used_evidence_ids": first_job["payload"]["used_evidence_ids"],
+                    "unsupported_claims": [
+                        {"claim_text": "Unverified migration metric", "risk_level": "high"}
+                    ],
+                    "draft_markdown": "Content with unsupported claim",
+                },
+            },
+        )
+        self.assertEqual("FAILED", failed["status"])
+
+        retry_response = self.client.post(
+            f"/api/agent-jobs/{first_job['id']}/retry",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_ADMIN_EMAIL},
+        )
+        self.assertEqual(201, retry_response.status_code, retry_response.text)
+        retry_job = retry_response.json()["job"]
+        retry_completed = self._complete_job(
+            retry_job["id"],
+            output={
+                "status": "SUCCEEDED",
+                "output_files": [{"path": "outputs/retry.md"}],
+                "payload": {
+                    "used_evidence_ids": retry_job["payload"]["used_evidence_ids"],
+                    "unsupported_claims": [],
+                    "draft_markdown": f"## {retry_job['payload']['heading']}\n\nClean section.",
+                },
+            },
+        )
+        self.assertEqual("SUCCEEDED", retry_completed["status"])
+
+        for job in section_jobs[1:]:
+            self._complete_job(
+                job["id"],
+                output={
+                    "status": "SUCCEEDED",
+                    "output_files": [{"path": "outputs/ok.md"}],
+                    "payload": {
+                        "used_evidence_ids": job["payload"]["used_evidence_ids"],
+                        "unsupported_claims": [],
+                        "draft_markdown": f"## {job['payload']['heading']}\n\nReady.",
+                    },
+                },
+            )
+
+        draft = self._assemble(article_id)
+        warnings = draft["unsupported_claim_warnings"]
+        self.assertTrue(any("Unverified migration metric" in warning for warning in warnings))
+        self.assertIn("## Unsupported Claim Warnings", draft["body_markdown"])
+
+    def test_draft_endpoints_return_404_for_missing_resources(self) -> None:
+        random_article_id = uuid4()
+        list_response = self.client.get(
+            f"/api/articles/{random_article_id}/drafts",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(404, list_response.status_code, list_response.text)
+
+        article_id, _ = self._prepare_article_for_draft_assembly()
+        random_draft_id = uuid4()
+        detail_response = self.client.get(
+            f"/api/articles/{article_id}/drafts/{random_draft_id}",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(404, detail_response.status_code, detail_response.text)
+
+        patch_response = self.client.patch(
+            f"/api/articles/{article_id}/drafts/{random_draft_id}",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+            json={"title": "Will fail"},
+        )
+        self.assertEqual(404, patch_response.status_code, patch_response.text)
+
+    def _assemble(self, article_id: str) -> dict[str, Any]:
+        response = self.client.post(
+            f"/api/articles/{article_id}/draft/assemble",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(201, response.status_code, response.text)
+        return response.json()["draft"]
+
+    def _complete_all_sections_success(self, section_jobs: list[dict[str, Any]]) -> None:
+        for index, job in enumerate(section_jobs, start=1):
+            completed = self._complete_job(
+                job["id"],
+                output={
+                    "status": "SUCCEEDED",
+                    "output_files": [{"path": f"outputs/{index}.md"}],
+                    "payload": {
+                        "used_evidence_ids": job["payload"]["used_evidence_ids"],
+                        "unsupported_claims": [],
+                        "draft_markdown": f"## {job['payload']['heading']}\n\nSection {index}.",
+                    },
+                },
+            )
+            self.assertEqual("SUCCEEDED", completed["status"])
+
+    def _complete_job(self, job_id: str, *, output: dict[str, Any]) -> dict[str, Any]:
+        response = self.client.post(
+            f"/internal/agent-jobs/{job_id}/complete",
+            json={
+                "workspace_path": f"/tmp/{job_id}",
+                "stdout": "fake section scaffolding runner\n",
+                "stderr": "",
+                "exit_code": 0,
+                "duration_ms": 1,
+                "output": output,
+            },
+        )
+        self.assertEqual(200, response.status_code, response.text)
+        return response.json()["job"]
+
+    def _start_parallel_production(self, article_id: str) -> list[dict[str, Any]]:
+        start_response = self.client.post(
+            f"/api/articles/{article_id}/draft/start",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(202, start_response.status_code, start_response.text)
+        jobs = start_response.json()["jobs"]
+        return [job for job in jobs if job["job_type"] == "SECTION_SCAFFOLD"]
+
+    def _prepare_article_for_draft_assembly(self) -> tuple[str, list[str]]:
+        article_id, section_headings = self._create_article_with_approved_plan()
+        self._ensure_evidence_ready(article_id)
+        return article_id, section_headings
+
+    def _ensure_evidence_ready(self, article_id: str) -> None:
+        research_response = self.client.post(
+            f"/api/articles/{article_id}/research/start",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(201, research_response.status_code, research_response.text)
+
+        evidence_response = self.client.get(
+            f"/api/articles/{article_id}/evidence",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(200, evidence_response.status_code, evidence_response.text)
+        self.assertEqual("EVIDENCE_MATRIX_READY", evidence_response.json()["article"]["status"])
+        self.assertFalse(evidence_response.json()["insufficient_evidence_reasons"])
+
+    def _create_article_with_approved_plan(self) -> tuple[str, list[str]]:
+        site = self.client.get(
+            "/api/sites",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        ).json()[0]["site"]
+        article = self.client.post(
+            "/api/articles",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+            json={
+                "target_site_id": site["id"],
+                "brief_description": "Assemble draft from section scaffolds with versions.",
+                "working_title": "Draft Assembly With Versions",
+                "content_type": "longform_guide",
+                "primary_keyword": "draft assembly editor preview",
+            },
+        ).json()["article"]
+        article_id = article["id"]
+
+        questions = self.client.post(
+            f"/api/articles/{article_id}/boundary-questions/generate",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        ).json()["questions"]
+        for question in questions:
+            if question["is_required"]:
+                patch_response = self.client.patch(
+                    f"/api/articles/{article_id}/boundary-questions/{question['id']}",
+                    headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+                    json={"answer": f"Answer for {question['category']}"},
+                )
+                self.assertEqual(200, patch_response.status_code, patch_response.text)
+
+        submit_response = self.client.post(
+            f"/api/articles/{article_id}/boundary-questions/submit",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(200, submit_response.status_code, submit_response.text)
+
+        plan_response = self.client.post(
+            f"/api/articles/{article_id}/plan/generate",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(201, plan_response.status_code, plan_response.text)
+        plan = plan_response.json()["plan"]
+        self.assertGreaterEqual(len(plan["sections"]), 1)
+
+        approve_response = self.client.post(
+            f"/api/articles/{article_id}/plans/{plan['id']}/approve",
+            headers={DEMO_USER_EMAIL_HEADER: DEMO_EDITOR_EMAIL},
+        )
+        self.assertEqual(200, approve_response.status_code, approve_response.text)
+
+        return article_id, [section["heading"] for section in plan["sections"]]
+
+
+if __name__ == "__main__":
+    unittest.main()