# 政务公文知识图谱本体 V1.5 增强 — 实施计划

## 1. 文档定位

本文档是在以下两份文档基础上的收敛版实施计划，用于指导“本期一次性做完”的剩余开发工作：

1. [government-document-graph-ontology-v1-prd.md](government-document-graph-ontology-v1-prd.md)
2. [政务公文知识图谱本体V1增强-实施计划.md](政务公文知识图谱本体V1增强-实施计划.md)

V1.5 的目标不是重新设计本体，而是在现有 V1 增强方案和已实现代码基础上，完成以下事情：

1. 补齐当前已纳入范围但尚未闭环的能力。
2. 修复查询、Planner、图谱浏览器中的正确性和权限边界问题。
3. 扩充本期允许纳入范围的核心层知识卡与 Planner 细分能力。
4. 补齐自动化测试、回归验证和验收文档。

V1.5 完成后，应达到“核心公文图 + 办公扩展层按场景启用 + 图谱浏览器知识卡 + Research 图谱证据”的稳定可交付状态。

---

## 2. 本期范围

### 2.1 本期必须完成

本期纳入以下 7 类工作：

1. 查询底座与权限正确性收尾。
2. Policy / Task / Project / Matter 知识卡前后端完整闭环。
3. System / DataResource / Budget / Indicator / Industry 五类核心层知识卡。
4. 上述五类核心层实体的 Planner 意图识别与证据收集。
5. GraphExplorer 图谱浏览器知识卡体验统一与 MatterCard 接入。
6. Phase 3 场景化抽取规则补强与验证。
7. 自动化测试、集成回归、验收文档与发布清单。

### 2.2 本期明确不做

以下事项不纳入 V1.5：

1. 更深层条款图能力。
2. 更完整的人事关系图。
3. 统一时间模型。
4. Person / Event / Mechanism / Standard / Infrastructure / Technology 的专用知识卡。
5. 上述 Phase 3 六类实体的 Planner detail intent。
6. 跨标签统一全文检索与复杂召回排序。
7. 卡片协议的统一抽象重构。

### 2.3 设计原则

V1.5 延续 V1 的核心原则，不改变以下基础设计：

1. 运行时支持集合、场景抽取集合、查询暴露集合三套口径继续保持一致。
2. `graph_schema.yaml` 仍是类型定义的唯一来源。
3. `active_phases` 仍保持 `phase_0 + phase_1`，`phase_3` 继续通过 `extraction_scenes.extra_phases` 按场景启用。
4. 业务主键继续使用 `entity_key` 语义，与 Neo4j `elementId` 语义严格区分。
5. 非 `name` 主键实体继续通过统一 key_property 解析链路接入查询与写图逻辑。

---

## 3. 完成标准

V1.5 交付完成，必须同时满足以下标准：

1. Policy、Task、Project、Matter、System、DataResource、Budget、Indicator、Industry 在 GraphExplorer 中可正确打开知识卡。
2. Research 模式可识别并处理 Policy、Task、Project、System、DataResource、Budget、Indicator、Industry 的详情类问题，并返回图谱证据。
3. Person 等非 `name` 主键实体在 related-docs 链路中不串数据。
4. 卡片查询与图谱查询不突破 ACL 和文档可见性边界。
5. `graph_schema.yaml`、GraphAdminService、前端 `graphLabels` 之间的 `zh_name` 和 `key_property` 链路稳定可用。
6. 实施计划中列出的主要验证项已转化为测试或验收记录。

---

## 4. 工作包与实施方案

V1.5 拆分为 7 个工作包，建议按顺序推进。

### 工作包 A：查询底座与权限正确性

#### 目标

修正当前查询服务的歧义处理、卡片 ACL 边界和主键解析一致性，作为后续卡片扩展和 Planner 扩展的底座。

#### 关键改造点

1. 重写 `resolve_entity_by_exact_name()` 的歧义处理策略。
2. 将卡片查询中的关联扩展查询统一纳入可见文档约束。
3. 保持 `get_docs_by_entity_key()` 对非 `name` 主键实体的精确定位能力，并补强回归逻辑。
4. 提供统一的 key_property 解析入口，避免查询层、写图层、API 层散落重复逻辑。

