django-base-ai 1.0.44

Django/DRF/RBAC 权限与常用 AI 接口封装

DjangoBaseAi

Django 通用底座，主推 AI：在 Django + DRF 之上提供 AI 对话、PPT 生成、文本润色/翻译 等开箱即用能力，并配套企业级底座（认证、RBAC、组织架构、操作/登录日志、文件与消息等），安装后一键集成，快速落地 AI 应用与权限体系。

• 包名：django-base-ai（导入名：django_base_ai）
• 快速开始（pip 安装 + 配置步骤，无需 MySQL/Redis）：help/QUICKSTART.md
• 架构说明：help/ARCHITECTURE.md — 底座分层、AI 与扩展、集成方式

---

快速开始（首次使用）

使用 pip 安装，在新建或已有 Django 项目中按文档配置即可，无需克隆仓库、无需 MySQL/Redis（SQLite + 内存缓存）。

pip install django-base-ai
django-admin startproject myproject && cd myproject

然后在项目的 settings.py 中先 from django_base_ai.settings import *，再按 help/QUICKSTART.md 配置数据库（SQLite）、缓存（内存）、INSTALLED_APPS、MIDDLEWARE、路由等；执行 migrate、runserver 即可访问。建议再执行 python manage.py init 初始化菜单/角色/字典，并配置 AI Key 后使用对话与 PPT 等接口。

---

痛点与解决方案

痛点	解决方案
想快速接入大模型能力，又不想从零搭权限与基础	主推 AI：多轮对话（含流式）、PPT 大纲/配图/布局、文本润色/翻译等开箱即用；底座提供认证、RBAC、日志，一次集成同时具备 AI + 企业规范
企业系统权限需求复杂，自建 RBAC 成本高、易遗漏	完整 RBAC：用户、角色、部门、菜单、按钮权限、接口白名单、数据权限过滤，开箱即用
国内大型企业组织架构明确、层级多、权限要求严	部门树、懒加载、数据权限按部门/角色过滤，贴合「组织架构清晰、权限分级严格」的国内企业场景
每个项目重复实现登录、字典、文件、日志等基础能力	统一认证（JWT、单点登录、验证码）、字典/系统配置、文件与文件夹、操作日志、消息中心等一应俱全
希望快速接入企业规范，而非从零搭架子	安装依赖、配置 INSTALLED_APPS 与路由后，一键集成到现有 Django 项目，无需重写权限与基础模块

技术信息

• Python：3.9+

---

功能概览

主推：AI 能力

模块	说明
AI 对话	会话管理、多轮对话（含流式）、多模型/多供应商（DeepSeek、腾讯混元、OpenAI、自定义）
PPT 生成	根据主题生成大纲、单页重生成、配图 prompt/通义万相生图、布局规范与拼装
文本处理	续写、重写、缩写、扩写、润色、校润、翻译等
AI 工作台	工作台应用管理（ai_desk_app_manage），与菜单与权限打通

配置 AI 供应商（见 conf/env.py 或文档）后即可使用，无需改业务代码。

底座核心（通用能力，支撑 AI 与业务）

模块	说明
认证	JWT（SimpleJWT）、单点/第三方登录、验证码、登出、Token 刷新
RBAC	用户、角色、部门、菜单、按钮权限、接口白名单、数据权限过滤
系统配置	字典、系统配置键值、调度中心（dispatch）、初始化接口
审计与日志	操作日志、登录日志、日志文件分析/下载/实时 tail
文件与存储	文件夹、文件上传/列表/下载、导入导出（Excel）
消息与协作	消息中心、常用联系人、协作人、我的上级、WebSocket
任务与配置	基础任务、任务历史、应用/标签、数据可视化配置
工具	统一 JSON 响应、分页、异常处理、权限校验、加解密、节假日、健康检查等

其他扩展（按需使用）

模块	说明
IM	会话、单聊、群聊、问题分组、问答、聊天记录
数据分析	通用分析视图（base_analyze）

---

统一响应格式

除流式接口与 WebSocket 外，接口均采用以下 JSON 结构。

成功

分页列表（list 等）：

{
  "code": 2000,
  "msg": "success",
  "data": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "is_next": true,
    "is_previous": false,
    "data": [ /* 当前页列表 */ ]
  }
}

单条/非分页（retrieve、create、update、部分自定义接口）：

{
  "code": 2000,
  "msg": "success",
  "data": { /* 单条对象或业务结构 */ }
}

错误

{
  "code": 400,
  "msg": "错误说明",
  "data": null
}

业务错误码可能为 4xxx（如 4000 登录失败、401 未授权等），status 为 HTTP 状态码。

---

