# django-base-ai

Django / DRF / RBAC 权限与常用基础能力封装，可作为业务项目的基础依赖包（如 DocsAI、Survey 等）复用。

- **Python**：3.9+
- **包名**：`django-base-ai`（导入名：`django_base_ai`）

---

## 功能概览

| 模块 | 说明 |
|------|------|
| **RBAC** | 用户、角色、部门、菜单、按钮权限、接口白名单、数据权限过滤 |
| **认证** | JWT（SimpleJWT）、单点登录、第三方登录、验证码 |
| **系统配置** | 字典、系统配置键值、调度与配置中心（`dispatch`） |
| **基础能力** | 文件上传/列表、导入导出（Excel）、操作日志、消息中心、WebSocket |
| **工具** | 统一 JSON 响应、分页、异常处理、权限校验（`validation_api`）、加解密、任务执行等 |

---

## 安装

```bash
# 克隆或进入项目目录
cd DjangoBaseAi

# 依赖安装
pip install -r requirements.txt

# 或可编辑安装（开发时推荐）
pip install -e ".[dev]"
```

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

---

## 在项目中使用

1. **安装**：将本仓库可编辑安装或打包后安装到目标 Django 项目环境。

2. **配置**：在目标项目的 `settings.py` 中：
   - 将 `django_base_ai` 加入 `INSTALLED_APPS`
   - 按需配置数据库、缓存、JWT、CORS 等（可参考本仓库 `DjangoBaseAi/settings.py` 或 `django_base_ai/settings.py`）
   - 自定义异常处理：`EXCEPTION_HANDLER = "django_base_ai.utils.exception.custom_exception_handler"`

3. **路由**：在目标项目 `urls.py` 中挂载：
   ```python
   from django_base_ai.system.urls import urlpatterns as system_urls
   urlpatterns = [..., path("api/", include(system_urls))]
   ```

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

---

## 项目结构（简要）

```
DjangoBaseAi/
├── django_base_ai/          # 主包（供其他项目安装引用）
│   ├── dispatch.py          # 配置/调度入口
│   ├── settings.py          # 默认配置片段
│   ├── system/              # 系统模块：模型、视图、权限、fixtures、management 命令
│   ├── utils/               # 工具：认证、权限、响应、分页、导入导出、加解密等
│   ├── websocket/           # WebSocket 路由与配置
│   └── templates/
├── DjangoBaseAi/            # 本仓库作为“可运行项目”时的应用入口（settings、asgi、urls）
├── conf/                    # 环境配置（env/test/pro）
├── tests/                   # pytest 测试
├── pyproject.toml           # 项目与 ruff/pytest 配置
├── 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`。