#### 涉及文件

1. `backend/app/core/graph_query_service.py`
2. `backend/app/core/graph_schema_loader.py`
3. `backend/app/api/v1/graph.py`

#### 详细任务

1. `resolve_entity_by_exact_name()` 从“命中第一条”改为“三态返回”：
   - 0 条命中：返回 `None`
   - 1 条命中：返回 `entity_key`
   - 多条命中：返回 `None`，并打歧义日志
2. 为卡片查询新增内部辅助约束方法，例如：
   - `visible_card_neighbor_exists_clause(...)`
   - `visible_doc_link_clause(...)`
3. Policy / Task / Project 现有卡片中的组织、项目、预算、指标、主题、文档等扩展查询，全部追加可见性约束。
4. 在 `GraphSchema` 中增加公共方法，例如：
   - `key_prop_for(label: str) -> str`
5. `backend/app/api/v1/graph.py` 中 related-docs 和卡片端点保持“非法 label 返回空结果 / 未命中返回 404 / 歧义返回空结果”的统一口径。

#### 完成判断

1. 同名实体不再静默命中错误结果。
2. 卡片展开结果不因二跳关系泄露不可见文档上的信息。
3. Person 及其他非 `name` 主键实体相关查询行为稳定。

---

### 工作包 B：扩充五类核心层知识卡

#### 目标

为已进入核心层 schema 且具备明确业务价值的五类实体增加专用知识卡：

1. System
2. DataResource
3. Budget
4. Indicator
5. Industry

#### 关键改造点

1. 后端增加五类卡片查询方法。
2. 后端增加五类卡片 API 端点和响应模型。
3. 前端增加五类卡片 API 封装、类型定义和组件。
4. GraphExplorer 将五类实体纳入卡片支持集合。

#### 涉及文件

1. `backend/app/core/graph_query_service.py`
2. `backend/app/api/v1/graph.py`
3. `frontend/src/api/graph.ts`
4. `frontend/src/views/GraphExplorer.vue`
5. `frontend/src/components/`

#### 详细任务

1. 在 `graph_query_service.py` 中新增：
   - `get_system_card(entity_key, acl_tokens=None)`
   - `get_data_resource_card(entity_key, acl_tokens=None)`
   - `get_budget_card(entity_key, acl_tokens=None)`
   - `get_indicator_card(entity_key, acl_tokens=None)`
   - `get_industry_card(entity_key, acl_tokens=None)`
2. 每个卡片查询都必须：
   - 动态解析该标签的 `key_property`
   - 保持显式标签约束
   - 追加文档可见性约束
3. 在 `backend/app/api/v1/graph.py` 中新增端点：
   - `/system/{entity_key}`
   - `/data-resource/{entity_key}`
   - `/budget/{entity_key}`
   - `/indicator/{entity_key}`
   - `/industry/{entity_key}`
4. 在 `frontend/src/api/graph.ts` 中新增对应 API 方法和 TypeScript 类型。
5. 在 `frontend/src/components/` 下新增：
   - `SystemCard.vue`
   - `DataResourceCard.vue`
   - `BudgetCard.vue`
   - `IndicatorCard.vue`
   - `IndustryCard.vue`
6. 在 `GraphExplorer.vue` 中将上述实体加入卡片类型集合，并支持“查看知识卡”。

#### 建议卡片字段

1. System：基础属性、运营单位、管理数据资源、采用技术、承载基础设施、相关文档证据（本期返回空列表）。
2. DataResource：基础属性、管理系统、符合标准（按 `Standard -[CONFORMED_BY]-> DataResource` 反向查询）、相关文档证据（本期返回空列表）。
3. Budget：基础属性、资助任务、资助项目、财政年度、相关文档证据。
4. Indicator：基础属性、评价任务、评价项目、目标值、单位、相关文档证据。
5. Industry：基础属性、支撑政策、所在地域、主管单位、相关文档证据。

#### 完成判断

1. 五类核心层实体都能在图谱浏览器中打开知识卡。
2. 卡片字段来自现有稳定关系，不新增临时关系模型。
3. 所有卡片 API 都以 `entity_key` 为唯一外部参数语义。

---

### 工作包 C：Planner 扩展到五类核心层实体

