feat(investigations): refine report authoring and replay flushing

app/domain/schemas/operational_task.py

@@ -5,13 +5,16 @@ import re
 from typing import Annotated, Literal
 from uuid import UUID
 
-from pydantic import Field, JsonValue, field_validator, model_serializer, model_validator
+from pydantic import Field, JsonValue, StringConstraints, field_validator, model_serializer, model_validator
 from app.domain.schemas.answer_ui import (
     CHART_SAMPLE_TIME_PATTERN, ReportUiBlock, validate_chart_sample_time, validate_report_ui_blocks,
 )
 
 from app.domain.schemas.task_question import TaskQuestionRequest
 from app.domain.schemas.shared import NonEmptyStr, PositiveInt, StrictBool, StrictModel
+from app.domain.schemas.report_authoring import (
+    validate_presentation_command_text, validate_report_text, validate_report_ui_text,
+)
 from app.domain.schemas.operational_data import TaskDataSnapshot, TaskDataSource
 from app.domain.schemas.workbench_runtime import (
     WorkbenchDateTime,
@@ -349,12 +352,44 @@ class InvestigationReport(StrictModel):
         return self
 
 
+class InvestigationDataGapInput(InvestigationDataGap):
+    """New gap descriptions use business prose; references remain opaque."""
+
+    missing_data: NonEmptyStr = Field(max_length=4000, description="缺失的业务资料，不写执行字段")
+    scope: NonEmptyStr = Field(max_length=4000, description="缺口涉及的对象、地点与当地时间范围")
+    impact: NonEmptyStr = Field(max_length=4000, description="资料缺项对当前判断的实际影响")
+    required_data: NonEmptyStr = Field(max_length=4000, description="需要补充的具体业务资料")
+
+    @field_validator("missing_data", "scope", "impact", "required_data")
+    @classmethod
+    def validate_reader_text(cls, value: str) -> str:
+        return validate_report_text(value)
+
+
 class InvestigationReportInput(InvestigationReport):
     """Write model: every new report explicitly declares its business result."""
 
+    title: NonEmptyStr = Field(max_length=80, description="简短中文业务标题，写明对象和当前结果，不含执行轮次、流程版本或原始时间戳")
+    current_conclusion: NonEmptyStr = Field(max_length=300, description="先写当前业务判断，再写关键依据与下一步，建议 150 字以内；完整数值和对象比较使用 ui_blocks.Table")
+    conclusion_boundary: NonEmptyStr = Field(max_length=240, description="只写影响判断的证据范围、不确定性和适用限制，不复述结论、执行步骤或参数")
+    recommendations: list[Annotated[NonEmptyStr, Field(max_length=160)]] = Field(default_factory=list)
+    pending_items: list[Annotated[NonEmptyStr, Field(max_length=160)]] = Field(default_factory=list)
+    stop_reason: Annotated[NonEmptyStr, Field(max_length=160)] | None = None
     stage: Literal["interim", "final"]
     outcome: Literal["concluded", "insufficient_data"]
-    data_gaps: list[InvestigationDataGap]
+    data_gaps: list[InvestigationDataGapInput]
+
+    @field_validator("title", "current_conclusion", "conclusion_boundary", "stop_reason")
+    @classmethod
+    def validate_reader_text(cls, value: str | None) -> str | None:
+        return validate_report_text(value) if value is not None else value
+
+    @model_validator(mode="after")
+    def validate_authoring(self):
+        for value in [*self.recommendations, *self.pending_items]:
+            validate_report_text(value)
+        validate_report_ui_text(self.ui_blocks)
+        return self
 
 
 class InvestigationProgress(StrictModel):
@@ -365,8 +400,14 @@ class InvestigationProgress(StrictModel):
 
 
 class InvestigationProgressInput(InvestigationProgress):
+    summary: NonEmptyStr = Field(max_length=300, description="用简短中文说明本轮新增发现、当前依赖和下一步；不复制报告、执行字段、版本号或证据编号")
     graph_update: InvestigationGraphUpdate | None = None
 
+    @field_validator("summary")
+    @classmethod
+    def validate_reader_summary(cls, value: str) -> str:
+        return validate_report_text(value)
+
     @model_validator(mode="after")
     def validate_graph_input(self):
         if self.graph_update is not None and self.diagram is not None:
@@ -908,11 +949,72 @@ TaskPresentationCommand = Annotated[
 ]
 
 
+class TaskPresentationNarration(StrictModel):
+    stage: Literal[
+        "anomaly_detection", "evidence_verification", "asset_localization",
+        "event_impact", "source_control", "isolation_plan", "flushing_plan",
+        "field_feedback", "clearance_verification", "recovery_verification",
+    ]
+    summary: Annotated[str, Field(strict=True, min_length=1, max_length=160)]
+    evidence_refs: Annotated[list[TaskFeatureId], Field(min_length=1, max_length=100)]
+    next_step: Annotated[str, Field(strict=True, min_length=1, max_length=120)] | None = None
+
+    @model_validator(mode="after")
+    def validate_narration(self):
+        if not self.summary.strip() or (self.next_step is not None and not self.next_step.strip()):
+            raise ValueError("presentation narration must contain readable text")
+        if len(set(self.evidence_refs)) != len(self.evidence_refs):
+            raise ValueError("presentation narration evidence IDs must be unique")
+        return self
+
+
+TaskPresentationPurpose = Annotated[
+    str, StringConstraints(strict=True, strip_whitespace=True, min_length=1, max_length=160),
+]
+
+
+class TaskPresentationNarrationInput(TaskPresentationNarration):
+    """New live findings use business prose; saved narration remains readable."""
+
+    summary: Annotated[str, Field(strict=True, min_length=1, max_length=160,
+        description="本步已取得的关键发现，建议 80 字以内；区分观测、模型候选和现场反馈，不复述动作或核查目的")]
+    next_step: Annotated[str, Field(strict=True, min_length=1, max_length=120,
+        description="实际下一步或等待条件，建议 60 字以内；无后续时省略，不把展示当作现场执行")] | None = None
+
+    @field_validator("summary", "next_step")
+    @classmethod
+    def validate_reader_text(cls, value: str | None) -> str | None:
+        return validate_report_text(value) if value is not None else value
+
+
 class TaskPresentationEventCommand(StrictModel):
     request_id: UUID
     run_id: UUID
     source_session_id: NonEmptyStr
     command: TaskPresentationCommand
+    narration: TaskPresentationNarrationInput | None = None
+    purpose: TaskPresentationPurpose | None = Field(default=None,
+        description="一句中文说明本步为何查看这些对象，建议 60 字以内；不堆砌编号、执行参数或复述当前发现")
+
+    @field_validator("purpose")
+    @classmethod
+    def validate_reader_purpose(cls, value: str | None) -> str | None:
+        return validate_report_text(value) if value is not None else value
+
+    @model_validator(mode="after")
+    def validate_visible_labels(self):
+        validate_presentation_command_text(self.command.model_dump())
+        return self
+
+    @model_serializer(mode="wrap")
+    def serialize_legacy_command(self, handler):
+        value = handler(self)
+        # Keep old idempotency digests stable when no narration was supplied.
+        if self.narration is None:
+            value.pop("narration", None)
+        if self.purpose is None:
+            value.pop("purpose", None)
+        return value
 
 
 class TaskPresentationEventResult(StrictModel):
@@ -943,6 +1045,8 @@ class TaskPresentationHistoryItem(StrictModel):
     # Stored records are validated against the current command contract by the
     # reader; an obsolete record must not prevent reading the rest of the page.
     command: dict[str, JsonValue]
+    narration: TaskPresentationNarration | None = None
+    purpose: TaskPresentationPurpose | None = None
 
 
 class TaskPresentationHistoryPage(StrictModel):