# 首版交付清单与实施方案（不含 Phase 2 条款图）

> 文档性质：首版交付范围与排期建议。
>
> 目标：在不实现 Phase 2A / 2B 条款图的前提下，优先交付 PRD 中最核心、最稳定、最有业务价值的场景能力。

---

## 1. 结论摘要

可以先不做 Phase 2A / 2B，仍然交付 PRD 中大部分核心场景能力。

但需要同步调整产品承诺：

- 首版交付到文档级、主题级、事项级
- 不承诺条款级定位、条款级证据回链、哪一条规定了什么
- 所有 `article_detail` 类能力整体后置到 Phase 2

如果以“稳定、可用、不影响基础功能、不明显拖慢性能”为优先目标，建议首版范围收敛为：

- 普通检索
- 文档详情与治理链
- 图谱增强的基础探索能力
- 事项知识卡与办事问答
- Research 首版

建议暂不纳入首版：

- 条款图相关全部能力
- 治理分析接口
- 主题地图
- 条款级 Research 可解释问答

---

## 2. 场景可交付矩阵

### 2.1 docs/PRD 场景

| 场景 | 是否首版可交付 | 交付口径 |
|------|----------------|----------|
| 场景一：普通检索 | 可以 | 按 PRD 正常交付 |
| 场景二：Research 研究型分析 | 可以，但范围收敛 | 做文档级 / chunk 级引用，不做条款级 |

### 2.2 graph-schema-optimization 场景

| 场景 | 是否首版可交付 | 说明 |
|------|----------------|------|
| 场景 A：文档详情推荐与治理链 | 可以 | Phase 0 范围，优先交付 |
| 场景 B：对话增强问答 | 可以，但只做子集 | 不含 `article_detail` |
| 场景 C：事项知识卡与办事问答 | 可以 | Phase 1 范围，优先交付 |
| 场景 D：治理型分析接口 | 暂不纳入首版 | 与 Phase 2 无强依赖，但建议后置 |
| 场景 E：主题地图 | 暂不纳入首版 | 与 Phase 2 无强依赖，但建议后置 |
| 场景 F：Research 专题研究 | 可以做首版收缩版 | 不做条款级引用和条款级解释 |

---

## 3. 首版可交付范围

### 3.1 普通检索

首版完整交付，不需要依赖 Phase 2。

交付内容：

- 混合检索：BM25 + 向量检索 + RRF 融合
- 权限过滤
- 高亮片段
- 聚合统计
- 分页
- 搜索建议

首版价值：

- 这是最核心的用户入口
- 对系统稳定性和响应时间要求最高
- 不应受条款图范围波动影响

### 3.2 文档详情与治理链

首版交付，作为图谱价值的第一层展示。

交付内容：

- 文档详情
- 文档版本信息
- 原文 / PDF 访问
- 文档子图
- 同机构 / 同主题 / 同地域推荐
- 政策依据链
- 修订 / 废止历史
- 同主题文档

交付目标：

- 先把 Document 级图谱价值稳定落地
- 先证明治理关系对检索和浏览有增强作用

### 3.3 图谱基础探索能力

首版交付，但范围控制在通用实体层，不引入 Article。

交付内容：

- 实体搜索
- 实体邻域图
- 通过实体找相关文档
- 文档关联实体
- 图谱概览

口径说明：

- 首版图谱浏览只覆盖 Phase 0 和 Phase 1 实体
- 不展示 Article 节点

### 3.4 事项知识卡与办事问答

首版交付，作为最重要的业务增强能力之一。

交付内容：

- 事项搜索
- 事项知识卡
- 办理条件、所需材料、办理时限
- 适用对象
- 办理部门
- 事项适用地域
- 依据文件列表

交付目标：

- 回答“需要什么材料”“多久办完”“哪个部门负责”
- 建立事项级结构化问答能力
- 用 Matter 替代条款级能力的第一阶段业务承载

### 3.5 对话增强问答

可以先做，但必须明确不含条款级问题。

首版建议支持的 query types：

- `policy_basis`
- `revision_status`
- `issuing_org`
- `theme_related`
- `matter_info`
- `material_list`

首版明确不支持：

- `article_detail`

产品口径必须同步改成：

- 可以回答“依据什么文件”“是否已废止”“哪个部门发布”“某事项需要哪些材料”
- 不承诺回答“依据哪一条”“哪条规定了这个要求”

### 3.6 Research 首版

可以交付一个收缩版，但不做条款级引用和条款级推理。

首版建议交付内容：

- 专题概述
- 核心文件清单
- 时间演进轨迹
- 依据链梳理
- 相关事项概览
- 引用文档列表
- 图谱辅助找到的相关文档

首版引用粒度：

- 文档级
- chunk 级

首版不承诺：

- 条款级引用
- 条款级要件定位
- “具体哪一条支撑该结论”

---

## 4. 明确延期范围

以下能力全部延期到 Phase 2 或 Phase 2 之后：

- Article 节点与 `HAS_ARTICLE`
- 条款级 `GOVERNS`
- 条款级 `ASSIGNS_TO`
- 条款级 `SETS_CONDITION`
- 条款级 `SETS_TIME_LIMIT`
- 条款级 `REQUIRES_MATERIAL`
- `article_detail`
- “依据哪一条”
- “哪条规定了这一要求”
- 条款级证据回链
- 条款级可解释问答

同时，以下能力虽然不依赖 Phase 2，但建议也不放入首版，以控制范围和风险：

- 治理分析接口
- 主题地图
- 增强版 Research 专题研究

