---
description: vps-manager 核心编码规范，每次会话自动加载
alwaysApply: true
---

# vps-manager 编码规范

## 技术栈

- 后端：Python + FastAPI + SQLModel
- 前端：Vue 3 + Tailwind CSS（本地化、深色模式、PWA）
- 数据库：SQLite 分库（assets.db / metrics.db）
- 加密：cryptography.Fernet（MASTER_KEY 存 .env）
- 部署：cc1 节点，Gitea push 自动更新，HTTPS via Tailscale

## 前端：移动端优先

- UI 设计遵循移动端优先原则，采用底部导航栏适配小屏幕
- 确保页面 scrollWidth 等于 clientWidth，避免横向溢出
- 桌面端使用侧边栏布局，移动端使用底部 Tab 导航
- 静态资源基于文件 mtime 自动注入 `?v={mtime}` 版本号，配合 Service Worker 实现缓存失效

## Service Worker 缓存策略

- HTML 导航请求：`network-first`（回源失败才用缓存）
- 静态资源：`stale-while-revalidate`（SWR），配合 `?v={mtime}` 版本号
- API 请求：纯网络模式，不经过 Service Worker
- `sw.js` 本体由服务端设置 `Cache-Control: no-cache`

## 数据库分库

- `data/assets.db`：资产核心数据（Provider / Asset / VPSDetail / DomainDetail / AIAccount / Credential）
- `data/metrics.db`：监控指标与日志（MetricPoint / ServerInfo / SecurityCheck / EventLog）
- 备份策略：assets.db 每日备份保留 14 份，metrics.db 每周备份保留 4 份

## 凭证与加密

- 凭据中心化架构：`credentials` 表作为登录凭据唯一事实源
- 使用 `cryptography.Fernet` 加密敏感字段，MASTER_KEY 存于 `.env`
- 账号表降级为纯"归属 + API 配置"容器，通过 `account.credential_id` 关联凭据

## 云厂商适配层

- 位于 `app/adapters/`：BaseAdapter 抽象基类 + `@register` 装饰器注册
- 按 `Provider.sdk_type` 路由，完整适配器清单以 `app/adapters/registry.py` 的 `@register` 注册项为唯一事实源
- 当前已注册：Vultr / DO / Cloudflare / 阿里云 / 腾讯云 / AWS / Linode / NameSilo / AI 适配器组（DeepSeek / Moonshot / OpenAI / MiniMax）
- 新增 AI 适配器时，须同步在 `app/core/seed.py` 的 `PRESET_PROVIDERS` 中添加对应平台记录（`category: ai_agent`、`services: ai_agent`），前端 AI 平台选择器从数据库 Provider 动态渲染，无硬编码列表
- 新增 AI 适配器时，须在对应 adapter 中实现余额查询方法，`scripts/sync_ai_balances.py` 通过 `sync_service.sync_all_ai_balances()` 自动遍历全部 AI 账号同步余额
- sync_service 以 `(provider_id, external_id)` 去重同步入库

## 平台分类

- `category` 字段仅作主业务标签用于列表排序和兜底展示，不设"综合平台"分类
- 资产关联平台时以 `services` 多标签为准，优先匹配目标资产类型对应的服务能力

## 通知

- 通知服务根据 `.env` 配置自动选择 Telegram 或邮件渠道
- 未配置渠道自动跳过，不中断通知流程