# Scenarios 模块需求分析

## 1. 模块定位

`apps.scenarios` 模块在当前代码中承担“场景列表展示与配置读取”职责。在本题重构后，它不应继续被理解为“多类题型模板市场”，而应升级为：

> 注册申报资料审核任务配置中心

也就是说，系统仍然可以保留配置化入口，但配置的对象不再是“知识问答、工单助手、财务审核”等通用 Agent，而是围绕注册申报业务拆分的若干子任务或工作模式。

需要特别说明的是：最新版原型已经把顶层导航收敛为 `审核智能体 / 资料包 / 知识库 / 处理历史`，因此 `apps.scenarios` 不再承担“首页大卡片导航中心”的产品角色，而是退回为 Agent 工作台中的任务模板与流程节点配置中心。

## 2. 重构目标

本模块需要完成以下目标：

1. 把当前项目首页从“通用 Demo 场景列表”重构为“注册申报任务入口页”。
2. 用配置化方式定义不同审核任务的目标、输入、输出和可调用能力。
3. 支撑后续 Demo 演示时快速切换不同任务视角，而不是频繁改代码。
4. 保持与 `agent_core` 的边界清晰，即场景模块只定义任务，不实现任务逻辑。
5. 支撑 `审核智能体` 页面中的预设提问模板、流程节点和执行卡片实时更新。

结合新增公告材料，场景模块还应承担“法规流程类型选择器”的角色，避免把注册申报、变更备案、延续注册三类任务混成一个入口。

## 3. 为什么本题仍然需要场景模块

虽然本题更像一个垂直系统，但场景模块依然有价值，原因有三：

1. 题面本身包含多个不同子任务：目录汇总、完整性检查、信息提取、回填、一致性核查、风险预警。
2. 复试演示通常需要分步骤展示，若所有能力都硬塞在一个入口，会让页面和结果过于拥挤。
3. 后续需求方很可能会提出“只想先看资料齐套性”“只想看字段抽取”这类细分诉求，配置化任务入口比写死流程更灵活。

## 4. 建议的场景体系

### 4.1 不建议继续使用通用题型命名

现有 `knowledge_qa`、`ticket_assistant`、`risk_audit` 等命名与本题关联度太弱。首版建议替换为以下业务导向任务：

1. `registration_overview`
   注册资料总览助手

2. `registration_completeness_check`
   法规完整性核查助手

3. `registration_field_extraction`
   产品关键信息抽取与回填助手

4. `registration_consistency_review`
   跨文档一致性核查助手

5. `registration_risk_report`
   合规风险预警助手

首版仍建议以 `registration_*` 作为主任务族，但应在配置语义上预留后续扩展族，例如：

- `change_registration_*`
- `renewal_registration_*`

### 4.2 是否需要多个场景还是一个总场景

建议首版保留“一个主 Agent 会话 + 若干子任务配置”的思路：

- 顶层页面不再展示多个独立业务页面，而是在 `审核智能体` 中展示多个任务模板与节点入口。
- 底层可共享同一个项目资料池和统一字段池。
- Demo 演示时可以先触发“目录汇总”，再继续执行“完整性检查”“一致性核查”，展示 Agent 沿节点推进。

## 5. 场景配置应包含的内容

每个任务配置文件建议至少包含以下信息：

### 5.1 基础标识

- `id`
- `name`
- `description`
- `icon` 或展示标签
- `sort_order`

### 5.2 任务目标

- 当前任务处理什么问题
- 适用输入资料范围
- 输出结果形式

例如，完整性检查任务的目标可以表述为：

> 根据 NMPA 注册申报资料要求，对当前项目资料包进行章节点齐套性检查、缺失项识别和待补清单生成。

### 5.3 输入约束

- 是否依赖已上传文件
- 是否依赖已入库文本
- 是否需要指定资料章节点
- 是否允许只针对选中文档执行

### 5.4 规则和工具绑定

