DjangoBaseAi

Django 通用底座：在 Django + DRF 之上提供企业级底座（认证、RBAC、组织架构、操作/登录日志、文件与消息等），以及可选 AI 工作台 / IM。产品业务（对话、文档、PPT 等）放在消费方仓库，不要写进本包。

给 AI / 后续模块开发：先读 AGENT.md。

包名：django-base-ai（导入名：django_base_ai）
快速开始（pip 安装 + 配置步骤，无需 MySQL/Redis）：help/QUICKSTART.md
架构说明：help/ARCHITECTURE.md — 底座分层、AI 与扩展、集成方式
代码逻辑图：help/code-map/README.md — 总览、登录鉴权、RBAC、存储、扩展点

快速开始（首次使用）

使用 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 初始化菜单/角色/字典。对话与 PPT HTTP 接口在产品仓库，不在本包。

痛点与解决方案

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

技术信息

Python：3.9+

功能概览

主推：AI 能力

模块	说明
AI 客户端	`django_base_ai.utils.ai`：多供应商 Chat / 生图，供产品 app 调用
AI 工作台	`ai_desk_app_manage/` 与菜单权限打通（对话/PPT HTTP 在产品仓库）

配置 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/`	节假日（匿名，无需 Token；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）

对话 / PPT HTTP 路由不在本包，见消费方（如 DocsAI AIChat）。本包提供 django_base_ai.utils.ai 客户端与 ai_desk_app_manage/。

其他资源上的自定义 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。
user AI 记忆（仅当前登录用户，不进登录/用户列表）：

方法	路径	说明	返回值
GET	`user/ai_memory/`	读取本人长期记忆；无记录时 `content=""`、`version=0`	`data: { user_id, filename, content, version, update_datetime }`，`filename` 为 `USER_AI_MEMORY_{user_id}.md`
PUT/PATCH	`user/ai_memory/`	写入 Markdown（≤64KB）。可选 `version` 做乐观锁，冲突返回 `code=409`	同上，`version` 加一
DELETE	`user/ai_memory/`	清空正文（保留行，`version` 加一）。可选带 `version`	同上

Python 侧注入 prompt：get_user_ai_memory_markdown(user) / format_user_ai_memory_for_prompt(user)。记忆与空间级 agent_memory 分层，不写在 Users 上。

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 在项目中完成配置即可。

Windows / Linux 兼容：uwsgi、supervisor 为 Linux/macOS 生产部署工具，包内代码不依赖它们。pip 会根据 sys_platform 自动跳过 Windows 上的这两项（无需 --no-deps）；Windows 本地开发请用 python manage.py runserver 或 daphne。

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

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

[dev] 会安装 pytest、pytest-django、ruff。Linux 生产环境可额外执行 pip install django-base-ai[deploy] 显式安装 uwsgi/supervisor。

本地一键启动（对接 DjangoBaseAiWeb）

需同级存在前端仓库 DjangoBaseAiWeb（已 pnpm install）。

# 后端(:8075) + 前端 Vite(:5789)
./dev_run.sh

# 仅后端 / 仅前端
./dev_run.sh api
./dev_run.sh web

# 后端用 SQLite 快速开始（无需 MySQL/Redis）
ENV=quickstart ./dev_run.sh

访问：http://localhost:5789/。可用 FRONTEND_DIR / BACKEND_PORT / WEB_PORT 覆盖路径与端口。

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

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

安装：将本仓库可编辑安装或打包后安装到目标 Django 项目环境。
配置：在目标项目 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、文本润色等接口。
路由：在目标项目 urls.py 中挂载系统路由，即可暴露登录、用户/角色/部门、菜单、字典及 AI 对话/PPT/文本处理 等全部接口：
```
from django_base_ai.system.urls import urlpatterns as system_urls
urlpatterns = [..., path("base/api/system/", include(system_urls))]
```
初始化：执行迁移，并可通过 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。

Metadata

Release files for django-base-ai 1.0.95

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-base-ai 1.0.95
File	Size	Uploaded
django_base_ai-1.0.95.tar.gz	351.9 kB	Oct 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for django-base-ai 1.0.95
File	Interpreter	ABI	Platform	Reset
django_base_ai-1.0.95-py3-none-any.whl 13.8 MB Oct 8, 2026	Python 3	none	any	Details

Total release size: 14.2 MB

Release files / django_base_ai-1.0.95.tar.gz

Download URL	django_base_ai-1.0.95.tar.gz
Size	351.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`827edd05245205e38972ae21e75e603a72ef5111872df22f224248bd29834f91`
BLAKE2b-256 checksum How to use checksums	`e1a2a07355bf99d8a27d0a6dd6ba87a0fd29a0779a1092b0754c9d4c71068b1b`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.4`

Release files / django_base_ai-1.0.95-py3-none-any.whl

Download URL	django_base_ai-1.0.95-py3-none-any.whl
Size	13.8 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`474d7ce701b2a42862b4dc96fca1e713d799c9cd5dae5fd41881e1effd254ae6`
BLAKE2b-256 checksum How to use checksums	`5afa981e25d3e1982282d5935ce36a1cbe6a7bfb622f265747b42f2f67631e4b`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.4`