Bruce/DEMO-AGENT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: Bruce:11c20593d577c0da9470e47e2546b7ab0ec54874
Branches Tags
Bruce:master Bruce:V2 Bruce:dev
...
compare: Bruce:7836690303e2839ddf9d7ba23e88a80b92d1e475
Branches Tags
Bruce:master Bruce:V2 Bruce:dev

20 Commits
11c20593d5 ... 7836690303

Author SHA1 Message Date
bruce
7836690303 feat(原型设计): 关联资料包与对话记录 2026-06-03 23:48:53 +08:00
bruce
aa5d4d77f8 refactor(原型设计): 调整用户信息展示位置 2026-06-03 23:44:40 +08:00
bruce
12a92ad278 refactor(原型设计): 调整导航并合并法规依据入口 2026-06-03 23:43:16 +08:00
bruce
134e0fb5ff feat(原型设计): 精简导航并补充资料与法规页 2026-06-03 23:32:56 +08:00
bruce
f53d5a1902 refactor(原型设计): 简化顶部导航结构 2026-06-03 23:28:26 +08:00
bruce
c303a2fcc6 style(原型设计): 调整为蓝白助手工作台风格 2026-06-03 23:24:16 +08:00
bruce
e75f0a0356 refactor(原型设计): 重构为Agent对话优先原型 2026-06-03 23:15:24 +08:00
bruce
3da774e537 feat(原型设计): 新增知识库管理与流程状态卡片 2026-06-03 23:00:22 +08:00
bruce
54fc1baa4c feat(原型设计): 增强强Agent对话工作台原型 2026-06-03 22:31:23 +08:00
bruce
5a137b5b45 fix(原型设计): 修复演示站内容空白问题 2026-06-03 22:01:00 +08:00
bruce
08251ae5e6 docs(原型设计): 同步原型交付入口索引 2026-06-03 21:44:31 +08:00
bruce
cace6cb941 feat(原型设计): 新增注册审核演示站 HTML 原型 2026-06-03 21:41:27 +08:00
bruce
78b841131b docs(原型设计): 补充注册审核平台分页原型方案 2026-06-03 21:34:36 +08:00
bruce
7a60af0485 docs(详细设计): 新增飞书通知设计 2026-06-03 21:15:34 +08:00
bruce
cc200a32c4 docs(详细设计): 新增Word回填导出设计 2026-06-03 21:12:04 +08:00
bruce
2876a1b028 docs(详细设计): 新增风险预警设计 2026-06-03 21:08:15 +08:00
bruce
0e49eea683 docs(详细设计): 新增一致性核查设计 2026-06-03 21:04:54 +08:00
bruce
4208f29d77 docs(详细设计): 新增字段抽取与字段池设计 2026-06-03 21:00:28 +08:00
bruce
759939b446 docs(详细设计): 新增法规完整性检查设计 2026-06-03 20:55:38 +08:00
bruce
18428e75fd docs(详细设计): 新增资料包导入与目录汇总设计 2026-06-03 20:50:27 +08:00
72 changed files with 11543 additions and 341 deletions
Expand all files Collapse all files

11
README.md
View File

@@ -252,4 +252,15 @@ docker compose config
- [模块需求文档索引](docs/需求分析/2.模块需求索引.md)
- [智能体总体设计](docs/设计文档/1.智能体总体设计.md)
- [设计文档索引](docs/设计文档/0.设计文档索引.md)
- [注册审核平台整体原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.整体原型设计.md)
- [原型设计目录](F:\PyCharm\DEMO-AGENT\docs\原型设计)
- [单文件演示站 HTML](F:\PyCharm\DEMO-AGENT\docs\原型设计\registration-prototype-demo.html)
- [协作与编码约定](AGENTS.md)
## 原型设计交付
当前仓库已补充一套围绕注册申报审核主线的原型设计资产，供复试讲解、方案评审和后续页面实现直接参考：
- 原型文档采用“总览 + 分页细设计”方式组织，覆盖资料包导入、审核任务工作台、法规完整性检查、字段抽取与字段池、一致性核查、风险预警、Word 回填导出、飞书通知视图和知识库治理台。
- `docs/原型设计/registration-prototype-demo.html` 提供单文件可交互 mock 演示站，内含 8 个主页面视图和知识库 / 治理台 CRUD 抽屉。
- 该演示站仅使用 mock 数据，不依赖 Django 路由或真实 Agent Core 执行结果。

142
docs/原型设计/1.1.资料包导入页原型设计.md Normal file
View File

@@ -0,0 +1,142 @@
# 资料包导入页原型设计
## 1. 页面目标
把注册申报资料的导入、解包、扫描、目录汇总和章节点识别结果集中展示出来，让用户第一眼就明白本平台的输入对象是“资料包”，不是单篇文档。
## 2. 适用角色
- 注册资料专员
- 文档整理人员
- 演示讲解人
## 3. 页面布局分区
页面建议采用“三段式”：
1. 顶部导入条
2. 中部处理看板
3. 底部目录汇总区
建议分区：
- 顶部：批次信息、上传入口、导入方式切换
- 左侧：文件 / 压缩包导入队列
- 中部：处理流水线
- 右侧：异常与待复核箱
- 底部：目录树与目录汇总表
## 4. 核心卡片 / 表格 / 状态区
### 4.1 导入入口卡
展示：
- 批量文件上传
- 文件夹导入
- 压缩包导入
- 支持格式标签：`pdf / docx / doc / zip / rar / 7z`
### 4.2 处理流水线
按步骤展示：
1. 创建批次
2. 文件校验
3. 解包
4. 文件树扫描
5. 页数统计
6. 章节点识别
7. 目录汇总
每一步显示：
- 当前状态
- 处理数量
- 成功 / 失败数
### 4.3 异常箱
展示以下异常类型：
- 页数待复核
- 扩展名与 MIME 不一致
- 扫描件待 OCR
- 章节点识别失败
- 解包失败
### 4.4 目录汇总表
表格列建议：
- 原始相对路径
- 文件名
- 文件类型
- 页数
- 页数可信度
- 章节点
- 资料名称
- 处理状态
- 是否命中法规目录
## 5. 关键字段定义
页面主要消费 `registration_overview_report`。
关键字段：
- `batch_id`
- `file_count`
- `supported_file_count`
- `failed_file_count`
- `total_page_count`
- `page_count_status`
- `chapter_summary`
- `documents[]`
目录条目关键字段：
- `original_filename`
- `relative_path`
- `file_type`
- `chapter_code`
- `chapter_name`
- `page_count`
- `page_count_confidence`
- `processing_status`
- `needs_manual_review`
## 6. 关键交互
- 点击“上传压缩包”后，展示模拟导入进度。
- 点击目录树节点，可在右侧高亮对应文件。
- 点击异常项，可筛选下方表格。
- 点击单个文件行，可打开“文档详情抽屉”，展示页数统计方式和章节点识别结果。
- 点击“进入法规完整性检查”，跳转下一页。
## 7. 与上下游页面的数据关系
上游：无，属于演示主线起点。
下游：
- 法规完整性检查页直接消费目录汇总结果。
- 字段抽取页复用文档主数据、文本状态和章节点结果。
- 治理台中的 RAG 文档源管理可从该页二级入口进入。
## 8. 演示话术重点
- 强调本平台处理的是整套注册资料，不是单文档聊天。
- 强调压缩包、目录层级、页数和章节点是后续审核的事实基础。
- 强调异常箱的价值在于把“资料问题”前置，而不是等到审核后才发现。
## 9. 与知识库 / 治理台的关联入口
本页应提供以下治理入口：
- `查看 RAG 入库策略`
- `查看支持文件类型配置`
- `查看章节点识别规则`
- `重跑切片任务`
这些入口统一打开治理台抽屉，不在本页直接展开 CRUD。

120
docs/原型设计/1.2.审核任务工作台原型设计.md Normal file
View File

@@ -0,0 +1,120 @@
# 审核任务工作台原型设计
## 1. 页面目标
作为整套原型的首页，先把当前批次的审核进度、任务状态、关键风险和操作入口集中展示，让用户在 10 秒内理解平台价值和当前处理位置。
## 2. 适用角色
- 注册申报负责人
- 项目经理
- 复试演示讲解人
## 3. 页面布局分区
页面建议采用“总览头图 + 流程卡片 + 风险与待办双栏”。
分区如下：
- 顶部 Hero：批次、产品、流程、总体结论
- 中部七卡任务区
- 下方左侧：风险总览
- 下方右侧：待办动作与推荐下一步
## 4. 核心卡片 / 表格 / 状态区
### 4.1 批次总览 Hero
展示：
- 批次编号
- 产品名称
- 当前流程类型
- 当前审核阶段
- 最高风险等级
- 是否允许正式导出
### 4.2 七个流程任务卡片
固定七张卡片：
1. 资料包导入
2. 目录汇总
3. 法规完整性检查
4. 字段抽取
5. 一致性核查
6. 风险预警
7. Word 回填导出
每张卡片展示：
- 任务名称
- 当前状态
- 关键指标
- 最近执行时间
- 进入页面按钮
### 4.3 风险总览区
展示：
- 高 / 中 / 低风险数量
- 当前阻断原因
- 需要人工复核的字段数
### 4.4 待办动作区
展示：
- 缺失项补充建议
- 字段冲突待确认项
- 推荐下一步操作
## 5. 关键字段定义
建议聚合使用以下对象：
- `registration_overview_report`
- `registration_completeness_report`
- `registration_field_extraction_report`
- `registration_consistency_report`
- `registration_risk_report`
- `registration_word_export_report`
工作台摘要字段：
- `task_name`
- `task_status`
- `last_run_at`
- `summary_label`
- `summary_value`
- `entry_target`
## 6. 关键交互
- 点击任务卡片进入对应页面。
- 点击“查看总体风险”滚动到风险区。
- 点击“打开治理台”查看规则版本、字段 Schema、模板版本。
- 鼠标悬浮卡片显示“本任务输入来自哪里，输出流向哪里”。
## 7. 与上下游页面的数据关系
上游：汇总所有页面结果。
下游：为各页面提供统一入口，不产生独立业务结果。
## 8. 演示话术重点
- 先讲“流程闭环”，再讲某个点上的智能能力。
- 突出这不是自由问答，而是受控的任务执行工作台。
- 强调每个任务卡片都有状态、有输入输出、有结构化结果。
## 9. 与知识库 / 治理台的关联入口
工作台页右上角提供：
- `规则版本总览`
- `模板版本总览`
- `责任人映射总览`
适合作为讲解治理能力的总入口。

123
docs/原型设计/1.3.法规完整性检查页原型设计.md Normal file
View File

@@ -0,0 +1,123 @@
# 法规完整性检查页原型设计
## 1. 页面目标
对照 NMPA 法规要求，展示当前资料包的齐套性、错放情况、法规依据、风险等级和处理建议，让用户知道“缺了什么、为什么缺、依据是什么”。
## 2. 适用角色
- 注册申报负责人
- 法规专员
- 质控复核人员
## 3. 页面布局分区
推荐采用“三栏 + 底部证据表”布局：
- 左栏：法规目录树与章节范围
- 中栏：缺失项 / 错放项主列表
- 右栏：法规依据和风险摘要
- 底部：证据与建议表
## 4. 核心卡片 / 表格 / 状态区
### 4.1 法规目录树
展示：
- `CH1 ~ CH6`
- 已匹配数量
- 缺失数量
- 待复核数量
### 4.2 问题列表
分标签展示：
- 缺失项
- 错放项
- 疑似提供
- 待人工复核
每条记录展示：
- 章节
- 资料名称
- 当前状态
- 风险等级
- 命中文档或未命中说明
### 4.3 法规依据舱
展示：
- 规则包名称
- 规则版本
- 法规原文来源
- 证据片段
- 适用流程
### 4.4 处理建议表
列建议：
- 问题类型
- 问题说明
- 法规依据
- 风险等级
- 建议动作
- 责任角色
## 5. 关键字段定义
页面主要消费 `registration_completeness_report`。
关键字段：
- `required_item_count`
- `provided_item_count`
- `missing_item_count`
- `suspected_item_count`
- `misplaced_item_count`
- `manual_review_item_count`
- `highest_risk_level`
- `pass_status`
- `missing_items[]`
- `misplaced_items[]`
- `manual_review_items[]`
- `evidence_refs[]`
- `suggestions[]`
## 6. 关键交互
- 点击目录树章节，筛选中部问题列表。
- 点击缺失项，右侧法规依据自动切换。
- 点击“查看证据片段”，展开 RAG 命中内容。
- 点击“进入字段抽取”，继续主线。
## 7. 与上下游页面的数据关系
上游：消费 `registration_overview_report`。
下游：
- 风险预警页复用完整性结论。
- 飞书通知页可引用完整性问题摘要。
- 治理台中的法规规则包和 RAG 文档源由本页进入最自然。
## 8. 演示话术重点
- 强调完整性判断由结构化规则决定，不由大模型自由发挥。
- 强调 RAG 的职责是给证据，不是当裁判。
- 强调风险等级和责任角色已经提前结构化，便于协同。
## 9. 与知识库 / 治理台的关联入口
本页应提供：
- `查看规则包`
- `查看法规原文切片`
- `新增法规来源`
- `编辑章节要求`
所有操作进入治理台对应 CRUD 视图。

124
docs/原型设计/1.4.字段抽取与字段池页原型设计.md Normal file
View File

@@ -0,0 +1,124 @@
# 字段抽取与字段池页原型设计
## 1. 页面目标
展示从说明书、申请表、产品列表等资料中抽取出的结构化字段，并把来源、置信度、标准值、待复核状态和是否可回填统一展示出来。
## 2. 适用角色
- 注册资料专员
- 数据校对人员
- 模板回填使用人
## 3. 页面布局分区
建议采用“顶部摘要 + 中部字段池表格 + 右侧来源证据抽屉”。
分区如下：
- 顶部：字段抽取统计
- 中部：字段池主表
- 下方：待复核字段区
- 右侧：字段来源详情抽屉
## 4. 核心卡片 / 表格 / 状态区
### 4.1 抽取摘要卡
展示：
- 目标字段数量
- 已抽取数量
- 待复核字段数量
- 冲突候选数量
- 可回填字段数量
### 4.2 字段池主表
列建议：
- 字段编码
- 中文字段名
- 标准值
- 原文值
- 来源文档
- 来源位置
- 抽取方式
- 置信度
- 冲突状态
- 待复核状态
- 是否可回填
### 4.3 待复核区
重点突出：
- 低置信度字段
- 长文本归纳字段
- 来源不唯一字段
## 5. 关键字段定义
页面主要消费 `registration_field_extraction_report`。
关键字段：
- `target_field_count`
- `extracted_field_count`
- `manual_review_field_count`
- `conflict_candidate_count`
- `field_pool_status`
- `field_pool_items[]`
- `manual_review_fields[]`
- `evidence_refs[]`
字段池条目关键字段：
- `field_key`
- `field_label`
- `standard_value`
- `raw_value`
- `source_document_name`
- `source_location`
- `extract_method`
- `confidence`
- `conflict_status`
- `manual_review_required`
- `fillable`
## 6. 关键交互
- 支持按“全部 / 可回填 / 待复核 / 高置信度”切换。
- 点击字段行打开来源详情。
- 点击“查看原文片段”展开证据区。
- 点击“标记推荐值”模拟人工确认。
- 点击“进入一致性核查”继续主线。
## 7. 与上下游页面的数据关系
上游：
- 来自资料导入页的文档主数据
- 来自完整性检查页的前置校验状态
下游：
- 一致性核查页直接使用字段池
- Word 回填导出页使用可回填字段集
## 8. 演示话术重点
- 强调统一字段池是后续一致性核查和回填导出的中间事实层。
- 强调固定字段优先规则抽取，长文本才交给 LLM 辅助归纳。
- 强调每个字段都有来源，不是“模型猜你要什么”。
## 9. 与知识库 / 治理台的关联入口
本页应提供：
- `维护字段 Schema`
- `维护字段来源优先级`
- `查看字段映射规则`
- `重跑抽取策略`
这些入口接入治理台的字段 Schema 和模板映射 CRUD。

113
docs/原型设计/1.5.一致性核查页原型设计.md Normal file
View File

@@ -0,0 +1,113 @@
# 一致性核查页原型设计
## 1. 页面目标
基于统一字段池，对同一审核范围内不同文档的关键字段做完全一致比对，清楚展示冲突字段、来源对比和混档风险。
## 2. 适用角色
- 注册资料负责人
- 复核人员
- 项目经理
## 3. 页面布局分区
建议采用“范围确认条 + 冲突主表 + 对比视图 + 风险侧栏”。
分区如下：
- 顶部：审核范围确认条
- 中部：冲突字段表
- 下部：来源对比面板
- 右侧：混档风险与建议
## 4. 核心卡片 / 表格 / 状态区
### 4.1 范围确认条
展示：
- 当前批次
- 已纳入文档数量
- 排除法规资料说明
- 是否存在疑似跨产品文档
### 4.2 冲突字段主表
列建议：
- 字段名
- 比对结果
- 冲突值数量
- 来源文档数
- 最高风险等级
- 是否疑似混档
### 4.3 来源对比面板
按选中字段展示：
- 文档 A 值
- 文档 B 值
- 来源章节
- 来源页码
- 标准化结果
### 4.4 风险侧栏
展示：
- 冲突字段总数
- 混档告警数量
- 待复核字段数
- 建议处理动作
## 5. 关键字段定义
页面主要消费 `registration_consistency_report`。
关键字段：
- `checked_field_count`
- `consistent_field_count`
- `conflict_field_count`
- `manual_review_field_count`
- `mixed_package_warning_count`
- `highest_risk_level`
- `pass_status`
- `conflict_fields[]`
- `manual_review_fields[]`
- `mixed_package_warnings[]`
- `suggestions[]`
## 6. 关键交互
- 点击字段行，在下方切换来源对比视图。
- 点击“仅看冲突字段”过滤表格。
- 点击混档告警可跳到相关文档范围说明。
- 点击“进入风险预警页”继续主线。
## 7. 与上下游页面的数据关系
上游：消费字段池。
下游：
- 风险预警页复用冲突结论
- Word 回填导出页依据冲突状态做拦截
## 8. 演示话术重点
- 强调一致性核查不重新抽取字段，只对字段事实做比对。
- 强调系统默认严格一致规则，避免模糊通过。
- 强调混档风险是当前业务场景的关键价值点。
## 9. 与知识库 / 治理台的关联入口
本页应提供：
- `维护强一致字段规则`
- `查看审核范围配置`
- `查看混档识别规则`
这些入口进入治理台的规则包和字段规则维护视图。

110
docs/原型设计/1.6.风险预警页原型设计.md Normal file
View File

@@ -0,0 +1,110 @@
# 风险预警页原型设计
## 1. 页面目标
把完整性、字段抽取和一致性核查的结果统一归并成综合风险清单，给出总风险等级、是否通过、整改建议和责任角色。
## 2. 适用角色
- 注册申报负责人
- 项目经理
- 业务主管
## 3. 页面布局分区
建议采用“总风险头图 + 风险矩阵 + 整改建议 + 责任分发区”。
分区如下：
- 顶部：总风险等级与通过结论
- 左侧：风险分布矩阵
- 中部：风险清单
- 右侧：责任角色与建议动作
## 4. 核心卡片 / 表格 / 状态区
### 4.1 总风险头图
展示：
- 当前批次
- 最高风险等级
- 是否通过
- 高 / 中 / 低风险数量
- 待人工复核数量
### 4.2 风险清单表
列建议：
- 风险类型
- 风险等级
- 问题描述
- 来源报告
- 关联文档
- 整改建议
- 责任角色
### 4.3 责任分发区
展示：
- 注册资料负责人
- 注册申报负责人
- 临床注册负责人
并显示每个角色对应待处理风险数。
## 5. 关键字段定义
页面主要消费 `registration_risk_report`。
关键字段：
- `risk_item_count`
- `high_risk_count`
- `medium_risk_count`
- `low_risk_count`
- `manual_review_count`
- `highest_risk_level`
- `pass_status`
- `risk_items[]`
- `manual_review_items[]`
- `suggestions[]`
- `owner_notifications[]`
## 6. 关键交互
- 点击风险类型过滤清单。
- 点击责任角色查看该角色负责的风险。
- 点击“生成通知摘要”跳转飞书通知视图。
- 点击“查看导出影响”跳转 Word 回填导出页。
## 7. 与上下游页面的数据关系
上游：
- 完整性报告
- 字段抽取报告
- 一致性报告
下游：
- Word 回填导出页引用是否通过和阻断项
- 飞书通知视图引用责任人和风险摘要
## 8. 演示话术重点
- 强调整个系统不是只找问题，而是把问题归并成“可执行风险”。
- 强调是否通过和责任角色已经直接结构化，可以进入实际协同。
- 强调高风险会影响后续导出和通知动作。
## 9. 与知识库 / 治理台的关联入口
本页应提供：
- `维护风险规则`
- `维护责任角色映射`
- `查看准入判定规则`
这些入口进入治理台的风险规则和责任人映射 CRUD。

118
docs/原型设计/1.7.Word回填导出页原型设计.md Normal file
View File

@@ -0,0 +1,118 @@
# Word回填导出页原型设计
## 1. 页面目标
展示字段如何回填到注册申报表格或对照清单中，并说明哪些字段已回填、哪些字段被风险或冲突拦截、当前导出状态如何以及用户从哪里下载文件。
## 2. 适用角色
- 注册资料专员
- 表格整理人员
- 审核结果使用人
## 3. 页面布局分区
建议采用“模板与导出状态头部 + 回填字段表 + 拦截项区 + 下载区”。
分区如下：
- 顶部：模板选择与导出结论
- 中部：回填字段表
- 右侧：拦截项和版式校验
- 底部：导出记录与下载入口
## 4. 核心卡片 / 表格 / 状态区
### 4.1 导出头部
展示：
- 模板名称
- 模板版本
- 当前导出状态
- 是否允许正式版
- 是否允许草稿版
### 4.2 回填字段表
列建议：
- 占位符
- 字段名
- 字段值
- 来源
- 回填状态
- 是否必填
### 4.3 拦截项区
展示：
- 冲突字段拦截
- 高风险拦截
- 待复核字段拦截
- 缺失必填字段拦截
### 4.4 导出记录区
展示：
- 输出文件名
- 输出版本
- 导出时间
- 版式校验结果
- 下载入口
## 5. 关键字段定义
页面主要消费 `registration_word_export_report`。
关键字段：
- `template_id`
- `export_status`
- `fillable_field_count`
- `filled_field_count`
- `blocked_field_count`
- `manual_review_field_count`
- `layout_check_status`
- `filled_fields[]`
- `blocked_fields[]`
- `output_file`
## 6. 关键交互
- 点击模板下拉模拟切换模板。
- 点击“生成草稿”切换导出状态。
- 点击“尝试生成正式版”时展示阻断提示。
- 点击某个拦截项，可查看其来源风险。
- 点击下载按钮，展示 mock 下载反馈。
## 7. 与上下游页面的数据关系
上游：
- 字段池
- 一致性核查报告
- 风险预警报告
下游：
- 飞书通知页可引用“已生成草稿”或“正式导出被阻断”的状态
## 8. 演示话术重点
- 强调平台不仅能抽取字段，还能进入真正的交付动作。
- 强调高风险不会被忽略，系统会阻止直接生成正式报送文件。
- 强调模板、字段映射、拦截条件都可治理，不写死在 Prompt 里。
## 9. 与知识库 / 治理台的关联入口
本页应提供：
- `维护 Word 模板`
- `维护字段映射`
- `查看导出版式校验规则`
- `查看导出记录`
这些入口进入治理台的模板与映射 CRUD。

104
docs/原型设计/1.8.飞书通知视图原型设计.md Normal file
View File

@@ -0,0 +1,104 @@
# 飞书通知视图原型设计
## 1. 页面目标
把风险预警和导出状态转成一张可发送的飞书消息卡片，展示责任人 `@`、消息摘要、Web 详情链接和发送回执，形成工作台外部协同闭环。
## 2. 适用角色
- 注册申报负责人
- 协同群聊成员
- 演示讲解人
## 3. 页面布局分区
建议采用“双栏布局”：
- 左侧：飞书消息卡片预览
- 右侧：通知配置与发送回执
底部补一条 Web 详情页入口说明。
## 4. 核心卡片 / 表格 / 状态区
### 4.1 飞书消息卡片预览
展示：
- 批次编号
- 风险摘要
- 是否通过
- 责任人 `@`
- 关键风险条目
- Web 详情按钮
### 4.2 通知配置区
展示：
- 触发来源
- 飞书群聊 ID
- 消息类型
- 是否包含责任人通知
- 是否附带 Web 链接
### 4.3 发送回执区
展示：
- 发送状态
- 消息 ID
- 发送时间
- 失败原因
## 5. 关键字段定义
页面主要消费 `feishu_notification_report`。
关键字段：
- `send_status`
- `message_type`
- `mentioned_users[]`
- `web_detail_url`
- `receipt.message_id`
- `receipt.sent_at`
同时复用风险页中的：
- `highest_risk_level`
- `pass_status`
- `owner_notifications[]`
## 6. 关键交互
- 点击“切换卡片样式”模拟不同消息模板。
- 点击“发送通知”切换为已发送状态。
- 点击责任人标签，查看角色映射详情。
- 点击 Web 详情按钮，跳转到 mock 审计详情链接。
## 7. 与上下游页面的数据关系
上游：
- 风险预警页提供责任角色和风险摘要
- Word 回填导出页提供导出状态
下游：无，属于主线收尾页。
## 8. 演示话术重点
- 强调平台不止有 Web 界面，还有飞书协同入口。
- 强调系统可以把风险结果直接转换成责任人可执行的通知载荷。
- 强调通知里保留 Web 详情链接，便于追溯。
## 9. 与知识库 / 治理台的关联入口
本页应提供：
- `维护责任人映射`
- `维护飞书机器人配置`
- `维护消息模板`
- `查看发送日志`
这些入口进入治理台中的责任人映射和飞书通知配置 CRUD。

222
docs/原型设计/1.9.知识库与治理台原型设计.md Normal file
View File

@@ -0,0 +1,222 @@
# 知识库与治理台原型设计
## 1. 页面目标
作为整套原型的治理能力承载层，统一展示法规知识、RAG 证据、字段标准、模板映射、责任人和飞书配置如何被维护，并明确支持完整 CRUD。
本页在 HTML 中不独立占据主导航，而是以“治理台抽屉 / 配置弹窗 / 详情侧栏”的形式从各业务页面打开。
## 2. 适用角色
- 规则维护人员
- 平台管理员
- 注册资料平台主管
- 演示讲解人
## 3. 治理台布局分区
建议采用“左侧治理对象导航 + 中部列表 + 右侧详情 / 编辑抽屉”的结构。
左侧对象导航固定包含：
1. 法规规则包
2. RAG 文档源
3. RAG 切片
4. 字段 Schema
5. Word 模板与字段映射
6. 责任人映射
7. 飞书通知配置
## 4. 法规规则包 CRUD
### 4.1 列表字段
- 规则包名称
- 适用流程
- 版本号
- 启用状态
- 最近更新时间
- 维护人
### 4.2 必备操作
- 新增规则包
- 编辑规则包
- 复制新版本
- 启用 / 停用
- 删除未生效草稿
- 查看章节要求详情
### 4.3 原型交互要求
- 点击规则包行，右侧打开章节树与要求项详情。
- 点击“新增规则包”，打开表单弹窗。
## 5. RAG 文档源 CRUD
### 5.1 列表字段
- 文档名称
- 文档类型
- 来源类别
- 版本号
- 入库状态
- 切片数量
- 最近同步时间
### 5.2 必备操作
- 上传新文档源
- 替换版本
- 编辑元数据
- 停用文档源
- 删除失效文档源
- 重新入库
### 5.3 原型交互要求
- 支持按“法规 / 模板 / 业务资料”过滤。
- 点击文档源查看切片预览和召回配置。
## 6. RAG 切片 CRUD
### 6.1 列表字段
- 切片 ID
- 所属文档
- 章节
- 片段摘要
- 切片长度
- 召回状态
- 最近更新时间
### 6.2 必备操作
- 新增手工切片
- 编辑切片摘要
- 合并切片
- 拆分切片
- 删除切片
- 重建向量
- 调整召回阈值
### 6.3 原型交互要求
- 点击切片行，右侧展示原文预览和命中场景。
- 支持“查看证据命中历史”的详情抽屉。
## 7. 字段 Schema CRUD
### 7.1 列表字段
- 字段编码
- 中文名
- 字段类型
- 是否可回填
- 是否强一致
- 启用状态
- 版本号
### 7.2 必备操作
- 新增字段
- 编辑字段
- 启停字段
- 删除草稿字段
- 复制 schema 版本
### 7.3 原型交互要求
- 点击字段查看来源优先级和适用页面。
- 支持切换“回填字段 / 强一致字段 / 全部字段”。
## 8. Word 模板与字段映射 CRUD
### 8.1 列表字段
- 模板名称
- 输出类型
- 版本号
- 占位符数量
- 启用状态
- 最近更新时间
### 8.2 必备操作
- 上传模板
- 编辑模板元数据
- 编辑占位符映射
- 启用 / 停用版本
- 删除未发布版本
- 预览模板
### 8.3 原型交互要求
- 点击模板打开占位符和字段映射详情。
- 支持查看“阻断条件影响哪些占位符”。
## 9. 责任人映射 CRUD
### 9.1 列表字段
- 映射类型
- 章节 / 风险类型
- 责任角色
- 飞书用户 ID
- 启用状态
- 备注
### 9.2 必备操作
- 新增映射
- 编辑映射
- 启停映射
- 删除映射
- 批量导入映射
### 9.3 原型交互要求
- 点击某条映射可联动查看受影响风险项或飞书卡片预览。
## 10. 飞书通知配置 CRUD
### 10.1 列表字段
- 配置名称
- 群聊 / 机器人标识
- 消息模板
- Web 链接模板
- 启用状态
- 最近测试状态
### 10.2 必备操作
- 新增配置
- 编辑配置
- 切换消息模板
- 启用 / 停用
- 删除草稿配置
- 发送测试消息
### 10.3 原型交互要求
- 支持查看 interactive card 模板预览。
- 支持查看最近一次回执记录。
## 11. 与业务页面的入口关系
各主页面的治理入口分配如下：
- 资料包导入页：RAG 文档源、章节点规则
- 法规完整性检查页：法规规则包、RAG 切片
- 字段抽取页：字段 Schema、字段来源优先级
- 一致性核查页：强一致规则
- 风险预警页：风险规则、责任人映射
- Word 回填页：模板与字段映射
- 飞书通知视图：责任人映射、飞书通知配置
## 12. 演示话术重点
- 强调这套系统不是一次性写死，而是可以被维护和演进。
- 强调法规判断、RAG 证据、字段标准、模板映射和飞书配置都能被可视化治理。
- 强调 CRUD 的存在，说明平台具备从 Demo 走向实际业务平台的治理基础。

231
docs/原型设计/1.整体原型设计.md Normal file
View File