- 需要的规则集
- 允许调用的工具列表
- 是否启用 RAG
- 是否启用统一字段池

### 5.5 输出模板

- 结构化结果类型
- 页面展示字段
- 是否生成报告
- 是否触发审计日志

## 6. 页面层需求

### 6.1 `审核智能体` 页面需要表达的内容

`审核智能体` 页不应只展示“这是几个 YAML 场景”，而应展示当前系统已支持的注册审核任务。建议每个任务卡片至少包含：

- 任务名称
- 任务目标
- 典型输入
- 典型输出
- 依赖资料条件
- 当前是否可执行

### 6.2 可执行状态判断

场景模块应能给出任务是否可执行的判定。例如：

- 未上传任何资料：完整性检查可执行，但只会提示无资料。
- 已上传未入库：目录汇总可执行，RAG 相关任务应提示需先入库。
- 规则文件缺失：完整性检查场景显示不可执行或部分能力不可用。

这类状态说明非常适合复试演示，因为它体现了系统不是“死调用大模型”，而是有明确任务前置条件，并能驱动右侧任务卡片从“待执行”实时更新为“解析中”“已完成”“待复核”等状态。

## 7. 配置驱动的业务能力

### 7.1 目录汇总任务

该任务侧重：

- 扫描文件夹
- 统计文件数、页数、章节点
- 生成目录总览表

配置上需要指定：

- 可读取的资料范围
- 输出字段，如文件名、文件类型、所属章节、页数、状态

### 7.2 完整性核查任务

该任务侧重：

- 读取法规模板
- 比对当前资料是否齐套
- 识别缺失文件、错放文件、待人工确认项

结合公告附件包，该任务还应明确区分三层依据：

1. 注册申报资料要求及说明
2. 批准证明文件格式要求
3. 安全和性能基本原则清单

配置上需要指定：

- 对应法规规则版本
- 缺失项风险等级策略
- 默认输出清单字段

### 7.3 字段抽取任务

该任务侧重：

- 从说明书、申请表、产品列表等材料提取产品名称、靶标、适用范围、规格、储存条件、性能信息等
- 形成统一字段池
- 将产品名称、检测靶标、适用范围、储存条件、性能指标等核心信息自动填入注册申报表格或对照清单

配置上需要指定：

- 目标字段 schema
- 字段来源优先级
- 是否允许 LLM 兜底抽取
- 注册申报表格 / 对照清单的字段映射关系
- 是否生成 Word 输出和导出入口

### 7.4 一致性核查任务

该任务侧重：

- 比对统一字段池中的冲突项
- 输出冲突来源、冲突内容和处理建议

配置上需要指定：

- 必须完全一致的字段
- 默认按完全一致处理的字段
- 风险分级规则

### 7.5 风险预警任务

该任务侧重：

- 汇总前述各任务结果
- 形成综合风险清单
- 给出整改建议和优先级

配置上需要指定：

- 风险合并策略
- 高中低风险判定口径
- 责任归属字段
- 飞书通知目标字段

### 7.6 法规依据展示结果区

基于新增公告材料，建议在任务配置中增加法规依据展示能力，至少能让系统说明：

1. 当前任务对应的是哪类法规流程。
2. 使用了哪份资料要求说明。
3. 使用了哪份格式要求或批准证明文件模板。

但该能力不应再通过单独一级“法规依据页”承载，而应：

1. 作为知识库中的法规资料被维护。
2. 在对话结果中以 RAG 命中依据卡片返回。
3. 在任务节点详情或右侧能力卡中展示引用来源。

## 8. 与原始材料对应的任务设计要点

### 8.1 要能体现“资料结构化目录”的任务价值

`CH1.2 监管信息目录.docx` 已经给出一个非常适合 Demo 的目录样例，场景模块应支持把“监管目录核对”配置成单独任务，而不是只能在自由聊天中触发。

