djangoadmin-wiki/DjangoAdmin_Django_NaiveVue/public/llms.txt

# DjangoAdmin Django+NaiveUI 开发文档

> DjangoAdmin 企业级中台解决方案 - Django + NaiveUI 前后端分离版本。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 135 篇，按章节组织。

## 1. 了解项目

- [1.1 项目介绍](http://docs.django.naivevue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 Django + Django ORM，前端基于 Vue3 + NaiveUI，内置 RBAC 权限、代码生成器等开箱即用功能，
- [更新日志](http://docs.django.naivevue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。
- [新手入门指南](http://docs.django.naivevue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。
- [项目目录结构](http://docs.django.naivevue.djangoadmin.cn/zh/struct.html): 本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。
- [为什么选择我们](http://docs.django.naivevue.djangoadmin.cn/zh/why.html): 本页从低代码生成能力、功能开箱即用与工程可持续性三个维度说明选择本项目的理由，技术选型对比时可作为评估依据。

## 2. 快速入门

- [后端启动](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。
- [数据库初始化](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DATABASE_ENGINE 和数据库连接信息已正确配置 3.
- [Docker 一键启动](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker
- [环境变量速查表](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env 文件包含项目的敏感配置信息，已被 .gitignore 忽略，不会提交到版本控制。
- [环境准备](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。
- [常见问题FAQ](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。
- [第一个接口调试](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动
- [前端启动](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。

## 3. 模块开发实战

- [完整代码清单](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总案例管理（Example）模块涉及的全部文件代码，开发时可快速查阅与复制对照。
- [常见问题与排错](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。
- [前端 API 层](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。
- [前端路由与菜单](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。
- [前端页面视图](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + NaiveUI 下一个完整 CRUD 页面的文件组成与编写方式。
- [表单验证（Form）](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/form.html): 表单验证是模块开发的第二步，讲解基于 Django ModelForm 的提交数据校验与错误信息约定。
- [数据模型（Model）](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/model.html): 数据模型是模块开发的第一步，讲解如何用 Django ORM 与 BaseModel 定义数据库表结构，新建模块时从本页开始。
- [模块开发实战概述](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/overview.html): 本章以案例管理（Example）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。
- [权限节点配置](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/permission.html): 本页讲解接口权限字符串的定义与菜单权限节点的配置方法，联调 403 问题时对照本页。
- [业务逻辑层（Service）](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/service.html): 业务逻辑层是模块开发的核心，CRUD 操作、业务规则与数据处理均封装在 Service 层函数，本页讲解其编写规范。
- [URL 路由配置](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/url.html): URL 路由是模块开发的最后一步，本页讲解用 Django path() 将路径映射到视图类的配置方法。
- [视图层（View）](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/view.html): 视图层负责处理 HTTP 请求并调用 Service 业务逻辑，本页讲解 Django 类视图的编写方式与响应约定。

## 4. 架构设计

- [第四章 架构设计 - 核心基类体系](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/base-classes.html): 本页汇总项目核心基类体系的总览与用法，编写业务代码前先了解可复用的基座能力。
- [第四章 架构设计 - 缓存架构](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/cache.html): 本页说明系统缓存架构的设计与使用方式，涉及缓存一致性或性能问题时查阅。
- [数据库设计指南](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/database-design-guide.html): 本文介绍本项目的数据库设计规范，包括表命名、字段类型选择、索引策略、常见表模式等。
- [第四章 架构设计 - 数据库设计](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/database-design.html): 本页说明数据库设计原则与表结构组织方式，建表或数据迁移时对照本页。
- [第四章 架构设计 - 目录结构设计](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/directory.html): 本页说明项目根目录与各层目录的组织设计，二次开发定位文件时对照查阅。
- [第四章 架构设计 - 扩展性设计](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/extensibility.html): 本页说明系统的扩展性设计原则，二次开发新增能力或改造现有模块时参考。
- [第四章 架构设计 - 分层架构详解](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/layer-arch.html): 本页详解后端分层架构的职责划分与调用关系，编写代码前先理解各层边界。
- [第四章 架构设计 - 系统架构总览](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/overview.html): 本页给出系统整体架构总览，理解各层职责与模块关系时从本页开始。
- [性能优化指南](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/performance.html): 本文介绍本项目中常见的性能优化策略，涵盖后端 ORM 查询、缓存、分页、前端加载等方面。
- [第四章 架构设计 - 请求处理流程](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/request-flow.html): 本页给出请求从进入路由到返回响应的全链路处理流程，排查接口问题时对照追踪。
- [第四章 架构设计 - 安全架构](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/security.html): 本页说明系统安全架构设计，含认证、权限与数据安全等防护机制。
- [第四章 架构设计 - 技术栈选型](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/tech-stack.html): 本页列出项目后端与前端完整技术选型及版本要求，评估兼容性或升级影响时对照本表。

## 5. 开发指南

- [API 接口速查表](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。
- [文章管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。
- [分类管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。
- [行政区划管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/city.html): 城市管理模块用于管理行政区划数据，支持省/市/区/街道/社区五级行政区划。
- [公告与链接管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/content.html): 公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。
- [部门/职级/岗位管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。
- [定时任务](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。
- [菜单管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。
- [参数管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。
- [角色管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。
- [用户管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。
- [认证流程实战](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 -> Token 获取 -> 权限校验 -> Token 刷新 -> 退出登录的完整认证链路实战说明。
- [验证码机制](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。
- [系统配置管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。
- [跨域资源共享（CORS）](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。
- [演示模式](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。
- [数据字典使用指南](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。
- [字典模块](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。
- [异常与响应处理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/exception.html): 定义了统一的响应格式和全局异常处理机制。
- [防重复提交](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。
- [用户认证（JWT）](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是系统的核心认证机制。
- [登录日志](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。
- [操作日志](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志通过 @operation_log 装饰器标记需要记录日志的视图方法，自动记录请求参数、响应结果、耗时、操作类型等信息。
- [请求限流](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/rate-limit.html): 请求限流可通过中间件实现 IP 级别的限流，防止恶意请求和 DoS 攻击。
- [权限管理（RBAC）](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/rbac.html): 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。
- [参数验证（Form）](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/validator.html): 使用 Django ModelForm 进行请求参数验证。
- [API 层开发](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。
- [前端构建](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。
- [公共组件库](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 NaiveUI 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。
- [BasicForm 表单](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 NaiveUI 的 n-form 二次封装，通过 schemas 配置化定义表单字段，
- [Hooks 组合式函数](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。
- [国际化](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，NaiveUI 使用中文语言包（zhCN），所有界面文本直接硬编码在组件中。
- [Modal 弹窗](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目使用 basicModal 组件（src/components/Modal/src/BasicModal.vue）配合 useModal hook 实现弹窗。
- [权限指令 v-perm](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。
- [路由与菜单](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。
- [前端环境与结构](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + NaiveUI 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。
- [Store 状态管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。
- [样式与主题](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + SCSS + NaiveUI 主题覆盖，支持深色模式切换。
- [BasicTable 表格](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 NaiveUI 的 n-data-table 二次封装，提供列定义、数据请求、分页、操作列、
- [工具函数](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。
- [页面视图开发](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）+ detail.vue（详情弹窗）的标准模式，辅以
- [接口响应规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。
- [字典数据联调](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。
- [权限节点联动](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 PermissionRequired 中间件校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。
- [代理配置](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端 Django 服务，生产环境通过 Nginx 代理。
- [文件上传联调](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。
- [数据库与 ORM](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/db-session.html): 项目使用 Django ORM 作为数据库访问层，数据库连接配置位于 config/env.py 和 application/settings.py。
- [导入导出](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/excel.html): 基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。
- [IP/UA 解析](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力，位于 utils/common.py。
- [日志系统](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/logger.html): 通过 Python 标准库 logging 实现结构化日志，Django 框架内置日志配置，支持控制台 + 文件双输出。
- [密码工具](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/password.html): 密码加密使用 Django 内置的 make_password 和 check_password 函数，基于 PBKDF2 算法（默认工作因子 320000 次迭代）。
- [权限缓存](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。
- [请求解析工具](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/request-util.html): utils/common.py 提供请求数据解析相关的工具函数，核心函数 parse_request_body() 用于解析请求体 JSON 数据。
- [富文本过滤](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，通过 save_content() 函数实现 HTML 内容处理，在落盘前统一过滤危险内容并迁移嵌入图片。
- [文件上传完整流程](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 WangEditor 等）的图片上传同样使用此接口。
- [文件上传](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/upload.html): 提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单校验。

## 6. 代码生成器

- [CLI 命令行使用](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、预览模式和配置导出。
- [代码生成引擎](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。
- [配置文件详解](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性等配置项的详细解释。
- [实战案例](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/demo.html): 以 django_example 演示表为完整案例，演示从建表到生成到使用的全流程。
- [常见问题](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。
- [概述与架构](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。
- [表结构解析引擎](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。
- [自定义模板](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。
- [Web 管理界面](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。

## 7. 运维部署

- [备份与恢复](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难）
- [CI/CD 流水线配置](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/ci-cd.html): CI/CD（持续集成/持续部署）是现代开发流程的基础设施。
- [数据库迁移](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Django 内置迁移系统（makemigrations + migrate） - 字段注释：Django 4.1+ 通过 db_comment 参数自动添加数据库字段注释
- [部署 Checklist](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。
- [Docker容器化](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦
- [环境规划](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。
- [健康检查与监控](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 ``
- [Nginx 反向代理](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 -> Nginx（80/443） ├─ / -> 前端静态资源（dist/） ├─ /api/... -> Django 后端（8000） ├─ /static/ -> Django
- [性能调优](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果
- [多实例与负载均衡](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/scaling.html): 当单台服务器无法满足性能需求时，需要通过多实例部署和负载均衡来提升系统吞吐量。
- [安全加固](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项
- [Supervisor进程管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程
- [故障排查手册](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3.
- [版本升级流程](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级

## 8. 规范标准

- [API响应规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok
- [代码审查清单](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价
- [代码风格与 Lint 规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/code-style.html): 统一的代码风格是团队协作的基础。
- [删除规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = False（0）：正常记录（默认值） - is_delete = True（1）：已删除记录 - 所有查询方法自动过滤 is_delete=False，业务层无需关心
- [文档规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行
- [前端 API 规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由
- [前端页面规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - NaiveUI - 自定义组件（BasicTable / BasicForm / TableAction /
- [Form层规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/form.html): - 继承 forms.ModelForm - 每个字段定义中文 error_messages - 使用 Meta.fields 指定验证字段 - 验证在 Service 层 ORM 操作之前执行
- [Git提交规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> ``
- [Model层规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/model.html): - 所有模型继承 BaseModel - 字段命名使用 snake_case - 每个字段必须有 db_comment 注释 - 使用 get_table_name() 生成表名
- [分页规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回 {records, total, size, current, pages} 结构 - 默认每页 10
- [Service层规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/service.html): - 所有业务逻辑集中在 Service 层 - View 层只负责接收请求和返回响应 - Model 层只负责数据定义 - Form 层只负责数据验证
- [测试最佳实践](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/testing-best-practices.html): 本文在 测试规范 基础上，介绍更高级的测试技巧，包括 Mock、Fixture、API 测试、覆盖率实战等。
- [测试规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/testing.html): 1. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 2. 集成测试（Integration）：验证模块间协作、真实数据库操作
- [View层规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/view.html): - 使用类视图（继承 View） - 通过 @method_decorator(check_login) 验证登录 - 通过 PermissionRequired mixin 检查权限 - 通过

## 附录

- [常见问题汇总](http://docs.django.naivevue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。
- [贡献指南](http://docs.django.naivevue.djangoadmin.cn/zh/other/contributing.html): 本页介绍如何参与项目贡献，包括代码提交、Issue 反馈与 PR 流程，欢迎关注本项目的开发者参阅。
- [免责声明](http://docs.django.naivevue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。
- [广告赞助](http://docs.django.naivevue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4.