@@ -0,0 +1,231 @@
# 注册审核平台整体原型设计
## 1. 产品定位与演示目标
本轮原型面向：
```text
试剂盒临床注册文件准备与审核智能体平台
```
原型不强调“通用 Agent 工具箱”，而是围绕 NMPA 体外诊断试剂注册申报资料场景，展示一条可讲解、可追溯、可协同的审核闭环。
本轮演示目标：
1. 让评委在 1 分钟内理解平台解决什么问题。
2. 让业务人员看到资料包导入、法规核查、字段抽取、一致性核查、风险预警、Word 回填、飞书协同的完整链路。
3. 让技术评委看到系统具备规则优先、RAG 证据解释、结构化输出和治理后台能力。
4. 为后续 Django 页面重构或前端实现提供可直接照做的页面规格。
## 2. 演示总动线
推荐演示顺序：
1. 从“审核任务工作台”进入，先看 7 个流程任务卡片和当前批次状态。
2. 跳到“资料包导入页”，解释资料包、目录、页数和章节点识别。
3. 进入“法规完整性检查页”，展示缺失项、错放项和法规依据。
4. 进入“字段抽取与字段池页”，展示统一字段池、置信度和待复核字段。
5. 进入“一致性核查页”，展示字段冲突和混档风险。
6. 进入“风险预警页”，说明总风险等级、是否通过、整改建议和责任角色。
7. 进入“Word 回填导出页”，说明自动回填、导出拦截和下载入口。
8. 最后展示“飞书通知视图”，形成协同闭环。
知识库与治理台不作为独立主线页面插入，而是作为上述页面的配置入口、侧边抽屉或管理弹层出现，用来回答“规则从哪里来、谁来维护、如何增删改查”。
## 3. 统一视觉风格
### 3.1 视觉关键词
- 监管科技
- 专业可信
- 高信息密度
- 可解释工作台
- 演示友好
### 3.2 色彩建议
- 主背景：浅灰蓝与米白渐变，形成轻量但不空泛的工作台底色。
- 主强调色：深青蓝，用于导航、主按钮、激活态和重点数值。
- 风险色：铜橙、深红，用于缺失、冲突、高风险、阻断状态。
- 成功色：低饱和绿色，用于完成、可通过、已同步状态。
- 中性色：冷灰，用于说明文字、边框、标签和禁用态。
### 3.3 组件风格
- 使用“带状布局 + 信息舱 + 分析表格”的组合，不做普通后台卡片堆砌。
- 表格、目录树、证据侧栏、步骤时间线是核心表达方式。
- 高风险结论必须同时展示证据来源和责任角色，避免只有颜色没有解释。
## 4. 统一交互规范
### 4.1 全局导航
- 顶部固定展示：平台名称、当前批次、产品名称、流程类型、全局风险状态。
- 左侧流程导航固定展示 8 个主页面入口。
- 每个页面右上角保留“打开治理台”入口。
### 4.2 统一交互规则
- 所有结果页都支持“查看来源证据”。
- 所有关键对象都支持“打开详情抽屉”。
- 所有治理对象都遵循“列表 -> 详情 -> 新增 / 编辑 / 启停 / 删除”的统一 CRUD 结构。
- 风险阻断项必须在 Word 导出页和飞书通知视图里继续可见，保证前后呼应。
### 4.3 状态规范
统一状态口径：
- `待导入`
- `处理中`
- `已完成`
- `待复核`
- `已阻断`
- `已发送`
- `失败`
统一风险口径：
- `高`
- `中`
- `低`
- `待确认`
## 5. 统一 Mock 数据口径
本轮所有文档和 HTML 共用同一组演示数据，避免页面间口径冲突。
### 5.1 批次口径
- `batch_id`: `SUB-20260603-001`
- `workflow_type`: `registration`
- `product_name`: `新型冠状病毒 2019-nCoV 核酸检测试剂盒`
- `applicant_name`: `示例生物科技（上海）有限公司`
- `chapter_scope`: `CH1 ~ CH6`
### 5.2 主线风险口径
固定演示问题：
1. `CH1.11.4` 缺少一份必交声明类资料。
2. 一份沟通记录疑似错放到 `CH1.9` 目录。
3. 说明书与申请表中的产品名称存在文本不一致。
4. 储存条件字段存在待人工复核状态。
5. 风险等级为高，当前批次不允许正式导出，仅允许生成草稿。
6. 飞书通知需要 `@注册资料负责人` 和 `@注册申报负责人`。
### 5.3 共用对象定义
文档和 HTML 共用以下结构化对象名称：
- `registration_overview_report`
- `registration_completeness_report`
- `registration_field_extraction_report`
- `registration_consistency_report`
- `registration_risk_report`
- `registration_word_export_report`
- `feishu_notification_report`
治理台对象：
- `knowledge_rule_package`
- `rag_source_document`
- `rag_chunk_item`
- `field_schema_item`
- `template_mapping_item`
- `owner_mapping_item`
- `feishu_channel_config`
## 6. 页面跳转关系
主页面跳转关系如下：
```text
审核任务工作台
-> 资料包导入页
-> 法规完整性检查页
-> 字段抽取与字段池页
-> 一致性核查页
-> 风险预警页
-> Word 回填导出页
-> 飞书通知视图
```
跨页关系约束：
- 资料包导入页产出 `registration_overview_report`。
- 法规完整性检查页消费 `registration_overview_report`，产出 `registration_completeness_report`。
- 字段抽取与字段池页消费导入结果和完整性结果，产出 `registration_field_extraction_report`。
- 一致性核查页消费字段池，产出 `registration_consistency_report`。
- 风险预警页消费前三类报告，产出 `registration_risk_report`。
- Word 回填导出页消费字段池、一致性和风险报告，产出 `registration_word_export_report`。
- 飞书通知视图消费风险报告和导出报告，产出 `feishu_notification_report`。
## 7. HTML 演示站说明
### 7.1 交付方式
交付一个单文件 HTML：
`docs/原型设计/registration-prototype-demo.html`
该文件仅展示 mock 内容，不接真实 Django 路由，不调用真实接口。
### 7.2 HTML 结构要求
- 一个全局 App Shell
- 八个主页面 section
- 一个治理台抽屉层
- 一份统一 mock 数据对象
- 一组轻量 JavaScript 交互
### 7.3 必备交互
- 切换 8 个页面视图
- 展开 / 收起目录树
- 切换流程任务卡片选中态
- 打开治理台抽屉
- 切换治理对象 CRUD 子视图
- 模拟 Word 导出状态切换
- 模拟飞书消息卡片预览
## 8. 文档拆分说明
本轮分页文档如下：
1. [1.1.资料包导入页原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.1.资料包导入页原型设计.md)
2. [1.2.审核任务工作台原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.2.审核任务工作台原型设计.md)
3. [1.3.法规完整性检查页原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.3.法规完整性检查页原型设计.md)
4. [1.4.字段抽取与字段池页原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.4.字段抽取与字段池页原型设计.md)
5. [1.5.一致性核查页原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.5.一致性核查页原型设计.md)
6. [1.6.风险预警页原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.6.风险预警页原型设计.md)
7. [1.7.Word回填导出页原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.7.Word回填导出页原型设计.md)
8. [1.8.飞书通知视图原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.8.飞书通知视图原型设计.md)
9. [1.9.知识库与治理台原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.9.知识库与治理台原型设计.md)
## 9. 实现边界
本轮原型只解决：
1. 演示表达
2. 页面结构
3. 模块关系
4. 数据口径
5. 治理台 CRUD 展示
本轮原型不直接承诺：
1. 后端真实接口联调
2. Django 模板替换
3. 真实 RAG 召回
4. 真实 Word 文件生成
5. 真实飞书 OpenAPI 调用
## 10. 结论
这套原型的核心讲法应统一为：
```text
资料包治理 -> 法规完整性核查 -> 字段池沉淀 -> 一致性检查 -> 风险预警 -> Word 回填导出 -> 飞书协同闭环
```
治理台负责回答“规则和知识如何维护”，工作台负责回答“这一批资料现在审核到了哪里、为什么这样判断、下一步谁来处理”。

1803
docs/原型设计/registration-prototype-demo.html Normal file
View File

File diff suppressed because it is too large Load Diff

341
docs/设计文档/1.注册资料审核Agent设计思路.md
View File

@@ -1,341 +0,0 @@
# 注册资料审核 Agent 需求分析与设计思路
## 1. 题目理解
本题要求建设的不是普通文档问答机器人，而是面向 NMPA 体外诊断试剂注册申报资料的“资料准备与审核 Agent”。
系统需要围绕一个注册资料包完成以下闭环：
1. 接收并解析一批申报资料。
2. 自动汇总文件目录与页数。
3. 对照 NMPA 法规和本地公告附件包检查资料完整性。
4. 从产品资料中抽取核心字段。
5. 将抽取结果填入申报表格、对照清单或目标模板。
6. 检查文档结构、章节规范性和跨文档字段一致性。
7. 输出合规风险预警、责任人通知建议和整改动作。
因此，系统设计的重点应从“单文档对话”转向“资料包级审核编排”。
## 2. 输入资料口径
### 2.1 待审核资料
题目第一项要求“自动汇总文件夹文件目录与页数”，这意味着首版输入不应只支持单文件上传，还要覆盖资料包导入。
V1 建议支持以下导入方式：
1. 多文件批量上传。
2. 文件夹拖拽或前端批量选择文件。
3. 压缩包上传并自动解压。
压缩包格式覆盖：
1. `zip`
2. `rar`
3. `7z`
系统解包后应保留原始相对路径，用于还原资料目录、识别章节点和发现文件夹结构异常。压缩包内多层目录按原目录作为章节点识别依据。
`rar`、`7z` 解压必须采用纯 Python 实现，允许新增第三方 Python 依赖包，避免服务器部署时依赖系统级解压工具。
### 2.2 法规依据资料
法规核查不应只依赖在线网页或大模型记忆。当前本地材料中已经提供了主规则依据：
```text
docs/原始材料/关于公布体外诊断试剂注册申报资料要求和批准证明文件格式的公告/
```
该目录下资料应作为 V1 的主规则包，包括注册申报资料要求、格式要求、安全和性能基本原则清单、注册证格式、变更和延续注册资料要求等。
`docs/原始材料/附件 4 体外诊断试剂注册申报资料要求及说明.doc` 可作为同源补充材料。
外部网站 `cmde.org.cn` 和 `nmpa.gov.cn` 在 V1 中主要作为法规来源说明和后续在线更新依据，不作为演示时的唯一实时依赖。
## 3. 核心需求重整
### 3.1 自动汇总文件目录与页数
系统应扫描当前资料包中的所有文件，形成目录汇总表。
目录汇总表至少包含：
| 字段 | 说明 |
|---|---|
| 原始路径 | 解压或上传后的相对路径 |
| 文件名 | 原始文件名 |
| 文件类型 | PDF、DOCX、DOC、TXT、MD 等 |
| 页数 | 精确页数或待复核状态 |
| 章节点 | 如 CH1.2、CH1.4、CH1.11.5 |
| 资料名称 | 识别出的注册资料名称 |
| 处理状态 | 已解析、解析失败、待人工确认 |
| 是否命中法规目录 | 用于后续完整性核查 |
页数统计策略：
1. PDF 优先用 `pdfplumber` 或 `PyMuPDF` 精确统计。
2. DOCX 页数必须精确统计，不能以估算页数作为 V1 验收结果。
3. DOC 可通过兼容解析工具或转换后处理，无法精确统计时标记为待人工复核。
4. 扫描件或无法提取正文的文件标记为“需 OCR / 待人工复核”。
### 3.2 按 NMPA 法规要求核查完整性
完整性核查的规则来源应优先来自本地公告附件包。
V1 规则建议拆成三层：
1. 资料齐套性：是否具备注册申报资料要求中的必交文件。
2. 章节点结构：文件是否落在正确章节，目录与实际文件是否一致。
3. 格式模板：申请表、注册证、清单、声明类文件是否符合对应格式要求。
核查结果需要区分：
| 状态 | 说明 |
|---|---|
| 已提供 | 文件和章节点均匹配 |
| 缺失 | 必交资料未找到 |
| 疑似提供 | 文件名或内容疑似匹配，但命名/归类不规范 |
| 错放 | 文件存在但章节点或目录位置不合理 |
| 待复核 | 规则无法直接判定 |
自动通知责任人属于完整性核查后的动作。V1 责任人先通过后台或配置文件手动维护，并按资料章节配置。系统可先输出责任角色和通知载荷，例如“CH4 临床评价资料缺失 -> 临床注册负责人”，后续再接飞书机器人执行 `@` 通知。
### 3.3 产品关键信息抽取与回填
题目中明确要求抽取：
1. 产品名称
2. 检测靶标
3. 适用范围
4. 储存条件
5. 性能指标
结合样例材料，首版建议以 `docs/原始材料/目标产品说明书.docx` 作为核心抽取样本，同时从申请表、产品列表、声明类文件中抽取可比对字段。
抽取结果先进入“统一字段池”，再用于回填。
统一字段池字段建议：
| 字段 | 说明 |
|---|---|
| field_key | 标准字段编码 |
| field_label | 中文字段名 |
| value | 标准化字段值 |
| raw_value | 原文值 |
| source_document | 来源文件 |
| source_location | 来源章节、表格或页码 |
| confidence | 置信度 |
| conflict_status | 一致、冲突、待确认 |
| fillable | 是否可回填 |
回填目标已确认。V1 应按两步走：
1. 先输出结构化回填表，并自动填入注册申报表格或法规对照清单字段。
2. 基于 Word 模板库生成可导出的目标文件。
注册申报表格和对照清单都应在模板库中建立字段映射，而不是把回填逻辑写死在 Prompt 中。
### 3.4 文档结构、信息一致性与章节规范性核查
结构核查应覆盖两类对象：
1. 单文档内部章节是否完整。
2. 资料包整体章节点是否符合 NMPA 目录结构。
以说明书或性能研究资料为例，需要检查是否包含分析灵敏度、特异性、重复性等必检项目。
一致性核查应基于统一字段池执行。首版按当前项目口径采用严格一致规则，即同一审核范围内同一字段只要文本不一致，就标记为冲突或待人工复核。
强一致字段建议包括：
1. 产品名称
2. 规格型号 / 包装规格
3. 申请人名称
4. 检测靶标
5. 适用范围 / 预期用途
6. 储存条件
当前样例中存在“目标产品说明书”和第 1 章监管资料产品名称不一致的情况。系统不应在需求阶段强行解释为同一产品，而应设计为：
1. 用户先选择审核范围或项目批次。
2. 系统对选定范围内的文件做一致性核查。
3. 若发现跨产品资料混入，输出混档风险。
### 3.5 合规风险预警与处理建议
风险清单应把完整性、结构、字段一致性和抽取失败结果统一汇总。
风险项字段建议：
| 字段 | 说明 |
|---|---|
| risk_level | 高 / 中 / 低 |
| risk_type | 缺失、错放、冲突、格式不规范、混档、待复核 |
| related_document | 涉及文件 |
| requirement_source | 法规或规则来源 |
| description | 问题描述 |
| suggestion | 处理建议 |
| owner_role | 建议责任角色 |
| notification_message | 可发送给责任人的通知摘要 |
示例：
```text
文件 CH4 临床评价资料：未在当前资料包中识别到临床评估报告。建议补充临床评价资料，并由临床注册负责人复核。
```
```text
产品名称冲突：说明书中的产品名称与申请表中的产品名称不一致。建议先确认当前审核范围是否混入其他产品资料。
```
## 4. Agent 编排设计
### 4.1 总体链路
建议 Agent Core 采用固定编排链路：
```text
资料导入
-> 解压与文件扫描
-> 页数统计与目录汇总
-> 文本 / 表格 / 章节解析
-> 章节点归类
-> 法规规则匹配
-> 字段抽取与统一字段池
-> 一致性核查
-> 风险汇总
-> 申报表格 / 对照清单自动回填
-> Word 生成
-> 审计记录与责任人通知
```
### 4.2 规则优先，模型辅助
法规完整性、必交项、章节点和强一致字段不应交给大模型自由判断。
推荐分工：
| 能力 | 处理方式 |
|---|---|
| 文件扫描、解压、页数统计 | 工具 / 服务层 |
| 法规目录匹配 | 结构化规则 |
| 必交项缺失判断 | 结构化规则 |
| 固定字段抽取 | 正则、标题、表格规则 |
| 长文本字段归纳 | LLM 辅助 |
| 法规条款引用 | RAG 辅助 |
| 风险文案与建议 | 规则结论 + LLM 组织语言 |
### 4.3 RAG 的职责
RAG 不作为最终合规判断引擎，只负责：
1. 从法规原文中找证据。
2. 从业务资料中找来源片段。
3. 为审计记录保留可追溯依据。
4. 支持用户追问“为什么这么判”。
### 4.4 Tool Registry 建议工具
Agent Core 后续应注册以下工具：
1. `scan_submission_package`：扫描资料包并保留目录结构。
2. `extract_archive`：解压 zip、rar、7z，其中 rar、7z 必须使用纯 Python 依赖实现。
3. `count_document_pages`：统计页数，DOCX 必须精确统计。
4. `classify_chapter_node`：识别章节点和资料名称。
5. `check_nmpa_completeness`：按结构化规则检查齐套性。
6. `extract_product_fields`：抽取产品核心字段。
7. `compare_field_consistency`：执行字段一致性比对。
8. `check_document_structure`：检查章节和必检项目。
9. `build_risk_alerts`：汇总风险和处理建议。
10. `build_fill_outputs`：生成注册申报表格或对照清单回填结果。
11. `render_word_template`：按模板生成 Word 文件。
12. `build_owner_notification`：生成责任人通知载荷。
## 5. Django 模块落地思路
### 5.1 Documents
Documents 是资料治理中心，应从“单文件上传记录”升级为“资料包 + 文件记录 + 解析结果”。
需要新增或强化：
1. 资料包批次。
2. 压缩包解压记录。
3. 原始相对路径。
4. 页数和页数可信度。
5. 章节点识别状态。
6. 文本、表格和标题解析状态。
7. 业务资料与法规资料隔离。
### 5.2 Agent Core
Agent Core 是审核编排引擎，应沉淀：
1. 注册资料审核专用输出 schema。
2. NMPA 规则包加载器。
3. 统一字段池。
4. 风险映射规则。
5. RAG 证据检索。
6. Word 模板回填接口。
### 5.3 Chat
Chat 页面应升级为注册审核工作台。
建议保留自然语言输入，同时提供快捷任务按钮：
1. 汇总当前资料目录及页数。
2. 检查资料完整性。
3. 抽取产品核心信息。
4. 检查一致性。
5. 生成风险预警报告。
### 5.4 Audit
Audit 需要记录：
1. 审核范围。
2. 使用的规则版本。
3. 参与文件清单。
4. 工具调用结果。
5. 风险结论。
6. 回填输出文件。
7. 通知责任人结果。
## 6. V1 实现优先级
建议按以下顺序落地，保证演示先闭环：
1. 批量上传 / 压缩包解压 / 文件目录汇总。
2. PDF、DOCX 页数统计和解析状态展示，其中 DOCX 必须精确统计。
3. 基于公告附件包整理结构化必交项规则，第 2 至第 6 章先做规则级初步确认。
4. 完整性核查与缺失项风险输出。
5. 从目标产品说明书抽取产品名称、靶标、适用范围、储存条件、性能指标。
6. 对说明书、申请表、产品列表做字段一致性核查。
7. 输出综合风险报告和处理建议。
8. 注册申报表格 / 对照清单自动回填和 Word 模板导出。
9. 责任人通知载荷与飞书机器人演示。
## 7. 已确认约束与剩余待确认事项
以下约束已经确认，应作为后续实现依据：
1. DOCX 页数必须精确统计。
2. 压缩包内多层目录按原目录作为章节点依据。
3. `rar`、`7z` 解压必须纯 Python 实现，允许新增第三方依赖包。
4. 责任人先手动配置，按资料章节维护。
5. 第 2 至第 6 章不补充企业真实样本，先按公告附件包进行规则级初步确认。
剩余待确认事项：
1. 后续如业务方另行提供专用 Word 模板，需要确认模板版本、生效范围和字段映射审批机制。
## 8. 结论
本题最稳的设计表达是：
```text
资料包治理 + 本地法规规则包 + 统一字段池 + 规则优先的 Agent 编排 + RAG 证据解释 + 风险与回填输出
```
这样既能覆盖题面五个要求，也能解释为什么系统需要 Django、Documents、Agent Core、RAG、Tool Registry 和 Audit 这些边界。

600
docs/详细设计/1.资料包导入与目录汇总.md Normal file
View File

@@ -0,0 +1,600 @@
# 1. 资料包导入与目录汇总详细设计
## 1. 设计目标
本步骤是注册申报资料审核工作流的入口，目标是把用户上传的注册申报资料包转化为可供后续法规完整性核查、字段抽取、一致性检查和风险预警使用的结构化文档底座。
本步骤需要完成以下业务结果：
1. 支持单文件、多文件、文件夹和压缩包导入。
2. 支持 `zip`、`rar`、`7z` 压缩包解包，并保留压缩包内原始相对路径。
3. 为每个文件建立注册资料记录，包含文件名、类型、大小、原始路径、所属批次和处理状态。
4. 统计文件页数，`PDF` 和 `DOCX` 必须精确统计，`DOC` 无法精确统计时标记为待人工复核。
5. 初步识别章节点、资料名称、资料类别和目录类文档。
6. 生成资料目录汇总结果，供页面展示和 Agent Core 后续任务使用。
本步骤不负责最终法规完整性判定，不负责字段抽取，不负责 RAG 入库。但它需要产出足够稳定的文档主数据，作为后续所有审核任务的事实输入。
## 2. 所属模块与边界
### 2.1 Django Documents
`apps.documents` 负责接收上传请求、保存原始文件、创建资料包批次、维护文档记录和展示目录汇总。
本步骤中 Django 侧建议提供：
1. 上传页和资料包导入入口。
2. 资料包批次模型。
3. 文档主数据模型。
4. 文档处理状态字段。
5. 目录汇总服务。
6. 目录汇总页面。
### 2.2 Agent Core
`agent_core` 负责沉淀可复用的资料包处理 Skill 和 Tool Registry 注册项。
本步骤中 Agent Core 建议提供：
1. `资料包导入Skill`
2. `压缩包解包Skill`
3. `资料包扫描Skill`
4. `文档页数统计Skill`
5. `章节点识别Skill`
6. `目录汇总Skill`
这些 Skill 不直接依赖 Django View。Django View 只负责收集参数并调用服务层，服务层再调用 Agent Core 的 Skill 或 Tool。
### 2.3 Audit
`apps.audit` 在本步骤中只记录资料包导入过程，不做审核结论留痕。
建议记录：
1. 导入入口。
2. 导入文件数量。
3. 解包结果。
4. 页数统计结果。
5. 失败文件数量。
6. 待人工复核文件数量。
## 3. 输入输出
### 3.1 输入
用户可以通过以下方式导入资料：
1. 单文件上传。
2. 多文件批量上传。
3. 文件夹上传，前端传递每个文件的相对路径。
4. 压缩包上传，后端解压后还原相对路径。
支持文件类型：
1. `pdf`
2. `docx`
3. `doc`
4. `txt`
5. `md`
6. `zip`
7. `rar`
8. `7z`
### 3.2 输出
本步骤输出 `registration_overview_report` 的第一版结构，核心字段如下：
```json
{
"batch_id": "SUB-20260603-001",
"workflow_type": "registration",
"source_role": "submission",
"file_count": 8,
"supported_file_count": 7,
"failed_file_count": 1,
"total_page_count": 36,
"page_count_status": "partial_review_required",
"chapter_summary": [
{
"chapter_code": "CH1.2",
"chapter_name": "监管信息目录",
"file_count": 1,
"page_count": 3
}
],
"documents": [],
"warnings": []
}
```
每个 `documents` 元素至少包含：
```json
{
"document_id": 1001,
"original_filename": "CH1.4 申请表.docx",
"relative_path": "第1章 监管信息/CH1.4 申请表.docx",
"file_type": "docx",
"file_size": 1048576,
"chapter_code": "CH1.4",
"chapter_name": "申请表",
"document_role": "application_form",
"page_count": 5,
"page_count_method": "docx_exact",
"page_count_confidence": "exact",
"processing_status": "summarized",
"review_status": "normal",
"needs_manual_review": false
}
```
## 4. 主工作流
```text
用户选择导入资料
-> 创建资料包批次
-> 校验上传文件
-> 判断是否压缩包
-> 解包或登记原始文件
-> 扫描文件树
-> 过滤不支持文件
-> 创建文档主数据
-> 统计页数
-> 初步识别章节点
-> 识别目录类/声明类/沟通类文件
-> 汇总目录与页数
-> 写入导入审计
-> 返回目录汇总页面
```
## 5. 节点详细设计
### 5.1 节点一：创建资料包批次
业务功能：
1. 为一次导入创建独立批次。
2. 记录导入来源、导入人、任务类型和资料来源角色。
3. 建立隔离存储目录，避免不同项目或不同批次文件混在一起。
建议模型：
```python
class SubmissionBatch(models.Model):
batch_no = models.CharField(max_length=64, unique=True)
name = models.CharField(max_length=255)
workflow_type = models.CharField(max_length=32, default="registration")
source_role = models.CharField(max_length=32, default="submission")
import_status = models.CharField(max_length=32, default="created")
created_by = models.ForeignKey(User, null=True, on_delete=models.SET_NULL)
created_at = models.DateTimeField(auto_now_add=True)
```
使用技术：
1. Django ORM
2. Django Storage
3. `uuid` 或业务编号生成器
产生方法：
1. `create_submission_batch(params) -> SubmissionBatch`
2. `build_batch_storage_path(batch) -> Path`
对应 Skill：
1. `资料包导入Skill`
### 5.2 节点二：上传文件校验
业务功能：
1. 校验文件扩展名是否支持。
2. 校验文件大小是否超过配置限制。
3. 校验文件名是否包含危险路径。
4. 识别普通文件和压缩包。
使用技术：
1. Django uploaded file API
2. `pathlib.PurePath`
3. `python-magic` 或 `mimetypes`
校验规则：
1. 禁止绝对路径。
2. 禁止 `..` 路径穿越。
3. 禁止空文件。
4. 允许中文文件名。
5. 对扩展名和 MIME 不一致的文件标记为待复核。
产生方法：
1. `validate_uploaded_file(uploaded_file) -> FileValidationResult`
2. `detect_upload_kind(uploaded_file) -> Literal["document", "archive"]`
对应 Skill：
1. `资料包导入Skill`
### 5.3 节点三：压缩包解包
业务功能：
1. 支持 `zip`、`rar`、`7z`。
2. 解包到批次隔离目录。
3. 保留压缩包内多层相对路径。
4. 记录每个解包文件来自哪个压缩包。
5. 对空包、损坏包、加密包、嵌套异常给出业务状态。
使用技术：
1. `zipfile`
2. `rarfile` 或纯 Python rar 解析依赖
3. `py7zr`
4. `pathlib`
5. 文件路径安全检查函数
关键状态：
1. `extracted`
2. `empty_archive`
3. `encrypted_archive`
4. `unsupported_archive`
5. `extract_failed`
6. `path_rejected`
产生方法：
1. `extract_archive(archive_path, target_dir) -> ArchiveExtractionResult`
2. `safe_extract_member(member_name, target_dir) -> Path`
3. `normalize_relative_path(raw_path) -> str`
对应 Skill：
1. `压缩包解包Skill`
### 5.4 节点四：扫描文件树
业务功能：
1. 遍历本次批次目录。
2. 过滤临时文件、系统隐藏文件和不支持文件。
3. 生成待处理文件清单。
4. 保留相对于资料包根目录的路径。
使用技术：
1. `pathlib.Path.rglob`
2. 文件哈希 `hashlib.sha256`
3. 后缀白名单
过滤规则：
1. 跳过 `__MACOSX`。
2. 跳过 `.DS_Store`。
3. 跳过 Office 临时文件，如 `~$申请表.docx`。
4. 对 `.exe` 等不支持文件记录为 `unsupported`，不进入后续页数统计。
产生方法：
1. `scan_submission_package(root_dir) -> PackageScanResult`
2. `build_file_fingerprint(file_path) -> str`
3. `is_supported_document(file_path) -> bool`
对应 Skill：
1. `资料包扫描Skill`
### 5.5 节点五：创建文档主数据
业务功能：
1. 为每个文件创建文档记录。
2. 写入文件名、相对路径、文件类型、大小、哈希、来源压缩包。
3. 标记初始处理状态。
4. 区分业务申报资料和法规依据资料。
建议模型：
```python
class RegistrationDocument(models.Model):
batch = models.ForeignKey(SubmissionBatch, on_delete=models.CASCADE)
original_filename = models.CharField(max_length=255)
relative_path = models.CharField(max_length=1024)
file_type = models.CharField(max_length=32)
file_size = models.PositiveBigIntegerField(default=0)
file_hash = models.CharField(max_length=128, blank=True)
source_archive_name = models.CharField(max_length=255, blank=True)
source_role = models.CharField(max_length=32, default="submission")
workflow_type = models.CharField(max_length=32, default="registration")
processing_status = models.CharField(max_length=32, default="created")
```
使用技术：
1. Django ORM
2. 批量创建 `bulk_create`
3. 唯一性约束：`batch + relative_path`
产生方法：
1. `create_document_records(batch, scanned_files) -> list[RegistrationDocument]`
2. `mark_unsupported_file(batch, scanned_file, reason) -> RegistrationDocument`
对应 Skill：
1. `资料包导入Skill`
2. `资料包扫描Skill`
### 5.6 节点六：页数统计
业务功能：
1. 为每份文档统计页数。
2. 写入页数统计方法和可信度。
3. 对无法精确统计的文档标记待人工复核。
使用技术：
1. PDF：`pypdf` 或 `PyMuPDF`
2. DOCX：优先读取 Word 兼容统计结果，必要时通过 LibreOffice headless 转 PDF 后精确统计
3. DOC：尝试转换或解析，失败时标记 `manual_review_required`
4. TXT/MD：页数不作为强制指标，可按 `not_applicable` 或导出预览后统计
页数状态：
1. `exact`
2. `not_applicable`
3. `manual_review_required`
4. `failed`
产生方法：
1. `count_document_pages(document) -> PageCountResult`
2. `count_pdf_pages(path) -> PageCountResult`
3. `count_docx_pages(path) -> PageCountResult`
4. `count_doc_pages(path) -> PageCountResult`
对应 Skill：
1. `文档页数统计Skill`
### 5.7 节点七：章节点与资料名称识别
业务功能：
1. 从文件名、相对路径和标题文本中识别章节点。
2. 识别资料名称。
3. 标记目录类、声明类、申请表、产品列表、历史沟通说明等文档角色。
4. 对无法确认的文件标记待人工确认。
使用技术：
1. 正则表达式
2. 本地章节点规则 YAML
3. `python-docx` 抽取首页标题
4. 简单关键词规则
识别优先级：
1. 相对路径中的章名，如 `第1章 监管信息`
2. 文件名中的章节点编码，如 `CH1.4`
3. 文件名中的标准资料名称，如 `申请表`
4. 文档首页标题
5. 用户手动选择的章节点
产生方法：
1. `classify_chapter_node(document) -> ChapterClassificationResult`
2. `extract_chapter_code_from_path(relative_path) -> str | None`
3. `detect_document_role(filename, title_text) -> str`
对应 Skill：
1. `章节点识别Skill`
### 5.8 节点八：目录汇总生成
业务功能：
1. 汇总当前批次所有文档。
2. 计算文件数量、支持文件数量、失败数量、总页数。
3. 按章节点聚合文件和页数。
4. 输出待人工复核清单。
5. 生成页面展示和 Agent Core 输入使用的统一结构。
使用技术：
1. Django ORM 聚合查询
2. Python dataclass 或 Pydantic schema
3. JSONField 存储结构化结果
产生方法：
1. `build_directory_summary(batch_id) -> RegistrationOverviewReport`
2. `summarize_chapters(documents) -> list[ChapterSummary]`
3. `collect_import_warnings(documents) -> list[ImportWarning]`
对应 Skill：
1. `目录汇总Skill`
### 5.9 节点九：审计留痕
业务功能：
1. 记录资料包导入执行过程。
2. 记录失败文件和待人工复核文件。
3. 为后续完整性核查提供可追溯基础。
使用技术：
1. `apps.audit` 服务层
2. JSONField
3. 敏感信息脱敏函数
产生方法：
1. `record_import_audit(batch, overview_report) -> AuditLog`
2. `sanitize_import_context(context) -> dict`
对应 Skill：
1. 本步骤不单独产生 Audit Skill，由 Django 服务层调用 Audit 服务完成。
## 6. Skill 清单
本步骤产生以下 Skill 设计文档：
1. [资料包导入Skill](skill/资料包导入Skill.md)
2. [压缩包解包Skill](skill/压缩包解包Skill.md)
3. [资料包扫描Skill](skill/资料包扫描Skill.md)
4. [文档页数统计Skill](skill/文档页数统计Skill.md)
5. [章节点识别Skill](skill/章节点识别Skill.md)
6. [目录汇总Skill](skill/目录汇总Skill.md)
## 7. 数据状态设计
### 7.1 批次状态
| 状态 | 含义 |
|---|---|
| `created` | 已创建批次，尚未完成文件登记 |
| `importing` | 正在导入或解包 |
| `summarizing` | 正在统计页数和目录 |
| `completed` | 导入与目录汇总完成 |
| `partial_completed` | 部分文件失败或需复核 |
| `failed` | 整体导入失败 |
### 7.2 文档状态
| 状态 | 含义 |
|---|---|
| `created` | 已创建记录 |
| `unsupported` | 文件类型不支持 |
| `page_counted` | 已完成页数统计 |
| `classified` | 已完成章节点识别 |
| `summarized` | 已进入目录汇总 |
| `manual_review_required` | 需要人工复核 |
| `failed` | 处理失败 |
### 7.3 页数可信度
| 状态 | 含义 |
|---|---|
| `exact` | 精确页数 |
| `not_applicable` | 不适用 |
| `manual_review_required` | 无法精确统计，需人工复核 |
| `failed` | 统计失败 |
## 8. 异常处理
本步骤需要业务化处理以下异常：
1. 上传空文件：拒绝导入，提示文件为空。
2. 文件名路径穿越：拒绝该文件，记录安全拦截。
3. 压缩包损坏：批次标记为 `failed` 或 `partial_completed`。
4. 压缩包加密：标记为 `manual_review_required`。
5. 解包后无支持文件：批次标记为 `partial_completed`，页面提示未发现可处理资料。
6. DOC 页数无法精确统计：文档标记待人工复核，不阻断目录汇总。
7. DOCX 页数无法精确统计：文档标记失败或待复核，并在汇总结果中突出提示。
8. 文件内容与扩展名不一致：记录风险提示，仍可尝试解析。
9. 同名相对路径重复：保留第一份，后续文件加版本后缀或标记重复。
10. 混入不支持文件：记录为 `unsupported`，不进入页数统计。
## 9. 页面展示
资料包导入完成后，Documents 页面建议展示：
1. 批次名称和导入时间。
2. 导入文件总数。
3. 支持文件数量。
4. 页数合计。
5. 待人工复核数量。
6. 解包失败或不支持文件数量。
7. 按章节点聚合的目录表。
8. 文件明细表。
文件明细表字段：
1. 原始相对路径。
2. 文件名。
3. 文件类型。
4. 页数。
5. 页数可信度。
6. 章节点。
7. 资料名称。
8. 处理状态。
9. 是否需人工复核。
## 10. 与后续步骤的接口
后续法规完整性核查需要读取：
1. `batch_id`
2. `workflow_type`
3. `source_role`
4. `documents[].document_id`
5. `documents[].relative_path`
6. `documents[].chapter_code`
7. `documents[].document_role`
8. `documents[].page_count`
9. `documents[].processing_status`
10. `documents[].needs_manual_review`
后续 RAG 入库需要读取：
1. 文件路径。
2. 文件类型。
3. 章节点。
4. 资料名称。
5. 业务资料或法规资料角色。
6. 文档处理状态。
## 11. 测试设计
### 11.1 单元测试
1. 上传文件校验。
2. 路径安全校验。
3. 压缩包解包。
4. 文件扫描过滤。
5. 页数统计。
6. 章节点识别。
7. 目录汇总聚合。
### 11.2 服务层测试
1. 单文件导入生成文档记录。
2. 多文件导入生成同一批次。
3. 压缩包导入保留相对路径。
4. 解包失败时批次状态正确。
5. DOC 无法统计页数时标记待复核。
6. 目录汇总结果包含文件数量、页数、章节点和警告。
### 11.3 页面测试
1. 上传成功后跳转到目录汇总页。
2. 页面展示页数可信度。
3. 页面展示待人工复核提示。
4. 不支持文件有清晰提示。
## 12. V1 实现建议
V1 建议先完成以下最小闭环：
1. 支持单文件和多文件上传。
2. 支持 `zip` 解包，并预留 `rar`、`7z` 依赖接入点。
3. 支持 `PDF`、`DOCX` 页数统计。
4. `DOC` 文件先标记待人工复核。
5. 基于文件名和路径识别 `CH1.*` 章节点。
6. 生成目录汇总页面和结构化 `registration_overview_report`。
在 V1 后续增强中补齐：
1. `rar`、`7z` 纯 Python 解包。
2. DOC 转换后精确统计。
3. 目录类文档内容解析。
4. 文件夹上传前端体验。
5. 后台人工修正章节点和资料名称。