结合新增公告材料，这个任务还应能够说明当前目录核对所引用的是“资料要求说明”而不是任意自由目录。

### 8.2 要能体现“跨文档冲突识别”的任务价值

当前材料中的产品名称冲突非常典型，但结合最新确认，系统目标是通用试剂盒注册审核智能体，而不是只围绕某一个固定产品。因此，一致性核查任务应强调：

1. 先界定审核范围，再执行严格一致性检查。
2. 对同一审核范围内的字段按完全一致规则比对。
3. 对疑似混档资料单独输出风险提示。

### 8.3 要能体现“历史申报沟通说明”的任务价值

`CH1.9` 所反映的历史受理、撤回、替换临床机构等内容，适合在风险预警任务中作为“历史事项复核”子项展示。

### 8.4 要为飞书接入预留并实现任务入口语义

结合当前确认结果，场景模块建议为飞书访问统一维护任务标识和简短描述，便于后续：

1. 在飞书机器人中按任务 ID 触发。
2. 在飞书侧展示任务摘要和结果链接。
3. 将“通知责任人”与任务类型建立映射。
4. 支持群聊机器人中的任务选择与结果查看。

如果后续采用飞书开放平台的 Agent 接入路线，还应确保这些任务标识可以映射到飞书消息指令、评论触发或会话菜单项。

## 9. 场景模块与其他模块的边界

### 9.1 与 Chat 模块的边界

场景模块定义任务模板、节点配置和执行入口，Chat 模块负责用户进入任务后的具体交互与结果展示。

### 9.2 与 Documents 模块的边界

场景模块不负责解析文档，只负责声明“当前任务依赖哪些资料和结构化资产”。

### 9.3 与 Agent Core 的边界

场景模块定义任务目标、输出模板、可用工具和规则集；Agent Core 负责真正执行审核与抽取。

## 10. 建议的配置文件组织方式

建议将当前 `configs/` 目录从“题型模板”调整为“注册任务配置”，例如：

```text
configs/
  registration_overview.yaml
  registration_completeness_check.yaml
  registration_field_extraction.yaml
  registration_consistency_review.yaml
  registration_risk_report.yaml
```

如果后续希望再进一步清晰化，也可以拆分为：

```text
configs/registration/
  overview.yaml
  completeness.yaml
  extraction.yaml
  consistency.yaml
  risk_report.yaml
```

但首版不必为了目录优雅而过度重构。

## 11. 首版验收要求

本模块完成后，应达到以下效果：

1. 首页展示的任务名称、描述和本题业务强相关。
2. 每个任务的输入前提、输出类型和所依赖规则清晰可见。
3. 任务配置变更主要通过 YAML 完成，不需要频繁改 Python 代码。
4. 至少能清楚区分“目录汇总、完整性检查、字段抽取、一致性核查、风险预警”五类任务。
5. 字段抽取任务必须能表达“抽取核心信息并自动填入注册申报表格或对照清单”的输出目标。
6. 任务配置能够驱动会话中的节点式执行和右侧状态卡实时更新。

## 12. 当前代码基线下的重构建议

### 12.1 建议保留

- 通过配置文件驱动场景展示的思路
- 场景读取失败时对首页做容错提示的机制

### 12.2 建议替换

1. 将“适用题型”文案替换为“任务适用资料/适用阶段”。
2. 将当前通用场景命名替换为注册审核任务命名。
3. 增加任务前置条件和执行依赖展示。
4. 增加“是否依赖字段池”“是否依赖法规模板”等配置位。

## 13. 本模块在复试讲解中的价值

如果场景模块重构到位，复试时可以很自然地说明：

1. 为什么虽然以对话为核心，但仍然保留配置化任务模板和节点编排。
2. 为什么用配置驱动的任务入口更适合监管审核场景。
3. 如何在不推翻现有系统结构的情况下，快速从通用 Demo 切换到具体业务题。

这会直接增强整套系统的“工程化思维”观感。
