Metadata-Version: 2.4
Name: fred_admin
Version: 1.0.17
Summary: A Flask-based web framework with built-in utilities and extensions
Author-email: chenyg <chenyougang@126.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/fred-framework
Project-URL: Repository, https://github.com/yourusername/fred-framework
Project-URL: Documentation, https://github.com/yourusername/fred-framework#readme
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=3.1.2
Requires-Dist: flask_cors>=6.0.1
Requires-Dist: flask_jwt_extended>=4.7.1
Requires-Dist: Pillow>=11.3.0
Requires-Dist: flask_smorest>=0.46.2
Requires-Dist: flask_swagger_ui>=5.21.0
Requires-Dist: cryptography>=46.0.0
Requires-Dist: requests>=2.32.5
Requires-Dist: flask_apscheduler>=1.13.1
Requires-Dist: flask_babelplus>=2.2.0
Requires-Dist: flask_sqlacodegen>=2.0.0
Requires-Dist: flask_sqlalchemy>=3.1.1
Requires-Dist: pymysql>=1.1.2
Requires-Dist: pytz>=2025.2
Requires-Dist: flask_mail>=0.10.0
Requires-Dist: redis>=7.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

# Fred Admin

基于 Flask 的后台管理框架，开箱即用的企业级脚手架。

## 特性

- 快速初始化：一条命令生成完整项目结构
- 模块化设计：支持多模块热加载，业务隔离
- 内置 Admin：完整的后台管理系统（前后端）
- 定时任务：APScheduler 持久化到数据库，重启自动恢复
- 多数据库：默认 SQLite，可切换 MySQL
- Swagger 文档：自动生成 API 文档
- 国际化：内置多语言支持

## 安装

```bash
pip install fred_admin
```

## 快速开始

```bash
# 1. 创建项目目录
mkdir myproject && cd myproject

# 2. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# 3. 安装框架
pip install fred_admin

# 4. 初始化项目
fred-init

# 5. 启动应用
python app.py
```

访问 http://127.0.0.1:5000 即可看到管理后台。

## 目录结构

### 框架包结构（fred_admin）

```
fred_admin/
├── __init__.py           # create_app() 入口
├── install_hook.py       # fred-init 命令实现
├── create_module.py      # fred-create 命令实现
├── common/               # 框架核心组件
│   ├── AliyunSms.py      # 阿里云短信
│   ├── Blueprints.py     # 蓝图自动注册
│   ├── Email.py          # 邮件发送
│   ├── Extensions.py     # 扩展初始化（DB、JWT、Scheduler等）
│   ├── HandleExcetion.py # 全局异常处理
│   ├── ImageVerification.py # 图片验证码
│   ├── PageSchema.py     # 分页 Schema
│   ├── Response.py       # 统一响应格式
│   ├── Route.py          # SPA 路由与静态资源
│   ├── RuntimeHook.py    # 运行时模块加载钩子
│   ├── Sqlacodegen.py    # 数据库模型自动生成
│   ├── Swagger.py        # Swagger UI 配置
│   ├── SystemLog.py      # 系统日志
│   ├── Utils.py          # 工具函数
│   └── WechatLogin.py    # 微信登录
├── config/               # 框架默认配置
│   ├── Config.py         # 默认配置项
│   └── Logger.py         # 日志配置
├── fonts/                # 字体文件
└── _template/            # 项目模板（fred-init 复制源）
    ├── app.py            # 应用入口模板
    ├── common/           # 公共模块模板
    ├── data/             # 数据库文件（app.db、fred.sql）
    ├── docs/             # 文档模板
    ├── modules/          # 模块模板
    │   └── admin/        # 内置 Admin 模块
    │       ├── backend/  # 后端（controller/service/schema）
    │       ├── frontend/ # 前端源码（Vue 3 + TypeScript）
    │       └── templates/# 前端构建产物
    └── requirements.txt
```

### 初始化后的项目结构

