gudupao-backend-frontend-demo 0.0.18
Add your description here
Requires Python: >=3.12

# FastAPI + Vue 3 全栈应用模板

这是一个现代化、生产就绪的全栈应用模板，采用 **Python FastAPI** 作为后端，**Vue 3** 作为前端。专为无缝开发体验和单端口部署而设计。

## ✨ 特性

*   **一体化部署**: 后端和前端在同一个端口 (8000) 上提供服务，无需额外部署前端服务器。
*   **SPA 支持**: 通过 FastAPI 的 Catch-all 路由完美支持 Vue Router 的 History 模式 (基于 `spa-manifest.json` 智能路由)。
*   **现代化工具链**:
    *   后端: 使用 `uv` 进行超快速的 Python 包管理。
    *   前端: 使用 `Vite` + `pnpm` + `unplugin-vue-router` (基于文件的自动路由)。
*   **API 自动化**:
    *   集成 `@hey-api/openapi-ts`，后端 API 变更时自动生成类型安全的前端客户端。
    *   开发模式下包含实时 Watcher，自动同步 OpenAPI 规范到前端。
*   **高性能服务器**: 支持 `Granian` (Rust 编写的 ASGI 服务器) 作为生产环境服务器选项。
*   **跨平台支持**: 内置的任务运行器可在 Windows, macOS 和 Linux 上流畅运行。
*   **极致开发体验**: 仅需一条命令即可同时启动前后端开发服务器，并支持热重载。
*   **简便的前端管理**: 提供 `f` 命令代理，无需手动切换目录即可执行前端命令。
*   **代码规范**: 内置 Ruff (Python) 和 ESLint (Vue/TS) 配置，配合 pre-commit 自动保证代码质量。

## 📋 环境要求

*   **Python** (3.12+)
*   **Node.js** (20+)
*   **uv** (Python 包管理器)
*   **pnpm** (Node 包管理器)

## 🚀 快速开始

1.  **安装依赖**
    ```bash
    # 安装后端依赖 (一般情况下会在执行 uv run 时自动安装)
    uv sync
    
    # 安装前端依赖 (一般情况下在启动 dev 时会自动安装)
    uv run f pnpm install
    ```

2.  **启动开发服务器**
    ```bash
    uv run dev
    ```
    *   后端地址: `http://localhost:8000`
    *   前端地址: `http://localhost:5173` (API 请求会自动代理到后端)

## 🛠️ 命令参考

我们通过 `pyproject.toml` 注册了以下快捷命令：

| 命令                  | 描述                                                         |
| :-------------------- | :----------------------------------------------------------- |
| `uv run dev`          | 并发启动后端和前端的开发服务器，并自动监视/同步 API 客户端。 |
| `uv run build`        | 同步 API 客户端，并将 Vue 前端构建到 `frontend_dist/` 目录。 |
| `uv run start`        | 启动生产环境后端服务器 (支持 `--granian` 标志)。             |
| `uv run preview`      | 先执行 `build` 然后执行 `start`，用于预览生产环境构建效果。  |
| `uv run f [cmd]`      | 在 `frontend/` 目录下运行命令。例如: `uv run f pnpm install` |
| `uv run manage update-api` | 手动从后端生成 OpenAPI 规范并更新前端 API 客户端。       |
| `uv run manage setup` | 手动安装/修复 Git Hooks (通常会自动执行，无需手动运行)。     |

*(注: 旧的 `uv run manage [command]` 方式依然受支持)*

## 📂 项目结构

```text
.
├── gudupao_backend_frontend_demo/ # Python 包源码
│   ├── app/                  # Python 后端代码
│   │   ├── core/             # 核心逻辑 (如 SPA 路由处理)
│   │   ├── routers/          # API 路由定义
│   │   ├── main.py           # FastAPI 入口点 & 静态文件托管逻辑
│   │   └── ...
│   ├── scripts/              # 项目管理脚本
│   │   └── manage.py         # 任务运行器逻辑 (dev, build, start 等)
│   └── ...
├── frontend/                 # Vue 3 前端源码
│   ├── src/pages/            # 基于文件的路由目录 (自动生成路由)
│   ├── src/client/           # [自动生成] API 客户端代码 (@hey-api)
│   ├── scripts/              # 前端脚本 (如 generate-manifest.ts)
│   ├── vite.config.ts        # Vite 配置 (包含 Proxy 和构建输出配置)
│   └── ...
├── frontend_dist/            # 构建产物 (由 build 命令生成)
├── pyproject.toml            # Python 依赖 & 脚本入口配置
└── uv.lock
```

## 🚢 部署指南

### ⚡ 极速部署 (uvx)

如果你已安装 `uv`，可以直接运行以下命令来启动最新版本的服务：

```bash
uvx gudupao-backend-frontend-demo@latest start
```

### 📦 标准部署 (源码构建)

本项目设计为可以像标准 Python 应用一样进行部署。

1.  **构建前端** (在 CI/CD 或本地环境执行):
    ```bash
    uv run build
    ```
2.  **准备服务器**:
    *   将 `gudupao_backend_frontend_demo/` 目录, `frontend_dist/` 目录, 和 `pyproject.toml` 复制到服务器。
    *   确保服务器已安装 Python 和 `uv`。
3.  **运行服务**:
    ```bash
    uv sync
    uv run start
    ```
    *   **注意**: 生产环境服务器**不需要**安装 Node.js (因为我们只托管构建好的静态文件)。

### 🐳 Docker 部署

本项目包含 `Dockerfile`，支持构建轻量级的生产镜像。镜像已发布至 `ghcr.io/gudupaocreativity/demo`。

```bash
# 拉取并运行
docker run -p 8000:8000 ghcr.io/gudupaocreativity/demo:latest

# 或者本地构建
docker build -t ghcr.io/gudupaocreativity/demo .
```

支持通过环境变量配置：
*   `USE_GRANIAN=true`: 使用 Granian 服务器。
*   `WORKERS=4`: 设置工作进程数。