docs: 重构真实题目下的需求与资料文档体系

docs/需求分析/2.scenarios模块需求分析.md

@@ -0,0 +1,277 @@
+# Scenarios 模块需求分析
+
+## 1. 模块定位
+
+`apps.scenarios` 模块在当前代码中承担“场景列表展示与配置读取”职责。在本题重构后，它不应继续被理解为“多类题型模板市场”，而应升级为：
+
+> 注册申报资料审核任务配置中心
+
+也就是说，系统仍然可以保留配置化入口，但配置的对象不再是“知识问答、工单助手、财务审核”等通用 Agent，而是围绕注册申报业务拆分的若干子任务或工作模式。
+
+## 2. 重构目标
+
+本模块需要完成以下目标：
+
+1. 把当前项目首页从“通用 Demo 场景列表”重构为“注册申报任务入口页”。
+2. 用配置化方式定义不同审核任务的目标、输入、输出和可调用能力。
+3. 支撑后续 Demo 演示时快速切换不同任务视角，而不是频繁改代码。
+4. 保持与 `agent_core` 的边界清晰，即场景模块只定义任务，不实现任务逻辑。
+
+## 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`
+   合规风险预警助手
+
+### 4.2 是否需要多个场景还是一个总场景
+
+建议首版保留“一个主场景 + 若干子任务配置”的思路：
+
+- 页面上可以展示多个任务入口。
+- 底层可共享同一个项目资料池和统一字段池。
+- Demo 演示时可以先点“完整性检查”，再点“一致性核查”，展示系统分工明确。
+
+## 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 完整性核查任务
+
+该任务侧重：
+
+- 读取法规模板
+- 比对当前资料是否齐套
+- 识别缺失文件、错放文件、待人工确认项
+
+配置上需要指定：
+
+- 对应法规规则版本
+- 缺失项风险等级策略
+- 默认输出清单字段
+
+### 7.3 字段抽取任务
+
+该任务侧重：
+
+- 从说明书、申请表、产品列表等材料提取产品名称、靶标、适用范围、规格、储存条件、性能信息等
+- 形成统一字段池
+
+配置上需要指定：
+
+- 目标字段 schema
+- 字段来源优先级
+- 是否允许 LLM 兜底抽取
+
+### 7.4 一致性核查任务
+
+该任务侧重：
+
+- 比对统一字段池中的冲突项
+- 输出冲突来源、冲突内容和处理建议
+
+配置上需要指定：
+
+- 必须完全一致的字段
+- 允许语义近似的字段
+- 风险分级规则
+
+### 7.5 风险预警任务
+
+该任务侧重：
+
+- 汇总前述各任务结果
+- 形成综合风险清单
+- 给出整改建议和优先级
+
+配置上需要指定：
+
+- 风险合并策略
+- 高中低风险判定口径
+- 责任归属字段
+
+## 8. 与原始材料对应的任务设计要点
+
+### 8.1 要能体现“资料结构化目录”的任务价值
+
+`CH1.2 监管信息目录.docx` 已经给出一个非常适合 Demo 的目录样例，场景模块应支持把“监管目录核对”配置成单独任务，而不是只能在自由聊天中触发。
+
+### 8.2 要能体现“跨文档冲突识别”的任务价值
+
+当前材料中的产品名称冲突非常典型，建议将“一致性核查”场景作为重点入口之一。
+
+### 8.3 要能体现“历史申报沟通说明”的任务价值
+
+`CH1.9` 所反映的历史受理、撤回、替换临床机构等内容，适合在风险预警任务中作为“历史事项复核”子项展示。
+
+## 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. 至少能清楚区分“目录汇总、完整性检查、字段抽取、一致性核查、风险预警”五类任务。
+
+## 12. 当前代码基线下的重构建议
+
+### 12.1 建议保留
+
+- 通过配置文件驱动场景展示的思路
+- 场景读取失败时对首页做容错提示的机制
+
+### 12.2 建议替换
+
+1. 将“适用题型”文案替换为“任务适用资料/适用阶段”。
+2. 将当前通用场景命名替换为注册审核任务命名。
+3. 增加任务前置条件和执行依赖展示。
+4. 增加“是否依赖字段池”“是否依赖法规模板”等配置位。
+
+## 13. 本模块在复试讲解中的价值
+
+如果场景模块重构到位，复试时可以很自然地说明：
+
+1. 为什么不是把所有能力塞进一个聊天机器人。
+2. 为什么用配置驱动的任务入口更适合监管审核场景。
+3. 如何在不推翻现有系统结构的情况下，快速从通用 Demo 切换到具体业务题。
+
+这会直接增强整套系统的“工程化思维”观感。