@kernel-sig/console 0.1.0

package/backend/app/api/v1/ai.py

@@ -0,0 +1,386 @@
+"""AI 配置与分析 API。
+
+模型端点是全局配置（一个部署通常接一两家中转），因此不挂在仓库路径下；
+分析结果则按对象查询，因为维护者是"看着某个 PR 想要它的摘要"。
+"""
+
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query, status
+
+from app.api.deps import CurrentUserDep, SessionDep, SettingsDep, require_permission
+from app.core.exceptions import ConflictError, NotFoundError
+from app.core.permissions import Permission
+from app.models.ai import AITask, AnalysisStatus, LLMProvider, TaskRouting
+from app.models.classification import SubjectType
+from app.models.credential import CredentialKind
+from app.models.pull_request import PullRequest
+from app.schemas.ai import (
+    AIAnalysisRead,
+    AIUsage,
+    LLMProviderCreate,
+    LLMProviderRead,
+    LLMProviderUpdate,
+    ProviderTestResult,
+    TaskRoutingRead,
+    TaskRoutingUpsert,
+)
+from app.schemas.common import MessageResponse
+from app.services import ai_service, credential_service, repository_service
+
+router = APIRouter(tags=["ai"])
+
+ManageCredentials = Annotated[object, Depends(require_permission(Permission.MANAGE_CREDENTIALS))]
+ManagePrompts = Annotated[object, Depends(require_permission(Permission.MANAGE_PROMPTS))]
+Trigger = Annotated[object, Depends(require_permission(Permission.TRIGGER_ANALYSIS))]
+
+
+# ---------------------------------------------------------------------------
+# 模型端点
+# ---------------------------------------------------------------------------
+
+
+@router.get("/ai/providers", response_model=list[LLMProviderRead])
+async def list_providers(session: SessionDep, _: ManageCredentials) -> list[LLMProviderRead]:
+    """列出已配置的模型端点。
+
+    模型端点配置属于管理操作（涉及 API Key 与费用），因此与凭据同一权限；
+    普通使用者只看得到分析结果，看不到平台接了哪些模型。
+    响应里不含任何密钥材料，只有指向凭据表的 id。
+    """
+    providers = await ai_service.list_providers(session)
+    return [LLMProviderRead.model_validate(provider) for provider in providers]
+
+
+@router.post("/ai/providers", response_model=LLMProviderRead, status_code=status.HTTP_201_CREATED)
+async def create_provider(
+    payload: LLMProviderCreate,
+    session: SessionDep,
+    settings: SettingsDep,
+    user: CurrentUserDep,
+    _: ManageCredentials,
+) -> LLMProviderRead:
+    """新增模型端点。
+
+    API Key 走与 AtomGit token 相同的凭据表加密存储 ——
+    明文永不回显，接口只暴露指纹。
+    """
+    from sqlalchemy import select
+
+    existing = await session.scalar(select(LLMProvider).where(LLMProvider.name == payload.name))
+    if existing is not None:
+        raise ConflictError(f"模型端点 {payload.name} 已存在")
+
+    credential_id = None
+    if payload.api_key:
+        credential = await credential_service.create_credential(
+            session,
+            settings,
+            name=f"llm:{payload.name}",
+            kind=CredentialKind.LLM_API_KEY,
+            plaintext=payload.api_key,
+            meta={"provider": payload.name, "base_url": payload.base_url},
+            created_by=user.id,
+        )
+        credential_id = credential.id
+
+    provider = LLMProvider(
+        name=payload.name,
+        base_url=payload.base_url,
+        model=payload.model,
+        credential_id=credential_id,
+        temperature=payload.temperature,
+        max_tokens=payload.max_tokens,
+        timeout_seconds=payload.timeout_seconds,
+        is_default=payload.is_default,
+    )
+    session.add(provider)
+    await session.flush()
+
+    if payload.is_default:
+        await _clear_other_defaults(session, provider)
+
+    await session.commit()
+    return LLMProviderRead.model_validate(provider)
+
+
+async def _clear_other_defaults(session: SessionDep, keep: LLMProvider) -> None:
+    """默认端点只能有一个：多默认等于没有默认。"""
+    from sqlalchemy import update
+
+    await session.execute(
+        update(LLMProvider)
+        .where(LLMProvider.id != keep.id, LLMProvider.is_default.is_(True))
+        .values(is_default=False)
+    )
+    keep.is_default = True
+
+
+async def _require_provider(session: SessionDep, provider_id: uuid.UUID) -> LLMProvider:
+    provider = await ai_service.get_provider(session, provider_id)
+    if provider is None:
+        raise NotFoundError("模型端点不存在", resource="llm_provider", identifier=str(provider_id))
+    return provider
+
+
+@router.patch("/ai/providers/{provider_id}", response_model=LLMProviderRead)
+async def update_provider(
+    provider_id: uuid.UUID,
+    payload: LLMProviderUpdate,
+    session: SessionDep,
+    settings: SettingsDep,
+    _: ManageCredentials,
+) -> LLMProviderRead:
+    provider = await _require_provider(session, provider_id)
+
+    if payload.api_key is not None:
+        if provider.credential_id:
+            credential = await credential_service.require_credential(
+                session, provider.credential_id
+            )
+            await credential_service.update_credential_value(
+                session, settings, credential, payload.api_key
+            )
+        else:
+            credential = await credential_service.create_credential(
+                session,
+                settings,
+                name=f"llm:{provider.name}",
+                kind=CredentialKind.LLM_API_KEY,
+                plaintext=payload.api_key,
+                meta={"provider": provider.name, "base_url": provider.base_url},
+            )
+            provider.credential_id = credential.id
+
+    for field, value in payload.model_dump(exclude_unset=True, exclude={"api_key"}).items():
+        setattr(provider, field, value)
+
+    if payload.is_default:
+        await _clear_other_defaults(session, provider)
+
+    await session.commit()
+    return LLMProviderRead.model_validate(provider)
+
+
+@router.post("/ai/providers/{provider_id}/test", response_model=ProviderTestResult)
+async def test_provider(
+    provider_id: uuid.UUID,
+    session: SessionDep,
+    settings: SettingsDep,
+    _: ManageCredentials,
+) -> ProviderTestResult:
+    """实测端点连通性与凭据有效性。
+
+    配置模型时最容易错的是 base_url 少一段 /v1、模型名拼错、
+    以及 Key 与端点不配套 —— 只有真发一次请求才能确认。
+    """
+    provider = await _require_provider(session, provider_id)
+    result = await ai_service.test_provider(session, settings, provider)
+    await session.commit()
+    return ProviderTestResult(**result)
+
+
+@router.delete("/ai/providers/{provider_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_provider(
+    provider_id: uuid.UUID, session: SessionDep, _: ManageCredentials
+) -> None:
+    from sqlalchemy import func, select
+
+    provider = await _require_provider(session, provider_id)
+    in_use = await session.scalar(
+        select(func.count()).select_from(TaskRouting).where(TaskRouting.provider_id == provider_id)
+    )
+    if in_use:
+        raise ConflictError(f"该端点仍被 {in_use} 条任务路由引用，请先改路由")
+
+    credential_id = provider.credential_id
+    await session.delete(provider)
+    await session.flush()
+    if credential_id:
+        credential = await credential_service.get_credential(session, credential_id)
+        if credential is not None:
+            await credential_service.delete_credential(session, credential)
+    await session.commit()
+
+
+# ---------------------------------------------------------------------------
+# 任务路由
+# ---------------------------------------------------------------------------
+
+
+@router.get("/ai/routing", response_model=list[TaskRoutingRead])
+async def list_routing(session: SessionDep, _: CurrentUserDep) -> list[TaskRoutingRead]:
+    rows = await ai_service.list_routing(session)
+    return [TaskRoutingRead.model_validate(row) for row in rows]
+
+
+@router.put("/ai/routing/{task}", response_model=TaskRoutingRead)
+async def upsert_routing(
+    task: AITask,
+    payload: TaskRoutingUpsert,
+    session: SessionDep,
+    _: ManagePrompts,
+) -> TaskRoutingRead:
+    """为某类任务指定模型。
+
+    按任务分开配置是刻意的：分类这类轻任务用便宜模型就够，
+    代码风险审查才值得用强模型。全部走大模型会让成本失控。
+    """
+    from sqlalchemy import select
+
+    await _require_provider(session, payload.provider_id)
+    if payload.fallback_provider_id:
+        await _require_provider(session, payload.fallback_provider_id)
+
+    routing = await session.scalar(select(TaskRouting).where(TaskRouting.task == task))
+    if routing is None:
+        routing = TaskRouting(task=task, provider_id=payload.provider_id)
+        session.add(routing)
+
+    routing.provider_id = payload.provider_id
+    routing.fallback_provider_id = payload.fallback_provider_id
+    routing.system_prompt = payload.system_prompt
+    routing.enabled = payload.enabled
+    await session.flush()
+    await session.commit()
+    return TaskRoutingRead.model_validate(routing)
+
+
+@router.delete("/ai/routing/{task}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_routing(task: AITask, session: SessionDep, _: ManagePrompts) -> None:
+    """删除路由后该任务回落到默认端点。"""
+    from sqlalchemy import delete, select
+
+    routing = await session.scalar(select(TaskRouting).where(TaskRouting.task == task))
+    if routing is None:
+        raise NotFoundError("该任务未配置路由", resource="task_routing", identifier=task.value)
+    await session.execute(delete(TaskRouting).where(TaskRouting.task == task))
+    await session.commit()
+
+
+# ---------------------------------------------------------------------------
+# 分析
+# ---------------------------------------------------------------------------
+
+
+@router.get("/ai/analyses/{subject_type}/{subject_id}", response_model=list[AIAnalysisRead])
+async def list_analyses(
+    subject_type: SubjectType,
+    subject_id: uuid.UUID,
+    session: SessionDep,
+    _: CurrentUserDep,
+) -> list[AIAnalysisRead]:
+    """某个 PR/Issue 的全部分析结果。
+
+    raw_response 不在此返回 —— 它是排查用的原始文本，体积大且对使用者无意义，
+    需要时直接查库。
+    """
+    rows = await ai_service.list_analyses(session, subject_type, subject_id)
+    return [AIAnalysisRead.model_validate(row) for row in rows]
+
+
+@router.post("/pulls/{pull_id}/ai/analyze", response_model=AIAnalysisRead)
+async def analyze_pull(
+    pull_id: uuid.UUID,
+    session: SessionDep,
+    settings: SettingsDep,
+    user: CurrentUserDep,
+    _: Trigger,
+    task: Annotated[AITask, Query()] = AITask.SUMMARIZE,
+    force: Annotated[bool, Query(description="绕过幂等检查，重新调用模型")] = False,
+) -> AIAnalysisRead:
+    """对单个 PR 触发一次分析。
+
+    同步执行而非入队：这是用户点了按钮在等结果的场景，
+    排队到 worker 反而让等待时间不可预期。单条分析通常几秒到几十秒。
+    """
+    pull = await session.get(PullRequest, pull_id)
+    if pull is None:
+        raise NotFoundError("PR 不存在", resource="pull_request", identifier=str(pull_id))
+
+    repository = await repository_service.require_repository(session, pull.repository_id)
+    target = await ai_service.build_target(session, task=task, pull=pull)
+    analysis = await ai_service.execute(
+        session, settings, repository, target, triggered_by=user.id, force=force
+    )
+
+    # 分类任务的结果要写回分类表，否则"分析了但没生效"
+    if task is AITask.CLASSIFY and analysis.result:
+        from app.services import classification_service
+
+        await classification_service.apply_ai_result(
+            session,
+            repository_id=repository.id,
+            subject_type=SubjectType.PULL_REQUEST,
+            subject_id=pull.id,
+            kind=str(analysis.result.get("kind", "unknown")),
+            subsystem=analysis.result.get("subsystem"),
+            confidence=float(analysis.result.get("confidence") or 0.0),
+            reason=analysis.result.get("reason"),
+        )
+
+    await session.commit()
+    return AIAnalysisRead.model_validate(analysis)
+
+
+@router.get("/ai/usage", response_model=AIUsage)
+async def usage(
+    session: SessionDep,
+    _: CurrentUserDep,
+    repository_id: uuid.UUID | None = None,
+    days: Annotated[int, Query(ge=1, le=365)] = 30,
+) -> AIUsage:
+    """模型用量。这是唯一按次计费的开销，必须能被直接看到。"""
+    return AIUsage(
+        **await ai_service.usage_stats(session, repository_id=repository_id, since_days=days)
+    )
+
+
+@router.get("/ai/tasks", response_model=list[str])
+async def task_catalog(_: CurrentUserDep) -> list[str]:
+    """可选任务清单。让前端不必硬编码任务名。"""
+    return [task.value for task in AITask]
+
+
+@router.post("/repositories/{repository_id}/ai/classify-missing")
+async def classify_missing(
+    repository_id: uuid.UUID,
+    session: SessionDep,
+    settings: SettingsDep,
+    _: Trigger,
+    limit: Annotated[int, Query(ge=1, le=50)] = 5,
+) -> MessageResponse:
+    """用模型补判规则判不出来的分类。
+
+    限流是刻意的：这是按次计费的操作，一次请求批量跑几十条会让
+    一次误点产生难以预期的账单。
+    """
+    from app.services import classification_service
+
+    repository = await repository_service.require_repository(session, repository_id)
+
+    # 先确认有可用模型再挑目标：否则会挑出一批、逐个失败，
+    # 返回一句"已补判 0/5 条"，使用者从中看不出是没配模型还是模型出错
+    await ai_service.resolve_provider(session, AITask.CLASSIFY)
+
+    targets = await classification_service.pulls_missing_classification(
+        session, repository.id, limit=limit
+    )
+    if not targets:
+        return MessageResponse(message="没有需要模型补判的条目")
+
+    succeeded = 0
+    failures: list[str] = []
+    for pull in targets:
+        analysis = await ai_service.classify_subject(session, settings, repository, pull=pull)
+        if analysis.status is AnalysisStatus.SUCCEEDED:
+            succeeded += 1
+        elif analysis.error:
+            failures.append(f"#{pull.number}: {analysis.error}")
+
+    await session.commit()
+    message = f"已补判 {succeeded}/{len(targets)} 条"
+    if failures:
+        message += f"；失败原因示例：{failures[0]}"
+    return MessageResponse(message=message)

package/backend/app/api/v1/analytics.py

@@ -0,0 +1,48 @@
+"""统计分析 API。"""
+
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+
+from app.api.deps import CurrentUserDep, SessionDep
+from app.services import analytics_service, repository_service
+
+router = APIRouter(tags=["analytics"])
+
+
+@router.get("/repositories/{repository_id}/analytics/summary")
+async def repository_summary(
+    repository_id: uuid.UUID, session: SessionDep, _: CurrentUserDep
+) -> dict:
+    """一次性返回仪表盘所需的全部指标。
+
+    刻意做成单个端点而非多个细粒度端点：仪表盘首屏需要全部数据，
+    拆成 8 个请求会让首屏从 1 次往返变成 8 次。
+    """
+    repository = await repository_service.require_repository(session, repository_id)
+    return await analytics_service.repository_summary(session, repository)
+
+
+@router.get("/repositories/{repository_id}/analytics/reviewers")
+async def reviewer_workload(
+    repository_id: uuid.UUID,
+    session: SessionDep,
+    _: CurrentUserDep,
+    days: Annotated[int, Query(ge=1, le=365)] = 90,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+) -> list[dict]:
+    """评审人工作量排行。
+
+    数据来自评论派生的评审事件 —— 评审人身份只存在于评论中，
+    标签给出的是汇总结果。
+    """
+    await repository_service.require_repository(session, repository_id)
+    return await analytics_service.reviewer_workload(session, repository_id, days=days, limit=limit)
+
+
+@router.get("/repositories/{repository_id}/analytics/waiting")
+async def waiting_stats(repository_id: uuid.UUID, session: SessionDep, _: CurrentUserDep) -> dict:
+    """待评审 PR 的等待时长分布，含 30 天以上积压量。"""
+    await repository_service.require_repository(session, repository_id)
+    return await analytics_service.waiting_time_stats(session, repository_id)

package/backend/app/api/v1/attention.py

@@ -0,0 +1,142 @@
+"""关注项 API。
+
+维护者日常的入口就是这个队列：几百条待办按严重程度排好，
+点开能看到"为什么被判定为超期"，认领后不再重复提示。
+"""
+
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+
+from app.api.deps import CurrentUserDep, SessionDep, require_permission
+from app.core.exceptions import NotFoundError
+from app.core.permissions import Permission
+from app.domain.attention import RULE_DESCRIPTIONS, Rule
+from app.models.attention import AttentionItem, AttentionRule, AttentionSeverity
+from app.models.classification import SubjectType
+from app.schemas.attention import AttentionCounts, AttentionItemRead, RuleDescription
+from app.schemas.common import Page
+from app.services import attention_service, repository_service
+
+router = APIRouter(tags=["attention"])
+
+Classify = Annotated[object, Depends(require_permission(Permission.CLASSIFY))]
+
+
+@router.get("/repositories/{repository_id}/attention", response_model=Page[AttentionItemRead])
+async def list_attention(
+    repository_id: uuid.UUID,
+    session: SessionDep,
+    _: CurrentUserDep,
+    severity: Annotated[list[AttentionSeverity] | None, Query()] = None,
+    rule: Annotated[list[AttentionRule] | None, Query()] = None,
+    subject_type: SubjectType | None = None,
+    include_resolved: bool = False,
+    unacknowledged_only: bool = False,
+    page: Annotated[int, Query(ge=1)] = 1,
+    per_page: Annotated[int, Query(ge=1, le=200)] = 50,
+) -> Page[AttentionItemRead]:
+    await repository_service.require_repository(session, repository_id)
+    rows, total = await attention_service.list_items(
+        session,
+        repository_id=repository_id,
+        severities=severity or (),
+        rules=rule or (),
+        subject_type=subject_type,
+        include_resolved=include_resolved,
+        unacknowledged_only=unacknowledged_only,
+        limit=per_page,
+        offset=(page - 1) * per_page,
+    )
+    return Page.create(
+        [AttentionItemRead.model_validate(row) for row in rows], total, page, per_page
+    )
+
+
+@router.get("/repositories/{repository_id}/attention/counts", response_model=AttentionCounts)
+async def attention_counts(
+    repository_id: uuid.UUID, session: SessionDep, _: CurrentUserDep
+) -> AttentionCounts:
+    """未解决项的分布。顶部筛选栏与仪表盘共用这一个端点。"""
+    await repository_service.require_repository(session, repository_id)
+    by_severity = await attention_service.severity_counts(session, repository_id)
+    by_rule = await attention_service.rule_counts(session, repository_id)
+    return AttentionCounts(
+        by_severity=by_severity,
+        by_rule=by_rule,
+        open_total=sum(by_severity.values()),
+    )
+
+
+@router.get("/pulls/{pull_id}/attention", response_model=list[AttentionItemRead])
+async def pull_attention(
+    pull_id: uuid.UUID, session: SessionDep, _: CurrentUserDep
+) -> list[AttentionItemRead]:
+    """该 PR 当前命中的关注项。
+
+    详情页需要知道"这个 PR 为什么在待办队列里"，而不是让维护者
+    自己回队列页翻找。只返回未解决的 —— 已解决的对决策没有意义。
+    """
+    from app.models.pull_request import PullRequest
+
+    if await session.get(PullRequest, pull_id) is None:
+        raise NotFoundError("PR 不存在", resource="pull_request", identifier=str(pull_id))
+
+    rows = await attention_service.items_for_subject(session, SubjectType.PULL_REQUEST, pull_id)
+    return [AttentionItemRead.model_validate(row) for row in rows]
+
+
+@router.get("/attention/rules", response_model=list[RuleDescription])
+async def rule_catalog(_: CurrentUserDep) -> list[RuleDescription]:
+    """规则清单与含义。界面上"这条规则是什么意思"的答案来自这里。
+
+    规则说明只在领域层维护一份，不在前端复刻 —— 两处各写一份必然漂移。
+    """
+    return [
+        RuleDescription(rule=AttentionRule(rule.value), description=RULE_DESCRIPTIONS[rule])
+        for rule in Rule
+    ]
+
+
+async def _require_item(session: SessionDep, item_id: uuid.UUID) -> AttentionItem:
+    item = await attention_service.get_item(session, item_id)
+    if item is None:
+        raise NotFoundError("关注项不存在", resource="attention_item", identifier=str(item_id))
+    return item
+
+
+@router.post("/attention/{item_id}/acknowledge", response_model=AttentionItemRead)
+async def acknowledge(
+    item_id: uuid.UUID, session: SessionDep, user: CurrentUserDep
+) -> AttentionItemRead:
+    """认领一条待办。
+
+    不需要额外权限：认领只是"我要处理这条"，任何登录用户都可以。
+    已被他人认领时不覆盖 —— 两个人同时在看同一件事时，
+    后者应该看到前者已经接手，而不是把它悄悄变成自己的。
+    """
+    item = await _require_item(session, item_id)
+    await attention_service.acknowledge(session, item, user.id)
+    await session.commit()
+    return AttentionItemRead.model_validate(item)
+
+
+@router.delete("/attention/{item_id}/acknowledge", response_model=AttentionItemRead)
+async def release(item_id: uuid.UUID, session: SessionDep, _: CurrentUserDep) -> AttentionItemRead:
+    item = await _require_item(session, item_id)
+    await attention_service.release(session, item)
+    await session.commit()
+    return AttentionItemRead.model_validate(item)
+
+
+@router.post("/repositories/{repository_id}/attention/recompute")
+async def recompute_attention(repository_id: uuid.UUID, session: SessionDep, _: Classify) -> dict:
+    """立即重算关注项。
+
+    定时任务每 15 分钟跑一次；手动入口是为"刚同步完想立刻看到结果"准备的。
+    """
+    repository = await repository_service.require_repository(session, repository_id)
+    stats = await attention_service.compute_for_repository(session, repository)
+    await session.commit()
+    return stats

package/backend/app/api/v1/auth.py

@@ -0,0 +1,106 @@
+"""认证端点。"""
+
+from fastapi import APIRouter, Request, Response, status
+
+from app.api.deps import ACCESS_COOKIE, REFRESH_COOKIE, CurrentUserDep, SessionDep, SettingsDep
+from app.core.config import Settings
+from app.core.exceptions import ForbiddenError, UnauthorizedError
+from app.core.permissions import ROLE_PERMISSIONS, Role
+from app.schemas.auth import LoginRequest, SetupRequest, SetupStatus, TokenResponse
+from app.schemas.user import CurrentUser, UserRead
+from app.services import auth_service, user_service
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+def _set_auth_cookies(response: Response, access: str, refresh: str, settings: Settings) -> None:
+    common = {
+        "httponly": True,
+        "samesite": "lax",
+        "secure": settings.cookie_secure,
+        "domain": settings.cookie_domain,
+    }
+    response.set_cookie(
+        ACCESS_COOKIE,
+        access,
+        max_age=settings.access_token_ttl_minutes * 60,
+        path="/",
+        **common,
+    )
+    # refresh cookie 只发给刷新端点，缩小暴露面
+    response.set_cookie(
+        REFRESH_COOKIE,
+        refresh,
+        max_age=settings.refresh_token_ttl_days * 86400,
+        path="/api/v1/auth",
+        **common,
+    )
+
+
+@router.get("/setup-status", response_model=SetupStatus)
+async def setup_status(session: SessionDep) -> SetupStatus:
+    """是否需要初始化（系统中无任何用户）。"""
+    return SetupStatus(needs_setup=await user_service.count_users(session) == 0)
+
+
+@router.post("/setup", response_model=UserRead, status_code=status.HTTP_201_CREATED)
+async def setup(payload: SetupRequest, session: SessionDep) -> UserRead:
+    """创建首个管理员。仅在系统无用户时可用。"""
+    if await user_service.count_users(session) > 0:
+        raise ForbiddenError("系统已完成初始化")
+
+    user = await user_service.create_user(
+        session,
+        username=payload.username,
+        display_name=payload.display_name,
+        email=payload.email,
+        password=payload.password,
+        role=Role.ADMIN,
+    )
+    await session.commit()
+    return UserRead.model_validate(user)
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(
+    payload: LoginRequest,
+    session: SessionDep,
+    settings: SettingsDep,
+    response: Response,
+) -> TokenResponse:
+    user = await auth_service.authenticate(session, payload.username, payload.password)
+    access, refresh = auth_service.issue_tokens(user, settings)
+    _set_auth_cookies(response, access, refresh, settings)
+    await session.commit()
+    return TokenResponse(access_token=access)
+
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh(
+    request: Request,
+    session: SessionDep,
+    settings: SettingsDep,
+    response: Response,
+) -> TokenResponse:
+    token = request.cookies.get(REFRESH_COOKIE)
+    if not token:
+        raise UnauthorizedError("缺少刷新令牌")
+    user = await auth_service.resolve_refresh_token(session, token, settings)
+    access, new_refresh = auth_service.issue_tokens(user, settings)
+    _set_auth_cookies(response, access, new_refresh, settings)
+    return TokenResponse(access_token=access)
+
+
+@router.post("/logout", status_code=status.HTTP_204_NO_CONTENT)
+async def logout(response: Response) -> None:
+    response.delete_cookie(ACCESS_COOKIE, path="/")
+    response.delete_cookie(REFRESH_COOKIE, path="/api/v1/auth")
+
+
+@router.get("/me", response_model=CurrentUser)
+async def me(user: CurrentUserDep) -> CurrentUser:
+    base = UserRead.model_validate(user)
+    return CurrentUser(
+        **base.model_dump(),
+        permissions=sorted(ROLE_PERMISSIONS[user.role], key=lambda p: p.value),
+    )