Metadata-Version: 2.4
Name: django-base-ai
Version: 1.0.67
Summary: Django/DRF/RBAC 权限与常用 AI 接口封装
Author-email: cx <2256807897@qq.com>
License-Expression: MIT
Project-URL: Bug Tracker, http://congxing.wang
Classifier: Environment :: Web Environment
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django<6.0,>=5.2.11
Requires-Dist: djangorestframework>=3.16.1
Requires-Dist: django-cors-headers>=4.9.0
Requires-Dist: django-filter>=25.2
Requires-Dist: django-redis>=6.0.0
Requires-Dist: django-guardian>=3.2.0
Requires-Dist: daphne>=4.2.1
Requires-Dist: channels>=4.3.2
Requires-Dist: djangorestframework-simplejwt>=5.5.1
Requires-Dist: PyMySQL>=1.1.2
Requires-Dist: requests>=2.32.5
Requires-Dist: httpx>=0.28.1
Requires-Dist: pypinyin>=0.47.1
Requires-Dist: pycryptodome>=3.23.0
Requires-Dist: pillow>=12.1.0
Requires-Dist: whitenoise>=6.11.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: django-user-agents>=0.4.0
Requires-Dist: django-restql>=0.18.0
Requires-Dist: django-celery-beat>=2.8.1
Requires-Dist: django-celery-results>=2.6.0
Requires-Dist: django-comment-migrate>=0.1.7
Requires-Dist: django-simple-captcha>=0.6.3
Requires-Dist: django-timezone-field>=1.0
Requires-Dist: xmltodict>=1.0.2
Requires-Dist: python-pptx>=0.6.23
Requires-Dist: dashscope>=1.20.0
Requires-Dist: bleach>=6.3.0
Requires-Dist: tinycss2>=1.5.1
Requires-Dist: jinja2>=3.1.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: supervisor>=4.3.0; sys_platform != "win32"
Requires-Dist: uwsgi>=2.0.31; sys_platform != "win32"
Provides-Extra: deploy
Requires-Dist: supervisor>=4.3.0; sys_platform != "win32" and extra == "deploy"
Requires-Dist: uwsgi>=2.0.31; sys_platform != "win32" and extra == "deploy"
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: pytest-django>=4.5; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: packaging>=24.2; extra == "dev"
Dynamic: license-file

# 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](AGENT.md)（pip 安装后位于 `django_base_ai/AGENT.md`）
- **快速开始（pip 安装 + 配置步骤）**：[help/QUICKSTART.md](help/QUICKSTART.md)
- **架构说明**：[help/ARCHITECTURE.md](help/ARCHITECTURE.md)
- **RSA 私钥部署**：[docs/RSA_KEY_ROTATION.md](docs/RSA_KEY_ROTATION.md)、[django_base_ai/utils/keys/README.md](django_base_ai/utils/keys/README.md)

---

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

```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) 配置数据库、缓存、`INSTALLED_APPS`、中间件与路由。然后：

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

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

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

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

---

## 痛点与解决方案

| 痛点 | 解决方案 |
|------|----------|
| 想快速接入大模型，又不想从零搭权限 | Python AI 客户端开箱即用；底座提供认证、RBAC、日志 |
| 企业 RBAC / 组织架构复杂 | 用户、角色、部门、菜单、按钮、接口白名单、数据权限过滤 |
| 重复实现登录、字典、文件、日志 | JWT、字典/系统配置、分片上传、操作/登录日志、消息中心 |
| 密钥与敏感数据进包 | 私钥与 `init_users.json` 不进制品；环境变量注入机密 |

### 技术信息

- **Python**：3.9+
- **Django**：5.2.x（见 `pyproject.toml`）

---

## 功能概览

### 主推：AI 能力（Python API）

| 模块 | 说明 |
|------|------|
| **AI 对话** | `utils.ai.ChatSession`：多轮对话、多供应商（DeepSeek、腾讯混元、OpenAI、自定义） |
| **PPT 生成** | `utils.html_to_pptx`、万相配图等工具函数 |
| **文本 / 文生图** | 业务侧封装 HTTP；底层用 `utils.ai` / `wanxiang` |
| **AI 工作台** | HTTP：`ai_desk_app_manage/` |

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

### 底座核心

| 模块 | 说明 |
|------|------|
| **认证** | JWT（短 Access + Refresh rotation/blacklist）、单点/第三方登录、验证码、登出 |
| **RBAC** | 用户（写入字段白名单）、角色、部门、菜单、按钮、接口白名单、数据权限 |
| **系统配置** | 字典、系统配置、`dispatch` 缓存（由管理命令初始化） |
| **审计与日志** | 操作日志（敏感字段脱敏）、登录日志；Redis 日志用 `sync_operation_log` 消费 |
| **文件与存储** | 登录上传、MIME/魔数校验、路径沙箱、对象级下载权限、分片秒传 |
| **消息与协作** | 消息中心、WebSocket（**token 不在 URL**）、常用联系人、协作人 |
| **任务与配置** | 基础任务、应用/标签、DataV 统计 action |
| **工具** | 统一 JSON 响应、分页、异常处理、XSS 清洗、RSA/AES、节假日等 |

### 其他扩展

| 模块 | 说明 |
|------|------|
| **IM** | 会话、单聊、群聊、问题分组、问答、聊天记录 |
| **数据分析** | `base_analyze/`（管理员权限） |

---

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

| 项 | 要求 |
|----|------|
| RSA 私钥 | 每个安装环境自行设置 `RSA_PRIVATE_KEY_PATH` / `RSA_PRIVATE_KEY_PEM`；历史泄露钥须轮换 |
| 发布包 | 不得含私钥、`.env`、`init_users.json`；构建后解包抽检 |
| WebSocket | `ws/base/<nid>/` + Header 或首帧 `auth`；禁止 `/ws/base/<token>/...` |
| 生产配置 | `ENV=pro` 须设 `ALLOWED_HOSTS`、DB/Redis 等；HSTS preload 默认开启 |
| 初始化 | `init` + `init_dispatch_cache`；`AppConfig.ready()` **不再**自动打 DB/Redis |

更多细节见 [AGENT.md §0.1 / §8](AGENT.md)。

---

## 统一响应格式

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

**分页列表**：

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

**单条 / 非分页**：

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

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

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

权限拒绝为 HTTP 403。

---

## 暴露的 HTTP API（摘要）

路径前缀默认 **`/base/api/system/`**。完整 action 表见 [AGENT.md](AGENT.md)。

### 认证与初始化

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `login/` | 登录 |
| POST | `sign_login/` / `custome_login/` | SSO / 自定义登录 |
| POST | `token/refresh/` | 刷新 JWT |
| POST | `logout/` | 登出 |
| GET | `captcha/` | 验证码 |
| GET | `init/dictionary/` / `init/settings/` | 前端初始化（不执行系统命令） |
| GET | `holiday/` | 节假日 |
| GET | `ws` | WebSocket **测试页 HTML**（不是通道） |

### 资源型 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/` 等。

### 文件（安全）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `file/upload_allow_file/` | 登录上传；魔数/扩展名校验 |
| GET | `file/download_file/?fid=` | 登录 + 对象级权限 + 路径沙箱 |
| POST | `file/check_file_by_md5/` → `upload_chunk/` → `merge_chunks/` | 分片秒传 |

### WebSocket（ASGI）

```
ws/base/<nid>/
```

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

---

## 安装

```bash
pip install django-base-ai
```

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

源码开发：

```bash
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. **路由**：
   ```python
   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` / 私钥。

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

---

## 许可证

见仓库根目录 `LICENSE`。
