# ShiErFeng

基于 Vue3 与 FastAPI 的前后端分离快速开发框架。

## 平台简介

施尔丰是一套全部开源的快速开发平台，供个人及企业免费使用。

* 前端采用Vue3、Element Plus。
* 移动端采用uni-app、Vue3、Vite，内置tailwindcss。
* 后端采用FastAPI、sqlalchemy、MySQL、Redis、OAuth2 & Jwt。
* 权限认证使用OAuth2 & Jwt，支持多终端认证系统。
* 支持加载动态权限菜单，多方式轻松权限控制。
* 纯Python版本：
  * Gitte仓库地址：<https://gitee.com/insistence2022/dash-fastapi-admin>
  * GitHub仓库地址：<https://github.com/insistence/Dash-FastAPI-Admin>

## 内置功能

1. 用户管理：用户是系统操作者，该功能主要完成系统用户配置。
2. 角色管理：角色菜单权限分配、设置角色按机构进行数据范围权限划分。
3. 菜单管理：配置系统菜单，操作权限，按钮权限标识等。
4. 部门管理：配置系统组织机构（公司、部门、小组）。
5. 岗位管理：配置系统用户所属担任职务。
6. 字典管理：对系统中经常使用的一些较为固定的数据进行维护。
7. 参数管理：对系统动态配置常用参数。
8. 通知公告：系统通知公告信息发布维护。
9. 操作日志：系统正常操作日志记录和查询；系统异常信息日志记录和查询。
10. 登录日志：系统登录日志记录查询包含登录异常。
11. 在线用户：当前系统中活跃用户状态监控。
12. 定时任务：在线（添加、修改、删除）任务调度包含执行结果日志。
13. 服务监控：监视当前系统CPU、内存、磁盘、堆栈等相关信息。
14. 缓存监控：对系统的缓存信息查询，命令统计等。
15. 传输加密：支持前后端请求加密、响应解密、公钥轮换、运行策略下发与监控统计。
16. 在线构建器：拖动表单元素生成相应的HTML代码。
17. 系统接口：根据业务代码自动生成相关的api接口文档。
18. 代码生成：配置数据库表信息一键生成前后端代码（python、sql、vue、js），支持下载。

## 托盘流转业务

本轮新增托盘全生命周期流转管理：

* 基础资料：菌种、客户、客户现场、产线、仓库、托盘。
* 业务流程：仓库入库、工厂装填、发货出库、客户现场使用、退回仓库。
* 只读报表：托盘库存、装填记录、发货出库、产线消耗、退回仓库、托盘追溯。
* Android PDA 可通过基于 uni-app 的 H5 页面使用，并支持 HID 扫码枪扫码后回车提交。

本轮交付包含 PDA H5 页面，但暂不打包 APK 或其他原生安装包，也未调用设备摄像头。上线前请阅读[托盘流转业务部署说明](./shierfeng-fastapi-backend/sql/pallet-workflow-deployment.md)。

测试数据批次的创建、授权、历史数据纳入和清理流程请阅读[测试数据批次操作说明](./shierfeng-fastapi-backend/sql/test-data-batch-operations.md)。

数据库初始化与升级入口请阅读 [SQL 使用说明](./shierfeng-fastapi-backend/sql/README.md)。新空库直接使用已包含隧道、物料日期、收货和 FIFO 结构的初始化 SQL；已有生产库不得运行全量初始化，请按[生产 Compose 增量迁移说明](./shierfeng-fastapi-backend/sql/production-compose-material-flow-migration-20261008.md)核对适用条件后执行。

### Git 跟踪范围

根目录 `.idea/`、`.pnpm-store/`、`.superpowers/`、`docs/`、`logs/` 及后端 `logs/` 仅保留本地，不再提交；Python 缓存及本地依赖同样忽略。必要的业务部署与数据库迁移说明随后端 `sql/` 目录维护。代码、迁移 SQL、测试和必要部署配置仍正常跟踪。