#### 目标

让 Research 模式能理解并处理以下问题：

1. 某系统是什么、管理哪些数据、用了什么技术
2. 某预算支持了哪些任务或项目
3. 某指标评价了哪些任务或项目
4. 某产业受哪些政策支撑、分布在哪些地域
5. 某数据资源由哪些系统管理、符合哪些标准

#### 关键改造点

1. 扩展 QueryIntent。
2. 扩展 `_infer_entity_label()` 的关键词规则。
3. 扩展 `plan()` 的 detail 分支。
4. 扩展 `collect_evidence()` 的卡片证据收集。
5. 新增 5 个模板到 `query_planning.py`。

#### 涉及文件

1. `backend/app/core/graph_query_planner.py`
2. `backend/app/prompts/query_planning.py`

#### 详细任务

1. 新增 QueryIntent：
   - `SYSTEM_DETAIL`
   - `DATA_RESOURCE_DETAIL`
   - `BUDGET_DETAIL`
   - `INDICATOR_DETAIL`
   - `INDUSTRY_DETAIL`
2. 在 `_infer_entity_label()` 中新增关键词优先级：
   - System：系统、平台、门户、应用、业务系统
   - DataResource：数据、数据集、数据库、资源目录、证照库
   - Budget：预算、经费、资金、专项资金、财政投入
   - Indicator：指标、考核、目标值、KPI、评价指标
   - Industry：产业、行业、产业链、产业集群
3. 在 `plan()` 中将标签解析结果映射到对应 detail intent。
4. 在 `collect_evidence()` 中统一走：
   - `resolve_entity_by_exact_name(...)`
   - `get_*_card(entity_key)`
   - 模板格式化
5. 模板字段与 card service 返回字段一一对应，避免模板空洞或字段名错位。

#### 完成判断

1. Research 模式可处理 8 类核心实体详情问题：
   - Policy、Task、Project、System、DataResource、Budget、Indicator、Industry
2. 歧义或未命中时稳定降级为空证据。
3. Planner 不额外引入错误标签判定。

---

### 工作包 D：GraphExplorer 图谱浏览器闭环

#### 目标

将知识卡入口、卡片弹层、MatterCard 接入、搜索结果点击与图节点点击统一到一套前端体验中。

#### 关键改造点

1. 接回 MatterCard。
2. 将卡片支持集合扩展到 9 类实体。
3. 统一节点选中与卡片打开逻辑。
4. 确保动态类型加载和 `keyProperties` 初始化顺序稳定。

#### 涉及文件

1. `frontend/src/views/GraphExplorer.vue`
2. `frontend/src/components/MatterCard.vue`
3. `frontend/src/utils/graphLabels.ts`
4. `frontend/src/api/graph.ts`

#### 详细任务

1. 在 `GraphExplorer.vue` 中将 `Matter` 加入卡片支持集合。
2. 新增 Matter 的卡片打开逻辑，沿用已有 Matter API。
3. 将卡片支持实体扩展为：
   - Policy
   - Task
   - Project
   - Matter
   - System
   - DataResource
   - Budget
   - Indicator
   - Industry
4. 统一 `hydrateSelectedNode()` 与 `openCardModal()` 的职责：
   - `hydrateSelectedNode()` 只负责选中和 related-docs
   - `openCardModal()` 负责按类型分派加载 card data
5. 所有点击路径都必须走统一函数：
   - 图上点击
   - 搜索结果点击
   - 展开邻居后点击
6. 保持 `typesReady` 与 `loadTypesFromApi()` 的顺序控制，避免因 key_property 未初始化导致相关查询退回旧路径。

#### 完成判断

1. Matter 在 GraphExplorer 中恢复知识卡能力。
2. 9 类卡片支持实体前端交互一致。
3. 首屏点击非 `name` 主键节点时不出现查询退化。

---

### 工作包 E：Phase 3 场景抽取补强与验证

#### 目标

在不改变“phase_3 按场景启用”策略的前提下，补强 Phase 3 场景化抽取的规则质量和日志可观察性。

#### 保持不变的约束

1. `active_phases` 仍不默认开启 `phase_3`。
2. `phase_3` 仍通过 `extraction_scenes.extra_phases` 按场景启用。
3. 不将 Person / Event 等扩展层实体改为所有文档默认抽取。