610
docs/详细设计/2.法规完整性检查.md Normal file
View File

@@ -0,0 +1,610 @@
# 2. 法规完整性检查详细设计
## 1. 设计目标
本步骤承接“资料包导入与目录汇总”的输出，目标是对照 NMPA 体外诊断试剂注册申报资料要求，检查当前资料包是否齐套、章节点是否匹配、资料是否错放、是否存在需要人工复核的完整性问题。
本步骤需要完成以下业务结果：
1. 识别当前审核任务适用的法规流程，V1 默认使用 `registration` 注册申报流程。
2. 装载本地法规规则包，默认以公告附件包为主规则来源。
3. 将资料包目录结果与法规目录模板进行匹配。
4. 区分已提供、缺失、疑似提供、错放、待人工复核等状态。
5. 对缺失、错放和不确定项生成完整性风险等级和处理建议。
6. 通过 RAG 检索法规原文证据，但不把 RAG 命中结果作为最终裁判。
7. 输出结构化 `registration_completeness_report`，供 Chat 页面、Audit 和后续风险预警使用。
本步骤不负责产品字段抽取，不负责跨文档字段一致性检查，不负责最终综合风险报告。它只产出法规完整性维度的结论和证据。
## 2. 所属模块与边界
### 2.1 Scenarios
`apps.scenarios` 负责定义“法规完整性核查”任务入口。
建议配置项：
1. `scenario_id`: `registration_completeness_check`
2. `workflow_type`: `registration`
3. `required_input`: `registration_overview_report`
4. `rule_package`: `nmpa_ivd_registration_v1`
5. `enable_rag_evidence`: `true`
6. `output_schema`: `registration_completeness_report`
### 2.2 Documents
`apps.documents` 提供第一步生成的文档主数据和目录汇总结果。
本步骤读取：
1. 批次信息。
2. 文件相对路径。
3. 文件名。
4. 文件类型。
5. 页数。
6. 章节点。
7. 文档角色。
8. 处理状态。
9. 待人工复核标记。
### 2.3 Agent Core
`agent_core` 是本步骤的执行主体，负责编排规则包加载、流程识别、规则匹配、完整性判定、法规证据检索和报告生成。
本步骤建议产生以下中文 Skill：
1. `法规完整性检查Skill`
2. `法规规则包加载Skill`
3. `法规流程识别Skill`
4. `资料要求匹配Skill`
5. `缺失错放判定Skill`
6. `法规证据检索Skill`
7. `完整性报告生成Skill`
### 2.4 RAG
RAG 只负责证据定位和解释引用。
RAG 可以回答：
1. 当前缺失项对应公告附件中的哪段要求。
2. 当前章节点属于哪类资料要求。
3. 当前格式要求来源于哪份附件。
RAG 不负责决定：
1. 某资料是否必交。
2. 当前资料是否合规。
3. 缺失项是否高风险。
这些结论必须来自结构化规则。
### 2.5 Audit
`apps.audit` 记录本次完整性检查的输入、规则版本、匹配结果、缺失项、证据和错误。
审计中必须保留：
1. `batch_id`
2. `scenario_id`
3. `workflow_type`
4. `rule_package_id`
5. `rule_version`
6. `selected_document_ids`
7. `matched_items`
8. `missing_items`
9. `misplaced_items`
10. `manual_review_items`
11. `evidence_refs`
## 3. 输入输出
### 3.1 输入
```json
{
"batch_id": 1001,
"scenario_id": "registration_completeness_check",
"workflow_type": "registration",
"rule_package_id": "nmpa_ivd_registration_v1",
"chapter_scope": ["CH1"],
"selected_document_ids": [1, 2, 3],
"enable_rag_evidence": true
}
```
其中 `chapter_scope` 可为空。为空时默认检查当前批次已识别章节点及 V1 默认范围；演示首版建议优先检查 `CH1`，同时保留全六章规则结构。
### 3.2 输出
本步骤输出 `registration_completeness_report`：
```json
{
"report_type": "registration_completeness_report",
"batch_id": 1001,
"workflow_type": "registration",
"rule_package_id": "nmpa_ivd_registration_v1",
"rule_version": "2026-06-03",
"chapter_scope": ["CH1"],
"summary": {
"required_item_count": 8,
"provided_item_count": 6,
"missing_item_count": 1,
"suspected_item_count": 1,
"misplaced_item_count": 0,
"manual_review_item_count": 1,
"highest_risk_level": "high",
"pass_status": "failed"
},
"matched_items": [],
"missing_items": [],
"misplaced_items": [],
"manual_review_items": [],
"evidence_refs": [],
"suggestions": []
}
```
### 3.3 结果状态
| 状态 | 含义 |
|---|---|
| `provided` | 已提供，命中文档和章节点 |
| `missing` | 必交资料未找到 |
| `suspected` | 疑似提供，但命名、章节点或文档角色不确定 |
| `misplaced` | 文件存在，但章节点或路径位置不匹配 |
| `manual_review_required` | 规则无法直接判断，需人工复核 |
| `not_applicable` | 当前流程或适用条件下不要求 |
## 4. 主工作流
```text
用户发起法规完整性检查
-> 读取资料包目录汇总结果
-> 确认法规流程类型
-> 装载法规规则包
-> 展开章节和必交项规则
-> 将实际文档与规则项匹配
-> 判定已提供/缺失/疑似/错放/待复核
-> 映射风险等级与处理建议
-> 检索法规原文证据
-> 生成完整性检查报告
-> 写入审计留痕
-> 返回 Web/飞书可展示结果
```
## 5. 节点详细设计
### 5.1 节点一：读取目录汇总结果
业务功能：
1. 根据 `batch_id` 读取第一步产出的 `registration_overview_report`。
2. 校验资料包是否完成目录汇总。
3. 过滤当前检查范围内的文档。
4. 收集待人工复核文档，作为完整性检查的不确定性输入。
使用技术：
1. Django ORM
2. JSONField
3. Pydantic 或 dataclass schema 校验
产生方法：
1. `load_overview_report(batch_id) -> RegistrationOverviewReport`
2. `select_documents_for_completeness(report, chapter_scope, selected_document_ids) -> list[DocumentFact]`
3. `collect_document_uncertainties(documents) -> list[DocumentUncertainty]`
对应 Skill：
1. `法规完整性检查Skill`
### 5.2 节点二：法规流程识别
业务功能：
1. 确认当前任务属于注册申报、变更备案、变更注册还是延续注册。
2. V1 默认使用 `registration`。
3. 如果用户选择了不支持流程，返回业务化提示。
4. 防止把变更或延续规则误用于首次注册申报。
使用技术：
1. 场景配置 YAML
2. 批次字段 `workflow_type`
3. 规则包元数据
产生方法：
1. `resolve_workflow_type(batch, scenario_config, user_input) -> WorkflowTypeResult`
2. `validate_workflow_supported(workflow_type, rule_package) -> bool`
对应 Skill：
1. `法规流程识别Skill`
### 5.3 节点三：法规规则包加载
业务功能：
1. 加载本地结构化法规规则文件。
2. 校验规则版本、适用流程和章节结构。
3. 按“章 -> 条 -> 要求项 -> 模板字段”四级结构展开规则。
4. 区分资料要求层、结构目录层和格式模板层。
使用技术：
1. YAML 规则文件
2. Pydantic schema
3. Django cache 或内存缓存
4. 规则版本号
建议规则目录：
```text
configs/registration/rules/
nmpa_ivd_registration_v1.yaml
chapter_catalog.yaml
risk_mapping.yaml
```
规则项示例：
```yaml
rule_package_id: nmpa_ivd_registration_v1
workflow_type: registration
version: "2026-06-03"
chapters:
- chapter_code: CH1
chapter_name: 监管信息
requirements:
- requirement_id: CH1.4
requirement_name: 申请表
required: true
expected_document_roles:
- application_form
risk_level_if_missing: high
evidence_query: "体外诊断试剂 注册申报 申请表 监管信息"
```
产生方法：
1. `load_rule_package(rule_package_id) -> RulePackage`
2. `validate_rule_package(rule_package) -> RulePackageValidationResult`
3. `expand_requirement_items(rule_package, workflow_type, chapter_scope) -> list[RequirementItem]`
对应 Skill：
1. `法规规则包加载Skill`
### 5.4 节点四：资料要求匹配
业务功能：
1. 将当前资料包文档与法规要求项进行匹配。
2. 优先使用章节点编码匹配。
3. 其次使用文档角色匹配。
4. 再使用文件名和资料名称关键词匹配。
5. 保留匹配证据和匹配置信度。
匹配优先级：
1. `document.chapter_code == requirement.requirement_id`
2. `document.document_role in requirement.expected_document_roles`
3. 文件名命中规则关键词。
4. 相对路径命中章节名称。
5. 人工修正字段命中。
使用技术：
1. Python 规则匹配
2. 字符串标准化
3. 简单中文关键词匹配
4. 可选 rapidfuzz 模糊匹配，V1 谨慎使用
产生方法：
1. `match_documents_to_requirements(documents, requirements) -> RequirementMatchSet`
2. `match_by_chapter_code(document, requirement) -> MatchEvidence | None`
3. `match_by_document_role(document, requirement) -> MatchEvidence | None`
4. `match_by_keywords(document, requirement) -> MatchEvidence | None`
5. `calculate_match_confidence(evidences) -> str`
对应 Skill：
1. `资料要求匹配Skill`
### 5.5 节点五：缺失、错放与待复核判定
业务功能：
1. 对每个法规要求项生成完整性状态。
2. 判断必交项是否缺失。
3. 判断文件是否存在但错放章节。
4. 判断疑似提供但证据不足的情况。
5. 将第一步处理失败或页数待复核文件纳入不确定性。
判定规则：
| 条件 | 状态 |
|---|---|
| 必交项有高置信匹配文档 | `provided` |
| 必交项无任何匹配文档 | `missing` |
| 有低置信匹配文档 | `suspected` |
| 文档角色匹配但章节点不匹配 | `misplaced` |
| 文档本身待人工复核 | `manual_review_required` |
| 规则项不适用于当前流程 | `not_applicable` |
使用技术：
1. Python 规则引擎
2. 风险映射 YAML
3. dataclass/Pydantic 结果对象
产生方法：
1. `evaluate_requirement_status(requirement, matches, document_uncertainties) -> CompletenessItemResult`
2. `detect_missing_items(requirements, matches) -> list[MissingItem]`
3. `detect_misplaced_items(requirements, matches) -> list[MisplacedItem]`
4. `detect_manual_review_items(requirements, matches, uncertainties) -> list[ManualReviewItem]`
对应 Skill：
1. `缺失错放判定Skill`
### 5.6 节点六：完整性风险映射
业务功能：
1. 根据规则项定义映射风险等级。
2. 缺失高风险必交项时，本维度判定不通过。
3. 对待复核项不直接判失败，但标记结果可信度下降。
4. 生成基础处理建议。
风险等级：
1. `high`
2. `medium`
3. `low`
准入规则：
1. 任一高风险缺失项：`pass_status = failed`
2. 无高风险但存在中风险缺失项：`pass_status = review_required`
3. 只有低风险或待复核项：`pass_status = conditional_pass`
4. 无缺失、无错放、无待复核：`pass_status = passed`
使用技术：
1. 规则包内风险配置
2. 本地建议模板
3. Python 枚举
产生方法：
1. `map_completeness_risk(item_result, risk_rules) -> RiskMappingResult`
2. `calculate_pass_status(item_results) -> str`
3. `build_completeness_suggestion(item_result) -> str`
对应 Skill：
1. `缺失错放判定Skill`
### 5.7 节点七：法规证据检索
业务功能：
1. 针对缺失项、错放项和待复核项检索法规原文。
2. 返回法规来源文档、章节、片段和匹配查询。
3. 将证据附加到完整性结果和审计记录。
使用技术：
1. Chroma 或 fallback 检索
2. 本地法规原文切片
3. metadata 过滤
4. 关键词查询兜底
检索过滤条件：
1. `source_role = regulation`
2. `workflow_type = registration`
3. `rule_package_id = nmpa_ivd_registration_v1`
4. `chapter_code` 或 `requirement_id`
产生方法：
1. `retrieve_regulation_evidence(requirement_item, query_context) -> list[EvidenceRef]`
2. `build_evidence_query(requirement_item) -> str`
3. `filter_evidence_by_metadata(results, requirement_item) -> list[EvidenceRef]`
对应 Skill：
1. `法规证据检索Skill`
### 5.8 节点八：完整性报告生成
业务功能：
1. 汇总完整性检查结果。
2. 生成结构化报告。
3. 生成页面展示摘要。
4. 生成飞书摘要所需的短消息结构。
5. 写入审计记录。
使用技术：
1. Pydantic 或 dataclass schema
2. JSONField
3. Django template 或页面组件消费 JSON
4. Audit 服务层
产生方法：
1. `build_completeness_report(context, item_results, evidence_refs) -> RegistrationCompletenessReport`
2. `build_completeness_summary(item_results) -> CompletenessSummary`
3. `build_display_sections(report) -> list[DisplaySection]`
4. `record_completeness_audit(report, execution_context) -> AuditLog`
对应 Skill：
1. `完整性报告生成Skill`
## 6. Skill 清单
本步骤产生以下 Skill 设计文档：
1. [法规完整性检查Skill](skill/法规完整性检查Skill.md)
2. [法规规则包加载Skill](skill/法规规则包加载Skill.md)
3. [法规流程识别Skill](skill/法规流程识别Skill.md)
4. [资料要求匹配Skill](skill/资料要求匹配Skill.md)
5. [缺失错放判定Skill](skill/缺失错放判定Skill.md)
6. [法规证据检索Skill](skill/法规证据检索Skill.md)
7. [完整性报告生成Skill](skill/完整性报告生成Skill.md)
## 7. 规则数据设计
### 7.1 规则包元数据
| 字段 | 说明 |
|---|---|
| `rule_package_id` | 规则包标识 |
| `version` | 规则版本 |
| `workflow_type` | 适用流程 |
| `source_documents` | 法规来源文档 |
| `effective_scope` | 适用范围 |
| `chapter_count` | 章节数量 |
### 7.2 要求项字段
| 字段 | 说明 |
|---|---|
| `requirement_id` | 要求项编码，如 `CH1.4` |
| `chapter_code` | 章编码，如 `CH1` |
| `requirement_name` | 要求项名称 |
| `required` | 是否必交 |
| `condition` | 适用条件 |
| `expected_document_roles` | 期望文档角色 |
| `keywords` | 匹配关键词 |
| `risk_level_if_missing` | 缺失风险等级 |
| `evidence_query` | 法规证据检索查询 |
| `template_field_refs` | 后续模板字段映射 |
### 7.3 匹配结果字段
| 字段 | 说明 |
|---|---|
| `requirement_id` | 要求项编码 |
| `status` | 完整性状态 |
| `matched_document_ids` | 命中文档 ID |
| `match_confidence` | 匹配置信度 |
| `match_evidence` | 匹配证据 |
| `risk_level` | 风险等级 |
| `suggestion` | 处理建议 |
| `evidence_refs` | 法规证据引用 |
## 8. 页面展示
Chat/工作台页面建议展示：
1. 当前规则包名称和版本。
2. 当前检查流程类型。
3. 当前检查章节点范围。
4. 总体结论。
5. 缺失项数量。
6. 错放项数量。
7. 待人工复核数量。
8. 高风险缺失项。
9. 完整性检查明细表。
10. 法规证据引用。
11. 审计入口。
明细表字段：
1. 章节点。
2. 法规要求项。
3. 当前状态。
4. 命中文档。
5. 风险等级。
6. 处理建议。
7. 法规依据。
## 9. 异常处理
1. 未找到批次：返回“当前资料包不存在或已删除”。
2. 目录汇总未完成：提示先完成资料包导入与目录汇总。
3. 规则包不存在：任务不可执行，记录失败审计。
4. 规则包版本不支持当前流程：提示流程配置错误。
5. 文档章节点大量缺失：可执行，但报告标记低可信。
6. RAG 检索失败：不阻断规则判断，报告中标记证据检索不可用。
7. 所选文档为空：返回空范围检查结果，并提示用户选择资料范围。
8. 文档仍待人工复核：完整性报告保留不确定状态。
## 10. 与后续步骤的接口
后续风险预警读取：
1. `pass_status`
2. `highest_risk_level`
3. `missing_items`
4. `misplaced_items`
5. `manual_review_items`
6. `suggestions`
7. `evidence_refs`
后续字段抽取可读取：
1. 已命中的申请表、产品列表、说明书等文档 ID。
2. 待人工复核文档清单。
3. 当前规则包中声明的模板字段映射。
## 11. 测试设计
### 11.1 单元测试
1. 规则包加载成功。
2. 不支持流程被拦截。
3. 章节点编码匹配成功。
4. 文档角色匹配成功。
5. 必交项缺失被识别。
6. 错放文件被识别。
7. 风险等级映射正确。
8. RAG 失败不影响规则判断。
### 11.2 服务层测试
1. 基于第一步目录汇总执行完整性检查。
2. 缺失 `CH1.4` 时输出高风险。
3. `CH1.2` 目录类文档能作为命中文档进入报告。
4. 待复核文档会进入 `manual_review_items`。
5. 规则包缺失时写入失败审计。
### 11.3 页面测试
1. 页面展示规则包版本。
2. 页面展示缺失项和风险等级。
3. 页面展示法规证据。
4. 页面展示审计入口。
5. RAG 不可用时页面仍显示规则判断结果。
## 12. V1 实现建议
V1 建议先完成以下最小闭环：
1. 基于本地 YAML 规则包实现 `CH1` 完整性检查。
2. 检查 `CH1.2`、`CH1.4`、`CH1.5`、`CH1.9`、`CH1.11.1`、`CH1.11.5`、`CH1.11.6`。
3. 基于第一步的 `chapter_code` 和 `document_role` 做规则匹配。
4. 输出缺失项、疑似项和待复核项。
5. RAG 证据检索先使用 fallback 检索，后续接 Chroma。
6. 完整性报告写入审计。
增强阶段再补齐：
1. 第 2 至第 6 章完整规则。
2. 资料格式要求层检查。
3. 安全和性能基本原则清单映射检查。
4. 后台规则人工校订。
5. 在线法规更新能力。

658
docs/详细设计/3.字段抽取与统一字段池.md Normal file
View File

@@ -0,0 +1,658 @@
# 3. 字段抽取与统一字段池详细设计
## 1. 设计目标
本步骤承接“资料包导入与目录汇总”和“法规完整性检查”的输出，目标是从说明书、申请表、产品列表、声明类文件等注册申报资料中抽取产品核心字段，形成可复用、可追溯、可回填、可一致性核查的统一字段池。
本步骤需要完成以下业务结果：
1. 明确本轮字段抽取的资料范围和目标字段范围。
2. 加载注册申报通用字段 schema。
3. 按字段来源优先级选择候选文档。
4. 对固定格式、标题段落、表格字段执行规则抽取。
5. 对长文本字段使用 LLM 辅助归纳。
6. 对字段值进行标准化、去噪和来源绑定。
7. 将字段结果写入统一字段池。
8. 标记字段置信度、冲突状态和待人工确认状态。
9. 输出结构化 `registration_field_extraction_report`。
本步骤不负责最终一致性判定，不负责 Word 文件生成。字段池会为后续“一致性核查”和“Word 回填导出”提供输入。
## 2. 所属模块与边界
### 2.1 Documents
`apps.documents` 提供文档主数据、正文文本、标题结构、表格结构和处理状态。
本步骤读取：
1. 文档 ID。
2. 文件名和相对路径。
3. 章节点。
4. 文档角色。
5. 正文文本。
6. 表格结构。
7. 文档处理状态。
8. 是否待人工复核。
如果某文档尚未完成文本或表格抽取，本步骤应给出业务提示，而不是默认字段缺失。
### 2.2 Agent Core
`agent_core` 是本步骤的执行主体，负责编排字段 schema 加载、抽取范围确认、规则抽取、表格抽取、LLM 归纳、字段标准化、字段池写入和报告生成。
本步骤建议产生以下中文 Skill：
1. `字段抽取编排Skill`
2. `字段抽取范围确认Skill`
3. `字段Schema加载Skill`
4. `规则字段抽取Skill`
5. `表格字段抽取Skill`
6. `长文本字段归纳Skill`
7. `字段标准化Skill`
8. `统一字段池写入Skill`
9. `字段抽取报告生成Skill`
### 2.3 LLM Provider
LLM 只用于长文本归纳和无法通过规则稳定提取的字段。
LLM 可以处理：
1. 适用范围 / 预期用途归纳。
2. 性能指标摘要。
3. 储存条件段落归纳。
4. 检测靶标从说明书长段落中提取。
LLM 不应处理：
1. 明确表格字段的直接读取。
2. 申请表中固定字段的直接抽取。
3. 字段冲突最终裁判。
4. 没有来源证据的字段编造。
所有 LLM 调用必须经过 Provider，并支持 Mock Provider 离线测试。
### 2.4 RAG
RAG 在本步骤中只作为来源片段定位能力使用。
可用于：
1. 从长文档中定位字段候选段落。
2. 为 LLM 归纳提供限定上下文。
3. 为字段来源证据提供片段引用。
RAG 不负责最终字段值裁判。
### 2.5 Audit
`apps.audit` 记录字段抽取任务的执行范围、目标字段、抽取结果、来源证据、LLM 使用情况和失败原因。
审计中必须保留：
1. `batch_id`
2. `scenario_id`
3. `selected_document_ids`
4. `field_schema_version`
5. `extracted_fields`
6. `manual_review_fields`
7. `llm_provider_name`
8. `tool_calls`
9. `evidence_refs`
## 3. 输入输出
### 3.1 输入
```json
{
"batch_id": 1001,
"scenario_id": "registration_field_extraction",
"field_schema_id": "ivd_registration_fields_v1",
"selected_document_ids": [11, 12, 13],
"target_field_keys": [
"product_name",
"detection_target",
"intended_use",
"storage_condition",
"performance_index"
],
"enable_llm_fallback": true,
"enable_rag_context": true
}
```
### 3.2 输出
本步骤输出 `registration_field_extraction_report`：
```json
{
"report_type": "registration_field_extraction_report",
"batch_id": 1001,
"field_schema_id": "ivd_registration_fields_v1",
"field_schema_version": "2026-06-03",
"summary": {
"target_field_count": 5,
"extracted_field_count": 4,
"manual_review_field_count": 1,
"conflict_candidate_count": 1,
"field_pool_status": "partial_completed"
},
"field_pool_items": [],
"manual_review_fields": [],
"evidence_refs": [],
"tool_calls": []
}
```
### 3.3 字段池条目结构
```json
{
"field_key": "product_name",
"field_label": "产品名称",
"standard_value": "新型冠状病毒 2019-nCoV 核酸检测试剂盒",
"raw_value": "新型冠状病毒2019-nCoV核酸检测试剂盒",
"source_document_id": 11,
"source_document_name": "目标产品说明书.docx",
"source_location": {
"chapter_title": "一、产品名称",
"table_index": null,
"page_no": null
},
"extract_method": "rule_heading",
"confidence": "high",
"conflict_status": "not_checked",
"manual_review_required": false,
"fillable": true
}
```
## 4. 主工作流
```text
用户发起字段抽取任务
-> 读取资料包和完整性检查上下文
-> 确认抽取文档范围
-> 加载字段 schema
-> 加载字段来源优先级
-> 读取文档文本和表格结构
-> 执行规则字段抽取
-> 执行表格字段抽取
-> 对长文本字段执行 RAG 定位与 LLM 归纳
-> 标准化字段值
-> 绑定字段来源证据
-> 写入统一字段池
-> 生成字段抽取报告
-> 写入审计留痕
-> 返回字段池视图
```
## 5. 节点详细设计
### 5.1 节点一：抽取任务上下文加载
业务功能：
1. 读取资料包批次。
2. 读取第一步目录汇总。
3. 读取第二步完整性检查报告。
4. 获取命中的申请表、产品列表、说明书等候选文档。
5. 确认当前资料是否满足字段抽取前置条件。
使用技术：
1. Django ORM
2. JSONField 报告快照
3. dataclass/Pydantic schema
产生方法：
1. `load_field_extraction_context(batch_id, scenario_id) -> FieldExtractionContext`
2. `load_candidate_documents(context, selected_document_ids) -> list[DocumentFact]`
3. `validate_extraction_prerequisites(context) -> ExtractionPrerequisiteResult`
对应 Skill：
1. `字段抽取编排Skill`
### 5.2 节点二：字段抽取范围确认
业务功能：
1. 确认参与字段抽取的文档范围。
2. 按文档角色筛选候选资料。
3. 排除法规资料和待处理失败资料。
4. 对待人工复核文档保留可用但低可信状态。
默认候选来源：
1. 申请表。
2. 产品说明书。
3. 产品列表。
4. 声明类文件。
5. 历史沟通说明。
使用技术：
1. 文档角色规则
2. 来源优先级 YAML
3. 文档状态过滤
产生方法：
1. `resolve_extraction_scope(documents, selected_document_ids, target_field_keys) -> ExtractionScope`
2. `filter_extractable_documents(documents) -> list[DocumentFact]`
3. `rank_documents_by_field_source(field_key, documents) -> list[DocumentFact]`
对应 Skill：
1. `字段抽取范围确认Skill`
### 5.3 节点三：字段 Schema 加载
业务功能：
1. 加载注册申报字段 schema。
2. 确认目标字段、字段类型、来源优先级、抽取方式和回填属性。
3. 为后续 Word 回填建立字段映射基础。
建议 schema 目录：
```text
configs/registration/fields/
ivd_registration_fields_v1.yaml
```
字段 schema 示例：
```yaml
field_schema_id: ivd_registration_fields_v1
version: "2026-06-03"
fields:
- field_key: product_name
field_label: 产品名称
value_type: text
fillable: true
consistency_required: true
source_priority:
- application_form
- product_instruction
- product_list
extraction_methods:
- rule_heading
- table_cell
```
使用技术：
1. YAML
2. Pydantic schema
3. Django cache
产生方法：
1. `load_field_schema(field_schema_id) -> FieldSchema`
2. `validate_field_schema(schema) -> FieldSchemaValidationResult`
3. `select_target_fields(schema, target_field_keys) -> list[FieldDefinition]`
对应 Skill：
1. `字段Schema加载Skill`
### 5.4 节点四：规则字段抽取
业务功能：
1. 从标题、段落、固定标签中提取字段。
2. 优先处理产品名称、申请人名称、储存条件等明确字段。
3. 记录抽取方法和来源片段。
适用字段：
1. 产品名称。
2. 申请人名称。
3. 包装规格。
4. 储存条件。
5. 申报日期。
使用技术：
1. 正则表达式
2. 标题层级解析
3. 标签后取值规则
4. 中文标点标准化
产生方法：
1. `extract_fields_by_rules(document, field_definitions) -> list[FieldCandidate]`
2. `extract_by_heading(text_structure, field_definition) -> FieldCandidate | None`
3. `extract_by_label(text, labels) -> FieldCandidate | None`
4. `build_source_location(document, match) -> SourceLocation`
对应 Skill：
1. `规则字段抽取Skill`
### 5.5 节点五：表格字段抽取
业务功能：
1. 从申请表、产品列表、标准清单等表格中提取字段。
2. 识别表头和字段标签。
3. 抽取规格型号、分类编码、标准清单等结构化字段。
适用字段：
1. 产品名称。
2. 包装规格。
3. 分类编码。
4. 申请人名称。
5. 生产地址。
6. 标准清单。
使用技术：
1. `python-docx` 表格解析
2. PDF 表格解析可选 `pdfplumber`
3. 表头标准化
4. 单元格坐标记录
产生方法：
1. `extract_fields_from_tables(document, field_definitions) -> list[FieldCandidate]`
2. `normalize_table_headers(table) -> NormalizedTable`
3. `match_table_field(table, field_definition) -> FieldCandidate | None`
4. `build_table_source_location(table_index, row_index, col_index) -> SourceLocation`
对应 Skill：
1. `表格字段抽取Skill`
### 5.6 节点六：长文本字段归纳
业务功能：
1. 对规则和表格无法稳定抽取的长文本字段进行归纳。
2. 先用 RAG 或关键词定位候选片段。
3. 将有限上下文交给 LLM Provider。
4. 要求 LLM 返回结构化字段值和引用片段。
适用字段：
1. 检测靶标。
2. 适用范围 / 预期用途。
3. 性能指标。
4. 临床评价路径。
使用技术：
1. RAG fallback / Chroma
2. LLM Provider
3. JSON schema 输出约束
4. Mock Provider 测试
产生方法：
1. `locate_field_context(document, field_definition) -> list[EvidenceChunk]`
2. `summarize_long_text_field(field_definition, chunks) -> FieldCandidate`
3. `call_llm_for_field_extraction(prompt, schema) -> dict`
4. `validate_llm_field_output(output) -> FieldCandidate`
对应 Skill：
1. `长文本字段归纳Skill`
### 5.7 节点七：字段标准化
业务功能：
1. 对抽取候选值做清洗和标准化。
2. 合并空格、全半角、中文标点差异。
3. 标准化单位、日期、枚举值。
4. 计算字段置信度。
5. 标记疑似冲突候选，但不做最终一致性裁判。
使用技术：
1. Python 字符串标准化
2. 字段类型规则
3. 日期解析
4. 单位标准化表
产生方法：
1. `normalize_field_candidate(candidate, field_definition) -> NormalizedFieldCandidate`
2. `normalize_text_value(value) -> str`
3. `normalize_date_value(value) -> str`
4. `calculate_field_confidence(candidate, source_priority) -> str`
5. `detect_conflict_candidates(candidates) -> list[ConflictCandidate]`
对应 Skill：
1. `字段标准化Skill`
### 5.8 节点八：统一字段池写入
业务功能：
1. 将字段候选写入统一字段池。
2. 按字段来源优先级选择推荐值。
3. 保留所有候选值和来源证据。
4. 标记字段是否可回填。
5. 标记字段是否需要一致性核查。
建议模型：
```python
class RegistrationFieldPoolItem(models.Model):
batch = models.ForeignKey(SubmissionBatch, on_delete=models.CASCADE)
field_key = models.CharField(max_length=128)
field_label = models.CharField(max_length=255)
standard_value = models.TextField(blank=True)
raw_value = models.TextField(blank=True)
source_document_id = models.IntegerField(null=True)
source_location = models.JSONField(default=dict)
extract_method = models.CharField(max_length=64)
confidence = models.CharField(max_length=32)
conflict_status = models.CharField(max_length=32, default="not_checked")
manual_review_required = models.BooleanField(default=False)
fillable = models.BooleanField(default=False)
```
使用技术：
1. Django ORM
2. JSONField
3. 批量写入
4. 字段池版本号
产生方法：
1. `write_field_pool(batch_id, normalized_candidates, field_schema) -> FieldPoolWriteResult`
2. `select_recommended_field_value(field_key, candidates, source_priority) -> FieldPoolItem`
3. `persist_field_candidates(field_pool_item, candidates) -> None`
4. `mark_manual_review_fields(field_pool_items) -> list[FieldPoolItem]`
对应 Skill：
1. `统一字段池写入Skill`
### 5.9 节点九：字段抽取报告生成
业务功能：
1. 汇总字段抽取结果。
2. 输出字段池表格。
3. 输出待人工复核字段。
4. 输出字段来源证据。
5. 生成页面展示和飞书摘要载荷。
6. 写入审计记录。
使用技术：
1. dataclass/Pydantic
2. JSONField
3. Audit 服务
4. 页面展示 schema
产生方法：
1. `build_field_extraction_report(context, field_pool_items) -> RegistrationFieldExtractionReport`
2. `build_field_pool_display_rows(field_pool_items) -> list[dict]`
3. `build_field_extraction_audit_payload(report) -> dict`
4. `record_field_extraction_audit(report, context) -> AuditLog`
对应 Skill：
1. `字段抽取报告生成Skill`
## 6. Skill 清单
本步骤产生以下 Skill 设计文档：
1. [字段抽取编排Skill](skill/字段抽取编排Skill.md)
2. [字段抽取范围确认Skill](skill/字段抽取范围确认Skill.md)
3. [字段Schema加载Skill](skill/字段Schema加载Skill.md)
4. [规则字段抽取Skill](skill/规则字段抽取Skill.md)
5. [表格字段抽取Skill](skill/表格字段抽取Skill.md)
6. [长文本字段归纳Skill](skill/长文本字段归纳Skill.md)
7. [字段标准化Skill](skill/字段标准化Skill.md)
8. [统一字段池写入Skill](skill/统一字段池写入Skill.md)
9. [字段抽取报告生成Skill](skill/字段抽取报告生成Skill.md)
## 7. 字段 Schema 设计
### 7.1 V1 目标字段
| 字段编码 | 中文名 | 是否回填 | 是否强一致 |
|---|---|---|---|
| `product_name` | 产品名称 | 是 | 是 |
| `detection_target` | 检测靶标 | 是 | 是 |
| `intended_use` | 适用范围 / 预期用途 | 是 | 是 |
| `storage_condition` | 储存条件 | 是 | 是 |
| `performance_index` | 性能指标 | 是 | 否 |
| `package_specification` | 包装规格 | 是 | 是 |
| `applicant_name` | 申请人名称 | 是 | 是 |
| `classification_code` | 分类编码 | 是 | 是 |
### 7.2 字段来源优先级
| 字段 | 来源优先级 |
|---|---|
| 产品名称 | 申请表 > 说明书 > 产品列表 |
| 检测靶标 | 说明书 > 产品列表 > 申请表 |
| 适用范围 | 说明书 > 申请表 |
| 储存条件 | 说明书 > 标签样稿 |
| 性能指标 | 说明书 > 性能研究资料 |
| 包装规格 | 产品列表 > 申请表 > 说明书 |
## 8. 页面展示
字段抽取结果页面建议展示：
1. 当前字段 schema 版本。
2. 抽取文档范围。
3. 字段总数。
4. 已抽取字段数。
5. 待人工复核字段数。
6. 字段池表格。
7. 字段来源证据。
8. 工具调用记录。
9. 审计入口。
字段池表格字段：
1. 字段名。
2. 推荐值。
3. 原始值。
4. 来源文档。
5. 来源位置。
6. 抽取方法。
7. 置信度。
8. 是否待人工复核。
9. 是否可回填。
## 9. 异常处理
1. 无可抽取文档：返回业务提示，不写空字段池。
2. 文档未完成文本抽取：标记前置条件不足。
3. 字段 schema 缺失：任务不可执行，写失败审计。
4. 表格解析失败：跳过表格抽取，保留规则抽取和 LLM 归纳。
5. LLM 不可用：仅输出规则和表格抽取结果。
6. LLM 输出非法 JSON：丢弃该候选并记录工具失败。
7. 多候选值不一致：写入候选值，字段状态标记 `conflict_candidate`。
8. 来源文档待复核：字段置信度不超过 `medium`。
## 10. 与后续步骤的接口
后续一致性核查读取：
1. `field_key`
2. `standard_value`
3. `raw_value`
4. `source_document_id`
5. `source_location`
6. `confidence`
7. `conflict_status`
8. `manual_review_required`
后续 Word 回填读取：
1. `field_key`
2. `standard_value`
3. `fillable`
4. `manual_review_required`
5. `conflict_status`
6. `template_field_refs`
## 11. 测试设计
### 11.1 单元测试
1. 字段 schema 加载成功。
2. 字段来源优先级排序正确。
3. 标题字段抽取正确。
4. 表格字段抽取正确。
5. LLM 输出 schema 校验正确。
6. 字段标准化正确。
7. 推荐值选择正确。
### 11.2 服务层测试
1. 基于说明书抽取产品名称。
2. 基于说明书抽取检测靶标。
3. 基于申请表抽取申请人名称。
4. 多来源候选写入字段池。
5. LLM 不可用时任务仍能完成部分结果。
6. 字段池报告写入审计。
### 11.3 页面测试
1. 页面展示字段池表格。
2. 页面展示字段来源文档。
3. 页面展示待人工复核字段。
4. 页面展示工具调用记录。
5. 页面展示审计入口。
## 12. V1 实现建议
V1 建议先完成以下最小闭环：
1. 建立字段 schema YAML。
2. 从 `目标产品说明书.docx` 抽取产品名称、检测靶标、适用范围、储存条件、性能指标。
3. 从 `CH1.4 申请表.docx` 和 `CH1.5 产品列表.docx` 抽取可比对字段。
4. 写入统一字段池。
5. 输出字段抽取报告。
6. 支持 Mock Provider 离线测试。
增强阶段再补齐：
1. 更多字段类型。
2. PDF 表格抽取。
3. OCR 兜底。
4. 后台人工修正字段池。
5. 字段池版本管理。

