# DV-0001：认证与会话 – 设计（Design）

## 上下文
涉及 `auth.py`（API）、`security.py`（JWT/bcrypt）、`deps.py`（依赖注入）、`redis_client.py`（TokenCache）。

## 数据模型
- `users`（id/username/password_hash/…）——细节见 DATABASE.md。

## 接口设计
- POST /api/v1/auth/{register,login,logout}
- GET /api/v1/auth/me
- PUT /api/v1/auth/profile
- POST /api/v1/auth/change-password
- POST /api/v1/auth/upload-avatar
- GET /api/v1/auth/avatar/{user_id}/{filename}
- GET/POST /api/v1/auth/mcp-credentials{,/rotate-secret}

## 认证流程
1. 登录成功：bcrypt 校验 → 生成 JWT（sub=user_id）→ 写入 Redis TokenCache。
2. 每次请求：`get_current_user` 校验 Redis 中 token→user_id，再 decode JWT，两项一致且用户启用才放行。
3. 登出：移除 Redis 中的 token，实现即时失效。

## 状态与降级
- Redis 不可用 → 认证失败（受 NFR-2 约束）；可选认证（`get_current_user_optional`）返回 None 而非报错。

## 变更影响
- NFR-9 敏感日志：security.py/deps.py 的 SECRET_KEY/JWT 载荷日志需脱敏（TS-12）。