# Django 通用底座（主推 AI）— 架构说明

本项目定位为 **Django 通用底座，主推 AI**：在 Django + DRF 之上**以 AI 能力为核心**（多轮对话、PPT 生成、文本润色/翻译等），并配套企业级底座（认证、RBAC、组织架构、配置、日志、文件与消息等）；业务项目安装后一键集成，即可落地 AI 应用与完整权限体系，也可仅使用底座能力。

---

## 一、分层与边界

```
┌─────────────────────────────────────────────────────────────────┐
│  业务项目（你的 Django 应用）                                        │
│  - 业务 Model / ViewSet / 自定义 API                               │
└─────────────────────────────────────────────────────────────────┘
                                  │ 依赖
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│  django_base_ai（本底座，主推 AI）                                   │
│  ├── 主推：AI 对话、PPT 生成、文本润色/翻译、AI 工作台                  │
│  ├── 底座核心：认证、RBAC、组织、配置、日志、文件、消息、任务等           │
│  └── 其他扩展：IM、数据分析等                                         │
└─────────────────────────────────────────────────────────────────┘
                                  │ 依赖
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│  Django + DRF + 数据库 / 缓存 / 消息队列等                           │
└─────────────────────────────────────────────────────────────────┘
```

- **主推 AI**：多轮对话、PPT、文本处理等为产品重点，配置供应商即可使用。
- **底座核心**：认证、RBAC、组织、配置、日志、文件等，支撑 AI 与业务，所有接入项目均可使用。
- **其他扩展**：IM、数据分析等，按需启用。

---

## 二、底座核心能力（按领域）

| 领域 | 能力 | 主要模型/接口 | 说明 |
|------|------|----------------|------|
| **认证** | 登录、登出、JWT 刷新、验证码、单点/第三方登录 | `login/`, `logout/`, `token/refresh/`, `captcha/` | 统一认证入口，可配置验证码、单点登录 |
| **RBAC** | 用户、角色、部门、菜单、按钮权限、接口白名单、数据权限 | `user/`, `role/`, `dept/`, `menu/`, `menu_button/`, `api_white_list/` | 完整 RBAC，支持部门树、数据权限过滤 |
| **组织与基础数据** | 字典、区域、系统配置、初始化接口 | `dictionary/`, `area/`, `system_config/`, `init/*` | 字典树、键值配置、dispatch 调度 |
| **审计与日志** | 操作日志、登录日志 | `operation_log/`, `login_log/` | 请求记录、登录记录、日志文件 tail/分析 |
| **文件与存储** | 文件夹、文件上传/列表/下载 | `folder/`, `file/` | 统一文件管理、导入导出能力 |
| **消息与协作** | 消息中心、常用联系人、协作人、我的上级 | `message_center/`, `frequently_used_contacts/`, `collaborator/`, `my_superiors/` | 站内消息、WebSocket 推送 |
| **任务与配置** | 基础任务、任务运行历史、应用/标签、数据可视化配置 | `task/`, `task_run_history/`, `apps/`, `tags/`, `datav/` | 任务执行、看板/大屏配置 |
| **工具接口** | 节假日、懒加载部门树、健康检查 | `holiday/`, `dept_lazy_tree/`, `/healthy`, `/readiness` | 通用工具与运维检查 |

以上均属「底座核心」，不依赖 AI 或 IM 业务逻辑。

---

## 三、主推：AI 能力

| 能力 | 说明 | 主要接口 | 依赖/配置 |
|------|------|----------|-----------|
| **AI 对话** | 多轮对话、流式输出、多模型/多供应商 | `ai_chat_session/`、`chat/` 等 | AI 供应商配置（DeepSeek/腾讯/OpenAI/自定义等，见 conf 或文档） |
| **PPT 生成** | 大纲生成、单页重生成、配图 prompt、通义万相生图、布局拼装 | `ai_chat_session/generate_ppt_*`、`build_ppt_slides` 等 | 同上 + 通义万相 key（文生图） |
| **文本处理** | 续写、重写、缩写、扩写、润色、校润、翻译 | `ai_chat_session/text_refine/` | 同上 |
| **AI 工作台** | 工作台应用管理，与菜单与权限打通 | `ai_desk_app_manage/` | 底座用户与菜单 |

配置 `AI_DEFAULT_PROVIDER` 与对应 `AI_*_API_KEY` 后即可使用，为主推能力。

## 四、其他扩展能力

