# AI+合规智能中枢 — 下一步开发与优化路线图（设计文档）

- 日期：2026-06-05
- 定位：试点 MVP 走向生产
- 范围：全景清单 + 异步任务化（设计①）+ 法规感知闭环（设计②）深入方案 + 三阶段实施路线图
- 作者：AI Regulations Team（brainstorming 产出）

---

## 0. 背景与目的

本文档基于对当前仓库前后端真实代码的逐文件探查，结合四份愿景文档（`AI_Regulations_Report.pptx`、`AI_Regulations_Architecture.docx`、`01_Architecture.html`、`02_Architecture_Detail.html`）与最新开源 AI 技术调研，给出**下一步可继续开发与优化的方向清单**，并对两个最高价值方向给出可落地的深入设计。

本文档是**方向性设计（spec）**，不是实施计划（plan）。阶段一、阶段二的具体落地由后续 writing-plans 环节拆分为分步计划。

### 0.1 现状一句话

后端是一套结构清晰的 DDD 风格 FastAPI RAG 系统（上传 → 解析 → 分块 → BGE-M3 嵌入 → Milvus → 混合检索 → 流式问答 + 合规分析），**真实可用**。但愿景文档中的多个旗舰能力（知识图谱、法规感知闭环、RBAC、EHS、异步化）目前为 **mock 或缺失**。

---

## 1. 现状盘点（基于真实代码）

### 1.1 已实现且真实可用

- **文档处理主链路**：`application/documents/services.py::DocumentCommandService.upload_and_process` — 存储 → 解析（阿里云 DocMind / 本地）→ 分块 → BGE-M3 嵌入 → Milvus 入库，含 `DocumentProcessingStore` 全程状态事件记录。
- **混合检索**：`application/knowledge/services.py::KnowledgeRetrievalService` — Dense（`DenseRetriever`）+ BM25（jieba）+ Reciprocal Rank Fusion + 可选 Cross-Encoder 重排。
- **流式 RAG 问答**：`application/agent/services.py::AgentConversationService.stream_chat` + `api/routes/rag.py` — 真实检索 + 引文 + 会话历史 + SSE。
- **合规分析管线**：`application/compliance/pipeline.py` — clause_split → retrieve → gap_check → conclusion，真实 LLM + 真实检索，SSE 流式（`api/routes/compliance.py::analyze_stream`）。
- **状态/健康面板**：`api/routes/status.py` + 前端 `StatusPage.tsx` — Milvus/MinIO/BM25/Reranker/会话实时状态。
- **存储后端**：PostgreSQL / MinIO 适配器齐全；JSON 与 Postgres 双后端可切换。
- **前端**：React 19 + Vite + Tailwind，6 个页面（Overview/Status/Perception/Docs/Compliance/RagChat）。

### 1.2 愿景已规划但代码缺失或为 mock

| 能力 | 愿景出处 | 代码现状 |
|------|---------|---------|
| 知识图谱 / Neo4j 多跳推理 | 架构图 L4/L5、Slide 5 | 全代码 0 处 neo4j/graph |
| 法规感知自动更新闭环 | 01_Architecture.html L157-193、Slide 11 | `PerceptionService` 喂 `MockEventStore`（20 条死数据） |
| 认证 / RBAC / 审计日志 | Slide 12 四角色权限矩阵 | 全代码 0 处 auth/jwt/rbac；`main.py` CORS=`*` |
| 异步任务 / Worker 集群 | 架构图"Worker 集群"、Slide 9 | `app/workers/` 空目录；处理全同步 |
| EHS 隐患识别（SIF/四维根因） | Slide 7 | 未实现 |
| 多渠道推送（Email/Teams/飞书） | Slide 8 | 未实现 |
| 闭环整改跟踪、可观测性 | 架构图右栏 | 缺失 |

### 1.3 关键发现

- **`requirements.txt:28` 已有 `celery>=5.3.0` + `redis>=4.5.0`**，`docker-compose.yml` 已配 Redis 7，`settings.py` 已有 redis 配置 —— **异步化是"接线"，不是"从零搭建"**。
- **`DocumentProcessingStore` 已能记录 run 状态/状态事件** —— 是天然的任务进度表。
- **`PerceptionService.analyze_event` 的 LLM 影响分析与 RAG 关联检索是真的** —— 感知闭环缺的只是前半段（采集 → Diff → 入库）。
- 后端正处于 legacy 迁移期：`services/*`、`workflows/*` 为兼容层（见 `docs/architecture/backend-project-architecture.md`）。

