# tnt **Repository Path**: guocongll/tnt ## Basic Information - **Project Name**: tnt - **Description**: 小程序 开发 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-12-21 - **Last Updated**: 2026-06-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

logo

TNT 管理后台

基于 Dash + FastAPI 的前后端分离后台（源自 Dash-FastAPI-Admin，含库存与小程序登录扩展）

## 目录 - [项目说明](#项目说明) - [工程结构](#工程结构) - [架构说明](#架构说明) - [本仓库相对上游的扩展](#本仓库相对上游的扩展) - [后端模块分层与代码骨架](#后端模块分层与代码骨架) - [环境要求](#环境要求) - [快速开始](#快速开始) - [运行与访问](#运行与访问) - [生产部署（Nginx 示例）](#生产部署nginx-示例) - [内置功能（框架能力）](#内置功能框架能力) - [Cursor 项目规则](#cursor-项目规则) - [常见问题](#常见问题) - [演示截图](#演示截图) - [致谢与参考](#致谢与参考) ## 项目说明 本仓库在开源项目 **[Dash-FastAPI-Admin](https://gitee.com/insistence2022/dash-fastapi-admin)** 基础上演进，用于 **Web 管理端 + 后端 API** 场景： - **前端**：Dash、[feffery-antd-components](https://github.com/CNFeffery/feffery-antd-components)、[feffery-utils-components](https://github.com/CNFeffery/feffery-utils-components)。 - **后端**：FastAPI、SQLAlchemy、MySQL 或 PostgreSQL、Redis、OAuth2 + JWT。 - **权限**：动态菜单、按钮级权限、数据权限等（与上游能力一致）。 **克隆本仓库（非上游模板仓库）：** ```bash git clone https://gitee.com/guocongll/tnt.git cd tnt ``` ## 工程结构 | 目录 | 说明 | |------|------| | `dash-fastapi-backend/` | FastAPI 后端：系统管理、监控、定时任务、**库存模块**、**小程序登录** 等 | | `dash-fastapi-frontend/` | Dash 前端：管理界面、请求后端 API | | `requirements.txt` | **MySQL** 依赖（含 `asyncmy`、`PyMySQL`） | | `requirements-pg.txt` | **PostgreSQL** 依赖（含 `asyncpg`、`psycopg2`） | | `dash-fastapi-backend/sql/` | 初始化与补丁 SQL（见下文） | | `.cursor/rules/` | Cursor 编辑器用的项目约定（架构、FastAPI、Dash 前端），见下文 [Cursor 项目规则](#cursor-项目规则) | ## 架构说明 ```text ┌─────────────────────┐ HTTP (requests) ┌──────────────────────┐ │ Dash 管理端 │ ──────────────────────────────► │ FastAPI 后端 │ │ dash-fastapi- │ Session 中带 Authorization 等 │ dash-fastapi-backend │ │ frontend :8088 │ │ :9099 │ └─────────────────────┘ └───────────┬────────────┘ │ │ 同一套 REST ▼ ┌────────────────────────┐ │ 微信小程序 / 其他客户端 │ │ (直连 API，不经 Dash) │ └────────────────────────┘ ``` - **管理端**：Dash 跑在 Flask 上，通过 `dash-fastapi-frontend/utils/request.py` 以 **服务端** 方式请求 FastAPI，默认与后端 **不同端口**（常见 `8088` → `9099`）。 - **小程序或其它客户端**：直接请求 FastAPI 的 Base URL；跨域由后端 **`middlewares/cors_middleware.py`** 配置，新域名或真机调试需在 `allow_origins` 中补充或改为读环境变量。 - **配置对齐**：前端 `.env.*` 中的 **`APP_BASE_URL`**、**`APP_IS_PROXY`**、**`APP_PROXY_PATH`** 需与 Nginx/反代及后端 **`APP_ROOT_PATH`** 一致，否则会出现页面能开、接口 404 或鉴权异常。 ## 本仓库相对上游的扩展 1. **库存管理（`module_inventory`）** - 后端路由：物料、仓库、库位、库存、流水、报表、条形码等（见 `dash-fastapi-backend/server.py` 中 `stockController`、`materialController` 等）。 - **数据库**：在基础库表初始化之后，需执行 **`dash-fastapi-backend/sql/inventory.sql`**（当前脚本面向 **MySQL 5.7+ / utf8mb4**）。 - 目录下另有 `fix_stock_unique_key*.sql`、`check_stock_indexes.sql` 等，用于索引/唯一约束类维护，按需执行。 2. **微信小程序登录（`module_miniapp`）** - 提供 `POST /miniapp/login` 等接口（前缀以实际路由为准，见 Swagger）。 - 用于小程序端账号体系与后台用户体系的对接场景；具体字段与配置以后端代码与 `.env` 为准。 3. **启动时建表** - 后端启动会执行 SQLAlchemy `create_all`（见 `config/get_db.py`），**仍建议用官方 SQL 做完整初始化**（含菜单、字典、初始管理员等），再执行扩展脚本。 ## 后端模块分层与代码骨架 FastAPI 应用在 **`dash-fastapi-backend/server.py`** 中装配：生命周期（Redis、定时任务、建表等）→ 子应用/静态资源 → 中间件（CORS、Gzip）→ 全局异常处理 → **`controller_list`** 中逐个 `include_router`。**新增业务路由必须完成两件事**：实现 `APIRouter`，并在 **`controller_list`** 中注册，否则文档与客户端均不可见。 | 路径模式 | 说明 | |----------|------| | `module_admin/` | 系统管理、登录、权限切面 `aspect/`、注解 `annotation/` 等 | | `module_inventory/` | 库存扩展：controller → service → dao，`entity/do` 与 `entity/vo` 分离 | | `module_miniapp/` | 小程序相关接口（如 `/miniapp/...`） | | `module_task/` | 与定时任务相关的脚本或占位 | **库存模块一键骨架（可选）**：仓库提供 Bash 脚本 **`dash-fastapi-backend/gen_inventory_module.sh`**，通过内嵌模板生成 `module_inventory` 目录骨架。使用前请阅读脚本内注释；生成后仍需：在 **`server.py`** 注册对应 `*Controller`、执行 **`sql/`** 下相关脚本、在后台配置菜单与接口权限字（与 `CheckUserInterfaceAuth` 一致）。Windows 可在 Git Bash 或 WSL 中执行。 **数据库会话**：多数管理端与库存接口使用 **`get_db`**（`AsyncSession`）；`module_miniapp` 等部分模块使用 **`get_db_sync`**（同步 `Session`）。新增代码请优先与**同模块**现有写法保持一致。 ## 环境要求 - Python **≥ 3.9** - **MySQL ≥ 5.7** 或 **PostgreSQL**（二选一，与 `requirements.txt` / `requirements-pg.txt` 对应） - **Redis**（会话、缓存、字典/配置缓存等） - 建议使用虚拟环境：`python -m venv .venv` 后激活再安装依赖 ## 快速开始 ### 1. 安装依赖 在项目根目录： ```bash # MySQL pip install -r requirements.txt # PostgreSQL pip install -r requirements-pg.txt ``` ### 2. 配置环境变量 - **后端**：编辑 `dash-fastapi-backend/.env.dev`（开发）或 `.env.prod`（生产） - 数据库连接、Redis、`APP_ROOT_PATH`（与 Nginx/前端代理路径一致）、JWT 密钥等。 - **前端**：编辑 `dash-fastapi-frontend/.env.dev` / `.env.prod` - `APP_BASE_URL` 指向后端可访问地址；若经 Nginx 反代，与 `APP_PROXY_PATH`、生产环境说明保持一致。 **请勿将真实生产密钥提交到 Git**；`config/env.py` 中的默认值为兜底，优先以 `.env.*` 为准。 ### 3. 初始化数据库 1. 创建空库（名称与 `.env` 中 `DB_DATABASE` 一致，例如本仓库示例常为 `tnt`）。 2. 执行基础脚本（二选一）： - MySQL：`dash-fastapi-backend/sql/dash-fastapi.sql` - PostgreSQL：`dash-fastapi-backend/sql/dash-fastapi-pg.sql` 3. **若启用库存模块（MySQL）**：继续执行 `dash-fastapi-backend/sql/inventory.sql`。 ### 4. 启动服务 **前端（开发）：** ```bash cd dash-fastapi-frontend python app.py --env=dev ``` **后端（开发）：** ```bash cd dash-fastapi-backend python app.py --env=dev ``` **生产前端（Waitress）：** ```bash cd dash-fastapi-frontend python wsgi.py --env=prod ``` **生产后端：** ```bash cd dash-fastapi-backend python app.py --env=prod ``` 亦可使用 `uvicorn` / `gunicorn` 等托管 FastAPI，需自行配置 `root_path` 与代理头。 ## 运行与访问 | 服务 | 默认端口（以 `.env` 为准） | 说明 | |------|---------------------------|------| | 前端 Dash | `8088` | 浏览器访问管理界面 | | 后端 FastAPI | `9099` | REST API；开发时可访问 **`http://:9099/docs`** 查看 Swagger | 同一后端进程同时承载 **Dash 管理端调用的接口** 与 **微信小程序等外部客户端**；Swagger 中可按 **Tags**（如「系统管理」「小程序登录」「库存管理」）筛选路由。 默认管理员账号与上游一致时一般为： - 账号：`admin` - 密码：`admin123` （若你修改过初始化 SQL 或密码策略，以实际数据为准。） ## 生产部署（Nginx 示例） 前端与后端分离部署时，常用反代：根路径指向前端，API 路径指向后端。示例（端口请按实际修改）： ```nginx server { location / { proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header REMOTE-HOST $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass http://127.0.0.1:8088/; } location /prod-api { proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header REMOTE-HOST $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass http://127.0.0.1:9099/; rewrite ^/prod-api/(.*)$ /$1 break; } error_page 500 502 503 504 /50x.html; location = /50x.html { root html; } } ``` 生产环境请在 `dash-fastapi-frontend/.env.prod` 中把 **`APP_BASE_URL`** 配成对外的站点根地址（例如 `https://your-domain.com`），并与后端的 `APP_ROOT_PATH`、Nginx 的 `location` 前缀对齐。 ## 内置功能（框架能力） 与 Dash-FastAPI-Admin 一致的核心模块包括： 1. 用户管理 2. 角色管理（菜单权限、数据范围） 3. 菜单管理 4. 部门管理 5. 岗位管理 6. 字典管理 7. 参数管理 8. 通知公告 9. 操作日志 / 登录日志 10. 在线用户 11. 定时任务 12. 服务监控 / 缓存监控 13. 自动接口文档（Swagger） ## Cursor 项目规则 使用 [Cursor](https://cursor.com) 在本仓库协作时，可在 **`.cursor/rules/`** 查看约定（随仓库版本控制，团队可共享）： | 文件 | 作用 | |------|------| | `tnt-project-context.mdc` | 全局：职责、改代码前建议阅读的规则顺序 | | `tnt-framework-and-codegen.mdc` | 仓库框架、启动链、`module_*` 分层、与 Dash 的协作方式 | | `tnt-fastapi-conventions.mdc` | 匹配 `dash-fastapi-backend/**/*.py`：CORS、统一 JSON、异常、分层 | | `tnt-dash-frontend-conventions.mdc` | 匹配 `dash-fastapi-frontend/**/*.py`：`api_request`、`api/`、`callbacks/`、`views/` | ## 常见问题 1. **`git push` 显示 `Everything up-to-date`，Gitee 上却看不到「新」提交** 表示远程已包含本地当前分支的全部提交。若你期望看到新改动，请先确认是否已 **`git add` / `git commit`**，以及浏览器是否打开 **正确仓库与 `main` 分支**，并尝试强制刷新。 2. **管理端能登录，但部分接口 404 或路径不对** 检查前端 **`APP_BASE_URL`**、**`APP_IS_PROXY`**、**`APP_PROXY_PATH`** 与 Nginx 的 `location` 前缀是否与后端 **`APP_ROOT_PATH`** 一致。 3. **小程序或浏览器跨域失败** 在 **`dash-fastapi-backend/middlewares/cors_middleware.py`** 中为实际来源增加 `origins`，或改为从环境变量读取；避免在需要 Cookie 的场景下误用 `allow_origins=["*"]`。 4. **Swagger 打不开的地址** 开发环境一般为 **`http://<后端主机>:9099/docs`**（端口以 `.env` 为准）。 ## 演示截图 界面与上游项目相近，完整演示图可参考上游仓库： - [Gitee 演示图目录](https://gitee.com/insistence2022/dash-fastapi-admin/tree/master/demo-pictures) 在线演示（上游维护，非本仓库部署承诺）： - 演示站：（账号 `admin` / 密码 `admin123`） ## 致谢与参考 - 核心框架：**[Dash-FastAPI-Admin](https://gitee.com/insistence2022/dash-fastapi-admin)** / [GitHub](https://github.com/insistence/Dash-FastAPI-Admin) - 思路与权限设计参考：**[RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue)** - 组件库：**[feffery-antd-components](https://github.com/CNFeffery/feffery-antd-components)**、**[feffery-utils-components](https://github.com/CNFeffery/feffery-utils-components)**