原因不是做不了，而是首版更应该优先把基础链路、Matter 级能力和 Research 首版先做稳。

---

## 5. 首版 API 范围

建议首版 API 范围如下。

### 5.1 搜索与文档

- `POST /api/v1/search`
- `POST /api/v1/search/suggest`
- `GET /api/v1/document/{doc_id}`
- `GET /api/v1/document/{doc_id}/graph`
- `GET /api/v1/document/versions/{content_hash}`
- `GET /api/v1/document/pdf/{doc_id}`
- `GET /api/v1/document/file/{doc_id}`

### 5.2 图谱查询

- `POST /api/v1/graph/search`
- `GET /api/v1/graph/entity/{entity_id}`
- `POST /api/v1/graph/related-docs`
- `GET /api/v1/graph/document/{doc_id}/entities`
- `GET /api/v1/graph/overview`
- `GET /api/v1/graph/document/{doc_id}/recommendations`
- `GET /api/v1/graph/document/{doc_id}/policy-chain`
- `GET /api/v1/graph/document/{doc_id}/revision-history`
- `GET /api/v1/graph/document/{doc_id}/same-theme`

### 5.3 事项知识卡

- `GET /api/v1/graph/matters`
- `GET /api/v1/graph/matters/{matter_id}`
- `GET /api/v1/graph/matters/{matter_id}/requirements`

### 5.4 Research

- `POST /api/v1/research`

首版不纳入：

- 所有 `/graph/articles*` 接口
- 所有 `/topics*` 接口
- 所有 `/analytics*` 接口

---

## 6. 首版产品口径修订

为了避免“PRD 写了但首版做不到”的预期错位，建议把以下口径同步改掉：

### 6.1 可以保留的承诺

- 能发现相关文件
- 能查看政策依据链和修订关系
- 能通过主题和事项组织结果
- 能回答事项材料、时限、办理部门相关问题
- 能输出带引用的 Research 报告

### 6.2 需要改成后置能力的承诺

- “依据哪一条”
- “哪条规定了这一要求”
- 条款级证据定位
- 条款级可解释问答
- 条款级制度分析

建议统一改为：

- 首版支持文档级和事项级结构化能力
- 条款级能力将在后续 Phase 2 引入

---

## 7. 首版发布顺序

建议按以下顺序落地。

### Release 1：搜索与文档详情稳定版

交付内容：

- 普通检索
- 搜索建议
- 文档详情
- 文档版本
- 文档子图
- 原文访问

验收目标：

- 搜索主链路稳定
- 权限过滤正确
- 文档详情和版本链路可用

### Release 2：治理链与图谱探索

交付内容：

- recommendations
- policy-chain
- revision-history
- same-theme
- graph explorer 基础能力

验收目标：

- Phase 0 图谱价值可被前端稳定消费
- 通用图谱查询响应稳定

### Release 3：事项知识卡与办事问答

交付内容：

- matters 搜索
- matter card
- requirements
- Matter 级问答支撑

验收目标：

- 事项卡结果结构完整
- Matter 级问答可直接支持真实业务问题

### Release 4：Research 首版 + 对话增强问答子集

交付内容：

- 多路召回
- 文档引用
- 图谱增强找文档
- 多轮 session
- 收缩版专题研究
- 规则优先的问题模板子集（`policy_basis`、`revision_status`、`issuing_org`、`theme_related`、`matter_info`、`material_list`）

验收目标：

- 可以生成稳定的研究型输出
- 不承诺条款级解释
- 高频问答可优先走模板与图谱增强，不阻塞普通 Research 输出

---

## 8. 首版必须补齐的验收

### 8.1 功能验收

必须验证：

- 搜索结果正确返回且权限过滤生效
- 文档详情、版本、原文访问可用
- recommendations / policy-chain / revision-history 可用
- Matter 搜索和知识卡可用
- Research SSE 输出稳定
- 对话增强问答子集可用，且失败时能回退普通 Research

### 8.2 回归验收

必须覆盖：

- 搜索接口回归
- Research 接口回归
- 图谱接口回归
- Matter 接口回归
- 文档详情接口回归

### 8.3 性能验收

优先观察：

- `/api/v1/search`
- `/api/v1/document/{doc_id}`
- `/api/v1/graph/overview`
- `/api/v1/graph/matters`
- `/api/v1/research`

目标：

- 现有在线接口不因新增 Matter / 图谱查询而出现明显回退
- Research 首字输出可接受
- 图谱查询结果量可控

---

## 9. 推荐采纳口径

如果当前决策是“先不做 Phase 2A+2B”，建议将首版正式范围定义为：

- 交付 Document 级 + Matter 级的核心业务能力
- 交付 Research 首版，但只做到文档级 / chunk 级解释
- 明确将条款级能力整体后置

这样做的优势是：

- 可以先把高频场景做稳
- 不会为了条款图引入额外复杂度和性能风险
- 后续 Phase 2 可以作为增强版能力独立推进，不影响首版上线

本质上，这是一条“先交付可用系统，再逐步增强解释粒度”的路线，而不是“等条款图完全做好后再上线”的路线。

---

## 10. 实施原则

首版实施遵循以下原则：

- 不引入 Article 相关 schema、接口和前端展示
- 所有新增能力优先复用现有接口和页面，不为首版范围外能力预埋复杂交互
- 先完成后端稳定接口，再推进前端消费，最后做端到端联调
- 每个 Release 都要有清晰的入口条件、出口条件和回滚方案
- 任何增强能力失败都不能影响搜索、文档详情和权限过滤主链路

---

## 11. 分阶段实施方案

