# Phase 3 Summary – 鉴权与配额基线

## 交付成果

1. **HTTP / WebSocket 鉴权加固**  
   - 引入统一速率限制器与失败计数：登录/注册/文件写操作等接口按 IP/用户多维限流，同时重试上限触发临时封禁。  
   - 自定义 CSRF 体系：后端提供 `/api/csrf-token`，前端全局 `fetch` 包装自动附带 `X-CSRF-Token`，所有写操作在 `before_request` 校验；会话 Cookie 统一启用 `SameSite=Strict`、`Secure/HttpOnly` 并增加基础安全头。  
   - Socket.IO 握手新增一次性 token（含 UA 指纹），连接、重连都会验证 token 并立即销毁，阻断单凭 session cookie 劫持的可能。

2. **模型 / 搜索用量配额**  
   - 新增 `modules/usage_tracker.py`，按用户与角色记录滑动窗口用量（普通用户：常规 50/5h、思考 20/5h、搜索 20/24h；管理员 9999），数据持久化在 `usage_stats.json`。  
   - `core/main_terminal.py` 在每次模型/搜索调用前检查并递增配额，超限时直接拒绝并返回重置时间；`web_server.py` 同步向前端广播 `quota_notice`，防止静默失败。  
   - UI 用量面板展示实时配额、重置时间，并在输入框侧阻止超限请求；新增右上角 toast 通知提醒配额状态。

3. **界面与体验**  
   - Web 用量组件、新增安全 toast、自动刷新配额数据（轮询 + Socket 事件），并隐藏 0 次额度的重置提示，避免噪音。

## 影响评估

- **攻击面收敛**：CSRF、防爆破、Socket 凭证等基础鉴权补齐后，未授权调用需要突破多重校验，WebSocket 劫持和暴力破解风险显著下降。  
- **可观测性/运维**：配额快照和 `/api/usage` 接口为后续差异化用户组与审计提供依据，可直观查看每类用量与重置时间。  
- **用户体验**：前端能够即时获知配额状态，避免“点击无响应”，同时 toast 提醒让限额策略更透明。

## 仍待处理

- 尚未引入 CAPTCHA / MFA、异常告警、CLI API Token 等进一步的身份防护手段。  
- Upload/MIME 检查、CSP/内容安全策略与更细粒度的 ACL 仍未落地。  
- 配额目前只区分普通/管理员，可在下一阶段扩展“用户组 + 自定义窗口/额度”的配置中心，并联动告警系统。

## 验证

- `python3 -m py_compile web_server.py core/main_terminal.py core/web_terminal.py modules/usage_tracker.py`。  
- 手动验证：登录界面输错多次触发 429，WebSocket 无 token 无法建立连接；浏览器抓包可见所有写请求均带 `X-CSRF-Token`。  
- 配额体验：普通用户 5 小时窗口内超限时前端弹出提示、API 返回重置时间，5 小时后自动恢复。