62 lines
1.6 KiB
Markdown
62 lines
1.6 KiB
Markdown
# 基础架构方案
|
|
|
|
## 前端
|
|
|
|
- 使用 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。
|
|
- 不在没有明确需求前添加服务接口。
|