### 11.1 Release 1：搜索与文档详情稳定版

#### 后端任务

- 稳定 `search`、`suggest`、`document detail`、`document graph`、`document versions`、`pdf/file` 相关接口
- 校验搜索缓存、权限过滤、高亮、分页、聚合统计的实际返回结构
- 补齐文档详情、版本、原文访问的异常场景和 ACL 行为

#### 重点文件

- `backend/app/api/v1/search.py`
- `backend/app/api/v1/document.py`
- `backend/app/core/search_engine.py`
- `backend/app/core/permission.py`

#### 前端任务

- 搜索页和文档详情页按现有路由稳定交付
- 打通搜索结果到文档详情跳转
- 校验高亮、分页、聚合统计与文档详情展示一致

#### 重点文件

- `frontend/src/views/SearchView.vue`
- `frontend/src/views/DocDetailView.vue`
- `frontend/src/router/index.ts`

#### 测试与验收

- `backend/tests/test_api_search.py`
- `backend/tests/test_api_document.py`
- `backend/tests/test_api_document_versions.py`
- `backend/tests/test_acl_boundary.py`

#### 入口条件

- 索引写入链路可用
- 权限映射与 JWT 登录链路可用

#### 出口条件

- 搜索与文档详情相关接口全部通过回归
- 前端搜索和文档详情页可完成主流程演示

### 11.2 Release 2：治理链与图谱探索

#### 后端任务

- 稳定 GraphQueryService 中的 Phase 0 查询能力
- 交付 recommendations、policy-chain、revision-history、same-theme、entity search、related-docs、overview
- 明确 graph explorer 只展示 Document、Organization、Region、PolicyTheme 与 Phase 1 实体，不引入条款节点

#### 重点文件

- `backend/app/core/graph_query_service.py`
- `backend/app/api/v1/graph.py`
- `backend/app/api/v1/document.py`

#### 前端任务

- 稳定图谱探索页
- 在文档详情页补齐推荐、依据链、修订历史、同主题入口或展示位
- 保持图谱概览节点数与返回体可控

#### 重点文件

- `frontend/src/views/GraphExplorer.vue`
- `frontend/src/views/DocDetailView.vue`

#### 测试与验收

- `backend/tests/test_api_graph.py`
- `backend/tests/test_api_document.py`
- `backend/tests/test_acl_boundary.py`

#### 入口条件

- Phase 0 数据已完成至少一轮全量重建
- 占位文档吸收、治理关系写入稳定

#### 出口条件

- 治理链查询可用于真实样例演示
- 图谱探索页不出现明显性能回退和返回体膨胀

### 11.3 Release 3：事项知识卡与办事问答

#### 后端任务

- 以 Phase 1 为上线前提，完成 Matter、Condition、Material、TimeLimit、TargetGroup 的构建与查询闭环
- 稳定 `search_matters`、`get_matter_card`、`get_matter_requirements`
- 校验 Matter 相关 ID 生成、归一化规则和 governing_docs 结果

#### 重点文件

- `backend/app/core/graph_builder.py`
- `backend/app/prompts/entity_extraction.py`
- `backend/app/core/graph_query_service.py`
- `backend/app/api/v1/graph.py`
- `backend/app/infrastructure/neo4j_client.py`

#### 前端任务

- 建议新增首版事项页与事项详情页，避免 Matter 能力只能通过接口验证
- 如果排期过紧，至少要在文档详情页或图谱页提供 Matter 搜索与事项卡入口

#### 建议新增前端文件

- `frontend/src/views/MattersView.vue`
- `frontend/src/views/MatterDetailView.vue`
- `frontend/src/router/index.ts`

#### 测试与验收

- `backend/tests/test_phase1_unit.py`
- `backend/tests/test_api_graph.py`
- `backend/tests/test_graph_builder_unit.py`
- `backend/tests/test_graph_schema_unit.py`

#### 入口条件

- 确认 Phase 1 schema 在目标环境启用
- 完成一次全量重建并通过基础 Cypher 校验

#### 出口条件

- Matter 搜索、知识卡、requirements 可被前端稳定消费
- 至少能稳定回答材料、时限、办理部门三类高频问题

### 11.4 Release 4：Research 首版 + 对话增强问答子集

#### 后端任务

- 稳定当前 `/research` SSE 输出链路
- 优化关键词抽取、多路召回、引用输出、session 持久化
- 对“对话增强问答”采取最小实现：
	- 优先新增 `graph_query_planner.py` 和 `query_planning.py`
	- 若排期不足，则先在 Research 流程内加入规则优先模板分流，不单独开放复杂新接口
- 首版只支持 `policy_basis`、`revision_status`、`issuing_org`、`theme_related`、`matter_info`、`material_list`
- 明确不实现 `article_detail`

#### 重点文件

- `backend/app/api/v1/research.py`
- `backend/app/core/research_engine.py`
- `backend/app/core/graph_query_service.py`
- `backend/app/core/graph_query_planner.py`（建议新增）
- `backend/app/prompts/query_planning.py`（建议新增）

#### 前端任务

- 稳定研究分析页 SSE 展示、引用文档列表、图谱侧边栏、多轮会话体验
- 明确引用跳转粒度为文档级 / Chunk 级，不展示条款级承诺文案

#### 重点文件

- `frontend/src/views/ResearchView.vue`
- `frontend/src/stores/research.ts`
- `frontend/src/components/MarkdownRenderer.vue`

#### 测试与验收

- `backend/tests/test_api_research.py`
- `backend/tests/test_flow_research.py`
- `backend/tests/test_api_graph.py`