528
docs/详细设计/4.一致性核查.md Normal file
View File

@@ -0,0 +1,528 @@
# 4. 一致性核查详细设计
## 1. 设计目标
本步骤承接“字段抽取与统一字段池”的输出，目标是核查同一审核范围内不同文档之间的关键字段是否完全一致，并识别跨产品资料混入、字段冲突、来源不确定和需要人工复核的问题。
本步骤需要完成以下业务结果：
1. 明确本次一致性核查的审核范围，避免把不同产品样例直接合并审核。
2. 加载强一致字段规则，V1 默认按完全一致处理。
3. 从统一字段池读取字段候选值和来源证据。
4. 按字段和来源文档分组。
5. 对强一致字段执行完全一致比对。
6. 识别字段冲突、疑似混档、待人工复核和一致通过项。
7. 生成冲突明细、风险建议和证据链。
8. 输出结构化 `registration_consistency_report`。
本步骤不负责重新抽取字段，不负责综合风险汇总，不负责自动修正字段池。它只对字段池中已有的字段事实进行一致性判断。
## 2. 所属模块与边界
### 2.1 Documents
`apps.documents` 提供文档主数据，用于确认字段来源文档是否属于同一批次、同一审核范围和相同业务资料角色。
本步骤读取：
1. 文档 ID。
2. 文档名称。
3. 章节点。
4. 文档角色。
5. 批次 ID。
6. 处理状态。
7. 是否待人工复核。
### 2.2 Agent Core
`agent_core` 是本步骤的执行主体，负责编排审核范围确认、强一致规则加载、字段池读取、字段分组、完全一致比对、混档识别、报告生成和审计留痕。
本步骤建议产生以下中文 Skill：
1. `一致性核查编排Skill`
2. `审核范围确认Skill`
3. `强一致规则加载Skill`
4. `字段分组Skill`
5. `字段完全一致比对Skill`
6. `混档风险识别Skill`
7. `一致性报告生成Skill`
### 2.3 LLM Provider
本步骤默认不使用 LLM 作为判断引擎。
LLM 只可用于：
1. 将规则结论组织成自然语言说明。
2. 生成处理建议文案。
3. 对复杂冲突进行解释性摘要。
LLM 不可用于：
1. 将不一致字段判为一致。
2. 覆盖强一致规则结论。
3. 无证据地解释跨产品资料混入。
### 2.4 Audit
`apps.audit` 记录一致性核查的审核范围、字段规则、冲突字段、来源文档、处理建议和最终状态。
审计中必须保留：
1. `batch_id`
2. `selected_document_ids`
3. `scope_confirmation`
4. `field_rule_version`
5. `consistent_fields`
6. `conflict_fields`
7. `mixed_package_warnings`
8. `manual_review_fields`
9. `evidence_refs`
## 3. 输入输出
### 3.1 输入
```json
{
"batch_id": 1001,
"scenario_id": "registration_consistency_review",
"selected_document_ids": [11, 12, 13],
"field_rule_id": "ivd_strict_consistency_v1",
"target_field_keys": [
"product_name",
"applicant_name",
"package_specification",
"classification_code"
],
"strict_mode": true
}
```
### 3.2 输出
本步骤输出 `registration_consistency_report`：
```json
{
"report_type": "registration_consistency_report",
"batch_id": 1001,
"field_rule_id": "ivd_strict_consistency_v1",
"summary": {
"checked_field_count": 4,
"consistent_field_count": 2,
"conflict_field_count": 1,
"manual_review_field_count": 1,
"mixed_package_warning_count": 1,
"highest_risk_level": "high",
"pass_status": "failed"
},
"consistent_fields": [],
"conflict_fields": [],
"manual_review_fields": [],
"mixed_package_warnings": [],
"suggestions": []
}
```
### 3.3 一致性状态
| 状态 | 含义 |
|---|---|
| `consistent` | 同一字段在审核范围内完全一致 |
| `conflict` | 同一字段出现不同标准值或原始值 |
| `single_source` | 只有一个来源，无法跨文档比对 |
| `manual_review_required` | 来源文档或字段值不确定 |
| `not_checked` | 字段不在本次核查范围 |
| `mixed_package_suspected` | 疑似跨产品资料混入 |
## 4. 主工作流
```text
用户发起一致性核查
-> 读取统一字段池
-> 确认审核范围
-> 加载强一致字段规则
-> 筛选目标字段
-> 按字段分组候选值
-> 按完全一致规则比对
-> 识别字段冲突
-> 识别疑似混档风险
-> 生成处理建议
-> 写入字段池冲突状态
-> 生成一致性报告
-> 写入审计留痕
-> 返回 Web/飞书可展示结果
```
## 5. 节点详细设计
### 5.1 节点一：读取统一字段池
业务功能：
1. 根据 `batch_id` 读取字段池。
2. 过滤本次目标字段。
3. 读取每个字段的所有候选值和推荐值。
4. 加载字段来源文档信息。
使用技术：
1. Django ORM
2. JSONField
3. dataclass/Pydantic schema
产生方法：
1. `load_field_pool(batch_id) -> list[FieldPoolItem]`
2. `load_field_candidates(batch_id, field_keys) -> list[FieldCandidateRecord]`
3. `attach_source_documents(candidates) -> list[FieldCandidateWithDocument]`
对应 Skill：
1. `一致性核查编排Skill`
### 5.2 节点二：审核范围确认
业务功能：
1. 确认哪些文档属于同一项目、批次和本次审核范围。
2. 如果用户选择了文档范围，只对选中范围执行。
3. 如果未选择范围，默认使用当前批次业务资料。
4. 对疑似不同产品、不同来源、不同流程资料给出范围警告。
范围确认规则：
1. 同一 `batch_id` 是最低要求。
2. `source_role` 必须为 `submission`。
3. 法规资料不进入一致性核查。
4. 待人工复核文档可以进入，但相关字段不直接判通过。
5. 疑似跨产品文档进入混档风险提示。
使用技术：
1. 文档主数据
2. 资料包批次
3. 文档角色规则
4. 用户选中文档范围
产生方法：
1. `resolve_review_scope(batch_id, selected_document_ids) -> ReviewScope`
2. `validate_scope_documents(documents) -> ScopeValidationResult`
3. `detect_scope_uncertainties(documents) -> list[ScopeWarning]`
对应 Skill：
1. `审核范围确认Skill`
### 5.3 节点三：强一致规则加载
业务功能：
1. 加载强一致字段规则。
2. 确认字段是否要求完全一致。
3. 定义冲突严重度。
4. 定义字段缺少多个来源时的处理方式。
规则示例：
```yaml
field_rule_id: ivd_strict_consistency_v1
version: "2026-06-03"
strict_mode: true
fields:
- field_key: product_name
field_label: 产品名称
consistency_required: true
compare_mode: exact
risk_level_if_conflict: high
- field_key: performance_index
consistency_required: false
compare_mode: not_checked
```
使用技术：
1. YAML
2. Pydantic schema
3. Django cache
产生方法：
1. `load_consistency_rules(field_rule_id) -> ConsistencyRuleSet`
2. `validate_consistency_rules(rule_set) -> RuleValidationResult`
3. `select_consistency_fields(rule_set, target_field_keys) -> list[ConsistencyFieldRule]`
对应 Skill：
1. `强一致规则加载Skill`
### 5.4 节点四：字段分组
业务功能：
1. 按 `field_key` 分组字段候选。
2. 按来源文档分组同一字段。
3. 保留标准值、原始值、来源位置、置信度。
4. 标记单来源字段和多来源字段。
使用技术：
1. Python 分组
2. 字段池候选表
3. 文档元数据
产生方法：
1. `group_candidates_by_field(candidates) -> dict[str, list[FieldCandidateWithDocument]]`
2. `group_candidates_by_document(candidates) -> dict[int, list[FieldCandidateWithDocument]]`
3. `build_field_compare_units(grouped_candidates) -> list[FieldCompareUnit]`
对应 Skill：
1. `字段分组Skill`
### 5.5 节点五：字段完全一致比对
业务功能：
1. 对强一致字段执行完全一致比对。
2. 对标准化值不同的字段判定冲突。
3. 对标准化值相同但原始值差异较大的字段标记待复核。
4. 对单来源字段标记无法跨文档比对。
比对规则：
1. `compare_mode = exact` 时，标准值必须完全一致。
2. 不采用语义相近判定。
3. 空值不参与通过判定。
4. 待人工复核来源不作为通过证据。
使用技术：
1. Python 严格字符串比较
2. 字段标准化结果
3. 风险映射规则
产生方法：
1. `compare_exact(field_compare_unit, rule) -> FieldCompareResult`
2. `detect_value_conflict(values) -> bool`
3. `detect_raw_value_variation(values) -> bool`
4. `build_conflict_detail(result) -> ConflictDetail`
对应 Skill：
1. `字段完全一致比对Skill`
### 5.6 节点六：混档风险识别
业务功能：
1. 基于产品名称、检测靶标、申请人等核心字段识别疑似跨产品资料混入。
2. 当同一审核范围内出现明显不同产品名称时，输出混档风险。
3. 区分“字段冲突”和“疑似资料包范围错误”。
典型规则：
1. 产品名称出现两个不同值：高风险混档。
2. 检测靶标与产品名称指向明显不同产品：高风险混档。
3. 申请人不同：高风险或待复核。
4. 同一文档角色出现多个版本：中风险或待复核。
使用技术：
1. 字段比对结果
2. 文档角色分析
3. 批次范围校验
4. 规则映射 YAML
产生方法：
1. `detect_mixed_package_risk(compare_results, scope) -> list[MixedPackageWarning]`
2. `detect_product_identity_conflict(field_results) -> MixedPackageWarning | None`
3. `classify_mixed_package_risk(warning) -> str`
对应 Skill：
1. `混档风险识别Skill`
### 5.7 节点七：字段池冲突状态回写
业务功能：
1. 将一致性核查结果回写到字段池。
2. 对冲突字段标记 `conflict`。
3. 对待复核字段标记 `manual_review_required`。
4. 对一致字段标记 `consistent`。
使用技术：
1. Django ORM
2. 批量更新
3. 字段池版本记录
产生方法：
1. `update_field_pool_consistency_status(compare_results) -> FieldPoolUpdateResult`
2. `mark_conflict_field(field_key, conflict_detail) -> None`
3. `mark_consistent_field(field_key) -> None`
对应 Skill：
1. `一致性核查编排Skill`
### 5.8 节点八：一致性报告生成
业务功能：
1. 汇总一致字段、冲突字段、待复核字段和混档风险。
2. 生成结构化报告。
3. 生成页面展示区块。
4. 生成飞书摘要载荷。
5. 写入审计记录。
使用技术：
1. dataclass/Pydantic
2. JSONField
3. Audit 服务
4. 页面展示 schema
产生方法：
1. `build_consistency_report(context, compare_results, mixed_warnings) -> RegistrationConsistencyReport`
2. `build_consistency_summary(compare_results, mixed_warnings) -> dict`
3. `build_consistency_display_sections(report) -> list[dict]`
4. `record_consistency_audit(report, context) -> AuditLog`
对应 Skill：
1. `一致性报告生成Skill`
## 6. Skill 清单
本步骤产生以下 Skill 设计文档：
1. [一致性核查编排Skill](skill/一致性核查编排Skill.md)
2. [审核范围确认Skill](skill/审核范围确认Skill.md)
3. [强一致规则加载Skill](skill/强一致规则加载Skill.md)
4. [字段分组Skill](skill/字段分组Skill.md)
5. [字段完全一致比对Skill](skill/字段完全一致比对Skill.md)
6. [混档风险识别Skill](skill/混档风险识别Skill.md)
7. [一致性报告生成Skill](skill/一致性报告生成Skill.md)
## 7. 强一致字段设计
V1 建议强一致字段：
| 字段编码 | 中文名 | 风险等级 |
|---|---|---|
| `product_name` | 产品名称 | 高 |
| `applicant_name` | 申请人名称 | 高 |
| `package_specification` | 包装规格 | 中 |
| `classification_code` | 分类编码 | 高 |
| `detection_target` | 检测靶标 | 高 |
| `intended_use` | 适用范围 / 预期用途 | 中 |
## 8. 页面展示
一致性核查页面建议展示：
1. 当前审核范围。
2. 参与核查文档。
3. 强一致字段规则版本。
4. 一致字段数量。
5. 冲突字段数量。
6. 待人工复核字段数量。
7. 混档风险提示。
8. 字段冲突明细表。
9. 来源证据。
10. 审计入口。
冲突明细表字段：
1. 字段名称。
2. 冲突值。
3. 来源文档。
4. 来源位置。
5. 风险等级。
6. 建议动作。
## 9. 异常处理
1. 字段池不存在：提示先执行字段抽取。
2. 未选择文档且批次为空：返回业务错误。
3. 审核范围内只有单个文档：输出单来源提示，不判冲突。
4. 强一致规则缺失：任务不可执行，写失败审计。
5. 字段全部为空：标记待人工复核。
6. 来源文档待复核：字段不直接判通过。
7. 混档风险存在：本步骤 `pass_status` 直接失败。
## 10. 与后续步骤的接口
后续风险预警读取：
1. `pass_status`
2. `highest_risk_level`
3. `conflict_fields`
4. `mixed_package_warnings`
5. `manual_review_fields`
6. `suggestions`
后续 Word 回填读取：
1. 字段池中的 `conflict_status`。
2. 冲突字段清单。
3. 待人工复核字段清单。
4. 可安全回填字段清单。
## 11. 测试设计
### 11.1 单元测试
1. 审核范围确认正确。
2. 强一致规则加载成功。
3. 字段按 `field_key` 分组正确。
4. 完全一致比对正确。
5. 字段冲突识别正确。
6. 单来源字段不判冲突。
7. 混档风险识别正确。
### 11.2 服务层测试
1. 产品名称不同输出高风险冲突。
2. 产品名称相同输出一致。
3. 申请人不同输出冲突。
4. 待复核字段进入人工复核清单。
5. 冲突状态回写字段池。
6. 一致性报告写入审计。
### 11.3 页面测试
1. 页面展示审核范围。
2. 页面展示冲突字段来源。
3. 页面展示混档风险。
4. 页面展示待人工复核状态。
5. 页面展示审计入口。
## 12. V1 实现建议
V1 建议先完成以下最小闭环：
1. 从统一字段池读取产品名称、申请人名称、包装规格、分类编码。
2. 按完全一致规则比对。
3. 识别样例中可能出现的产品名称冲突。
4. 输出冲突明细和混档风险。
5. 回写字段池 `conflict_status`。
6. 生成一致性核查报告并写审计。
增强阶段再补齐：
1. 更多强一致字段。
2. 版本重复识别。
3. 文档结构一致性检查。
4. 人工确认后重新判定。
5. 冲突字段修正建议。

477
docs/详细设计/5.风险预警.md Normal file
View File

@@ -0,0 +1,477 @@
# 5. 风险预警详细设计
## 1. 设计目标
本步骤承接法规完整性检查、字段抽取与一致性核查结果，目标是把缺失项、错放项、字段冲突、混档风险、待人工复核项和交付风险统一汇总成可执行的合规风险清单，并给出是否通过、整改优先级和责任建议。
本步骤需要完成以下业务结果：
1. 汇总前序任务报告。
2. 加载风险分级和准入规则。
3. 将完整性、字段抽取、一致性等结果映射为风险项。
4. 合并重复风险和关联风险。
5. 计算最高风险等级和是否通过。
6. 生成整改建议、处理优先级和责任角色。
7. 输出结构化 `registration_risk_report`。
8. 为飞书通知步骤生成风险摘要载荷。
本步骤不重新执行完整性检查、字段抽取或一致性核查。它只消费前序结构化报告，并在规则基础上生成综合风险预警。
## 2. 所属模块与边界
### 2.1 Agent Core
`agent_core` 是本步骤的执行主体，负责编排报告加载、风险规则加载、风险项生成、风险归并、准入判定、整改建议生成和报告输出。
本步骤建议产生以下中文 Skill：
1. `风险预警编排Skill`
2. `前序报告汇总Skill`
3. `风险规则加载Skill`
4. `风险项生成Skill`
5. `风险归并Skill`
6. `准入判定Skill`
7. `整改建议生成Skill`
8. `风险报告生成Skill`
### 2.2 LLM Provider
LLM 可以用于将规则风险结论整理为自然语言建议，但不能改变风险等级、是否通过和整改优先级。
LLM 可以处理：
1. 风险摘要润色。
2. 整改建议文案组织。
3. 飞书通知摘要表达。
LLM 不可处理：
1. 修改规则判定的风险等级。
2. 将高风险降级。
3. 将不通过改为通过。
### 2.3 Audit
`apps.audit` 记录风险预警的输入报告、风险规则版本、风险项、准入结论和建议动作。
审计中必须保留：
1. `batch_id`
2. `source_report_ids`
3. `risk_rule_version`
4. `risk_items`
5. `pass_status`
6. `highest_risk_level`
7. `manual_review_items`
8. `owner_roles`
9. `suggestions`
## 3. 输入输出
### 3.1 输入
```json
{
"batch_id": 1001,
"scenario_id": "registration_risk_report",
"risk_rule_id": "ivd_registration_risk_v1",
"include_reports": [
"registration_completeness_report",
"registration_field_extraction_report",
"registration_consistency_report"
],
"enable_llm_summary": true
}
```
### 3.2 输出
本步骤输出 `registration_risk_report`：
```json
{
"report_type": "registration_risk_report",
"batch_id": 1001,
"risk_rule_id": "ivd_registration_risk_v1",
"summary": {
"risk_item_count": 6,
"high_risk_count": 2,
"medium_risk_count": 2,
"low_risk_count": 1,
"manual_review_count": 1,
"highest_risk_level": "high",
"pass_status": "failed"
},
"risk_items": [],
"manual_review_items": [],
"suggestions": [],
"owner_notifications": []
}
```
## 4. 主工作流
```text
用户发起风险预警
-> 读取前序任务报告
-> 加载风险规则
-> 从完整性报告生成缺失/错放风险
-> 从字段抽取报告生成抽取不确定风险
-> 从一致性报告生成冲突/混档风险
-> 合并重复和关联风险
-> 计算风险等级和准入状态
-> 生成整改建议和责任角色
-> 生成综合风险报告
-> 写入审计留痕
-> 返回 Web/飞书可展示结果
```
## 5. 节点详细设计
### 5.1 节点一：前序报告汇总
业务功能：
1. 读取当前批次的完整性检查报告。
2. 读取字段抽取报告。
3. 读取一致性核查报告。
4. 判断哪些报告缺失或过期。
5. 将报告统一转为风险输入上下文。
使用技术：
1. Django ORM
2. JSONField
3. 报告版本号
4. dataclass/Pydantic
产生方法：
1. `load_source_reports(batch_id, include_reports) -> SourceReportBundle`
2. `validate_source_reports(bundle) -> SourceReportValidationResult`
3. `build_risk_context(bundle) -> RiskEvaluationContext`
对应 Skill：
1. `前序报告汇总Skill`
### 5.2 节点二：风险规则加载
业务功能：
1. 加载风险分级规则。
2. 加载准入规则。
3. 加载风险类型和责任角色映射。
4. 加载整改建议模板。
建议规则目录：
```text
configs/registration/risk/
ivd_registration_risk_v1.yaml
```
规则示例：
```yaml
risk_rule_id: ivd_registration_risk_v1
version: "2026-06-03"
admission:
high_risk_policy: fail
multiple_medium_policy: review_required
risk_types:
missing_required_document:
default_level: high
owner_role: 注册申报负责人
field_conflict:
default_level: high
owner_role: 注册资料负责人
```
使用技术：
1. YAML
2. Pydantic schema
3. Django cache
产生方法：
1. `load_risk_rules(risk_rule_id) -> RiskRuleSet`
2. `validate_risk_rules(rule_set) -> RiskRuleValidationResult`
3. `load_owner_role_mapping(rule_set) -> dict`
对应 Skill：
1. `风险规则加载Skill`
### 5.3 节点三：风险项生成
业务功能：
1. 从完整性报告生成缺失、错放、待复核风险。
2. 从字段抽取报告生成字段缺失、低可信、抽取失败风险。
3. 从一致性报告生成字段冲突、混档风险。
4. 记录风险来源报告和证据。
风险类型：
1. `missing_required_document`
2. `misplaced_document`
3. `field_missing`
4. `field_low_confidence`
5. `field_conflict`
6. `mixed_package`
7. `manual_review_required`
8. `delivery_blocker`
使用技术：
1. Python 规则映射
2. 风险规则 YAML
3. 前序报告 schema
产生方法：
1. `build_risks_from_completeness(report, rules) -> list[RiskItem]`
2. `build_risks_from_field_extraction(report, rules) -> list[RiskItem]`
3. `build_risks_from_consistency(report, rules) -> list[RiskItem]`
4. `attach_risk_evidence(risk_item, source_report) -> RiskItem`
对应 Skill：
1. `风险项生成Skill`
### 5.4 节点四：风险归并
业务功能：
1. 合并重复风险。
2. 关联同一根因风险。
3. 避免同一字段冲突重复出现在多个列表。
4. 保留风险来源链路。
归并示例：
1. 产品名称冲突和混档风险可以关联。
2. 缺失申请表和字段缺失申请人名称可以关联。
3. 文档待复核导致的字段低可信可以关联。
使用技术：
1. 风险指纹
2. `risk_type + field_key + document_id`
3. Python 分组
产生方法：
1. `build_risk_fingerprint(risk_item) -> str`
2. `merge_duplicate_risks(risk_items) -> list[RiskItem]`
3. `link_related_risks(risk_items) -> list[RiskGroup]`
对应 Skill：
1. `风险归并Skill`
### 5.5 节点五：准入判定
业务功能：
1. 计算最高风险等级。
2. 根据规则判断是否通过。
3. 区分风险等级和人工复核状态。
4. 输出最终准入结论。
准入规则：
1. 任一高风险项：`pass_status = failed`
2. 无高风险但多个中风险：`pass_status = review_required`
3. 仅低风险：`pass_status = conditional_pass`
4. 无风险但有人工复核项：`pass_status = review_required`
5. 无风险无复核：`pass_status = passed`
使用技术：
1. 风险规则
2. Python 枚举
3. 评分配置
产生方法：
1. `calculate_highest_risk_level(risk_items) -> str`
2. `calculate_pass_status(risk_items, manual_review_items, rules) -> str`
3. `build_admission_detail(risk_items, status) -> AdmissionDecision`
对应 Skill：
1. `准入判定Skill`
### 5.6 节点六：整改建议生成
业务功能：
1. 为每个风险项生成建议动作。
2. 按高、中、低风险排序。
3. 映射责任角色。
4. 生成可用于飞书通知的摘要。
使用技术：
1. 本地建议模板
2. 责任角色映射
3. 可选 LLM Provider 生成自然语言摘要
产生方法：
1. `build_risk_suggestion(risk_item, rules) -> Suggestion`
2. `sort_suggestions_by_priority(suggestions) -> list[Suggestion]`
3. `build_owner_notification_payload(risk_items) -> list[OwnerNotificationPayload]`
4. `summarize_risk_report_with_llm(report) -> str`
对应 Skill：
1. `整改建议生成Skill`
### 5.7 节点七：风险报告生成
业务功能：
1. 汇总风险项和建议。
2. 生成结构化风险报告。
3. 生成页面展示区块。
4. 生成飞书通知载荷。
5. 写入审计。
使用技术：
1. dataclass/Pydantic
2. JSONField
3. Audit 服务
4. 飞书摘要 payload schema
产生方法：
1. `build_risk_report(context, risk_items, admission, suggestions) -> RegistrationRiskReport`
2. `build_risk_summary(risk_items, admission) -> dict`
3. `build_risk_display_sections(report) -> list[dict]`
4. `record_risk_audit(report, context) -> AuditLog`
对应 Skill：
1. `风险报告生成Skill`
## 6. Skill 清单
本步骤产生以下 Skill 设计文档：
1. [风险预警编排Skill](skill/风险预警编排Skill.md)
2. [前序报告汇总Skill](skill/前序报告汇总Skill.md)
3. [风险规则加载Skill](skill/风险规则加载Skill.md)
4. [风险项生成Skill](skill/风险项生成Skill.md)
5. [风险归并Skill](skill/风险归并Skill.md)
6. [准入判定Skill](skill/准入判定Skill.md)
7. [整改建议生成Skill](skill/整改建议生成Skill.md)
8. [风险报告生成Skill](skill/风险报告生成Skill.md)
## 7. 风险项结构
```json
{
"risk_id": "RISK-001",
"risk_type": "field_conflict",
"risk_level": "high",
"source_report_type": "registration_consistency_report",
"related_documents": [11, 12],
"related_field_key": "product_name",
"description": "说明书与申请表中的产品名称不一致。",
"suggestion": "请先确认当前审核范围是否混入其他产品资料。",
"owner_role": "注册资料负责人",
"manual_review_required": false
}
```
## 8. 页面展示
风险预警页面建议展示：
1. 综合结论。
2. 是否通过。
3. 最高风险等级。
4. 高/中/低风险数量。
5. 待人工复核数量。
6. 风险清单。
7. 整改建议。
8. 责任角色。
9. 审计入口。
## 9. 异常处理
1. 前序报告缺失：生成“报告不完整”风险或提示先执行对应任务。
2. 风险规则缺失：任务不可执行，写失败审计。
3. LLM 不可用：使用本地模板生成建议。
4. 责任角色未配置：使用默认责任角色并提示维护映射。
5. 风险项为空：输出通过或待复核状态。
## 10. 与后续步骤的接口
后续 Word 回填读取：
1. `pass_status`
2. `high_risk_count`
3. `field_conflict` 风险项。
4. `manual_review_items`
5. 可回填风险拦截状态。
后续飞书通知读取：
1. 风险摘要。
2. 高风险清单。
3. 责任角色。
4. 责任人通知载荷。
5. Web 详情页链接。
## 11. 测试设计
### 11.1 单元测试
1. 风险规则加载成功。
2. 完整性缺失项生成风险。
3. 字段冲突生成高风险。
4. 混档风险生成高风险。
5. 风险归并正确。
6. 任一高风险判不通过。
### 11.2 服务层测试
1. 缺少完整性报告时提示前序任务缺失。
2. 有高风险时 `pass_status = failed`。
3. 只有低风险时 `conditional_pass`。
4. 待复核项进入人工复核清单。
5. 风险报告写入审计。
### 11.3 页面测试
1. 页面展示最高风险等级。
2. 页面展示风险清单。
3. 页面展示整改建议。
4. 页面展示责任角色。
5. 页面展示审计入口。
## 12. V1 实现建议
V1 建议先完成以下最小闭环：
1. 汇总完整性检查和一致性核查报告。
2. 生成缺失风险、字段冲突风险、混档风险。
3. 实现任一高风险即不通过。
4. 生成整改建议和责任角色。
5. 输出 `registration_risk_report`。
6. 写入审计。
增强阶段再补齐：
1. 多维度风险评分。
2. 历史申报事项风险。
3. 版本一致性风险。
4. 飞书责任人通知联动。
5. 后台风险规则维护。

456
docs/详细设计/6.Word回填导出.md Normal file
View File

