From 89917a7baf8a56a111d84459841dc98f0b7435d6 Mon Sep 17 00:00:00 2001 From: yanjunpu <541726449@qq.com> Date: Wed, 9 Sep 2026 16:54:35 +0800 Subject: [PATCH] docs: classify music library status route --- docs/architecture/agent-api-surface-audit.json | 16 ++++++++++++++-- docs/architecture/agent-api-surface-audit.md | 5 +++-- scripts/generate_agent_api_surface_audit.py | 8 ++++++++ tests/test_music_endpoint.py | 4 ++++ 4 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/architecture/agent-api-surface-audit.json b/docs/architecture/agent-api-surface-audit.json index 36ca0d94c..d1c23e961 100644 --- a/docs/architecture/agent-api-surface-audit.json +++ b/docs/architecture/agent-api-surface-audit.json @@ -6,7 +6,7 @@ "provider-skill": 12, "stream_or_binary": 10, "transport_or_identity": 66, - "ui_presentation": 22 + "ui_presentation": 23 }, "dynamic_gateway_routes": [ { @@ -21,7 +21,7 @@ "gateway_http_route_count": 203, "gateway_operation_count": 205, "matched_gateway_http_route_count": 202, - "openapi_operation_count": 395, + "openapi_operation_count": 396, "operations": [ { "disposition": "consolidated", @@ -1894,6 +1894,18 @@ "music" ] }, + { + "disposition": "ui_presentation", + "method": "POST", + "operation_ids": [], + "owner": "host-ui", + "path": "/api/v1/music/library/status", + "reason": "Batch music-library presence is a bounded projection for the authenticated artist resource matrix; it is not a standalone Agent business action.", + "summary": "批量查询音乐专辑入库状态", + "tags": [ + "music" + ] + }, { "disposition": "gateway", "method": "POST", diff --git a/docs/architecture/agent-api-surface-audit.md b/docs/architecture/agent-api-surface-audit.md index 22f6cd5f5..35982d7a7 100644 --- a/docs/architecture/agent-api-surface-audit.md +++ b/docs/architecture/agent-api-surface-audit.md @@ -5,7 +5,7 @@ ## Result -- OpenAPI HTTP operations: **395** +- OpenAPI HTTP operations: **396** - Stable `moviepilot_api` operations: **205** - Exact HTTP routes used by the gateway: **203** - OpenAPI routes matched directly by the gateway: **202** @@ -23,7 +23,7 @@ | `provider-skill` | 12 | Low-level downloader or media-server capability owned by a provider Skill. | | `stream_or_binary` | 10 | Streaming or binary response owned by a direct client transport. | | `transport_or_identity` | 66 | Authentication, protocol, callback, account, or conversation transport boundary. | -| `ui_presentation` | 22 | Frontend or plugin-rendered presentation contract. | +| `ui_presentation` | 23 | Frontend or plugin-rendered presentation contract. | ## Bounded Dynamic Routes @@ -183,6 +183,7 @@ | `GET` | `/api/v1/music/cache` | music | `gateway` | music.cache.get | 查询音乐识别缓存 | | `DELETE` | `/api/v1/music/cache/{cache_key}` | music | `gateway` | music.cache.delete | 删除指定音乐识别缓存 | | `GET` | `/api/v1/music/explore` | music | `gateway` | music.explore | 探索音乐 | +| `POST` | `/api/v1/music/library/status` | music | `ui_presentation` | host-ui | 批量查询音乐专辑入库状态 | | `POST` | `/api/v1/music/recognize` | music | `gateway` | music.recognize | 识别音乐元数据详情 | | `POST` | `/api/v1/notification/config` | notification | `transport_or_identity` | host-runtime | 保存通知渠道并同步登录缓存 | | `POST` | `/api/v1/notification/manage` | notification | `transport_or_identity` | host-runtime | 通知渠道统一管理 | diff --git a/scripts/generate_agent_api_surface_audit.py b/scripts/generate_agent_api_surface_audit.py index 390e9e723..c095256d9 100644 --- a/scripts/generate_agent_api_surface_audit.py +++ b/scripts/generate_agent_api_surface_audit.py @@ -112,6 +112,7 @@ EXPLICIT_TRANSPORT_PATHS = frozenset( ) SUBSCRIPTION_EXECUTION_UI_PREFIX = "/api/v1/subscribe/execution/" CLASSIFICATION_POLICY_UI_PREFIX = "/api/v1/media/classification/" +MUSIC_LIBRARY_STATUS_UI_PATH = "/api/v1/music/library/status" def _gateway_routes() -> dict[tuple[str, str], list[str]]: @@ -196,6 +197,13 @@ def _classify( "Classification policy authoring, validation, preview, impact analysis, and publication are owned by the authenticated frontend editor until a stable Agent governance contract is approved.", [], ) + if method == "POST" and path == MUSIC_LIBRARY_STATUS_UI_PATH: + return ( + "ui_presentation", + "host-ui", + "Batch music-library presence is a bounded projection for the authenticated artist resource matrix; it is not a standalone Agent business action.", + [], + ) if path in EXPLICIT_TRANSPORT_PATHS: return ( "transport_or_identity", diff --git a/tests/test_music_endpoint.py b/tests/test_music_endpoint.py index e916f9bdb..128af59e7 100644 --- a/tests/test_music_endpoint.py +++ b/tests/test_music_endpoint.py @@ -132,6 +132,8 @@ def test_media_search_forwards_explicit_music_source(): def test_recognize_music_returns_detail(): """音乐识别接口应按来源和 ID 经统一识别入口返回详情。""" + from app.chain.media import MediaChain + chain = Mock() chain.async_recognize_media = AsyncMock( return_value=MusicInfo( @@ -164,6 +166,8 @@ def test_recognize_music_returns_detail(): def test_recognize_music_returns_404_for_unknown_item(): """音乐详情不存在时接口应返回 404。""" + from app.chain.media import MediaChain + chain = Mock() chain.async_recognize_media = AsyncMock(return_value=None)