#### 入口条件

- Search、Graph、Matter 三条基础能力已可稳定提供上下文
- Research 引用与图谱数据结构已与前端对齐

#### 出口条件

- Research 首版在真实数据上可以稳定输出
- 高频问答子集失败时自动回退普通 Research，不影响主流程

---

## 12. 跨模块依赖与前置动作

### 12.1 数据与环境前置

- 完成至少一轮可复现的文档入库
- Phase 0 上线前完成一次全量图重建
- Phase 1 上线前再次执行全量图重建
- 生产环境所有上线动作必须带回滚说明

### 12.2 前后端联调前置

- 接口字段命名固定，不在联调中频繁变更响应结构
- 对 Matter 相关接口优先采用明确的 Pydantic 模型，不返回裸字典
- Research SSE chunk 类型在前后端之间先固定，再做 UI 打磨

### 12.3 不做的内容必须显式隔离

- 不新增 `/graph/articles*`
- 不新增 `/topics*`
- 不新增 `/analytics*`
- 不在前端菜单和页面中出现条款级入口

---

## 13. 完成定义与回滚要求

### 13.1 每个 Release 的完成定义

- 对应 API 已实现并通过回归测试
- 前端主路径可演示
- 至少一轮联调完成
- 关键指标无明显性能回退
- 文档与 Swagger 口径一致

### 13.2 回滚要求

- Release 1 失败时，可回滚到纯搜索链路
- Release 2 失败时，不影响搜索与文档详情
- Release 3 失败时，可以隐藏 Matter 前端入口，但不得影响 Phase 0 能力
- Release 4 失败时，可以关闭增强问答子集并退回普通 Research SSE 输出

### 13.3 首版总体 Done Definition

- 用户可以完成“搜文档、看详情、看治理链、查事项、做研究”五条主路径
- 所有能力默认只承诺文档级、主题级、事项级解释粒度
- 条款级能力在产品、接口和前端文案上均未被误承诺

---

## 14. 开发任务表（结合前端页面与交互设计）

本节将 [frontend-page-and-interaction-design.md](d:\work\zm-rag\prd\frontend-page-and-interaction-design.md) 中的页面与交互要求，收敛为可直接派工的首版开发任务表。

拆分原则：

- 以现有前端代码结构为起点，不推翻当前 Shell、路由和页面组织方式
- 先补齐首版主路径，再做条件性增强页
- 前端任务必须绑定后端接口和验收口径，避免只做静态页面
- 未进入首版范围的主题地图、治理分析、条款级锚点导航，不纳入本轮任务表

### 14.1 前端首版范围收敛

| 模块 | 是否纳入首版 | 说明 |
|------|--------------|------|
| 搜索页增强 | 是 | 对齐检索页批量导入、版本抽屉、结果操作区 |
| 文档详情页增强 | 是 | 对齐详情页右侧结构化卡片、治理链、加入 Research |
| Research 参考资料篮 | 是 | 这是跨页面核心能力，优先级高于独立 QA 页 |
| Research 工作台增强 | 是 | 对齐三栏工作区、引用列表、资料管理 |
| 图谱探索页增强 | 是 | 保留专业增强定位，补齐加入 Research 和文档跳转 |
| 事项页 `/matters` | 是 | Phase 1 已启用时纳入首版主路径 |
| 智能问答页 `/qa` | 条件纳入 | 仅在 `/api/v1/qa` 或等价模板分流能力稳定后开放 |
| 主题地图 `/topics` | 否 | 后置，不纳入首版 |
| 治理分析 `/analytics` | 否 | 后置，不纳入首版 |
| 条款级展示与锚点导航 | 否 | 后置到 Phase 2 |

### 14.2 当前前端现状与实现差距

| 维度 | 当前现状 | 与目标差距 |
|------|----------|------------|
| 路由 | 已有 `/search`、`/research`、`/qa`、`/doc/:id`、`/graph`、`/matters`、`/matters/:matterId`、`/admin*`、`/mock` | `/topics`、`/analytics` 仍未进入首版 |
| Shell | `App.vue` 已接入 Header 资料篮入口、Sider 事项入口、全局资料篮 Drawer、QA 菜单入口 | Topics / Analytics 尚无入口 |
| Store | 已有 `searchStore`、增强后的 `researchStore`、`basketStore`、`matterStore`、`qaStore`、`userStore`、`tabsStore` | Topics / Analytics 对应 store 未实现 |
| 通用组件 | 已有 `ResearchBasketDrawer`、`MatterCard`、`StatusTag`、`DocumentVersionDrawer`、`CitationCard`、`ImportToResearchDialog`、`DocumentQuickPreview` | 图谱页仍未完全切到统一导入弹窗 |
| 页面能力 | 搜索、详情、Research、QA、图谱、事项六条主路径已可演示；文档详情和事项详情已支持直接跳转独立 QA | Topics、Analytics 未实现；部分高级交互仍以后续增强为主 |
| 测试基础 | 已完成多轮 `npx vite build` 和后端定向单测；前端仍无专用测试框架 | 仍需补主路径烟测记录与联调记录；`npm run type-check` 受本地 `vue-tsc` 工具链问题影响，暂未作为稳定验收基线 |

### 14.3 基础设施与跨页面任务表

状态口径说明：

- `已完成`：当前代码已落地，主路径可用
- `部分完成`：主能力已落地，但仍有子项或验收项未完成
- `条件完成`：按首版降级方案已完成，但完整版能力未开放
- `待执行`：尚未完成联调、烟测或正式验收

