From 4c22966ed3531248f513d08a37070d328cd36afb Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Mon, 6 Jul 2026 04:21:50 +0800 Subject: [PATCH] =?UTF-8?q?S118=20=E6=8E=A5=E5=8F=A3=E5=A5=91=E7=BA=A6?= =?UTF-8?q?=E5=AF=BC=E5=87=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/route_registry.py | 1 + backend/routes/contract_routes.py | 23 ++++++++++++++++ backend/services/contract_service.py | 30 +++++++++++++++++++++ main.py | 1 + tests/test_contract_service.py | 39 ++++++++++++++++++++++++++++ tests/test_plugin_entrypoint.py | 1 + tests/test_route_registry.py | 1 + 7 files changed, 96 insertions(+) create mode 100644 backend/routes/contract_routes.py create mode 100644 backend/services/contract_service.py create mode 100644 tests/test_contract_service.py diff --git a/backend/route_registry.py b/backend/route_registry.py index 5a583a4..694e4d4 100644 --- a/backend/route_registry.py +++ b/backend/route_registry.py @@ -45,6 +45,7 @@ class RouteSpec: ROUTES: tuple[RouteSpec, ...] = ( RouteSpec("GET", "ui/bootstrap", "backend.routes.ui_routes.get_ui_bootstrap", "read"), RouteSpec("GET", "ui/actions", "backend.routes.ui_routes.get_ui_actions", "read"), + RouteSpec("GET", "contract", "backend.routes.contract_routes.get_api_contract", "read"), RouteSpec("GET", "dashboard/summary", "backend.routes.dashboard_routes.get_dashboard_summary", "read"), RouteSpec("GET", "profiles", "backend.routes.profile_routes.list_profiles", "read"), RouteSpec("POST", "profiles", "backend.routes.profile_routes.create_profile", "write"), diff --git a/backend/routes/contract_routes.py b/backend/routes/contract_routes.py new file mode 100644 index 0000000..89506b4 --- /dev/null +++ b/backend/routes/contract_routes.py @@ -0,0 +1,23 @@ +"""API contract route handlers.""" + +from __future__ import annotations + +from typing import Any + +from backend.routes.common import handle_request +from backend.services.contract_service import ContractService +from core.identity import RequestContext +from core.security import require_authenticated + + +def get_api_contract( + ctx: RequestContext, + service: ContractService | None = None, +) -> dict: + contract_service = service or ContractService() + + def action() -> dict[str, Any]: + require_authenticated(ctx) + return contract_service.get_contract() + + return handle_request(ctx, action) diff --git a/backend/services/contract_service.py b/backend/services/contract_service.py new file mode 100644 index 0000000..9bbafff --- /dev/null +++ b/backend/services/contract_service.py @@ -0,0 +1,30 @@ +"""Backend API contract export.""" + +from __future__ import annotations + +from typing import Any + +from backend.dto.common import ErrorCode +from backend.route_registry import permission_matrix, route_manifest +from backend.services.ui_service import API_BASE + + +class ContractService: + def get_contract(self) -> dict[str, Any]: + return { + "contract_version": "3.0", + "api_base": API_BASE, + "routes": route_manifest(), + "permissions": permission_matrix(), + "error_codes": [code.value for code in ErrorCode], + "response_shape": { + "success": {"ok": True, "data": {}, "warnings": [], "request_id": "req_..."}, + "error": { + "ok": False, + "error_code": ErrorCode.VALIDATION_FAILED.value, + "message": "error message", + "details": {}, + "request_id": "req_...", + }, + }, + } diff --git a/main.py b/main.py index 47c2e40..4989126 100644 --- a/main.py +++ b/main.py @@ -29,6 +29,7 @@ def get_plugin_manifest() -> dict[str, Any]: return { "plugin_name": PLUGIN_NAME, "api_base": API_BASE, + "contract_url": f"{API_BASE}/contract", "web": web_manifest, "routes": runtime_route_table(), "runtime": runtime, diff --git a/tests/test_contract_service.py b/tests/test_contract_service.py new file mode 100644 index 0000000..80a09ee --- /dev/null +++ b/tests/test_contract_service.py @@ -0,0 +1,39 @@ +from __future__ import annotations + +import unittest + +from backend.dto.common import ErrorCode +from backend.route_registry import ROUTES +from backend.routes.contract_routes import get_api_contract +from backend.services.contract_service import ContractService +from core.identity import RequestContext + + +class ContractServiceTests(unittest.TestCase): + def test_contract_exports_routes_permissions_and_error_codes(self): + contract = ContractService().get_contract() + + self.assertEqual(contract["contract_version"], "3.0") + self.assertTrue(contract["api_base"].endswith("astrbot_plugin_imagestudio")) + self.assertEqual(len(contract["routes"]), len(ROUTES)) + self.assertIn("VALIDATION_FAILED", contract["error_codes"]) + self.assertEqual(set(contract["error_codes"]), {code.value for code in ErrorCode}) + self.assertTrue(all("auth_required" in route for route in contract["routes"])) + self.assertTrue(any(item["permission"] == "config" for item in contract["permissions"])) + self.assertEqual(contract["response_shape"]["success"]["ok"], True) + self.assertEqual(contract["response_shape"]["error"]["ok"], False) + + def test_contract_route_requires_authentication(self): + ctx = RequestContext.from_astrbot(username="admin", user_id="user_001") + + response = get_api_contract(ctx, ContractService()) + anonymous = get_api_contract(RequestContext(), ContractService()) + + self.assertTrue(response["ok"]) + self.assertEqual(response["data"]["contract_version"], "3.0") + self.assertFalse(anonymous["ok"]) + self.assertEqual(anonymous["error_code"], "UNAUTHORIZED") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_plugin_entrypoint.py b/tests/test_plugin_entrypoint.py index 7bd8936..7ab0f61 100644 --- a/tests/test_plugin_entrypoint.py +++ b/tests/test_plugin_entrypoint.py @@ -13,6 +13,7 @@ class PluginEntrypointTests(unittest.TestCase): self.assertEqual(manifest["plugin_name"], PLUGIN_NAME) self.assertTrue(manifest["api_base"].endswith("astrbot_plugin_imagestudio")) + self.assertTrue(manifest["contract_url"].endswith("/contract")) self.assertIn("web", manifest) self.assertTrue(any(route["endpoint"] == "dashboard/summary" for route in manifest["routes"])) self.assertTrue(manifest["runtime"]["health"]["ok"]) diff --git a/tests/test_route_registry.py b/tests/test_route_registry.py index 3759f83..8a88cb3 100644 --- a/tests/test_route_registry.py +++ b/tests/test_route_registry.py @@ -28,6 +28,7 @@ class RouteRegistryTests(unittest.TestCase): self.assertIn(("GET", "ui/bootstrap"), keys) self.assertIn(("GET", "ui/actions"), keys) + self.assertIn(("GET", "contract"), keys) self.assertIn(("POST", "nodes/{node_id}/generate"), keys) self.assertIn(("POST", "profiles/quick-draft/save"), keys) self.assertIn(("GET", "security/audit-logs"), keys)