@@ -0,0 +1,456 @@
# 6. Word 回填导出详细设计
## 1. 设计目标
本步骤承接字段抽取、统一字段池、一致性核查和风险预警结果，目标是将可回填字段按模板映射写入注册申报表格或对照清单，并生成新的 Word 文件供用户下载、复核和归档。
本步骤需要完成以下业务结果：
1. 选择适用的 Word 模板。
2. 加载模板字段映射。
3. 从统一字段池读取可回填字段。
4. 根据风险报告和冲突状态执行回填拦截。
5. 生成回填数据集。
6. 按模板写入 Word 文档。
7. 校验输出文档版式、字段落位和导出状态。
8. 生成导出记录和下载入口。
9. 写入审计留痕。
本步骤不重新抽取字段，不修改法规判断和风险结论。若字段冲突或高风险未处理，应阻止自动生成可报送文件，或者生成“待复核草稿版”并明确标记。
## 2. 所属模块与边界
### 2.1 Documents
`apps.documents` 负责保存生成后的 Word 文件、记录导出文件元数据，并提供下载入口。
### 2.2 Agent Core
`agent_core` 负责模板选择、字段映射、回填数据集构建、Word 渲染、版式校验和导出报告生成。
本步骤建议产生以下中文 Skill：
1. `Word回填导出编排Skill`
2. `模板选择Skill`
3. `模板字段映射加载Skill`
4. `回填字段集构建Skill`
5. `回填拦截检查Skill`
6. `Word模板渲染Skill`
7. `导出版式校验Skill`
8. `导出记录生成Skill`
### 2.3 Audit
`apps.audit` 记录本次回填导出的模板版本、字段映射、回填字段、拦截状态、输出文件和失败原因。
审计中必须保留：
1. `batch_id`
2. `template_id`
3. `template_version`
4. `field_mapping_version`
5. `filled_fields`
6. `blocked_fields`
7. `output_file_id`
8. `export_status`
9. `layout_check_result`
## 3. 输入输出
### 3.1 输入
```json
{
"batch_id": 1001,
"scenario_id": "registration_word_fill_export",
"template_id": "registration_application_form_v1",
"target_output_type": "application_form",
"allow_draft_when_blocked": true,
"selected_field_keys": [
"product_name",
"detection_target",
"intended_use",
"storage_condition",
"performance_index"
]
}
```
### 3.2 输出
本步骤输出 `registration_word_export_report`：
```json
{
"report_type": "registration_word_export_report",
"batch_id": 1001,
"template_id": "registration_application_form_v1",
"export_status": "draft_generated",
"summary": {
"fillable_field_count": 5,
"filled_field_count": 4,
"blocked_field_count": 1,
"manual_review_field_count": 1,
"layout_check_status": "passed"
},
"filled_fields": [],
"blocked_fields": [],
"output_file": {
"file_id": 2001,
"filename": "注册申报表格_回填草稿.docx",
"download_url": "/documents/exports/2001/download/"
}
}
```
## 4. 主工作流
```text
用户发起 Word 回填导出
-> 读取字段池和风险报告
-> 选择目标模板
-> 加载模板字段映射
-> 构建回填字段集
-> 执行冲突和风险拦截检查
-> 渲染 Word 模板
-> 校验字段落位和版式
-> 保存导出文件
-> 生成导出报告
-> 写入审计留痕
-> 返回下载入口
```
## 5. 节点详细设计
### 5.1 节点一：导出上下文加载
业务功能：
1. 读取资料包批次。
2. 读取统一字段池。
3. 读取一致性核查报告。
4. 读取风险预警报告。
5. 确认是否允许生成正式版或草稿版。
使用技术：
1. Django ORM
2. JSONField 报告快照
3. dataclass/Pydantic
产生方法：
1. `load_export_context(batch_id, template_id) -> WordExportContext`
2. `load_fillable_field_pool(batch_id) -> list[FieldPoolItem]`
3. `load_export_blockers(batch_id) -> ExportBlockerContext`
对应 Skill：
1. `Word回填导出编排Skill`
### 5.2 节点二：模板选择
业务功能：
1. 根据输出目标选择模板。
2. 校验模板是否存在。
3. 校验模板适用流程。
4. 校验模板版本是否启用。
模板类型：
1. 注册申报表格模板。
2. 法规对照清单模板。
3. 注册证或批准证明文件格式模板。
使用技术：
1. 模板库模型
2. Django Storage
3. YAML/JSON 模板元数据
产生方法：
1. `select_word_template(template_id, target_output_type) -> WordTemplate`
2. `validate_template_applicability(template, workflow_type) -> TemplateValidationResult`
3. `resolve_template_file_path(template) -> Path`
对应 Skill：
1. `模板选择Skill`
### 5.3 节点三：模板字段映射加载
业务功能：
1. 加载模板字段和统一字段池字段的映射关系。
2. 校验模板占位符是否完整。
3. 标记必填字段、可选字段和人工复核字段。
映射示例：
```yaml
template_id: registration_application_form_v1
version: "2026-06-03"
mappings:
- placeholder: "{{ product_name }}"
field_key: product_name
required: true
- placeholder: "{{ intended_use }}"
field_key: intended_use
required: true
```
使用技术：
1. YAML
2. Pydantic
3. 模板占位符扫描
产生方法：
1. `load_template_field_mapping(template_id) -> TemplateFieldMapping`
2. `validate_mapping_against_template(template, mapping) -> MappingValidationResult`
3. `scan_template_placeholders(template_file) -> list[str]`
对应 Skill：
1. `模板字段映射加载Skill`
### 5.4 节点四：回填字段集构建
业务功能：
1. 从字段池读取映射字段。
2. 选择推荐值。
3. 过滤不可回填字段。
4. 生成待回填字段集。
使用技术：
1. Django ORM
2. 字段池数据
3. 映射规则
产生方法：
1. `build_fill_dataset(field_pool, mapping) -> FillDataset`
2. `resolve_field_value(field_key, field_pool) -> FillValue`
3. `collect_missing_fill_values(mapping, field_pool) -> list[MissingFillValue]`
对应 Skill：
1. `回填字段集构建Skill`
### 5.5 节点五：回填拦截检查
业务功能：
1. 检查字段是否存在冲突。
2. 检查字段是否待人工复核。
3. 检查风险报告是否存在高风险。
4. 判断是否允许生成正式版或草稿版。
拦截规则：
1. 高风险未处理：禁止生成正式版。
2. 字段冲突未处理：禁止自动正式回填。
3. 必填字段缺失：禁止正式版。
4. 允许生成草稿版时，输出文件必须标记“待复核草稿”。
使用技术：
1. 风险报告
2. 字段池冲突状态
3. 回填策略规则
产生方法：
1. `check_fill_blockers(fill_dataset, risk_report) -> FillBlockerResult`
2. `determine_export_mode(blockers, allow_draft) -> str`
3. `build_blocked_field_list(blockers) -> list[BlockedField]`
对应 Skill：
1. `回填拦截检查Skill`
### 5.6 节点六：Word 模板渲染
业务功能：
1. 打开 Word 模板。
2. 替换占位符。
3. 写入表格单元格。
4. 保留标题层级、表格、页眉页脚、盖章位和原始样式。
5. 输出新的 Word 文件。
使用技术：
1. `python-docx`
2. `docxtpl` 可选
3. Django Storage
4. 临时文件目录
产生方法：
1. `render_word_template(template_file, fill_dataset, export_mode) -> RenderedWordFile`
2. `replace_paragraph_placeholders(document, values) -> None`
3. `replace_table_placeholders(document, values) -> None`
4. `save_rendered_document(document, output_path) -> Path`
对应 Skill：
1. `Word模板渲染Skill`
### 5.7 节点七：导出版式校验
业务功能：
1. 校验输出文件是否存在。
2. 校验必填占位符是否已替换。
3. 校验是否仍残留模板占位符。
4. 校验基础版式元素是否存在。
5. 必要时渲染预览用于人工确认。
使用技术：
1. `python-docx`
2. 文档占位符扫描
3. 可选 LibreOffice 转 PDF
4. 可选 PDF 渲染检查
产生方法：
1. `check_export_layout(output_file, mapping) -> LayoutCheckResult`
2. `detect_unfilled_placeholders(output_file) -> list[str]`
3. `validate_required_sections(output_file) -> list[LayoutWarning]`
对应 Skill：
1. `导出版式校验Skill`
### 5.8 节点八：导出记录生成
业务功能：
1. 保存输出文件记录。
2. 生成下载地址。
3. 生成导出报告。
4. 写入审计。
使用技术：
1. Django ORM
2. Django Storage
3. JSONField
4. Audit 服务
产生方法：
1. `create_export_file_record(batch, output_file) -> ExportedDocument`
2. `build_download_url(export_file) -> str`
3. `build_word_export_report(context, result) -> RegistrationWordExportReport`
4. `record_word_export_audit(report, context) -> AuditLog`
对应 Skill：
1. `导出记录生成Skill`
## 6. Skill 清单
本步骤产生以下 Skill 设计文档：
1. [Word回填导出编排Skill](skill/Word回填导出编排Skill.md)
2. [模板选择Skill](skill/模板选择Skill.md)
3. [模板字段映射加载Skill](skill/模板字段映射加载Skill.md)
4. [回填字段集构建Skill](skill/回填字段集构建Skill.md)
5. [回填拦截检查Skill](skill/回填拦截检查Skill.md)
6. [Word模板渲染Skill](skill/Word模板渲染Skill.md)
7. [导出版式校验Skill](skill/导出版式校验Skill.md)
8. [导出记录生成Skill](skill/导出记录生成Skill.md)
## 7. 导出模式
| 模式 | 含义 |
|---|---|
| `formal` | 正式导出，字段无冲突且无高风险 |
| `draft` | 草稿导出，存在待复核项但允许预览 |
| `blocked` | 拦截导出，不生成文件 |
## 8. 页面展示
Word 回填导出页面建议展示：
1. 模板名称和版本。
2. 回填字段数量。
3. 已回填字段。
4. 被拦截字段。
5. 导出模式。
6. 版式校验结果。
7. Word 下载入口。
8. 审计入口。
## 9. 异常处理
1. 模板不存在：任务失败。
2. 模板字段映射缺失：任务失败。
3. 必填字段缺失：正式版导出拦截。
4. 字段冲突：正式版导出拦截。
5. 高风险未处理：正式版导出拦截。
6. Word 渲染失败：记录导出失败。
7. 版式校验失败：生成文件标记待复核。
## 10. 与后续步骤的接口
飞书通知读取：
1. 导出状态。
2. 下载链接。
3. 被拦截字段。
4. 待复核字段。
5. 责任角色。
## 11. 测试设计
### 11.1 单元测试
1. 模板选择正确。
2. 字段映射加载正确。
3. 必填字段缺失被拦截。
4. 冲突字段被拦截。
5. 占位符替换正确。
6. 残留占位符可识别。
### 11.2 服务层测试
1. 能基于字段池生成 Word 草稿。
2. 高风险存在时禁止正式导出。
3. 导出文件记录生成。
4. 导出报告写入审计。
### 11.3 页面测试
1. 页面展示导出状态。
2. 页面展示下载入口。
3. 页面展示拦截原因。
4. 页面展示版式校验结果。
## 12. V1 实现建议
V1 建议先完成以下最小闭环：
1. 维护一个注册申报表格或对照清单模板。
2. 支持字段占位符回填。
3. 支持冲突字段和高风险拦截。
4. 生成新的 `.docx` 文件。
5. 提供下载入口。
6. 写入审计。
增强阶段再补齐：
1. 多模板库管理。
2. PDF 归档件导出。
3. 高保真版式自动校验。
4. 模板版本审批。
5. 后台模板字段映射维护。

407
docs/详细设计/7.飞书通知.md Normal file
View File

@@ -0,0 +1,407 @@
# 7. 飞书通知详细设计
## 1. 设计目标
本步骤承接风险预警和 Word 回填导出结果，目标是在飞书群聊或应用会话中完成任务触发、结果摘要查看、责任人通知和 Web 详情跳转，让注册申报审核流程具备 Web 工作台以外的协同入口。
本步骤需要完成以下业务结果：
1. 支持飞书群聊机器人触发审核任务。
2. 支持在飞书内选择任务或查看任务摘要。
3. 根据风险项和章节点映射责任角色。
4. 根据责任角色解析飞书账号。
5. 生成飞书消息摘要和 @ 通知载荷。
6. 调用飞书 OpenAPI 或 MCP 工具发送消息。
7. 记录发送结果、失败原因和回传链接。
8. 写入审计留痕。
本步骤不执行具体审核规则，不改变风险结论，不直接修改字段池或导出文件。它只负责飞书入口和通知协作。
## 2. 所属模块与边界
### 2.1 Chat
`apps.chat` 提供 Web 详情页链接和任务执行结果页面，飞书消息中应回传 Web 详情入口。
### 2.2 Agent Core
`agent_core` 负责飞书通知编排、摘要生成、责任人映射和发送载荷构建。
本步骤建议产生以下中文 Skill：
1. `飞书通知编排Skill`
2. `飞书任务入口解析Skill`
3. `飞书责任人映射Skill`
4. `飞书消息摘要生成Skill`
5. `飞书消息发送Skill`
6. `飞书回执记录Skill`
### 2.3 MCP / OpenAPI
飞书能力通过两类方式接入：
1. 飞书机器人 / Channel SDK：作为群聊触发和消息回传入口。
2. 飞书 OpenAPI MCP：作为 Agent 调用飞书消息、文档、群聊和用户信息的工具层。
MCP 只作为外部工具接入层，不承载业务审核逻辑。
### 2.4 Audit
`apps.audit` 记录飞书触发来源、消息载荷、通知对象、发送状态和失败原因。
审计中必须保留：
1. `batch_id`
2. `scenario_id`
3. `trigger_source`
4. `feishu_chat_id`
5. `feishu_message_id`
6. `mentioned_user_ids`
7. `notification_payload`
8. `send_status`
9. `error_message`
## 3. 输入输出
### 3.1 输入
```json
{
"batch_id": 1001,
"scenario_id": "registration_risk_report",
"trigger_source": "feishu_group_bot",
"feishu_chat_id": "oc_demo_chat",
"feishu_message_id": "om_demo_message",
"notify_owner": true,
"include_web_link": true
}
```
### 3.2 输出
本步骤输出 `feishu_notification_report`：
```json
{
"report_type": "feishu_notification_report",
"batch_id": 1001,
"send_status": "sent",
"message_type": "interactive_card",
"mentioned_users": [
{
"owner_role": "注册资料负责人",
"feishu_user_id": "ou_demo_owner"
}
],
"web_detail_url": "http://localhost:8000/audit/1001/",
"receipt": {
"message_id": "om_demo_message",
"sent_at": "2026-06-03T10:30:00+08:00"
}
}
```
## 4. 主工作流
```text
飞书群聊或 Web 触发通知
-> 解析飞书触发上下文
-> 读取风险报告和导出报告
-> 解析责任角色和飞书账号
-> 生成飞书消息摘要
-> 构建消息卡片和 @ 通知
-> 调用飞书 OpenAPI / MCP 发送
-> 记录发送回执
-> 写入审计留痕
-> 返回发送结果
```
## 5. 节点详细设计
### 5.1 节点一：飞书任务入口解析
业务功能：
1. 解析飞书消息事件。
2. 识别任务指令。
3. 识别批次 ID 或项目上下文。
4. 将飞书触发请求映射到系统场景。
支持指令示例：
1. `检查资料完整性`
2. `生成风险报告`
3. `查看导出结果`
4. `通知责任人`
使用技术：
1. 飞书事件订阅
2. 群聊机器人消息
3. Django webhook view
4. 场景配置 YAML
产生方法：
1. `parse_feishu_event(event_payload) -> FeishuTriggerContext`
2. `resolve_scenario_from_command(text) -> str`
3. `resolve_batch_from_message(text, chat_context) -> int | None`
对应 Skill：
1. `飞书任务入口解析Skill`
### 5.2 节点二：通知上下文加载
业务功能：
1. 读取风险报告。
2. 读取 Word 导出报告。
3. 读取审计详情链接。
4. 读取任务状态。
使用技术：
1. Django ORM
2. JSONField
3. URL reverse
产生方法：
1. `load_notification_context(batch_id, scenario_id) -> NotificationContext`
2. `build_web_detail_url(report_or_audit) -> str`
3. `collect_notification_sources(context) -> list[dict]`
对应 Skill：
1. `飞书通知编排Skill`
### 5.3 节点三：责任人映射
业务功能：
1. 根据风险项、章节点和任务类型确定责任角色。
2. 根据责任角色查找飞书账号。
3. 支持后台或配置文件手动维护。
4. 对未配置账号的责任角色给出提示。
建议配置：
```yaml
owners:
CH1:
owner_role: 注册资料负责人
feishu_user_id: ou_demo_owner
field_conflict:
owner_role: 注册资料负责人
feishu_user_id: ou_demo_owner
missing_required_document:
owner_role: 注册申报负责人
feishu_user_id: ou_demo_registration_owner
```
使用技术：
1. YAML 配置
2. Django Admin 维护表
3. 飞书用户 ID
产生方法：
1. `resolve_owner_roles(risk_items) -> list[OwnerRole]`
2. `load_owner_mapping() -> OwnerMapping`
3. `resolve_feishu_user_ids(owner_roles, mapping) -> list[FeishuMentionTarget]`
对应 Skill：
1. `飞书责任人映射Skill`
### 5.4 节点四：飞书消息摘要生成
业务功能：
1. 生成风险摘要。
2. 生成高风险列表。
3. 生成导出结果摘要。
4. 生成 Web 详情链接。
5. 生成飞书交互卡片或纯文本消息。
消息内容：
1. 当前任务名称。
2. 批次名称。
3. 是否通过。
4. 最高风险等级。
5. 高风险数量。
6. 待复核数量。
7. 责任人 @。
8. Web 详情入口。
9. 导出文件链接。
使用技术：
1. 飞书互动卡片 JSON
2. 文本消息模板
3. 可选 LLM 摘要
产生方法：
1. `build_feishu_summary(context) -> FeishuSummary`
2. `build_interactive_card(summary, mentions) -> dict`
3. `build_text_message(summary, mentions) -> dict`
对应 Skill：
1. `飞书消息摘要生成Skill`
### 5.5 节点五：飞书消息发送
业务功能：
1. 调用飞书 OpenAPI 或 MCP 发送消息。
2. 支持群聊消息。
3. 支持 @ 指定责任人。
4. 捕获发送结果和失败原因。
使用技术：
1. 飞书 OpenAPI
2. 飞书机器人
3. MCP 工具封装
4. 请求重试
产生方法：
1. `send_feishu_message(chat_id, payload) -> FeishuSendResult`
2. `send_feishu_card(chat_id, card_payload) -> FeishuSendResult`
3. `retry_send_on_transient_error(request) -> FeishuSendResult`
对应 Skill：
1. `飞书消息发送Skill`
### 5.6 节点六：飞书回执记录
业务功能：
1. 保存发送状态。
2. 保存消息 ID。
3. 保存通知对象。
4. 保存失败原因。
5. 写入审计。
使用技术：
1. Django ORM
2. Audit 服务
3. JSONField
产生方法：
1. `record_feishu_receipt(result, context) -> FeishuNotificationRecord`
2. `build_feishu_audit_payload(record, context) -> dict`
3. `record_feishu_audit(payload) -> AuditLog`
对应 Skill：
1. `飞书回执记录Skill`
## 6. Skill 清单
本步骤产生以下 Skill 设计文档：
1. [飞书通知编排Skill](skill/飞书通知编排Skill.md)
2. [飞书任务入口解析Skill](skill/飞书任务入口解析Skill.md)
3. [飞书责任人映射Skill](skill/飞书责任人映射Skill.md)
4. [飞书消息摘要生成Skill](skill/飞书消息摘要生成Skill.md)
5. [飞书消息发送Skill](skill/飞书消息发送Skill.md)
6. [飞书回执记录Skill](skill/飞书回执记录Skill.md)
## 7. 消息类型设计
| 类型 | 使用场景 |
|---|---|
| `text` | 简单摘要和失败提示 |
| `interactive_card` | 风险报告摘要、按钮和详情链接 |
| `mention_text` | @ 责任人 |
## 8. 页面与飞书展示
飞书消息建议展示：
1. 任务名称。
2. 批次名称。
3. 最高风险等级。
4. 是否通过。
5. 高风险摘要。
6. 待人工复核事项。
7. 责任人 @。
8. Web 详情链接。
9. 导出文件链接。
## 9. 异常处理
1. 飞书事件验签失败：拒绝请求。
2. 无法识别任务指令：返回帮助提示。
3. 未找到批次：返回业务提示。
4. 责任人未配置：发送群消息但不 @。
5. 飞书 API 失败：记录失败回执，可重试。
6. Web 链接生成失败：消息中省略链接并记录警告。
## 10. 与全流程接口
本步骤读取：
1. `registration_risk_report`
2. `registration_word_export_report`
3. 审计详情链接
4. 责任人映射配置
本步骤输出：
1. `feishu_notification_report`
2. 飞书消息 ID
3. 通知状态
4. 审计记录
## 11. 测试设计
### 11.1 单元测试
1. 飞书事件解析。
2. 任务指令解析。
3. 责任人映射。
4. 消息摘要构建。
5. 发送 payload 构建。
### 11.2 服务层测试
1. 风险报告可生成飞书卡片。
2. 责任人可被 @。
3. 未配置责任人时仍能发送摘要。
4. API 失败时记录失败回执。
5. 审计记录包含飞书来源。
### 11.3 集成测试
1. 群聊机器人触发风险报告查看。
2. 群聊机器人发送责任人通知。
3. Web 链接可跳转到详情页。
## 12. V1 实现建议
V1 建议先完成以下最小闭环：
1. 支持飞书群聊机器人接收指令。
2. 支持发送风险报告摘要。
3. 支持责任人手动配置和 @。
4. 支持 Web 详情链接。
5. 支持发送回执和审计记录。
增强阶段再补齐：
1. 飞书应用会话菜单。
2. 文档评论区 @bot。
3. 多维表格同步。
4. 飞书文档写回。
5. 消息卡片交互按钮。

90
docs/详细设计/skill/Word回填导出编排Skill.md Normal file
View File

@@ -0,0 +1,90 @@
# Word回填导出编排Skill 设计
## 1. Skill 定位
`Word回填导出编排Skill` 是第六步工作流的总入口 Skill，负责组织模板选择、字段映射加载、回填字段集构建、回填拦截检查、Word 渲染、版式校验和导出记录生成。
英文实现标识建议使用 `WordFillExportOrchestrateSkill`。
## 2. 输入
```python
@dataclass
class WordFillExportOrchestrateInput:
batch_id: int
template_id: str
target_output_type: str
selected_field_keys: list[str] = field(default_factory=list)
allow_draft_when_blocked: bool = True
```
## 3. 输出
```python
@dataclass
class WordFillExportOrchestrateOutput:
report_type: str
batch_id: int
export_status: str
output_file: dict | None
filled_fields: list[dict]
blocked_fields: list[dict]
audit_id: int | None = None
```
## 4. 依赖 Skill
1. `模板选择Skill`
2. `模板字段映射加载Skill`
3. `回填字段集构建Skill`
4. `回填拦截检查Skill`
5. `Word模板渲染Skill`
6. `导出版式校验Skill`
7. `导出记录生成Skill`
## 5. 核心方法
### 5.1 `run(input) -> WordFillExportOrchestrateOutput`
主入口方法。
### 5.2 `load_export_context(input) -> WordExportContext`
加载字段池、风险报告和一致性报告。
### 5.3 `resolve_export_mode(blockers) -> str`
确认正式、草稿或拦截模式。
## 6. 技术实现
使用技术：
1. Tool Registry
2. Django ORM
3. Django Storage
4. dataclass/Pydantic
建议注册名：
```python
tool_registry.register(
name="word_fill_export_orchestrate",
handler=WordFillExportOrchestrateSkill().run,
)
```
## 7. 异常处理
1. 模板缺失：任务失败。
2. 字段池缺失：任务失败。
3. 正式导出被拦截：按配置生成草稿或直接返回拦截。
4. 渲染失败：写失败审计。
## 8. 测试要点
1. 能按顺序调用依赖 Skill。
2. 冲突字段导致正式导出拦截。
3. 草稿模式可生成文件。
4. 输出报告稳定。

67
docs/详细设计/skill/Word模板渲染Skill.md Normal file
View File

@@ -0,0 +1,67 @@
# Word模板渲染Skill 设计
## 1. Skill 定位
`Word模板渲染Skill` 负责将回填字段集写入 Word 模板，生成新的 `.docx` 文件。
英文实现标识建议使用 `WordTemplateRenderSkill`。
## 2. 输入
```python
@dataclass
class WordTemplateRenderInput:
template_file_path: Path
fill_dataset: dict
export_mode: str
output_dir: Path
```
## 3. 输出
```python
@dataclass
class WordTemplateRenderOutput:
output_file_path: Path
rendered_placeholders: list[str]
render_warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> WordTemplateRenderOutput`
主入口方法。
### 4.2 `replace_paragraph_placeholders(document, values) -> None`
替换段落占位符。
### 4.3 `replace_table_placeholders(document, values) -> None`
替换表格占位符。
### 4.4 `save_document(document, output_path) -> Path`
保存文档。
## 5. 技术实现
使用技术：
1. `python-docx`
2. 可选 `docxtpl`
3. Django Storage
## 6. 异常处理
1. 模板打不开：任务失败。
2. 占位符替换失败：记录警告。
3. 保存失败：任务失败。
## 7. 测试要点
1. 段落占位符可替换。
2. 表格占位符可替换。
3. 输出文件存在。

88
docs/详细设计/skill/一致性报告生成Skill.md Normal file
View File

@@ -0,0 +1,88 @@
# 一致性报告生成Skill 设计
## 1. Skill 定位
`一致性报告生成Skill` 负责将字段比对结果和混档风险组装成稳定的 `registration_consistency_report`，并生成页面展示、审计和飞书摘要载荷。
英文实现标识建议使用 `ConsistencyReportBuildSkill`。
## 2. 输入
```python
@dataclass
class ConsistencyReportBuildInput:
context: ConsistencyReviewContext
compare_results: list[FieldCompareResult]
mixed_package_warnings: list[dict]
```
## 3. 输出
```python
@dataclass
class ConsistencyReportBuildOutput:
report: dict
display_sections: list[dict]
audit_payload: dict
feishu_summary_payload: dict
```
## 4. 报告结构
报告必须包含：
1. `report_type`
2. `batch_id`
3. `field_rule_id`
4. `summary`
5. `consistent_fields`
6. `conflict_fields`
7. `manual_review_fields`
8. `mixed_package_warnings`
9. `suggestions`
## 5. 核心方法
### 5.1 `run(input) -> ConsistencyReportBuildOutput`
主入口方法。
### 5.2 `build_summary(compare_results, warnings) -> dict`
生成汇总。
### 5.3 `split_compare_results(compare_results) -> dict`
拆分一致、冲突、待复核字段。
### 5.4 `build_suggestions(conflicts, warnings) -> list[dict]`
生成处理建议。
### 5.5 `build_audit_payload(report, context) -> dict`
生成审计载荷。
## 6. 技术实现
使用技术：
1. dataclass/Pydantic
2. JSONField
3. Audit 服务
4. 页面展示 schema
## 7. 异常处理
1. 报告字段缺失：任务失败。
2. 没有可比对字段：输出空报告。
3. 飞书摘要构建失败：不影响 Web 报告。
4. 审计写入失败：记录系统警告。
## 8. 测试要点
1. 冲突字段进入 `conflict_fields`。
2. 混档风险进入 `mixed_package_warnings`。
3. 汇总数量正确。
4. 审计载荷包含审核范围。

103
docs/详细设计/skill/一致性核查编排Skill.md Normal file
View File

@@ -0,0 +1,103 @@
# 一致性核查编排Skill 设计
## 1. Skill 定位
`一致性核查编排Skill` 是第四步工作流的总入口 Skill，负责组织审核范围确认、强一致规则加载、字段分组、完全一致比对、混档风险识别、字段池状态回写和报告生成。
英文实现标识建议使用 `ConsistencyReviewOrchestrateSkill`。
## 2. 输入
```python
@dataclass
class ConsistencyReviewOrchestrateInput:
batch_id: int
scenario_id: str = "registration_consistency_review"
selected_document_ids: list[int] = field(default_factory=list)
field_rule_id: str = "ivd_strict_consistency_v1"
target_field_keys: list[str] = field(default_factory=list)
strict_mode: bool = True
```
## 3. 输出
```python
@dataclass
class ConsistencyReviewOrchestrateOutput:
report_type: str
batch_id: int
summary: dict
consistent_fields: list[dict]
conflict_fields: list[dict]
manual_review_fields: list[dict]
mixed_package_warnings: list[dict]
audit_id: int | None = None
```
## 4. 依赖 Skill
1. `审核范围确认Skill`
2. `强一致规则加载Skill`
3. `字段分组Skill`
4. `字段完全一致比对Skill`
5. `混档风险识别Skill`
6. `一致性报告生成Skill`
## 5. 核心方法
### 5.1 `run(input) -> ConsistencyReviewOrchestrateOutput`
主入口方法。
执行顺序：
1. 读取统一字段池。
2. 调用 `审核范围确认Skill`。
3. 调用 `强一致规则加载Skill`。
4. 调用 `字段分组Skill`。
5. 调用 `字段完全一致比对Skill`。
6. 调用 `混档风险识别Skill`。
7. 回写字段池冲突状态。
8. 调用 `一致性报告生成Skill`。
9. 写入审计。
### 5.2 `load_field_pool(batch_id) -> list[FieldPoolItem]`
读取字段池主表和候选值。
### 5.3 `update_field_pool_status(compare_results) -> FieldPoolUpdateResult`
回写一致、冲突、待复核状态。
## 6. 技术实现
使用技术：
1. Django ORM
2. Tool Registry
3. dataclass/Pydantic
4. Audit 服务
建议注册名：
```python
tool_registry.register(
name="consistency_review_orchestrate",
handler=ConsistencyReviewOrchestrateSkill().run,
)
```
## 7. 异常处理
1. 字段池不存在：任务失败并提示先执行字段抽取。
2. 审核范围为空：返回业务错误。
3. 规则缺失：任务失败并写审计。
4. 字段池回写失败：报告仍生成，但标记系统警告。
## 8. 测试要点
1. 能按顺序调用依赖 Skill。
2. 字段池缺失时返回清晰错误。
3. 冲突结果能回写字段池。
4. 输出报告 schema 稳定。

70
docs/详细设计/skill/准入判定Skill.md Normal file
View File

@@ -0,0 +1,70 @@
# 准入判定Skill 设计
## 1. Skill 定位
`准入判定Skill` 负责根据风险项、人工复核项和准入规则计算最终是否通过。
英文实现标识建议使用 `AdmissionDecisionSkill`。
## 2. 输入
```python
@dataclass
class AdmissionDecisionInput:
risk_items: list[RiskItem]
manual_review_items: list[dict]
admission_rules: dict
```
## 3. 输出
```python
@dataclass
class AdmissionDecisionOutput:
pass_status: str
highest_risk_level: str
decision_reason: str
score_detail: dict
```
## 4. 判定规则
1. 任一高风险：不通过。
2. 多个中风险：待整改后复核。
3. 只有低风险：条件通过。
4. 有人工复核项：待复核。
5. 无风险：通过。
## 5. 核心方法
### 5.1 `run(input) -> AdmissionDecisionOutput`
主入口方法。
### 5.2 `calculate_highest_level(risk_items) -> str`
计算最高风险等级。
### 5.3 `calculate_status(risk_items, manual_review_items, rules) -> str`
计算准入状态。
### 5.4 `build_decision_reason(status, risk_items) -> str`
生成判定理由。
## 6. 技术实现
使用技术：
1. 风险等级枚举
2. 准入规则 YAML
3. Python 规则判断
## 7. 测试要点
1. 高风险导致失败。
2. 中风险过多导致复核。
3. 低风险条件通过。
4. 无风险通过。

67
docs/详细设计/skill/前序报告汇总Skill.md Normal file
View File

@@ -0,0 +1,67 @@
# 前序报告汇总Skill 设计
## 1. Skill 定位
`前序报告汇总Skill` 负责读取当前批次已经生成的完整性、字段抽取和一致性核查报告，并统一转为风险评估上下文。
英文实现标识建议使用 `SourceReportCollectSkill`。
## 2. 输入
```python
@dataclass
class SourceReportCollectInput:
batch_id: int
include_reports: list[str]
```
## 3. 输出
```python
@dataclass
class SourceReportCollectOutput:
reports: dict[str, dict]
missing_reports: list[str]
stale_reports: list[str]
validation_warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> SourceReportCollectOutput`
主入口方法。
### 4.2 `load_report(batch_id, report_type) -> dict | None`
读取报告快照。
### 4.3 `validate_report_freshness(report) -> bool`
校验报告是否过期。
### 4.4 `build_report_bundle(reports) -> SourceReportBundle`
构建报告集合。
## 5. 技术实现
使用技术：
1. Django ORM
2. JSONField
3. 报告版本号
## 6. 异常处理
1. 报告不存在：加入 `missing_reports`。
2. 报告 schema 不完整：加入警告。
3. 报告过期：加入 `stale_reports`。
## 7. 测试要点
1. 能读取多个报告。
2. 缺失报告能识别。
3. 过期报告能识别。
4. 输出 bundle 稳定。

137
docs/详细设计/skill/压缩包解包Skill.md Normal file
View File