| 任务 ID | 优先级 | 负责人建议 | 状态 | 任务 | 后端依赖 | 建议文件 | 完成标准 |
|---------|--------|------------|------|------|----------|----------|----------|
| FE-BASE-01 | P0 | 前端 | 已完成 | 收敛全局 Shell，保留当前布局，增加事项入口和 Research 资料篮入口 | 无硬依赖 | `frontend/src/App.vue`、`frontend/src/router/index.ts` | Header 可见资料篮入口，Sider 新增事项入口，现有路由不回归 |
| FE-BASE-02 | P0 | 前端 | 已完成 | 新增 `researchBasketStore`，支持 `document`、`snippet`、`answer`、`matter` 四类首版对象，去重并记录来源、备注、重要级别 | 无硬依赖 | `frontend/src/stores/researchBasket.ts`（建议新增） | 资料篮可跨页保留，重复加入时有稳定提示 |
| FE-BASE-03 | P0 | 前端 | 部分完成 | 落地 `ResearchBasket` Drawer 和 `ImportToResearchDialog`，统一“加入 Research”行为 | `POST /api/v1/research` | `frontend/src/components/ResearchBasket.vue`、`frontend/src/components/ImportToResearchDialog.vue`（建议新增） | 搜索页、详情页、图谱页、事项页可共用同一导入弹窗 |
| FE-BASE-04 | P0 | 前后端 | 已完成 | 整理前端 API 封装与类型定义，补齐 document、graph、matter、research 模块的响应类型 | 首版 API 全量 | `frontend/src/api/document.ts`、`frontend/src/api/graph.ts`、`frontend/src/api/research.ts`、`frontend/src/api/matter.ts`（建议新增） | 前端不再在页面内散落拼接接口结构，联调字段集中管理 |
| FE-BASE-05 | P1 | 前端 | 已完成 | 新增 `StatusTag`、`DocumentVersionDrawer`、`DocumentQuickPreview` 等通用组件，统一状态、版本和轻预览交互 | `GET /api/v1/document/versions/{content_hash}` | `frontend/src/components/StatusTag.vue`、`frontend/src/components/DocumentVersionDrawer.vue`、`frontend/src/components/DocumentQuickPreview.vue`（建议新增） | 搜索页、详情页、Research 引用区复用同一套展示组件 |
| FE-BASE-06 | P0 | 前端 + 测试 | 部分完成 | 建立首版前端验收基线：`build`、`type-check`、关键页面烟测清单、接口联调清单 | 无 | `frontend/package.json`、`prd/testing.md` 或本文件附录 | 每次提测至少通过构建检查，并完成主路径烟测记录 |

### 14.4 页面任务表

| 任务 ID | 优先级 | 页面/模块 | 状态 | 任务 | 依赖接口 | 建议文件 | 验收标准 |
|---------|--------|-----------|------|------|----------|----------|----------|
| FE-R1-01 | P0 | 搜索页 `/search` | 已完成 | 增强结果卡片，补齐查看详情、加入 Research、查看版本、查看关系等操作 | `POST /api/v1/search`、`GET /api/v1/document/versions/{content_hash}` | `frontend/src/views/SearchView.vue`、`frontend/src/components/ResultCard.vue` | 单条结果可完成“查看详情”和“加入 Research”两条主动作 |
| FE-R1-02 | P0 | 搜索页 `/search` | 已完成 | 增加多选、批量加入 Research、右侧资料篮区域，打通“搜索 → Research”主路径 | `POST /api/v1/search`、`POST /api/v1/research` | `frontend/src/views/SearchView.vue`、`frontend/src/stores/search.ts`、`frontend/src/stores/researchBasket.ts` | 可从搜索结果批量加入 3 篇文档并进入 Research |
| FE-R1-03 | P0 | 文档详情 `/doc/:id` | 已完成 | 按首版口径补齐文档概览、依据链、修订史、推荐、同主题等右侧结构化卡片 | `GET /api/v1/document/{doc_id}`、`GET /api/v1/graph/document/{doc_id}/policy-chain`、`GET /api/v1/graph/document/{doc_id}/revision-history`、`GET /api/v1/graph/document/{doc_id}/recommendations`、`GET /api/v1/graph/document/{doc_id}/same-theme` | `frontend/src/views/DocDetailView.vue` | 详情页不只展示正文，右侧可稳定展示治理增强信息 |
| FE-R1-04 | P0 | 文档详情 `/doc/:id` | 已完成 | 补齐“加入 Research”“问这个文档”“下载原文”“查看版本”等操作，并显式处理占位文档提示 | `GET /api/v1/document/file/{doc_id}`、`GET /api/v1/document/versions/{content_hash}` | `frontend/src/views/DocDetailView.vue`、`frontend/src/components/DocumentVersionDrawer.vue` | 从详情页可直接导入当前文档并可选附带依据链文件 |
| FE-R2-01 | P1 | 图谱页 `/graph` | 部分完成 | 保持当前图谱页定位，增加节点详情中的“查看文档”“加入 Research”，并确认默认不暴露 Article 节点 | `POST /api/v1/graph/search`、`POST /api/v1/graph/related-docs`、`GET /api/v1/graph/overview` | `frontend/src/views/GraphExplorer.vue` | 选中节点后可回到文档主路径或进入资料篮，图谱返回量可控 |
| FE-R2-02 | P1 | 文档详情 + 图谱 | 已完成 | 增加从详情页进入图谱探索的入口，以及从图谱返回详情时保持资料篮状态 | 复用图谱接口 | `frontend/src/views/DocDetailView.vue`、`frontend/src/views/GraphExplorer.vue` | “详情 → 图谱 → 详情”过程中资料篮不丢失 |
| FE-R3-01 | P0 | 事项页 `/matters` | 已完成 | 新增事项列表页和事项详情路由，严格使用 `matter_id` 作为稳定路由标识 | `GET /api/v1/graph/matters`、`GET /api/v1/graph/matters/{matter_id}` | `frontend/src/views/MattersView.vue`、`frontend/src/views/MatterDetailView.vue`、`frontend/src/router/index.ts`（建议新增/修改） | `/matters` 和 `/matters/:matterId` 可独立访问，刷新不丢失上下文 |
| FE-R3-02 | P0 | 事项页 `/matters/:matterId` | 已完成 | 落地事项知识卡结构，展示条件、材料、时限、适用对象、办理部门、地域和依据文件 | `GET /api/v1/graph/matters/{matter_id}`、`GET /api/v1/graph/matters/{matter_id}/requirements` | `frontend/src/views/MatterDetailView.vue`、`frontend/src/components/MatterCard.vue`（建议新增） | 至少能稳定回答材料、时限、办理部门三类高频问题 |
| FE-R3-03 | P0 | 事项页 + Research | 已完成 | 支持“加入 Research”“同时加入依据文件”“查看依据文件”“问这个事项” | Matter 接口 + `POST /api/v1/research` | `frontend/src/views/MatterDetailView.vue`、`frontend/src/stores/researchBasket.ts` | 可围绕事项发起研究，且能附带 governing docs |
| FE-R4-01 | P0 | Research `/research` | 已完成 | 将当前 Research 页增强为三栏工作台，补齐研究列表、主输出区、右侧参考资料区 | `POST /api/v1/research` | `frontend/src/views/ResearchView.vue`、`frontend/src/stores/research.ts` | 可看到会话列表、流式输出、引用区和资料区 |
| FE-R4-02 | P0 | Research `/research` | 部分完成 | 打通资料篮导入、引用文档列表、Chunk 级跳转和失败保留机制，文案只承诺文档级 / Chunk 级引用 | `POST /api/v1/research` | `frontend/src/views/ResearchView.vue`、`frontend/src/components/MarkdownRenderer.vue`、`frontend/src/components/CitationCard.vue`（建议新增） | Research 流式失败时不丢已导入资料，引用可跳文档或片段 |
| FE-R4-03 | P1 | 智能问答 `/qa` | 已完成 | 作为条件项实现独立 QA 页；若后端 planner 未就绪，则先保留“问这个文档/事项”跳转到 Research 模板模式 | `POST /api/v1/qa` 或等价模板分流能力 | `frontend/src/views/QAView.vue`、`frontend/src/stores/qa.ts`（建议新增） | QA 页仅在后端能力稳定时对外开放，否则不阻塞首版上线 |

