docs(详细设计): 新增字段抽取与字段池设计

docs/详细设计/skill/字段Schema加载Skill.md

@@ -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. 来源优先级输出正确。
+

docs/详细设计/skill/字段抽取报告生成Skill.md

@@ -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. 飞书摘要不包含敏感信息。
+

docs/详细设计/skill/字段抽取编排Skill.md

@@ -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. 输出报告结构稳定。
+

docs/详细设计/skill/字段抽取范围确认Skill.md

@@ -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. 待复核文档会降低抽取可信度。
+

docs/详细设计/skill/字段标准化Skill.md

@@ -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. 低可信候选进入待复核。
+

docs/详细设计/skill/统一字段池写入Skill.md

@@ -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. 可回填字段标记正确。
+

docs/详细设计/skill/表格字段抽取Skill.md

@@ -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. 表格解析失败不影响规则抽取。
+

docs/详细设计/skill/规则字段抽取Skill.md

@@ -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. 空文本不报错。
+

docs/详细设计/skill/长文本字段归纳Skill.md

@@ -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 关闭时主流程仍可完成。
+