---

## 2. 全景机会清单

类型标记：`[新能力]`=愿景缺口补齐，`[加固]`=已实现能力优化。价值 ★（1-5），工作量 S/M/L。

### P0 — 生产地基（阻断"走向生产"的硬伤）

| # | 机会点 | 类型 | 现状证据 | 价值 | 工作量 |
|---|--------|------|---------|------|--------|
| 1 | 异步任务化（Celery + 已配 Redis）：解析/嵌入/感知/推送下沉 worker | 加固 | `workers/` 空；`documents.py:34` 上传同步阻塞 | ★★★★★ | L |
| 2 | 认证 + RBAC + 审计日志，收紧 CORS | 新能力 | 0 处 auth；`main.py` CORS=`*`；Slide 12 | ★★★★★ | M |
| 3 | 会话 & 任务持久化（内存 → Redis/PG） | 加固 | `bootstrap.py:254` 内存会话；`compliance.py:25` 内存字典 | ★★★★ | M |
| 4 | 基础可观测性（Prometheus + 结构化日志 + 追踪） | 加固 | 仅 loguru；架构图右栏全缺 | ★★★ | M |

### P1 — 高价值能力补齐 + RAG 质量

| # | 机会点 | 类型 | 现状证据 | 价值 | 工作量 |
|---|--------|------|---------|------|--------|
| 5 | 启用并升级 Reranker（`bge-reranker-v2.5-gemma2-lightweight`） | 加固 | `settings.py:113` 默认关；管线已写好 | ★★★★ | S |
| 6 | Agentic 检索（查询改写/意图理解/多路召回） | 加固 | `agent/services.py` 直接 retrieve，无 rewrite/HyDE | ★★★★ | M |
| 7 | 知识图谱 / GraphRAG（Neo4j + LightRAG v1.5） | 新能力 | 0 处 neo4j；LightRAG v1.5 原生支持 | ★★★★★ | L |
| 8 | 法规感知自动更新闭环（真实采集 + 版本 Diff + 增量重索引） | 新能力 | `perception/services.py` 用 MockEventStore | ★★★★★ | L |
| 9 | 引文置信度评分（Slide 5 承诺"置信度评分+页码溯源"） | 加固 | `rag.py` sources 无 confidence | ★★★ | S |
| 10 | 检索评估 harness（recall@k / faithfulness） | 加固 | `tests/` 需真实服务，无离线 RAG 评估 | ★★★ | M |

### P2 — 视野扩展（独立子项目）

| # | 机会点 | 类型 | 价值 | 工作量 |
|---|--------|------|------|--------|
| 11 | EHS 隐患识别（SIF 评分 + 四维根因 + ISO 45001 扫描，Slide 7） | 新能力 | ★★★★ | L |
| 12 | 多渠道推送 + 订阅规则引擎（Email/Teams/飞书，Slide 8） | 新能力 | ★★★ | M |
| 13 | 闭环整改跟踪（任务派发 → 进度 → 验收归档） | 新能力 | ★★★ | M |
| 14 | 企业系统集成（PLM/ERP/OA/MES Webhook） | 新能力 | ★★ | L |
| 15 | MinerU 3.1 升级（已转 Apache 协议，VLM 解析）作本地兜底 | 加固 | ★★ | S |
| 16 | 前端加固（清 mock 数据、补 error/loading 态、KG 可视化、登录态） | 加固 | ★★★ | M |
| 17 | 收口 legacy 迁移（`services/*`、`workflows/*` 按架构文档归位） | 加固 | ★★ | M |

---

## 3. 深入设计 ① — 异步任务化

### 3.1 问题

`upload_document`（`api/routes/documents.py:34`）在单个 HTTP 请求内同步跑完 存储 → 解析（阿里云云端可达 900 秒，`settings.py:49`）→ 嵌入 → Milvus 入库。大体量 GB 标准必然超时；`compliance.py` 的 `/analyze` 为假异步（立即返回 mock）；perception 爬取闭环无执行载体。PPT Slide 9 已将"大文件性能"列为关键挑战，对策正是"流式处理 + 异步队列 + 实时进度"。