其他已有克隆首次拉取本次清理提交前，应先备份这些目录中需要保留的文件：Git 可能删除此前被跟踪的副本。此次清理不重写历史，旧提交中的文件仍然存在。

## 在线体验

* *账号：admin*
* *密码：请通过授权渠道获取，不在仓库中记录*
* 演示地址：<a href="https://vfadmin.insistence.tech">vfadmin管理系统<a>

## 项目开发及发布相关

### 传输层加解密配置说明

后端密钥配置与轮换说明：[shierfeng-fastapi-backend/docs/transport_crypto_config.md](./shierfeng-fastapi-backend/docs/transport_crypto_config.md)

### 开发

```bash
# 克隆项目
git clone https://git.yujiangrubber.cn/niuniu/ShiErFeng.git

# 进入项目根目录
cd ShiErFeng
```

#### 前端

```bash
# 进入前端目录
cd shierfeng-fastapi-frontend

# 安装依赖
npm install 或 yarn --registry=https://registry.npmmirror.com

# 建议不要直接使用 cnpm 安装依赖，会有各种诡异的 bug。可以通过如下操作解决 npm 下载速度慢的问题
npm install --registry=https://registry.npmmirror.com

# 启动服务
npm run dev 或 yarn dev
```

#### 移动端

```bash
# 进入移动端目录
cd shierfeng-fastapi-app

# 安装依赖
npm install -g pnpm
pnpm install

# 启动 H5
pnpm dev:h5

# 启动微信小程序
pnpm dev:mp-weixin
```

移动端详细文档请参考：[shierfeng-fastapi-app/README.md](./shierfeng-fastapi-app/README.md)

#### 后端

```bash
# 进入后端目录
cd shierfeng-fastapi-backend

# 安装项目依赖环境（统一使用 MySQL）
pip3 install -r requirements.txt

# 配置环境
在.env.dev文件中配置开发环境的数据库和redis

# 运行 SQL 文件
1. 新建数据库 shierfeng-fastapi（默认，可修改）
2. 使用命令或数据库连接工具运行 sql 文件夹下的 shierfeng-fastapi.sql

# 运行后端
shierfeng app run --env=dev
```

后端 CLI 使用说明请参考：[shierfeng-fastapi-backend/docs/cli_usage.md](./shierfeng-fastapi-backend/docs/cli_usage.md)

#### 访问

```bash
# 本地账号
账号：admin
密码：请在目标环境安全配置中设置后手工输入，不在仓库中记录

# 浏览器访问
地址：http://localhost:8080
```

### 发布

#### 前端

```bash
# 构建测试环境
npm run build:stage 或 yarn build:stage

# 构建生产环境
npm run build:prod 或 yarn build:prod
```

#### 后端

```bash
# 配置环境
在.env.prod文件中配置生产环境的数据库和redis

# 运行后端
shierfeng app run --env=prod
```

### Docker Compose部署方式

> ⚠️ **说明：** 根目录 Compose 使用 MySQL 和 Redis 命名卷持久化数据。初始化 SQL 只会在 MySQL 数据目录首次为空时执行。

#### MySQL 全栈版本

```bash
# 首次使用时创建本地配置文件
cp .env.docker.example .env
# 编辑 .env，至少修改 MYSQL_ROOT_PASSWORD、DB_PASSWORD 和 JWT_SECRET_KEY

# 启动前只做静态配置校验
docker compose config --quiet

# 构建并启动前端、后端、MySQL、Redis
docker compose up -d --build

# 查看服务状态
docker compose ps
```

浏览器访问：http://localhost:8080；后端直连接口为 `http://localhost:9099`；宿主机连接 MySQL 时使用 `127.0.0.1:13307`。需要局域网访问时，将根目录 `.env` 中的 `COMPOSE_BIND_IP` 改为 `0.0.0.0`，再使用宿主机局域网地址访问前端和后端端口。

已有数据库不能通过全量初始化脚本升级。请先备份并核对目标库，再按照 `shierfeng-fastapi-backend/sql/patches/` 下对应的 MySQL 增量补丁和部署文档执行；不要通过删除 Compose 数据卷来代替迁移。