142 lines
5.7 KiB
Markdown
142 lines
5.7 KiB
Markdown
# AI 工单平台
|
||
|
||
面向单一企业私有化部署的 AI 原生技术支持工单平台。系统以工单和业务知识为中心，
|
||
提供多模态智能受理、技术支持分析、知识治理、Agent/Skill/模型配置、Tool/MCP 扩展、
|
||
企业身份、渠道接入、审计和生产运维能力。
|
||
|
||
## 当前状态
|
||
|
||
阶段 1～6 的工程基线已经实现，完整自动化基线为后端 **217 项**、前端 **73 项**。
|
||
工程完成不等于真实生产环境验收完成：统一蓝图退出报告当前为 **1/9 个门槛通过**，
|
||
已通过隔离一致性恢复；其余 8 项需要脱敏真实案例或企业外部服务。
|
||
|
||
| 领域 | 已实现能力 | 仍待真实环境验收 |
|
||
|---|---|---|
|
||
| 工单 | 权限、状态机、字段保护、证据、协作、附件、审计 | 真实业务量下的权限和流程策略 |
|
||
| 智能受理 | 文本、图片、PDF、TXT、LOG、DOCX、XLSX、PPTX，自动建单和人工降级 | 脱敏真实案例自动建单率与字段准确率 |
|
||
| 智能支持 | 混合检索、引用冻结、方案复用、自动解决策略、客户回复和 SLA | 真实案例、Embedding、重排和文本模型 |
|
||
| 知识治理 | 统一版本、独立审核、蒸馏、发布、下线、回滚和安全文档导入 | 真实 MinIO、ClamAV、PostgreSQL 和模型服务 |
|
||
| Agent/Tool | 步骤级模型、运行快照、HTTP MCP、授权交集、高风险双人确认 | 生产 MCP 网络与凭据边界 |
|
||
| 企业能力 | OIDC、目录同步、企业组映射、渠道幂等收发和回执 | 企业 IdP/LDAP 与服务群机器人 |
|
||
| 生产运维 | Compose、健康探针、指标、告警、备份、校验和隔离恢复 | 告警接收方、定时任务和异地加密备份 |
|
||
|
||
## 系统架构
|
||
|
||
```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、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)。
|
||
|
||
## 蓝图退出验收
|
||
|
||
统一报告把阶段 2～6 的真实案例、真实服务和恢复证据收敛为 9 个门槛：
|
||
|
||
```powershell
|
||
cd backend
|
||
python manage.py report_blueprint_readiness `
|
||
--evidence ../docs/product/acceptance/blueprint-external-evidence.template.json `
|
||
--format text `
|
||
--output ../docs/product/acceptance/blueprint-readiness.current.json
|
||
```
|
||
|
||
当前尚待：
|
||
|
||
1. 阶段 2 脱敏真实受理案例。
|
||
2. 阶段 3 脱敏真实支持案例。
|
||
3. 真实 PostgreSQL、Embedding 和重排检索验收。
|
||
4. 真实模型知识蒸馏、审核、发布和回检。
|
||
5. 六类文档在真实 MinIO、ClamAV、PostgreSQL 和 Embedding 环境的闭环。
|
||
6. 企业服务群机器人。
|
||
7. 企业 OIDC、LDAP 或目录服务。
|
||
8. 生产告警、定时备份和异地加密存储。
|
||
|
||
证据文件不得包含密码、密钥、令牌或凭据字段。
|
||
|
||
## 文档导航
|
||
|
||
- [产品蓝图](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/ 产品、开发、前端、运维和验收文档
|
||
```
|
||
|
||
生产部署前请阅读[生产部署与恢复手册](docs/operations/production-runbook.md)，不要把
|
||
`.env`、真实凭据、运行数据或备份提交到 Git。
|