# 政务公文 RAG 系统 — 实施进度

> 最近更新: 2026-03-18（Guide 回归修复：入库保留旧 Guide、引用并存、检索并集语义）

## Phase 1: 基础设施搭建
- [x] 1.1 Docker 部署 OpenSearch 2.19 (含 IK 分词器) — `docker/docker-compose.yml`, `docker/opensearch/`（已从 ES 8.x 迁移）
- [x] 1.2 Docker 部署 Neo4j (含 APOC) — `docker/docker-compose.yml`
- [x] 1.3 Docker 部署 Redis — `docker/docker-compose.yml`
- [x] 1.4 Python FastAPI 项目骨架 — `backend/` 全套代码
- [x] 1.5 Vue 3 前端项目骨架 — `frontend/` 全套代码
- [x] 1.6 Nginx 反向代理配置 — `docker/nginx/nginx.conf`
- [x] 1.7 创建 ES 索引 (mapping) — `backend/app/infrastructure/es_client.py` + `backend/scripts/init_es_index.py`
- [x] 1.8 创建 Neo4j 约束和索引 — `backend/app/infrastructure/neo4j_client.py` + `backend/scripts/init_neo4j_schema.py`

## Phase 2: 文档入库管线
- [x] 2.1 Python 侧 Webhook 接收 + PDF 暂存 — `backend/app/api/v1/ingest.py` (webhook_receive_document)
- [x] 2.2 权限变更 Webhook — `backend/app/api/v1/ingest.py` (webhook_update_permission)
- [x] 2.3 Python: PDF 解析模块 (PyMuPDF) — `backend/app/core/document_processor.py`
- [x] 2.4 Python: 智能分块模块 — `backend/app/core/chunker.py`
- [x] 2.5 Python: Embedding 批量生成 — `backend/app/core/embedding.py`
- [x] 2.6 Python: ES Bulk 写入 — `backend/app/infrastructure/es_client.py` (bulk_index_chunks)
- [x] 2.7 Celery Worker 任务流编排 — `backend/app/tasks/ingest_task.py` + `backend/app/core/ingest_pipeline.py`
- [x] 2.8 批量导入脚本 — `backend/scripts/bulk_ingest.py`
- [x] 2.9 入库端到端测试 — `backend/tests/test_flow_ingest_search.py` (webhook → 等待完成 → 搜索 → 详情 → 删除)

## Phase 3: 混合检索与权限
- [x] 3.1 权限解析模块 — `backend/app/core/permission.py` (PermissionContext + PermissionService + Redis 缓存)
- [x] 3.2 ES RRF 混合检索引擎 — `backend/app/core/search_engine.py` (BM25 + kNN + RRF + ACL pre-filter)
- [x] 3.3 文档级结果聚合 — `search_engine.py` (_aggregate_to_documents: chunk→doc 聚合)
- [x] 3.4 搜索 API 完整实现 — `backend/app/api/v1/search.py` (hybrid_search + suggest)
- [x] 3.5 Redis 用户权限缓存 — `permission.py` (PermissionService 含 Redis get/set)
- [x] 3.6 文档详情 API — `backend/app/api/v1/document.py` (权限校验 + 元数据返回)
- [x] 3.7 管理统计 API — `backend/app/api/v1/admin.py` (ES/Neo4j/Redis 实时统计)
- [x] 3.8 前端: 搜索页面 — Phase 1 已创建 (SearchView, ResultCard, AdvancedFilter)
- [x] 3.9 检索端到端测试 — 已验证：BM25+kNN混合检索 200 OK，ACL权限过滤正常，RRF降级处理正常

## Phase 4: 知识图谱构建 ✅
- [x] 4.1 LLM 实体抽取 Prompt 设计 — `backend/app/prompts/entity_extraction.py`
- [x] 4.2 实体抽取 + 消歧/归一化模块 — `backend/app/core/graph_builder.py` (GraphBuilder)
- [x] 4.3 Neo4j 写入模块 (merge 语义) — `neo4j_client.merge_document_graph()` + `_merge_node()` + `_merge_rel()`
- [x] 4.4 文号引用识别 — `graph_builder._scan_doc_numbers()` (regex) + LLM 抽取 `referenced_doc_numbers`
- [x] 4.5 图谱构建集成到入库管线 — `ingest_pipeline.py` Step 6 (可选, 失败不阻塞) + `create_pipeline(with_graph=True)`
- [x] 4.6 存量数据批量构建脚本 — `backend/scripts/bulk_build_graph.py` (滚动查询 + 并发控制)
- [x] 4.x Celery 图谱任务 — `backend/app/tasks/graph_task.py` (build_document_graph_task + bulk_build_graph_task)