```
myproject/
├── app.py                # 应用入口
├── common/               # 项目公共模块
│   ├── config/
│   │   ├── Config.py          # 项目配置（覆盖框架默认值）
│   │   └── Config.example.py  # 完整可覆盖项目录（可选参考）
│   └── model/
│       └── model.py      # 数据库模型（sqlacodegen 生成）
├── data/                 # 数据文件
│   ├── app.db            # SQLite 数据库
│   └── fred.sql          # SQL 初始化脚本
├── docs/                 # 项目文档
├── logs/                 # 日志目录
├── modules/              # 业务模块
│   └── admin/            # 内置 Admin
│       ├── backend/
│       │   ├── constant/ # 常量定义
│       │   ├── controller/ # 控制器（API 入口）
│       │   ├── schema/   # 请求/响应 Schema
│       │   └── service/  # 业务逻辑层
│       ├── frontend/     # 前端源码
│       └── templates/    # 前端构建产物
├── requirements.txt      # 项目依赖
└── .gitignore
```

## 配置说明

项目配置位于 `common/config/Config.py`，只需配置项目特有项，其余使用框架默认值。  
完整可覆盖项目录见模板 `common/config/Config.example.py`（与 `fred_admin.config.Config` 键对齐）；框架源码注释见 `src/fred_admin/config/Config.py`。

### 必须配置

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `SQLALCHEMY_DATABASE_URI` | 数据库连接 | `sqlite:///data/app.db` |
| `SECRET_KEY` | Flask Session 密钥 | 需在生产环境替换 |
| `JWT_SECRET_KEY` | JWT 签名密钥 | 需在生产环境替换 |

### 基础配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `ENABLE_SWAGGER` | `False` | 是否启用 Swagger 文档（模板脚手架常开 `True`） |
| `ENCRYPT_DATA` | `False` | 返回数据是否加密 |
| `ENABLE_GLOBAL_EXCEPTION` | `True` | 全局异常处理 |
| `DEFAULT_PASSWORD` | `'Fred@2026'` | 新建/重置用户默认密码 |
| `DEFAULT_MODULE` | `'admin'` | 访问 `/` 重定向到 `/{模块名}` |

### 模块加载

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `LOAD_CUSTOM_MODULES` | `[]` | 只加载指定模块，空列表加载所有 |
| `EXTERNAL_MODULES` | `[]` | pip 包模块，如 `['uc_integration']` |

### 门户 qiankun CORS

子系统嵌入 gss-portal 时开启；最外层 WSGI，带 credentials，不被 `after_request` 信封冲掉。

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `PORTAL_CORS_ENABLED` | `False` | 是否启用门户跨域 |
| `PORTAL_CORS_ORIGINS` | `http://127.0.0.1:5002` 等 | 允许的门户 Origin 白名单 |
| `PORTAL_CORS_PATH_PREFIXES` | `[]` | 路径前缀；空列表=全部路径，建议如 `['/todo']` |

### 数据库

```python
# SQLite（默认，无需安装）
SQLALCHEMY_DATABASE_URI = 'sqlite:///data/app.db'

# MySQL
SQLALCHEMY_DATABASE_URI = 'mysql+pymysql://user:pwd@127.0.0.1:3306/db'

# 多数据库绑定
SQLALCHEMY_BINDS = {'other': 'mysql+pymysql://user:pwd@127.0.0.1:3306/other'}
```

### Redis

```python
REDIS_URL = 'redis://:password@127.0.0.1:6379/1'
```

### JWT 配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `JWT_ACCESS_TOKEN_EXPIRES` | `timedelta(days=2)` | 访问令牌有效期 |
| `JWT_REFRESH_TOKEN_EXPIRES` | `timedelta(days=7)` | 刷新令牌有效期 |
| `FERNET_KEY` | `''` | `ENCRYPT_DATA=True` 时的加解密密钥 |

### 日志配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `LOG_LEVEL` | `'DEBUG'` | 日志级别 |
| `LOG_FILE` | `'logs/app.log'` | 日志文件路径 |
| `LOG_FORMAT` | 标准格式 | 日志格式字符串 |