#### 关键改造点

1. 增强 Scene prompt 中的歧义规则和示例。
2. 增加 scene_type 相关日志和过滤统计。
3. 对所有 build_graph 调用链路做一次 scene_type 传参一致性检查。

#### 涉及文件

1. `backend/app/prompts/entity_extraction.py`
2. `backend/app/core/graph_builder.py`
3. `backend/app/core/ingest_pipeline.py`
4. `backend/app/tasks/graph_task.py`
5. `backend/scripts/bulk_build_graph.py`

#### 详细任务

1. 增强 `SCENE_ENHANCEMENT_RULES`，重点加强以下区分：
   - Person vs Organization / Position
   - Event vs Document
   - Mechanism vs Task / Standard
   - Infrastructure vs System
   - Technology vs 泛化技术表述
2. 在 `graph_builder.py` 中增加 scene 构建日志，至少包含：
   - `scene_type`
   - 场景有效类型集合
   - 原始实体数 / 归一化后实体数 / 被过滤实体数
3. 确认以下路径全部透传 `scene_type`：
   - ingest pipeline
   - Celery/后台 task
   - bulk build script
4. 回归验证：scene 为空时只使用默认 active 集合。

#### 完成判断

1. `leader_speech_*` 场景可稳定抽取 Person / Event。
2. `digital_gov_project` 场景可稳定抽取 Project / System / Technology / Budget / Infrastructure。
3. 普通公文不会因 scene 规则变多而大幅增加噪声抽取。

---

### 工作包 F：测试补齐

#### 目标

将 V1 增强实施计划中的主要验证项，转化为后端测试、前端测试和集成回归。

#### 后端测试

建议新增或扩充以下测试文件：

1. `backend/tests/test_graph_schema_unit.py`
   - `entity_types_for_scene()`
   - `all_entity_type_names_unfiltered()`
   - `all_entity_type_map_unfiltered()["Person"]["key_property"] == "person_id"`
2. `backend/tests/test_api_graph.py`
   - related-docs 的 `entity_key` 场景
   - Policy / Task / Project / System / DataResource / Budget / Indicator / Industry 卡片 API
   - 非法 label 行为
   - 歧义名称行为
3. `backend/tests/test_api_admin_graph.py`
   - 禁用类型定义级 CRUD 返回 400
   - 实体/关系 update 的只读字段约束
4. `backend/tests/test_api_ingest.py` 或相近文件
   - scene_type 驱动的图谱构建回归
5. 如有需要，补充 `graph_query_service` 单元测试，验证 ACL 一致性与 key_property 行为。

#### 前端测试

1. GraphExplorer 组件测试：
   - 动态类型加载后 `visibleTypes` 自动同步
   - `查看知识卡` 按钮显示条件
   - MatterCard 接入
   - 五类新增核心层卡片入口
2. TypeManageTab 组件测试：
   - 无 create / delete / rename 入口
   - 只保留展示元数据编辑
3. graphLabels 测试：
   - `zh_name` 优先级
   - `key_property` 注入
   - 新类型动态进入 `NODE_TYPE_LIST`

#### 集成回归

至少完成两条端到端回归：

1. 讲话稿场景：
   - 提取 Person / Event
   - 查询 related-docs
   - 打开图谱浏览器
2. 数字政府项目场景：
   - 提取 Project / System / Technology / Budget
   - 打开对应卡片
   - Planner 收集证据

#### 完成判断

1. 后端核心新增能力有测试覆盖。
2. 前端关键交互至少有组件级测试或明确手工脚本。
3. 典型业务文档场景完成端到端回归。

---

### 工作包 G：验收、文档与发布收尾

#### 目标

在代码完成后，形成可审计的验收输出和明确的发布清单。

#### 输出物

1. 新增一份 V1.5 验收文档，建议放在 `docs/`：
   - 完成范围
   - 非完成范围
   - 关键接口清单
   - 测试结果
   - 回归结果
   - 已知边界
2. 新增一份发布前检查清单，建议包括：
   - Neo4j 约束与全文索引状态
   - schema reload 结果
   - 前端类型元数据刷新情况
   - Planner 模板更新情况
   - 关键测试通过情况
