Files
2026-09-24 10:40:57 +08:00

185 lines
7.8 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""Typed, frozen task requirements and independent review responses."""
from typing import Literal
from pydantic import BaseModel, ConfigDict, Field, model_validator
STAGES = ("base", "features", "detail")
class Record(BaseModel):
model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
class EnvelopeDimension(Record):
axis: Literal["X", "Y", "Z"]
expected_mm: float = Field(gt=0)
tolerance_mm: float = Field(gt=0)
class Requirement(Record):
id: str
description: str
stage: Literal["base", "features", "detail"]
source: Literal["explicit", "inferred", "uncertain"]
evidence: str
critical: bool
envelope_dimension: EnvelopeDimension | None
verification: Literal["geometry", "design_choice", "manufacturing", "information"] = "geometry"
class ClarificationQuestion(Record):
question: str = Field(min_length=1, max_length=400)
reason: str = Field(min_length=1, max_length=600)
options: list[str] = Field(default_factory=list, max_length=3)
class Brief(Record):
name: str
coordinate_system: str
body_interpretation: str
requirements: list[Requirement]
assumptions: list[str]
unresolved: list[str]
stage_plan: list[str]
non_geometric_requirements: list[str] = Field(default_factory=list)
reference_product: str = ""
reference_questions: list[str] = Field(default_factory=list, max_length=8)
clarification_questions: list[ClarificationQuestion] = Field(default_factory=list, max_length=3)
@model_validator(mode="after")
def check_requirements(self):
ids = [r.id for r in self.requirements]
if not ids or len(set(ids)) != len(ids) or any(not i.strip() for i in ids):
raise ValueError("需求 id 必须非空且唯一")
if not any(r.stage == "base" and r.critical and r.verification == "geometry" for r in self.requirements):
raise ValueError("必须记录关键主体需求")
for r in self.requirements:
if not r.evidence.strip() or not r.description.strip():
raise ValueError("需求必须包含描述和证据")
if r.envelope_dimension and r.verification != "geometry":
raise ValueError("明确包络尺寸必须作为几何验收条件")
if r.envelope_dimension and r.source == "uncertain":
raise ValueError("模糊尺寸不能作为确定包络约束")
return self
def due(self, stage):
return [r for r in self.requirements if r.verification == "geometry" and STAGES.index(r.stage) <= STAGES.index(stage)]
class ReviewItem(Record):
requirement_id: str
status: Literal["pass", "fail", "unverified"]
evidence: str
repair: str
class ReviewFinding(Record):
category: Literal["geometry", "manufacturing", "information", "measurement"]
requirement_id: str | None
message: str = Field(min_length=1)
evidence: str = Field(min_length=1)
class ReviewDecision(ClarificationQuestion):
requirement_ids: list[str] = Field(min_length=1)
source_quotes: list[str] = Field(min_length=1, max_length=3)
class Review(Record):
items: list[ReviewItem]
additional_issues: list[str]
observations: list[str] = Field(default_factory=list)
findings: list[ReviewFinding] = Field(default_factory=list)
clarification_questions: list[ReviewDecision] = Field(default_factory=list, max_length=3)
class ParameterRecord(Record):
name: str = Field(min_length=1)
value: float | str | list[float] | None
unit: str = "mm"
source: Literal["explicit", "assumed", "unresolved"]
evidence: str = Field(min_length=1)
requirement_ids: list[str] = Field(default_factory=list)
@model_validator(mode="after")
def check_value(self):
if isinstance(self.value, str) and not self.value.strip():
raise ValueError("文字参数不能为空")
if isinstance(self.value, list) and not self.value:
raise ValueError("坐标参数不能为空")
if self.source != "unresolved" and self.value is None:
raise ValueError("已采用参数必须记录实际数值")
return self
def assess_review(brief, stage, review):
"""The host, not the reviewer, decides whether coverage permits acceptance."""
due = {r.id: r for r in brief.due(stage)}
ids = [item.requirement_id for item in review.items]
errors = []
if len(set(ids)) != len(ids) or set(ids) != set(due):
errors.append("REVIEW_COVERAGE: 必须逐项核对当前阶段全部需求,不能遗漏或替换 id")
for item in review.items:
if not item.evidence.strip():
errors.append(f"{item.requirement_id}: 缺少核对证据")
requirement = due.get(item.requirement_id)
if requirement and requirement.critical and item.status != "pass":
errors.append(f"{item.requirement_id}: {item.status}; {item.evidence}; {item.repair}")
errors.extend(review.additional_issues)
errors.extend(f.message for f in review.findings if f.category == "geometry")
return errors
def dimension_errors(brief, stage, shape):
sizes = dict(zip("XYZ", shape.bounding_box().size))
errors = []
for requirement in brief.due(stage):
d = requirement.envelope_dimension
if d and abs(sizes[d.axis] - d.expected_mm) > d.tolerance_mm:
errors.append(f"{requirement.id}: 固定包络 {d.axis}={d.expected_mm}±{d.tolerance_mm}mm,"
f"实测 {sizes[d.axis]:.4f}mm;不能修改需求来通过检查")
return errors
def review_protocol_errors(brief, stage, review):
due = {r.id for r in brief.due(stage)}
ids = [item.requirement_id for item in review.items]
errors = []
if len(ids) != len(set(ids)) or set(ids) != due:
errors.append(f"核对项必须恰好包含 {sorted(due)},实际为 {ids};只纠正核对输出,不要求重建几何")
if any(not item.evidence.strip() for item in review.items):
errors.append("每项必须包含证据")
for finding in review.findings:
if finding.category == "geometry" and finding.requirement_id and finding.requirement_id not in due:
errors.append("几何缺陷不能引用非几何或尚未到期的需求;资料和制造事项应正确分类")
return errors
def review_notes(brief, review=None):
notes = {"design_choices": [], "information_needed": list(brief.unresolved),
"manufacturing_notes": list(brief.non_geometric_requirements)}
keys = {"design_choice": "design_choices", "manufacturing": "manufacturing_notes", "information": "information_needed"}
for req in brief.requirements:
if req.verification in keys:
notes[keys[req.verification]].append(req.description)
if review:
for f in review.findings:
if f.category in ("manufacturing", "information"):
notes["manufacturing_notes" if f.category == "manufacturing" else "information_needed"].append(f.message)
return {k: list(dict.fromkeys(v)) for k, v in notes.items()}
def review_information_blockers(brief, stage, review):
"""Missing source evidence must not enter the geometry repair loop.
Keep critical requirements pending, never convert an unverified fit to pass.
Explicit geometric failures and measured dimensions always stay geometric.
"""
due = {r.id:r for r in brief.due(stage)}
geometry_ids = {f.requirement_id for f in review.findings if f.category == "geometry"}
information_ids = {f.requirement_id for f in review.findings if f.category == "information"}
return [item for item in review.items if item.status == "unverified"
and item.requirement_id in information_ids and item.requirement_id not in geometry_ids
and item.requirement_id in due and due[item.requirement_id].critical
and due[item.requirement_id].envelope_dimension is None]