### 14.5 联调与验收任务表

| 任务 ID | 优先级 | 负责人建议 | 状态 | 联调主题 | 依赖 | 验收标准 |
|---------|--------|------------|------|----------|------|----------|
| JT-01 | P0 | 前后端 | 待执行 | 搜索 → 详情 → Research 主路径联调 | Search、Document、Research 接口 | 能从搜索选中文档，进入详情，再把文档导入 Research |
| JT-02 | P1 | 前后端 | 待执行 | 详情治理卡片与图谱联调 | Graph Query 接口 | 依据链、修订史、推荐和图谱入口字段一致，无额外前端拼装兜底 |
| JT-03 | P0 | 前后端 | 待执行 | 事项页联调 | Matter API | `matter_id` 路由稳定，事项知识卡字段完整，依据文件可跳详情 |
| JT-04 | P0 | 前后端 | 部分完成 | Research 流式输出与引用联调 | Research SSE | SSE chunk 类型固定，引用列表和主内容中的引用编号一致 |
| JT-05 | P1 | 前后端 | 已完成 | QA 条件开放评估 | QA / Planner 能力 | QA 首轮链路已接通，可独立访问 `/qa` 并完成基础问答、引用回跳和导入 Research |

### 14.6 建议开发顺序

建议按以下顺序派工：

1. 先做 `FE-BASE-01` 到 `FE-BASE-04`，把路由、资料篮、统一导入弹窗、API 类型层打稳。
2. 再做 `FE-R1-01` 到 `FE-R1-04`，优先把“搜索 → 详情 → Research”链路跑通。
3. 然后做 `FE-R3-01` 到 `FE-R3-03`，把 Matter 能力变成真实可用页面，而不是只停留在接口层。
4. 最后做 `FE-R4-01` 到 `FE-R4-03`，增强 Research 工作台，并按后端稳定度决定是否开放独立 QA 页。

### 14.7 首版前端最小可上线标准

满足以下条件即可认为前端达到首版可上线状态：

- Header 中已存在可用的 Research 资料篮入口
- `/search`、`/doc/:id`、`/research`、`/qa`、`/graph`、`/matters` 六条主路径可独立演示
- 搜索页和详情页的“加入 Research”均走统一资料篮和统一 store
- `matter_id` 路由稳定，不依赖事项名称拼接 URL
- Research 只承诺文档级 / Chunk 级引用，不出现条款级误导文案
- `npm run build` 与 `npm run type-check` 通过，且已完成一轮主路径烟测

### 14.8 推荐实施排期（6 阶段重排版）

基于当前仓库真实状态，建议不要直接按“8 阶段并行铺开”的方式推进，而是重排为 6 个阶段。

重排原则：