3. 在相关文档中补一份已知边界说明：
   - `phase_3` 仍按场景启用
   - 本期只支持 9 类知识卡
   - 不包含更深层条款图、人事关系图、统一时间模型

#### 发布顺序建议

1. 先合并查询底座与权限修复。
2. 再合并卡片 service 与 API。
3. 再合并 Planner 扩展。
4. 再合并前端知识卡与 MatterCard 接入。
5. 最后补测试、验收文档和发布检查。

#### 完成判断

1. 所有本期功能点都有对应验收记录。
2. 产品、研发、测试对本期边界口径一致。
3. 发布清单可直接指导预发和生产上线。

---

## 5. 按开发任务拆分

建议将 V1.5 拆分为以下 10 个开发任务：

1. 查询歧义处理与 key_property 公共化。
2. 卡片 ACL 一致性改造。
3. System / DataResource 卡片后端与 API。
4. Budget / Indicator / Industry 卡片后端与 API。
5. 五类核心层 Planner 扩展。
6. 五类核心层前端卡片组件与 API 封装。
7. GraphExplorer 接回 MatterCard 并统一卡片入口。
8. Phase 3 场景抽取规则补强与日志增强。
9. 后端测试补齐。
10. 前端测试、验收文档与发布清单。

---

## 6. 推荐实施顺序与依赖

### 第一阶段：底座正确性

1. 任务 1：查询歧义处理与 key_property 公共化。
2. 任务 2：卡片 ACL 一致性改造。

说明：这两项是所有卡片和 Planner 的前置依赖，必须先做。

### 第二阶段：后端能力扩展

3. 任务 3：System / DataResource 卡片后端与 API。
4. 任务 4：Budget / Indicator / Industry 卡片后端与 API。
5. 任务 5：五类核心层 Planner 扩展。

说明：后端接口先稳定，再推进前端。

### 第三阶段：前端闭环

6. 任务 6：五类核心层前端卡片组件与 API 封装。
7. 任务 7：GraphExplorer 接回 MatterCard 并统一卡片入口。

### 第四阶段：质量与收尾

8. 任务 8：Phase 3 场景抽取规则补强与日志增强。
9. 任务 9：后端测试补齐。
10. 任务 10：前端测试、验收文档与发布清单。

---

## 7. 里程碑与验收口径

### M1：查询底座稳定

完成标志：

1. 重名实体不再静默命中错误结果。
2. Person 相关 related-docs 精确可用。
3. 卡片查询的 ACL 边界统一。

### M2：九类知识卡闭环

完成标志：

1. Policy、Task、Project、Matter、System、DataResource、Budget、Indicator、Industry 都能在 GraphExplorer 中打开知识卡。
2. Policy、Task、Project 可打开来源文件；Budget、Indicator、Industry 显示相关文档证据（允许为空）；System、DataResource 本期无文档关联。
3. 卡片支持节点的前端交互一致。

### M3：Research 图谱证据闭环

完成标志：

1. Planner 可处理 8 类核心实体详情问题：
   - Policy、Task、Project、System、DataResource、Budget、Indicator、Industry
2. 模糊命中、歧义命中、未命中行为稳定。

### M4：场景抽取与质量闭环

完成标志：

1. `leader_speech_*` 与 `digital_gov_project` 两类典型场景回归通过。
2. Phase 3 仍按场景启用，不污染默认抽取。
3. 测试与验收文档齐全。

---

## 8. 风险与应对

### 风险 1：卡片扩展导致 ACL 口径失控

应对：

1. 先完成工作包 A，再开发新增卡片。
2. 卡片 service 统一复用可见性辅助方法，不允许每个方法自写一套可见性逻辑。

### 风险 2：五类新卡片字段不稳定

应对：

1. 严格只用当前 schema 中已有关系构建卡片。
2. 不为卡片体验新增临时关系或字段。

### 风险 3：Planner 关键词误判过高

应对：

1. 采用保守关键词策略。
2. 歧义时统一降级为空证据，不强行返回错误卡片。

### 风险 4：Phase 3 prompt 增强导致默认场景噪声升高

应对：

1. 不改变 active_phases。
2. 所有规则补强只作用于 scene enhancement 路径。

