签入版本
This commit is contained in:
@@ -1,3 +1,5 @@
|
||||
# 新手入门指南
|
||||
|
||||
:::warning 特别提醒
|
||||
官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
# 项目介绍
|
||||
|
||||
:::tip 概述
|
||||
DjangoAdmin 是企业级中台解决方案，后端基于 Flask + SQLAlchemy，前端基于 Vue3 + ElementPlus，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。
|
||||
:::
|
||||
|
||||
<div align="center">
|
||||
<p align="center">
|
||||
<img src="/logo.png" height="150" alt="logo"/>
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 免责声明
|
||||
|
||||
:::tip 概述
|
||||
使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。
|
||||
:::
|
||||
|
||||
:::danger 重要提示
|
||||
任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 项目目录结构
|
||||
|
||||
## 目录说明
|
||||
|
||||
在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 路由注册（Flask Blueprint）
|
||||
|
||||
:::tip 概述
|
||||
路由注册基于 Flask Blueprint 机制实现模块化挂载，本页讲解 Blueprint 的定义与在路由中心统一注册的方法。
|
||||
:::
|
||||
|
||||
Flask 使用 `Blueprint` 机制实现模块化路由注册。每个业务模块定义自己的 Blueprint，然后在路由注册中心统一挂载到应用。
|
||||
|
||||
## Blueprint 概念
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 完整代码清单
|
||||
|
||||
:::tip 概述
|
||||
本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。
|
||||
:::
|
||||
|
||||
本章汇总 Position 岗位模块涉及的全部文件，便于开发时快速查阅和复制。
|
||||
|
||||
## 后端文件清单
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# Router 层（Flask Blueprint）
|
||||
|
||||
:::tip 概述
|
||||
Router 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数解析，编写新接口从本页开始。
|
||||
:::
|
||||
|
||||
Router 层是 HTTP 接口层，负责定义路由、权限装饰器和请求参数解析。每个业务模块对应一个 router 文件，所有业务逻辑委托给 Service 层处理。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 常见问题与排错
|
||||
|
||||
:::tip 概述
|
||||
本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。
|
||||
:::
|
||||
|
||||
本章汇总模块开发过程中的常见问题和解决方案。
|
||||
|
||||
## 后端问题
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 前端 API 层
|
||||
|
||||
:::tip 概述
|
||||
前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。
|
||||
:::
|
||||
|
||||
前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 前端路由与菜单
|
||||
|
||||
:::tip 概述
|
||||
本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。
|
||||
:::
|
||||
|
||||
前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。
|
||||
|
||||
## 路由配置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 前端页面视图
|
||||
|
||||
:::tip 概述
|
||||
前端页面视图是用户直接交互的界面，本页讲解 Vue3 + ElementPlus 下一个完整 CRUD 页面的文件组成与编写方式。
|
||||
:::
|
||||
|
||||
前端页面视图是用户直接交互的界面。项目使用 Vue3 + ElementPlus + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成：
|
||||
|
||||
```
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 数据模型（Model）
|
||||
|
||||
:::tip 概述
|
||||
数据模型是模块开发的第一步，讲解如何用 SQLAlchemy ORM 与基类定义数据库表结构，新建模块时从本页开始。
|
||||
:::
|
||||
|
||||
数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 `SQLAlchemy ORM`，模型类通过继承基类自动获得通用字段和方法。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# Repository 层
|
||||
|
||||
:::tip 概述
|
||||
Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。
|
||||
:::
|
||||
|
||||
Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类只需声明 `model` 并按需实现 `page()` 和 `list_enabled()` 方法。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 路由注册
|
||||
|
||||
:::tip 概述
|
||||
路由注册是将模块 Blueprint 挂载到应用的过程，本页讲解在路由注册中心统一挂载的方法。
|
||||
:::
|
||||
|
||||
路由注册是将模块的 Blueprint 挂载到应用的过程。所有模块的路由在 `src/routes/v1.py` 中统一注册。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# WTForms Schema
|
||||
|
||||
:::tip 概述
|
||||
Schema 层负责请求数据校验，本页讲解基于 WTForms 表单类与 validators 的校验规范。
|
||||
:::
|
||||
|
||||
Schema 层负责请求数据的校验。项目使用 `WTForms` 定义表单类，通过 `validators` 约束字段格式，框架在接收请求体时自动执行校验。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# Service 层
|
||||
|
||||
:::tip 概述
|
||||
Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。
|
||||
:::
|
||||
|
||||
Service 层是业务逻辑层，负责实现具体的业务规则。简单 CRUD 模块继承 `BaseService` 基类，只需声明差异点即可获得完整的增删改查能力。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 文章管理
|
||||
|
||||
:::tip 文章管理
|
||||
文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。本模块是典型的「带文件处理」业务模块，涵盖了封面迁移、图集处理、富文本 XSS 清洗等核心机制。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 分类管理
|
||||
|
||||
:::tip 分类管理
|
||||
分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 行政区划管理
|
||||
|
||||
:::tip 行政区划
|
||||
行政区划模块管理全国省/市/区/街道四级区域数据，支持树形结构查询、级联选择器、拼音自动生成等功能。用户表通过 `province_code`/`city_code`/`district_code`/`street_code` 四个字段关联城市表的 `area_code`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 公告与链接管理
|
||||
|
||||
:::tip 公告/链接/城市
|
||||
公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 部门/职级/岗位管理
|
||||
|
||||
:::tip 部门/职级/岗位
|
||||
部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块，均继承 `BaseService`。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 案例演示
|
||||
|
||||
:::tip 案例演示
|
||||
案例演示模块是代码生成器的参考模板，展示了标准 CRUD 模块的完整实现。包含文件字段处理、枚举字典映射、状态管理等功能，可作为新模块开发的参考范例。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 文件模板管理
|
||||
|
||||
:::tip 文件模板
|
||||
文件模板模块用于管理系统中的文件模板，如导入导出模板、报表模板等。支持模板文件上传、按编码查询、文件 URL 自动转换等功能。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 定时任务
|
||||
|
||||
:::tip 定时任务
|
||||
定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）、scheduler（调度器）三个子模块。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 菜单管理
|
||||
|
||||
:::tip 菜单管理
|
||||
菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。权限节点由系统根据前端勾选自动生成，采用 `sys:module:action` 三段式命名。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 参数管理
|
||||
|
||||
:::tip 参数管理
|
||||
参数管理模块用于管理系统配置和业务配置，每个参数包含名称、编码、值、类型、排序、状态等属性。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 角色管理
|
||||
|
||||
:::tip 角色管理
|
||||
角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。角色删除时需清理关联的用户角色和角色菜单数据，并即时失效受影响用户的权限缓存。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 用户管理
|
||||
|
||||
:::tip 用户管理
|
||||
用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划、Excel 导入导出等功能。用户管理继承 `BaseService` 获得标准 CRUD 能力，并通过覆写钩子方法实现头像保存、密码加密、角色关联等定制逻辑。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 验证码机制
|
||||
|
||||
:::tip 验证码
|
||||
验证码是防止自动化攻击的重要安全手段。项目使用 Pillow 生成图片验证码，存储在 Redis 中，支持防刷限流和万能验证码（演示模式）。源码位于 `src/common/utils/captcha.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 系统配置管理
|
||||
|
||||
:::tip 系统配置
|
||||
系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `src/modules/configuration/`，路由位于 `src/modules/configuration/config/router.py` 和 `config_item/router.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 演示模式
|
||||
|
||||
:::tip 演示模式
|
||||
演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `FLASK_DEMO` 环境变量控制。装饰器位于 `src/middleware/demo.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 字典模块
|
||||
|
||||
:::tip 数据字典
|
||||
数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。后端读取工具位于 `src/common/utils/dict_util.py`，内置进程内 TTL 缓存。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 异常与响应处理
|
||||
|
||||
:::tip 全局异常与响应
|
||||
项目定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式，异常被捕获后也转换为相同格式。响应函数位于 `src/core/response.py`，异常类型位于 `src/core/exceptions.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 防重复提交
|
||||
|
||||
:::tip 防重复提交
|
||||
防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。后端唯一性校验通过 WTForms 自定义校验器查询数据库实现。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 用户认证（JWT）
|
||||
|
||||
:::tip JWT认证
|
||||
JWT（JSON Web Token）是项目的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `src/core/jwt.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 登录日志
|
||||
|
||||
:::tip 登录日志
|
||||
登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。支持 IP 地理位置解析（ip2region）和 User-Agent 解析。登录逻辑位于 `src/modules/auth/service.py`，日志记录位于 `src/modules/login_log/service.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 操作日志
|
||||
|
||||
:::tip 操作日志
|
||||
操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。日志落库通过后台线程异步执行，不阻塞响应。源码位于 `src/middleware/operation_log.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 权限管理（RBAC）
|
||||
|
||||
:::tip RBAC权限
|
||||
项目采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `@check_permission` 装饰器校验（`src/core/permission.py`），前端通过 `v-perm` 指令控制按钮显隐。
|
||||
:::
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 事务装饰器
|
||||
|
||||
:::tip 概述
|
||||
本页讲解事务装饰器的用法，适用于中间件自动事务之外的特殊场景事务控制。
|
||||
:::
|
||||
|
||||
除了 AOP 中间件自动管理事务外，项目还提供了事务装饰器，用于特殊场景下的事务控制。
|
||||
|
||||
## @transactional 装饰器
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# AOP 事务管理
|
||||
|
||||
:::tip 概述
|
||||
本页讲解 AOP 风格的事务管理机制——中间件自动管理数据库事务，业务代码无需手动 commit 或 rollback。
|
||||
:::
|
||||
|
||||
项目采用 AOP（面向切面编程）风格的事务管理机制，通过中间件自动管理数据库事务，业务代码无需手动调用 `commit` 或 `rollback`。
|
||||
|
||||
## 设计理念
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 参数验证（Schema）
|
||||
|
||||
:::tip 参数验证
|
||||
项目使用 WTForms 进行请求参数验证。所有请求体参数通过 WTForms 表单类定义，框架自动解析和验证 JSON 请求体，验证失败返回标准格式错误信息。BaseForm 基类位于 `src/common/forms/base_form.py`。
|
||||
:::
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 代码生成器
|
||||
|
||||
:::tip 概述
|
||||
本页讲解代码生成器的用法，可根据数据库表结构一键生成前后端 CRUD 全套代码。
|
||||
:::
|
||||
|
||||
代码生成器是项目的重要工具，可以根据数据库表结构一键生成前后端 CRUD 代码，包括模型、仓库、服务、路由、表单、前端 API、前端页面等全套代码。
|
||||
|
||||
## 功能概述
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 为什么选择我们？
|
||||
|
||||
:::tip 核心价值
|
||||
企业级数据中台不应从零搭建。本框架提供开箱即用的完整解决方案，为中大型企业构建统一的数字化基座。
|
||||
本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。
|
||||
:::
|
||||
|
||||
## 解决什么问题？
|
||||
|
||||
Reference in New Issue
Block a user