## Phase 5: Research 研究模式 ✅
- [x] 5.1 图谱查询服务 — `backend/app/core/graph_query_service.py` (entity search, doc discovery, entity neighborhood)
- [x] 5.2 研究任务 / 计划模型 — `backend/app/api/schemas/research.py` (ResearchTask, ResearchPlan, ResearchRunRequest, ResearchSectionRerunRequest)
- [x] 5.3 计划生成 + 深度研究 Prompt — `backend/app/prompts/research_prompts.py` (plan, structured report, section rerun templates)
- [x] 5.4 Research Engine 深度研究编排 — `backend/app/core/research_engine.py` (plan generation, structured SSE, report assembly, section rerun)
- [x] 5.5 Research API 完整实现 — `backend/app/api/v1/research.py` (POST /research, /research/plan, /research/run, /research/sections/rerun)
- [x] 5.6 前端 Research 工作台 — `frontend/src/views/ResearchView.vue` + `frontend/src/stores/research.ts` + `frontend/src/types/research.ts`
- [x] 5.7 导出与章节迭代 — `frontend/src/views/ResearchView.vue` (Markdown / Word / 汇报版导出 + section rerun action)
- [x] 5.8 SSE 完成语义修复 — `frontend/src/composables/useSSE.ts` (guard onDone to avoid duplicate completion callbacks)
- [x] 5.9 Graph API 完整实现 — `backend/app/api/v1/graph.py` (POST /graph/search, GET /entity/:id, POST /related-docs, GET /overview)
- [x] 5.x deps.py 补充 get_embedding_client / get_llm_client

## Phase 6: 图谱可视化 + 管理后台
- [x] 6.1 图谱子图查询 API — `graph.py` GET /graph/overview + GET /entity/:id/neighborhood
- [x] 6.2 前端: 知识图谱探索页 — `GraphExplorer.vue` (G6 画布 + 实体搜索 + 展开邻居 + 全局概览，已接入真实 API)
- [x] 6.3 前端: 管理后台 Dashboard + 入库日志 — `Dashboard.vue` (统计卡片 + 服务健康状态 + 入库日志分页表格) + `admin.py` GET /admin/ingest-logs

## Phase 7: 性能优化 + 生产加固 ✅
- [x] 7.1 搜索结果缓存 — `app/utils/query_cache.py` + `search.py` (per-user Redis cache, TTL 2min)
- [x] 7.2 Embedding 向量缓存 — `query_cache.py` (SHA256 key, TTL 1h，可复用于 research engine)
- [x] 7.3 接口限流中间件 — `app/middleware/rate_limit.py` (Redis 滑动窗口, Research 10/60s, Search 60/60s)
- [x] 7.4 限流/缓存配置项 — `config.py` 新增 rate_limit_* / *_cache_ttl 配置
- [x] 7.5 环境变量配置示例 — `backend/.env.example` (完整生产配置模板)
- [ ] 7.6 压力测试脚本 (可选，按需补充)

## Phase 8: Elasticsearch → OpenSearch 迁移 ✅
- [x] 8.1 迁移方案文档 — `docs/opensearch-migration.md`
- [x] 8.2 Python 依赖替换 — `pyproject.toml` (`elasticsearch[async]` → `opensearch-py[async]`)
- [x] 8.3 ES 客户端核心改造 — `es_client.py` (AsyncOpenSearch + knn_vector + search pipeline)
- [x] 8.4 RRF 查询重写 — `search_engine.py` + `research_engine.py` (retriever API → hybrid query + pipeline)
- [x] 8.5 Celery 任务/脚本替换 — `ingest_pipeline.py`, `ingest_task.py`, `graph_task.py`, `bulk_build_graph.py`
- [x] 8.6 API 层响应解析统一 — `document.py`, `admin.py`, `admin_graph.py`, `mock.py`, `search.py`
- [x] 8.7 Docker 配置 — `docker/opensearch/` + `docker-compose.yml` + `docker-compose-bind.yml`
- [x] 8.8 端到端验证 — 53 passed, 1 skipped (ASGI 模式, OpenSearch 2.19.4)

## Phase 9: 自动化测试 ✅
- [x] 9.1 测试框架搭建 — pytest + pytest-asyncio + httpx + asgi-lifespan
- [x] 9.2 conftest.py 基础 Fixture — client (ASGI/HTTP 双模式), auth_headers, user_headers, example_pdf_path
- [x] 9.3 接口粒度测试 — 153 个 API 用例（含 admin_graph、mock helpers、document versions、research plan/run/rerun 等）
- [x] 9.4 业务流程测试 — 4 个测试文件, 7 个用例 (导入搜索全流程, ACL 权限, 研究 Q&A, 图谱构建)
- [x] 9.5 测试文档 — `docs/testing.md` (用例清单 + 运行指南 + CI/CD 建议)
- [x] 9.6 当前仓库测试收集量 — `python -m pytest --collect-only -q` = 303 collected（2026-03-13）