@@ -0,0 +1,137 @@
# 压缩包解包Skill 设计
## 1. Skill 定位
`压缩包解包Skill` 负责压缩包解包，是资料包导入链路中的文件展开能力。它需要支持 `zip`、`rar`、`7z`，并确保解包过程安全、可追踪、可复核。
本 Skill 的输出是“解包后的文件树”，不是文档审核结论。
英文实现标识建议使用 `ArchiveExtractionSkill`，用于 Python 类名和 Tool Registry 注册处理器。
## 2. 输入
```python
@dataclass
class ArchiveExtractionInput:
archive_path: Path
target_dir: Path
source_archive_name: str
max_file_count: int = 1000
max_total_size: int | None = None
```
## 3. 输出
```python
@dataclass
class ArchiveExtractionOutput:
status: str
archive_type: str
extracted_files: list[ExtractedFile]
skipped_items: list[SkippedArchiveItem]
warnings: list[dict]
```
`ExtractedFile` 字段：
1. `absolute_path`
2. `relative_path`
3. `file_size`
4. `source_archive_name`
5. `file_hash`
## 4. 支持格式与技术
| 格式 | 技术 |
|---|---|
| `zip` | Python 标准库 `zipfile` |
| `rar` | 纯 Python rar 解析依赖，优先选择不依赖系统命令的库 |
| `7z` | `py7zr` |
V1 可以先完成 `zip`，同时保留 `rar`、`7z` 的接口和失败提示。正式验收前需要补齐纯 Python 解包能力。
## 5. 核心方法
### 5.1 `run(input) -> ArchiveExtractionOutput`
主入口方法。
处理顺序：
1. 识别压缩包类型。
2. 打开压缩包。
3. 遍历成员文件。
4. 校验成员路径安全性。
5. 校验数量和大小限制。
6. 解包到批次隔离目录。
7. 生成解包结果。
### 5.2 `detect_archive_type(path) -> str`
根据扩展名和文件头识别压缩包类型。
返回：
1. `zip`
2. `rar`
3. `7z`
4. `unsupported`
### 5.3 `validate_member_path(member_name) -> str`
路径安全校验。
拒绝：
1. 绝对路径。
2. 包含 `..` 的路径。
3. Windows 盘符路径。
4. 空路径。
5. 控制字符。
### 5.4 `extract_zip(input) -> list[ExtractedFile]`
使用 `zipfile` 解包。
### 5.5 `extract_rar(input) -> list[ExtractedFile]`
使用纯 Python rar 依赖解包。
如果当前环境依赖未安装，返回 `unsupported_archive`，并提示需要安装对应依赖。
### 5.6 `extract_7z(input) -> list[ExtractedFile]`
使用 `py7zr` 解包。
### 5.7 `build_file_hash(path) -> str`
使用 `sha256` 生成文件指纹，用于重复文件识别。
## 6. 状态设计
| 状态 | 含义 |
|---|---|
| `extracted` | 解包成功 |
| `partial_extracted` | 部分成员解包失败 |
| `empty_archive` | 压缩包为空 |
| `encrypted_archive` | 加密压缩包 |
| `unsupported_archive` | 格式不支持 |
| `path_rejected` | 存在危险路径 |
| `extract_failed` | 解包失败 |
## 7. 异常处理
1. 加密压缩包：不尝试暴力解析，标记为待人工处理。
2. 路径穿越：拒绝危险成员并记录安全拦截。
3. 超大压缩包：超过配置限制时停止处理。
4. 成员数量过多：停止处理并提示资料包异常。
5. 文件名乱码：保留原始名称，展示层提示人工复核。
## 8. 测试要点
1. 普通 zip 解包成功。
2. 多层目录相对路径被保留。
3. `../evil.docx` 被拒绝。
4. 空压缩包返回 `empty_archive`。
5. 不支持格式返回 `unsupported_archive`。
6. 解包后文件哈希生成稳定。

62
docs/详细设计/skill/回填字段集构建Skill.md Normal file
View File

@@ -0,0 +1,62 @@
# 回填字段集构建Skill 设计
## 1. Skill 定位
`回填字段集构建Skill` 负责根据模板字段映射和统一字段池构建实际要写入 Word 模板的字段值集合。
英文实现标识建议使用 `FillDatasetBuildSkill`。
## 2. 输入
```python
@dataclass
class FillDatasetBuildInput:
field_pool_items: list[FieldPoolItem]
template_mappings: list[dict]
selected_field_keys: list[str] = field(default_factory=list)
```
## 3. 输出
```python
@dataclass
class FillDatasetBuildOutput:
fill_dataset: dict
missing_required_fields: list[dict]
manual_review_fields: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> FillDatasetBuildOutput`
主入口方法。
### 4.2 `resolve_field_value(mapping, field_pool) -> FillValue`
解析字段值。
### 4.3 `build_placeholder_values(mappings, field_pool) -> dict`
生成占位符和值。
## 5. 技术实现
使用技术：
1. 字段池数据
2. 模板映射
3. Python 字典构建
## 6. 异常处理
1. 必填字段缺失：进入缺失列表。
2. 字段待复核：进入待复核列表。
3. 字段不可回填：跳过。
## 7. 测试要点
1. 可回填字段进入 dataset。
2. 必填缺失可识别。
3. 待复核字段可识别。

70
docs/详细设计/skill/回填拦截检查Skill.md Normal file
View File

@@ -0,0 +1,70 @@
# 回填拦截检查Skill 设计
## 1. Skill 定位
`回填拦截检查Skill` 负责根据字段冲突、风险报告和必填字段缺失情况判断是否允许正式回填导出。
英文实现标识建议使用 `FillBlockerCheckSkill`。
## 2. 输入
```python
@dataclass
class FillBlockerCheckInput:
fill_dataset: dict
risk_report: dict
consistency_report: dict
missing_required_fields: list[dict]
allow_draft_when_blocked: bool
```
## 3. 输出
```python
@dataclass
class FillBlockerCheckOutput:
export_mode: str
blocked_fields: list[dict]
blockers: list[dict]
```
## 4. 拦截规则
1. 高风险未处理：拦截正式版。
2. 字段冲突：拦截正式版。
3. 必填字段缺失：拦截正式版。
4. 待人工复核：允许草稿，不允许正式版。
## 5. 核心方法
### 5.1 `run(input) -> FillBlockerCheckOutput`
主入口方法。
### 5.2 `detect_high_risk_blocker(risk_report) -> list[dict]`
检测高风险。
### 5.3 `detect_conflict_blocker(consistency_report) -> list[dict]`
检测冲突字段。
### 5.4 `resolve_export_mode(blockers, allow_draft) -> str`
确定导出模式。
## 6. 技术实现
使用技术：
1. 风险报告
2. 一致性报告
3. 本地规则
## 7. 测试要点
1. 高风险拦截正式导出。
2. 冲突字段拦截正式导出。
3. 草稿模式可用。
4. 无拦截时正式导出。

75
docs/详细设计/skill/字段Schema加载Skill.md Normal file
View File

@@ -0,0 +1,75 @@
# 字段Schema加载Skill 设计
## 1. Skill 定位
`字段Schema加载Skill` 负责加载注册申报字段 schema，提供字段定义、来源优先级、抽取方式、回填属性和一致性要求。
英文实现标识建议使用 `FieldSchemaLoadSkill`。
## 2. 输入
```python
@dataclass
class FieldSchemaLoadInput:
field_schema_id: str
target_field_keys: list[str] = field(default_factory=list)
```
## 3. 输出
```python
@dataclass
class FieldSchemaLoadOutput:
field_schema_id: str
version: str
fields: list[FieldDefinition]
source_priority: dict
validation_warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> FieldSchemaLoadOutput`
主入口方法。
### 4.2 `load_schema_file(field_schema_id) -> dict`
从 YAML 读取字段 schema。
### 4.3 `validate_field_schema(raw_schema) -> FieldSchemaValidationResult`
校验字段定义。
### 4.4 `select_target_fields(schema, target_field_keys) -> list[FieldDefinition]`
筛选目标字段。
## 5. 技术实现
使用技术：
1. `PyYAML`
2. Pydantic
3. Django cache
建议路径：
```text
configs/registration/fields/ivd_registration_fields_v1.yaml
```
## 6. 异常处理
1. schema 文件不存在：任务失败。
2. 字段定义缺少 `field_key`：校验失败。
3. 目标字段不存在：返回业务错误。
4. 来源优先级缺失：允许执行，但记录警告。
## 7. 测试要点
1. schema 加载成功。
2. 目标字段筛选正确。
3. 缺少必填字段时报错。
4. 来源优先级输出正确。

66
docs/详细设计/skill/字段分组Skill.md Normal file
View File

@@ -0,0 +1,66 @@
# 字段分组Skill 设计
## 1. Skill 定位
`字段分组Skill` 负责将统一字段池中的字段候选按字段编码和来源文档分组，形成可比对的数据单元。
英文实现标识建议使用 `FieldGroupSkill`。
## 2. 输入
```python
@dataclass
class FieldGroupInput:
field_pool_items: list[FieldPoolItem]
field_candidates: list[FieldCandidateRecord]
scope_documents: list[DocumentFact]
```
## 3. 输出
```python
@dataclass
class FieldGroupOutput:
compare_units: list[FieldCompareUnit]
single_source_fields: list[dict]
excluded_candidates: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> FieldGroupOutput`
主入口方法。
### 4.2 `group_by_field_key(candidates) -> dict`
按字段编码分组。
### 4.3 `filter_candidates_by_scope(candidates, scope_documents) -> list`
只保留审核范围内来源文档的候选。
### 4.4 `build_compare_unit(field_key, candidates) -> FieldCompareUnit`
构建字段比对单元。
## 5. 技术实现
使用技术：
1. Python 分组
2. 字段池候选记录
3. 文档范围过滤
## 6. 异常处理
1. 字段无候选：进入待复核。
2. 来源文档不在范围内：排除候选。
3. 单来源字段：标记 `single_source`。
## 7. 测试要点
1. 候选按字段分组正确。
2. 范围外候选被排除。
3. 单来源字段识别正确。

77
docs/详细设计/skill/字段完全一致比对Skill.md Normal file
View File

@@ -0,0 +1,77 @@
# 字段完全一致比对Skill 设计
## 1. Skill 定位
`字段完全一致比对Skill` 负责按强一致规则对同一字段的不同来源值执行完全一致比对。
英文实现标识建议使用 `ExactFieldCompareSkill`。
本 Skill 不做语义相似判断。
## 2. 输入
```python
@dataclass
class ExactFieldCompareInput:
compare_units: list[FieldCompareUnit]
rules: list[ConsistencyFieldRule]
```
## 3. 输出
```python
@dataclass
class ExactFieldCompareOutput:
compare_results: list[FieldCompareResult]
conflict_fields: list[dict]
consistent_fields: list[dict]
manual_review_fields: list[dict]
```
## 4. 比对规则
1. 标准值完全相等才算一致。
2. 空值不算一致证据。
3. 待复核来源不算通过证据。
4. 原始值明显差异但标准值相同，进入待复核。
## 5. 核心方法
### 5.1 `run(input) -> ExactFieldCompareOutput`
主入口方法。
### 5.2 `compare_exact(unit, rule) -> FieldCompareResult`
完全一致比对。
### 5.3 `build_conflict_result(unit, values, rule) -> FieldCompareResult`
构建冲突结果。
### 5.4 `build_consistent_result(unit, rule) -> FieldCompareResult`
构建一致结果。
## 6. 技术实现
使用技术：
1. Python 字符串比较
2. 字段标准化值
3. 风险规则
## 7. 异常处理
1. 无候选值：待人工复核。
2. 单来源：不判冲突。
3. 字段无规则：不检查。
4. 候选来源待复核：结果待复核。
## 8. 测试要点
1. 相同标准值判一致。
2. 不同标准值判冲突。
3. 单来源不判冲突。
4. 待复核来源进入人工复核。

89
docs/详细设计/skill/字段抽取报告生成Skill.md Normal file
View File

@@ -0,0 +1,89 @@
# 字段抽取报告生成Skill 设计
## 1. Skill 定位
`字段抽取报告生成Skill` 负责将字段池写入结果组装成稳定的 `registration_field_extraction_report`，并生成页面展示、审计和飞书摘要所需的数据结构。
英文实现标识建议使用 `FieldExtractionReportBuildSkill`。
## 2. 输入
```python
@dataclass
class FieldExtractionReportBuildInput:
context: FieldExtractionContext
field_pool_items: list[FieldPoolItem]
manual_review_fields: list[dict]
tool_calls: list[dict]
```
## 3. 输出
```python
@dataclass
class FieldExtractionReportBuildOutput:
report: dict
display_sections: list[dict]
audit_payload: dict
feishu_summary_payload: dict
```
## 4. 报告结构
报告必须包含：
1. `report_type`
2. `batch_id`
3. `field_schema_id`
4. `field_schema_version`
5. `summary`
6. `field_pool_items`
7. `manual_review_fields`
8. `evidence_refs`
9. `tool_calls`
## 5. 核心方法
### 5.1 `run(input) -> FieldExtractionReportBuildOutput`
主入口方法。
### 5.2 `build_summary(field_pool_items) -> dict`
汇总字段数量、已抽取数量、待复核数量和冲突候选数量。
### 5.3 `build_field_rows(field_pool_items) -> list[dict]`
生成字段池页面表格。
### 5.4 `build_audit_payload(report, context) -> dict`
生成审计载荷。
### 5.5 `build_feishu_summary_payload(report) -> dict`
生成飞书摘要载荷。
## 6. 技术实现
使用技术：
1. dataclass/Pydantic
2. JSONField
3. Audit 服务
4. 页面展示 schema
## 7. 异常处理
1. 字段池为空：输出空报告并提示无可用字段。
2. 报告字段缺失：任务失败。
3. 审计写入失败：报告仍返回，但记录系统警告。
4. 飞书摘要构建失败：不影响 Web 报告。
## 8. 测试要点
1. 输出 schema 稳定。
2. 字段池行展示完整。
3. 审计载荷包含字段 schema 版本。
4. 飞书摘要不包含敏感信息。

114
docs/详细设计/skill/字段抽取编排Skill.md Normal file
View File

@@ -0,0 +1,114 @@
# 字段抽取编排Skill 设计
## 1. Skill 定位
`字段抽取编排Skill` 是第三步工作流的总入口 Skill，负责组织字段抽取范围确认、字段 schema 加载、规则抽取、表格抽取、长文本归纳、字段标准化、统一字段池写入和报告生成。
英文实现标识建议使用 `FieldExtractionOrchestrateSkill`。
本 Skill 不直接完成每一种抽取细节，而是负责执行顺序和结果合并。
## 2. 输入
```python
@dataclass
class FieldExtractionOrchestrateInput:
batch_id: int
scenario_id: str = "registration_field_extraction"
field_schema_id: str = "ivd_registration_fields_v1"
selected_document_ids: list[int] = field(default_factory=list)
target_field_keys: list[str] = field(default_factory=list)
enable_llm_fallback: bool = True
enable_rag_context: bool = True
```
## 3. 输出
```python
@dataclass
class FieldExtractionOrchestrateOutput:
report_type: str
batch_id: int
field_schema_id: str
summary: dict
field_pool_items: list[dict]
manual_review_fields: list[dict]
evidence_refs: list[dict]
audit_id: int | None = None
```
## 4. 依赖 Skill
1. `字段抽取范围确认Skill`
2. `字段Schema加载Skill`
3. `规则字段抽取Skill`
4. `表格字段抽取Skill`
5. `长文本字段归纳Skill`
6. `字段标准化Skill`
7. `统一字段池写入Skill`
8. `字段抽取报告生成Skill`
## 5. 核心方法
### 5.1 `run(input) -> FieldExtractionOrchestrateOutput`
主入口方法。
执行顺序：
1. 加载执行上下文。
2. 调用 `字段抽取范围确认Skill`。
3. 调用 `字段Schema加载Skill`。
4. 调用 `规则字段抽取Skill`。
5. 调用 `表格字段抽取Skill`。
6. 按需调用 `长文本字段归纳Skill`。
7. 调用 `字段标准化Skill`。
8. 调用 `统一字段池写入Skill`。
9. 调用 `字段抽取报告生成Skill`。
10. 写入审计记录。
### 5.2 `load_execution_context(input) -> FieldExtractionContext`
加载批次、文档、完整性检查报告和已有字段池状态。
### 5.3 `merge_field_candidates(*candidate_groups) -> list[FieldCandidate]`
合并规则抽取、表格抽取和长文本归纳结果。
### 5.4 `filter_target_fields(schema, target_field_keys) -> list[FieldDefinition]`
筛选本次需要抽取的字段。
## 6. 技术实现
使用技术：
1. Python dataclass 或 Pydantic
2. Tool Registry
3. LLM Provider
4. Django 服务层
5. Audit 服务
建议注册名：
```python
tool_registry.register(
name="field_extraction_orchestrate",
handler=FieldExtractionOrchestrateSkill().run,
)
```
## 7. 异常处理
1. 无可抽取文档：返回业务提示。
2. 字段 schema 不存在：任务失败并写审计。
3. LLM 不可用：跳过 LLM，保留规则和表格结果。
4. 所有抽取方式均失败：返回待人工复核报告。
## 8. 测试要点
1. 能按顺序调用依赖 Skill。
2. LLM 关闭时仍可执行规则抽取。
3. 无文档时返回清晰错误。
4. 输出报告结构稳定。

79
docs/详细设计/skill/字段抽取范围确认Skill.md Normal file
View File

@@ -0,0 +1,79 @@
# 字段抽取范围确认Skill 设计
## 1. Skill 定位
`字段抽取范围确认Skill` 负责确定本次字段抽取使用哪些文档，以及每个目标字段优先从哪些文档角色中抽取。
英文实现标识建议使用 `FieldExtractionScopeResolveSkill`。
## 2. 输入
```python
@dataclass
class FieldExtractionScopeResolveInput:
documents: list[DocumentFact]
selected_document_ids: list[int]
target_field_keys: list[str]
field_source_priority: dict
```
## 3. 输出
```python
@dataclass
class FieldExtractionScopeResolveOutput:
extractable_documents: list[DocumentFact]
excluded_documents: list[dict]
field_document_plan: dict[str, list[DocumentFact]]
warnings: list[dict]
```
## 4. 文档筛选规则
参与抽取的文档必须满足：
1. `source_role = submission`
2. 文档处理状态可用。
3. 文档存在文本或表格结构。
4. 文档角色属于字段来源配置。
排除：
1. 法规依据资料。
2. 不支持文件。
3. 解析失败且无可用文本。
4. 用户未选择且不在默认来源范围内的文档。
## 5. 核心方法
### 5.1 `run(input) -> FieldExtractionScopeResolveOutput`
主入口方法。
### 5.2 `filter_extractable_documents(documents) -> list[DocumentFact]`
筛选可抽取文档。
### 5.3 `build_field_document_plan(fields, documents, priority) -> dict`
为每个字段构建候选文档顺序。
### 5.4 `collect_scope_warnings(documents) -> list[dict]`
收集待复核、解析失败、文本缺失等警告。
## 6. 技术实现
使用技术：
1. 文档角色枚举
2. YAML 来源优先级
3. Python 排序规则
## 7. 测试要点
1. 法规资料被排除。
2. 申请表、说明书、产品列表被纳入。
3. 用户选择文档时只使用选中范围。
4. 待复核文档会降低抽取可信度。

83
docs/详细设计/skill/字段标准化Skill.md Normal file
View File

@@ -0,0 +1,83 @@
# 字段标准化Skill 设计
## 1. Skill 定位
`字段标准化Skill` 负责对字段候选值进行清洗、标准化、置信度计算和冲突候选标记。
英文实现标识建议使用 `FieldNormalizeSkill`。
## 2. 输入
```python
@dataclass
class FieldNormalizeInput:
candidates: list[FieldCandidate]
field_definitions: list[FieldDefinition]
source_priority: dict
```
## 3. 输出
```python
@dataclass
class FieldNormalizeOutput:
normalized_candidates: list[NormalizedFieldCandidate]
conflict_candidates: list[dict]
manual_review_candidates: list[dict]
```
## 4. 标准化规则
1. 去除首尾空白。
2. 合并连续空白。
3. 全角半角标准化。
4. 中文标点标准化。
5. 日期格式标准化。
6. 单位格式标准化。
7. 空值和异常长值标记待复核。
## 5. 核心方法
### 5.1 `run(input) -> FieldNormalizeOutput`
主入口方法。
### 5.2 `normalize_text_value(value) -> str`
文本清洗。
### 5.3 `normalize_date_value(value) -> str`
日期标准化。
### 5.4 `calculate_confidence(candidate, field_definition) -> str`
计算置信度。
### 5.5 `detect_conflict_candidates(candidates) -> list[dict]`
检测同字段多候选值差异。
## 6. 技术实现
使用技术：
1. Python 字符串处理
2. 正则表达式
3. 日期解析
4. 字段类型规则
## 7. 异常处理
1. 值为空：标记待复核。
2. 值过长：标记待复核。
3. 日期无法解析：保留原值并标记低可信。
4. 多候选不一致：标记 `conflict_candidate`。
## 8. 测试要点
1. 空白和标点标准化正确。
2. 日期标准化正确。
3. 多候选冲突可识别。
4. 低可信候选进入待复核。

115
docs/详细设计/skill/完整性报告生成Skill.md Normal file
View File

@@ -0,0 +1,115 @@
# 完整性报告生成Skill 设计
## 1. Skill 定位
`完整性报告生成Skill` 负责把完整性检查链路中的规则判定结果、风险映射结果和法规证据组装成稳定的 `registration_completeness_report`。
英文实现标识建议使用 `CompletenessReportBuildSkill`。
本 Skill 不重新判定缺失，不重新检索证据，只负责报告结构、展示摘要和审计载荷生成。
## 2. 输入
```python
@dataclass
class CompletenessReportBuildInput:
execution_context: CompletenessExecutionContext
item_results: list[CompletenessItemResult]
evidence_refs: list[EvidenceRef]
pass_status: str
highest_risk_level: str
```
## 3. 输出
```python
@dataclass
class CompletenessReportBuildOutput:
report: dict
display_sections: list[dict]
audit_payload: dict
feishu_summary_payload: dict
```
## 4. 报告结构
报告必须包含：
1. `report_type`
2. `batch_id`
3. `workflow_type`
4. `rule_package_id`
5. `rule_version`
6. `chapter_scope`
7. `summary`
8. `matched_items`
9. `missing_items`
10. `misplaced_items`
11. `manual_review_items`
12. `evidence_refs`
13. `suggestions`
## 5. 核心方法
### 5.1 `run(input) -> CompletenessReportBuildOutput`
主入口方法。
### 5.2 `build_summary(item_results) -> dict`
汇总：
1. 要求项数量。
2. 已提供数量。
3. 缺失数量。
4. 疑似提供数量。
5. 错放数量。
6. 待复核数量。
7. 最高风险等级。
8. 是否通过。
### 5.3 `split_item_results(item_results) -> dict`
按状态拆分明细。
### 5.4 `attach_evidence(item_results, evidence_refs) -> list[dict]`
把法规证据挂到对应要求项。
### 5.5 `build_display_sections(report) -> list[dict]`
生成页面展示区块。
### 5.6 `build_audit_payload(report, context) -> dict`
生成审计载荷。
### 5.7 `build_feishu_summary_payload(report) -> dict`
生成飞书摘要载荷，供后续飞书通知步骤复用。
## 6. 技术实现
使用技术：
1. Pydantic/dataclass
2. JSONField
3. Django Audit 服务层
4. 结构化消息模板
## 7. 异常处理
1. 报告字段缺失：构建失败并写入失败审计。
2. 证据为空：正常输出，标记证据缺失。
3. 明细为空：输出空检查结果。
4. 风险等级缺失：按 `low` 处理，并记录规则警告。
## 8. 测试要点
1. 输出 schema 字段稳定。
2. 缺失项进入 `missing_items`。
3. 错放项进入 `misplaced_items`。
4. 待复核项进入 `manual_review_items`。
5. 审计载荷包含规则版本和输入范围。
6. 飞书摘要载荷不包含敏感信息。

77
docs/详细设计/skill/审核范围确认Skill.md Normal file
View File

@@ -0,0 +1,77 @@
# 审核范围确认Skill 设计
## 1. Skill 定位
`审核范围确认Skill` 负责确认本次一致性核查的文档范围，避免把不同项目、不同产品或法规依据资料混入同一轮比对。
英文实现标识建议使用 `ReviewScopeResolveSkill`。
## 2. 输入
```python
@dataclass
class ReviewScopeResolveInput:
batch_id: int
documents: list[DocumentFact]
selected_document_ids: list[int] = field(default_factory=list)
```
## 3. 输出
```python
@dataclass
class ReviewScopeResolveOutput:
scope_documents: list[DocumentFact]
excluded_documents: list[dict]
scope_warnings: list[dict]
scope_status: str
```
## 4. 范围规则
1. 必须同一批次。
2. 必须是业务申报资料。
3. 法规资料排除。
4. 处理失败资料排除。
5. 待人工复核资料保留但标记警告。
6. 用户选中范围优先。
## 5. 核心方法
### 5.1 `run(input) -> ReviewScopeResolveOutput`
主入口方法。
### 5.2 `filter_by_selected_documents(documents, ids) -> list[DocumentFact]`
根据用户选择过滤文档。
### 5.3 `exclude_non_submission_documents(documents) -> list[dict]`
排除法规资料和非业务资料。
### 5.4 `build_scope_warnings(documents) -> list[dict]`
生成范围警告。
## 6. 技术实现
使用技术：
1. 文档主数据
2. Django ORM
3. 资料来源角色枚举
## 7. 异常处理
1. 范围为空：任务不可执行。
2. 只有单个文档：允许执行，但只能输出单来源结果。
3. 全部文档待复核：输出低可信警告。
## 8. 测试要点
1. 选中文档范围生效。
2. 法规资料被排除。
3. 待复核文档输出警告。
4. 空范围返回错误。

65
docs/详细设计/skill/导出版式校验Skill.md Normal file
View File

@@ -0,0 +1,65 @@
# 导出版式校验Skill 设计
## 1. Skill 定位
`导出版式校验Skill` 负责检查回填后的 Word 文件是否仍有未替换占位符、必填字段是否落位、基础版式是否完整。
英文实现标识建议使用 `ExportLayoutCheckSkill`。
## 2. 输入
```python
@dataclass
class ExportLayoutCheckInput:
output_file_path: Path
template_mappings: list[dict]
```
## 3. 输出
```python
@dataclass
class ExportLayoutCheckOutput:
layout_check_status: str
unfilled_placeholders: list[str]
layout_warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> ExportLayoutCheckOutput`
主入口方法。
### 4.2 `detect_unfilled_placeholders(file) -> list[str]`
检查残留占位符。
### 4.3 `validate_required_fields(file, mappings) -> list[dict]`
校验必填字段。
### 4.4 `validate_basic_layout(file) -> list[dict]`
校验基础版式元素。
## 5. 技术实现
使用技术：
1. `python-docx`
2. 可选 LibreOffice 转 PDF
3. 占位符扫描规则
## 6. 异常处理
1. 文件不存在：校验失败。
2. 残留占位符：标记待复核。
3. 版式元素缺失：标记警告。
## 7. 测试要点
1. 残留占位符可识别。
2. 必填字段缺失可识别。
3. 正常文档通过校验。

75
docs/详细设计/skill/导出记录生成Skill.md Normal file
View File

@@ -0,0 +1,75 @@
# 导出记录生成Skill 设计
## 1. Skill 定位
`导出记录生成Skill` 负责保存导出文件元数据、生成下载入口、构建导出报告并写入审计。
英文实现标识建议使用 `ExportRecordBuildSkill`。
## 2. 输入
```python
@dataclass
class ExportRecordBuildInput:
batch_id: int
output_file_path: Path | None
export_mode: str
layout_check_result: dict
filled_fields: list[dict]
blocked_fields: list[dict]
```
## 3. 输出
```python
@dataclass
class ExportRecordBuildOutput:
report: dict
output_file: dict | None
audit_payload: dict
```
## 4. 核心方法
### 4.1 `run(input) -> ExportRecordBuildOutput`
主入口方法。
### 4.2 `create_export_file_record(file_path) -> ExportedDocument`
创建导出文件记录。
### 4.3 `build_download_url(export_file) -> str`
生成下载 URL。
### 4.4 `build_report(input, output_file) -> dict`
生成导出报告。
### 4.5 `build_audit_payload(report) -> dict`
生成审计载荷。
## 5. 技术实现
使用技术：
1. Django ORM
2. Django Storage
3. JSONField
4. Audit 服务
## 6. 异常处理
1. 文件不存在：只生成拦截报告。
2. 下载链接生成失败：报告标记异常。
3. 审计失败：记录系统警告。
## 7. 测试要点
1. 文件记录创建成功。
2. 下载链接生成成功。
3. 拦截模式不创建文件。
4. 审计载荷完整。

74
docs/详细设计/skill/强一致规则加载Skill.md Normal file
View File

@@ -0,0 +1,74 @@
# 强一致规则加载Skill 设计
## 1. Skill 定位
`强一致规则加载Skill` 负责加载字段一致性核查规则，定义哪些字段必须完全一致、如何比对、冲突风险等级和是否参与回填拦截。
英文实现标识建议使用 `StrictConsistencyRuleLoadSkill`。
## 2. 输入
```python
@dataclass
class StrictConsistencyRuleLoadInput:
field_rule_id: str
target_field_keys: list[str] = field(default_factory=list)
strict_mode: bool = True
```
## 3. 输出
```python
@dataclass
class StrictConsistencyRuleLoadOutput:
field_rule_id: str
version: str
rules: list[ConsistencyFieldRule]
validation_warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> StrictConsistencyRuleLoadOutput`
主入口方法。
### 4.2 `load_rule_file(field_rule_id) -> dict`
读取 YAML 规则。
### 4.3 `validate_rules(raw_rules) -> RuleValidationResult`
校验规则字段。
### 4.4 `select_target_rules(rules, target_field_keys) -> list[ConsistencyFieldRule]`
筛选本次目标字段规则。
## 5. 技术实现
使用技术：
1. YAML
2. Pydantic
3. Django cache
建议路径：
```text
configs/registration/consistency/ivd_strict_consistency_v1.yaml
```
## 6. 异常处理
1. 规则文件不存在：任务失败。
2. 目标字段无规则：标记不检查。
3. 风险等级缺失：默认中风险并记录警告。
## 7. 测试要点
1. 规则加载成功。
2. 目标字段筛选正确。
3. 缺少规则时报错。
4. `strict_mode` 生效。

71
docs/详细设计/skill/整改建议生成Skill.md Normal file
View File

@@ -0,0 +1,71 @@
# 整改建议生成Skill 设计
## 1. Skill 定位
`整改建议生成Skill` 负责根据风险项生成处理建议、整改优先级和责任角色。
英文实现标识建议使用 `RectificationSuggestionBuildSkill`。
## 2. 输入
```python
@dataclass
class RectificationSuggestionBuildInput:
risk_items: list[RiskItem]
suggestion_templates: dict
owner_role_mapping: dict
enable_llm_summary: bool = True
```
## 3. 输出
```python
@dataclass
class RectificationSuggestionBuildOutput:
suggestions: list[dict]
owner_notifications: list[dict]
summary_text: str
```
## 4. 核心方法
### 4.1 `run(input) -> RectificationSuggestionBuildOutput`
主入口方法。
### 4.2 `build_suggestion(risk_item) -> dict`
生成单项建议。
### 4.3 `resolve_owner_role(risk_item) -> str`
映射责任角色。
### 4.4 `sort_by_priority(suggestions) -> list[dict]`
按风险等级和业务优先级排序。
### 4.5 `build_summary_text(suggestions) -> str`
生成摘要，可选使用 LLM Provider。
## 5. 技术实现
使用技术：
1. 建议模板
2. 责任角色映射
3. 可选 LLM Provider
## 6. 异常处理
1. 模板缺失：使用默认建议。
2. 责任角色缺失：使用默认负责人。
3. LLM 不可用：使用本地摘要。
## 7. 测试要点
1. 高风险建议优先。
2. 责任角色映射正确。
3. LLM 不可用时本地摘要可用。

126
docs/详细设计/skill/文档页数统计Skill.md Normal file
View File

@@ -0,0 +1,126 @@
# 文档页数统计Skill 设计
## 1. Skill 定位
`文档页数统计Skill` 负责为注册申报资料文件生成页数统计结果。页数是题面明确要求的关键指标，因此本 Skill 必须把页数、统计方法和可信度分开记录。
本 Skill 不负责文档正文抽取，不负责 OCR，不负责合规判断。
英文实现标识建议使用 `DocumentPageCountSkill`，用于 Python 类名和 Tool Registry 注册处理器。
## 2. 输入
```python
@dataclass
class DocumentPageCountInput:
document_id: int
file_path: Path
file_type: str
options: dict = field(default_factory=dict)
```
## 3. 输出
```python
@dataclass
class PageCountResult:
document_id: int
page_count: int | None
method: str
confidence: str
status: str
message: str = ""
```
## 4. 页数统计策略
| 文件类型 | 策略 | 可信度 |
|---|---|---|
| `pdf` | 使用 `pypdf` 或 `PyMuPDF` 读取页数 | `exact` |
| `docx` | 优先读取 Word 统计信息，必要时转换 PDF 后统计 | `exact` |
| `doc` | 尝试转换后统计，失败则待复核 | `manual_review_required` |
| `txt` | 页数不适用 | `not_applicable` |
| `md` | 页数不适用 | `not_applicable` |
DOCX 是 V1 验收重点，不能用字数、段落数或估算分页代替精确页数。
## 5. 核心方法
### 5.1 `run(input) -> PageCountResult`
根据文件类型路由到具体统计方法。
### 5.2 `count_pdf_pages(path) -> PageCountResult`
推荐使用 `pypdf` 或 `PyMuPDF`。
失败处理：
1. 文件损坏：`failed`
2. 加密 PDF：`manual_review_required`
3. 无法读取：`failed`
### 5.3 `count_docx_pages(path) -> PageCountResult`
DOCX 精确页数建议采用两级策略：
1. 读取文档内部统计属性中的页数。
2. 若统计属性不可用，使用 LibreOffice headless 转 PDF，再统计 PDF 页数。
如果两级策略均失败，输出 `manual_review_required`，并在页面突出显示。
### 5.4 `count_doc_pages(path) -> PageCountResult`
DOC 文件首版策略：
1. 尝试用兼容转换工具转 PDF。
2. 转换成功后统计 PDF 页数。
3. 转换失败则标记待人工复核。
### 5.5 `count_text_pages(path) -> PageCountResult`
TXT/MD 首版不做页数强制验收。
返回：
1. `page_count = None`
2. `method = "not_applicable"`
3. `confidence = "not_applicable"`
## 6. 技术实现
建议依赖：
1. `pypdf`
2. `PyMuPDF`
3. `python-docx`
4. LibreOffice headless，可作为增强能力
如果 V1 Docker 环境暂不内置 LibreOffice，应在配置中显式标注 `DOCX_PAGE_COUNT_STRATEGY`，并保证演示样本能通过已实现策略得到精确页数。
## 7. 状态设计
| 状态 | 含义 |
|---|---|
| `success` | 页数统计成功 |
| `not_applicable` | 文本类文件不适用 |
| `manual_review_required` | 需要人工复核 |
| `failed` | 统计失败 |
## 8. 落库字段
建议写入 `RegistrationDocument`：
1. `page_count`
2. `page_count_method`
3. `page_count_confidence`
4. `page_count_status`
5. `processing_message`
## 9. 测试要点
1. PDF 返回精确页数。
2. DOCX 返回精确页数。
3. DOC 无法统计时标记待人工复核。
4. TXT/MD 返回不适用。
5. 损坏文件返回失败状态。

