# DjangoBaseAi

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

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

---

## 快速开始（首次使用）

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

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

然后在项目的 `settings.py` 中先 `from django_base_ai.settings import *`，再按 [help/QUICKSTART.md](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` 等）：

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

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

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

### 错误

```json
{
  "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](help/QUICKSTART.md) 在项目中完成配置即可。

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

```bash
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/文本处理** 等全部接口：
   ```python
   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](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` 即可。

### 常用命令

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

---

## 许可证

见仓库根目录 `LICENSE`。