暴露的 API 接口

以下路径均以 /base/api/system/ 为前缀（由主项目 urls.py 挂载决定）。

---

认证与登录（无需 Token）

方法	路径	说明	返回值
POST	login/	用户名密码登录（可选验证码）	{ code, msg, data: { access, refresh, name, userId, avatar, user_type, skin, pwd_defaulted, user_config, is_staff, dept_info?, role_info? } }
POST	sign_login/	单点登录/第三方集成	同上结构
POST	custome_login/	自定义登录	同上结构
GET	captcha/	获取图形验证码	data: { key, image_base }（base64 图片）
GET	init/dictionary/	初始化字典（query: dictionary_key，all 或父 value）	分页或列表格式，data 为字典项列表
GET	init/settings/	初始化系统配置（query: key，可选，多 key 用 | 分隔）	data: 键值对配置

Token 与登出（需 Token）

方法	路径	说明	返回值
POST	token/refresh/	刷新 JWT	{ code, msg, data: { access, refresh } }（注意：序列化器可能返回 code=0，视图再封装为 Response）
POST	logout/	登出，使当前 token 失效	{ code: 2000, msg: "注销成功", data: null }

---

系统配置扩展

方法	路径	说明	返回值
PUT	system_config/save_content/	保存配置内容	DetailResponse
GET	system_config/get_association_table/	获取关联表配置	分页格式，data.data 为表数据
GET	system_config/get_table_data/<pk>/	获取指定表数据	DetailResponse
GET	system_config/get_relation_info/	查询关联模板信息（query: varName, table, relationIds）	DetailResponse 或 ErrorResponse
GET	system_config/check/	项目安全依赖检查（Admin）	data: { timestamp, pkg_count, vulnerabilities_count, vulnerabilities }
GET	system_config/vulnerabilities_count/	漏洞包总数（Admin）	data: 数字

---

部门扩展

方法	路径	说明	返回值
GET	dept_lazy_tree/	部门懒加载树	DetailResponse，树形结构

---

节假日与 WebSocket

方法	路径	说明	返回值
GET	holiday/	节假日（query: type=0 当天/1 指定日期/2 全部，day 为日期）	data: 当天信息或 day_infos 列表
GET	ws	WebSocket 连接（消息中心等）	非 JSON，WebSocket 协议

---

资源型 CRUD（标准 REST）

以下资源均支持：GET 列表（分页）、POST 创建、GET /{id}/ 详情、PUT/PATCH /{id}/ 更新、DELETE /{id}/ 删除。返回格式见「统一响应格式」。

资源路径	说明
menu/	菜单
menu_button/	菜单按钮
role/	角色
dept/	部门
user/	用户
operation_log/	操作日志
dictionary/	字典
area/	区域
folder/	文件夹
file/	文件
api_white_list/	接口白名单
system_config/	系统配置（CRUD）
message_center/	消息中心
message_center_target_user/	消息中心目标用户
frequently_used_contacts/	常用联系人
datav/	数据可视化配置
task/	基础任务
task_run_history/	任务运行历史
apps/	应用管理
tags/	标签
collaborator/	协作人
my_superiors/	我的上级
ai_desk_app_manage/	AI 工作台应用管理
im_session/	IM 会话
im_chat_to_user/	IM 单聊
im_chat_question_group/	IM 问题分组
im_chat_question/	IM 问题
im_chat_to_group/	IM 群聊
im_chat_to_group_message/	IM 群消息
im_chat_qa/	IM 问答
im_chat_record_form/	IM 聊天记录表单
login_log/	登录日志
base_analyze/	数据分析（ViewSet，多为 GET 自定义 action）
ai_chat_session/	AI 会话（CRUD + 下列自定义 action）

---

AI 会话与对话（ai_chat_session）

方法	路径	说明	返回值
POST	ai_chat_session/chat/	发消息并获取 AI 回复（支持 stream、附件）	非流式：data: { content, usage, model, session_id, message_id }；流式：text/event-stream
POST	ai_chat_session/generate_ppt_outline/	根据主题生成 PPT 大纲	data: { outline: [{ title, points }], raw, model, usage }
POST	ai_chat_session/regenerate_ppt_outline_page/	单页重新生成大纲	data: { slide: { title, points }, page_index, raw, model, usage }
POST	ai_chat_session/generate_ppt_slide_image_prompt/	生成单页配图描述与关键词	data: { image_prompt, image_keywords, suggestion, model, usage }
POST	ai_chat_session/generate_ppt_slide_image/	生成单页配图（通义万相）	data: { image_url, image_urls, image_prompt, image_keywords, suggestion, error? }
GET	ai_chat_session/get_ppt_slide_layout_spec/	PPT 单页布局规范与模板	data: { schema, templates }
POST	ai_chat_session/build_ppt_slides/	根据大纲与图片 URL 拼装每页布局	data: { slides: [{ title, body, image, layout_id }, ...] }
POST	ai_chat_session/text_refine/	文本处理：续写/重写/缩写/扩写/润色/校润/翻译	data: { content, operation, operation_name, model, usage }