67
docs/详细设计/skill/模板字段映射加载Skill.md Normal file
View File

@@ -0,0 +1,67 @@
# 模板字段映射加载Skill 设计
## 1. Skill 定位
`模板字段映射加载Skill` 负责加载 Word 模板占位符与统一字段池字段之间的映射关系。
英文实现标识建议使用 `TemplateFieldMappingLoadSkill`。
## 2. 输入
```python
@dataclass
class TemplateFieldMappingLoadInput:
template_id: str
template_file_path: Path
```
## 3. 输出
```python
@dataclass
class TemplateFieldMappingLoadOutput:
template_id: str
mapping_version: str
mappings: list[dict]
missing_placeholders: list[str]
extra_placeholders: list[str]
```
## 4. 核心方法
### 4.1 `run(input) -> TemplateFieldMappingLoadOutput`
主入口方法。
### 4.2 `load_mapping(template_id) -> dict`
读取映射规则。
### 4.3 `scan_placeholders(template_file) -> list[str]`
扫描模板占位符。
### 4.4 `validate_mapping(mapping, placeholders) -> MappingValidationResult`
校验映射完整性。
## 5. 技术实现
使用技术：
1. YAML
2. `python-docx`
3. Pydantic
## 6. 异常处理
1. 映射不存在：任务失败。
2. 必填占位符缺失：任务失败。
3. 模板存在未映射占位符：标记警告。
## 7. 测试要点
1. 映射加载成功。
2. 模板占位符能扫描。
3. 缺失必填映射时报错。

65
docs/详细设计/skill/模板选择Skill.md Normal file
View File

@@ -0,0 +1,65 @@
# 模板选择Skill 设计
## 1. Skill 定位
`模板选择Skill` 负责根据目标输出类型选择可用 Word 模板，并校验模板适用流程和版本状态。
英文实现标识建议使用 `WordTemplateSelectSkill`。
## 2. 输入
```python
@dataclass
class WordTemplateSelectInput:
template_id: str
target_output_type: str
workflow_type: str = "registration"
```
## 3. 输出
```python
@dataclass
class WordTemplateSelectOutput:
template_id: str
template_version: str
template_file_path: Path
template_type: str
validation_warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> WordTemplateSelectOutput`
主入口方法。
### 4.2 `load_template(template_id) -> WordTemplate`
读取模板记录。
### 4.3 `validate_template(template, workflow_type) -> TemplateValidationResult`
校验模板适用性。
## 5. 技术实现
使用技术：
1. Django ORM
2. Django Storage
3. 模板元数据 YAML
## 6. 异常处理
1. 模板不存在：任务失败。
2. 模板文件丢失：任务失败。
3. 模板未启用：任务失败。
4. 流程不匹配：任务失败。
## 7. 测试要点
1. 能选择启用模板。
2. 禁用模板不可用。
3. 流程不匹配时报错。

136
docs/详细设计/skill/法规完整性检查Skill.md Normal file
View File

@@ -0,0 +1,136 @@
# 法规完整性检查Skill 设计
## 1. Skill 定位
`法规完整性检查Skill` 是第二步工作流的总编排 Skill，负责根据资料包目录汇总结果、法规流程类型和本地规则包，组织完整性检查链路并输出结构化完整性报告。
英文实现标识建议使用 `RegulationCompletenessCheckSkill`，用于 Python 类名和 Tool Registry 注册处理器。
本 Skill 不直接解析原始文件，不负责字段抽取，不负责综合风险报告。它消费第一步产生的文档事实。
## 2. 输入
```python
@dataclass
class RegulationCompletenessCheckInput:
batch_id: int
scenario_id: str = "registration_completeness_check"
workflow_type: str = "registration"
rule_package_id: str = "nmpa_ivd_registration_v1"
chapter_scope: list[str] = field(default_factory=list)
selected_document_ids: list[int] = field(default_factory=list)
enable_rag_evidence: bool = True
```
## 3. 输出
```python
@dataclass
class RegulationCompletenessCheckOutput:
report_type: str
batch_id: int
rule_package_id: str
rule_version: str
summary: dict
matched_items: list[dict]
missing_items: list[dict]
misplaced_items: list[dict]
manual_review_items: list[dict]
evidence_refs: list[dict]
audit_id: int | None = None
```
## 4. 依赖 Skill
1. `法规流程识别Skill`
2. `法规规则包加载Skill`
3. `资料要求匹配Skill`
4. `缺失错放判定Skill`
5. `法规证据检索Skill`
6. `完整性报告生成Skill`
## 5. 核心方法
### 5.1 `run(input) -> RegulationCompletenessCheckOutput`
主入口方法。
执行顺序：
1. 读取资料包目录汇总。
2. 调用 `法规流程识别Skill`。
3. 调用 `法规规则包加载Skill`。
4. 按章节范围展开法规要求项。
5. 调用 `资料要求匹配Skill`。
6. 调用 `缺失错放判定Skill`。
7. 按需调用 `法规证据检索Skill`。
8. 调用 `完整性报告生成Skill`。
9. 写入审计记录。
10. 返回完整性报告。
### 5.2 `load_execution_context(input) -> CompletenessExecutionContext`
加载执行上下文。
包含：
1. 批次信息。
2. 目录汇总报告。
3. 选中文档范围。
4. 场景配置。
5. 用户输入参数。
### 5.3 `select_document_facts(context) -> list[DocumentFact]`
从目录汇总中筛选参与完整性检查的文档。
如果 `selected_document_ids` 为空，则使用当前批次所有业务申报资料。
### 5.4 `build_requirement_scope(rule_package, chapter_scope) -> list[RequirementItem]`
根据章节点范围展开法规要求项。
V1 默认：
1. 有 `chapter_scope` 时按范围执行。
2. 无 `chapter_scope` 时优先执行 `CH1`。
3. 后续支持全六章。
## 6. 技术实现
使用技术：
1. Python dataclass 或 Pydantic
2. Tool Registry
3. Django 服务层调用
4. JSONField 报告快照
5. Audit 服务
建议注册名：
```python
tool_registry.register(
name="regulation_completeness_check",
handler=RegulationCompletenessCheckSkill().run,
)
```
## 7. 异常处理
| 异常 | 处理 |
|---|---|
| 批次不存在 | 返回业务错误并写失败审计 |
| 目录汇总不存在 | 提示先执行资料包导入与目录汇总 |
| 规则包不存在 | 返回任务不可执行 |
| 流程不支持 | 返回流程配置错误 |
| RAG 不可用 | 保留规则判断，证据标记不可用 |
| 所选文档为空 | 返回空范围报告 |
## 8. 测试要点
1. 能基于目录汇总生成完整性报告。
2. 能调用依赖 Skill 并合并结果。
3. 规则包缺失时写入失败审计。
4. RAG 失败不阻断主链路。
5. 输出 schema 稳定。

90
docs/详细设计/skill/法规流程识别Skill.md Normal file
View File

@@ -0,0 +1,90 @@
# 法规流程识别Skill 设计
## 1. Skill 定位
`法规流程识别Skill` 负责确认当前完整性检查适用哪一类法规流程，避免把注册申报、变更备案、变更注册和延续注册混用。
英文实现标识建议使用 `RegulationWorkflowResolveSkill`。
V1 默认只执行 `registration`，但设计上保留扩展位。
## 2. 输入
```python
@dataclass
class RegulationWorkflowResolveInput:
batch_workflow_type: str | None
scenario_workflow_type: str | None
user_workflow_type: str | None
rule_package_supported_workflows: list[str]
```
## 3. 输出
```python
@dataclass
class RegulationWorkflowResolveOutput:
workflow_type: str
confidence: str
source: str
supported: bool
warnings: list[dict]
```
## 4. 识别优先级
1. 用户显式选择。
2. 场景配置。
3. 资料包批次字段。
4. 系统默认值 `registration`。
如果多个来源冲突，标记为 `manual_review_required`，并优先使用用户显式选择。
## 5. 核心方法
### 5.1 `run(input) -> RegulationWorkflowResolveOutput`
主入口方法。
### 5.2 `resolve_workflow_type(input) -> str`
按优先级解析流程类型。
### 5.3 `detect_workflow_conflict(input) -> list[dict]`
检测用户选择、场景配置和批次字段是否冲突。
### 5.4 `validate_supported(workflow_type, supported_workflows) -> bool`
校验规则包是否支持当前流程。
## 6. 技术实现
使用技术：
1. 场景 YAML
2. 批次模型字段
3. 规则包元数据
4. Python 枚举
流程枚举：
1. `registration`
2. `change_record`
3. `change_registration`
4. `renewal`
## 7. 异常处理
1. 流程为空：使用 `registration`。
2. 流程冲突：标记警告。
3. 流程不支持：阻断完整性检查。
4. 用户输入非法：返回业务化错误。
## 8. 测试要点
1. 默认返回 `registration`。
2. 用户显式选择优先。
3. 场景和批次冲突时输出警告。
4. 不支持流程返回 `supported = false`。

118
docs/详细设计/skill/法规规则包加载Skill.md Normal file
View File

@@ -0,0 +1,118 @@
# 法规规则包加载Skill 设计
## 1. Skill 定位
`法规规则包加载Skill` 负责加载、校验和展开本地结构化法规规则包，是完整性检查的规则来源入口。
英文实现标识建议使用 `RegulationRulePackageLoadSkill`。
本 Skill 不读取用户资料，不做匹配判断，只处理法规规则本身。
## 2. 输入
```python
@dataclass
class RegulationRulePackageLoadInput:
rule_package_id: str
workflow_type: str
chapter_scope: list[str] = field(default_factory=list)
```
## 3. 输出
```python
@dataclass
class RegulationRulePackageLoadOutput:
rule_package_id: str
version: str
workflow_type: str
source_documents: list[dict]
requirements: list[dict]
risk_rules: dict
validation_warnings: list[dict]
```
## 4. 规则包来源
V1 默认来源：
```text
docs/原始材料/关于公布体外诊断试剂注册申报资料要求和批准证明文件格式的公告/
```
结构化规则建议维护在：
```text
configs/registration/rules/
nmpa_ivd_registration_v1.yaml
chapter_catalog.yaml
risk_mapping.yaml
```
## 5. 核心方法
### 5.1 `run(input) -> RegulationRulePackageLoadOutput`
主入口方法。
执行顺序：
1. 根据 `rule_package_id` 定位规则文件。
2. 读取 YAML。
3. 校验规则包元数据。
4. 校验规则包是否支持当前 `workflow_type`。
5. 展开章节范围。
6. 返回要求项和风险规则。
### 5.2 `load_yaml_rule_file(path) -> dict`
读取 YAML 文件。
### 5.3 `validate_rule_package(raw_rules) -> RulePackageValidationResult`
校验：
1. 是否有规则包 ID。
2. 是否有版本。
3. 是否有适用流程。
4. 是否有章节。
5. 每个必交项是否有风险等级。
6. 每个要求项是否有稳定 `requirement_id`。
### 5.4 `expand_requirements(rule_package, chapter_scope) -> list[RequirementItem]`
展开要求项。
如果 `chapter_scope = ["CH1"]`，只返回第 1 章要求项。
### 5.5 `load_risk_rules(rule_package) -> dict`
读取缺失、错放、待复核对应的风险映射规则。
## 6. 技术实现
使用技术：
1. `PyYAML`
2. Pydantic schema
3. Django cache
4. 文件修改时间检测
## 7. 异常处理
| 异常 | 处理 |
|---|---|
| 规则文件不存在 | 返回 `rule_package_not_found` |
| YAML 格式错误 | 返回 `rule_package_invalid` |
| 流程不匹配 | 返回 `workflow_not_supported` |
| 缺少风险配置 | 规则包校验失败 |
| 章节范围为空 | 使用默认范围 |
## 8. 测试要点
1. 成功加载规则包。
2. 规则包版本正确。
3. `CH1` 范围展开正确。
4. 不支持流程被拒绝。
5. 缺少必填字段时报校验错误。

100
docs/详细设计/skill/法规证据检索Skill.md Normal file
View File

@@ -0,0 +1,100 @@
# 法规证据检索Skill 设计
## 1. Skill 定位
`法规证据检索Skill` 负责为完整性检查结果补充法规原文证据，用于解释、页面展示和审计留痕。
英文实现标识建议使用 `RegulationEvidenceRetrieveSkill`。
本 Skill 不改变完整性判定结论。规则链路已经判定的缺失、错放和风险等级不能被 RAG 检索结果反向覆盖。
## 2. 输入
```python
@dataclass
class RegulationEvidenceRetrieveInput:
requirement_results: list[CompletenessItemResult]
rule_package_id: str
workflow_type: str
max_results_per_item: int = 3
```
## 3. 输出
```python
@dataclass
class RegulationEvidenceRetrieveOutput:
evidence_refs: list[EvidenceRef]
unavailable_items: list[dict]
warnings: list[dict]
```
`EvidenceRef` 字段：
1. `requirement_id`
2. `source_document`
3. `source_type`
4. `chapter_code`
5. `section_title`
6. `snippet`
7. `page_no`
8. `retrieval_score`
9. `metadata`
## 4. 检索范围
只检索法规资料，不检索业务申报资料。
metadata 过滤：
1. `source_role = regulation`
2. `workflow_type = registration`
3. `rule_package_id = nmpa_ivd_registration_v1`
4. `requirement_id` 或 `chapter_code`
## 5. 核心方法
### 5.1 `run(input) -> RegulationEvidenceRetrieveOutput`
主入口方法。
### 5.2 `build_evidence_query(item_result) -> str`
根据要求项名称、章节点和规则配置生成检索 query。
### 5.3 `retrieve_from_vector_store(query, metadata_filter) -> list[EvidenceRef]`
优先使用 Chroma。
### 5.4 `retrieve_from_fallback_index(query, metadata_filter) -> list[EvidenceRef]`
当 Chroma 不可用时，使用本地切片或关键词 fallback。
### 5.5 `normalize_evidence_results(results) -> list[EvidenceRef]`
统一证据格式。
## 6. 技术实现
使用技术：
1. Chroma
2. 本地 fallback 检索
3. 文本切片 metadata
4. Python 关键词匹配
## 7. 异常处理
1. 向量库不可用：降级 fallback。
2. fallback 也不可用：返回证据不可用警告。
3. 找不到证据：不阻断完整性报告。
4. 命中业务资料：过滤掉，避免把申报资料当法规依据。
## 8. 测试要点
1. 能根据要求项生成查询。
2. Chroma 可用时返回证据。
3. Chroma 不可用时 fallback 生效。
4. 证据检索失败不改变缺失结论。
5. 非法规资料被过滤。

73
docs/详细设计/skill/混档风险识别Skill.md Normal file
View File

@@ -0,0 +1,73 @@
# 混档风险识别Skill 设计
## 1. Skill 定位
`混档风险识别Skill` 负责基于一致性核查结果识别疑似跨产品、跨批次或错误资料混入风险。
英文实现标识建议使用 `MixedPackageRiskDetectSkill`。
## 2. 输入
```python
@dataclass
class MixedPackageRiskDetectInput:
compare_results: list[FieldCompareResult]
scope_documents: list[DocumentFact]
```
## 3. 输出
```python
@dataclass
class MixedPackageRiskDetectOutput:
mixed_package_warnings: list[dict]
highest_risk_level: str
```
## 4. 识别规则
1. 产品名称冲突：高风险。
2. 检测靶标冲突：高风险。
3. 产品名称和检测靶标指向不同产品：高风险。
4. 申请人名称冲突：高风险或待复核。
5. 相同文档角色出现多份不同产品文件：中风险。
## 5. 核心方法
### 5.1 `run(input) -> MixedPackageRiskDetectOutput`
主入口方法。
### 5.2 `detect_product_name_conflict(results) -> dict | None`
识别产品名称冲突。
### 5.3 `detect_target_conflict(results) -> dict | None`
识别检测靶标冲突。
### 5.4 `classify_warning_risk(warning) -> str`
映射风险等级。
## 6. 技术实现
使用技术：
1. 字段比对结果
2. 文档角色规则
3. 风险映射 YAML
## 7. 异常处理
1. 缺少产品名称字段：不输出混档结论，标记待复核。
2. 只有单来源：不输出混档结论。
3. 字段已冲突但来源不明：标记待人工确认。
## 8. 测试要点
1. 产品名称冲突输出高风险。
2. 检测靶标冲突输出高风险。
3. 单来源不输出混档风险。
4. 缺少核心字段时输出待复核。

185
docs/详细设计/skill/目录汇总Skill.md Normal file
View File

@@ -0,0 +1,185 @@
# 目录汇总Skill 设计
## 1. Skill 定位
`目录汇总Skill` 负责把一个资料包批次中的文档主数据聚合为目录汇总报告。它是第一步“资料包导入与目录汇总”的最终输出 Skill。
本 Skill 不重新扫描文件，不重新统计页数，只消费已经落库或已处理的文档事实。
英文实现标识建议使用 `DirectorySummarySkill`，用于 Python 类名和 Tool Registry 注册处理器。
## 2. 输入
```python
@dataclass
class DirectorySummaryInput:
batch_id: int
include_unsupported: bool = true
include_warnings: bool = true
```
## 3. 输出
```python
@dataclass
class RegistrationOverviewReport:
batch_id: int
batch_no: str
workflow_type: str
source_role: str
file_count: int
supported_file_count: int
unsupported_file_count: int
failed_file_count: int
manual_review_count: int
total_page_count: int
page_count_status: str
chapter_summary: list[dict]
documents: list[dict]
warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> RegistrationOverviewReport`
主入口方法。
执行顺序：
1. 读取批次信息。
2. 读取该批次所有文档记录。
3. 计算总文件数。
4. 计算支持文件、不支持文件、失败文件和待复核文件数量。
5. 汇总页数。
6. 按章节点聚合。
7. 生成文档明细。
8. 生成导入警告。
9. 返回结构化报告。
### 4.2 `summarize_counts(documents) -> dict`
计算：
1. `file_count`
2. `supported_file_count`
3. `unsupported_file_count`
4. `failed_file_count`
5. `manual_review_count`
### 4.3 `summarize_pages(documents) -> dict`
计算：
1. `total_page_count`
2. `exact_page_count`
3. `manual_review_page_count`
4. `page_count_status`
`page_count_status` 规则：
1. 全部精确：`exact`
2. 部分待复核：`partial_review_required`
3. 全部无法统计：`manual_review_required`
### 4.4 `summarize_chapters(documents) -> list[dict]`
按 `chapter_code` 聚合：
1. 文件数。
2. 页数。
3. 待复核数。
4. 主要资料角色。
无章节点的文件归入 `unclassified`。
### 4.5 `build_document_rows(documents) -> list[dict]`
生成页面明细。
字段：
1. `document_id`
2. `relative_path`
3. `original_filename`
4. `file_type`
5. `page_count`
6. `page_count_confidence`
7. `chapter_code`
8. `chapter_name`
9. `document_role`
10. `processing_status`
11. `needs_manual_review`
### 4.6 `build_warnings(documents) -> list[dict]`
生成业务化提示。
提示类型：
1. `unsupported_file`
2. `page_count_review_required`
3. `chapter_unclassified`
4. `file_type_mismatch`
5. `duplicate_file`
6. `archive_extract_warning`
## 5. 技术实现
使用技术：
1. Django ORM 聚合查询
2. Python dataclass 或 Pydantic
3. JSONField 存储报告快照
建议注册名：
```python
tool_registry.register(
name="build_directory_summary",
handler=DirectorySummarySkill().run,
)
```
## 6. 报告存储
建议将目录汇总报告快照写入批次模型或独立模型：
```python
class SubmissionBatchSummary(models.Model):
batch = models.OneToOneField(SubmissionBatch, on_delete=models.CASCADE)
report_type = models.CharField(max_length=64, default="registration_overview_report")
report_json = models.JSONField(default=dict)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
```
## 7. 与页面接口
Documents 页面直接消费 `RegistrationOverviewReport`：
1. 顶部显示统计卡片。
2. 中部显示按章节点聚合表。
3. 底部显示文件明细。
4. 侧边显示待人工复核提示。
## 8. 与后续 Agent Core 接口
法规完整性核查从本报告读取：
1. `batch_id`
2. `documents`
3. `chapter_summary`
4. `manual_review_count`
5. `warnings`
如果 `manual_review_count > 0`，后续完整性核查仍可执行，但最终报告应标记“存在资料处理不确定性”。
## 9. 测试要点
1. 空批次返回合理空报告。
2. 多章节点文件能正确聚合。
3. 页数合计只统计有明确页数的文档。
4. 待复核文件数量正确。
5. 不支持文件可选展示。
6. 输出 schema 字段稳定。

158
docs/详细设计/skill/章节点识别Skill.md Normal file
View File

@@ -0,0 +1,158 @@
# 章节点识别Skill 设计
## 1. Skill 定位
`章节点识别Skill` 负责对已登记文档进行章节点和资料角色的初步识别，为目录汇总和后续法规完整性核查提供结构化字段。
本 Skill 使用规则优先，不依赖 LLM。后续可以在人工复核或复杂标题解析中引入模型辅助，但不作为 V1 必需能力。
英文实现标识建议使用 `ChapterClassificationSkill`，用于 Python 类名和 Tool Registry 注册处理器。
## 2. 输入
```python
@dataclass
class ChapterClassificationInput:
document_id: int
original_filename: str
relative_path: str
file_type: str
title_text: str | None = None
manual_hint: dict = field(default_factory=dict)
```
## 3. 输出
```python
@dataclass
class ChapterClassificationResult:
document_id: int
chapter_code: str | None
chapter_name: str | None
document_role: str | None
declared_document_name: str | None
confidence: str
status: str
evidence: list[dict]
```
## 4. 识别规则
### 4.1 章节点编码识别
从文件名和相对路径中识别：
1. `CH1.2`
2. `CH1.4`
3. `CH1.5`
4. `CH1.9`
5. `CH1.11.1`
6. `CH1.11.5`
7. `CH1.11.6`
正则示例：
```python
r"CH\s*(\d+(?:\.\d+)*)"
```
### 4.2 章节名称识别
从相对路径中识别：
1. `第1章 监管信息`
2. `第2章 综述资料`
3. `第3章 非临床资料`
4. `第4章 临床评价资料`
5. `第5章 产品说明书和标签样稿`
6. `第6章 质量管理体系文件`
### 4.3 文档角色识别
| 关键词 | document_role |
|---|---|
| `监管信息目录` | `regulatory_information_catalog` |
| `申请表` | `application_form` |
| `产品列表` | `product_list` |
| `符合标准的清单` | `standard_compliance_list` |
| `真实性声明` | `authenticity_statement` |
| `符合性声明` | `conformity_statement` |
| `沟通的说明` | `pre_submission_communication` |
| `说明书` | `product_instruction` |
## 5. 核心方法
### 5.1 `run(input) -> ChapterClassificationResult`
主入口方法。
执行顺序：
1. 从相对路径识别章名称。
2. 从文件名识别章节点编码。
3. 从文件名识别文档角色。
4. 如有标题文本，则用标题补充识别。
5. 计算置信度。
6. 返回识别结果。
### 5.2 `extract_chapter_code(text) -> str | None`
从路径或文件名提取 `CHx.x`。
### 5.3 `extract_chapter_name(relative_path) -> str | None`
从目录层级识别章节名称。
### 5.4 `detect_document_role(text) -> str | None`
基于关键词和规则表识别文档角色。
### 5.5 `calculate_confidence(matches) -> str`
置信度规则：
1. 路径、文件名和标题一致：`high`
2. 文件名命中但路径缺失：`medium`
3. 只有关键词命中：`low`
4. 无法识别：`manual_review_required`
## 6. 技术实现
使用技术：
1. `re`
2. YAML 规则表
3. 可选 `python-docx` 首页标题抽取
4. Django 管理后台人工修正
建议规则文件：
```text
configs/registration/chapter_classification.yaml
```
## 7. 落库字段
建议写入 `RegistrationDocument`：
1. `chapter_code`
2. `chapter_name`
3. `document_role`
4. `declared_document_name`
5. `classification_confidence`
6. `classification_status`
7. `needs_manual_review`
## 8. 异常处理
1. 文件名无章节点：尝试路径识别。
2. 路径与文件名冲突：标记待人工复核。
3. 识别为法规资料但批次为业务资料：标记潜在混入风险。
4. 同一文件命中多个角色：保留最高优先级角色，记录警告。
## 9. 测试要点
1. `CH1.4 申请表.docx` 识别为 `CH1.4` 和 `application_form`。
2. `第1章 监管信息/CH1.2 监管信息目录.docx` 识别章节和目录角色。
3. 无章节点文件标记待人工复核。
4. 路径与文件名冲突时输出警告。

83
docs/详细设计/skill/统一字段池写入Skill.md Normal file
View File

@@ -0,0 +1,83 @@
# 统一字段池写入Skill 设计
## 1. Skill 定位
`统一字段池写入Skill` 负责将标准化后的字段候选写入统一字段池，并为每个字段选择推荐值、保留候选值和来源证据。
英文实现标识建议使用 `UnifiedFieldPoolWriteSkill`。
## 2. 输入
```python
@dataclass
class UnifiedFieldPoolWriteInput:
batch_id: int
normalized_candidates: list[NormalizedFieldCandidate]
field_definitions: list[FieldDefinition]
source_priority: dict
```
## 3. 输出
```python
@dataclass
class UnifiedFieldPoolWriteOutput:
field_pool_items: list[FieldPoolItem]
candidate_records: list[dict]
manual_review_fields: list[dict]
write_status: str
```
## 4. 推荐值选择规则
1. 优先选择高置信候选。
2. 同置信度时按来源优先级选择。
3. 来源优先级一致时选择规则抽取结果。
4. 多候选值明显不同则标记 `conflict_candidate`。
5. 待人工复核字段不作为无条件回填值。
## 5. 核心方法
### 5.1 `run(input) -> UnifiedFieldPoolWriteOutput`
主入口方法。
### 5.2 `group_candidates_by_field(candidates) -> dict`
按 `field_key` 分组。
### 5.3 `select_recommended_value(field_key, candidates, priority) -> FieldPoolItem`
选择推荐值。
### 5.4 `persist_field_pool_item(item) -> RegistrationFieldPoolItem`
写入字段池。
### 5.5 `persist_field_candidates(item, candidates) -> None`
保留所有候选值。
## 6. 技术实现
使用技术：
1. Django ORM
2. JSONField
3. 批量写入
4. 唯一约束：`batch + field_key`
## 7. 异常处理
1. 没有候选值：写入空字段并标记待复核。
2. 数据库写入失败：任务失败并写审计。
3. 字段重复写入：更新字段池版本或覆盖当前批次结果。
4. 候选冲突：保留候选并标记冲突候选。
## 8. 测试要点
1. 高置信候选被选为推荐值。
2. 来源优先级生效。
3. 冲突候选被保留。
4. 可回填字段标记正确。

118
docs/详细设计/skill/缺失错放判定Skill.md Normal file
View File

@@ -0,0 +1,118 @@
# 缺失错放判定Skill 设计
## 1. Skill 定位
`缺失错放判定Skill` 负责根据法规要求项和资料匹配结果，判定每个要求项的完整性状态，并映射完整性维度的风险等级和基础处理建议。
英文实现标识建议使用 `MissingMisplacementEvaluateSkill`。
本 Skill 是完整性检查中真正产生“缺失、错放、待复核”结论的规则执行单元。
## 2. 输入
```python
@dataclass
class MissingMisplacementEvaluateInput:
requirements: list[RequirementItem]
matches: list[RequirementDocumentMatch]
document_uncertainties: list[DocumentUncertainty]
risk_rules: dict
```
## 3. 输出
```python
@dataclass
class MissingMisplacementEvaluateOutput:
item_results: list[CompletenessItemResult]
missing_items: list[dict]
misplaced_items: list[dict]
suspected_items: list[dict]
manual_review_items: list[dict]
pass_status: str
highest_risk_level: str
```
## 4. 判定规则
| 条件 | 状态 |
|---|---|
| 必交要求项有高置信匹配 | `provided` |
| 必交要求项没有匹配 | `missing` |
| 有低置信匹配 | `suspected` |
| 文档角色匹配但章节点不匹配 | `misplaced` |
| 命中文档待人工复核 | `manual_review_required` |
| 当前流程不适用 | `not_applicable` |
## 5. 风险映射
风险来源：
1. 规则项自身的 `risk_level_if_missing`。
2. 错放风险映射。
3. 待复核不确定性。
4. 资料处理失败状态。
准入结论：
1. 存在高风险缺失：`failed`
2. 存在中风险缺失或错放：`review_required`
3. 只有低风险或待复核：`conditional_pass`
4. 全部已提供：`passed`
## 6. 核心方法
### 6.1 `run(input) -> MissingMisplacementEvaluateOutput`
主入口方法。
### 6.2 `evaluate_requirement_status(requirement, matches) -> CompletenessItemResult`
对单个要求项判定状态。
### 6.3 `detect_misplacement(requirement, matches) -> bool`
判断文档是否存在但归错章节点。
### 6.4 `detect_suspected_provided(requirement, matches) -> bool`
判断是否疑似提供。
### 6.5 `map_risk_level(requirement, status, risk_rules) -> str`
映射风险等级。
### 6.6 `build_suggestion(requirement, status, risk_level) -> str`
生成基础处理建议。
建议示例：
1. `补充 CH1.4 申请表，并由注册申报负责人复核。`
2. `核对该文件是否应归入 CH1.5 产品列表。`
3. `当前资料疑似提供但命名不规范，建议人工确认后修正章节点。`
## 7. 技术实现
使用技术：
1. Python 规则引擎
2. YAML 风险映射
3. Pydantic/dataclass
4. 本地建议模板
## 8. 异常处理
1. 要求项缺少风险配置：默认中风险，并记录规则警告。
2. 匹配结果为空：按必交状态判缺失或不适用。
3. 匹配冲突：标记待人工复核。
4. 文档处理失败：不作为已提供，进入待复核。
## 9. 测试要点
1. 必交项无匹配时判缺失。
2. 高风险缺失导致 `failed`。
3. 低置信匹配进入 `suspected`。
4. 章节点不一致进入 `misplaced`。
5. 待复核文档不会直接判为通过。

81
docs/详细设计/skill/表格字段抽取Skill.md Normal file
View File

@@ -0,0 +1,81 @@
# 表格字段抽取Skill 设计
## 1. Skill 定位
`表格字段抽取Skill` 负责从申请表、产品列表、标准清单等表格结构中抽取字段候选值。
英文实现标识建议使用 `TableFieldExtractSkill`。
## 2. 输入
```python
@dataclass
class TableFieldExtractInput:
documents: list[DocumentContent]
field_definitions: list[FieldDefinition]
```
## 3. 输出
```python
@dataclass
class TableFieldExtractOutput:
candidates: list[FieldCandidate]
failed_tables: list[dict]
tool_calls: list[dict]
```
## 4. 适用字段
1. 产品名称。
2. 包装规格。
3. 申请人名称。
4. 分类编码。
5. 生产地址。
6. 标准清单。
## 5. 核心方法
### 5.1 `run(input) -> TableFieldExtractOutput`
主入口方法。
### 5.2 `normalize_table(table) -> NormalizedTable`
标准化表头、空单元格和合并单元格。
### 5.3 `match_table_header(table, field_definition) -> TableMatch | None`
匹配表头。
### 5.4 `extract_cell_value(table, match) -> FieldCandidate`
抽取单元格值。
### 5.5 `build_table_source_location(table_index, row_index, col_index) -> SourceLocation`
记录表格来源位置。
## 6. 技术实现
使用技术：
1. `python-docx`
2. `pdfplumber`
3. 表头关键词映射
4. 合并单元格兼容处理
## 7. 异常处理
1. 无表格：跳过。
2. 表头无法识别：记录待复核。
3. 合并单元格解析失败：记录表格失败。
4. 多行多值：保留所有候选。
## 8. 测试要点
1. 能从申请表抽取产品名称。
2. 能从产品列表抽取包装规格。
3. 能记录表格坐标。
4. 表格解析失败不影响规则抽取。

