refactor(phase8 #48 G2): settings shim → knowledge_base domain + /api/v2 hard-cut (#1678)

Phase 8 second batch G2 — per architect canonical D7-2 (msg=94f663f2 §3.2.2),
``aperag/views/settings.py`` is carved into the knowledge_base domain and the
URL prefix is hard-cut from ``/api/v1/settings*`` to ``/api/v2/settings*``.

Changes:
- Rename ``aperag/views/settings.py`` → ``aperag/domains/knowledge_base/api/settings_routes.py``
- Inline the small ``Settings`` request schema locally so the new domain
  module does not import ``aperag.schema.view_models`` (G1 ban). Drop the
  now-orphan ``Settings`` class from ``aperag/schema/view_models.py`` —
  no other caller imports it (verified by grep).
- Switch the ``settings_router`` mount in ``aperag/app.py`` from
  ``/api/v1`` to ``/api/v2``; sort the import line into the
  ``aperag.domains.knowledge_base.api.*`` block.
- Add a new boundary test
  ``test_no_module_imports_legacy_views_settings`` — analogous to the
  existing ``test_aperag_domains_never_import_legacy_auth_view_dependencies``
  added by #36. Total boundary tests now 22.
- Update ``docs/modularization/cleanup-inventory.md`` §3.2 to mark the
  row done.

FE follow-up: ``web/src/features/admin/{client,server}-api.ts`` (and
related typed-client regen) will be picked up by @dongdong in a sibling
PR per task thread #模块化重构:e1f4ce71.

Gates: 22/22 boundary, 686 pass / 29 skip / 1 deselect / 0 fail unit
suite, ruff check + format clean.

Author: earayu

aperag/app.py

@@ -55,6 +55,7 @@
     set_quota_init_ops as _id_set_quota_init_ops,
 )
 from aperag.domains.knowledge_base.api.routes import router as knowledge_base_router
+from aperag.domains.knowledge_base.api.settings_routes import router as settings_router
 from aperag.domains.knowledge_base.service.collection_service import (
     set_marketplace_collection_ops as _kb_set_marketplace_collection_ops,
 )
@@ -87,7 +88,6 @@
 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.prompts import router as prompts_router
-from aperag.views.settings import router as settings_router
 
 # Wire the knowledge_base domain's consumer-owned Protocol DI slots
 # (Phase 3 Step 5b2c). All four legacy service singletons now
@@ -229,7 +229,7 @@ async def health_check():
 app.include_router(
     marketplace_router, prefix="/api/v1"
 )  # Marketplace domain router (marketplace + marketplace_collections)
-app.include_router(settings_router, prefix="/api/v1")
+app.include_router(settings_router, prefix="/api/v2")  # KB domain settings (carved from views/ in #48)
 app.include_router(prompts_router, prefix="/api/v1")  # Add prompts router
 app.include_router(web_access_router, prefix="/api/v2", tags=["web_access"])  # Add web_access domain router
 app.include_router(retrieval_router, prefix="/api/v2", tags=["retrieval"])  # Add retrieval domain router

aperag/views/settings.py …ns/knowledge_base/api/settings_routes.pyaperag/views/settings.py renamed to aperag/domains/knowledge_base/api/settings_routes.py aperag/views/settings.py renamed to aperag/domains/knowledge_base/api/settings_routes.py