## Phase 10: Guide 契约加固
- [x] 10.1 Guide API 统一依赖注入与 ACL 复用 — `backend/app/api/v1/service_guide.py` + `backend/app/core/permission.py`
- [x] 10.2 Guide 抽取器日志与容错增强 — `backend/app/core/service_guide_extractor.py`
- [x] 10.3 Guide profile API 首批强类型化 — `backend/app/api/schemas/service_guide.py`（稳定字段显式模型 + `extra=allow` 兼容未来扩展）
- [x] 10.4 Guide schema / API 定向回归 — `backend/tests/test_service_guide_schema_unit.py` + `backend/tests/test_service_guide_api_unit.py` + `backend/tests/test_service_guide_extractor_unit.py`
- [x] 10.5 Guide 内部链路 typed 化起步 — `backend/app/schemas/service_guide_profile.py` + `backend/app/core/service_guide_extractor.py` + `backend/app/core/ingest_pipeline.py`
- [x] 10.6 Guide 抽取失败降级与历史 profile 兼容读取 — `backend/app/core/service_guide_extractor.py` + `backend/app/api/v1/service_guide.py`
- [x] 10.7 Guide 列表查询参数对齐 PRD §12.1 — `backend/app/api/v1/service_guide.py` + `backend/tests/test_service_guide_api_unit.py`
- [x] 10.8 Guide 前端页面与用户入口 — `frontend/src/views/ServiceGuidesView.vue` + `frontend/src/views/GuideDetailView.vue` + `frontend/src/api/serviceGuide.ts`
- [x] 10.9 Guide 文档详情与 QA/Research 引用跳转 — `frontend/src/views/DocDetailView.vue` + `frontend/src/components/CitationCard.vue` + `frontend/src/utils/referenceRouting.ts`
- [x] 10.10 Guide 字段级证据标签回显 — `backend/app/core/research_engine.py` + `frontend/src/components/CitationCard.vue`
- [x] 10.11 Guide 回归修复闭环 — `backend/app/core/ingest_pipeline.py` + `backend/app/core/research_engine.py` + `backend/app/infrastructure/es_client.py` + `frontend/src/stores/qa.ts` + `frontend/src/stores/research.ts` + `backend/tests/test_ingest_pipeline_service_guide_unit.py` + `backend/tests/test_research_engine_unit.py` + `backend/tests/test_es_client_service_guide_unit.py`

> 当前已做：API、extractor、ingest pipeline 已共用 typed profile；识别到 Guide 但抽取失败时会按 `detected=true, profile=None` 降级；该分支现会保留既有 Guide 摘要字段与旧结构化结果，不再误删历史 Guide；detail API 可兼容历史脏 profile；列表 API 已支持 `query`/`q`、`basic_code`、`matter_type`、`handled_org`、`region`、`express_supported`、`reservation_supported`、`must_onsite` 等组合筛选；前端已新增 Guide 列表页、详情页、事项详情导流入口，并支持从文档详情与 QA/Research Guide 引用直接跳转到 Guide 页面；Guide 引用现可与同 doc_id 的普通文档引用共存，且深度研究里 `doc_ids` 与 `matter_ids` 组合检索已改为并集 anchor 语义并补齐回归测试；Guide 引用卡片现已回显命中的字段标签（如材料、收费、时限、窗口、咨询、流程）。
>
> 以后再做：继续推进 root_fields / bindings / quality 的 typed 化，并在 Guide detail / summary / related 系列接口定型后，统一评估是否把 ServiceGuideDetailResponse 从“顶层摘要字段 + profile”收敛为仅保留 profile。

---

## 已完成文件清单

### 文档
- `docs/PRD.md` — 产品需求文档
- `docs/PROGRESS.md` — 本文件，实施进度跟踪

### Docker & 基础设施
- `docker/docker-compose.yml` — OpenSearch 2.19 + Neo4j 5.x + Redis 7.x
- `docker/docker-compose-bind.yml` — Bind-mount 版本
- `docker/opensearch/Dockerfile` — OpenSearch 2.19 + IK 分词器
- `docker/opensearch/opensearch.yml` — OpenSearch 配置
- `docker/opensearch/analysis/gov_synonyms.txt` — 政务同义词表
- `docker/nginx/nginx.conf` — Nginx 反向代理
- `docs/opensearch-migration.md` — ES → OpenSearch 迁移方案文档