---

其他资源上的自定义 Action（选列）

• dictionary：GET dictionary/dictionary_tree/?value=xxx → 指定节点递归树，DetailResponse。
• role：role/role_list/、role/role_id_list/、role/tree/、role/open/ 等，见 role.py。
• user：user/user_list/、user/export/、user/import/、user/update_user_info/、user/reset_password/、user/change_avatar/ 等，见 user.py。
• menu：menu/tree/ 等。
• dept：dept_lazy_tree/ 已单独列出；另有 dept/tree/、dept/export/、dept/import/ 等。
• file：上传、下载、自定义 action 见 file_list.py。
• message_center：已读、未读、推送等 action。
• task：task/run/、task/update_task_status/ 等。
• login_log：自定义统计等 action。
• base_analyze：多种 GET/POST 分析接口（AllowAny），见 base_analyze.py。

具体请求参数与字段以各 ViewSet 内 docstring 及 serializer 为准。

---

安装

首次使用：直接执行 pip install django-base-ai，再按 help/QUICKSTART.md 在项目中完成配置即可。

从源码开发/可编辑安装（本仓库克隆后）：

pip install -r requirements.txt
# 或 pip install -e ".[dev]"

[dev] 会安装 pytest、pytest-django、ruff。

---

在项目中使用（一键集成）

安装 DjangoBaseAi 后，按以下步骤即可将 AI 能力与底座（RBAC、组织架构与基础能力） 一键集成到现有 Django 项目。

1. 安装：将本仓库可编辑安装或打包后安装到目标 Django 项目环境。
2. 配置：在目标项目 settings.py 中：
   • 将 django_base_ai.system 加入 INSTALLED_APPS
   • 按需配置数据库、缓存、JWT、CORS 等（可参考本仓库 django_base_ai/settings.py）
   • 自定义异常处理：EXCEPTION_HANDLER = "django_base_ai.utils.exception.custom_exception_handler"
   • 主推 AI：在 conf/env.py 或环境中配置 AI_DEFAULT_PROVIDER 与对应 AI_*_API_KEY（如 DeepSeek/腾讯/OpenAI），即可使用对话、PPT、文本润色等接口。
3. 路由：在目标项目 urls.py 中挂载系统路由，即可暴露登录、用户/角色/部门、菜单、字典及 AI 对话/PPT/文本处理 等全部接口：

   from django_base_ai.system.urls import urlpatterns as system_urls
   urlpatterns = [..., path("base/api/system/", include(system_urls))]
   

4. 初始化：执行迁移，并可通过 django_base_ai.dispatch 及 system fixtures 初始化菜单、角色、字典等。

---

项目结构（简要）

详见 help/ARCHITECTURE.md 中的包内结构与分层说明。

DjangoBaseAi/
├── django_base_ai/          # 底座主包（供其他项目安装引用）
│   ├── dispatch.py          # 系统配置/字典调度入口
│   ├── settings.py          # 默认配置（DRF、JWT、分页、认证、日志等）
│   ├── system/              # 唯一应用：底座核心 + 可选扩展（模型、视图、fixtures、management）
│   ├── utils/               # 工具：认证、权限、响应、分页、异常、导入导出、AI 基座等
│   ├── websocket/           # WebSocket 路由与配置
│   └── templates/
├── help/                    # 架构与规范（ARCHITECTURE.md、COMMENT_AND_LOGGING.md）
├── DjangoBaseAi/            # 本仓库作为可运行项目时的入口（settings、asgi、urls）
├── conf/                    # 环境配置（quickstart/env/test/pro，见 QUICKSTART）
├── tests/                   # pytest 测试
├── pyproject.toml
├── requirements.txt
└── README.md

---

开发约定（与 Rules/python.mdc 一致）

• PEP 8：全包使用小写+下划线命名，ruff format . 与 ruff check . 通过后再提交。
• 类型与文档：新代码与核心模块使用类型注解与 docstring。
• 测试：使用 pytest，DJANGO_SETTINGS_MODULE 已写在 pyproject.toml，在项目根执行 pytest 即可。

常用命令

ruff format .
ruff check . --fix
pytest
pytest tests/ -v
pip install build && python -m build

---

许可证

见仓库根目录 LICENSE。