### Swagger 配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `API_TITLE` | `'FredFrameApi'` | API 标题 |
| `API_VERSION` | `'v1'` | API 版本 |
| `OPENAPI_SWAGGER_UI_PATH` | `'/docs'` | Swagger 访问路径 |

### 定时任务

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `SCHEDULER_API_ENABLED` | `True` | 启用定时任务 API |
| `SCHEDULER_TIMEZONE` | `'Asia/Shanghai'` | 任务时区 |
| `JOBS` | `[]` | 预定义任务列表 |

### 邮件配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `MAIL_SERVER` | `''` | 邮件服务器地址 |
| `MAIL_PORT` | `25` | 端口 |
| `MAIL_USE_TLS` | `True` | 使用 TLS |
| `MAIL_USERNAME` | `''` | 邮箱用户名 |
| `MAIL_PASSWORD` | `''` | 邮箱密码 |
| `MAIL_DEFAULT_SENDER` | `''` | 默认发件人 |

### 阿里云短信

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `ALIBABA_SIGN_NAME` | `''` | 短信签名 |
| `ALIBABA_KEY_ID` | `''` | AccessKey ID |
| `ALIBABA_KEY_SECRET` | `''` | AccessKey Secret |
| `ALIBABA_TEMPLATE_CODE` | `''` | 短信模板编号 |

### 路由映射

```python
ROUTE_CONFIG = {
    'upload': 'upload',       # /upload/<path> -> upload/
    'download': 'download'    # /download/<path> -> download/
}
```

## 命令行工具

### fred-init

初始化项目，将模板复制到当前目录：

```bash
fred-init
```

- 复制 `app.py`、`common/`、`data/`、`modules/` 等
- `demo_` 前缀文件自动重命名为隐藏文件（`.gitignore` 等）
- 自动构建前端（如 templates/ 不存在）

### fred-create

创建业务模块：

```bash
fred-create user    # 创建 user 模块
```

- 生成 `modules/user/backend/`（controller/service/schema）
- 生成 `modules/user/frontend/`（Vue 前端）
- 文档写入 `docs/modules/user.md`

## 代码规范

### 后端规范（Python）

- **代码风格**: 遵循 PEP 8，使用 Google 风格注释
- **目录分层**: controller → service → model，职责清晰
- **蓝图注册**: 控制器使用 `MethodView`，自动注册到蓝图
- **Schema 验证**: 使用 marshmallow 定义请求/响应 Schema
- **异常处理**: 统一通过 `HandleException` 捕获，返回标准格式
- **日志**: 使用 `app.logger`，格式统一

### 前端规范（Vue 3 + TypeScript）

#### JS/TS 规范
- 使用 Composition API (`<script setup>`)
- 优先 `let/const`，禁止 `var`
- 禁止未使用变量、空函数
- 类型明确，避免 `any`

#### CSS/SCSS 规范
- 组件样式 `scoped`，避免全局污染
- 使用 SCSS 变量与 CSS 变量保持主题一致性
- 属性顺序遵循 recess-order

#### Vue 组件规范
- 使用 `<script setup>` 语法
- 语义化标签，避免内联样式
- Props 单向数据流，命名连字符化

#### Git 提交规范
- type 限定: `feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert`
- 分支命名: `feature/xxx`, `fix/xxx`, `docs/xxx`
- 提交前自动执行 ESLint + Prettier + Stylelint

### 前端构建

```bash
cd modules/admin/frontend

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 生产构建（输出到 ../templates/）
pnpm build:pro
```

## 模块开发

### 后端模块结构

```
modules/
└── your_module/
    └── backend/
        ├── constant/     # 常量（如 RedisKey.py）
        ├── controller/   # 控制器（API 入口）
        ├── schema/       # 请求/响应验证
        └── service/      # 业务逻辑
```

### 定时任务

在 `modules/your_module/backend/service/SchedulerTasks.py` 中定义任务函数：

```python
def your_task():
    # 任务逻辑
    return {'success': True, 'message': 'done'}
```

通过管理后台或 API 添加定时任务，任务会持久化到数据库，重启后自动恢复。

## License

MIT
