Metadata-Version: 2.4
Name: gudupao-backend-frontend-demo
Version: 0.0.2
Summary: Add your description here
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.128.0
Requires-Dist: psutil>=7.2.1
Requires-Dist: typer>=0.21.1
Requires-Dist: uvicorn>=0.40.0

# FastAPI + Vue 3 全栈应用模板

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

## ✨ 特性

*   **一体化部署**: 后端和前端在同一个端口 (8000) 上提供服务，无需额外部署前端服务器。
*   **SPA 支持**: 通过 FastAPI 的 Catch-all 路由完美支持 Vue Router 的 History 模式。
*   **现代化工具链**:
    *   后端: 使用 `uv` 进行超快速的 Python 包管理。
    *   前端: 使用 `Vite` + `pnpm` + `unplugin-vue-router` (基于文件的自动路由)。
*   **跨平台支持**: 内置的任务运行器可在 Windows, macOS 和 Linux 上流畅运行。
*   **极致开发体验**: 仅需一条命令即可同时启动前后端开发服务器，并支持热重载。
*   **简便的前端管理**: 提供 `f` 命令代理，无需手动切换目录即可执行前端命令。

## 📋 环境要求

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

## 🚀 快速开始

1.  **安装依赖**
    ```bash
    # 安装后端依赖
    uv sync
    
    # 安装前端依赖 (使用内置的 f 命令代理)
    uv run f pnpm install
    ```

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

## 🛠️ 命令参考

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

| 命令 | 对应脚本 | 描述 |
| :--- | :--- | :--- |
| `uv run dev` | `scripts.manage:dev` | 并发启动后端和前端的开发服务器。 |
| `uv run build` | `scripts.manage:build` | 将 Vue 前端构建到 `frontend_dist/` 目录。 |
| `uv run start` | `scripts.manage:start` | 启动生产环境后端服务器 (同时托管 API 和静态文件)。 |
| `uv run preview` | `scripts.manage:preview` | 先执行 `build` 然后执行 `start`，用于预览生产环境构建效果。 |
| `uv run f [cmd]` | `scripts.manage:f_entry` | 在 `frontend/` 目录下运行命令。例如: `uv run f pnpm install` |

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

## 📂 项目结构

```text
.
├── app/                  # Python 后端代码
│   ├── main.py           # FastAPI 入口点 & 静态文件托管逻辑
│   └── ...
├── scripts/              # 项目管理脚本
│   └── manage.py         # 任务运行器逻辑 (dev, build, start 等)
├── frontend/             # Vue 3 前端源码
│   ├── src/pages/        # 基于文件的路由目录 (自动生成路由)
│   ├── vite.config.js    # Vite 配置 (包含 Proxy 和构建输出配置)
│   └── ...
├── frontend_dist/        # 构建产物 (由 build 命令生成)
├── pyproject.toml        # Python 依赖 & 脚本入口配置
└── uv.lock
```

## 🚢 部署指南

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

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