171 lines
7.3 KiB
Markdown
171 lines
7.3 KiB
Markdown
# AI 工单平台
|
||
|
||
> 面向企业私有化部署的 AI 原生技术支持与知识运营平台。
|
||
|
||
AI 工单平台把问题受理、技术排查、方案复用、知识沉淀和企业协作连接成一个可审计的
|
||
服务闭环。员工可以直接提交文字、截图或文档，系统自动识别问题、创建工单并组织证据；
|
||
技术支持人员可借助 Agent 检索可信知识和历史方案，完成排查、回复与知识发布。
|
||
|
||
平台并不把 AI 作为绕过流程的自动化脚本。所有模型输出、字段来源、工具调用和状态变化
|
||
都受到权限、策略、版本与审计约束，适合部署在对数据边界和操作风险有明确要求的企业环境。
|
||
|
||
[快速启动](#快速启动) · [产品蓝图](docs/product/blueprint.md) ·
|
||
[开发指南](docs/development/development-guide.md) ·
|
||
[生产部署](docs/operations/production-runbook.md)
|
||
|
||
## 核心价值
|
||
|
||
- **从材料到工单**：提交文字、图片、日志、PDF 或 Office 文档，自动解析问题并创建工单。
|
||
- **从工单到解决**：结合知识、历史工单和解决方案生成有引用、可追溯的技术支持建议。
|
||
- **从解决到知识**：将已解决工单蒸馏为候选知识，经独立审核后发布并重新进入检索。
|
||
- **从 Agent 到受控执行**：通过 Tool/MCP 调用企业系统，高风险操作必须经过独立确认。
|
||
- **从单点功能到企业闭环**：支持 OIDC、目录同步、服务渠道、SLA、审计和生产运维。
|
||
|
||
## 核心能力
|
||
|
||
| 能力域 | 主要能力 |
|
||
|---|---|
|
||
| 工单管理 | 权限、状态机、字段保护、协作、附件、证据、评论、事件与操作审计 |
|
||
| 智能受理 | 文本与多文件解析、结构化提取、自动建单、追问补全、人工接管和 SSE 进度 |
|
||
| 智能支持 | 混合检索、引用冻结、方案复用、受控自动解决、客户回复任务和 SLA |
|
||
| 知识治理 | 文档导入、版本审核、发布、下线、回滚、知识蒸馏和发布后索引 |
|
||
| Agent 平台 | 版本化编排、步骤级模型绑定、运行快照、时间预算、重试和结构化输出 |
|
||
| Tool/MCP | HTTP MCP、工具目录同步、授权交集、SSRF 防护、高风险双人确认和调用审计 |
|
||
| 企业集成 | OIDC、目录与用户组同步、渠道入站、出站回复、回执和消息幂等 |
|
||
| 生产运维 | 健康探针、Prometheus 指标、告警、备份校验、恢复和隔离演练 |
|
||
|
||
## 工作闭环
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
MATERIAL["文字 / 图片 / 文档"] --> INTAKE["AI 智能受理"]
|
||
INTAKE --> TICKET["正式工单"]
|
||
TICKET --> SUPPORT["Agent 技术支持"]
|
||
SUPPORT --> REPLY["解决方案与客户回复"]
|
||
REPLY --> RESOLVED["工单解决"]
|
||
RESOLVED --> DISTILL["知识蒸馏"]
|
||
DISTILL --> REVIEW["人工审核"]
|
||
REVIEW --> KNOWLEDGE["发布知识"]
|
||
KNOWLEDGE --> SUPPORT
|
||
```
|
||
|
||
## 系统架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
USER["员工 / 技术支持 / 管理员"] --> WEB["React 前端"]
|
||
CHANNEL["企业渠道"] --> API["Django Ninja API"]
|
||
WEB --> API
|
||
API --> DOMAIN["工单 / 知识 / Agent / Tool 领域服务"]
|
||
DOMAIN --> PG["PostgreSQL + pgvector"]
|
||
DOMAIN --> REDIS["Redis"]
|
||
DOMAIN --> MINIO["MinIO"]
|
||
DOMAIN --> CLAMAV["ClamAV"]
|
||
REDIS --> CELERY["Celery Worker / Beat"]
|
||
CELERY --> MODEL["OpenAI-compatible 模型服务"]
|
||
CELERY --> MCP["HTTP MCP 服务"]
|
||
```
|
||
|
||
关键约束：
|
||
|
||
- 工单写入必须经过领域服务，Agent、Celery 和 Tool 不直接写工单主表。
|
||
- 人工修改字段默认受保护，后续 Agent 不得静默覆盖。
|
||
- 高风险工具调用需要独立审核，申请人不能自审。
|
||
- 自动解决同时受 Agent 版本授权、全局策略、置信度和操作人权限约束。
|
||
- 原始材料、字段来源、模型运行、工具调用和状态变化均可追溯。
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|---|---|
|
||
| 后端 | Python 3.12、Django、Django Ninja、Celery |
|
||
| 前端 | React 19、TypeScript、Vite、Tailwind CSS、shadcn/ui |
|
||
| 数据 | PostgreSQL、pgvector、Redis、MinIO |
|
||
| AI | OpenAI-compatible 模型接口、Embedding、Rerank、Agent Runtime |
|
||
| 安全解析 | ClamAV、文件签名与 MIME 校验、受控文档解析 |
|
||
| 运维 | Docker Compose、Nginx、Prometheus、Alertmanager |
|
||
|
||
## 快速启动
|
||
|
||
前置环境：Python 3.12、Node.js 22 或更高版本、pnpm 11.9.0、Docker Desktop 或
|
||
Docker Engine + Compose。
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||
```
|
||
|
||
将生成值写入 `.env` 的 `AI_CREDENTIAL_ENCRYPTION_KEY`，并修改默认数据库、MinIO、
|
||
Django 和管理员密码。然后在项目根目录启动完整环境：
|
||
|
||
```powershell
|
||
docker compose -f infra/docker-compose.yml --env-file .env up --build
|
||
```
|
||
|
||
- 前端：<http://localhost:5173>
|
||
- API 文档：<http://localhost:8000/api/docs>
|
||
- 就绪探针：<http://localhost:8000/api/system/health/ready>
|
||
- MinIO 控制台：<http://localhost:9001>
|
||
|
||
开发环境默认管理员为 `admin / admin12345`，只能用于本地开发，生产部署前必须替换。
|
||
详细步骤见[本地开发环境](docs/development/local-setup.md)。
|
||
|
||
## 开发与质量检查
|
||
|
||
```powershell
|
||
cd backend
|
||
python -m pip install -e ".[dev]"
|
||
pytest
|
||
ruff check .
|
||
python manage.py check
|
||
python manage.py makemigrations --check --dry-run
|
||
|
||
cd ..\frontend
|
||
pnpm install --frozen-lockfile
|
||
pnpm test:run
|
||
pnpm typecheck
|
||
pnpm lint
|
||
pnpm build
|
||
```
|
||
|
||
代码结构、领域约束、迁移和提交规范见[开发指南](docs/development/development-guide.md)。
|
||
|
||
## 项目状态
|
||
|
||
阶段 1～6 的工程基线已经实现，当前自动化基线为后端 **217 项**、前端 **73 项**。
|
||
真实案例、企业外部服务和生产环境验证采用独立证据管理，不占用项目主页的产品说明；
|
||
需要评估上线准备度时，请查看[能力状态](docs/product/capability-status.md)和
|
||
[验收说明](docs/product/acceptance/blueprint-readiness.md)。
|
||
|
||
## 文档导航
|
||
|
||
- [产品蓝图](docs/product/blueprint.md)
|
||
- [阶段计划](docs/product/stage-plan.md)
|
||
- [能力状态](docs/product/capability-status.md)
|
||
- [统一蓝图验收](docs/product/acceptance/blueprint-readiness.md)
|
||
- [企业身份接入](docs/product/enterprise-identity.md)
|
||
- [本地开发环境](docs/development/local-setup.md)
|
||
- [开发指南](docs/development/development-guide.md)
|
||
- [生产部署与恢复](docs/operations/production-runbook.md)
|
||
- [隔离恢复演练记录](docs/operations/recovery-drill-2026-07-27.md)
|
||
- [前端设计系统](docs/frontend/design-system.md)
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
backend/ Django、Django Ninja、Celery 和领域服务
|
||
frontend/ React、Vite、Tailwind CSS 和 shadcn/ui
|
||
infra/ Compose、Nginx、监控、备份与恢复脚本
|
||
docs/ 产品、开发、前端、运维和验收文档
|
||
```
|
||
|
||
## 安全提示
|
||
|
||
- `.env`、模型凭据、OIDC 密钥、渠道密钥和 MCP Token 不得提交到 Git。
|
||
- 生产环境必须替换示例账号、数据库密码和 MinIO 凭据，并启用 HTTPS。
|
||
- 自动解决和高风险工具能力默认应保持关闭，完成权限与审计配置后再逐项启用。
|
||
- 外部证据只保存脱敏结果和引用，不保存密码、密钥、令牌或完整敏感输出。
|
||
|
||
生产部署前请阅读[生产部署与恢复手册](docs/operations/production-runbook.md)，不要把
|
||
`.env`、真实凭据、运行数据或备份提交到 Git。
|