- 先完成首版主路径：搜索、详情、图谱、事项、Research
- `QA` 作为条件开放项，不阻塞首版主线
- `Topics` 与 `Analytics` 不纳入首版，放到 Release + 1
- 先补壳层、资料篮和统一导入链路，再做页面增强，避免返工

#### Phase 1：基础壳层与资料篮底座

目标：把后续页面都会依赖的前端壳层、类型、API、全局状态先打稳。

范围：

- 新增前端类型与 API 封装：优先 `matter`、`basket`，`qa` 作为可选预留
- 新增 `researchBasketStore`，支持跨页收集文档、片段、事项、回答等对象
- 改造 `App.vue` Header 与 Sider：增加资料篮入口、事项入口、挂载 Drawer
- 新增首批通用组件：`StatusTag`、`ResearchBasketDrawer`、`DocumentVersionDrawer`
- 路由先补 `/matters`、`/matters/:matterId`，`/qa` 可先做隐藏占位；不新增 `/topics`、`/analytics`

说明：

- `Matter` 后端接口已存在，不应计入本阶段的“后端新增接口”工作量
- 当前 Header 和菜单都还没有资料篮能力，这一层必须前置，否则后续页面会各自实现一套“加入 Research”逻辑

验收标准：

- Header 出现资料篮入口和数量徽标
- Sider 出现事项入口
- 资料篮 Drawer 可正常打开、关闭、增删项目
- 路由新增后不影响现有 `/search`、`/research`、`/doc/:id`、`/graph` 主路径
- `npm run type-check` 与 `npm run build` 通过

#### Phase 2：搜索页、详情页、图谱页主路径增强

目标：优先打通首版最重要的“发现资料 → 沉淀资料”主路径。

范围：

- 搜索页支持单条与批量加入资料篮
- 搜索结果补齐查看版本、复制引用、查看关系等操作
- 文档详情页补右侧治理卡片：概览、依据链、修订史、推荐、操作区
- 图谱页增加加入资料篮、跳转文档详情等动作

说明：

- 这一阶段直接对应首版主路径，不需要新增新的后端能力，只需消费已有 Search、Document、Graph API
- 搜索过滤项可以同步补齐 `knowledge_category`、`status`、`region`、`theme`

验收标准：

- 可完成“搜索 → 详情 → 加入资料篮”主流程
- 搜索结果支持批量加入资料篮
- 文档详情页右侧治理增强信息稳定展示
- 图谱页可从节点回到文档主路径，并可将文档加入资料篮

#### Phase 3：事项页落地

目标：把已存在的 Matter 后端能力真正落成可用页面。

范围：

- 新增事项列表页 `/matters`
- 新增事项详情页 `/matters/:matterId`
- 新增 `MatterCard` 组件，展示条件、材料、时限、办理部门、适用地域、依据文件
- 支持从事项页加入资料篮和跳转文档详情

说明：

- 事项页属于首版主路径，应优先于 QA、Topics、Analytics 落地
- 路由参数必须严格使用 `matter_id`，不得用事项名称拼接 URL

验收标准：

- `/matters` 与 `/matters/:matterId` 可独立访问
- Matter 卡片字段完整，可稳定展示条件、材料、时限、办理部门、依据文件
- governing docs 可从事项页跳回文档详情
- 可从事项页加入资料篮

#### Phase 4：Research 工作台增强

目标：让资料篮真正能导入 Research，会话真正可管理，而不是只停留在单次流式问答。

范围：

- 为 Research 增加会话列表、本地持久化、新建、重命名、删除
- 支持从资料篮导入到当前会话或新建会话
- 新增 `ImportToResearchDialog` 与 `CitationCard`
- 强化右侧引用区，展示来源、重要性、备注等信息
- 保留流式失败后的会话与已导入资料

说明：

- 当前 `researchStore` 只有单会话状态，不支持“已有 Research 列表”选择
- 因此“导入到当前 / 已有 / 新建 Research”不能在最初阶段完成，必须等这一阶段补齐 Research 会话模型后再实现

验收标准：

- 可从资料篮导入到当前会话
- 可新建会话并导入资料
- 会话刷新后不丢失
- Research 页面可同时展示主输出区、引用区、资料区

#### Phase 5：QA 条件开放阶段

目标：只在后端能力确认稳定时开放独立 QA 页面，否则保持为跳转式模板模式。

范围：

- 若后端新增独立 `QA` SSE 接口，则补 `qa.py`、QA prompt、`qaStore`、`QAView`
- 若后端暂不新增独立 `QA` 接口，则仅实现“问这个文档 / 问这个事项”跳转到 Research 模板模式

说明：

- `QA` 在首版中是条件开放项，而不是必做项
- 独立 QA 若要成立，需要新的后端 prompt 和 SSE 契约，不能简单假设只给 `ResearchEngine` 传一个 `mode=qa` 就足够

验收标准：

- 若开放独立 QA：支持流式问答、引用展示、加入资料篮
- 若不开放独立 QA：文档详情和事项详情中的“问这个对象”必须可跳转到 Research 并带入模板问题
- 不允许出现菜单已开放但后端能力未稳定的半成品入口

#### Phase 6：Release + 1 的 Topics 与 Analytics

目标：将非首版能力单独推进，不干扰首版上线节奏。

范围：

- 独立实现 `Topics` API、路由、页面
- 独立实现 `Analytics` API、路由、页面
- 支持主题时间线、无效引用、孤立文档、依据覆盖率、部门统计等增强功能

说明：

