DjangoBaseAi

Django 通用底座，主推 AI：在 Django + DRF 之上提供 AI 对话、PPT 生成、文本润色/翻译 等 Python API，并配套企业级底座（认证、RBAC、组织架构、操作/登录日志、文件与消息等）。安装后挂载路由即可使用权限与基础能力；大模型能力通过 django_base_ai.utils.ai 调用（当前包未暴露 ai_chat_session HTTP 路由）。

• 包名：django-base-ai（导入名：django_base_ai）
• Agent 编码指南（对外 API 全量，避免重复造轮子）：AGENT.md（pip 安装后位于 django_base_ai/AGENT.md）
• 快速开始（pip 安装 + 配置步骤）：help/QUICKSTART.md
• 架构说明：help/ARCHITECTURE.md
• RSA 私钥部署：docs/RSA_KEY_ROTATION.md、django_base_ai/utils/keys/README.md

快速开始（首次使用）

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

在 settings.py 中 from django_base_ai.settings import *，再按 help/QUICKSTART.md 配置数据库、缓存、INSTALLED_APPS、中间件与路由。然后：

python manage.py migrate
python manage.py init                 # 菜单 / 角色 / 字典等 fixtures
python manage.py init_dispatch_cache  # 配置与字典写入缓存（勿依赖应用启动钩自动初始化）
python manage.py runserver

需要字段加密（EncrypyField）时，由宿主应用配置私钥（不要写进仓库或 wheel）：

export RSA_PRIVATE_KEY_PATH=/path/to/private.pem
# 或
export RSA_PRIVATE_KEY_PEM="-----BEGIN RSA PRIVATE KEY-----..."

配置 AI Key 后即可在业务代码中使用 ChatSession 等 Python API。

痛点与解决方案

技术信息

• Python：3.9+
• Django：5.2.x（见 pyproject.toml）

功能概览

主推：AI 能力（Python API）

说明：历史文档中的 ai_chat_session/* HTTP 接口当前未注册。需要 HTTP 时请业务项目自行封装 ViewSet，或直接调用 Python API。以 AGENT.md 为准。

底座核心

其他扩展

安全与部署要点（整改后）

更多细节见 AGENT.md §0.1 / §8。

统一响应格式

除流式接口与 WebSocket 外，接口均采用：

分页列表：

{
  "code": 2000,
  "msg": "success",
  "data": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "is_next": true,
    "is_previous": false,
    "data": []
  }
}

单条 / 非分页：

{ "code": 2000, "msg": "success", "data": {} }

错误（ErrorResponse 默认 HTTP 400；未处理异常 HTTP 500，不回传堆栈）：

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

权限拒绝为 HTTP 403。

暴露的 HTTP API（摘要）

路径前缀默认 /base/api/system/。完整 action 表见 AGENT.md。

认证与初始化

资源型 CRUD

多数资源支持标准 list/create/retrieve/update/destroy。例外：

• datav/：仅统计类 action（如 users_total/），无 list
• base_analyze/：仅分析 action，默认管理员
• ai_chat_session/：未注册

常见资源：menu/、role/、dept/、user/、file/、dictionary/、system_config/、message_center/、task/、apps/、login_log/、operation_log/、IM 系列、ai_desk_app_manage/ 等。

文件（安全）

WebSocket（ASGI）

ws/base/<nid>/

认证：Authorization: Bearer <token>，或连接后首帧 {"type":"auth","token":"..."}。

安装

pip install django-base-ai

Windows / Linux：uwsgi、supervisor 仅非 Windows 安装；本地可用 runserver / daphne。

源码开发：

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

Linux 生产可 pip install django-base-ai[deploy]。

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

1. 安装包到目标环境。
2. 配置 settings.py：
   • INSTALLED_APPS 加入 django_base_ai.system
   • EXCEPTION_HANDLER = "django_base_ai.utils.exception.custom_exception_handler"
   • 按需配置 JWT、CORS、AI Key、RSA 私钥环境变量
3. 路由：

   path("base/api/system/", include("django_base_ai.system.urls"))
   

4. ASGI（消息推送）：挂载 django_base_ai.websocket.routing.websocket_urlpatterns
5. 初始化：migrate → init → init_dispatch_cache
6. 运维（可选）：定时 sync_operation_log

项目结构（简要）

DjangoBaseAi/
├── django_base_ai/          # 可安装主包
│   ├── dispatch.py
│   ├── settings.py
│   ├── system/              # 模型、视图、fixtures、management
│   ├── utils/               # 认证、权限、AI、RSA、XSS…
│   ├── websocket/           # ws/base/<nid>/
│   └── AGENT.md
├── docs/                    # RSA 轮换等运维说明
├── help/                    # QUICKSTART、ARCHITECTURE
├── conf/                    # quickstart / env / test / pro
├── tests/                   # 含 tests/security 回归
├── pyproject.toml
└── README.md

开发约定

• PEP 8：ruff format . 与 ruff check . 通过后再提交。
• 测试：ENV=quickstart pytest（安全专项：pytest tests/security）。
• 构建：清理 build/ 后打包；解包确认无 init_users.json / 私钥。

ruff format .
ruff check .
ENV=quickstart pytest -q
python -m build   # 或项目 build.sh；构建前 rm -rf build dist

许可证

见仓库根目录 LICENSE。