vps-manager/.qoder/rules/coding-standards.md

description, alwaysApply

description	alwaysApply
vps-manager 核心编码规范，每次会话自动加载	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）
• sync_service 以 (provider_id, external_id) 去重同步入库

平台分类

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

通知

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