### 3.2 关键前提：基建已就位

- `requirements.txt:28` 已含 `celery>=5.3.0` + `redis>=4.5.0`
- `docker-compose.yml:46` Redis 7 已配置；`settings.py:64` 已有 redis 连接配置
- `PostgresDocumentProcessingStore` 已记录 run 状态/状态事件 —— 天然任务进度表
- `app/workers/` 为空目录（唯一缺口）

### 3.3 架构（遵循 AGENTS.md 的 `api → application → domain ports → infrastructure`）

```
api/routes/documents.py  POST /upload
        │ 1. 存二进制 + 建 Document 记录（快，同步）
        │ 2. enqueue task → 立即返回 {doc_id, status:"queued", run_id}
        ▼
infrastructure/tasks/            ← 新增
   celery_app.py                 broker=redis, backend=redis
   document_tasks.py             @task process_document(doc_id) → DocumentCommandService
        │ 复用现有 upload_and_process 的 parse→embed→index 段
        ▼
application/documents/services.py（拆分：store 与 process 解耦）
        │ 每阶段写 DocumentProcessingStore（已存在）→ 进度可查
        ▼
api/routes/documents.py  GET /status/{doc_id}  ← 已存在，读 run 状态即可
```

### 3.4 落地步骤（增量、不破坏现有同步路径）

1. 新增 `infrastructure/tasks/celery_app.py` — Celery 实例，broker/backend 指向已配 Redis。
2. 拆分 `upload_and_process` → `store_document`（同步快）+ `process_document`（可异步），复用现有逻辑，零重写解析/嵌入代码。
3. 新增 `document_tasks.py` — `@celery_app.task` 包裹 `process_document`，失败用 `tenacity`（已在 deps）重试 + 死信。
4. 改 `documents.py` 上传 — 默认入队（保留 `?sync=true` 同步回退便于演示）；`GET /status/{doc_id}` 读 `DocumentProcessingStore` 返回阶段进度。
5. 前端 `DocsPage.tsx` — 上传后轮询/SSE 进度条（架构图 Worker"心跳/状态上报"已是既定设计）。
6. `dev.sh`/`dev.bat` 加 worker 启动：`celery -A app.infrastructure.tasks.celery_app worker`。

### 3.5 工作量与风险

- **M（中），3-5 天。**
- 最大风险：Celery worker 进程内 `PYTHONPATH=backend` 与 bootstrap `lru_cache` 单例需重新初始化 —— 可控，因 bootstrap 已是懒加载。
- YAGNI 边界：本期仅异步化"文档处理"一条链；compliance/perception 复用同一 Celery 基建后续接入。

---

## 4. 深入设计 ② — 法规感知自动更新闭环

### 4.1 问题

感知闭环是愿景旗舰能力（`01_Architecture.html` L157-193、Slide 11）。现状：`PerceptionService` 喂 `MockEventStore`（`mock_event_store.py:7`，20 条手写死数据），`list_events`/`stats` 全静态，`source_url` 真实但从不访问。**LLM 影响分析与 RAG 关联检索是真的** —— 闭环缺的是前半段：真实采集 → 变更感知（Diff）→ 入库。

### 4.2 六步现状对照

| 步骤 | 愿景设计 | 现状 | 本期目标 |
|------|---------|------|---------|
| ① 法规源监控 | 定时爬国标网/MIIT/UN-ECE/EUR-Lex | ❌ 无 | ✅ 适配器+定时 |
| ② 智能变更感知 | NLP 比对新旧版本 Diff | ❌ 无 | ✅ 内容指纹+LLM Diff |
| ③ 自动解析入库 | MinerU→分块→BGE-M3→Milvus | ✅ 已有（复用设计①管线） | ✅ 接线 |
| ④ 知识图谱更新 | Neo4j 关系同步 | ❌ 无 | ⏭️ 本期不做（归 GraphRAG 专项） |
| ⑤ 差距分析&推送 | AI 比对+按角色推送 | 🟡 analyze_event 已有分析，无推送 | 🟡 分析复用，推送下期 |
| ⑥ 触发整改闭环 | 整改任务跟踪 | ❌ 无 | ⏭️ 下期 |

本期聚焦 ①②③，复用设计①异步管线与已有解析/嵌入/检索/分析能力。