---

## 9. 最终结论

V1.5 不是新的本体版本设计，而是一次针对 V1 增强方案的“收尾 + 扩容 + 交付化”实施。

本期完成后，系统将具备：

1. 更稳定的查询正确性与权限边界。
2. 覆盖 9 类实体的图谱知识卡能力。
3. 覆盖 8 类核心实体详情问题的 Research 图谱证据能力。
4. 更稳健的 Phase 3 场景化抽取与可观察性。
5. 可直接用于验收、回归和发布的测试与文档输出。

在不引入“更深层条款图、人事关系图、统一时间模型”这三项大范围扩张的前提下，V1.5 已足以作为本期一次性收尾版本。

---

## 10. Claude 可执行 Batch Plan

本节用于将 V1.5 方案拆成可顺序执行的 batch。每个 batch 都应满足以下原则：

1. 单个 batch 只解决一个紧密相关的问题簇。
2. 每个 batch 必须先完成代码实现，再完成最小必要测试。
3. 未通过测试或存在明显回归时，不进入下一个 batch。
4. 每个 batch 完成后都要输出变更摘要、测试结果和风险说明。

### Batch 0：基线检查与范围冻结

#### 目标

在正式改动前确认当前分支状态、已实现能力和未完成项，冻结 V1.5 范围，避免 Claude 在实现过程中继续扩 scope。

#### 输入上下文

1. `prd/government-document-graph-ontology-v1-prd.md`
2. `prd/政务公文知识图谱本体V1增强-实施计划.md`
3. `prd/政务公文知识图谱本体V1.5增强-实施计划.md`
4. 当前未提交代码改动

#### 执行动作

1. 检查 git diff，确认已实现内容与待做内容。
2. 明确本期不做项，不允许擅自引入：
   - 更深层条款图
   - 更完整人事关系图
   - 统一时间模型
   - Phase 3 六类专用知识卡
3. 输出一次“冻结范围说明”。

#### 主要交付物

1. 范围冻结说明
2. 当前能力快照

#### 完成定义

1. 后续 batch 都以本文件为准，不再扩 scope。

---

### Batch 1：查询歧义处理与 key_property 公共化

#### 目标

修正查询底座，确保后续卡片与 Planner 构建在正确的实体解析逻辑之上。

#### 改动范围

1. `backend/app/core/graph_query_service.py`
2. `backend/app/core/graph_schema_loader.py`
3. 如有必要，`backend/app/api/v1/graph.py`

#### 必做事项

1. 将 `resolve_entity_by_exact_name()` 改为三态行为：
   - 0 条命中返回 `None`
   - 1 条命中返回 `entity_key`
   - 多条命中返回 `None` 并记录歧义日志
2. 将 key_property 解析抽到 `GraphSchema.key_prop_for(label)` 或等价公共方法。
3. 将 `get_docs_by_entity_key()` 的 key_property 获取逻辑改为复用统一入口。
4. 对非法 label、空结果、歧义结果统一错误口径。

#### 测试要求

1. 新增或补充单测覆盖：
   - label 非法返回空
   - 精确解析未命中
   - 精确解析唯一命中
   - 精确解析歧义命中

#### 交付物

1. 查询歧义修复代码
2. 对应测试

#### 完成定义

1. 不再出现“同名实体静默命中第一条”的行为。

---

### Batch 2：现有卡片 ACL 一致性修复

#### 目标

修复现有 Policy / Task / Project 卡片的 ACL 和可见性边界问题。

#### 改动范围

1. `backend/app/core/graph_query_service.py`
2. 必要时 `backend/app/api/v1/graph.py`

#### 必做事项

1. 为卡片展开查询增加统一的“可见文档追溯”约束。
2. 现有 Policy / Task / Project 卡片中的所有扩展查询都必须复用该约束。
3. 确认 related docs、card docs、关联组织、任务、预算、项目、主题等不会越过 ACL。

#### 测试要求

1. 覆盖至少以下场景：
   - 入口节点可见，但部分关联信息仅存在于不可见文档
   - 卡片返回中不得出现该不可见信息

#### 交付物

1. ACL 修复代码
2. 权限边界测试

#### 完成定义

