# 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。