### 4.3 架构（端口与适配器）

```
domain/perception/ports.py        ← 新增
   RegulationSource (Protocol)    fetch_latest() → list[RawRegulation]
   EventStore (Protocol)          抽象掉 MockEventStore（现有 mock 成为一个实现）
   ChangeDetector (Protocol)      diff(old, new) → ChangeSet

infrastructure/perception/
   sources/                       ← 新增，每法规源一个适配器
     gb_openstd_source.py         国标网 (openstd.samr.gov.cn)
     miit_source.py               工信部
     base_html_source.py          通用 HTML 抓取基类（httpx 已在 deps）
   postgres_event_store.py        ← 替换 MockEventStore（真实持久化）
   content_fingerprint_detector.py  哈希指纹 + LLM 语义 Diff

application/perception/services.py（扩展现有）
   ingest_cycle()                 ← 新增：①抓取 → ②Diff → ③入队解析（设计①的 task）
   （list_events/analyze_event 保持不变，已是真实逻辑）

infrastructure/tasks/perception_tasks.py  ← 复用设计①的 Celery
   @task perception_crawl_cycle()  Celery Beat 定时触发
```

### 4.4 关键设计决策

1. **接口契约零改动**：`PostgresEventStore` 输出与 `MockEventStore` 完全相同的 dict 结构（mock_event_store.py 的 20 字段），故 `perception.ts` 前端契约、`PerceptionPage.tsx`、`analyze_event` 全部不改。Mock 退化为种子数据/演示回退，通过 `perception_event_store=mock|postgres` 开关切换（对齐现有 `document_repository_backend` 模式）。
2. **变更感知分两层**：廉价层（内容哈希指纹判断"是否变了"）+ 智能层（变了才调 LLM 做"新增/修订/废止条款"结构化 Diff，复用 `get_llm_client`，prompt 风格照搬 `compliance/pipeline.py::_extract_json`）。
3. **合规防滥用**：尊重 `robots.txt` + 限速 + `tenacity` 重试 + 抓取失败不污染已有数据；适配器隔离，单源故障不影响其它。
4. **入库复用设计①**：抓到新法规 PDF → 丢进 `process_document` task → 自动走完解析/嵌入/索引。

### 4.5 落地步骤

1. 抽 `domain/perception/ports.py`，让现有 `MockEventStore` 实现 `EventStore` 协议（纯重构，行为不变）。
2. `PostgresEventStore` + 建表（参照 `aliyun_parser/schema.sql` 风格）+ 20 条 mock 作 seed。
3. 先做 1 个真实源适配器（建议国标网，结构最稳）跑通 ①→②→③，验证端到端。
4. `content_fingerprint_detector` + LLM Diff。
5. `perception_crawl_cycle` Celery Beat 定时（每日）；新事件落 PostgresEventStore + 新法规入队解析。
6. 前端 `PerceptionPage` 加"最近同步时间/本次新增 N 条"（stats 已有结构，加 2 字段）。

### 4.6 工作量与风险

- **L（大），5-8 天**，依赖设计①先落地（共用 Celery）。
- 最大风险：外部源站不可控（改版/反爬）。缓解：适配器隔离 + mock 永久保留为回退 + 先攻 1 个源验证（对齐 Slide 13"选取 2-3 个场景 POC 验证"）。
- YAGNI 边界：④Neo4j 图谱、⑥整改闭环、多渠道推送本期不做，各自独立子项目。

---

## 5. 三阶段实施路线图

### 5.1 核心主线

项目不缺"能力点"，缺的是**让能力点从同步脚本变成可运营的系统**。主线是**异步化基建**：既是文档处理性能解药（设计①），又是感知闭环执行载体（设计②），也是未来 EHS/推送的统一底座。路线图以它为"第 0 块地基"，其余能力挂载其上。

### 5.2 与 PPT 三阶段映射（Slide 10）

```
PPT 规划                  代码现状          本路线图补齐
─────────────────────────────────────────────────────
一阶段 知识库+基础问答   ✅ 大体已实现     → 加固 (P0/P1)
二阶段 文档审查+API集成  🟡 审查真/API半   → 异步化+感知闭环
三阶段 EHS+个性化+图谱   ❌ 基本缺失       → 子项目 (P2)
```