### Python 后端 (FastAPI)
- `backend/pyproject.toml` — 依赖管理
- `backend/app/main.py` — FastAPI 入口 + lifespan
- `backend/app/config.py` — 配置管理 (pydantic-settings)
- `backend/app/api/deps.py` — 公共依赖 (ES/Neo4j/Redis 客户端, JWT 认证)
- `backend/app/api/v1/router.py` — API 路由汇总
- `backend/app/api/v1/search.py` — 搜索 API（混合检索 + suggest + 权限过滤）
- `backend/app/api/v1/research.py` — 研究 API（兼容模式 + plan/run + section rerun）
- `backend/app/api/v1/document.py` — 文档详情 / 图谱 / 版本接口
- `backend/app/api/v1/graph.py` — 图谱、事项、推荐、政策链查询 API
- `backend/app/api/v1/ingest.py` — 入库 API + Webhook 接收端点（完整实现）
- `backend/app/api/v1/admin.py` — 管理 API（系统统计 + 入库日志）
- `backend/app/api/v1/service_guide.py` — Guide 列表 / 明细 API（公开优先 + ACL + typed profile 输出）
- `backend/app/api/schemas/search.py` — 搜索请求/响应模型
- `backend/app/api/schemas/research.py` — 研究请求/响应模型
- `backend/app/api/schemas/document.py` — 文档详情模型
- `backend/app/api/schemas/ingest.py` — 入库请求/状态模型
- `backend/app/api/schemas/service_guide.py` — Guide API 模型（首批稳定字段强类型 + 扩展字段兼容）
- `backend/app/schemas/service_guide_profile.py` — Guide 共享 profile 模型（供 API / extractor / ingest pipeline 复用）
- `backend/app/infrastructure/es_client.py` — ES 客户端 (含完整 mapping)
- `backend/app/infrastructure/neo4j_client.py` — Neo4j 客户端 (含 schema)
- `backend/app/infrastructure/redis_client.py` — Redis 客户端 (权限缓存)
- `backend/app/infrastructure/llm_client.py` — LLM API 客户端
- `backend/app/infrastructure/embedding_client.py` — Embedding API 客户端
- `backend/app/core/document_processor.py` — PDF 解析 + 文本清洗
- `backend/app/core/chunker.py` — 智能分块（段落级 + 重叠窗口）
- `backend/app/core/embedding.py` — Embedding 批量生成（重试 + 并发控制）
- `backend/app/core/ingest_pipeline.py` — 入库管线编排（解析→分块→Embedding→ES写入→元数据→图谱构建）
- `backend/app/core/graph_builder.py` — 知识图谱构建器（LLM抽取→归一化→Neo4j写入）
- `backend/app/core/graph_query_service.py` — 图谱查询服务（实体搜索、文档发现、邻居子图）
- `backend/app/core/research_engine.py` — 研究引擎（plan-driven deep research + structured SSE + section rerun）
- `backend/app/prompts/entity_extraction.py` — 实体抽取 Prompt
- `backend/app/prompts/research_prompts.py` — 研究分析 Prompt（计划 / 结构化报告 / 章节重跑）
- `backend/app/tasks/celery_app.py` — Celery 配置
- `backend/app/tasks/ingest_task.py` — Celery 入库任务 + 权限更新任务
- `backend/app/tasks/graph_task.py` — Celery 图谱构建任务
- `backend/app/utils/logger.py` — 日志配置
- `backend/scripts/bulk_ingest.py` — 存量文档批量导入脚本
- `backend/scripts/bulk_build_graph.py` — 存量数据批量图谱构建脚本
- `backend/scripts/init_es_index.py` — ES 索引初始化脚本
- `backend/scripts/init_neo4j_schema.py` — Neo4j schema 初始化脚本
- `backend/tests/conftest.py` — 测试 fixtures (client 双模式, JWT helpers, PDF 路径)
- `backend/tests/test_api_health.py` — 健康检查接口测试 (2 用例)
- `backend/tests/test_api_mock.py` — Mock OA 接口测试 (9 用例)
- `backend/tests/test_api_search.py` — 搜索接口测试 (8 用例)
- `backend/tests/test_api_ingest.py` — 文档导入接口测试 (11 用例)
- `backend/tests/test_api_document.py` — 文档详情接口测试 (6 用例)
- `backend/tests/test_api_admin.py` — 管理接口测试 (8 用例)
- `backend/tests/test_api_research.py` — 研究接口测试（plan / legacy / run / section rerun，共 7 用例）
- `backend/tests/test_research_engine_unit.py` — ResearchEngine 单元测试（graph evidence / plan / structured report / section rerun）
- `backend/tests/test_service_guide_api_unit.py` — Guide API 单元测试（ACL、按事项、typed profile 返回）
- `backend/tests/test_service_guide_schema_unit.py` — Guide schema 单元测试（typed profile 兼容扩展字段）
- `backend/tests/test_service_guide_extractor_unit.py` — Guide 抽取器单元测试（材料、咨询投诉、多行字段、容错）
- `backend/tests/test_ingest_pipeline_service_guide_unit.py` — Guide 入库链路单元测试（抽取触发、Matter 绑定、typed profile 序列化、失败降级保留旧 Guide）
- `backend/tests/test_es_client_service_guide_unit.py` — Guide 检索单元测试（`doc_ids` + `matter_ids` 并集 anchor 语义）
- `backend/tests/test_api_graph.py` — 知识图谱接口测试 (6 用例)
- `backend/tests/test_flow_ingest_search.py` — 流程: 导入→搜索全生命周期 (2 用例)
- `backend/tests/test_flow_permission.py` — 流程: ACL 权限控制 (1 用例)
- `backend/tests/test_flow_research.py` — 流程: 研究 Q&A 管道 (3 用例)
- `backend/tests/test_flow_graph.py` — 流程: 图谱构建+查询 (1 用例)
- `backend/app/middleware/__init__.py` — 中间件包
- `backend/app/middleware/rate_limit.py` — Redis 滑动窗口限流中间件
- `backend/app/utils/query_cache.py` — Embedding 向量缓存 + 搜索结果缓存 (Redis)
- `backend/.env.example` — 环境变量配置模板

