# AI合规智能中枢 — 技术架构详解

> 本文档对应架构文档：`01_分层次技术架构图.html` 和 `02_详细技术架构图.html`

---

## 一、六层架构总览

```
┌──────────────────────────────────────────────────────────────────┐
│  L1  应用接入层：Web / Mobile / Bot / API Gateway / RBAC         │
├──────────────────────────────────────────────────────────────────┤
│  L2  业务能力层：知识库问答 / 文档审查 / EHS / 法规监控 / 推荐   │
├──────────────────────────────────────────────────────────────────┤
│  L3  法规感知层：监控 → 感知 → 解析 → 图谱 → 分析 → 闭环        │
├──────────────────────────────────────────────────────────────────┤
│  L4  AI引擎层：RAG / LLM / 文档解析 / 知识图谱推理 / NLP        │
├──────────────────────────────────────────────────────────────────┤
│  L5  数据知识层：Milvus / PostgreSQL / Neo4j / Redis / 知识库    │
├──────────────────────────────────────────────────────────────────┤
│  L6  基础设施层：安全治理 / 容器编排 / 运维观测 / CI/CD          │
└──────────────────────────────────────────────────────────────────┘
```

---

## 二、六大微服务详解

### 2.1 kbmp-service（知识库公开接口）

**职责：** 知识库的统一入口，处理文件上传、检索编排、任务投递。

**核心接口：**

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/workspace/create` | 创建知识库工作空间 |
| POST | `/files/upload` | 上传文件（触发解析任务） |
| POST | `/files/parse` | 手动触发解析 |
| POST | `/knowledge/retrieval` | 混合检索（BM25 + 向量）|
| POST | `/chunks/recall` | 原始 Chunk 召回 |
| POST | `/qa` | 检索 + LLM 问答生成 |

**内部流程：**
```
文件上传 → 存储 data/uploads → 投递 Celery 任务（parse-queue）
    → parse-worker 调用 mcp-server 解析
    → vectorize-worker 调用 embedding-service 向量化
    → 写入 Milvus（向量）+ PostgreSQL（元数据）
```

---

### 2.2 mcp-server（文档解析服务）

**职责：** 将 PDF/Word/Excel 等文档转换为结构化 Markdown，供后续向量化。

**核心接口：**

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/parse-document` | 通用解析（自动选择引擎）|
| POST | `/mineru-parse` | MinerU 精准解析 |
| GET | `/health` | 健康检查 |

**解析策略（降级链）：**
```
1. 阿里云文档解析 API（云端高精度）→ [调研版暂不启用]
2. MinerU（本地，GPU/CPU 均支持）→ 主用
3. python-docx / PyMuPDF（纯文本降级）→ 兜底
```

**MinerU 特性：**
- GPU 最快：0.21 秒/页
- CPU 模式：约 3-5 秒/页（调研阶段可接受）
- 支持 109 种语言 OCR
- 布局感知：区分正文/标题/表格/图片/页眉页脚
- 输出格式：Markdown + JSON（含结构化元数据）

---

### 2.3 合规业务后端（compliance-backend）

**职责：** 核心业务逻辑，整合三条闭环的业务处理。

**核心接口：**

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/compliance/upload` | 上传待审查文档 |
| POST | `/compliance/check` | 智能合规审查 |
| GET | `/compliance/report/{id}` | 获取审查报告 |
| POST | `/compliance/regulations/download` | 下载法规 |
| POST | `/compliance/regulations/update` | 更新法规版本 |
| POST | `/compliance/access-control` | 权限分级管理 |
| POST | `/compliance/subscribe` | 订阅变更推送 |

---

### 2.4 法规感知引擎（Regulation Awareness Engine）

**职责：** 定时监控法规源，自动检测变更，触发增量更新。

**六步感知闭环：**

```
① 法规源监控
   - 定时抓取：国家标准委、工信部、UN-ECE、EUR-Lex、碳交易平台
   - 技术：requests + BeautifulSoup + Playwright（动态页面）

② 智能变更感知
   - Hash 对比（快速过滤）
   - NLP 版本 Diff（精确识别新增/修订/废止条款）

③ 自动解析入库
   - MinerU 解析 → 条款级分割
   - BGE-M3 向量化 → Milvus + PostgreSQL

④ 知识图谱同步
   - Neo4j 更新：法规-条款-义务关系
   - 影响分析：哪些企业文档受影响

⑤ 差距分析
   - AI 比对企业现状 vs 新法规要求
   - 生成差距报告

⑥ 推送与整改触发
   - 按角色推送（研发/EHS/采购/法务）
   - 自动生成整改任务
