# 基础架构方案

## 前端

- 使用 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。

## 后端分层

后端目录按职责划分：

```text
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。
- 不在没有明确需求前添加服务接口。