@@ -12,15 +12,43 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""System settings routes for the knowledge_base domain.
+
+Hosts ``/settings`` endpoints related to document parser configuration
+(MinerU token, parser health). Carved here from ``aperag/views/settings.py``
+in Phase 8 task #48 (G2) per canonical D7-2: ``/api/v1/settings*`` is
+hard-cut to ``/api/v2/settings*`` (see cleanup-inventory.md §3.2.2).
+
+Backing service is ``aperag.domains.governance.service.setting_service``
+because the underlying ``Setting`` ORM lives in the governance domain;
+this module is a thin api layer that the knowledge_base domain owns
+because the settings exposed here are doc-parser configuration that
+the KB ingest pipeline consumes.
+"""
+
 from typing import Optional
 
 from fastapi import APIRouter, Body, Depends, Response
 from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
 
 from aperag.docparser.health import ParserHealthReport, get_parser_health_report
 from aperag.domains.governance.service.setting_service import setting_service
 from aperag.domains.identity.service.auth_dependencies import required_user
-from aperag.schema.view_models import Settings
+
+
+class Settings(BaseModel):
+    """Knowledge-base parser settings request/response schema.
+
+    Carved here from ``aperag.schema.view_models.Settings`` in #48 (G2)
+    so the knowledge_base domain owns the shape directly and does not
+    depend on the legacy aggregate ``aperag.schema.view_models``.
+    """
+
+    use_mineru: Optional[bool] = Field(None, description="Whether to use MinerU")
+    mineru_api_token: Optional[str] = Field(None, description="API token for MinerU")
+    use_markitdown: Optional[bool] = Field(None, description="Whether to use MarkItDown")
+
 
 router = APIRouter()
 

aperag/schema/view_models.py

@@ -72,12 +72,6 @@ class FailResponse(BaseModel):
 # keep resolving the same class objects.
 
 
-class Settings(BaseModel):
-    use_mineru: Optional[bool] = Field(None, description="Whether to use MinerU")
-    mineru_api_token: Optional[str] = Field(None, description="API token for MinerU")
-    use_markitdown: Optional[bool] = Field(None, description="Whether to use MarkItDown")
-
-
 class ParserHealthItem(BaseModel):
     key: str
     label: str

docs/modularization/cleanup-inventory.md

@@ -196,7 +196,7 @@ marketplace.py / marketplace_collections.py / providers_v2.py / __init__.py →
 | `aperag/views/openai.py` | 83 | **迁到** `aperag/domains/conversation/api/openai_routes.py`（OpenAI-compat 归 conversation），挂 `/v1/chat/completions` 保留 |
 | `aperag/views/prompts.py` | 205 | **迁到** `aperag/domains/model_platform/api/prompt_routes.py`，挂 `/api/v1/user-prompts` 保留 |
 | `aperag/views/quota.py` | 234 | **迁到** `aperag/domains/governance/api/quota_routes.py`，挂 `/api/v1/quota` 保留 |
-| `aperag/views/settings.py` | 67 | **迁到** `aperag/domains/knowledge_base/api/settings_routes.py`（parser health），挂 `/api/v1/settings` 保留 |
+| ~~`aperag/views/settings.py`~~ | ~~67~~ | ✅ Phase 8 #48 (G2) **DONE** — carved to `aperag/domains/knowledge_base/api/settings_routes.py`, hard-cut prefix `/api/v1/settings` → `/api/v2/settings` per D7-2 (msg=94f663f2 §3.2.2). Legacy file deleted. |
 | `aperag/views/test.py` | 60 | **dev-only**；**直接 rm** 或迁 `tests/fixtures/`（PM 决定） |
 | `aperag/views/utils.py` | 134 | `auth.py` + `config.py` 依赖；**随它们迁到 identity 域 `_utils.py`**，然后 rm |
 | `aperag/views/chat_documents.py` | 21 | 空 stub，app.py 未 mount；**直接 rm** |

tests/unit_test/test_modularization_boundaries.py

@@ -358,6 +358,29 @@ def test_aperag_domains_never_import_legacy_auth_view_dependencies():
     )
 
 
+def test_no_module_imports_legacy_views_settings():
+    """Phase 8 #48 (G2): ``aperag/views/settings.py`` was carved into
+    ``aperag.domains.knowledge_base.api.settings_routes`` and the legacy
+    file is gone. No code anywhere in ``aperag/`` may import from the
+    deleted module — the new home is the canonical owner.
+    """
+    offenders: list[str] = []
+    aperag_root = REPO_ROOT / "aperag"
+    for path in aperag_root.rglob("*.py"):
+        if not path.is_file():
+            continue
+        modules = _imported_modules(path.read_text())
+        if "aperag.views.settings" in modules:
+            offenders.append(f"{path.relative_to(REPO_ROOT).as_posix()} imports aperag.views.settings")
+
+    assert not offenders, (
+        "`aperag.views.settings` was deleted in Phase 8 task #48 (G2). "
+        "Import the carved router or service from "
+        "`aperag.domains.knowledge_base.api.settings_routes` instead. "
+        "Offenders:\n  " + "\n  ".join(sorted(offenders))
+    )
+
+
 # ---------- Retrieval <-> knowledge_graph one-way bridge ----------