### Vue 3 前端
- `frontend/package.json` — 依赖
- `frontend/vite.config.ts` — Vite 配置 (含 API 代理)
- `frontend/tsconfig.json` — TypeScript 配置
- `frontend/index.html` — SPA 入口
- `frontend/src/main.ts` — App 入口
- `frontend/src/App.vue` — 根组件 (Layout)
- `frontend/src/router/index.ts` — 路由配置
- `frontend/src/api/request.ts` — Axios 实例
- `frontend/src/api/search.ts` — 搜索 API
- `frontend/src/api/research.ts` — 研究 API（plan / run / section rerun 请求体）
- `frontend/src/api/document.ts` — 文档 API
- `frontend/src/api/graph.ts` — 图谱 API
- `frontend/src/stores/user.ts` — 用户状态
- `frontend/src/stores/search.ts` — 搜索状态
- `frontend/src/stores/research.ts` — 研究工作台状态（task / plan / report / imported items 多会话持久化）
- `frontend/src/composables/useSSE.ts` — SSE 流式响应 hook
- `frontend/src/composables/useSearch.ts` — 搜索组合式函数
- `frontend/src/components/SearchBar.vue` — 搜索栏组件
- `frontend/src/components/ResultCard.vue` — 搜索结果卡片
- `frontend/src/components/ChatMessage.vue` — 聊天消息组件
- `frontend/src/components/MarkdownRenderer.vue` — Markdown 渲染组件
- `frontend/src/components/AdvancedFilter.vue` — 高级筛选组件
- `frontend/src/views/SearchView.vue` — 搜索页面
- `frontend/src/views/ResearchView.vue` — Deep Research 工作台（计划、报告、章节重跑、导出）
- `frontend/src/types/research.ts` — Research task/plan/report 类型定义
- `frontend/src/views/DocDetailView.vue` — 文档详情页面
- `frontend/src/views/GraphExplorer.vue` — 图谱探索页面
- `frontend/src/views/ServiceGuidesView.vue` — Guide 列表页（筛选、分页、跳转 QA/原文/详情）
- `frontend/src/views/GuideDetailView.vue` — Guide 详情页（材料、收费、流程、窗口、咨询、质量提示）
- `frontend/src/api/serviceGuide.ts` — Guide 列表/详情 API 封装
- `frontend/src/types/service-guide.d.ts` — Guide 前端类型定义
- `frontend/src/utils/referenceRouting.ts` — QA/Research 引用的目标路由解析（Guide → 指南详情，其他 → 文档详情）
- `frontend/src/views/admin/Dashboard.vue` — 管理后台
- `frontend/src/types/search.d.ts` — 搜索类型定义
- `frontend/src/types/document.d.ts` — 文档类型定义
- `frontend/src/types/graph.d.ts` — 图谱类型定义
- `frontend/src/styles/global.less` — 全局样式