签入版本
This commit is contained in:
@@ -1,3 +1,5 @@
|
||||
# 新手入门指南
|
||||
|
||||
:::warning 特别提醒
|
||||
官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
# 1.1 项目介绍
|
||||
|
||||
:::tip 概述
|
||||
DjangoAdmin 是企业级中台解决方案，后端基于 Django + Django ORM，前端基于 Vue3 + AntDesign，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。
|
||||
:::
|
||||
|
||||
<div align="center">
|
||||
<p align="center">
|
||||
<img src="/logo.png" height="150" alt="logo"/>
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 贡献指南
|
||||
|
||||
:::tip 说明
|
||||
感谢你对本项目的关注！本文档介绍如何参与项目贡献，包括代码提交、Issue 反馈、PR 流程等。
|
||||
本页介绍如何参与项目贡献，包括代码提交、Issue 反馈与 PR 流程，欢迎关注本项目的开发者参阅。
|
||||
:::
|
||||
|
||||
## 开发环境搭建
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 免责声明
|
||||
|
||||
:::tip 概述
|
||||
使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。
|
||||
:::
|
||||
|
||||
:::danger 重要提示
|
||||
任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。
|
||||
:::
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 项目目录结构
|
||||
|
||||
:::tip 概述
|
||||
本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。
|
||||
:::
|
||||
|
||||
## 整体结构
|
||||
|
||||
```
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 完整代码清单
|
||||
|
||||
:::tip 概述
|
||||
本页汇总案例管理（Example）模块涉及的全部文件代码，开发时可快速查阅与复制对照。
|
||||
:::
|
||||
|
||||
本章汇总 Example 案例模块涉及的全部文件，便于开发时快速查阅和复制。
|
||||
|
||||
## 后端文件清单
|
||||
|
||||
@@ -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 + AntDesign 下一个完整 CRUD 页面的文件组成与编写方式。
|
||||
:::
|
||||
|
||||
前端页面视图是用户直接交互的界面。项目使用 Vue3 + Ant Design Vue + Vite 构建。一个完整的 CRUD 页面由 5 个文件组成：
|
||||
|
||||
```
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 表单验证（Form）
|
||||
|
||||
:::tip 概述
|
||||
表单验证是模块开发的第二步，讲解基于 Django ModelForm 的提交数据校验与错误信息约定。
|
||||
:::
|
||||
|
||||
表单验证是模块开发的第二步，用于对前端提交的数据进行验证。项目使用 Django 的 `ModelForm` 实现表单验证，所有错误信息使用中文提示。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 数据模型（Model）
|
||||
|
||||
:::tip 概述
|
||||
数据模型是模块开发的第一步，讲解如何用 Django ORM 与 BaseModel 定义数据库表结构，新建模块时从本页开始。
|
||||
:::
|
||||
|
||||
数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 Django ORM，模型类通过继承 `BaseModel` 自动获得通用字段。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 模块开发实战概述
|
||||
|
||||
:::tip 概述
|
||||
本章以案例管理（Example）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。
|
||||
:::
|
||||
|
||||
本章以「案例管理（Example）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。
|
||||
|
||||
## 你将学到什么
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 权限节点配置
|
||||
|
||||
:::tip 概述
|
||||
本页讲解接口权限字符串的定义与菜单权限节点的配置方法，联调 403 问题时对照本页。
|
||||
:::
|
||||
|
||||
后端代码中的 `permission_required = ("sys:example:page",)` 定义了接口所需的权限字符串，但权限节点本身需要在数据库中配置，才能在「菜单管理」中分配给角色。
|
||||
|
||||
## 权限字符串格式
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 业务逻辑层（Service）
|
||||
|
||||
:::tip 概述
|
||||
业务逻辑层是模块开发的核心，CRUD 操作、业务规则与数据处理均封装在 Service 层函数，本页讲解其编写规范。
|
||||
:::
|
||||
|
||||
业务逻辑层是模块开发的第三步，也是最核心的部分。所有 CRUD 操作、业务规则、数据处理都封装在 Service 层的独立函数中。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# URL 路由配置
|
||||
|
||||
:::tip 概述
|
||||
URL 路由是模块开发的最后一步，本页讲解用 Django path() 将路径映射到视图类的配置方法。
|
||||
:::
|
||||
|
||||
URL 路由是模块开发的最后一步，负责将 URL 路径映射到视图类。项目使用 Django 的 `path()` 函数定义路由，通过 `include()` 将模块路由注册到主路由。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 视图层（View）
|
||||
|
||||
:::tip 概述
|
||||
视图层负责处理 HTTP 请求并调用 Service 业务逻辑，本页讲解 Django 类视图的编写方式与响应约定。
|
||||
:::
|
||||
|
||||
视图层是模块开发的第四步，负责处理 HTTP 请求并调用 Service 层的业务逻辑。项目使用 Django 的类视图（Class-Based Views），每个视图类对应一个 API 端点。
|
||||
|
||||
## 文件位置
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 核心基类体系
|
||||
|
||||
:::tip 概述
|
||||
本页汇总项目核心基类体系的总览与用法，编写业务代码前先了解可复用的基座能力。
|
||||
:::
|
||||
|
||||
## 4.1 基类总览
|
||||
|
||||
核心基类体系由四大基类组成，覆盖从数据模型到请求校验再到响应输出的完整链路。子类只需声明差异点，即可获得标准化的增删改查能力。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 缓存架构
|
||||
|
||||
:::tip 概述
|
||||
本页说明系统缓存架构的设计与使用方式，涉及缓存一致性或性能问题时查阅。
|
||||
:::
|
||||
|
||||
## 4.1 缓存架构概述
|
||||
|
||||
项目使用 Redis 作为缓存后端，通过 Django 的缓存框架实现统一的缓存管理。缓存主要用于以下场景：
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 数据库设计
|
||||
|
||||
:::tip 概述
|
||||
本页说明数据库设计原则与表结构组织方式，建表或数据迁移时对照本页。
|
||||
:::
|
||||
|
||||
## 4.1 数据库设计概述
|
||||
|
||||
项目使用 MySQL 8.0 作为主数据库，通过 Django ORM 进行数据访问。所有业务表继承 BaseModel 抽象基类，自动获得 6 个通用字段。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 目录结构设计
|
||||
|
||||
:::tip 概述
|
||||
本页说明项目根目录与各层目录的组织设计，二次开发定位文件时对照查阅。
|
||||
:::
|
||||
|
||||
## 4.1 项目根目录
|
||||
|
||||
```
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 扩展性设计
|
||||
|
||||
:::tip 概述
|
||||
本页说明系统的扩展性设计原则，二次开发新增能力或改造现有模块时参考。
|
||||
:::
|
||||
|
||||
## 4.1 扩展性设计原则
|
||||
|
||||
项目遵循开闭原则（OCP）：对扩展开放，对修改关闭。新功能通过添加新模块实现，而非修改现有代码。系统通过 Django App 机制、代码生成器、模板定制等方式提供扩展能力。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 分层架构详解
|
||||
|
||||
:::tip 概述
|
||||
本页详解后端分层架构的职责划分与调用关系，编写代码前先理解各层边界。
|
||||
:::
|
||||
|
||||
## 4.1 分层架构概述
|
||||
|
||||
项目采用经典的五层架构设计，各层职责明确，依赖关系清晰：
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 系统架构总览
|
||||
|
||||
:::tip 概述
|
||||
本页给出系统整体架构总览，理解各层职责与模块关系时从本页开始。
|
||||
:::
|
||||
|
||||
## 4.1 整体架构
|
||||
|
||||
项目采用前后端分离的 B/S 架构，后端基于 Django 6.0.3 提供 RESTful API，前端基于 Vue3 + Ant Design Vue 构建单页应用。系统通过 Nginx 反向代理统一入口，实现静态资源托管与 API 转发。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 请求处理流程
|
||||
|
||||
:::tip 概述
|
||||
本页给出请求从进入路由到返回响应的全链路处理流程，排查接口问题时对照追踪。
|
||||
:::
|
||||
|
||||
## 4.1 请求处理全链路
|
||||
|
||||
一个完整的 HTTP 请求在 系统中的处理流程如下：
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 安全架构
|
||||
|
||||
:::tip 概述
|
||||
本页说明系统安全架构设计，含认证、权限与数据安全等防护机制。
|
||||
:::
|
||||
|
||||
## 4.1 安全架构概述
|
||||
|
||||
系统从认证、授权、防护三个维度构建安全体系：
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 第四章 架构设计 - 技术栈选型
|
||||
|
||||
:::tip 概述
|
||||
本页列出项目后端与前端完整技术选型及版本要求，评估兼容性或升级影响时对照本表。
|
||||
:::
|
||||
|
||||
## 4.1 后端技术栈
|
||||
|
||||
### Django 6.0.3
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 文章管理
|
||||
|
||||
:::tip 文章管理
|
||||
文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 分类管理
|
||||
|
||||
:::tip 分类管理
|
||||
分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 行政区划管理
|
||||
|
||||
:::tip 城市管理
|
||||
城市管理模块用于管理行政区划数据，支持省/市/区/街道/社区五级行政区划。通过 `parent_code` 字段实现树形结构。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 公告与链接管理
|
||||
|
||||
:::tip 公告/链接
|
||||
公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。适用于系统公告、友情链接等场景。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 部门/职级/岗位管理
|
||||
|
||||
:::tip 部门/职级/岗位
|
||||
部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 定时任务
|
||||
|
||||
:::tip 定时任务
|
||||
定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）两个子模块。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 菜单管理
|
||||
|
||||
:::tip 菜单管理
|
||||
菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 参数管理
|
||||
|
||||
:::tip 参数管理
|
||||
参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 角色管理
|
||||
|
||||
:::tip 角色管理
|
||||
角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 用户管理
|
||||
|
||||
:::tip 用户管理
|
||||
用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划等功能。与简单 CRUD 模块不同，用户管理使用自定义 service 函数。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 验证码机制
|
||||
|
||||
:::tip 验证码
|
||||
验证码是防止自动化攻击的重要安全手段。项目使用 django-simple-captcha 库生成图片验证码，存储在数据库中，支持多种验证码格式。源码位于 `application/login/views.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 系统配置管理
|
||||
|
||||
:::tip 系统配置
|
||||
系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `application/config/`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 跨域资源共享（CORS）
|
||||
|
||||
:::tip CORS跨域
|
||||
CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。项目使用 `django-cors-headers` 中间件处理跨域请求，通过 `.env` 配置允许的跨域源。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 演示模式
|
||||
|
||||
:::tip 演示模式
|
||||
演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `DJANGO_DEMO` 环境变量控制。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 字典模块
|
||||
|
||||
:::tip 数据字典
|
||||
数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。模块位于 `application/dict/`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 异常与响应处理
|
||||
|
||||
:::tip 全局异常与响应
|
||||
定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式。响应函数位于 `utils/R.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 防重复提交
|
||||
|
||||
:::tip 防重复提交
|
||||
防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 用户认证（JWT）
|
||||
|
||||
:::tip JWT认证
|
||||
JWT（JSON Web Token）是系统的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `utils/jwt.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 登录日志
|
||||
|
||||
:::tip 登录日志
|
||||
登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。登录逻辑位于 `application/login/services.py`，日志记录位于 `application/login_log/` 模块。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 操作日志
|
||||
|
||||
:::tip 操作日志
|
||||
操作日志通过 `@operation_log` 装饰器标记需要记录日志的视图方法，自动记录请求参数、响应结果、耗时、操作类型等信息。源码位于 `application/operation_log/decorators.py`。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 请求限流
|
||||
|
||||
:::tip 请求限流
|
||||
请求限流可通过中间件实现 IP 级别的限流，防止恶意请求和 DoS 攻击。项目中限流可通过 Nginx 反向代理或自定义中间件实现。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 权限管理（RBAC）
|
||||
|
||||
:::tip RBAC权限
|
||||
采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `PermissionRequired` 混入类校验（`middleware/permission_middleware.py`），前端通过 `v-perm` 指令控制按钮显隐。
|
||||
:::
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# 参数验证（Form）
|
||||
|
||||
:::tip 参数验证
|
||||
使用 Django ModelForm 进行请求参数验证。所有请求体参数通过 Django Form 定义，视图中调用 `form.is_valid()` 自动验证，验证失败通过 `regular.get_err()` 提取错误信息返回前端。
|
||||
:::
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 为什么选择我们
|
||||
|
||||
:::tip 概述
|
||||
本页从低代码生成能力、功能开箱即用与工程可持续性三个维度说明选择本项目的理由，技术选型对比时可作为评估依据。
|
||||
:::
|
||||
|
||||
## 低代码生成，开发效率倍增
|
||||
|
||||
项目最大的特点是代码生成器。只需在数据库中建好表，一条命令即可生成完整的前后端 CRUD 模块：
|
||||
|
||||
Reference in New Issue
Block a user