- `Topics` 与 `Analytics` 不纳入首版，不应混入当前主线计划
- 若后续实现，建议分别使用独立 router，而不是塞入现有 `/graph` 路由之下

验收标准：

- 不影响首版搜索、详情、图谱、事项、Research 五条主路径
- `Topics` 与 `Analytics` 的路由、接口、前端展示均独立可回滚

### 14.9 与原 8 阶段计划的映射关系

为避免沟通成本，可以保留原 8 阶段命名作为参考，但实际执行建议按以下关系合并与重排：

- 原 Phase 1、Phase 2、Phase 3、Phase 5，合并为新的 Phase 1
- 原 Phase 8 中与搜索、详情、图谱增强相关的部分，前移为新的 Phase 2
- 原 Phase 6 中的事项页部分，拆出作为新的 Phase 3
- 原 Phase 8 中的 Research 会话管理与引用面板增强，拆出作为新的 Phase 4
- 原 Phase 4 仅保留 QA 条件能力，改为新的 Phase 5
- 原 Phase 7 整体后移，改为新的 Phase 6（Release + 1）

### 14.10 推荐的实际开发顺序

建议实际派工顺序如下：

1. 先做资料篮、壳层、事项路由、基础组件，建立统一入口。
2. 再做搜索、详情、图谱的“加入资料篮”与治理增强，优先打通主路径。
3. 然后完成事项列表页与事项详情页，让 Matter 能力从接口变成页面。
4. 再增强 Research 工作台，让“导入 Research”真正形成闭环。
5. 最后根据后端稳定度决定是否开放独立 QA。
6. `Topics` 与 `Analytics` 进入下一轮版本，不与首版抢排期。

### 14.11 截至 2026-03-12 的实现状态

本节用于同步当前代码实际落地情况，避免本章前半部分的“目标任务表”与当前仓库状态混淆。

#### 14.11.1 已实现

| 范围 | 当前状态 |
|------|----------|
| Phase 1：基础壳层与资料篮底座 | 已完成。已落地资料篮类型、Matter/QA 类型、Matter/QA API 封装、`basketStore`、Header 资料篮入口、Sider 事项入口、`ResearchBasketDrawer`、`StatusTag`、`DocumentVersionDrawer`，并补齐 `/matters`、`/matters/:matterId`、`/qa` 路由。 |
| Phase 2：搜索/详情/图谱主路径增强 | 已完成。搜索页支持单条与批量加入 Research、快速预览、引用复制、关系跳转、版本抽屉；文档详情页已补齐概览、依据链、修订史、推荐与同主题卡片，并切入统一导入弹窗；图谱页已支持从节点打开文档和加入资料篮。 |
| Phase 3：事项页落地 | 已完成。`/matters` 和 `/matters/:matterId` 已可访问；`MatterCard` 已展示条件、材料、时限、办理部门、地域和依据文件；事项页已支持加入 Research、依据文件加入 Research、导出办理清单和跳转文档详情。 |
| Phase 4：Research 工作台增强 | 已完成首版范围。Research 已增强为会话工作台，支持本地持久化会话、新建、重命名、删除、资料篮导入、引用卡片展示、已导入资料管理。后端 `/research` 已支持 `seed_doc_ids`，导入资料会真实进入 Research 上下文构建。 |
| Phase 5：QA 条件开放 | 已完成。前端已落地独立 `QAView`、`qaStore`、QA 菜单入口与上下文导入；后端已落地 `/api/v1/qa`、QA prompt 与 `ResearchEngine` QA 模式，文档详情页和事项详情页已支持直接跳转独立 QA。 |

#### 14.11.2 未实现

| 范围 | 当前状态 | 说明 |
|------|----------|------|
| 图谱页统一导入弹窗接入 | 未实现 | 当前搜索页、文档详情页、事项详情页、QA 页已切到统一导入弹窗，图谱页仍保留旧的直接加入资料篮模式。 |
| 搜索高级过滤增强 | 未实现 | 文档设计里提到的 `knowledge_category`、`status`、`region`、`theme` 过滤项未前推实现，原因是当前后端搜索接口未稳定提供这些过滤能力。 |
| Topics | 未实现 | 没有 `/topics`、`/topics/:themeName` 路由，也没有对应前后端接口与页面。 |
| Analytics | 未实现 | 没有 `/analytics` 路由，也没有对应前后端接口与页面。 |

#### 14.11.3 明确延后到首版之后

以下能力仍按 Release + 1 管理，不进入当前首版交付边界：

- `Topics` 主题地图全量能力
- `Analytics` 治理分析全量能力
- 条款级展示、条款级锚点导航、Article 级前端入口

#### 14.11.4 当前首版边界判断

截至当前，首版主路径已经达到“可演示、可联调”的状态：

- 已可完成“搜索 → 详情 → 加入资料篮 → Research”主路径
- 已可完成“事项查询 → 事项详情 → 加入 Research / 问这个事项 → QA”主路径
- 已可完成“文档详情 → 问这篇文档 → QA → 导入 Research”主路径
- 已可完成“图谱 → 文档详情 / 加入资料篮”主路径

但以下验收项仍应明确视为待完成，而不是默认已关闭：

- 一轮成体系的主路径烟测记录
- 前后端联调记录沉淀
- `npm run type-check` 恢复为稳定可用状态

### 14.12 相关扩展规划

围绕 ES 混合检索、知识图谱、QA、Research 的高频应用场景扩展规划，另见：

- [es-graph-high-frequency-scenarios.md](prd/es-graph-high-frequency-scenarios.md)
- [research-deep-research-alignment.md](prd/research-deep-research-alignment.md)