78
docs/详细设计/skill/规则字段抽取Skill.md Normal file
View File

@@ -0,0 +1,78 @@
# 规则字段抽取Skill 设计
## 1. Skill 定位
`规则字段抽取Skill` 负责从标题、段落和固定标签中抽取字段候选值，适合处理格式稳定、标签明确的注册申报字段。
英文实现标识建议使用 `RuleFieldExtractSkill`。
## 2. 输入
```python
@dataclass
class RuleFieldExtractInput:
documents: list[DocumentContent]
field_definitions: list[FieldDefinition]
```
## 3. 输出
```python
@dataclass
class RuleFieldExtractOutput:
candidates: list[FieldCandidate]
failed_fields: list[dict]
tool_calls: list[dict]
```
## 4. 抽取方式
1. 标题后取值。
2. 标签后取值。
3. 固定段落规则。
4. 正则匹配。
## 5. 核心方法
### 5.1 `run(input) -> RuleFieldExtractOutput`
主入口方法。
### 5.2 `extract_by_heading(document, field_definition) -> FieldCandidate | None`
从标题结构中抽取。
### 5.3 `extract_by_label(document, field_definition) -> FieldCandidate | None`
从标签字段中抽取。
### 5.4 `extract_by_regex(document, field_definition) -> FieldCandidate | None`
使用字段配置中的正则规则抽取。
### 5.5 `build_candidate(field, value, source) -> FieldCandidate`
构建字段候选。
## 6. 技术实现
使用技术：
1. `re`
2. 文本结构解析结果
3. 中文标点标准化
## 7. 异常处理
1. 文本为空：跳过该文档。
2. 多个候选：全部保留。
3. 正则异常：记录工具失败。
4. 候选值过长：标记待复核。
## 8. 测试要点
1. 能从标题抽取产品名称。
2. 能从标签抽取储存条件。
3. 多候选值全部保留。
4. 空文本不报错。

168
docs/详细设计/skill/资料包导入Skill.md Normal file
View File

@@ -0,0 +1,168 @@
# 资料包导入Skill 设计
## 1. Skill 定位
`资料包导入Skill` 是资料包导入工作流的总入口 Skill，负责把用户上传的文件集合转化为一个可处理的资料包批次，并协调解包、扫描、文档登记、页数统计、章节点识别和目录汇总。
它不直接处理法规完整性，不调用 LLM，不执行 RAG 入库。
英文实现标识建议使用 `SubmissionPackageImportSkill`，用于 Python 类名和 Tool Registry 注册处理器。
## 2. 触发场景
1. 用户在 Web 工作台上传单文件。
2. 用户批量上传多个文件。
3. 用户上传压缩包。
4. 飞书入口后续触发资料包导入任务。
5. 管理员导入平台内置法规资料。
## 3. 输入
```python
@dataclass
class SubmissionPackageImportInput:
files: list[UploadedFileRef]
batch_name: str
workflow_type: str = "registration"
source_role: str = "submission"
created_by_id: int | None = None
import_options: dict = field(default_factory=dict)
```
字段说明：
| 字段 | 说明 |
|---|---|
| `files` | 用户上传文件引用 |
| `batch_name` | 资料包批次名称 |
| `workflow_type` | 注册流程类型，V1 默认 `registration` |
| `source_role` | `submission` 或 `regulation` |
| `created_by_id` | 操作人 |
| `import_options` | 是否立即页数统计、是否跳过不支持文件等选项 |
## 4. 输出
```python
@dataclass
class SubmissionPackageImportOutput:
batch_id: int
batch_no: str
status: str
overview_report: dict
warnings: list[dict]
failed_items: list[dict]
```
## 5. 依赖 Skill
1. `压缩包解包Skill`
2. `资料包扫描Skill`
3. `文档页数统计Skill`
4. `章节点识别Skill`
5. `目录汇总Skill`
## 6. 核心方法
### 6.1 `run(input) -> SubmissionPackageImportOutput`
主入口方法。
执行顺序：
1. 创建 `SubmissionBatch`。
2. 保存上传文件到批次隔离目录。
3. 对压缩包调用 `压缩包解包Skill`。
4. 调用 `资料包扫描Skill` 扫描批次目录。
5. 创建 `RegistrationDocument` 记录。
6. 调用 `文档页数统计Skill`。
7. 调用 `章节点识别Skill`。
8. 调用 `目录汇总Skill`。
9. 更新批次状态。
10. 返回目录汇总结果。
### 6.2 `create_batch(input) -> SubmissionBatch`
创建资料包批次。
状态：
1. 初始为 `created`。
2. 文件保存开始后更新为 `importing`。
3. 汇总阶段更新为 `summarizing`。
4. 成功后更新为 `completed` 或 `partial_completed`。
### 6.3 `save_uploaded_files(batch, files) -> list[StoredUpload]`
保存原始上传文件，并记录上传文件来源。
安全要求：
1. 过滤路径穿越。
2. 原始文件名只用于展示。
3. 真实存储路径使用批次目录和安全文件名。
### 6.4 `create_document_records(batch, scanned_files) -> list[RegistrationDocument]`
把扫描结果落库为文档主数据。
落库字段：
1. `original_filename`
2. `relative_path`
3. `file_type`
4. `file_size`
5. `file_hash`
6. `source_archive_name`
7. `source_role`
8. `workflow_type`
9. `processing_status`
### 6.5 `finalize_batch_status(batch, overview_report) -> str`
根据结果决定批次状态。
规则：
1. 全部成功：`completed`
2. 存在待人工复核：`partial_completed`
3. 存在不支持文件但有有效文件：`partial_completed`
4. 无有效文件：`failed`
## 7. 技术实现
使用技术：
1. Django ORM
2. Django Storage
3. `pathlib`
4. `dataclasses` 或 Pydantic
5. Tool Registry
建议注册名：
```python
tool_registry.register(
name="submission_package_import",
handler=SubmissionPackageImportSkill().run,
)
```
## 8. 异常处理
| 异常 | 处理 |
|---|---|
| 上传文件为空 | 拒绝该文件，记录失败项 |
| 批次目录创建失败 | 整体失败 |
| 解包失败 | 批次部分失败或整体失败 |
| 无支持文件 | 批次失败 |
| 页数统计部分失败 | 批次部分完成 |
| 章节点识别失败 | 文档标记待人工确认 |
## 9. 测试要点
1. 单文件导入成功。
2. 多文件导入共用同一批次。
3. 压缩包导入保留相对路径。
4. 不支持文件不会阻断有效文件。
5. 部分失败时批次为 `partial_completed`。
6. 输出包含 `overview_report`。

127
docs/详细设计/skill/资料包扫描Skill.md Normal file
View File

@@ -0,0 +1,127 @@
# 资料包扫描Skill 设计
## 1. Skill 定位
`资料包扫描Skill` 负责扫描资料包根目录，生成后续文档登记、页数统计和章节点识别所需的文件清单。
它处理的是文件系统事实，不读取文档正文，不做页数统计。
英文实现标识建议使用 `PackageFileScanSkill`，用于 Python 类名和 Tool Registry 注册处理器。
## 2. 输入
```python
@dataclass
class PackageFileScanInput:
root_dir: Path
batch_id: int
source_role: str = "submission"
allowed_extensions: set[str] = field(default_factory=set)
```
## 3. 输出
```python
@dataclass
class PackageFileScanOutput:
scanned_files: list[ScannedFile]
unsupported_files: list[ScannedFile]
skipped_files: list[SkippedFile]
warnings: list[dict]
```
`ScannedFile` 字段：
1. `absolute_path`
2. `relative_path`
3. `original_filename`
4. `extension`
5. `file_size`
6. `file_hash`
7. `source_role`
## 4. 核心方法
### 4.1 `run(input) -> PackageFileScanOutput`
主入口方法。
执行顺序：
1. 遍历根目录。
2. 过滤目录和临时文件。
3. 识别文件类型。
4. 生成文件大小和哈希。
5. 区分支持文件、不支持文件和跳过文件。
6. 返回扫描结果。
### 4.2 `iter_files(root_dir) -> Iterator[Path]`
使用 `pathlib.Path.rglob("*")` 遍历文件。
### 4.3 `should_skip(path) -> bool`
跳过规则：
1. `.DS_Store`
2. `Thumbs.db`
3. `__MACOSX`
4. Office 临时文件 `~$*.docx`
5. 空文件
### 4.4 `is_supported_document(path) -> bool`
支持类型：
1. `pdf`
2. `docx`
3. `doc`
4. `txt`
5. `md`
压缩包在本 Skill 中不再进入支持文档列表，应由导入入口先交给 `压缩包解包Skill`。
### 4.5 `build_relative_path(root_dir, path) -> str`
生成统一的相对路径，使用 `/` 作为内部存储分隔符。
### 4.6 `build_file_hash(path) -> str`
使用 `sha256`。
## 5. 技术实现
使用技术：
1. `pathlib`
2. `hashlib`
3. `mimetypes`
4. 可选 `python-magic`
## 6. 输出用途
扫描结果用于：
1. 创建 `RegistrationDocument`。
2. 保留资料包原始目录结构。
3. 识别重复文件。
4. 后续章节点识别。
5. 页面展示不支持文件提示。
## 7. 异常处理
| 异常 | 处理 |
|---|---|
| 根目录不存在 | 返回失败 |
| 文件读取失败 | 加入 `skipped_files` |
| 文件为空 | 加入 `skipped_files` |
| 类型不支持 | 加入 `unsupported_files` |
| 哈希计算失败 | 保留文件记录，标记警告 |
## 8. 测试要点
1. 多层目录扫描后相对路径正确。
2. Office 临时文件被跳过。
3. 不支持文件进入 `unsupported_files`。
4. 支持文件进入 `scanned_files`。
5. 哈希对同一文件稳定。

112
docs/详细设计/skill/资料要求匹配Skill.md Normal file
View File

@@ -0,0 +1,112 @@
# 资料要求匹配Skill 设计
## 1. Skill 定位
`资料要求匹配Skill` 负责把当前资料包中的文档事实与法规要求项进行匹配，生成每个要求项的候选命中文档和匹配证据。
英文实现标识建议使用 `RequirementDocumentMatchSkill`。
本 Skill 只判断“是否可能命中”，不负责最终缺失或风险判定。
## 2. 输入
```python
@dataclass
class RequirementDocumentMatchInput:
documents: list[DocumentFact]
requirements: list[RequirementItem]
```
## 3. 输出
```python
@dataclass
class RequirementDocumentMatchOutput:
matches: list[RequirementDocumentMatch]
unmatched_documents: list[DocumentFact]
warnings: list[dict]
```
## 4. 匹配策略
### 4.1 章节点编码匹配
最高优先级。
示例：
1. 文档 `CH1.4 申请表.docx`
2. 要求项 `CH1.4 申请表`
3. 结果：高置信命中
### 4.2 文档角色匹配
使用第一步产生的 `document_role`。
示例：
1. `application_form`
2. `product_list`
3. `regulatory_information_catalog`
### 4.3 关键词匹配
使用法规要求项中的关键词表匹配文件名和相对路径。
### 4.4 人工修正字段匹配
如果用户在后台修正了章节点或资料名称，应优先使用修正结果。
## 5. 核心方法
### 5.1 `run(input) -> RequirementDocumentMatchOutput`
主入口方法。
### 5.2 `match_by_chapter_code(document, requirement) -> MatchEvidence | None`
章节点编码完全相等时返回高置信证据。
### 5.3 `match_by_document_role(document, requirement) -> MatchEvidence | None`
文档角色命中期望角色时返回证据。
### 5.4 `match_by_keywords(document, requirement) -> MatchEvidence | None`
文件名、资料名称或相对路径命中关键词时返回证据。
### 5.5 `calculate_match_confidence(evidences) -> str`
置信度：
1. `high`
2. `medium`
3. `low`
4. `none`
## 6. 技术实现
使用技术：
1. Python 字符串规则
2. `re`
3. 中文空白和标点标准化
4. 可选 `rapidfuzz`
V1 中不建议过度依赖模糊匹配，避免把相似但不等价的资料误判为已提供。
## 7. 异常处理
1. 一个要求项命中多个文档：保留全部候选，交给判定 Skill 处理。
2. 一个文档命中多个要求项：标记潜在错放或重复。
3. 文档待人工复核：仍可参与匹配，但置信度不超过 `medium`。
4. 章节点冲突：输出警告。
## 8. 测试要点
1. 章节点完全匹配返回高置信。
2. 文档角色匹配返回中高置信。
3. 只有关键词匹配返回低或中置信。
4. 待复核文档不会被高置信命中。
5. 多重命中输出警告。

83
docs/详细设计/skill/长文本字段归纳Skill.md Normal file
View File

@@ -0,0 +1,83 @@
# 长文本字段归纳Skill 设计
## 1. Skill 定位
`长文本字段归纳Skill` 负责对规则和表格无法稳定抽取的长文本字段进行证据限定后的 LLM 归纳。
英文实现标识建议使用 `LongTextFieldSummarizeSkill`。
本 Skill 必须通过 LLM Provider 调用模型，并支持 Mock Provider。
## 2. 输入
```python
@dataclass
class LongTextFieldSummarizeInput:
documents: list[DocumentContent]
field_definitions: list[FieldDefinition]
enable_rag_context: bool = True
```
## 3. 输出
```python
@dataclass
class LongTextFieldSummarizeOutput:
candidates: list[FieldCandidate]
evidence_refs: list[EvidenceRef]
tool_calls: list[dict]
failed_fields: list[dict]
```
## 4. 处理字段
1. 检测靶标。
2. 适用范围 / 预期用途。
3. 性能指标。
4. 临床评价路径。
## 5. 核心方法
### 5.1 `run(input) -> LongTextFieldSummarizeOutput`
主入口方法。
### 5.2 `locate_field_context(document, field_definition) -> list[EvidenceChunk]`
通过 RAG 或关键词定位候选片段。
### 5.3 `build_llm_prompt(field_definition, chunks) -> str`
构造限定上下文提示词。
### 5.4 `call_provider(prompt, output_schema) -> dict`
调用 LLM Provider。
### 5.5 `validate_output(output) -> FieldCandidate`
校验结构化输出。
## 6. 技术实现
使用技术：
1. RAG fallback / Chroma
2. LLM Provider
3. JSON schema
4. Mock Provider
## 7. 异常处理
1. 找不到候选片段：字段标记待人工复核。
2. Provider 不可用：跳过 LLM。
3. 输出 JSON 非法：丢弃结果。
4. 输出没有来源片段：标记低可信。
## 8. 测试要点
1. Mock Provider 可返回固定字段。
2. 找不到上下文时不会编造字段。
3. 非法 JSON 被拦截。
4. LLM 关闭时主流程仍可完成。

62
docs/详细设计/skill/风险归并Skill.md Normal file
View File

@@ -0,0 +1,62 @@
# 风险归并Skill 设计
## 1. Skill 定位
`风险归并Skill` 负责合并重复风险、关联同根因风险，并生成可排序的风险组。
英文实现标识建议使用 `RiskMergeSkill`。
## 2. 输入
```python
@dataclass
class RiskMergeInput:
risk_items: list[RiskItem]
```
## 3. 输出
```python
@dataclass
class RiskMergeOutput:
merged_risk_items: list[RiskItem]
risk_groups: list[RiskGroup]
```
## 4. 核心方法
### 4.1 `run(input) -> RiskMergeOutput`
主入口方法。
### 4.2 `build_fingerprint(risk_item) -> str`
生成风险指纹。
### 4.3 `merge_duplicates(items) -> list[RiskItem]`
合并重复风险。
### 4.4 `link_related(items) -> list[RiskGroup]`
关联同根因风险。
## 5. 技术实现
使用技术：
1. Python 分组
2. 风险指纹
3. 关联规则
## 6. 异常处理
1. 风险项为空：返回空集合。
2. 风险缺少关键字段：不合并并记录警告。
## 7. 测试要点
1. 重复风险可合并。
2. 产品名称冲突和混档风险可关联。
3. 空风险列表可处理。

88
docs/详细设计/skill/风险报告生成Skill.md Normal file
View File

@@ -0,0 +1,88 @@
# 风险报告生成Skill 设计
## 1. Skill 定位
`风险报告生成Skill` 负责将风险项、准入判定和整改建议组装成稳定的 `registration_risk_report`，并生成页面展示、审计和飞书通知载荷。
英文实现标识建议使用 `RiskReportBuildSkill`。
## 2. 输入
```python
@dataclass
class RiskReportBuildInput:
context: RiskEvaluationContext
risk_items: list[RiskItem]
admission_decision: AdmissionDecisionOutput
suggestions: list[dict]
owner_notifications: list[dict]
```
## 3. 输出
```python
@dataclass
class RiskReportBuildOutput:
report: dict
display_sections: list[dict]
audit_payload: dict
feishu_notification_payload: dict
```
## 4. 报告结构
报告必须包含：
1. `report_type`
2. `batch_id`
3. `risk_rule_id`
4. `summary`
5. `risk_items`
6. `manual_review_items`
7. `suggestions`
8. `owner_notifications`
## 5. 核心方法
### 5.1 `run(input) -> RiskReportBuildOutput`
主入口方法。
### 5.2 `build_summary(risk_items, admission) -> dict`
生成汇总。
### 5.3 `build_display_sections(report) -> list[dict]`
生成页面展示区块。
### 5.4 `build_audit_payload(report, context) -> dict`
生成审计载荷。
### 5.5 `build_feishu_payload(report) -> dict`
生成飞书通知载荷。
## 6. 技术实现
使用技术：
1. dataclass/Pydantic
2. JSONField
3. Audit 服务
4. 飞书消息 payload schema
## 7. 异常处理
1. 风险项为空：输出通过报告。
2. 审计失败：报告返回并记录系统警告。
3. 飞书载荷生成失败：不影响 Web 报告。
## 8. 测试要点
1. 报告 schema 稳定。
2. 汇总数量正确。
3. 审计载荷包含规则版本。
4. 飞书载荷包含高风险摘要。

64
docs/详细设计/skill/风险规则加载Skill.md Normal file
View File

@@ -0,0 +1,64 @@
# 风险规则加载Skill 设计
## 1. Skill 定位
`风险规则加载Skill` 负责加载风险分级、准入规则、责任角色映射和整改建议模板。
英文实现标识建议使用 `RiskRuleLoadSkill`。
## 2. 输入
```python
@dataclass
class RiskRuleLoadInput:
risk_rule_id: str
```
## 3. 输出
```python
@dataclass
class RiskRuleLoadOutput:
risk_rule_id: str
version: str
risk_type_rules: dict
admission_rules: dict
owner_role_mapping: dict
suggestion_templates: dict
```
## 4. 核心方法
### 4.1 `run(input) -> RiskRuleLoadOutput`
主入口方法。
### 4.2 `load_rule_file(risk_rule_id) -> dict`
读取 YAML。
### 4.3 `validate_rules(raw_rules) -> RiskRuleValidationResult`
校验规则完整性。
## 5. 技术实现
使用技术：
1. YAML
2. Pydantic
3. Django cache
## 6. 异常处理
1. 规则不存在：任务失败。
2. 准入规则缺失：校验失败。
3. 责任角色缺失：使用默认角色并警告。
## 7. 测试要点
1. 规则加载成功。
2. 准入规则可读取。
3. 责任角色映射可读取。
4. 缺失规则时报错。

66
docs/详细设计/skill/风险项生成Skill.md Normal file
View File

@@ -0,0 +1,66 @@
# 风险项生成Skill 设计
## 1. Skill 定位
`风险项生成Skill` 负责从前序报告中提取风险事实，并按照风险规则生成标准化风险项。
英文实现标识建议使用 `RiskItemBuildSkill`。
## 2. 输入
```python
@dataclass
class RiskItemBuildInput:
reports: dict[str, dict]
risk_rules: dict
```
## 3. 输出
```python
@dataclass
class RiskItemBuildOutput:
risk_items: list[RiskItem]
manual_review_items: list[dict]
warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> RiskItemBuildOutput`
主入口方法。
### 4.2 `build_from_completeness(report) -> list[RiskItem]`
从缺失、错放、待复核生成风险。
### 4.3 `build_from_field_extraction(report) -> list[RiskItem]`
从字段缺失、低可信、抽取失败生成风险。
### 4.4 `build_from_consistency(report) -> list[RiskItem]`
从字段冲突、混档风险生成风险。
## 5. 技术实现
使用技术：
1. 前序报告 schema
2. 风险规则映射
3. dataclass/Pydantic
## 6. 异常处理
1. 报告缺失：生成报告缺失警告。
2. 风险类型未配置：使用中风险并警告。
3. 证据缺失：风险仍生成，但标记证据不足。
## 7. 测试要点
1. 缺失项生成风险。
2. 字段冲突生成风险。
3. 混档生成高风险。
4. 手工复核项被保留。

90
docs/详细设计/skill/风险预警编排Skill.md Normal file
View File

@@ -0,0 +1,90 @@
# 风险预警编排Skill 设计
## 1. Skill 定位
`风险预警编排Skill` 是第五步工作流的总入口 Skill，负责组织前序报告汇总、风险规则加载、风险项生成、风险归并、准入判定、整改建议生成和风险报告输出。
英文实现标识建议使用 `RiskWarningOrchestrateSkill`。
## 2. 输入
```python
@dataclass
class RiskWarningOrchestrateInput:
batch_id: int
scenario_id: str = "registration_risk_report"
risk_rule_id: str = "ivd_registration_risk_v1"
include_reports: list[str] = field(default_factory=list)
enable_llm_summary: bool = True
```
## 3. 输出
```python
@dataclass
class RiskWarningOrchestrateOutput:
report_type: str
batch_id: int
summary: dict
risk_items: list[dict]
manual_review_items: list[dict]
suggestions: list[dict]
audit_id: int | None = None
```
## 4. 依赖 Skill
1. `前序报告汇总Skill`
2. `风险规则加载Skill`
3. `风险项生成Skill`
4. `风险归并Skill`
5. `准入判定Skill`
6. `整改建议生成Skill`
7. `风险报告生成Skill`
## 5. 核心方法
### 5.1 `run(input) -> RiskWarningOrchestrateOutput`
主入口方法。
### 5.2 `load_execution_context(input) -> RiskEvaluationContext`
加载批次、场景和前序报告上下文。
### 5.3 `merge_results(risks, admission, suggestions) -> dict`
合并风险、准入和建议。
## 6. 技术实现
使用技术：
1. Tool Registry
2. dataclass/Pydantic
3. Django ORM
4. Audit 服务
建议注册名：
```python
tool_registry.register(
name="risk_warning_orchestrate",
handler=RiskWarningOrchestrateSkill().run,
)
```
## 7. 异常处理
1. 前序报告缺失：输出业务提示。
2. 风险规则缺失：任务失败。
3. LLM 不可用：使用模板摘要。
4. 审计写入失败：报告返回并记录系统警告。
## 8. 测试要点
1. 能串联所有依赖 Skill。
2. 高风险导致不通过。
3. 前序报告缺失时提示清晰。
4. 输出报告 schema 稳定。

67
docs/详细设计/skill/飞书任务入口解析Skill.md Normal file
View File

@@ -0,0 +1,67 @@
# 飞书任务入口解析Skill 设计
## 1. Skill 定位
`飞书任务入口解析Skill` 负责解析飞书事件和用户指令，将群聊消息映射到系统审核任务。
英文实现标识建议使用 `FeishuTaskEntryParseSkill`。
## 2. 输入
```python
@dataclass
class FeishuTaskEntryParseInput:
event_payload: dict
```
## 3. 输出
```python
@dataclass
class FeishuTaskEntryParseOutput:
command: str
scenario_id: str | None
batch_id: int | None
chat_id: str
message_id: str
warnings: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> FeishuTaskEntryParseOutput`
主入口方法。
### 4.2 `verify_event_signature(payload) -> bool`
校验事件来源。
### 4.3 `extract_command(payload) -> str`
提取用户指令。
### 4.4 `resolve_scenario(command) -> str | None`
映射任务场景。
## 5. 技术实现
使用技术：
1. 飞书事件订阅
2. Django webhook
3. 场景配置 YAML
## 6. 异常处理
1. 验签失败：拒绝请求。
2. 指令无法识别：返回帮助提示。
3. 批次无法解析：提示用户补充批次。
## 7. 测试要点
1. 能解析群聊消息。
2. 能识别风险报告指令。
3. 验签失败被拒绝。

69
docs/详细设计/skill/飞书回执记录Skill.md Normal file
View File

@@ -0,0 +1,69 @@
# 飞书回执记录Skill 设计
## 1. Skill 定位
`飞书回执记录Skill` 负责记录飞书消息发送结果、通知对象、消息 ID、失败原因和审计载荷。
英文实现标识建议使用 `FeishuReceiptRecordSkill`。
## 2. 输入
```python
@dataclass
class FeishuReceiptRecordInput:
batch_id: int
send_result: dict
mention_targets: list[dict]
notification_payload: dict
trigger_context: dict
```
## 3. 输出
```python
@dataclass
class FeishuReceiptRecordOutput:
notification_record_id: int
audit_payload: dict
status: str
```
## 4. 核心方法
### 4.1 `run(input) -> FeishuReceiptRecordOutput`
主入口方法。
### 4.2 `create_notification_record(input) -> FeishuNotificationRecord`
创建通知记录。
### 4.3 `build_audit_payload(record) -> dict`
生成审计载荷。
### 4.4 `record_audit(payload) -> AuditLog`
写入审计。
## 5. 技术实现
使用技术：
1. Django ORM
2. JSONField
3. Audit 服务
## 6. 异常处理
1. 记录写入失败：返回系统错误。
2. 审计写入失败：保留通知记录并标记警告。
3. 发送失败：仍记录失败回执。
## 7. 测试要点
1. 成功发送可记录 message_id。
2. 失败发送可记录错误。
3. 审计载荷包含触发来源。
4. 提及用户列表可保存。

70
docs/详细设计/skill/飞书消息发送Skill.md Normal file
View File

@@ -0,0 +1,70 @@
# 飞书消息发送Skill 设计
## 1. Skill 定位
`飞书消息发送Skill` 负责调用飞书 OpenAPI 或 MCP 工具发送消息，并返回发送结果。
英文实现标识建议使用 `FeishuMessageSendSkill`。
## 2. 输入
```python
@dataclass
class FeishuMessageSendInput:
chat_id: str
message_type: str
payload: dict
```
## 3. 输出
```python
@dataclass
class FeishuMessageSendOutput:
send_status: str
message_id: str | None
raw_response: dict
error_message: str = ""
```
## 4. 核心方法
### 4.1 `run(input) -> FeishuMessageSendOutput`
主入口方法。
### 4.2 `send_text(chat_id, payload) -> dict`
发送文本消息。
### 4.3 `send_card(chat_id, payload) -> dict`
发送互动卡片。
### 4.4 `retry_on_transient_error(request) -> dict`
临时错误重试。
## 5. 技术实现
使用技术：
1. 飞书 OpenAPI
2. 飞书 MCP 工具
3. HTTP client
4. 重试策略
## 6. 异常处理
1. token 失效：发送失败并记录。
2. chat_id 无效：发送失败。
3. 网络超时：重试后失败。
4. payload 非法：发送失败。
## 7. 测试要点
1. 文本消息 payload 正确。
2. 卡片消息 payload 正确。
3. API 失败可记录错误。
4. 临时错误可重试。

68
docs/详细设计/skill/飞书消息摘要生成Skill.md Normal file
View File

@@ -0,0 +1,68 @@
# 飞书消息摘要生成Skill 设计
## 1. Skill 定位
`飞书消息摘要生成Skill` 负责将风险报告、导出报告和责任人信息组装为飞书文本消息或互动卡片。
英文实现标识建议使用 `FeishuMessageSummaryBuildSkill`。
## 2. 输入
```python
@dataclass
class FeishuMessageSummaryBuildInput:
risk_report: dict
word_export_report: dict | None
mention_targets: list[dict]
web_detail_url: str | None
```
## 3. 输出
```python
@dataclass
class FeishuMessageSummaryBuildOutput:
message_type: str
payload: dict
summary_text: str
```
## 4. 核心方法
### 4.1 `run(input) -> FeishuMessageSummaryBuildOutput`
主入口方法。
### 4.2 `build_summary_text(report) -> str`
生成文本摘要。
### 4.3 `build_interactive_card(report, mentions, url) -> dict`
生成互动卡片。
### 4.4 `build_mentions(mention_targets) -> list[dict]`
生成 @ 用户片段。
## 5. 技术实现
使用技术：
1. 飞书卡片 JSON
2. 文本模板
3. 可选 LLM 摘要
## 6. 异常处理
1. 风险报告为空：生成提示消息。
2. Web 链接为空：卡片不展示按钮。
3. 责任人为空：不生成 @。
## 7. 测试要点
1. 能生成风险摘要。
2. 能生成卡片 payload。
3. 能包含 @ 用户。
4. 无链接时消息仍可发送。

64
docs/详细设计/skill/飞书责任人映射Skill.md Normal file
View File

@@ -0,0 +1,64 @@
# 飞书责任人映射Skill 设计
## 1. Skill 定位
`飞书责任人映射Skill` 负责将风险项、章节点和责任角色映射到飞书用户 ID。
英文实现标识建议使用 `FeishuOwnerMappingSkill`。
## 2. 输入
```python
@dataclass
class FeishuOwnerMappingInput:
risk_items: list[dict]
owner_mapping_config: dict | None = None
```
## 3. 输出
```python
@dataclass
class FeishuOwnerMappingOutput:
mention_targets: list[dict]
unresolved_roles: list[dict]
```
## 4. 核心方法
### 4.1 `run(input) -> FeishuOwnerMappingOutput`
主入口方法。
### 4.2 `load_owner_mapping() -> dict`
读取责任人映射。
### 4.3 `resolve_roles(risk_items) -> list[str]`
解析责任角色。
### 4.4 `resolve_user_ids(roles, mapping) -> list[dict]`
映射飞书用户 ID。
## 5. 技术实现
使用技术：
1. YAML 配置
2. Django Admin 维护表
3. 飞书用户 ID
## 6. 异常处理
1. 责任角色未配置：加入 unresolved。
2. 用户 ID 为空：不 @，但保留角色。
3. 配置文件缺失：使用默认映射。
## 7. 测试要点
1. 风险项能映射责任角色。
2. 责任角色能映射用户 ID。
3. 未配置角色能被识别。

78
docs/详细设计/skill/飞书通知编排Skill.md Normal file
View File

@@ -0,0 +1,78 @@
# 飞书通知编排Skill 设计
## 1. Skill 定位
`飞书通知编排Skill` 是第七步工作流的总入口 Skill，负责组织飞书触发上下文解析、通知上下文加载、责任人映射、消息摘要生成、消息发送和回执记录。
英文实现标识建议使用 `FeishuNotificationOrchestrateSkill`。
## 2. 输入
```python
@dataclass
class FeishuNotificationOrchestrateInput:
batch_id: int
scenario_id: str
trigger_source: str
feishu_chat_id: str
feishu_message_id: str | None = None
notify_owner: bool = True
include_web_link: bool = True
```
## 3. 输出
```python
@dataclass
class FeishuNotificationOrchestrateOutput:
report_type: str
batch_id: int
send_status: str
mentioned_users: list[dict]
receipt: dict
audit_id: int | None = None
```
## 4. 依赖 Skill
1. `飞书任务入口解析Skill`
2. `飞书责任人映射Skill`
3. `飞书消息摘要生成Skill`
4. `飞书消息发送Skill`
5. `飞书回执记录Skill`
## 5. 核心方法
### 5.1 `run(input) -> FeishuNotificationOrchestrateOutput`
主入口方法。
### 5.2 `load_notification_context(input) -> NotificationContext`
加载风险报告、导出报告和 Web 链接。
### 5.3 `build_notification_payload(context) -> dict`
构建消息载荷。
## 6. 技术实现
使用技术：
1. Tool Registry
2. 飞书 OpenAPI / MCP
3. Django ORM
4. Audit 服务
## 7. 异常处理
1. 风险报告缺失：发送提示消息。
2. 飞书 chat_id 缺失：任务失败。
3. 发送失败：记录失败回执。
## 8. 测试要点
1. 能生成飞书通知报告。
2. 能串联责任人映射和消息发送。
3. 发送失败可记录审计。

18
docs/需求分析/1.V1总需求文档.md
View File

@@ -172,6 +172,24 @@ V1 除 Web 工作台外，还需要实际支持飞书入口能力，使审核任
3. 按 `config -> scenarios -> documents -> agent_core -> chat -> audit` 顺序推进重构。
4. 同步更新 README、AGENTS 和场景配置命名。
当前仓库已补充一组演示型原型设计文档与单文件 HTML，作为设计到实现之间的中间层交付：
- [整体原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.整体原型设计.md)
- [分页原型设计目录](F:\PyCharm\DEMO-AGENT\docs\原型设计)
- [单文件演示站 HTML](F:\PyCharm\DEMO-AGENT\docs\原型设计\registration-prototype-demo.html)
该组原型资产覆盖：
1. 资料包导入页
2. 审核任务工作台
3. 法规完整性检查页
4. 字段抽取与字段池页
5. 一致性核查页
6. 风险预警页
7. Word 回填导出页
8. 飞书通知视图
9. 知识库与治理台 CRUD 设计
## 9. 结论
当前 V1 需求已经从“通用 Agent Demo 基座”重构为“注册申报资料审核系统”。后续所有设计、实现和讲解，建议都围绕以下四个关键词展开：