| 扩展 | 能力 | 主要接口 | 说明 |
|------|------|----------|------|
| **IM** | 会话、单聊、群聊、问题分组、问答、聊天记录 | `im_session/`, `im_chat_*` | 依赖底座用户与消息能力，按需使用 |
| **数据分析** | 通用分析视图（AllowAny 可选） | `base_analyze/` | 依赖底座数据与权限，按需使用 |

主项目若仅需底座 + AI，可不使用 IM/数据分析；路由中已单独标注（见 system/urls.py）。

---

## 五、包内结构（简要）

```
django_base_ai/
├── __init__.py          # 包入口、版本、pymysql 兼容
├── dispatch.py           # 系统配置/字典调度（get_system_config_values、init_*）
├── settings.py           # 默认配置（DRF、JWT、分页、认证、日志等）
├── system/               # 唯一 Django 应用，包含底座 + 扩展
│   ├── models.py         # 用户、角色、部门、菜单、字典、日志、文件、消息、AI/IM 等模型
│   ├── views/            # 所有 ViewSet 与 APIView（按资源分文件）
│   ├── urls.py           # 统一路由（可区分底座/扩展注释或分组）
│   ├── fixtures/         # 初始化数据
│   └── management/       # 初始化命令（init、init_area、generate_init_json 等）
├── utils/                # 工具层：认证、权限、响应、分页、异常、导入导出、AI 基座等
├── websocket/            # WebSocket 路由与配置
└── templates/
```

- **底座与扩展共用一个 `system` 应用**，通过**路由与文档**区分核心与扩展，避免拆包带来的迁移与依赖复杂度。
- 主项目通过 `INSTALLED_APPS` 只安装 `django_base_ai.system` 即可获得全部能力；若未来需要「仅底座」发行版，可在本仓库内通过 URL 子列表或条件注册实现「仅底座路由」。

---

## 六、依赖与配置入口

- **认证**：`AUTHENTICATION_BACKENDS`、`REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"]`、`SIMPLE_JWT` 等由 `django_base_ai.settings` 提供默认值，主工程可覆盖。
- **异常与响应**：`EXCEPTION_HANDLER` 指向 `django_base_ai.utils.exception.custom_exception_handler`，保证统一错误格式。
- **系统配置与字典**：通过 `django_base_ai.dispatch` 的 `get_system_config_values`、`init_system_config`、`init_dictionary` 访问；配置来源为 Redis 或内存（`DISPATCH_DB_TYPE`）。
- **环境配置**：主工程使用 `conf/env.py`、`conf/pro.py`、`conf/test.py` 等区分环境，底座仅读取 `settings` 中已有项（如 `API_LOG_ENABLE`、`TABLE_PREFIX`）。

---

## 七、集成方式（主项目）

1. **安装**：`pip install django-base-ai` 或可编辑安装本仓库。
2. **配置**：主工程 `settings` 中 `from django_base_ai.settings import *`（再按需覆盖），并确保 `django_base_ai.system` 在 `INSTALLED_APPS` 中。
3. **路由**：在 `urls.py` 中挂载 `path("base/api/system/", include("django_base_ai.system.urls"))`，即暴露底座核心 + 扩展全部接口。
4. **迁移与初始化**：执行 `migrate`，并按需执行 `init`、`init_area` 等 management 命令或调用初始化接口。

若未来提供「仅底座」路由列表，主项目可改为只 `include` 底座路由，从而不暴露 AI/IM 等扩展接口。

---

## 八、扩展底座的方式

- **新增接口**：在主项目新建 ViewSet/APIView，在自身 `urls.py` 中注册，或通过 `PLUGINS_URL_PATTERNS` 等扩展点挂载（若底座支持）。
- **覆盖行为**：主项目可自定义认证、权限类或异常处理，在 `settings` 中覆盖底座默认配置。
- **新增配置项**：在 `dispatch` 或系统配置表中增加键值，业务通过 `get_system_config_values` 读取。
- **不修改底座源码**：尽量通过配置、子类与路由扩展，保证底座升级时易于合并。

---

## 九、与 README 的关系

- **README**：面向使用者，强调「是什么、能做什么、如何安装与集成、API 一览」。
- **本文档（ARCHITECTURE）**：面向开发与二次开发，说明「分层、核心与扩展边界、包结构、依赖与扩展方式」。

两者互补，共同支撑「Django 通用底座」的定位与长期维护。
