refactor(phase8-g1): carve export v1 shim to knowledge_base domain (#47) (#1677)

earayu · claude · web-flow · commit 940d5bb3aab7 · 2026-04-25T17:03:53.000+08:00
* refactor(phase8-g1): carve export v1 shim to knowledge_base domain (#47) Per PM scope (msg=7733c905) and Bryce inventory G1: complete the export carve trail started by #1670 (ExportTask ORM) and #1672 (export_collection_task). Pure carve / move; URL contract `/api/v1/export*` and `/api/v1/export-tasks*` unchanged. Changes: - aperag/views/export.py → aperag/domains/knowledge_base/api/export_routes.py (3 routes: create_export_task / get_export_task / download_export; switched User ORM dep → AuthenticatedUser Protocol, matching the canonical KB routes pattern) - aperag/service/export_service.py → aperag/domains/knowledge_base/service/export_service.py (git mv preserves history; replaced view_models.ExportTaskResponse references with bare ExportTaskResponse imported from KB schemas) - ExportTaskResponse schema migrated from aperag/schema/view_models.py to aperag/domains/knowledge_base/schemas.py (added to __all__); view_models.py keeps a backward-compat re-export following the same pattern used for knowledge_graph/retrieval schemas - aperag/app.py: import switched from aperag.views.export to aperag.domains.knowledge_base.api.export_routes; mount prefix remains /api/v1 (D1 hard-cut to /api/v2 deferred to later G3+ batch) Verification: - pytest tests/unit_test/test_modularization_boundaries.py -x → 21 passed (G1-G19 all green; new KB route does not import legacy aggregates) - pytest tests/unit_test/ → 686 passed, 29 skipped (matches phase8 baseline) - grep "from aperag.service.export_service|from aperag.views.export" returns 0 hits in aperag/, tests/, config/ - python -c "from aperag.app import app; ..." confirms 3 export endpoints remain at /api/v1/collections/{id}/export, /api/v1/export-tasks/{id}, /api/v1/export-tasks/{id}/download aperag/service/ retains exactly the 3 permanent seam files (quota_service / prompt_template_service / search_pipeline_service); no Layer A / Layer B violation. Ghost-check: none. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * refactor(phase8-g1): D7 v2 hard-cut for export endpoints (#47) Per @符炫炜 D7 canonical update (msg=30405f5b) + PM msg=3b0c2589: G1 includes URL prefix migration `/api/v1/export*` → `/api/v2/export*`, not just file carve. - aperag/app.py: export_router mount /api/v1 → /api/v2 - aperag/domains/knowledge_base/api/export_routes.py: docstring updated to reflect D7 v2 hard-cut - aperag/domains/knowledge_base/service/export_service.py: download_url template /api/v1/... → /api/v2/... - web/src/api-v2/schema.d.ts: 3 export route key strings v1 → v2 - web/src/features/collection/client-api.ts: 2 client call paths v1 → v2 - tests/unit_test/test_web_typed_api_contract.py: assertions and comment updated to expect v2 paths post-D7 Verification: - pytest tests/unit_test/test_modularization_boundaries.py tests/unit_test/test_web_typed_api_contract.py -x → 37 passed - python -c "from aperag.app import app; ..." → 3 export endpoints now mounted at /api/v2/{collections/{id}/export, export-tasks/{id}, export-tasks/{id}/download} - grep "/api/v1/export" aperag/ tests/ web/ config/ → 0 hits (a single unrelated historical comment about KG-eval export remains in knowledge_graph/api/routes.py:259, untouched) Ghost-check: none. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
diff --git a/aperag/app.py b/aperag/app.py
@@ -67,6 +67,7 @@
 from aperag.domains.knowledge_base.service.collection_service import (
     set_search_pipeline_ops as _kb_set_search_pipeline_ops,
 )
+from aperag.domains.knowledge_base.api.export_routes import router as export_router
 from aperag.domains.knowledge_graph.api.routes import router as knowledge_graph_router
 from aperag.domains.marketplace.api.routes import router as marketplace_router
 from aperag.domains.marketplace.service.marketplace_collection_service import (
@@ -85,7 +86,6 @@
 from aperag.openapi_spec import custom_generate_unique_id
 from aperag.service.quota_service import quota_service as _legacy_quota_service
 from aperag.service.search_pipeline_service import search_pipeline_service as _legacy_search_pipeline_service
-from aperag.views.export import router as export_router
 from aperag.views.prompts import router as prompts_router
 from aperag.views.settings import router as settings_router
 
@@ -223,7 +223,7 @@ async def health_check():
 
 
 app.include_router(auth_router, prefix="/api/v2/auth")
-app.include_router(export_router, prefix="/api/v1")  # Add export router
+app.include_router(export_router, prefix="/api/v2")  # KB-domain export router (Phase 8 #47 G1, D7 v2 hard-cut)
 app.include_router(governance_router, prefix="/api/v1")  # Governance domain router (api_key + audit)
 app.include_router(llm_router, prefix="/api/v1")  # Model platform: embed/rerank (OpenAI-compat)
 app.include_router(
diff --git a/aperag/domains/knowledge_base/api/export_routes.py b/aperag/domains/knowledge_base/api/export_routes.py
@@ -12,14 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Export operations HTTP router (Phase 8 #47 G1 carve, D7 v2 hard-cut).
+
+Carved from legacy ``aperag/views/export.py``. URLs migrated to v2
+(``/api/v2/collections/{id}/export`` + ``/api/v2/export-tasks/*``);
+mounted at ``/api/v2`` in ``aperag/app.py`` per D7 canonical
+(uniform ``/api/v2`` for all backend routes; OpenAI-compat
+``/api/v1/embeddings`` + ``/api/v1/rerank`` are the only remaining
+v1 allowlist).
+"""
+
 import logging
 
 from fastapi import APIRouter, Depends, Request
 
-from aperag.domains.identity.db.models import User
 from aperag.domains.identity.service.auth_dependencies import required_user
-from aperag.schema import view_models
-from aperag.service.export_service import export_service
+from aperag.domains.knowledge_base.ports import AuthenticatedUser
+from aperag.domains.knowledge_base.schemas import ExportTaskResponse
+from aperag.domains.knowledge_base.service.export_service import export_service
 
 logger = logging.getLogger(__name__)
 
@@ -35,8 +45,8 @@
 async def create_export_task_view(
     request: Request,
     collection_id: str,
-    user: User = Depends(required_user),
-) -> view_models.ExportTaskResponse:
+    user: AuthenticatedUser = Depends(required_user),
+) -> ExportTaskResponse:
     """Create an async export task to package all object-store files under the collection."""
     return await export_service.create_export_task(str(user.id), collection_id)
 
@@ -49,8 +59,8 @@ async def create_export_task_view(
 async def get_export_task_view(
     request: Request,
     task_id: str,
-    user: User = Depends(required_user),
-) -> view_models.ExportTaskResponse:
+    user: AuthenticatedUser = Depends(required_user),
+) -> ExportTaskResponse:
     """Query the status and progress of an export task."""
     return await export_service.get_export_task(str(user.id), task_id)
 
@@ -63,7 +73,7 @@ async def get_export_task_view(
 async def download_export_view(
     request: Request,
     task_id: str,
-    user: User = Depends(required_user),
+    user: AuthenticatedUser = Depends(required_user),
 ):
     """Stream the completed export ZIP file to the client."""
     return await export_service.download_export(str(user.id), task_id)
diff --git a/aperag/domains/knowledge_base/schemas.py b/aperag/domains/knowledge_base/schemas.py
@@ -77,6 +77,7 @@
     "SharingStatusResponse",
     "MineruTokenTestRequest",
     "MineruTokenTestResponse",
+    "ExportTaskResponse",
 ]
 
 
@@ -381,3 +382,33 @@ class MineruTokenTestResponse(BaseModel):
         default_factory=dict,
         description="Passthrough body from MinerU upstream",
     )
+
+
+# ---------- Phase 8 #47 G1: export envelope ---------- #
+#
+# Carved from ``aperag.schema.view_models.ExportTaskResponse`` so the
+# KB domain owns the response shape used by its export routes
+# (``POST /collections/{id}/export`` + ``GET /export-tasks/*``).
+# ``aperag.schema.view_models`` continues to re-export this name during
+# the cleanup window.
+
+
+class ExportTaskResponse(BaseModel):
+    export_task_id: str = Field(..., description="Unique ID of the export task")
+    status: Literal["PENDING", "PROCESSING", "COMPLETED", "FAILED", "EXPIRED"] = Field(
+        ..., description="Current status of the export task"
+    )
+    progress: Optional[conint(ge=0, le=100)] = Field(None, description="Progress percentage (0-100)")
+    message: Optional[str] = Field(None, description="Human-readable status message")
+    error_message: Optional[str] = Field(None, description="Error detail when status is FAILED")
+    download_url: Optional[str] = Field(
+        None,
+        description="URL to download the ZIP file (only set when status is COMPLETED)",
+    )
+    file_size: Optional[int] = Field(None, description="Size of the ZIP file in bytes")
+    gmt_created: Optional[datetime] = None
+    gmt_completed: Optional[datetime] = None
+    gmt_expires: Optional[datetime] = Field(
+        None,
+        description="Time when the export file will be automatically deleted (7 days after creation)",
+    )
diff --git a/aperag/domains/knowledge_base/service/export_service.py b/aperag/domains/knowledge_base/service/export_service.py
@@ -26,9 +26,9 @@
     ExportTask,
     ExportTaskStatus,
 )
+from aperag.domains.knowledge_base.schemas import ExportTaskResponse
 from aperag.exceptions import CollectionNotFoundException, PermissionDeniedError
 from aperag.objectstore.base import get_async_object_store
-from aperag.schema import view_models
 from aperag.utils.utils import utc_now
 
 logger = logging.getLogger(__name__)
@@ -40,7 +40,7 @@ class ExportService:
     def __init__(self):
         self.db_ops = async_db_ops
 
-    async def create_export_task(self, user_id: str, collection_id: str) -> view_models.ExportTaskResponse:
+    async def create_export_task(self, user_id: str, collection_id: str) -> ExportTaskResponse:
         async def _create(session):
             # Verify collection exists and user is owner
             result = await session.execute(
@@ -103,14 +103,14 @@ async def _create(session):
 
         export_collection_task.delay(task.id)
 
-        return view_models.ExportTaskResponse(
+        return ExportTaskResponse(
             export_task_id=task.id,
             status=task.status,
             progress=task.progress,
             message=task.message,
         )
 
-    async def get_export_task(self, user_id: str, task_id: str) -> view_models.ExportTaskResponse:
+    async def get_export_task(self, user_id: str, task_id: str) -> ExportTaskResponse:
         async def _get(session):
             result = await session.execute(
                 select(ExportTask).where(and_(ExportTask.id == task_id, ExportTask.user == user_id))
@@ -123,9 +123,9 @@ async def _get(session):
 
         download_url = None
         if task.status == ExportTaskStatus.COMPLETED:
-            download_url = f"/api/v1/export-tasks/{task_id}/download"
+            download_url = f"/api/v2/export-tasks/{task_id}/download"
 
-        return view_models.ExportTaskResponse(
+        return ExportTaskResponse(
             export_task_id=task.id,
             status=task.status,
             progress=task.progress,
diff --git a/aperag/schema/view_models.py b/aperag/schema/view_models.py
@@ -649,25 +649,13 @@ class EvaluationChatWithAgentResponse(RootModel[Union[ChatSuccessResponse, Agent
 # AgentMessage``) keep resolving the same class object.
 
 
-class ExportTaskResponse(BaseModel):
-    export_task_id: str = Field(..., description="Unique ID of the export task")
-    status: Literal["PENDING", "PROCESSING", "COMPLETED", "FAILED", "EXPIRED"] = Field(
-        ..., description="Current status of the export task"
-    )
-    progress: Optional[conint(ge=0, le=100)] = Field(None, description="Progress percentage (0-100)")
-    message: Optional[str] = Field(None, description="Human-readable status message")
-    error_message: Optional[str] = Field(None, description="Error detail when status is FAILED")
-    download_url: Optional[str] = Field(
-        None,
-        description="URL to download the ZIP file (only set when status is COMPLETED)",
-    )
-    file_size: Optional[int] = Field(None, description="Size of the ZIP file in bytes")
-    gmt_created: Optional[datetime] = None
-    gmt_completed: Optional[datetime] = None
-    gmt_expires: Optional[datetime] = Field(
-        None,
-        description="Time when the export file will be automatically deleted (7 days after creation)",
-    )
+# ``ExportTaskResponse`` was carved to
+# ``aperag.domains.knowledge_base.schemas`` in Phase 8 #47 G1 so the
+# KB domain owns its export envelope. The end-of-file
+# ``from aperag.domains.knowledge_base.schemas import (...)`` re-export
+# block keeps pre-migration callers
+# (``from aperag.schema.view_models import ExportTaskResponse``)
+# resolving the same class object.
 
 
 # ---------------------------------------------------------------------------
@@ -684,6 +672,9 @@ class ExportTaskResponse(BaseModel):
 # directly from the canonical modules; consumers outside
 # ``aperag/domains/**`` may continue to use either path during the
 # transition window.
+from aperag.domains.knowledge_base.schemas import (  # noqa: E402,F401
+    ExportTaskResponse,
+)
 from aperag.domains.knowledge_graph.schemas import (  # noqa: E402,F401
     GraphCurationRunSummary,
     GraphEdge,
diff --git a/tests/unit_test/test_web_typed_api_contract.py b/tests/unit_test/test_web_typed_api_contract.py
@@ -639,14 +639,13 @@ def test_collection_feature_uses_v2_typed_api_boundary():
     assert "from '@/features/collection/types'" in export_dialog_tsx
 
     # features/collection adapter must only reach v2 typed paths and not
-    # fall back to the old `@/api` generated SDK or raw fetch. The still-v1
-    # export-task paths are allowed as Phase 1b typed-wrapping, not a v1→v2
-    # rename.
+    # fall back to the old `@/api` generated SDK or raw fetch. Export
+    # endpoints were migrated v1→v2 by Phase 8 #47 G1 (D7 hard-cut).
     assert "from '@/api'" not in feature_sources
     assert "fetch(" not in feature_sources
     assert "/api/v2/collections" in feature_sources
-    assert "'/api/v1/collections/{collection_id}/export'" in feature_sources
-    assert "'/api/v1/export-tasks/{task_id}'" in feature_sources
+    assert "'/api/v2/collections/{collection_id}/export'" in feature_sources
+    assert "'/api/v2/export-tasks/{task_id}'" in feature_sources
 
     # Positive: schema-derived types + fail-fast export-task adapter.
     types_ts = (REPO_ROOT / "web/src/features/collection/types.ts").read_text()
diff --git a/web/src/api-v2/schema.d.ts b/web/src/api-v2/schema.d.ts
@@ -549,7 +549,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/v1/collections/{collection_id}/export": {
+    "/api/v2/collections/{collection_id}/export": {
         parameters: {
             query?: never;
             header?: never;
@@ -569,7 +569,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/v1/export-tasks/{task_id}": {
+    "/api/v2/export-tasks/{task_id}": {
         parameters: {
             query?: never;
             header?: never;
@@ -589,7 +589,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/v1/export-tasks/{task_id}/download": {
+    "/api/v2/export-tasks/{task_id}/download": {
         parameters: {
             query?: never;
             header?: never;
diff --git a/web/src/features/collection/client-api.ts b/web/src/features/collection/client-api.ts
@@ -121,7 +121,7 @@ export async function createExportTask(
   collectionId: string,
 ): Promise<ExportTaskResponse> {
   const { data } = await browserApiClient.POST(
-    '/api/v1/collections/{collection_id}/export',
+    '/api/v2/collections/{collection_id}/export',
     {
       params: { path: { collection_id: collectionId } },
     },
@@ -140,7 +140,7 @@ export async function getExportTask(
   taskId: string,
 ): Promise<ExportTaskResponse> {
   const { data } = await browserApiClient.GET(
-    '/api/v1/export-tasks/{task_id}',
+    '/api/v2/export-tasks/{task_id}',
     {
       params: { path: { task_id: taskId } },
     },
