S118 接口契约导出

这个提交存在于:
YokiiroBW 2026-07-06 04:21:50 +08:00
父节点 a1916f9955
当前提交 4c22966ed3
共有 7 个文件被更改,包括 96 次插入 和 0 次删除

查看文件

@ -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"),

查看文件

@ -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)

查看文件

@ -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_...",
},
},
}

查看文件

@ -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,

查看文件

@ -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()

查看文件

@ -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"])

查看文件

@ -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)