pyxray/docs/infra.md

基础架构方案

前端

• 使用 Bun 管理依赖、开发和构建。
• 使用 React 编写 UI。
• 使用 shadcn/Radix 作为组件基础。
• 使用 TailwindCSS 编写样式。
• 前端只通过协议层定义的 HTTP API 与后端通信。
• 前端不直接读取 backend 文件，也不依赖 Python 内部实现。

协议

• dev/protocol/ 是前后端之间的稳定边界。
• HTTP API 使用 OpenAPI 3.1 定义。
• 共享数据结构使用 JSON Schema 表达。
• 前端 TypeScript 类型和 API client 应从协议生成。
• 后端必须实现协议，而不是让协议跟随后端内部结构变化。

后端

• 使用 Python 实现当前后端。
• 使用 FastAPI 提供 HTTP API。
• 使用 Pydantic v2 做数据校验和 DTO。
• 使用 Typer 提供 CLI。
• 使用 uv 管理 Python 环境和依赖。
• 使用 pytest 做测试。
• 使用 ruff 做 lint 和 format。
• 本地状态持久化优先使用 SQLite。

后端分层

后端目录按职责划分：

dev/backend/
  src/pyxray_backend/
    api/
    cli/
    core/
    runtime/
    storage/
    subscriptions/
    xray/
  tests/

• api/ 只负责 HTTP 适配。
• cli/ 只负责命令行适配。
• core/ 放核心用例逻辑。
• runtime/ 放运行态状态、日志和生命周期管理。
• storage/ 放本地持久化。
• subscriptions/ 放节点订阅解析。
• xray/ 放 Xray 下载、配置生成和进程管理。

边界原则

• 稳定 API 契约放在 dev/protocol/。
• backend 是协议的一种实现，未来可以替换为 Rust。
• frontend 依赖协议，不依赖 backend。
• 不在没有明确需求前添加服务接口。