Kris
ddafd95ff0
1. 移除多个导出接口的显式response_model声明 2. 调整access_rule和test_case的创建接口位置，修复静态路径冲突 3. 优化适配器配置校验的异常处理逻辑 4. 重构集成路由的查询逻辑，统一使用get_integration_or_raise 5. 新增channels路由组下的capability、reports、dashboard、webhook、wizard、doctor、directory、session共8个子路由模块 6. 注册channels_router到全局路由列表
249 lines
10 KiB
Python
249 lines
10 KiB
Python
"""目录查询域 Router（FR-14，DIR-QUERY-01~04 + DIR-01 + DIR-CACHE-CLEAR）。
|
||
|
||
本 router 实现渠道通讯录目录查询的全部 HTTP 端点，覆盖用户搜索 / 群组搜索 /
|
||
用户资料 / 群组详情 / 群组成员 / 缓存清理共 6 个操作。所有端点统一采用模板 A
|
||
（控制面端口路由），通过 ``get_channel_use_cases`` 装配 ``ChannelUseCases``，
|
||
经 ``directory`` 端口调用类型化方法，由 ``ChannelControlService._executeControl``
|
||
内部走控制面管道（auth → permission → rate_limit → dispatch → audit）。
|
||
|
||
鉴权策略：全部端点使用 ``get_admin_user`` 依赖，要求管理员或超级管理员角色。
|
||
角色校验由依赖函数完成，router 内不做角色判断（规范 §4）。
|
||
|
||
路径设计：静态后缀路径（``/search``）先于动态单段路径（``/{peer_id}`` /
|
||
``/{group_id}``）声明，动态单段先于多段子资源路径（``/{group_id}/members``）
|
||
声明（规范 §6.5），避免静态路径被动态参数捕获。子 router 不自行设置 prefix，
|
||
根前缀 ``/channels`` 由 ``channels_router`` 聚合 router 统一追加。
|
||
|
||
端点清单（对应《05-目录查询域设计方案 v1.1》§2.3）：
|
||
- GET /{channel_type}/{account_id}/directory/users/search DIR-QUERY-01 search_directory_users
|
||
- GET /{channel_type}/{account_id}/directory/groups/search DIR-QUERY-02 search_directory_groups
|
||
- GET /{channel_type}/{account_id}/directory/users/{peer_id} DIR-QUERY-03 get_directory_user_profile
|
||
- GET /{channel_type}/{account_id}/directory/groups/{group_id} DIR-01 get_directory_group_detail
|
||
- GET /{channel_type}/{account_id}/directory/groups/{group_id}/members DIR-QUERY-04 get_directory_group_members
|
||
- DELETE /{channel_type}/{account_id}/directory/cache DIR-CACHE-CLEAR clear_directory_cache
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Any
|
||
|
||
from fastapi import APIRouter, Depends, Query, Request
|
||
|
||
from yuxi.channels.contract.dtos.channel import ChannelType
|
||
from yuxi.channels.contract.dtos.directory import ClearDirectoryCacheCmd, DirectoryQuery
|
||
from yuxi.storage.postgres.models_business import User
|
||
|
||
from server.routers.channels import (
|
||
build_operator,
|
||
get_channel_use_cases,
|
||
raiseOnControlFailure,
|
||
serialize_control_data,
|
||
)
|
||
from server.utils.auth_middleware import get_admin_user
|
||
|
||
directory_router = APIRouter(tags=["channels-directory"])
|
||
|
||
|
||
# ---------------- Endpoints ----------------
|
||
|
||
|
||
@directory_router.get(
|
||
"/{channel_type}/{account_id}/directory/users/search",
|
||
response_model=dict,
|
||
)
|
||
async def search_directory_users(
|
||
channel_type: ChannelType,
|
||
account_id: str,
|
||
request: Request,
|
||
keyword: str | None = Query(default=None, description="搜索关键词"),
|
||
cursor: str | None = Query(default=None, description="游标分页标记"),
|
||
limit: int = Query(default=20, ge=1, le=100, description="分页大小"),
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""搜索渠道用户目录（FR-14，DIR-QUERY-01）。
|
||
|
||
5min TTL 缓存。渠道未注册目录适配器或目录开关关闭返回 501。
|
||
对应控制面操作 ``directory/users``（由 ``ChannelControlService.searchDirectoryUsers``
|
||
内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
query = DirectoryQuery(keyword=keyword, cursor=cursor, limit=limit)
|
||
result = await use_cases.directory.searchDirectoryUsers(
|
||
channel_type=channel_type,
|
||
account_id=account_id,
|
||
query=query,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@directory_router.get(
|
||
"/{channel_type}/{account_id}/directory/groups/search",
|
||
response_model=dict,
|
||
)
|
||
async def search_directory_groups(
|
||
channel_type: ChannelType,
|
||
account_id: str,
|
||
request: Request,
|
||
keyword: str | None = Query(default=None, description="搜索关键词"),
|
||
cursor: str | None = Query(default=None, description="游标分页标记"),
|
||
limit: int = Query(default=20, ge=1, le=100, description="分页大小"),
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""搜索渠道群组目录（FR-14，DIR-QUERY-02）。
|
||
|
||
5min TTL 缓存。对应控制面操作 ``directory/groups``（由
|
||
``ChannelControlService.searchDirectoryGroups`` 内部构造 ``ControlCmd``
|
||
并委托 ``_executeControl`` 执行控制面管道）。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
query = DirectoryQuery(keyword=keyword, cursor=cursor, limit=limit)
|
||
result = await use_cases.directory.searchDirectoryGroups(
|
||
channel_type=channel_type,
|
||
account_id=account_id,
|
||
query=query,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@directory_router.get(
|
||
"/{channel_type}/{account_id}/directory/users/{peer_id}",
|
||
response_model=dict,
|
||
)
|
||
async def get_directory_user_profile(
|
||
channel_type: ChannelType,
|
||
account_id: str,
|
||
peer_id: str,
|
||
request: Request,
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""查询渠道用户资料（FR-14，DIR-QUERY-03）。
|
||
|
||
按对端 ID 查询。5min TTL 缓存。对应控制面操作 ``directory/user_profile``
|
||
（由 ``ChannelControlService.getDirectoryUserProfile`` 内部构造
|
||
``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
|
||
协议翻译：HTTP 路径参数 ``peer_id`` 映射为用例方法 ``user_id`` 入参，
|
||
以对齐 ``DirectoryPort.getDirectoryUserProfile`` 的契约命名。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
result = await use_cases.directory.getDirectoryUserProfile(
|
||
channel_type=channel_type,
|
||
account_id=account_id,
|
||
user_id=peer_id,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@directory_router.get(
|
||
"/{channel_type}/{account_id}/directory/groups/{group_id}",
|
||
response_model=dict,
|
||
)
|
||
async def get_directory_group_detail(
|
||
channel_type: ChannelType,
|
||
account_id: str,
|
||
group_id: str,
|
||
request: Request,
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""查询渠道群组详情（FR-14，DIR-01）。
|
||
|
||
按 group_id 查询。5min TTL 缓存。对应控制面操作 ``directory/group_detail``
|
||
（由 ``ChannelControlService.getDirectoryGroupDetail`` 内部构造
|
||
``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
result = await use_cases.directory.getDirectoryGroupDetail(
|
||
channel_type=channel_type,
|
||
account_id=account_id,
|
||
group_id=group_id,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@directory_router.get(
|
||
"/{channel_type}/{account_id}/directory/groups/{group_id}/members",
|
||
response_model=dict,
|
||
)
|
||
async def get_directory_group_members(
|
||
channel_type: ChannelType,
|
||
account_id: str,
|
||
group_id: str,
|
||
request: Request,
|
||
cursor: str | None = Query(default=None, description="游标分页标记"),
|
||
limit: int = Query(default=20, ge=1, le=100, description="分页大小"),
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""查询渠道群组成员（FR-14，DIR-QUERY-04）。
|
||
|
||
5min TTL 缓存。对应控制面操作 ``directory/group_members``（由
|
||
``ChannelControlService.getDirectoryGroupMembers`` 内部构造 ``ControlCmd``
|
||
并委托 ``_executeControl`` 执行控制面管道）。
|
||
|
||
分页参数仅含 ``cursor`` 与 ``limit``，构造 ``DirectoryQuery`` 时不传
|
||
``keyword``（群组成员查询无关键词语义）。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
query = DirectoryQuery(cursor=cursor, limit=limit)
|
||
result = await use_cases.directory.getDirectoryGroupMembers(
|
||
channel_type=channel_type,
|
||
account_id=account_id,
|
||
group_id=group_id,
|
||
query=query,
|
||
operator=operator,
|
||
)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|
||
|
||
|
||
@directory_router.delete(
|
||
"/{channel_type}/{account_id}/directory/cache",
|
||
response_model=dict,
|
||
)
|
||
async def clear_directory_cache(
|
||
channel_type: ChannelType,
|
||
account_id: str,
|
||
request: Request,
|
||
scope: str = Query(
|
||
default="all",
|
||
description="清理范围：users / groups / all（默认 all）",
|
||
),
|
||
use_cases=Depends(get_channel_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""清理目录缓存（DIR-CACHE-CLEAR）。
|
||
|
||
对应控制面操作 ``directory/cache_clear``（由
|
||
``ChannelControlService.clearDirectoryCache`` 内部构造 ``ControlCmd``
|
||
并委托 ``_executeControl`` 执行控制面管道）。清理指定渠道账户的目录
|
||
查询缓存（用户 / 群组 / 全部），供管理员在渠道侧数据变更后手动刷新
|
||
缓存。编排链路：HTTP 入参 → ``build_operator`` 构造操作人 → 构造
|
||
``ClearDirectoryCacheCmd`` → ``use_cases.directory.clearDirectoryCache``
|
||
调用端口方法 → 控制面管道检查适配器是否实现 ``clearCache`` → 调用
|
||
适配器清理 + ``CachePort`` 失效本地缓存 → ``ControlResult`` 经
|
||
``raiseOnControlFailure`` 转译失败 → ``serialize_control_data`` 序列化
|
||
清理结果返回。适配器未实现 ``clearCache`` 时返回 501。
|
||
"""
|
||
operator = build_operator(current_user, request)
|
||
cmd = ClearDirectoryCacheCmd(
|
||
channel_type=channel_type,
|
||
account_id=account_id,
|
||
operator=operator,
|
||
scope=scope,
|
||
)
|
||
result = await use_cases.directory.clearDirectoryCache(cmd)
|
||
raiseOnControlFailure(result)
|
||
return {"success": True, "data": serialize_control_data(result.data)}
|