1. 现有三类卡片达到可上线的权限一致性。

---

### Batch 3：System / DataResource 卡片后端

#### 目标

先实现结构最清晰的两类卡片后端能力，为后续新增卡片建立模式。

#### 改动范围

1. `backend/app/core/graph_query_service.py`
2. `backend/app/api/v1/graph.py`

#### 必做事项

1. 新增 `get_system_card()`。
2. 新增 `get_data_resource_card()`。
3. 新增对应 API 响应模型和路由。
4. 全部使用动态 key_property + 显式标签约束 + ACL 约束。

#### 测试要求

1. 接口测试覆盖：
   - 命中
   - 未命中
   - 非法 label 不相关场景
   - 来源文件输出

#### 交付物

1. System / DataResource card service
2. API 路由与响应模型
3. 测试

#### 完成定义

1. 两类卡片接口可被前端直接消费。

---

### Batch 4：Budget / Indicator / Industry 卡片后端

#### 目标

完成剩余三类核心层卡片后端能力。

#### 改动范围

1. `backend/app/core/graph_query_service.py`
2. `backend/app/api/v1/graph.py`

#### 必做事项

1. 新增 `get_budget_card()`。
2. 新增 `get_indicator_card()`。
3. 新增 `get_industry_card()`。
4. 新增对应响应模型和路由。

#### 测试要求

1. 接口测试覆盖 3 类卡片的命中、未命中和来源文件输出。

#### 交付物

1. Budget / Indicator / Industry card service
2. API 路由与响应模型
3. 测试

#### 完成定义

1. 五类新增核心层卡片后端全部完备。

---

### Batch 5：五类核心层 Planner 扩展

#### 目标

让 Research 模式支持 System / DataResource / Budget / Indicator / Industry 的 detail 问题。

#### 改动范围

1. `backend/app/core/graph_query_planner.py`
2. `backend/app/prompts/query_planning.py`

#### 必做事项

1. 新增 5 个 QueryIntent。
2. 扩展 `_infer_entity_label()` 关键词规则。
3. 扩展 `plan()` detail 分支。
4. 扩展 `collect_evidence()` 的 5 个卡片证据收集分支。
5. 新增 5 个模板。

#### 测试要求

1. 至少覆盖：
   - 典型命中语句
   - 未命中语句
   - 歧义名称语句

#### 交付物

1. Planner 扩展代码
2. 模板
3. 测试

#### 完成定义

1. Research 模式支持 8 类核心实体 detail 证据收集。

---

### Batch 6：前端新增五类卡片组件与 API 封装

#### 目标

补齐前端对五类新增卡片的消费能力。

#### 改动范围

1. `frontend/src/api/graph.ts`
2. `frontend/src/components/`
3. 必要时 `frontend/src/types/graph.d.ts`

#### 必做事项

1. 新增 API 方法与类型：
   - system
   - data resource
   - budget
   - indicator
   - industry
2. 新增 5 个 Vue 卡片组件。
3. 卡片组件统一支持：
   - 打开来源文件
   - 空列表兜底
   - 基础属性区 + 分块列表区

#### 测试要求

1. 组件级测试至少覆盖渲染和空态。

#### 交付物

1. 五类卡片前端组件
2. API 封装
3. 组件测试

#### 完成定义

1. GraphExplorer 已具备接入这些组件的前端基础能力。

---

### Batch 7：GraphExplorer 接回 MatterCard 并统一卡片入口

#### 目标

完成图谱浏览器前端闭环，使 9 类卡片型节点的行为一致。

#### 改动范围

1. `frontend/src/views/GraphExplorer.vue`
2. `frontend/src/components/MatterCard.vue`
3. `frontend/src/utils/graphLabels.ts`

#### 必做事项

1. 将 `Matter` 纳入卡片支持集合。
2. 将新增五类核心实体也纳入卡片支持集合。
3. 统一 `openCardModal()` 的分派逻辑，避免模板层散落分支。
4. 保证：
   - 图上点击
   - 搜索结果点击
   - 展开后点击
   的选中行为一致。
5. 确认 `typesReady` 与 `loadTypesFromApi()` 时序稳定。

#### 测试要求

