---
description: Nexus Python/FastAPI 后端规范 — 异步、Pydantic、Repository、UTC 时间
globs: server/**/*.py
alwaysApply: false
---

# Nexus Python 后端

## 依赖版本（勿随意降级）

FastAPI 0.115 · SQLAlchemy 2.0 async · aiomysql · Pydantic v2 · asyncssh 2.17 · redis 5.x · PyJWT 2.10

## API 路由

- 请求/响应模型定义在 `server/api/schemas.py`
- 业务 API 必须 `Depends(get_current_admin)`；Agent 用 `X-API-Key`；install 路由无 JWT
- 返回结构化错误，禁止裸 `except: pass`

## 数据库

- 模型：`server/domain/models/__init__.py`（14 表）
- 访问：`*_repo.py`，分页在 Repository 层 `offset/limit/count`
- 时间戳：`datetime.now(timezone.utc)`，禁止 naive datetime
- 连接池：默认 pool=160、overflow=120（安装向导按 MySQL `max_connections` 计算）

## Redis

- 客户端：`server/infrastructure/redis/client.py`，启动时强校验（ADR-009）
- 心跳 key：`heartbeat:{server_id}` TTL 600；告警 key：`alerts:{server_id}` TTL 3600
- 跨 worker 广播：Redis Pub/Sub `nexus:alerts`

## SSH

- 仅用 **asyncssh**（已删除 paramiko）
- 连接池引用计数：`acquire` / `release`，空闲 5min 清理
- 远程命令参数必须 `shlex.quote()`

## 凭据加密

- Fernet 存储 `Server.password` / `ssh_key_private`
- API 响应：`password_set` 布尔，禁止返回明文密码

## 测试

- `pytest` + `tests/conftest.py`；改 API/Service 须跑相关测试
- 新 endpoint 至少覆盖：认证失败、校验失败、成功路径