Metadata-Version: 2.4
Name: django-base-ai
Version: 1.0.135
Summary: Django/DRF/RBAC 权限与常用 AI 接口封装
Author-email: cx <2256807897@qq.com>
License: 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: 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"
Requires-Dist: gunicorn>=23.0.0; extra == "deploy"
Requires-Dist: uvicorn>=0.32.0; 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 通用底座**：在 Django + DRF 之上提供企业级底座（认证、RBAC、组织架构、操作/登录日志、文件与消息等），以及可选 AI 工作台 / IM。产品业务（对话、文档、PPT 等）放在消费方仓库，不要写进本包。

给 AI / 后续模块开发：先读 **[AGENT.md](./AGENT.md)**。

- **包名**：`django-base-ai`（导入名：`django_base_ai`）
- **快速开始（pip 安装 + 配置步骤，无需 MySQL/Redis）**：[help/QUICKSTART.md](help/QUICKSTART.md)
- **架构说明**：[help/ARCHITECTURE.md](help/ARCHITECTURE.md) — 底座分层、AI 与扩展、集成方式
- **代码逻辑图**：[help/code-map/README.md](help/code-map/README.md) — 总览、登录鉴权、RBAC、存储、扩展点
- **多租户（默认关闭）**：[多租户](#多租户默认关闭) — 第三方不打开开关则什么都不用改
- **插件中心**：[插件中心](#插件中心) — zip 登记 / 安装 / 启用，进程内挂 `/plugins/`
- **OAuth2 统一登录门户**：[OAuth2 第三方接入](#oauth2-第三方接入authorization-code) — 应用管理注册后授权绑定 / SSO 登录
- **个人中心授权码**：[个人中心授权码 ac_code](#个人中心授权码-ac_code) — 与 OAuth `code` 完全分离
- 详细副本：[help/TENANT.md](help/TENANT.md)、[help/PLUGIN_CENTER.md](help/PLUGIN_CENTER.md)、[help/OAUTH_SSO.md](help/OAUTH_SSO.md)

---

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

使用 **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` 初始化菜单/角色/字典。对话与 PPT HTTP 接口在产品仓库，不在本包。

**发布时前端**：在本仓执行 `./build.sh` 会自动在同级 `../DjangoBaseAiWeb`（或本仓 `./web`）跑 `npm run build:pack`，再拷入 `django_base_ai/static/adminweb/` 打进 wheel。不必再手动打包/拷贝。跳过重编：`SKIP_FRONTEND_BUILD=1 ./build.sh`。

**管理后台（零配置）**：wheel 内已打入 DjangoBaseAIWeb 生产构建。只要 `INSTALLED_APPS` 含 `django_base_ai.system`，启动后打开：

```text
http://ip:port/admin/          # 管理端 SPA
http://ip:port/admin/#/login   # 登录页（hash 路由）
```

接口仍走同源 `http://ip:port/base/api/system/...`，不必再单独部署前端或配 nginx 静态目录。

---

## 配置参数关系与效果

底座配置写在业务项目的 `settings.py`（先 `from django_base_ai.settings import *`，再按需覆盖）。下面按「谁依赖谁 → 能得到什么」说明；未列出的项保持底座默认即可跑通。

### 1. 管理端页面（adminweb）

| 参数 | 默认 | 依赖关系 | 效果 |
|------|------|----------|------|
| `django_base_ai.system` ∈ `INSTALLED_APPS` | 必选 | 触发 `AppConfig.ready()` | 启动时尝试自动挂载管理端路由 |
| `ADMINWEB_AUTO_MOUNT` | `True` | 依赖上一项；且 wheel 内存在 `django_base_ai/static/adminweb/index.html` | `True`：自动挂到根 URLconf；`False`：不挂，需自行 `include` |
| `ADMINWEB_MOUNT_PATH` | `"/admin/"` | 仅在自动挂载开启时生效 | 浏览器访问前缀；`/admin` 会 302 到带尾斜杠的路径 |
| 包内 `static/adminweb/` | 发布机 `build:pack` + `bundle` 打进 wheel | 无产物则跳过挂载并打日志 | 提供 `index.html` 与 `static/js|css/...`；安装路径为 `site-packages/django_base_ai/static/adminweb/` |

关系简述：

```text
pip 安装（含 adminweb）
    → INSTALLED_APPS 含 django_base_ai.system
        → ADMINWEB_AUTO_MOUNT=True（默认）
            → 挂载 ADMINWEB_MOUNT_PATH（默认 /admin/）
                → 打开 /admin/ 即管理端；API 仍用 /base/api/system/
```

关闭示例：

```python
ADMINWEB_AUTO_MOUNT = False
# 或改挂载前缀：
# ADMINWEB_MOUNT_PATH = "/console/"
```

### 2. 接入底座 API 的最小三角

| 参数 / 配置 | 默认或示例 | 依赖关系 | 效果 |
|-------------|------------|----------|------|
| `from django_base_ai.settings import *` | — | 最先执行 | 带入 DRF / JWT / 分页 / 认证 / 异常处理等默认 |
| `INSTALLED_APPS` 含 `django_base_ai.system` | — | 依赖 Django 应用加载 | 模型、迁移、管理命令、`/admin/` 自动挂载 |
| `urls.py`：`path("base/api/system/", include("django_base_ai.system.urls"))` | — | 与上一项配合 | 暴露登录、用户/角色/部门、菜单、字典等 HTTP API |
| `SECRET_KEY` / 环境变量 `DJANGO_SECRET_KEY` | 开发有占位；`ENV=pro` 必填真密钥 | JWT / session 签名 | 多应用共用同一密钥可共享登录态；生产禁止 `django-insecure` |

缺路由则只有页面没有接口；缺 `system` 应用则页面也不会自动挂载。

未匹配的 `/base/api/` 即使 `DEBUG=True` 也返回 JSON 404，而不是 Django 技术黄页。非 API 页面（例如 `/admin/`）仍保留原来的 DEBUG 黄页。

| 参数 | 默认 | 效果 |
|------|------|------|
| `API_JSON_404_ENABLED` | `True` | `False` 时不再改写 404，API 路径也会回到 Django 的 HTML 404 |
| `API_JSON_404_PREFIXES` | `["/base/api/"]` | 要改写成 JSON 的前缀。覆盖此列表会替换默认值 |
| `API_JSON_404_EXTRA_PREFIXES` | `[]` | 只追加、不替换。产品前缀写在宿主，例如 `["/docs/app/"]` |

`django_base_ai.system` 就绪时，若 `MIDDLEWARE` 里还没有 `ApiJson404Middleware`，会插到 CORS 之后、`CommonMiddleware` 之前。JSON 体与底座 `Http404` 口径一致：`{"code": 400, "data": null, "msg": "接口地址不正确"}`，HTTP 状态为 404。

### 3. 运行环境与数据面

| 参数 | 典型值 | 依赖关系 | 效果 |
|------|--------|----------|------|
| `DATABASES` | SQLite 或 MySQL | ORM / 迁移 | 存用户、角色、菜单、日志等 |
| `REDIS_MODE` / `CACHES` / `CHANNEL_LAYERS` | `memory` 或 Redis | 缓存、Channels、部分限流 | quickstart 用内存即可；生产建议 Redis |
| `DISPATCH_DB_TYPE` | `"memory"` / 库 | 字典与系统配置调度 | 控制配置缓存后端 |
| `CORS_ALLOWED_ORIGINS` | 同源可空；跨域需显式列表 | 浏览器跨域调 API | 管理端与 API 不同源时必配 |
| `ALLOWED_HOSTS` | 开发可用 `["*"]` | Django 主机校验 | 生产必须写成真实域名/IP |

### 4. 初始化与权限相关开关

| 参数 | 默认 | 效果 |
|------|------|------|
| `python manage.py migrate` | — | 创建底座表结构 |
| `python manage.py init` | — | 导入菜单 / 角色 / 字典等 fixtures |
| `INITIALIZE_DEPT_AND_USERS` | `True` | init 时是否初始化部门与用户 |
| `INITIALIZE_ALL_USERS` | `True` | `False` 时 init 只保留第一个用户（admin） |
| `LICENSE_VERIFY_ENABLE` | `False` | 打开后按 License 拦截；`/admin`、`/healthy` 等在默认排除列表 |

### 5. 运维页（可选）

| 参数 | 默认 | 效果 |
|------|------|------|
| `CELERY_OPS_QUEUES` | `["celery", "vector", "skill"]` | 管理端「任务状态」巡检的队列名 |
| `SUPERVISOR_SOCKET` | `/var/run/supervisor.sock` | 「进程守护」连本机 Supervisor |
| `SUPERVISOR_CONTROL_ENABLED` | `True` | 是否允许启停进程 |
| `SUPERVISOR_NODES` / `SUPERVISOR_AGENT_TOKEN` | 空 | 多机 Supervisor 代理查询 |

这些只影响管理端运维菜单对应的 API，不影响 `/admin/` 页面能否打开。

---

### 痛点与解决方案

| 痛点 | 解决方案 |
|------|----------|
| 想快速接入大模型能力，又不想从零搭权限与基础 | 底座提供认证、RBAC、日志与 `utils.ai` 客户端；对话/PPT HTTP 由产品 app 接入 |
| 企业系统权限需求复杂，自建 RBAC 成本高、易遗漏 | 完整 RBAC：用户、角色、部门、菜单、按钮权限、接口白名单、**数据权限过滤**，开箱即用 |
| 国内大型企业组织架构明确、层级多、权限要求严 | 部门树、懒加载、数据权限按部门/角色过滤，贴合「组织架构清晰、权限分级严格」的国内企业场景 |
| 每个项目重复实现登录、字典、文件、日志等基础能力 | 统一认证（JWT、单点登录、验证码）、字典/系统配置、文件与文件夹、操作日志、消息中心等一应俱全 |
| 希望快速接入企业规范，而非从零搭架子 | 安装依赖、配置 `INSTALLED_APPS` 与路由后，**一键集成**到现有 Django 项目，无需重写权限与基础模块 |

### 技术信息

- **Python**：3.9+

---

## 功能概览

### 主推：AI 能力

| 模块 | 说明 |
|------|------|
| **AI 客户端** | `django_base_ai.utils.ai`：多供应商 Chat / 生图，供产品 app 调用 |
| **AI 工作台** | `ai_desk_app_manage/` 与菜单权限打通（对话/PPT HTTP 在产品仓库） |

配置 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/` | 用户名密码登录（可选验证码；多租户开启时须 `tenant_code`） | `{ code, msg, data: { access, refresh, name, userId, … } }` |
| POST | `sign_login/` | 企业 4A / 第三方 code 换票 | 同上结构 |
| POST | `custome_login/` | 自定义登录 | 同上结构 |
| POST | `user/ac_code_to_login/` | 个人中心授权码换 JWT（见下文） | 同上结构；`login_type=4` |
| GET | `oauth/client_meta/` | OAuth 应用公开元数据 | `title` / `icon` / `scopes` / `oauth_auth_mode` / `redirect_uri_allowed` |
| POST | `oauth/authorize/` | 已登录用户签发 OAuth `code`（须白名单；授权绑定须 `consent`） | `{ code }` |
| POST | `oauth/token/` | OAuth code + 密钥换 `access_token` | `{ access_token, token_type, expires_in }` |
| GET | `oauth/userinfo/` | Bearer OAuth AT 取用户信息 | 用户摘要 |
| 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/` | 节假日（匿名，无需 Token；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/` | 应用管理（含 OAuth appid / 白名单） |
| `plugin/` | 插件中心（catalog / upload / install / enable…，见[插件中心](#插件中心)） |
| `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） |

对话 / PPT HTTP 路由不在本包，见消费方（如 DocsAI `AIChat`）。本包提供 `django_base_ai.utils.ai` 客户端与 `ai_desk_app_manage/`。

---

### 其他资源上的自定义 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`。
- **user AI 记忆**（仅当前登录用户，不进登录/用户列表）：

| 方法 | 路径 | 说明 | 返回值 |
|------|------|------|--------|
| GET | `user/ai_memory/` | 读取本人长期记忆；无记录时 `content=""`、`version=0` | `data: { user_id, filename, content, version, update_datetime }`，`filename` 为 `USER_AI_MEMORY_{user_id}.md` |
| PUT/PATCH | `user/ai_memory/` | 写入 Markdown（≤64KB）。可选 `version` 做乐观锁，冲突返回 `code=409` | 同上，`version` 加一 |
| DELETE | `user/ai_memory/` | 清空正文（保留行，`version` 加一）。可选带 `version` | 同上 |

Python 侧注入 prompt：`get_user_ai_memory_markdown(user)` / `format_user_ai_memory_for_prompt(user)`。记忆与空间级 `agent_memory` 分层，不写在 `Users` 上。
- **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) 在项目中完成配置即可。

**Windows / Linux 兼容**：`uwsgi`、`supervisor` 为 Linux/macOS 生产部署工具，包内代码不依赖它们。pip 会根据 `sys_platform` 自动跳过 Windows 上的这两项（无需 `--no-deps`）；Windows 本地开发请用 `python manage.py runserver` 或 `daphne`。

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

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

`[dev]` 会安装 pytest、pytest-django、ruff。Linux 生产环境可额外执行 `pip install django-base-ai[deploy]` 显式安装 uwsgi/supervisor。

### 本地一键启动（对接 DjangoBaseAiWeb）

需同级存在前端仓库 `DjangoBaseAiWeb`（已 `pnpm install`）。

```bash
# 后端(:8075) + 前端 Vite(:5789)
./dev_run.sh

# 仅后端 / 仅前端
./dev_run.sh api
./dev_run.sh web

# 后端用 SQLite 快速开始（无需 MySQL/Redis）
ENV=quickstart ./dev_run.sh
```

访问：`http://localhost:5789/`。可用 `FRONTEND_DIR` / `BACKEND_PORT` / `WEB_PORT` 覆盖路径与端口。

---

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

安装 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` 中挂载系统 API（管理端页面默认自动挂到 `/admin/`，一般不必再写静态路由）：
   ```python
   from django.urls import include, path
   urlpatterns = [
       path("base/api/system/", include("django_base_ai.system.urls")),
       # 管理端：默认 ADMINWEB_AUTO_MOUNT=True，无需再写 path("admin/", ...)
   ]
   ```
4. **初始化**：执行迁移，并可通过 `django_base_ai.dispatch` 及 system fixtures 初始化菜单、角色、字典等。
5. **打开管理端**：`python manage.py runserver 0.0.0.0:8000` 后访问 `http://127.0.0.1:8000/admin/`。

---

## 项目结构（简要）

目录、消费边界与 Git / PyPI 版本差见 [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)。分层说明见 [help/ARCHITECTURE.md](help/ARCHITECTURE.md)。

```
DjangoBaseAi/
├── django_base_ai/          # 底座主包（供其他项目安装引用）
│   ├── adminweb/            # /admin/ 零配置托管（自动挂载包内 SPA）
│   ├── dispatch.py          # 系统配置/字典调度入口
│   ├── settings.py          # 默认配置（含 ADMINWEB_* ）
│   ├── system/              # 唯一应用：底座核心 + ready() 里挂管理端
│   ├── static/adminweb/     # 发布时打进 wheel 的前端产物（不进 Git）
│   ├── utils/
│   ├── websocket/
│   └── templates/
├── help/
├── DjangoBaseAi/
├── conf/
├── tests/
├── pyproject.toml
└── 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
```

---

## 多租户（默认关闭）

开关名 **`BASE_AI_TENANT_ENABLED`**，默认 **`False`**。定义在 `django_base_ai/settings.py`。宿主 `from django_base_ai.settings import *` 之后再设为 `True` 才打开。不设置、或显式 `False`，行为与现在的单库底座一致。

操作说明的另一份副本在 [help/TENANT.md](help/TENANT.md)。下面这份是本仓库的完整约定，按代码实现书写。

### 第三方不打开开关时

`pip install django-base-ai` 并且**不**把 `BASE_AI_TENANT_ENABLED` 设为 `True` 的应用：

| 项 | 行为 |
|----|------|
| 登录 | `POST /base/api/system/login/` 仍是用户名（或邮箱、手机号）+ 密码，可带验证码。请求里多带 `tenant_code` 会被忽略，不报错 |
| JWT | 不增加 `tenant_code` / `platform` 声明 |
| 用户名 | 仍是整库唯一（`Users.username` 的 `unique=True` 没改） |
| 数据库 | 仍是 `DATABASES["default"]` 这一套。新增路由在关闭时每个方法都返回空，不改查询去向 |
| 菜单 | 没有「租户管理」。`init_menu.json` 里没有这条 |
| 插件 | 仍按 `project_code` 安装、启用 |
| 缓存键、媒体路径、Celery 消息头、WebSocket 房间名 | 与改前相同。关闭时不会给缓存键加前缀 |
| 中间件 | `TenantMiddleware` 会自动插到中间件最前面，但关闭时只调用下一层，不解析令牌 |

需要改的代码：**没有**。`migrate` 会多一张登记表 `base_ai_tenant`（空表），并把 `Users.last_token` 从 `varchar(255)` 改为文本字段，否则带 `tenant_code` 的 JWT 写不进去。其余字段和约束不变。关闭开关时登录请求和 JWT 声明仍与原来一致，多带的 `tenant_code` 仍被忽略。

### 打开之后的库

不使用 `django-tenants`（它只支持 PostgreSQL）。不把底座迁到 PostgreSQL。

- **MySQL**：一个租户一个库。MySQL 里 schema 就是库。建库用 `default` 连接上的账号执行 `CREATE DATABASE`，账号需要建库权限。库名形如 `ba_t_{租户编码}`。
- **SQLite（快速开始）**：一个租户一个文件，目录为 `BASE_AI_TENANT_DB_DIR`，未设置时是项目下的 `tenant_dbs/{编码}.sqlite3`。

`default` 是**全局库**。每个租户另有一条运行时注册的连接，别名 `tenant_{编码}`。

| 全局库 | 每个租户库 |
|--------|------------|
| 租户登记 `Tenant`：编码、名称、是否启用、库名、创建时间 | 该租户的用户、部门、角色、菜单、文件、消息、配置、日志等现有业务表 |
| 平台超管（`Users.is_superuser`，只在全局库登录） | 该租户自己的用户。用户名只在本库唯一，两个租户可以用同一个用户名 |
| 插件目录 `Plugin` 与版本 `PluginVersion`（全局一份） | 插件安装 `PluginInstall`、钩子订阅，以及插件自己的业务表 |

进程内插件代码可以共用一份。插件读写数据库必须走当前租户连接：建表用 `django_base_ai.plugin.schema.ensure_plugin_models`（内部是 `active_connection()`）。不要在插件里另开连接去读别的库。

### 登录

**租户用户**仍走 `POST /base/api/system/login/`。打开开关后请求体必须带 `tenant_code`。顺序是：先在全局库确认该租户存在且 `enabled=True`，再切到该租户库校验账号。成功后的 access / refresh JWT 带声明 `tenant_code`。之后的请求只认令牌里的租户，改 `X-Tenant-Code` 之类的请求头无效。停用的租户不能登录，已发出的令牌也会被拒绝。

**平台超管**不走这条登录。单独入口：

`POST /base/api/system/tenant/platform_login/`

只查全局库，账号必须是全局库里的 `is_superuser`。JWT 带 `platform: true`，不带 `tenant_code`。这个身份可以建租户、启用、停用，**不能**对租户业务接口做写操作（用户、角色、插件安装等 `POST/PUT/PATCH/DELETE` 会 403，提示不能直接修改租户业务数据）。平台令牌也不会因为请求头切到某个租户库。

全局库里的平台超管可以这样准备（在没有租户上下文时执行，数据落在 `default`）：

```bash
python manage.py createsuperuser
```

或在打开开关后对全局库执行 `python manage.py init`（此时「租户管理」菜单会写在全局库）。租户库自己的 `init` 不会写入「租户管理」。

### 租户管理菜单与接口

菜单在「管理」分组下，和「插件中心」同级。`name=TenantManagement`，路由 `tenant_management`，组件 `/@/views/setting/tenantManagement/index.vue`，标题「租户管理」。只在开关打开时出现在**全局库**，因此只有平台超管拉全局库菜单时看得到。租户库没有这条菜单。页面在 DjangoBaseAIWeb 另做，本仓库只提供菜单数据和接口。

接口风格与 `/base/api/system/plugin/` 相同：成功 `{code:2000, msg, data}`；列表的 `data` 内再包 `{page, limit, total, data}`。下面的 JSON 示例是 **`data` 字段**，外面还有 `code` 和 `msg`。

**两种模式都能匿名访问**

`GET /base/api/system/tenant/status/`

```json
{"enabled": false}
```

登录页用 `data.enabled` 决定是否显示租户编码输入框。关闭时也返回 200，`enabled` 为 `false`，不要求登录。

**平台超管，且开关必须打开**（Header：`Authorization: JWT <access>`，令牌来自平台登录）

| 方法 | 路径 | 作用 |
|------|------|------|
| GET | `/base/api/system/tenant/` | 分页列表。每项含 `id`、`code`、`name`、`enabled`、`db_name`、`create_datetime`、`description` |
| POST | `/base/api/system/tenant/` | 创建 |
| POST | `/base/api/system/tenant/{id}/enable/` | 启用 |
| POST | `/base/api/system/tenant/{id}/disable/` | 停用。停用后不能登录 |

创建请求体：

```json
{
  "code": "acme",
  "name": "Acme",
  "admin_username": "acme_admin",
  "admin_password": "请换成强密码",
  "admin_name": "Acme 管理员"
}
```

`code`：小写字母开头，只含小写字母、数字、下划线，最长 32。`name` 必填。`admin_username` / `admin_password` / `admin_name` 可省略；省略时仍会对新库执行 `migrate` 和 `init`（fixture 里的 admin）。填写了用户名就必须带密码。创建过程：写全局登记、建库、对该库 `migrate`、`init`、按需写入租户管理员。

开关关闭，或令牌不是平台超管：这些管理接口 **403**。`status` 除外。

**租户登录（打开开关）**

`POST /base/api/system/login/`

```json
{"username": "acme_admin", "password": "请换成强密码", "tenant_code": "acme"}
```

成功时 `data` 在原有 `access`、`refresh`、`userId`、`name` 之外多一个 `tenant_code`。JWT 里同样有 `tenant_code`。没带编码、编码不存在或租户已停用：业务失败（`code` 4000），消息为「请填写租户编码」或「租户不存在或已停用」。

注册、找回密码、授权码登录、4A / 第三方登录在打开开关后同样要带 `tenant_code`（JSON 或 query），用户落在该租户库。关闭开关时这些入口不要求该字段。

### 管理命令

```bash
python manage.py migrate_default_tenant --code default --name 默认租户
```

把**当前全局库里的业务数据**复制到默认租户库（默认编码 `default`），然后从全局库删掉业务行。平台超管（`is_superuser=True`）留在全局库，同时会复制进租户库，所以同一个超管可以用租户编码登录，也可以走平台登录。插件目录留在全局库。

**开关关闭时这条命令只打印警告，不改任何数据，也不会自动在部署或 migrate 里执行。** 编码不合法时命令以错误退出。

已经迁走过（租户库已有用户，且全局库里不再有非超管用户）时会跳过复制，避免把已经清空的全局库再覆盖回租户库。请在日常使用租户之前执行一次。

新租户不要用这条命令，用上面的创建接口（或自行登记后调用同一套建库、迁移、初始化）。

### 缓存、Celery、文件、WebSocket

只在开关**打开**时带租户：

- 缓存键在原键前加上 `t:{租户编码}:`。没有租户上下文时用 `t:_global:`。关闭时键函数原样调用，键名不变。
- 从带租户上下文的进程 `delay` / `apply_async` 时，消息头写入 `base_ai_tenant_code`。Worker 须加载 `django_base_ai.system`（`AppConfig.ready` 里挂了信号）。关闭时不加这个头。
- 上传相对路径：打开且已绑定租户时为 `files/{租户编码}/{md5}{后缀}`，否则仍是 `files/{md5}{后缀}`。
- WebSocket 房间：打开时为 `user_{租户编码}_{用户id}_{设备}`。未绑定租户的令牌会被拒绝。关闭时房间名仍是 `user_{用户id}_{设备}`。

### 产品怎么打开（例如 DocsAI）

安装新版本**不会**自动变成多租户。产品需要自己：

1. 设置 `BASE_AI_TENANT_ENABLED = True`。
2. 对全局库 `migrate`（多一张 `base_ai_tenant`，并加长 `Users.last_token`）。开关已打开且已经登记过租户时，这次 `migrate` 会把未应用的迁移同步到那些已有租户库，避免库还停在 `varchar(255)`。
3. 准备全局库平台超管，用平台登录创建第一个租户；或先 `migrate_default_tenant` 把现有单库数据放进默认租户。
4. 登录请求增加 `tenant_code`。每个新租户库在创建时会 `migrate` + `init`。已有租户库若仍缺迁移，下一次绑定该租户（登录、刷新令牌）会先补迁移再写 `last_token`。
5. 队列、上传目录、WebSocket、以及产品自己的独立服务（不经过这套中间件的进程）要带上租户上下文。插件若自己 `connect()` 到固定库，要改成当前连接。

本阶段不做：计费 / 订阅、独立域名、跨租户查询、DocsAI / DocsWebAI 改造、升版本号、发 PyPI、部署。

### 测试

```bash
ENV=quickstart pytest tests/tenant/ -v
ENV=quickstart pytest tests/login/ -v
```

`tests/tenant/` 覆盖：开关关闭时的登录契约、无租户菜单、用户名仍全局唯一、缓存键不变、迁移命令不改数据；开关打开时两个租户同名用户互不可见（改请求头、改令牌载荷都不行）、停用不能登录、A 的插件启用不影响 B、新建租户能初始化并登录、默认租户迁移命令、平台超管能建/停租户但不能改租户业务数据、管理菜单下有租户管理。

### 已知限制

- 插件目录是全局一份。能调用插件目录接口的租户管理员登记的插件，其它租户也能在目录里看到。安装和启用状态仍按租户库分开。删除目录项不会逐个租户库去卸安装。
- 平台超管令牌不能写租户业务接口，也不能靠请求头进入租户库。
- 一个请求里的跨库操作不是同一个数据库事务。
- Celery 任务如果不是在已绑定租户的进程里发出的，消息头里没有租户，Worker 按全局库执行。
- 缓存键加前缀后更长。原来就把整段 JWT 当缓存键的用法，在 Memcached 250 字符限制下可能告警；关闭开关时键名不变。
- `token_blacklist`、`guardian` 在打开开关且当前是租户请求时跟租户库走，避免登录黑名单的用户外键跨库。其它第三方应用若有指向 `Users` 的外键，需要同样跟着当前租户库，或不要建数据库级外键。

---

## 插件中心

把独立插件工程打成 zip，在管理端登记后安装、启用。进程内插件**不必**写入宿主 `INSTALLED_APPS`。完整流程图与打包约定见 [help/PLUGIN_CENTER.md](help/PLUGIN_CENTER.md)；示例工程同级仓库 `PluginDemo/`。

侧栏：**管理 → 插件中心**（`PluginCenter` / `plugin_center`）。DjangoBaseAIWeb 另有配置路由 `/setting/pluginCenter`。

### 参与方与形态

| 角色 | 作用 |
|------|------|
| 插件工程 | `plugin.json` + Python 包 + 可选 Vue `frontend/dist`，`pack.sh` 产出 zip |
| 宿主底座 | 目录、解压、`importlib`、建表、挂 `/plugins/` |
| 管理端 | 上传 / 安装 / 启用；iframe 打开插件 UI |
| 运行时目录 | `{BASE_DIR}/plugin_workspace/`（zip 与解压结果，勿提交 git） |

| kind | 加载 | 路由 | 用途 |
|------|------|------|------|
| `inproc` | zip 解压后加载 `entry` | `/plugins/{url_prefix}/` | 进程内 API + 静态 UI |
| `remote` | 关联 `Apps` + 钩子，不进进程 | 不挂宿主路由 | 独立 HTTP 服务 |

### 安装包结构（inproc）

```text
bohe.demo-1.1.0.zip
├── plugin.json              # 必填：code / name / version / kind；inproc 还须 entry
├── backend/<pkg>/           # entry = 模块路径:类名
└── frontend/dist/           # 可选；启用后托管为 /plugins/{prefix}/ui/
```

Vue 的 `base` 须为 `/plugins/{url_prefix}/ui/`。`requires` 必须是宿主 `BASE_AI_HOST_CAPABILITIES` ∪ 底座 `BASE_CAPABILITIES` 的子集，否则无法启用。`menus` / `permissions` 目前只入库，**不自动写侧栏/RBAC**。

### 生命周期

```text
上传登记 → 安装(install) → 启用(enable) → 停用(disable) → 卸载(uninstall)
```

| 动作 | 接口 | 宿主行为 |
|------|------|----------|
| 登记 | `POST /base/api/system/plugin/upload/` | zip 或 `package_uri`；校验清单；写入 `Plugin` + `PluginVersion` |
| 目录 | `GET …/plugin/catalog/` | 目录 + 本项目安装态 |
| 项目信息 | `GET …/plugin/project_info/` | `project_code` + 宿主能力 |
| 安装 | `POST …/plugin/{id}/install/` | 兼容性与 `requires`；`PluginInstall`；`get_models()` 建表；`install()`；同步 hooks |
| 启用 | `POST …/plugin/{id}/enable/` | 未安装则先装；`enable()`；`PluginRegistry.reload()` |
| 停用 | `POST …/plugin/{id}/disable/` | `disable()`；卸路由；**保留安装记录与业务表** |
| 卸载 | `POST …/plugin/{id}/uninstall/` | `uninstall()`；删安装与 hooks；**默认不 DROP 表** |

启用后典型 URL（以 PluginDemo、`url_prefix=demo` 为例）：

| URL | 说明 |
|-----|------|
| `/plugins/demo/ping/` 等 | 插件 `get_urls()` |
| `/plugins/demo/ui/` | 托管 `frontend/dist` |
| 管理端「打开界面」 | iframe → 上述 UI |

开发代理：DjangoBaseAIWeb（如 `:5789`）已转发 `/plugins` 到底座（如 `:8075`）。

### 插件表约定

插件不进 `INSTALLED_APPS`，不能对插件包 `makemigrations`。模型经 `BasePlugin.get_models()` 在 **install** 时由宿主 `schema_editor` 建表：`Meta.app_label="system"`、`managed=False`、独立 `db_table`。卸载默认保留数据。

### 安全

- `package_uri` 仅允许 `BASE_AI_PLUGIN_WORKSPACE` 或 `BASE_AI_PLUGIN_ALLOWED_PACKAGE_DIRS`
- 登记写 `checksum`（sha256），加载前校验
- zip 大小/成员数限制，拒绝 zip-slip
- 多 worker：启停会 bump registry 代际，下次访问 `/plugins/` 热加载；只装可信包

### 多租户

`BASE_AI_TENANT_ENABLED` 关闭时：安装/启用按 `project_code`，与单库一致。

打开后：**目录与版本在全局库**；**安装/启用在当前租户库**。A 租户启用不影响 B。进程内代码可共用，建表与查询须走当前租户连接（`ensure_plugin_models` / `active_connection()`），不要自连固定库。

### 快速验收（PluginDemo）

```bash
cd PluginDemo && ./pack.sh
# 管理端 → 管理 → 插件中心 → 上传 dist/bohe.demo-*.zip → 安装并启用 → 打开界面

curl -s -H "Authorization: JWT <TOKEN>" \
  http://127.0.0.1:8075/plugins/demo/ping/
```

---

## OAuth2 第三方接入（Authorization Code）

本平台作为**统一登录门户**。第三方在管理端 **应用管理** 注册后，用标准 Authorization Code 拿用户信息。详细步骤与示例另见 [help/OAUTH_SSO.md](help/OAUTH_SSO.md)；演示工程：`test/oauth_demo_fastapi/`。

### 与「个人中心授权码」的区别（必读）

| | OAuth2 `code` | 个人中心 `ac_code` |
|--|---------------|---------------------|
| 用途 | 第三方网站 / 应用登录或授权绑定 | 用户本人在个人中心生成的长期授权码换 JWT |
| 存储 | **仅缓存** `oauth:code:`，5 分钟、一次性 | 落库 `Users.authorization_code`（AES-GCM） |
| 入口 | `/#/oauth/authorize` → `oauth/token/` → `oauth/userinfo/` | `user/get_ac_code/` → `user/ac_code_to_login/` |
| 能否混用 | **禁止**：个人中心码不能当 OAuth `code` 换票 | 与 OAuth 无关 |

### 1. 注册应用（管理端 → 应用管理）

| 字段 | 说明 |
|------|------|
| **appid**（`Apps.agent_id`） | 自动生成**唯一 8 位数字**；对外 query/body 优先用 `appid`（兼容 `client_id`） |
| **密钥**（`secret`） | 自动生成；换票时作 `client_secret` |
| **OAuth 认证模式**（`oauth_auth_mode`） | `0` **授权绑定**（默认）：同意页须用户点「允许」，且 API 须 `consent=true`；`1` **SSO 登录**：登录成功后跳过同意页直接发码回跳 |
| **IP/域名白名单**（`server_ip`） | 多行混填；`redirect_uri` 的 **host（域名或 IP）必须命中**；换票时若配置了 IP 条目则校验来源 IP |
| **OAuth 回调地址**（`oauth_redirect_uris`） | 多行绝对 URL；若配置则须**精确匹配**整行，同时 host 仍须可信 |

白名单全空则拒绝一切 `redirect_uri`。生产建议同时配置精确回调与白名单。

### 2. 浏览器授权入口（前端统一登录页）

认证**只走系统登录页** `/#/login`（勿另写登录页）。授权入口：

```http
GET {WEB}/#/oauth/authorize?response_type=code&appid={appid}&redirect_uri={urlencoded}&state={random}
```

未登录 → 跳转 `/#/login` 并透传 `appid` / `redirect_uri` / `state`；登录成功回到授权页。

**授权绑定（mode=0）**

1. 同意页展示：应用名称、将授权权限、当前账号  
2. 用户点 **允许** → `POST /base/api/system/oauth/authorize/`（body 含 `consent: true`）→ 为当前用户 upsert「`授权-{应用名称}`」个人信息授权码（同 `appid` 仅一条）→ 回跳 `{redirect_uri}?code=...&state=...`  
3. 取消 → `{redirect_uri}?error=access_denied&state=...`  

**SSO 登录（mode=1）**

已登录且 `redirect_uri` 合法 → 不弹同意页，自动发码并回跳。后端不要求 `consent`。

成功发码会写 **登录日志**（`login_type=5` OAuth授权，字段 `appid`）。

### 3. 换票与用户信息

```http
POST /base/api/system/oauth/token/
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "...",
  "appid": "{appid}",
  "client_secret": "{secret}",
  "redirect_uri": "https://app.partner.com/oauth/callback"
}
```

```json
{ "code": 2000, "data": { "access_token": "...", "token_type": "Bearer", "expires_in": 1800 } }
```

```http
GET /base/api/system/oauth/userinfo/
Authorization: Bearer {access_token}
```

返回 `id` / `username` / `name` / `email` / 部门与角色摘要。

公开元数据（不含密钥）：

```http
GET /base/api/system/oauth/client_meta/?appid={appid}&redirect_uri={optional}
```

### 4. 安全要点

- 授权绑定发码：**后端强制** `consent=true`，不能只靠前端隐藏同意页绕过  
- `redirect_uri`：校验 host∈可信 IP/域名；有精确列表时还须整 URL 匹配  
- `code`：缓存、5 分钟、一次性；与个人中心授权码隔离  
- 登录认证 UI：仅 `Login.vue`；`/oauth/authorize` 只做同意/自动回跳，不是第二套登录页  
- 建议生产：强制非空 `oauth_redirect_uris`；后续可补 PKCE / state 服务端绑定  

### 5. 多租户下的 OAuth

开关打开后，浏览器登录与发码落在**当前租户库**的用户/应用数据上；`Apps`、登录日志均在租户库。平台超管令牌不能代替租户用户完成授权绑定。第三方接入方仍使用同一套 `oauth/*` 路径，由平台 JWT 的 `tenant_code` 决定库。

### 6. 验收演示

```bash
# 需已启动底座 API（如 :8075）与管理端（如 :5789）
cd test/oauth_demo_fastapi   # 相对 BoheServer 仓库
.venv/bin/python e2e_accept.py
# 浏览器：http://127.0.0.1:8765/
#   「获取授权码」→ appid=87654321（同意页）
#   「OAuth2登录」→ appid=87654322（跳过同意）
```

---

## 个人中心授权码（ac_code）

用于**当前登录用户**生成/重置授权码，供自有脚本或受信任客户端换 JWT；**不是** OAuth2 门户的第三方 Authorization Code。

### 开关

- 系统配置 `third.enable_ac_code_login`，或 settings `ENABLE_AC_CODE_LOGIN`  
- 关闭时 `ac_code_to_login` 返回未启用  

### 接口

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET | `/base/api/system/user/get_ac_code/` | JWT | 获取或补发本人授权码 |
| GET | `/base/api/system/user/reset_ac_code/` | JWT | 重置授权码 |
| POST | `/base/api/system/user/ac_code_to_login/` | 匿名（限流） | body：`{ "ac_code": "..." }`；多租户开启时另带 `tenant_code` |

换发的 JWT 带声明 `ac_login`，**不写** `last_token`，避免挤掉浏览器会话。成功写登录日志 `login_type=4`。

### 接入示例

```http
POST /base/api/system/user/ac_code_to_login/
Content-Type: application/json

{ "ac_code": "<从个人中心复制的授权码>" }
```

多租户：

```json
{ "ac_code": "...", "tenant_code": "acme" }
```

---

## 第三方接入方式对照

| 场景 | 推荐方式 | 说明 |
|------|----------|------|
| 扩展底座能力（进程内 API + UI） | **插件中心** inproc zip | 见[插件中心](#插件中心)；不必改宿主 `INSTALLED_APPS` |
| 独立 HTTP 服务挂到平台 | **插件中心** remote + 应用管理 | 钩子回调 / OpenAPI ticket，不挂 `/plugins/` |
| 外部 Web/App 用本平台账号登录 | **OAuth2**，应用模式 **SSO 登录** | 跳过同意页，登录后直接回跳 |
| 外部应用要读用户资料且需用户知情 | **OAuth2**，应用模式 **授权绑定** | 同意页展示权限，须手动允许 |
| 自有工具 / 脚本代替密码登录 | **个人中心 ac_code** | 勿走 OAuth authorize |
| 企业 4A / 统一认证回跳 | `sign_login/` 或登录页 `accToken`/`ticket` | 系统配置 `SSOLOGIN.*` / `third.login_type` |
| 多租户产品 | 打开 `BASE_AI_TENANT_ENABLED` | 登录与上述换票均带 `tenant_code`；见[多租户](#多租户默认关闭) |

## 许可证

见仓库根目录 `LICENSE`。