### 5.3 阶段一 · 生产地基（2-3 周）— "让它扛得住生产"

| 顺序 | 事项 | 依据 | 估时 |
|------|------|------|------|
| 1 | 设计① 异步任务化 | celery/redis 已在 deps，workers/ 空 | M, 3-5d |
| 2 | 认证 + RBAC + 审计 + 收紧 CORS | 0 处 auth；Slide 12 矩阵 | M, 3-5d |
| 3 | 会话/任务持久化（内存 → Redis/PG） | InMemoryConversationStore 重启即丢 | M, 2-3d |
| 4 | 快赢：启用 Reranker | settings 默认关，管线已写好 | S, 0.5d |

### 5.4 阶段二 · 招牌能力（2-3 周）— "让它有亮点"

建议**感知闭环优先于图谱**（前者复用阶段一异步基建，ROI 更高）。

| 顺序 | 事项 | 依据 | 估时 |
|------|------|------|------|
| 5 | 设计② 法规感知闭环 ①②③ | MockEventStore → 真实采集 | L, 5-8d |
| 6 | Agentic 检索（查询改写/意图理解） | Slide 5"意图理解"，代码是直检索 | M, 3-4d |
| 7 | 引文置信度评分 + 基础可观测性 | Slide 5 承诺；架构图右栏全缺 | S+M, 3-4d |

### 5.5 阶段三 · 视野扩展（按需，各为独立子项目）— "让它成体系"

每项单独 brainstorm → spec → 实施，本期不细化：

- 知识图谱 / GraphRAG（Neo4j + LightRAG v1.5，接感知闭环第④步）
- EHS 隐患识别（SIF + 四维根因，Slide 7）
- 多渠道推送 + 订阅规则引擎（Slide 8）→ 闭环整改跟踪（第⑤⑥步）
- 持续加固：MinerU 3.1 升级、前端清 mock、legacy 收口

### 5.6 决策建议

1. 强烈建议按阶段顺序：地基 → 招牌 → 扩展。跳过地基直接做招牌，会在生产暴露超时/无鉴权/数据丢失。
2. 阶段一第 4 项（Reranker）可立即做 —— 半天见效，与其它解耦，适合先尝甜头。
3. 阶段二二选一先行：要 demo 冲击力选"感知闭环"；要问答质量选"Agentic 检索"。

---

## 6. 最新 AI 技术调研（支撑选型）

| 技术 | 版本/状态（2026） | 对应机会点 |
|------|------------------|-----------|
| LightRAG | v1.5.0（2026-06），EMNLP 2025；KG-RAG，原生支持 Neo4j + MinerU/Docling，含 Web UI 图谱可视化 | #7 知识图谱 |
| MinerU | v3.1.0（2026-04），协议转为 Apache 2.0 基础的开源协议，VLM 解析（MinerU2.5-Pro），109 语言 OCR | #15 本地解析兜底 |
| BGE Reranker | `bge-reranker-v2.5-gemma2-lightweight`（token 压缩 + 分层轻量化，生产推荐） | #5 Reranker 升级 |
| BGE-M3 | 100+ 语言，8192 上下文，dense+sparse+colbert 统一（现已在用） | 现有嵌入 |
| RAGFlow | 2026 支持 DeepSeek v4 / MCP / 跨语言查询；agentic RAG 参考实现 | #6 Agentic 检索参考 |

---

## 7. 验收与边界

### 7.1 本文档明确不做（YAGNI）

- 阶段三所有子项目（图谱、EHS、推送、整改闭环、企业集成）仅列方向，不在本期展开。
- 移动端适配（AGENTS.md 明确 desktop-first）。
- 感知闭环的第④⑤⑥步（图谱同步、推送、整改）。

### 7.2 架构约束（必须遵守）

- 后端遵循 `api → application → domain ports → infrastructure`（`docs/architecture/backend-project-architecture.md` 为权威）。
- 新业务逻辑不得落入 `services/*`、`workflows/*`（legacy 迁移区）。
- `shared/bootstrap.py` 为依赖装配 composition root，新依赖在此接线。
- 后端注释/docstring 全英文（AGENTS.md 规范）。

### 7.3 下一步

经用户审阅本 spec 后，对**阶段一**（异步任务化优先）调用 writing-plans 拆分为分步实施计划。