# AI 工单平台

> 面向企业私有化部署的 AI 原生技术支持与知识运营平台。

AI 工单平台把问题受理、技术排查、方案复用、知识沉淀和企业协作连接成一个可审计的
服务闭环。员工可以直接提交文字、截图或文档，系统自动识别问题、创建工单并组织证据；
技术支持人员可借助 Agent 检索可信知识和历史方案，完成排查、回复与知识发布。

平台并不把 AI 作为绕过流程的自动化脚本。所有模型输出、字段来源、工具调用和状态变化
都受到权限、策略、版本与审计约束，适合部署在对数据边界和操作风险有明确要求的企业环境。

[快速启动](#快速启动) ·
[产品蓝图](docs/product/blueprint.md) ·
[开发指南](docs/development/development-guide.md) ·
[生产部署](docs/operations/production-runbook.md)

## 产品预览

截图来自本地演示环境，可能涉及企业或客户的内容均已匿名化。

### 今日工作台

聚合个人待办、SLA 风险、任务中心和最近工单，并在同一页面提供上下文 Agent 助手。

![AI 工单平台今日工作台](docs/assets/screenshots/workbench.png)

| 智能建单 | 工单详情 |
|---|---|
| 提交聊天记录与多格式材料，经过安全检查和智能解析后自动建单。 | 集中查看业务上下文、支持分析、知识沉淀、协作成员和处理记录。 |
| ![多模态智能建单](docs/assets/screenshots/intelligent-intake.png) | ![工单详情与支持分析](docs/assets/screenshots/ticket-detail.png) |

### 知识库

统一管理人工知识、已解决工单案例、解决方案知识和文档导入队列。

![知识库与文档导入](docs/assets/screenshots/knowledge-base.png)

## 核心价值

- **从材料到工单**：提交文字、图片、日志、PDF 或 Office 文档，自动解析问题并创建工单。
- **从工单到解决**：结合知识、历史工单和解决方案生成有引用、可追溯的技术支持建议。
- **从解决到知识**：将已解决工单蒸馏为候选知识，经独立审核后发布并重新进入检索。
- **从 Agent 到受控执行**：通过 Tool/MCP 调用企业系统，高风险操作必须经过独立确认。
- **从单点功能到企业闭环**：支持 OIDC、目录同步、服务渠道、SLA、审计和生产运维。

## 核心能力

| 能力域 | 主要能力 |
|---|---|
| 工单管理 | 权限、状态机、字段保护、协作、附件、证据、评论、事件与操作审计 |
| 智能受理 | 文本与多文件解析、结构化提取、自动建单、追问补全、人工接管和 SSE 进度 |
| 智能支持 | 混合检索、引用冻结、可信降级、正式回复任务和方案风险判断 |
| 自动闭环 | 自动进入处理与分析、一次批准发送、送达后解决、客户反馈和 24 小时策略关闭 |
| 知识治理 | 文档导入、版本审核、发布、下线、回滚、知识蒸馏和发布后索引 |
| Agent 平台 | 版本化编排、步骤级模型绑定、运行快照、时间预算、重试和结构化输出 |
| Tool/MCP | HTTP MCP、工具目录同步、授权交集、SSRF 防护、高风险双人确认和调用审计 |
| 企业集成 | OIDC、目录与用户组同步、渠道入站、出站回复、回执和消息幂等 |
| 生产运维 | 健康探针、Prometheus 指标、告警、备份校验、恢复和隔离演练 |

## 工作闭环

```mermaid
flowchart LR
    MATERIAL["文字 / 图片 / 文档"] --> INTAKE["AI 智能受理"]
    INTAKE --> TICKET["正式工单"]
    TICKET --> SUPPORT["Agent 技术支持"]
    SUPPORT --> APPROVAL["一次批准方案并发送"]
    APPROVAL --> RESOLVED["送达后自动解决"]
    RESOLVED --> CLOSED["客户确认 / 24 小时无异议关闭"]
    CLOSED --> DISTILL
    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 不得静默覆盖。
- 高风险工具调用需要独立审核，申请人不能自审。
- 正常工单只保留一次“批准方案并发送”；方案版本、回复版本、权限和风险检查同时冻结。
- 回复明确送达后才记录解决；客户认可立即关闭，24 小时无异议后由系统关闭。
- 生命周期自动化默认关闭，启用前会检查受理/支持 Agent、模型、Celery 和对象存储配置。
- 原始材料、字段来源、模型运行、工具调用和状态变化均可追溯。

## 技术栈

| 层级 | 技术 |
|---|---|
| 后端 | 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/ticket-support-lifecycle-manual.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。