```

---

### 2.5 AI 推理引擎（AI Inference Engine）

**职责：** 混合检索、精排、LLM 生成、知识图谱推理。

**混合检索流程：**

```
用户查询
    │
    ├─► BGE-M3 向量化（Dense 1024维）
    │       │
    │       └─► Milvus ANN 检索（HNSW，Cosine 相似度）
    │
    ├─► BM25 关键词检索（稀疏向量/倒排索引）
    │
    └─► 结果融合（RRF 排名融合）
            │
            ▼
    Cross-Encoder Reranker（精排 Top-K）
            │
            ▼
    LLM 生成（DeepSeek API）
    - System Prompt：引文锚定要求
    - 输出：答案 + 原文引用 + 来源文档 + 页码
```

**BGE-M3 三种向量输出：**
- **Dense Vector**（1024维）：语义相似度，主要用于向量检索
- **Sparse Vector**（词汇权重）：关键字匹配，等效 BM25
- **Multi-Vector**（ColBERT 风格）：精细粒度 token 级匹配

---

### 2.6 Worker 集群

**职责：** 异步任务处理，解耦主服务压力。

**Worker 类型：**

| Worker | 队列 | 职责 |
|--------|------|------|
| parse-worker | `parse` | 调用 mcp-server 解析文档 |
| vectorize-worker | `vectorize` | BGE-M3 向量化 + Milvus 写入 |
| compliance-worker | `compliance` | 合规比对 + 风险评分 |
| monitor-worker | `monitor` | 法规源定时抓取 |
| push-worker | `push` | 推送通知（Email/Webhook）|

**调度配置（Celery Beat）：**
```python
CELERY_BEAT_SCHEDULE = {
    "regulation-monitor": {
        "task": "app.worker.fetch_regulation_updates",
        "schedule": crontab(hour=2, minute=0),  # 每天凌晨2点
    },
    "push-notifications": {
        "task": "app.worker.send_pending_notifications",
        "schedule": crontab(minute="*/30"),  # 每30分钟
    },
}
```

---

## 三、数据模型

### 3.1 PostgreSQL 表结构

```
workspaces          → 知识库工作空间
files               → 上传文件记录（含解析状态）
tasks               → 异步任务状态追踪
compliance_reports  → 合规审查报告
regulation_sources  → 法规监控源配置
regulation_updates  → 法规变更记录
subscriptions       → 推送订阅配置
audit_logs          → 全链路审计日志
```

### 3.2 Milvus Collection 结构

```python
# regulation_chunks / doc_chunks / case_library 共用相同 Schema
fields = [
    FieldSchema("id",           VARCHAR, primary_key=True),
    FieldSchema("file_id",      VARCHAR),          # 关联文件
    FieldSchema("workspace_id", VARCHAR),          # 所属工作空间
    FieldSchema("chunk_idx",    INT64),            # 块序号
    FieldSchema("content",      VARCHAR(65535)),   # 原文内容
    FieldSchema("dense_vec",    FLOAT_VECTOR(1024)), # BGE-M3 向量
    FieldSchema("metadata",     JSON),             # 扩展元数据
]
# 索引：HNSW，Cosine 相似度，M=16，efConstruction=200
```

### 3.3 Neo4j 图模型

```cypher
// 节点类型
(:Regulation {id, title, code, version, domain, effective_date})
(:Clause     {id, number, content, clause_type})
(:Obligation {id, description, obligation_type, subject})
(:Enterprise {id, name, industry})
(:RiskItem   {id, description, severity, domain})
(:Domain     {name, label})

// 关系类型
(Regulation)-[:CONTAINS]->(Clause)
(Clause)-[:REQUIRES]->(Obligation)
(Regulation)-[:SUPERSEDES]->(Regulation)  // 版本替代
(Clause)-[:MAPS_TO]->(RiskItem)
(Enterprise)-[:SUBJECT_TO]->(Regulation)
```

---

## 四、核心技术栈版本锁定

| 组件 | 版本 | Docker 镜像 |
|------|------|------------|
| PostgreSQL | 16 + pgvector | `pgvector/pgvector:pg16` |
| Redis | 7.x | `redis:7-alpine` |
| Milvus | 2.4.13 | `milvusdb/milvus:v2.4.13` |
| Neo4j | 5.20 Community | `neo4j:5.20-community` |
| BGE-M3 | 最新 | BAAI/bge-m3（HuggingFace）|
| MinerU | 1.x | opendatalab/MinerU（pip）|
| LangChain | 0.3+ | pip install langchain>=0.3 |
| FastAPI | 0.115+ | pip install fastapi>=0.115 |
| Celery | 5.4+ | pip install celery[redis]>=5.4 |
| Python | 3.12 | python:3.12-slim（Docker）|
| Nginx | 1.25 | `nginx:1.25-alpine` |