# Python Basic Framework

**Repository Path**: newpc/python-basic-framework

## Basic Information

- **Project Name**: Python Basic Framework
- **Description**: 一个面向中后台项目的全栈基础框架，提供开箱即用的认证鉴权、权限管理、系统配置、数据字典、附件、审计与运行监控能力。项目采用前后端分离开发模式，生产构建后可由 FastAPI 统一托管前端静态资源。

本仓库只保留可复用的基础能力，不包含特定业务模块，适合作为新项目脚手架或管理端原型的起点。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python Basic Framework

一个面向中后台项目的全栈基础框架，提供开箱即用的认证鉴权、权限管理、系统配置、数据字典、附件、审计与运行监控能力。项目采用前后端分离开发模式，生产构建后可由 FastAPI 统一托管前端静态资源。

本仓库只保留可复用的基础能力，不包含特定业务模块，适合作为新项目脚手架或管理端原型的起点。

## 界面预览

### 工作台

![工作台](doc/images/readme-dashboard.jpg)

### 用户管理

![用户管理](doc/images/readme-users.jpg)

### 数据字典

![数据字典](doc/images/readme-dictionaries.jpg)

## 核心能力

- **认证与安全**：登录验证码、JWT Bearer Token、失败登录限流、生产配置基线校验和常用安全响应头。
- **RBAC 权限**：用户、角色、菜单、按钮权限管理；前端支持动态菜单与 `v-permission`，后端使用权限码执行最终校验。
- **平台配置**：系统配置、数据字典、附件上传下载与业务关联。
- **运维审计**：操作审计、系统监控、数据库连通性、磁盘空间、版本信息和 Python 运行环境查看。
- **开发支撑**：SQLAlchemy 分层、Pydantic v2 校验、通用 CRUD 工厂、CSV 导入导出工具和基础数据权限脚手架。
- **统一交付**：前端构建产物输出到 `server/dist`，由后端提供 SPA 静态托管与路由回退。

## 技术栈

| 层级 | 技术 |
| --- | --- |
| 前端 | Vue 3、TypeScript、Vite、Element Plus、Vue Router、Pinia、Axios |
| 后端 | FastAPI、SQLAlchemy 2、Pydantic 2、Uvicorn |
| 认证 | JWT、RBAC、验证码、登录防爆破 |
| 数据库 | SQLite（本地默认），可配置 MySQL/PostgreSQL |

## 项目结构

```text
Python Basic Framework/
├── server/                   # FastAPI 后端与生产静态资源托管
│   ├── app/
│   │   ├── api/              # API 路由与依赖注入
│   │   ├── models/           # SQLAlchemy 模型
│   │   ├── repositories/     # 数据访问层
│   │   ├── schemas/          # Pydantic 请求/响应模型
│   │   └── services/         # 业务服务与通用能力
│   ├── config.example.toml   # 配置模板
│   ├── requirements.txt      # Python 依赖
│   └── main.py               # 后端入口
├── web/                      # Vue 3 管理端
│   ├── src/api/              # API Client
│   ├── src/assets/styles/    # 全局样式与设计 Token
│   └── src/pages/            # 路由、布局与业务页面
├── doc/                      # 能力与安全文档
└── README.md
```

## 快速开始

### 环境要求

- Python 3.10+
- Node.js 18+
- npm 9+

### 1. 启动后端

```powershell
cd server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
Copy-Item config.example.toml config.toml
python main.py
```

Linux/macOS 激活虚拟环境时使用：

```bash
source .venv/bin/activate
```

后端默认地址：`http://127.0.0.1:8330`

- 健康检查：`http://127.0.0.1:8330/api/health`
- API 文档：`http://127.0.0.1:8330/docs`（仅在配置允许时启用）

### 2. 启动前端

另开一个终端：

```powershell
cd web
npm install
npm run dev
```

前端默认地址：`http://127.0.0.1:8331`

开发服务器会把 `/api` 请求代理到 `http://127.0.0.1:8330`。需要修改联调地址时，请调整 `web/vite.config.ts` 中的代理配置。

### 3. 登录

开发环境默认管理员账号：

- 用户名：`admin`
- 密码：`ChangeMe@12345`

首次进入需填写页面验证码。该账号只用于本地开发，部署前必须修改默认密码，并按实际环境调整 `server/config.toml`。

## 构建与运行

在 `web` 目录执行：

```powershell
npm run build
```

构建产物会输出到 `server/dist`。完成构建后启动后端，即可由 FastAPI 统一提供 API 与前端页面：

```powershell
cd server
python main.py
```

## 关键配置

复制 `server/config.example.toml` 为 `server/config.toml` 后按环境调整。常用配置包括：

| 配置项 | 说明 |
| --- | --- |
| `app_env` | 运行环境；生产环境使用 `production` 或 `prod` |
| `app_host` / `app_port` | 后端监听地址与端口 |
| `secret_key` | JWT 签名密钥，生产环境必须使用至少 32 位随机强密钥 |
| `database_url` | SQLAlchemy 数据库连接串 |
| `cors_origins` | 允许访问后端的前端来源白名单 |
| `enable_docs` | 是否启用 FastAPI API 文档 |
| `allow_default_admin` | 是否允许初始化默认管理员 |
| `upload_max_size_mb` | 单个附件大小限制 |

`server/config.toml`、数据库文件、日志、上传文件和构建产物均属于本地运行数据，不应提交到仓库。

## 常用验证

```powershell
# 后端语法检查
python -m compileall server/app server/main.py

# 前端生产构建
cd web
npm run build
```

## 项目文档

- [后端使用与启动说明](server/README.md)
- [前端开发说明](web/README.md)
- [后端模块维护文档](server/MODULE.md)
- [前端模块维护文档](web/MODULE.md)
- [框架能力说明](doc/framework-capabilities.md)
- [安全机制与上线检查](doc/security-mechanism.md)
- [开发指南](DEVELOPMENT_GUIDE.md)

## 上线前检查

生产部署至少需要替换 `secret_key`、默认管理员密码和数据库连接，收紧 CORS 来源，关闭热重载与非必要 API 文档，并通过 HTTPS 对外提供服务。完整检查项参见[安全机制与上线检查](doc/security-mechanism.md)。