1. 组件测试覆盖：
   - 9 类卡片支持实体的按钮显示
   - MatterCard 打开
   - 首屏 typesReady 行为

#### 交付物

1. GraphExplorer 闭环改造
2. MatterCard 接入
3. 组件测试

#### 完成定义

1. 图谱浏览器层面完成 9 类知识卡闭环。

---

### Batch 8：Phase 3 场景规则补强与日志增强

#### 目标

补强 Phase 3 场景抽取质量，但不改变 `phase_3` 按场景启用的总体策略。

#### 改动范围

1. `backend/app/prompts/entity_extraction.py`
2. `backend/app/core/graph_builder.py`
3. `backend/app/core/ingest_pipeline.py`
4. `backend/app/tasks/graph_task.py`
5. `backend/scripts/bulk_build_graph.py`

#### 必做事项

1. 增强 `SCENE_ENHANCEMENT_RULES` 的歧义说明与示例。
2. 在 builder 增加 scene 统计日志。
3. 检查所有调用链路透传 `scene_type`。
4. 补充 scene 为空时的默认行为回归。

#### 测试要求

1. 覆盖至少两个场景：
   - `leader_speech_*`
   - `digital_gov_project`

#### 交付物

1. scene prompt 补强
2. 日志增强
3. 回归测试

#### 完成定义

1. Phase 3 场景规则“可观察、可回归、可解释”。

---

### Batch 9：后端测试补齐

#### 目标

将 V1.5 的后端验证项系统化落地。

#### 改动范围

1. `backend/tests/test_graph_schema_unit.py`
2. `backend/tests/test_api_graph.py`
3. `backend/tests/test_api_admin_graph.py`
4. `backend/tests/test_api_ingest.py`
5. 如有需要，新增 query service 单测文件

#### 必做事项

1. schema loader 测试
2. related-docs / card API 测试
3. admin graph 只读策略测试
4. scene ingest 回归测试
5. ACL 边界测试

#### 交付物

1. 完整后端测试集增量

#### 完成定义

1. 后端新增能力具备最低可维护测试覆盖。

---

### Batch 10：前端测试、验收文档与发布清单

#### 目标

完成本期最后的质量收尾和交付文档化。

#### 改动范围

1. 前端手工验收脚本与构建校验
2. `docs/` 下新增验收文档
3. `docs/` 下新增发布检查清单

#### 必做事项

1. 形成 GraphExplorer 与 graphLabels 的前端手工验收脚本，覆盖 9 类卡片入口、MatterCard 接入、typesReady 非 `name` 主键回归。
2. 形成一份 V1.5 验收文档。
3. 形成一份发布检查清单。
4. 以前端可执行构建校验作为交付检查，使用 `npx vite build`；不将当前不可稳定执行的 `vue-tsc --noEmit && vite build` 作为本期阻塞验收项。
5. 明确本期已知边界。

#### 交付物

1. 前端手工验收脚本与构建记录
2. 验收文档
3. 发布清单

#### 完成定义

1. V1.5 达到“可验收、可回归、可发布”状态。

---

## 11. Claude 执行约束

为保证 batch 执行质量，Claude 在每个 batch 中应遵循以下约束：

1. 不跨 batch 提前实现后续功能。
2. 每个 batch 完成后必须先跑与该 batch 直接相关的测试。
3. 如果某个 batch 发现设计冲突，应先回写问题说明，再决定是否继续下一个 batch。
4. 对涉及 ACL、key_property、scene_type 的改动，必须补最少一条测试。
5. 前端卡片组件应优先复用现有 UI 模式，不另起一套设计体系。

---

## 12. 推荐交付节奏

建议采用以下执行节奏：

1. 第 1 天：Batch 0 ~ Batch 2
2. 第 2 天：Batch 3 ~ Batch 5
3. 第 3 天：Batch 6 ~ Batch 8
4. 第 4 天：Batch 9 ~ Batch 10

如需压缩周期，可将以下 batch 并行：

1. Batch 3 与 Batch 4
2. Batch 6 与 Batch 8

但以下 batch 不建议并行：

1. Batch 1 与后续所有 batch
2. Batch 2 与任何新增卡片 batch
3. Batch 7 与前端测试 batch

原因：这些 batch 是后续实现的正确性前置条件。